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.

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.

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.