Skip to main content

Create Dropship Label

POST 
/api/purchase-orders/:purchase_order/dropship-labels

Requests a dropship label for the purchase order — buy it now, or schedule the purchase for the date the order will be ready to ship (the label is bought at the configured purchase time on that date in the supplier's timezone).

Required scope: purchase-orders:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Body fields:

  • ready (string, required): now or date
  • ship_date (string, required when ready=date, Y-m-d): today or later in the supplier's timezone, at most 90 days ahead. Ignored when ready=now.
  • service_token (string, optional, max 191): pin a service from Quote Dropship Label Rates; omitted = cheapest allowed rate Package fields (packages, 1–10 entries, required):
  • packages.*.weight (number, required, > 0)
  • packages.*.weight_unit (string, required): lb, oz, kg, g
  • packages.*.length / width / height (number, required, > 0)
  • packages.*.dimension_unit (string, required): in, cm
  • partial (boolean, optional): true = ship only the items in lines; false = ignore lines and label the whole order
  • lines (array, optional; required when partial=true): ship only part of the order. Omit for every open line. Rows with a quantity of 0 are dropped; when lines is sent (or partial=true) at least one row must have a positive quantity, otherwise 422 "Select at least one item to ship."
  • lines.*.purchase_order_line_id (integer, required): must belong to this purchase order
  • lines.*.quantity (number, required, >= 0; 0 = not in this shipment)

Idempotent: when the purchase order already has an open full-order label, that label is returned with 200 instead of creating another. A new label returns 201.

Domain failures return 422 with {message, reason} where reason is one of: no_provider (no label-capable shipping integration is assigned to the supplier or set as the default), not_eligible (the purchase order cannot get a label — e.g. not a dropship order, closed, or the supplier uses their own labels), purchase_failed (the carrier/provider refused the purchase), already_in_progress, relabel_limit_reached, invalid_state (the label's status does not allow the action) or provider_unavailable (the shipping provider could not be reached).

Label objects include label_file_count (number of downloadable label files, one per package; 0 until purchased) — pass a zero-based index below it as package to Download Dropship Label. portal_url (on each label and at the top level) is returned only to users with the purchase_orders.update permission — and, when calling with a Personal Access Token, only if the token has the purchase-orders:write scope; otherwise it is null. The link carries the supplier's share token, which lets its holder buy, re-label and void labels.

Authentication: Requires Bearer token.

Requires permission: purchase_orders.update

Request​

Responses​

Created

Response Headers
    Content-Type