Shipments & tracking
Contents 26 pages
Everything your organization has booked, whether through the web app or through this API. There is one shipment list, and it is the same one the web app shows. A Shopify store's key reads the store's own shipments instead, place-only: see Shopify stores.
List shipments#
/api/v1/shipmentsScope shipments:readcurl "https://app.shipeasyco.com/api/v1/shipments?status=in_transit&limit=50" \
-H "Authorization: Bearer $SHIPEASY_API_KEY"const url = new URL("https://app.shipeasyco.com/api/v1/shipments");
url.searchParams.set("status", "in_transit");
url.searchParams.set("limit", "50");
const res = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.SHIPEASY_API_KEY}` },
});
const { data, has_more, next_cursor } = await res.json();import os
import requests
res = requests.get(
"https://app.shipeasyco.com/api/v1/shipments",
params={"status": "in_transit", "limit": 50},
headers={"Authorization": f"Bearer {os.environ['SHIPEASY_API_KEY']}"},
)
page = res.json(){
"object": "list",
"data": [
{
"object": "shipment",
"id": "cm2k8x7d2…",
"reference": "SHP-4M7QX2R",
"customer_reference": "SO-1041",
"status": "in_transit",
"cancellation_requested": false,
"exception_at": null,
"carrier": "AIT Worldwide Logistics",
"service": "White Glove",
"pro_number": "551-9920184",
"tracking_url": "https://…",
"has_bol": true,
"amount_usd": "1341.00",
"currency": "USD",
"pickup_date": "2026-11-17",
"picked_up_at": "2026-11-17T19:20:00.000Z",
"eta": "2026-11-20T00:00:00.000Z",
"delivery_appointment_from": null,
"delivery_appointment_to": null,
"delivered_at": null,
"carrier_status": "In Transit",
"has_pod": false,
"has_label": false,
"pickup_window": "full-day",
"origin_region": "IL",
"destination_region": "TX",
"status_synced_at": "2026-11-18T09:40:02.000Z",
"created_at": "2026-11-12T14:05:01.000Z",
"changed_at": "2026-11-17T19:25:12.000Z",
"coverage": null
}
],
"has_more": false,
"next_cursor": null
}| Parameter | |
|---|---|
status |
all (default) · pending · booked · in_transit · delivered · cancelled · exception · cancel_requested |
carrier |
A carrier key from GET /account (ait), or the carrier name exactly as shipments carry it. |
limit, starting_after, updated_since |
See pagination. |
cancel_requested is not a carrier status — it means you asked us to cancel
and we have not confirmed yet. The same shipment still carries its real
status, plus cancellation_requested: true.
exception_at is when our team declared a carrier exception, and null
otherwise. A shipment our team flags by hand shows status: "exception" with
exception_at: null. Either clears once the shipment is delivered or cancelled.
On tracking, exception_open is true for both.
eta is the carrier's delivery date: the booked appointment when there is one,
else its estimate. delivery_appointment_from and delivery_appointment_to are
the booked window, null when the carrier named only a day. carrier_status is
the carrier's own wording beside our status.
customer_reference is whatever you sent as customer_reference when booking,
which makes it the natural join key back to your own order.
coverage is null unless cargo coverage was bought with the booking. When it
was, it carries reference, status, declared_value_usd, deductible_usd,
premium_usd and certificate_number, and the freight is insured only once
status is in_force. See cargo coverage.
Requires shipments:read.
Pickups and deliveries by day#
/api/v1/scheduleScope shipments:readWhat is picked up and delivered on which days: the web app's Calendar on the
wire. from and to are required (YYYY-MM-DD, both included, at most 62 days).
curl "https://app.shipeasyco.com/api/v1/schedule?from=2026-11-16&to=2026-11-22" \
-H "Authorization: Bearer $SHIPEASY_API_KEY"const url = new URL("https://app.shipeasyco.com/api/v1/schedule");
url.searchParams.set("from", "2026-11-16");
url.searchParams.set("to", "2026-11-22");
const res = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.SHIPEASY_API_KEY}` },
});
const { data } = await res.json();import os
import requests
res = requests.get(
"https://app.shipeasyco.com/api/v1/schedule",
params={"from": "2026-11-16", "to": "2026-11-22"},
headers={"Authorization": f"Bearer {os.environ['SHIPEASY_API_KEY']}"},
)
days = res.json()["data"]{
"object": "list",
"data": [
{
"object": "schedule_entry",
"kind": "pickup",
"date": "2026-11-19",
"state": "scheduled",
"state_label": "Pickup scheduled",
"preference": false,
"shipment_id": "cm2k8x7d2…",
"reference": "SHP-4M7QX2R",
"customer_reference": "SO-1041",
"pro_number": "551-9920184",
"carrier": "AIT Worldwide Logistics",
"service": "Curbside",
"origin": "Columbus, OH",
"destination": "Nashville, TN",
"starts_at": "2026-11-19T13:00:00.000Z",
"ends_at": "2026-11-19T17:00:00.000Z",
"time_zone": "America/New_York",
"time_text": "Morning (8 AM – 12 PM EST)",
"note": null
},
{
"object": "schedule_entry",
"kind": "delivery",
"date": "2026-11-20",
"state": "requested",
"state_label": "Preferred delivery day",
"preference": true,
"shipment_id": "cm2k9a1b4…",
"reference": "SHP-7TQ2W8D",
"customer_reference": "PO-4519",
"pro_number": null,
"carrier": "CEVA Logistics",
"service": "White Glove",
"origin": "Houston, TX",
"destination": "New Orleans, LA",
"starts_at": null,
"ends_at": null,
"time_zone": "America/Chicago",
"time_text": null,
"note": "Preferred days: Nov 20 – Nov 21, 2026. These days are a preference, not a guaranteed date."
}
],
"has_more": false,
"next_cursor": null
}- A pickup is on the day it was booked for.
scheduleduntil that day ends at the pickup dock,picked_uponce the carrier says so, thennot_picked_up("Awaiting pickup confirmation": the carrier has often been and not reported it yet).cancelledpickups are listed too. - A delivery is on its day at the delivery dock:
delivered,appointment(a day the carrier booked),expected(the carrier's estimate) oroverdue(a full day past it). While nothing is booked, the receiver's preferred days come asrequestedlines, one per day, withpreference: true: a preference, not a guaranteed date. starts_atandends_atare the pickup window or the booked appointment, andtime_zoneis that dock's; both are null for a line that is the day alone.- Lines are in day order, the ones that need a call first within a day. It is one
page: more than 1,000 pickups or deliveries in the span answers
invalid_parameter, asking for fewer days. - Place-only, so a Shopify store's key reads it too: never a name, street or
price. With the calendar switched off it answers
404 unknown_endpoint.
Calendar subscribe links#
/api/v1/schedule/linksScope shipments:read/api/v1/schedule/linksScope shipments:write/api/v1/schedule/links/{linkId}Scope shipments:writeUp to 5 links for Apple, Google or Outlook Calendar to subscribe to pickups and
deliveries: a Shopify store's, or those of the
member behind an
organization's key, which show what that member can see. POST takes an optional label and
answers the link's url and webcal_url once: anyone holding it sees the
schedule, so it is never shown again, and GET lists the links by their last
four characters. DELETE revokes one; it stops answering at once. Reading
needs shipments:read, making and revoking shipments:write.
A web app link belongs to one person, so a key with no member behind it gets
insufficient_scope.
One shipment, in full#
/api/v1/shipments/{shipmentId}Scope shipments:readcurl https://app.shipeasyco.com/api/v1/shipments/cm2k8x7d2… \
-H "Authorization: Bearer $SHIPEASY_API_KEY"The detail response is a shipment plus what is actually on the truck:
{
"object": "shipment",
"id": "cm2k8x7d2…",
"status": "in_transit",
"origin": {
"name": "Dock A",
"company": "Acme Freight",
"address1": "1200 Devon Ave",
"address2": null,
"city": "Elk Grove Village",
"state": "IL",
"postal_code": "60007",
"country": "US",
"phone": "+1-847-555-0100",
"residential": false
},
"destination": { … },
"handling_units": [
{
"package_type": "pallet",
"length_in": "48",
"width_in": "40",
"height_in": "52",
"weight_lbs": "780",
"quantity": "2",
"description": "Palletized machine parts"
}
]
}An id that belongs to another organization returns 404 resource_not_found,
not a 403 — telling you the difference would confirm the row exists.
notes lists what ShipEasy's team wrote for you about the shipment, newest
first, each with id, body, created_at and edited; it never names who
wrote it. A Shopify store's are always empty, since a note may name the buyer.
Ship again#
/api/v1/shipments/{shipmentId}/ship-againScope quotes:writecurl https://app.shipeasyco.com/api/v1/shipments/cm2k8x7d2…/ship-again \
-H "Authorization: Bearer $SHIPEASY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'Today's rates for a past shipment's lane and freight, answered exactly as
POST /quotes answers them and counted against the same
daily quote budget: never its old price or pickup day. Send pickup_date for a
day other than the earliest, and include_all_carriers: true for every carrier.
Requires quotes:write. To keep a lane for next time, save a
template.
Status report#
/api/v1/shipments/reportScope shipments:readcurl "https://app.shipeasyco.com/api/v1/shipments/report?days=7" \
-H "Authorization: Bearer $SHIPEASY_API_KEY"{
"object": "status_report",
"days": 7,
"as_of": "2026-11-19T15:02:10.000Z",
"empty": false,
"sections": [
{
"section": "inTransit",
"title": "In transit",
"count": 1,
"groups": [
{
"carrier": "CEVA Logistics",
"line": "Expected Nov 21",
"note": null,
"shipments": [{ "id": "cm2k8x7d2…", "name": "SHP-7KD2Q · PRO 551-9920184" }]
}
]
}
],
"quotes": { "shown": [], "more": 0 },
"cases": []
}The report the web app, the Shopify app and our team's emails show: what was
delivered, is in transit or is being picked up in the last days (7, 14 or 30;
14 by default), and what needs you: quotes still bookable and support cases
waiting on your answer. time_zone (an IANA zone, UTC by default) only words the
quotes' deadlines. A Shopify store's note is always null. Requires
shipments:read.
Download the shipments CSV#
/api/v1/shipments/exportScope shipments:readcurl "https://app.shipeasyco.com/api/v1/shipments/export?status=delivered&from=2026-10-01" \
-H "Authorization: Bearer $SHIPEASY_API_KEY" -o shipments.csvThe web app's shipments CSV, one row per shipment, newest first, at most 10,000
rows, with no cost or margin column. Filter by status, and by the UTC day it
was booked with from and to. It shares the web app's budget of 30 downloads
an hour; over it, 429 rate_limit_exceeded. Organizations only: a Shopify
store's key gets not_available_for_shopify. Requires shipments:read.
Track by PRO number#
/api/v1/tracking/{pro}Scope shipments:readcurl https://app.shipeasyco.com/api/v1/tracking/551-9920184 \
-H "Authorization: Bearer $SHIPEASY_API_KEY"{
"object": "tracking",
"id": "cm2k8x7d2…",
"pro_number": "551-9920184",
"reference": "SHP-4M7QX2R",
"status": "in_transit",
"exception_open": false,
"carrier": "AIT Worldwide Logistics",
"tracking_url": "https://…",
"pickup_date": "2026-11-17",
"eta": "2026-11-20T00:00:00.000Z",
"delivered_at": null,
"origin_region": "IL",
"destination_region": "TX",
"status_synced_at": "2026-11-18T09:40:02.000Z"
}A slim projection for the common case: you have a PRO from a carrier email or a
customer, and you want its status. id is the shipment's id, so you can go on to
its detail or its events. Scoped to your organization; a PRO is not unique across
carriers, so the newest match wins.
Requires shipments:read.
The BOL#
/api/v1/shipments/{shipmentId}/bolScope shipments:readcurl https://app.shipeasyco.com/api/v1/shipments/cm2k8x7d2…/bol \
-H "Authorization: Bearer $SHIPEASY_API_KEY" \
-o bol.pdfReturns the PDF itself — Content-Type: application/pdf, not JSON, not a
redirect to a signed URL. ShipEasy-Request-Id is still on the response.
has_bol on a shipment tells you whether there is one to fetch. A BOL appears
shortly after booked; before that, and for a shipment that is not yours, you
get 404 resource_not_found — the same answer for both, on purpose.
If the carrier's copy cannot be fetched right now you get 502 with
{"error":"Document unavailable"} — not the usual error object. Retry later.
Requires shipments:read.
Proof of delivery#
/api/v1/shipments/{shipmentId}/podScope shipments:readcurl https://app.shipeasyco.com/api/v1/shipments/cm2k8x7d2…/pod \
-H "Authorization: Bearer $SHIPEASY_API_KEY" \
-o pod.pdfThe same shape as the BOL: the PDF itself, not a redirect to a signed URL.
has_pod says whether there is one to fetch, and shipment.document_available
with kind: "pod" fires when it appears — subscribe to that rather than
polling. Before the carrier files it, and for a shipment that is not yours, you
get 404 resource_not_found — the same answer for both, on purpose.
If the carrier's copy cannot be fetched right now you get 502 with
{"error":"Document unavailable"} — not the usual error object. Retry later.
Requires shipments:read.
Labels#
/api/v1/shipments/{shipmentId}/labelScope shipments:readcurl https://app.shipeasyco.com/api/v1/shipments/cm2k8x7d2…/label \
-H "Authorization: Bearer $SHIPEASY_API_KEY" \
-o labels.pdfThe carrier's shipping labels for the freight, as one PDF, fetched from the
carrier when you call. Only AIT and Alliance shipments have them. has_label says whether
there is one to fetch; for a shipment with none, and for one that is not yours,
you get 404 resource_not_found, the same answer for both.
If the carrier cannot be reached right now you get 502 with
{"error":"Document unavailable"}, not the usual error object. Retry later.
Requires shipments:read.
Refresh status on demand#
/api/v1/shipments/{shipmentId}/refresh-statusScope shipments:writecurl -X POST https://app.shipeasyco.com/api/v1/shipments/cm2k8x7d2…/refresh-status \
-H "Authorization: Bearer $SHIPEASY_API_KEY"{
"object": "refresh_result",
"refreshed": 1,
"shipment_id": "cm2k8x7d2…",
"status": "in_transit",
"pro_number": "551-9920184",
"status_synced_at": "2026-11-18T09:12:44.000Z"
}We already poll carriers on a schedule, so you rarely need this. Use it when a person is waiting for an answer — a customer on the phone, a dock supervisor looking at a screen.
refreshed: 1 means the carrier answered, even if nothing changed.
refreshed: 0 means we could not read it this time; status and
status_synced_at are the last known values.
Limited to 60 per hour per organization, separately from your daily quotas,
because each call spends a real carrier lookup. Over it, you get
429 rate_limit_exceeded with Retry-After.
While we have status checks paused, the call answers 503 api_unavailable and
does not count against that limit. Shipments keep their last known status, and
status_synced_at tells you how old it is; they catch up on their own once
checks resume, so retry later rather than in a loop.
Requires shipments:write. Idempotency-Key is honoured but not required — a
duplicate refresh changes nothing and charges nothing.
Refresh many at once#
/api/v1/shipments/refresh-statusScope shipments:writecurl https://app.shipeasyco.com/api/v1/shipments/refresh-status \
-H "Authorization: Bearer $SHIPEASY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"shipment_ids": ["cm2k8x7d2…", "cm2k9b3f1…"]}'{
"object": "refresh_many_result",
"refreshed": 2,
"shipments": [
{
"shipment_id": "cm2k8x7d2…",
"status": "in_transit",
"pro_number": "551-9920184",
"status_synced_at": "2026-11-18T09:12:44.000Z"
},
{
"shipment_id": "cm2k9b3f1…",
"status": "delivered",
"pro_number": "551-9920377",
"status_synced_at": "2026-11-18T09:12:45.000Z"
}
]
}Up to 100 of your shipments in one call, which counts as one refresh against the
same hourly limit. Ids that are not yours are left out; none of them yours is
404 resource_not_found.
Cancelling#
/api/v1/shipments/{shipmentId}/cancelScope shipments:writecurl -X POST https://app.shipeasyco.com/api/v1/shipments/cm2k8x7d2…/cancel \
-H "Authorization: Bearer $SHIPEASY_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"{
"object": "cancellation",
"shipment_id": "cm2k8x7d2…",
"cancelled": false,
"refund_issued": false,
"next_step": "Cancellation received. Your card is refunded in full once the carrier confirms the booking is voided, usually within one business day. The shipment is not cancelled until then."
}This call records a cancellation request; it never cancels or refunds on its
own. The carrier has no cancel API we can call, so our team voids the booking
with the carrier first, and only then is the shipment cancelled and any refund
issued. Until then the shipment keeps its real status and shows
cancellation_requested: true.
next_step says which of two requests this is:
- Refund approved (more than one business day before pickup, paid by card, nothing blocking it) — the card is refunded in full once the carrier confirms the booking is voided, usually within one business day. If the carrier has already picked the freight up, the refund is no longer automatic and our team follows up.
- Request for review (closer to pickup, invoiced, or otherwise not automatic) — our team confirms with the carrier, decides what is refundable, and follows up.
Read cancelled before telling anyone the freight is cancelled. It is
false on this response; the shipment's own status becomes cancelled — and
changed_at moves on the change feed — when our team
has confirmed it. That confirmation is also an event: shipment.status_changed
and shipment.cancellation_confirmed, on your webhooks and in GET /events.
refund_issued is likewise false here; the refund follows the confirmation.
If the carrier reports the cancellation first, status can be cancelled before
the refund is released.
Too late to cancel at all gives 409 shipment_not_cancellable: once the
carrier has picked the freight up (status is in_transit, or the pickup has
been recorded), or the shipment is delivered or cancelled. Freight already
moving is a conversation with our team.
The same 409 answers a shipment whose cancellation is already requested (retry
with the same Idempotency-Key to get the first answer back) and an id that is
not yours — not a 404.
Requires shipments:write and an Idempotency-Key.
Following a shipment properly#
Do not poll shipments one by one. Use the change feed:
curl "https://app.shipeasyco.com/api/v1/shipments?updated_since=2026-11-12T00:00:00Z" \
-H "Authorization: Bearer $SHIPEASY_API_KEY"It returns only what actually changed, oldest first, and resumes from a cursor.
Once a minute is plenty. See pagination & change feeds
for the loop, and for why changed_at — not a generic "last modified" — is the
field that means what you want.
For one shipment's tracking timeline, read GET /shipments/{id}/events; see
events.