Starmile Partner API

Introduction

The Starmile Partner API lets a connected partner hand packages to Starmile cross-border logistics over a simple REST interface. Authenticate with OAuth2 client credentials, list the services available to you, then create orders — each one enters a Starmile flow and is tracked end to end.

The API is versioned under /api/v1. The base URL is your Starmile partner’s host — for example https://api.starmile.io. All requests and responses are JSON over HTTPS.

Before you start

Your Starmile partner issues you a credential — a client_id and client_secret — from their console. The credential is bound to your partner account and the warehouse your orders are received at, so you never send those in the request body.

How it works

Exchange your credential at POST /oauth/token for a short-lived bearer token (client_credentials grant).
Read your services & rates — GET /api/v1/services and GET /api/v1/rates — to learn the service_id values you may order and how they are priced.
Create orders at POST /api/v1/orders with the token, naming a service_id from your services.
Follow your orders by polling the status pool — a pull-based feed of status changes.

Sandbox vs production

Endpoints, request shapes and status codes are identical in both. Use the credential and base URL your partner gives you for each environment.

# 1. Exchange your credentials for an access token
curl -X POST https://api.starmile.io/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "<your client id>",
    "client_secret": "<your client secret>"
  }'

# 2. List the services you may order (pick a service_id)
curl https://api.starmile.io/api/v1/services \
  -H 'Authorization: Bearer <access_token>'

# 3. Create an order with the returned bearer token
curl -X POST https://api.starmile.io/api/v1/orders \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "service_id": 5,
    "external_parent_id": "PO-10294",
    "items": [{ "merchant_tracking_number": "TRK-1" }]
  }'

Authentication

Exchange your client_id and client_secret for a bearer token.

Services & rates

List the services and rates available to you.

Create an order

Hand a package off to Starmile over the order API.

Status updates

Poll the status pool for changes to your orders.