Resources
Glossary
Key terms used throughout the Starmile Partner API.
- Credential
- A client_id + client_secret pair your Starmile partner issues you. It identifies your partner account and the warehouse (tenant) your orders are received at.
- Access token
- A short-lived bearer token obtained from /oauth/token with your credential, sent on every API call.
- Parent order
- The order you create. It gets exactly one Starmile tracking number and carries one or more items.
- Item
- A line in a parent order, identified by your own merchant_tracking_number.
- Tracking number
- The globally unique Starmile identifier assigned to a parent order, used to follow it through the flow.
- Service
- A named logistics offering your partner publishes, each backed by one flow. List the ones available to you with GET /api/v1/services; every order must name one via service_id (the Service's flow_definition_id).
- Rate
- The pricing your orders are billed at for a given service and corridor (origin → destination), with weight tiers. Preview the rates bound to you with GET /api/v1/rates.
- external_parent_id
- Your own reference for a parent order, echoed back on the order and in the status pool.
- Region reference
- How you address a Home Delivery destination: your OWN parent region id/code (parent_region) plus your own leaf region id/code (region). Starmile maps that pair, per partner, to one of its regions — your ids never need to match ours.
- region_status
- On the create-order response: whether your Home Delivery region reference resolved. "mapped" = resolved; "pending_mapping" = the order was accepted but your reference is not mapped yet (an operator maps it and the order resolves automatically — do not resend); "not_applicable" = PUDO / locker / clearance service (no home region).
- Status pool
- A pull-based, per-credential feed of status changes to your orders. You poll GET /api/v1/partner/changes?since=<cursor> instead of receiving pushed webhooks.
- Inbound partner event
- A lifecycle event you report for a package you handle (shipment.* / parcel.* / customs.* / leg.*) via POST /api/v1/partner/events. It is validated before it is accepted and then advances the package.
- Scope
- An ability on your credential that gates what you can call — e.g. orders:create, orders:update, orders:cancel, status:read, events:transport. You hold any combination your partner grants.