Create Purchase Order
POST/api/purchase-orders
Create a new purchase order with optional line items.
purchase-orders:writeGrant 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
Request
Responses
- 200
- 401
- 403
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.