Skip to main content

List Dropship Labels for Purchase Order

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

Returns the purchase order's current dropship label (with its event timeline), the full label history (newest first, including voided and replaced labels), whether a label can be requested now, and the supplier portal link.

Required scope: purchase-orders:read

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

eligibility fields:

  • eligible (boolean)
  • reason (string|null): why a label cannot be requested
  • mode (string): the supplier's label mode — vendor_label (labels off — vendor ships on their own account), auto (label is bought automatically when the PO is sent) or on_request (vendor requests it from the portal)
  • provider (object|null): the shipping integration that will buy the label — id, name, type (shippo, shipstation, starshipit, easypost), label, integration_name (the integration's display name, e.g. "Shippo") and image_url (relative path to the provider logo, null when the provider has none)
  • default_packages (array): pre-filled packages from the supplier's default package, else from product weights/dimensions; empty when they cannot be derived
  • max_relabels / relabels_remaining (integer)
  • supplier_today (string, Y-m-d): today's date in the supplier's timezone — the earliest allowed ship_date
  • max_ship_date (string, Y-m-d): the latest allowed ship_date (90 days after supplier_today)
  • supplier_timezone (string): IANA timezone used for ship dates and scheduled purchases, e.g. America/New_York

current is null when the purchase order has no label. portal_url is null when the purchase order has no share link yet, or when the caller is not allowed to see it (see below).

Label objects include provider_image_url (relative path to the label provider's logo, null when it has none; returned alongside integration_instance_name on current and on single-label responses) and 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.

provider_supports_tracking (per label) and eligibility.provider.supports_tracking say whether the label provider sends tracking updates. When false (ShipStation), a label goes from purchased to shipped when the vendor marks it shipped or at the end of the ship date, and never reaches in_transit or delivered. null when unknown.

Request​

Responses​

OK

Response Headers
    Content-Type