Purchase Label
POST/api/fulfillment-orders/:fulfillmentOrder/shippo/labels
Buys the label(s) for a rate returned by Get Shipping Rates. The Shippo instance and the ship-from address are resolved from the fulfillment order (its Shippo instance and its warehouse's sender-address mapping) — they are never passed by the client. Requires a token with the orders read/write scope. When the label is bought a sales order fulfillment is created with the tracking number and, if record_shipping_costs is on, the postage cost.
orders:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Body fields:
- rate_object_id (string, required): the chosen rate's object_id. Max 64.
- label_file_type (string, optional, nullable): PDF_4x6, PDF, PDF_A4, PDF_A5, PDF_A6, PNG or ZPLII. Defaults to the instance's label_file_type setting.
- shipment_object_id (string, optional, nullable): the shipment_object_id from the quote. Max 64.
- rate (object, optional, nullable): a snapshot of the chosen rate from the quote, used to record the carrier, service and cost:
- rate.amount (number, nullable, min 0), rate.currency (string, nullable, 3 chars)
- rate.amount_local (number, nullable, min 0), rate.currency_local (string, nullable, 3 chars)
- rate.provider, rate.carrier, rate.carrier_name (string, nullable, max 64)
- rate.servicelevel_token (string, nullable, max 128), rate.servicelevel_name (string, nullable, max 255)
- rate.shipment (string, nullable, max 64): used as the shipment id when shipment_object_id is omitted.
Returns 201 with the purchased label(s) (one per parcel). Returns 202 when Shippo is still processing the purchase — the labels are returned in QUEUED/WAITING state and complete automatically via webhook or the tracking reconcile. Returns 409 when a live label already exists or a purchase is in progress, 422 {message, messages[]} when Shippo fails the purchase (messages carries Shippo's reasons). Returns 422 {message, reason} when the fulfillment order cannot use Shippo labels. reason is one of: no_instance (Shippo is not connected), fulfillment_order_closed (the fulfillment order is no longer open), warehouse_unmapped (its warehouse has no usable Shippo sender address), international (only US ship-to addresses are supported), address_incomplete (the ship-to address is missing a required field). Shippo client-side refusals (including a rejected token) return 422 {message, messages[]}; Shippo throttling, Shippo server errors and connection failures return 502. Returns 422 with field errors when validation fails, 404 for an unknown fulfillment order.
Authentication: Requires a Bearer token.
Request
Responses
- 201
- 202
- 401
- 403
- 404
- 409
- 422
- 429
- 502
Created
Response Headers
Accepted
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Not Found
Response Headers
Conflict
Response Headers
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.
Bad Gateway