Common Workflows

End-to-end flows that chain V5 endpoints together. Each workflow lists the exact endpoint sequence and what to do with the response between steps.

Create, rate, label, and ship a single courier package. The most common V5 flow — covers ~80% of carrier integrations.

Use an Idempotency-Key header on steps 1, 3, and 4 so network retries can't double-charge or double-book.

Less-than-truckload freight has its own endpoints, all under the ltl:read / ltl:write scopes. Quoting is stateless: the booking call repeats the quote body and adds the chosen service.

Carrier adjustments also appear on GET /billing/transactions (needs billing:read): match them to the shipment with shipment_id and read the cause from adjustment.reason.

Use an Idempotency-Key header on step 2 so a network retry can't book twice.

Group many shipments into a single batch, generate labels for all of them, and drain per-shipment failures.

If you buy each label as you pack (POST /labels/{shipment_id}), there is nothing left for process to buy — it answers 422 and leaves the batch open. Close the batch instead; nothing is purchased or charged.

Orders imported from a connected store (Shopify, Amazon, …) are listed by GET /orders. To have the label mark the order fulfilled in the store and send it the tracking number, create the shipment from the order with store_order_id — the order's id, not the store's order number. order_id alone is only a reference and links nothing.

Steps 2 and 4 can be one call: POST /labels takes store_order_id too. If that call answers 422 or 402 with details.shipment_id, the carrier already holds a booking for the shipment: retry with POST /labels/{shipment_id} rather than creating the shipment again.

• An order has one shipment. A second create for the same order is refused with conflict (409 on POST /labels), naming the existing shipment.
• PUT /shipments/{shipment_id} keeps the link; only order_id cannot be changed on a linked shipment.
• Drafts made by a scheduled import (POST /crons/{cron_id}/run) are linked the same way and additionally have your automation rules applied. They are created on your account's region.
• Voiding the label cancels the fulfillment in the store where the store supports it.

Labels are paid from the account's credit balance. If the balance is low, top up first.

Always send an Idempotency-Key header on step 1. Top-up retries without a key double-charge.

Customs declarations need a per-product HS code. V5 wraps the TRU classification API so you can ask for a suggested code, optionally verify the manufacturer, then persist the product.

If an existing product enters Manufacturer Failed after import, you can run just step 2 on it and re-call POST /products/{sku}/approve-classification.

CUSMA certificates are submitted and reviewed on the dashboard's Products page, but their state is on the product record, so you can gate shipping on it without opening the dashboard.

Gate on active_for_duty, not on status. status is the dashboard's label, and two of its values do not split the way a shipping gate needs:

• expiring is covered — the certificate ends within 30 days but still applies today. It is a cue to renew, not a reason to hold. It is also not a reliable renewal reminder: approval sets the product's internal "apply CUSMA" flag, and a product carrying it reports approved right up to the expiry date, so expiring only appears where that flag is not set.
• in_group means either that the group has no live certificate or that the group's certificate is expiring. The Products page collapses the two because a child product cannot renew its group's certificate, so the status alone cannot tell them apart. active_for_duty can.

{
  "data": {
    "sku": "MAPLE-SYRUP-250",
    "ddp_status": "Approved",
    "cusma": {
      "status": "approved",
      "active_for_duty": true,
      "submission_id": 4821,
      "reference_code": "CUSMA-2026-004821",
      "blanket_period_from": "2026-01-01",
      "blanket_period_to": "2026-12-31",
      "group_sku": null
    }
  }
}

Notes:

• cusma.status is not ddp_status. ddp_status is the customs classification; a product has to be DDP Approved with a US / CA / MX manufacturer before CUSMA applies at all, and one that is not reports cusma.status: "ineligible".
• A product in a product group inherits the group's certificate and reports approved_in_group / in_group / expired_in_group, with group_sku naming the parent.
• active_for_duty is what the duty calculation actually uses, and it is the field to gate on. It is true when both hold: the product's DDP record is itself CUSMA-eligible (DDP status Approved and a US / CA / MX manufacturer country on the DDP record), and an approved certificate covers today. When both hold it covers approved, approved_in_group, expiring, an in_group product whose group certificate is merely expiring, and a pending renewal where an earlier approved version still covers today.
• That first condition is why an approved-looking status can still report active_for_duty: false: status also accepts the manufacturer country from the product row. If the two copies disagree, no CUSMA treatment is applied — correct the manufacturer country on the DDP record.
• expiring means the certificate ends within 30 days. It is not a reason to hold on its own — the certificate still covers the product — but ship on active_for_duty as everywhere else, since an expiring product can still report false through the DDP-country case above.
• GET /products returns the same cusma block for every product on the page.

Some reseller and partner integrations need to show what a shipment would cost at Stallion's standard retail (small business) and enterprise published margins, alongside the account's own quoted rate.

Each tier entry has the same fields as the primary rate (service, subtotal, tax, total, currency, add_ons, etc.), so clients can display them without a separate parser. When the setting is off or the rate cannot be re-margined (no captured postage cost), the tier_pricing key is omitted.

The same opt-in field is available on v4 get-rates responses (rates[].tier_pricing).

Constraints

• Tier totals are derived from the already-fetched carrier cost — no extra carrier API calls.
• Stallion Protection add-ons are recomputed per tier because insurance pricing depends on the rate total.
• Booking always uses the account's primary quoted rate, not a tier comparison.

A service can be missing from a rates response for two very different reasons: the carrier didn't answer in time (transient — retry and it may come back), or the carrier answered and genuinely doesn't serve the lane. Every rates response (GET /rates/{shipment_id}, POST /rates, POST /rates/estimate) carries a meta object that makes the difference explicit:

{
  "data": [ ...rates... ],
  "meta": {
    "timeout_seconds": 7,
    "excluded_services": [
      {
        "postage_type_id": 141,
        "service": "intelcom.standard",
        "carrier": "Intelcom",
        "service_name": "Intelcom Standard",
        "reason": "carrier_timeout",
        "message": "The carrier did not respond within the 7-second rate timeout. ..."
      }
    ]
  }
}

Choosing a timeout

• A higher value (e.g. 15–25) trades latency for completeness — fewer carrier_timeout omissions, useful for batch quoting or building a lane-coverage dataset.
• A lower value (e.g. 3–5) favors a fast checkout: slow carriers are dropped and reported in meta.excluded_services instead of holding up the response.
• The cap is 25 seconds so the HTTP request itself can still complete; omitting the parameter uses the platform default (meta.timeout_seconds always tells you what was applied).

These don't need a multi-step description — they're single calls or small glue logic.

• Quote rates without creating a shipment — POST /rates with shipment details. Returns rates. No shipment row is created.
• Validate addresses — POST /addresses/validate before POST /shipments to surface bad zip/postal codes early.
• Manage imported orders — POST /orders, GET /orders, PUT /orders/{order_id}. Delete only before linking to a non-voided shipment.
• Find drop-off locations — GET /locations. Render the returned branch and partner-site addresses; refresh periodically because the catalog changes.

All mutating endpoints (POST, PUT, DELETE) accept an Idempotency-Key header. A retried request with the same key inside 24h returns the original response byte-for-byte. Reusing a key with a different body yields 409 idempotency_conflict. See Errors & Idempotency.