Sales order bulk export — incremental sync guide
The export endpoint (GET /external/api/v1/sales-orders/export) is designed for large-volume or recurring syncs. It uses stable cursor pagination and an updated_at-based lower bound.
First request — starting a sync
Pass since to define the inclusive lower bound on updated_at:
GET /external/api/v1/sales-orders/export?since=2026-09-01T00:00:00Z
since is always interpreted as UTC, regardless of whether you include the Z suffix:
2026-09-01T00:00:00Z✅ explicit UTC2026-09-01 00:00:00✅ also read as UTC2026-09-01T00:00:00-06:00✅ explicit offset honored
Do not subtract a fixed offset from
sinceto compensate for timezone differences — the endpoint handles the conversion internally.
Subsequent pages — use cursor
Each response includes next_cursor and has_more:
{ "data": [...], "next_cursor": "eyJ...", "has_more": true, "meta": { "rows": 1000 } }
Pass cursor (not since) for every page after the first:
GET /external/api/v1/sales-orders/export?cursor=eyJ...
When has_more is false and next_cursor is null, the walk is complete.
Next incremental run
Record the highest updated_at value you received (all timestamps are UTC ISO 8601 with microseconds, e.g. 2026-09-17T19:21:32.000000Z). Use that value as since on your next run.
Because since is inclusive, records whose updated_at exactly equals your bound are returned again. Upsert on order_id — do not insert blindly.
Daylight saving time fall-back
If your since value falls inside a repeated clock hour (when DST clocks go back), the endpoint floors the bound to the start of that repeated hour. This means up to one extra hour of records may be returned. Upserting on order_id handles this correctly with no data loss.
Parameters
| Parameter | Required | Description |
|---|---|---|
since | Required for first page | Inclusive lower bound on updated_at, interpreted as UTC |
cursor | Required for subsequent pages | Value of next_cursor from prior response. Do not send with since. |
limit | Optional | Default 1000, maximum 1000 |
Only these three parameters are accepted. Sending any other parameter, or sending since and cursor in the same request, returns a validation error.
Response timestamps
All created_at / updated_at fields on orders, items, shipments, and fulfillment orders are returned in UTC ISO 8601 with microsecond precision. order_date and ship_date are returned as stored.