Pagination & change feeds
Contents 26 pages
Every list endpoint returns the same envelope. GET /origins and
GET /payment_methods return everything in one page (has_more is always
false) and ignore the paging parameters. The rest page as described here.
{
"object": "list",
"data": [ { "object": "shipment", … }, … ],
"has_more": true,
"next_cursor": "MjAyNi0wOC0xMlQxMjowMDowMC4wMDBafGNtMms4eDdkMjAwMDFsMjA4YWIzY2Q5ZWY"
}| Parameter | |
|---|---|
limit |
1–100. Default 25. A value above 100 is treated as 100 and 0 as 1; anything that is not a whole number falls back to 25. |
starting_after |
The previous page's next_cursor, verbatim. |
updated_since |
An ISO-8601 timestamp with a zone (Z or an offset). Switches the list into a change feed — see below. An unreadable value gets 400 invalid_parameter. |
Always send the zone in updated_since. A date and time without one is read in
our server's local time zone, which you should not rely on.
Walking a list#
Keep going while has_more is true, passing the last next_cursor each time:
/api/v1/shipmentsScope shipments:readcurl "https://app.shipeasyco.com/api/v1/shipments?limit=100" \
-H "Authorization: Bearer $SHIPEASY_API_KEY"
curl "https://app.shipeasyco.com/api/v1/shipments?limit=100&starting_after=MjAyNi0wOC0xMlQxMjowMDowMC4wMDBafGNtMms4eDdkMjAwMDFsMjA4YWIzY2Q5ZWY" \
-H "Authorization: Bearer $SHIPEASY_API_KEY"BASE = "https://app.shipeasyco.com"
# session: a requests.Session that sends your Authorization header
def all_shipments(session, **params):
cursor = None
while True:
page = session.get(f"{BASE}/api/v1/shipments",
params={**params, "limit": 100, "starting_after": cursor}).json()
yield from page["data"]
if not page["has_more"]:
return
cursor = page["next_cursor"]The cursor is opaque. Pass it back exactly as you received it, with the same
updated_since and filters as the request that returned it; do not construct,
decode or modify one. A cursor we cannot read gets 400 invalid_cursor; a cursor
taken from a different query is not detected and returns the wrong page.
There is no page number and no offset, on purpose. Offsets skip and duplicate
rows when the underlying list changes mid-walk — which for a live shipment list
is most of the time. A cursor points at a specific row, so inserting new
shipments while you page cannot make you miss one.
has_more is the end-of-list signal; use it rather than counting rows. A full
page can still be the last one.
Change feeds#
Full sweeps are the wrong tool for "what happened since yesterday". Add
updated_since and the same endpoint becomes a resumable feed of changes:
curl "https://app.shipeasyco.com/api/v1/shipments?updated_since=2026-08-12T00:00:00Z&limit=100" \
-H "Authorization: Bearer $SHIPEASY_API_KEY"Three things change when you pass it:
- The sort flips to oldest-first. A plain list is newest-first because that is how a list is read. A feed has to hand out changes in the order they happened, or resuming from a cursor would skip the ones that arrived while you were reading.
- The sort column becomes the change timestamp —
changed_aton shipments,updated_aton destinations,createdonGET /eventsandGET /shipments/{id}/events, and the quote's last update onGET /quotes. Quotes do not carry that timestamp, so for a quote feed start the next poll at the time your previous poll started, minus 10 seconds. If your clock can drift from ours, subtract more: a re-read row is harmless, a skipped one is not. - The feed runs about ten seconds behind the clock. A change appears only once its timestamp is at least 10 seconds old. See the settle window.
The polling loop#
def poll(session, since):
# since: ISO-8601 string with a zone, e.g. "2026-08-12T00:00:00Z"
cursor = None
high_water = since
while True:
page = session.get(f"{BASE}/api/v1/shipments",
params={"updated_since": since,
"starting_after": cursor, "limit": 100}).json()
for shipment in page["data"]:
handle(shipment)
high_water = shipment["changed_at"] or high_water
if not page["has_more"]:
return high_water # ← next poll starts here
cursor = page["next_cursor"]Store the high-water mark after you have processed the page, not before. If your process dies mid-page you will re-read a few rows, which is the failure mode you want — handlers should be idempotent, keyed on the shipment id.
Poll no more than once a minute. min_poll_interval_seconds on /ping says
so too.
The settle window#
A change gets its timestamp a moment before it is saved, and several things write changes at once. So a change stamped 12:00:00 can be saved just after one stamped 12:00:02. If the feed served the 12:00:02 change straight away, your high-water mark would move past 12:00:00 before that change existed, and your next poll would start above it and never see it.
The feed prevents this by serving only changes whose timestamp is at least 10 seconds old. By then every change stamped earlier has been saved, so carrying the high-water mark forward as shown above never skips a row. You pay for it with ten seconds of delay: a change made at 12:00:00 first appears in a poll made after 12:00:10. That makes no difference at the once-a-minute poll rate, and there is nothing you need to change in your loop.
The same window applies to GET /events and to every other list you read with
updated_since.
Why changed_at and not updated_at#
A shipment's changed_at moves only when something a customer would notice
changes — status, PRO number, tracking link, BOL, pickup date, an exception, or
a cancellation request.
Our own routine checks on a shipment do not move it, so a feed on changed_at
hands you real changes and nothing else.
One thing to know before your first sweep. Shipments created before the API
existed have changed_at set to their creation time. Your first updated_since
poll will therefore return your history once, oldest first. Seed your
high-water mark from "now" if you only care about future changes, or from a date
you choose if you want a backfill.
Filtering#
Filters combine with paging and with updated_since. An unknown status,
state or type gets 400 invalid_parameter.
GET /shipments takes status — one of all, pending, booked,
in_transit, delivered, cancelled, exception, cancel_requested — and
carrier, which takes a carrier key from GET /account (for example ait) or
the exact carrier name a shipment carries (for example CEVA Logistics).
cancel_requested is not a status the carrier reports; it is "you asked us to
cancel and we have not confirmed yet". It is a separate filter value for
exactly that reason, and it is the same list the web app shows, so the two can
never disagree.
exception is set by ShipEasy when a shipment needs attention. It is a value of
status, not a lifecycle step, and filters like any other.
GET /quotes takes state — all (the default), bookable, expired or
booked — and carrier, an exact match on the carrier name a quote carries
(for example AIT Worldwide Logistics).
GET /events takes type (a webhook event type), shipment_id and
booking_id.
Searching destinations#
GET /destinations takes q, 2–200 characters: it matches a consignee's
nickname, company or city (any part, any case) and the start of its ZIP — the
same search as the web app. A q outside that range gets
400 invalid_parameter.
Contact names, street lines, phones, emails and notes are encrypted at rest, so search does not cover them; filter those client-side, or key your records on the destination id.