Skip to main content

Create Purchase Order

POST 
/api/purchase-orders

Create a new purchase order with optional line items.

Required scope: purchase-orders:write

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

Authentication: Requires Bearer token.

Required fields:

  • purchase_order_date (date)
  • supplier_id OR supplier_name
  • currency_id OR currency_code
  • destination_warehouse_id: warehouse the stock will be received into (required for standard purchase orders; omit for dropship purchase orders, which ship directly to the customer)

Optional fields:

  • purchase_order_number: custom PO number (auto-generated if omitted)
  • approval_status: pending (default) or approved
  • order_status: draft (only allowed value; omit for open)
  • shipment_id: required when destination_warehouse is Amazon FBA

Line item fields:

  • product_id OR sku (required if not a cost line)
  • quantity (required, min:0)
  • amount (required, min:0) — unit cost
  • description, discount, tax_rate_id, estimated_delivery_date, nominal_code_id, is_free_of_charge, free_of_charge_reason, linked_backorders all optional

Requires permission: purchase_orders.create

Approval policy: When the purchase-order approval policy is enabled, sending approval_status: approved approves and opens the order only if you can approve it in one call (its amount is within your limit, or its tier auto-approves). Otherwise the order stays in draft, an approval request is raised to the policy's approvers, and the response adds top-level approval: {requested: true, request_id}. The data object also adds approval — present only while the purchase-order approval policy is enabled (omitted otherwise, so responses are unchanged without a policy). Fields: policy_enabled, request_id, status (pending, approved, rejected, withdrawn, superseded; null when no request was ever raised), reason, tier_name, waiting_on[] (id, name of users who can act now), reapproval_pending (an open order whose changes await re-approval), awaiting_viewer (you can act on it now), and on single-order responses can_approve_directly (you can approve it in one call — within your limit), blocked_reason (why not), send_blocked_reason (why it cannot be sent to the supplier yet) and deposit_blocked_reason (why no new vendor deposit can be taken against it). Use GET /api/approval-requests/for/purchase_order/{id} for the full approval timeline.

Request​

Responses​

OK

Response Headers
    Content-Type