API reference (v1)

Authentication

Send your key as a bearer token. A key acts with the permissions of the team member who created it and stops working if they leave the organization or the key is revoked. Test keys (sk_test_…) only create test labels that are not valid for postage; live keys (sk_live_…) buy real postage.

curl https://YOUR-APP/api/v1/rates \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"to":{"name":"Jane Doe","street1":"500 Pine St","city":"Seattle","state":"WA","zip":"98101"},
       "parcel":{"weight_oz":20,"length_in":10,"width_in":8,"height_in":4}}'

Endpoints

• POST/api/v1/rates
  Create a shipment and get priced rates. Omit "from" to ship from your default address. Rates expire at expires_at.
  Scope: rates:read
• GET/api/v1/shipments/:id
  Shipment status, current rates (until purchased), label and tracking summary.
  Scope: rates:read
• POST/api/v1/labels
  Buy postage for a rate. Requires an Idempotency-Key header. 201 = purchased, 202 = being confirmed with the carrier (poll the label).
  Scope: labels:write
• GET/api/v1/labels/:id
  Label status, tracking number and file_url.
  Scope: labels:write
• GET/api/v1/labels/:id/file?format=pdf|png|zpl
  Download the label document.
  Scope: labels:write
• GET/api/v1/tracking/:tracking_number
  Tracking status and events for one of your shipments.
  Scope: tracking:read

Buying labels safely

Generate one Idempotency-Key per label you intend to buy and reuse it on every retry: the same key always returns the same label and never buys postage twice. Send the price you were quoted as expected_price_cents; if the price changed, the request is refused and nothing is bought.

curl https://YOUR-APP/api/v1/labels \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: order-1001-label" \
  -H "Content-Type: application/json" \
  -d '{"rate_id":"<rate id>","expected_price_cents":742}'

Errors and limits

Errors share one shape. Include request_id when contacting support.

{ "error": { "code": "PRICE_MISMATCH", "message": "…", "request_id": "…" } }

401 invalid/revoked key · 403 missing scope, plan or permission · 404 not found (including other organizations’ data) · 409 conflicts (price changed, label exists) · 422 validation · 429 rate limited (per key).