API reference

Services & rates

Read-only endpoints that tell you what you may order and how it is priced. Both are scoped to your credential — services to the warehouse (tenant) it is bound to, rates to your partner account. Call them before creating an order to pick a valid service_id.

A Service is a named logistics offering your partner publishes, each backed by one flow. A Rate is the pricing your orders are billed at for a service and corridor (origin → destination), broken into weight tiers.

What to send on order creation

On order creation you pass only the Service’s own id from GET /api/v1/services as service_id— the flow and the corridor (origin → destination) are resolved from it. You do not send a rate: Starmile resolves the applicable rate automatically and bills at its configured trigger status. GET /api/v1/rates stays available so you can review your pricing.

This lists only the services you are contracted for — the ones you hold an active rate on. A service you have no rate for is not returned, and creating an order against it is rejected 422. Ask your partner manager to set up a rate to enable a new service.

List services

GET/api/v1/services

Response — data[]

idintegeroptional: The Service's own identifier (for display). Do NOT send this as an order's service_id.
namestringoptional: Human-readable service name set by your partner.
flow_definition_idintegeroptional: The flow this service runs. This is the value you pass as service_id when creating an order.
flow_keystringoptional: Stable machine key of the flow (e.g. cb3_cross_border_terminal_hd).
flow_labelstringoptional: Human-readable flow label.
familystringoptional: Flow family — "cross_border" or "domestic".
variantstringoptional: Flow variant within the family (e.g. lm_hd, fm_mm).
scopestringoptional: Flow scope (e.g. cross_border).
org_country_idintegeroptional: The tenant (OrgCountry) the service belongs to.

curl https://api.starmile.io/api/v1/services \
  -H 'Authorization: Bearer <access_token>'

List rates

GET/api/v1/rates

Returns only the rates bound to your partner account. Each rate is priced in weight tiers — find the tier whose min_kg / max_kg range covers your parcel.

Response — data[]

idintegeroptional: The rate identifier.
service_idintegeroptional: The flow this rate prices — matches a Service's flow_definition_id and the service_id you send on order creation.
namestringoptional: Human-readable rate name.
origin_countrystringoptional: ISO-3166-1 alpha-2 origin country (nullable).
destination_countrystringoptional: ISO-3166-1 alpha-2 destination country (nullable).
directionstringoptional: "sell" (what you are charged) or "buy".
calculation_typestringoptional: "per_kg" or "per_package".
weight_typestringoptional: "actual" or "volumetric" — which weight the tiers apply to.
currencystringoptional: ISO-4217 currency code.
minimum_chargenumberoptional: Floor charged when the tier price falls below it (nullable).
statusstringoptional: "active" or "inactive".
tiers[]arrayoptional: Weight bands — each with min_kg, max_kg and price.
bindings[]arrayoptional: Which partner / service / tenant the rate is bound to.

curl https://api.starmile.io/api/v1/rates \
  -H 'Authorization: Bearer <access_token>'