Skip to main content

Create Dropship Order

POST 
/api/portal/dropship/orders

Sends one consumer order for the supplier to ship directly to your customer, priced at your dropship pricing tier with the program's dropship fee and shipping charge added. Your retailer_order_number is the idempotency key: sending the same number again while that order is still open creates nothing and returns the existing order with 200 and duplicate: true, so a timed-out request is safe to retry. A new order returns 201. If your company's approval policy holds the order, the response is 202 with code: pending_approval and an approval_id — the order is placed (and its ship-by clock starts) once it is approved.

Not yet available to API tokens

This endpoint currently requires session authentication; Personal Access Token scope support is in progress.

Auth: a portal session bearer token, or a portal API key (pfk_…) with the dropship:write scope, sent as Authorization: Bearer. A Viewer-role buyer (or a key owned by one) is refused with 403 viewer_read_only. Requires an enabled dropship program; 60 requests a minute.

Body fields:

  • retailer_order_number (string, required, max 128) — your own order number.
  • ship_to (object, required) — the consumer's address; it is used for this order only and never saved to your address book.
    • name (string, required, max 255) — recipient name.
    • company (string, optional, max 255).
    • address1 (string, required, max 255) — street address.
    • address2, address3 (string, optional, max 255).
    • city (string, required, max 255).
    • province (string, optional, max 255) — state/province name.
    • province_code (string, optional, max 10) — state/province code, e.g. CO.
    • zip (string, optional, max 20) — postal code; the address check may still require it for the destination.
    • country (string, optional, max 255).
    • country_code (string, optional, exactly 2 letters) — ISO country code; defaults to US.
    • phone (string, optional, max 64) — required for international destinations.
    • email (email, optional, max 255).
  • lines (array, required, 1–200 items) — repeated SKUs are merged.
    • lines.*.sku (string, required, max 255) — a SKU in your dropship catalog.
    • lines.*.quantity (integer, required, 1–100000).
  • shipping_method_id (integer, optional) — a shipping method your dropship program allows.
  • service (string, optional, max 255) — alternatively, a service name matched against your allowed methods (e.g. ground). With neither, the program's default service is used.
  • gift_message (string, optional, max 500) — printed on the branded packing slip.
  • notes (string, optional, max 2000) — a note to your supplier, shown on the order.

Business-rule errors return 422 with {code, message, field, errors}, where errors lists every problem line when the issue is per line. Codes: dropship_not_enabled (API intake is not enabled for your program), portal_account_inactive (your account is pending or disabled), retailer_order_number_required, retailer_order_number_invalid, address_incomplete, international_not_allowed, international_phone_required, shipping_method_not_allowed, empty_order, unknown_sku, not_dropship_eligible, unpriced, insufficient_stock, below_min_order_value (unless your program is exempt), credit_hold, exceeds_credit_limit. Field-shape problems return the standard 422 validation body.

The new order's status is usually received; its sla is computed from the program's ship-by rule.

Request​

Responses​

OK

Response Headers
    Content-Type