Skip to main content

Submit Checkout

POST 

/api/portal/checkout

Submit the active cart. The cart is re-priced and re-validated; the account's minimum order value is enforced (422 below it). If the account's approval policy requires it, an approval request is created (status pending_approval, no order yet); otherwise a draft order is created and the cart is emptied. ship_to_address_id (or an inline ship_to), customer_po_number, requested_delivery_date, shipping_method_id, note, and payment_method are accepted. Lines that cannot be supplied are rejected with 422 unpurchasable_lines, listing each offending line and a reason of insufficient_stock (fewer units in stock than requested, and no backorder), out_of_stock, or unpriced.

Buyer portal token

Called by a B2B portal buyer with the bearer token POST /api/portal/auth/login returns (or the buyer's feed key) — not with a staff Personal Access Token.

Every checkout is checked against the account's credit: an account on credit hold gets 422 credit_hold, and an order that would take the account's open balance past its credit limit gets 422 exceeds_credit_limit (with available_credit and shortfall). Accounts with no credit limit are not capped. payment_method is recorded with the order for reference only. Portal checkout does not take payment, so the value never skips the credit check.

A buyer whose portal role is Viewer gets 422 role_cannot_order; a ship_to_address_id that is not one of the account's addresses gets 422 unknown_ship_to_address ("That ship-to address is not on your account.").

Request fields

  • ship_to_address_id (integer, optional) — one of the account's saved addresses.
  • ship_to (object, optional; required for a dropship order) — a typed address: name, address1, city required; company, address2, address3, province, province_code, zip, country, country_code, phone, email (valid email) optional.
  • save_address (boolean, optional, default false) — keep a typed ship_to in the account's address book. Only matters when the account may ship to one-time addresses (account.ship_to_policy = may_ship_anywhere); otherwise a typed address is always saved (may_add_saved) or refused (saved_only).
  • customer_po_number, requested_delivery_date (date), shipping_method_id (integer), note, payment_method — optional.
  • dropship (object, optional) — ship the order straight to the buyer's own customer:
    • dropship.enabled (boolean) — turns the checkout into a dropship order.
    • dropship.retailer_order_number (string, required when enabled, max 128) — the buyer's own order number for this sale; each number can be used for one open order.
    • dropship.gift_message (string, optional, max 500) — printed on the packing slip.
    • dropship.shipping_method_id (integer, optional) — the requested shipping service; must be one the account's dropship program allows (account.dropship.allowed_shipping_method_ids). Falls back to shipping_method_id, then the program's default.

Ship-to policy. A typed ship_to on an account whose ship_to_policy is saved_only (or a one-time address the policy does not allow) gets 422 ship_to_not_allowed. A dropship order's consumer address is never saved to the address book and is not subject to the policy.

Dropship orders. The cart is priced on the account's dropship pricing, the dropship fee and shipping charge are added, the minimum order value does not apply when the program exempts dropship orders, and the parcel ships blind under the buyer's branding. The response's dropship block carries the retailer_order_number and the ship_by_date the merchant committed to (null for a normal order). An approval policy still applies to the buyer's own dropship checkout (a rep placing it on the account's behalf skips it). The goods, the dropship fee and the shipping charge are all taxed at the order's tax rate, the same as the Shipping charge on an ordinary portal order. A dropship checkout ignores expected_shipping_amount and is never refused with shipping_changed: its shipping comes from the dropship program, not portal shipping pricing. Dropship-specific 422 reasons: dropship_not_enabled; portal_account_inactive (the account is pending or disabled); duplicate_retailer_order_number (an open order already uses that number — context names it); not_dropship_eligible (special order items, or a product that cannot be dropshipped); unknown_sku, unpriced, insufficient_stock (with context.lines); address_incomplete (context.field names the missing part — check addresses first with Validate Address); international_not_allowed; international_phone_required; shipping_method_not_allowed / unsupported_service. A missing ship_to or dropship.retailer_order_number is a standard validation error.

Shipping is re-priced server-side for the chosen shipping_method_id (else the account's default for the ship-to) and written onto the order: a Shipping charge for a priced method, nothing for free, and "shipping pending" for a method calculated on review. Send expected_shipping_amount (number ≥ 0, nullable; null = calculated on review) with the price shown by List Shipping Methods or Estimate Checkout: when the re-priced shipping differs by more than the greater of 1.00 and 0.5%, the order is not placed and the response is 409 shipping_changed with the new shipping_amount (and context.shipping_label / context.currency_code) — confirm it and submit again with the new amount. Omit the field to skip the check. A chosen method that does not apply to this order gets 422 shipping_method_unavailable.

When the seller calculates tax live with a tax engine (Numeral), the ship-to must be an address the engine can tax: one it refuses (ZIP / state mismatch, malformed address) gets 422 tax_address_invalid with the engine's error_code and the ship_to_address_id in context. Fix the address and resubmit; Estimate Checkout reports the same problem before submitting. Any other tax-engine failure does not block the order.

Product lifecycle: each unpurchasable_lines entry also carries message (the buyer-readable reason, e.g. "Only 5 left. This item has been discontinued."), discontinued (true when the product's lifecycle state blocks backorders) and successor (id, sku, name of the visible replacement, or null). When the only offending line is a discontinued product, the error names it: "GLUE-500: Only 5 left. This item has been discontinued. Please review your cart."

Request​

Responses​

Created

Response Headers
    Content-Type