Skip to content

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#

GET/api/v1/shipmentsScope shipments:read
Request
curl "https://app.shipeasyco.com/api/v1/shipments?status=in_transit&limit=50" \
  -H "Authorization: Bearer $SHIPEASY_API_KEY"
Response
{
	"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#

GET/api/v1/scheduleScope shipments:read

What 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).

Request
curl "https://app.shipeasyco.com/api/v1/schedule?from=2026-11-16&to=2026-11-22" \
  -H "Authorization: Bearer $SHIPEASY_API_KEY"
Response
{
	"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. scheduled until that day ends at the pickup dock, picked_up once the carrier says so, then not_picked_up ("Awaiting pickup confirmation": the carrier has often been and not reported it yet). cancelled pickups 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) or overdue (a full day past it). While nothing is booked, the receiver's preferred days come as requested lines, one per day, with preference: true: a preference, not a guaranteed date.
  • starts_at and ends_at are the pickup window or the booked appointment, and time_zone is 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.
POST/api/v1/schedule/linksScope shipments:write

Up 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#

GET/api/v1/shipments/{shipmentId}Scope shipments:read
Shell
curl 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:

JSON
{
  "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#

POST/api/v1/shipments/{shipmentId}/ship-againScope quotes:write
Shell
curl 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#

GET/api/v1/shipments/reportScope shipments:read
Request
curl "https://app.shipeasyco.com/api/v1/shipments/report?days=7" \
  -H "Authorization: Bearer $SHIPEASY_API_KEY"
Response
{
	"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#

GET/api/v1/shipments/exportScope shipments:read
Shell
curl "https://app.shipeasyco.com/api/v1/shipments/export?status=delivered&from=2026-10-01" \
  -H "Authorization: Bearer $SHIPEASY_API_KEY" -o shipments.csv

The 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#

GET/api/v1/tracking/{pro}Scope shipments:read
Request
curl https://app.shipeasyco.com/api/v1/tracking/551-9920184 \
  -H "Authorization: Bearer $SHIPEASY_API_KEY"
Response
{
	"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#

GET/api/v1/shipments/{shipmentId}/bolScope shipments:read
Shell
curl https://app.shipeasyco.com/api/v1/shipments/cm2k8x7d2…/bol \
  -H "Authorization: Bearer $SHIPEASY_API_KEY" \
  -o bol.pdf

Returns 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#

GET/api/v1/shipments/{shipmentId}/podScope shipments:read
Shell
curl https://app.shipeasyco.com/api/v1/shipments/cm2k8x7d2…/pod \
  -H "Authorization: Bearer $SHIPEASY_API_KEY" \
  -o pod.pdf

The 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#

GET/api/v1/shipments/{shipmentId}/labelScope shipments:read
Shell
curl https://app.shipeasyco.com/api/v1/shipments/cm2k8x7d2…/label \
  -H "Authorization: Bearer $SHIPEASY_API_KEY" \
  -o labels.pdf

The 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#

POST/api/v1/shipments/{shipmentId}/refresh-statusScope shipments:write
Request
curl -X POST https://app.shipeasyco.com/api/v1/shipments/cm2k8x7d2…/refresh-status \
  -H "Authorization: Bearer $SHIPEASY_API_KEY"
Response
{
	"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#

POST/api/v1/shipments/refresh-statusScope shipments:write
Request
curl 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…"]}'
Response
{
	"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#

POST/api/v1/shipments/{shipmentId}/cancelScope shipments:write
Request
curl -X POST https://app.shipeasyco.com/api/v1/shipments/cm2k8x7d2…/cancel \
  -H "Authorization: Bearer $SHIPEASY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
Response
{
	"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:

Shell
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.