Orders

Validates and queues a sales order for asynchronous processing. Request bodies are limited to 1 MiB. The request may contain at most 50 line items; each SKU is limited to 100 characters, and quote_number is limited to 50 characters.

Poll the URL returned in data._links.self after creation. 202 Accepted means the submission is queued, not that the order was successfully created. A queued submission is available through GET with its queue-derived status. GET returns 200 OK whenever the record is found, including pending or failed processing. 404 means not found or inaccessible; it does not mean “still processing.”

Always inspect data.queue_error, even when data.status is a normal order status such as confirmed. Canonical order statuses remain unchanged. queue_error is omitted when the queue is not failed; its absence alone does not establish successful creation.

Display queue_error.message and any optional queue_error.skus. Unknown or unresolved item IDs are never returned. Known validation messages cover inactive items, phone number length, attention length, and attachment filename length. Other errors use safe generic wording.

Compatibility change: queue_result_code now contains one of these public failure codes, duplicate, or null, rather than raw worker codes.

Example failed-processing fields, returned alongside existing order details with HTTP 200:

Code
 
{
  "data": {
    "id": "990e8400-e29b-41d4-a716-446655440000",
    "status": "failed_erp",
    "order_status": "failed",
    "queue_result_code": "ORDER_CREATE_FAILED",
    "queue_error": {
      "code": "ORDER_CREATE_FAILED",
      "message": "Inactive items cannot be added to an order.",
      "skus": ["ABC-123"]
    }
  }
}

Do not automatically resubmit attachment failures or ambiguous processing failures. Direct users to support; an order may already exist.

For POST /v1/sales-orders, send an Idempotency-Key (1–255 characters), scoped to your tenant.

• Replay an ambiguous request: If the POST response is lost or a timeout leaves acceptance uncertain, replay the identical body with the same key. This does not retry failed processing. Once accepted, poll data._links.self.
• Submit a corrected order: A corrected creation submission requires a new key. Changing the payload while reusing the original key returns 409. A new key permits a new submission; consumer duplicate handling must make that submission safe.
• Attachment or ambiguous processing failures: Do not automatically resubmit ORDER_ATTACHMENT_FAILED or ORDER_PROCESSING_FAILED, including with a new key. Direct users to support because an order may already exist.

Do not assume other write endpoints are idempotent or automatically retry account/key creation.

Returns invoices linked to a sales order, resolved by the order's public ID.

Returns shipments linked to a sales order, resolved by the order's public ID.

Poll the URL returned in data._links.self after creation. 202 Accepted means the submission is queued, not that the order was successfully created. A queued submission is available through GET with its queue-derived status. GET returns 200 OK whenever the record is found, including pending or failed processing. 404 means not found or inaccessible; it does not mean “still processing.”

Always inspect data.queue_error, even when data.status is a normal order status such as confirmed. Canonical order statuses remain unchanged. queue_error is omitted when the queue is not failed; its absence alone does not establish successful creation.

Display queue_error.message and any optional queue_error.skus. Unknown or unresolved item IDs are never returned. Known validation messages cover inactive items, phone number length, attention length, and attachment filename length. Other errors use safe generic wording.

Compatibility change: queue_result_code now contains one of these public failure codes, duplicate, or null, rather than raw worker codes.

Example failed-processing fields, returned alongside existing order details with HTTP 200:

Code
 
{
  "data": {
    "id": "990e8400-e29b-41d4-a716-446655440000",
    "status": "failed_erp",
    "order_status": "failed",
    "queue_result_code": "ORDER_CREATE_FAILED",
    "queue_error": {
      "code": "ORDER_CREATE_FAILED",
      "message": "Inactive items cannot be added to an order.",
      "skus": ["ABC-123"]
    }
  }
}

Do not automatically resubmit attachment failures or ambiguous processing failures. Direct users to support; an order may already exist.