For the complete documentation index, see llms.txt. This page is also available as Markdown.

Orders

Administrative endpoints for orders — the purchase records created when a customer completes the checkout flow. These endpoints are used by Omnitron to push order status updates to Commerce and to query order details.

Core Capabilities

1. Order Listing & Filtering

  • Retrieve a paginated list of orders, newest first.

  • Filter by status, order number, user email, creation date range, payability, and easy return code.

  • Order results with the sort parameter; created_date is supported.

2. Order Retrieval

  • Retrieve a single order by its identifier.

  • Retrieve the legal agreements (contracts) associated with an order via the /orders/{id}/order_agreements/ endpoint.

3. Order Update

  • Fully or partially update an order — primarily used to advance the order status.

  • When an order is moved from waiting (200) to approved (400) or payment_waiting (300), all waiting order items are updated to the same status and their sold quantities are recalculated.

4. Async Order Completion

  • Trigger asynchronous completion of an order created through a deferred checkout flow via POST /orders/complete_async/.

Order Statuses

The status field controls the lifecycle of an order. Values are numeric strings.

Value
Name
Description

50

cancellation_waiting

Cancellation has been requested and is pending.

100

cancelled

The order has been cancelled.

200

waiting

The order has been created but payment has not yet been confirmed.

300

payment_waiting

Payment has been initiated and is waiting for confirmation.

350

confirmation_waiting

The order is awaiting manual confirmation.

400

approved

Payment confirmed; the order is approved for fulfilment.

430

waiting_for_substitute

Waiting for a substitute product.

450

preparing

The order is being prepared / packed.

500

shipped

The order has been dispatched to the carrier.

510

shipped_and_informed

The order has been shipped and the customer has been notified.

520

ready_for_pickup

The order is ready for in-store collection.

540

attempted_delivery

A delivery attempt was made but the recipient was unavailable.

544

review_started

A trade-in review has been started.

545

review_waiting

A trade-in review is waiting.

546

waiting_for_payment

Waiting for trade-in payment.

547

paid

Trade-in payment received.

550

delivered

The order has been delivered to the customer.

600

refunded

The order has been refunded.

700

merged

An add-on order that has been merged into the main order.

Dynamic Settings & Environment Variables

PUT /orders/{id}/ and PATCH /orders/{id}/ save the order and then execute a set of post-update actions (notifications, emails, SMS) whose behaviour is controlled by the following dynamic settings. The settings below do not affect GET responses or the order_agreements / complete_async actions.

Key

Type

Default

Effect on PUT/PATCH

SEND_SHIPPING_NOTIFICATIONS_PARTIALLY

boolean

false

When true, a shipping notification is sent per order item as each item is shipped, instead of once when the whole order reaches shipped status.

SEND_SHIPPING_DELIVERED_NOTIFICATIONS_PARTIALLY

boolean

false

When true, a delivery notification is sent per order item as each item is delivered.

SEND_ORDER_CANCELLED_NOTIFICATIONS_PARTIALLY

boolean

false

When true, a cancellation notification is sent per order item as each item is cancelled, instead of once when the whole order is cancelled.

SEND_REFUND_RESULT_NOTIFICATIONS

boolean

false

When true, a notification is sent to the customer when the refund result is processed.

SEND_INVOICE_AVAILABLE_NOTIFICATIONS

boolean

true

When true, a notification is sent to the customer when e_archive_url is set on an order item.

NOTIFICATION_GATEWAY

string

""

The name of the active push notification gateway. When empty, push notifications triggered by status changes are silently skipped. Must match a key in NOTIFICATION_GATEWAYS.

NOTIFICATION_GATEWAYS

object

{"console": {"conf": {}}}

Configuration map for available push notification gateways. Keys are gateway names; values are gateway-specific config objects.

SMS_GATEWAY

string

"console"

The name of the active SMS gateway. "console" logs to stdout without sending. Must match a key in SMS_GATEWAYS.

SMS_GATEWAYS

object

{"console": {"conf": {"verify_message": "Verification code: {}"}}}

Configuration map for available SMS gateways. Keys are gateway names; values are gateway-specific config objects.

EMAIL_BCC_AND_CC

object

all email templates mapped to {"bcc": [], "cc": []}

Per-template BCC and CC addresses for outgoing emails. Keys are email template names (e.g. orders_completed); values are {"bcc": [...], "cc": [...]}.

Environment variables: No environment variables are read directly by these endpoints.

Last updated

Was this helpful?