API reference

Status updates

Follow your orders with a pull-based status pool. Each status change appends to a per-credential, cursor-ordered feed; you poll for everything since your last cursor. There is no outbound URL to register and nothing to retry — you are in control of when you read.

Replaces outbound webhooks

The status pool is the pull-based replacement for the previous outbound webhook delivery — there is no endpoint to register and nothing to retry. Requires the status:read scope.

Polling is stateless on our side: you persist the last next_cursor you processed and pass it back as since on the next call. Omit since on the first call to read from the beginning. Keep polling while has_more is true to drain a backlog, then poll on an interval (e.g. every few seconds) for new changes.

The feed is scoped to your credential — you only ever see status changes for packages that belong to you. Requires the status:read scope.

Poll the status pool

GET/api/v1/partner/changes

Query parameters

sinceintegeroptional: The last cursor you processed. Returns every change after it. Omit to start from the beginning.
limitintegeroptional: Max changes to return in one page (default applies if omitted).

Response — data[]

cursorintegeroptional: Monotonic position of this change in your feed. Pass the latest back as since.
tracking_numberstringoptional: The Starmile tracking number of the affected parent order.
external_parent_idstringoptional: Your own reference, echoed back.
statusstringoptional: The new status the order moved to.
previous_statusstringoptional: The status it moved from.
occurred_atstringoptional: ISO-8601 timestamp of the change.

Response — envelope

next_cursorintegeroptional: Pass this as since on your next poll.
has_morebooleanoptional: true if more changes are waiting beyond this page — poll again immediately.

curl 'https://api.starmile.io/api/v1/partner/changes?since=10480' \
  -H 'Authorization: Bearer <access_token>'