> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/admin/orders/create-an-order.md).

# Create an order

Validates the submitted order payload against the `Order` schema.

**Note:** The creation handler (`perform_create`) is intentionally a no-op on this endpoint — the order record is not persisted to the database. This endpoint exists to satisfy the Omnitron push protocol; actual order persistence is handled by the checkout flow.

```json
{"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"tags":[{"name":"Orders","description":"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.\n\n## Core Capabilities\n\n**1. Order Listing & Filtering**\n* Retrieve a paginated list of orders, newest first.\n* Filter by status, order number, user email, creation date range, payability, and easy return code.\n* Order results with the `sort` parameter; `created_date` is supported.\n\n**2. Order Retrieval**\n* Retrieve a single order by its identifier.\n* Retrieve the legal agreements (contracts) associated with an order via the `/orders/{id}/order_agreements/` endpoint.\n\n**3. Order Update**\n* Fully or partially update an order — primarily used to advance the order `status`.\n* 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.\n\n**4. Async Order Completion**\n* Trigger asynchronous completion of an order created through a deferred checkout flow via `POST /orders/complete_async/`.\n\n## Order Statuses\n\nThe `status` field controls the lifecycle of an order. Values are numeric strings.\n\n| Value | Name | Description |\n|-------|------|-------------|\n| `50` | `cancellation_waiting` | Cancellation has been requested and is pending. |\n| `100` | `cancelled` | The order has been cancelled. |\n| `200` | `waiting` | The order has been created but payment has not yet been confirmed. |\n| `300` | `payment_waiting` | Payment has been initiated and is waiting for confirmation. |\n| `350` | `confirmation_waiting` | The order is awaiting manual confirmation. |\n| `400` | `approved` | Payment confirmed; the order is approved for fulfilment. |\n| `430` | `waiting_for_substitute` | Waiting for a substitute product. |\n| `450` | `preparing` | The order is being prepared / packed. |\n| `500` | `shipped` | The order has been dispatched to the carrier. |\n| `510` | `shipped_and_informed` | The order has been shipped and the customer has been notified. |\n| `520` | `ready_for_pickup` | The order is ready for in-store collection. |\n| `540` | `attempted_delivery` | A delivery attempt was made but the recipient was unavailable. |\n| `544` | `review_started` | A trade-in review has been started. |\n| `545` | `review_waiting` | A trade-in review is waiting. |\n| `546` | `waiting_for_payment` | Waiting for trade-in payment. |\n| `547` | `paid` | Trade-in payment received. |\n| `550` | `delivered` | The order has been delivered to the customer. |\n| `600` | `refunded` | The order has been refunded. |\n| `700` | `merged` | An add-on order that has been merged into the main order. |\n\n## Dynamic Settings & Environment Variables\n\n`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.\n\n| Key | Type | Default | Effect on `PUT`/`PATCH` |\n|-----|------|---------|-------------------------|\n| `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. |\n| `SEND_SHIPPING_DELIVERED_NOTIFICATIONS_PARTIALLY` | boolean | `false` | When `true`, a delivery notification is sent per order item as each item is delivered. |\n| `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. |\n| `SEND_REFUND_RESULT_NOTIFICATIONS` | boolean | `false` | When `true`, a notification is sent to the customer when the refund result is processed. |\n| `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. |\n| `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`. |\n| `NOTIFICATION_GATEWAYS` | object | `{\"console\": {\"conf\": {}}}` | Configuration map for available push notification gateways. Keys are gateway names; values are gateway-specific config objects. |\n| `SMS_GATEWAY` | string | `\"console\"` | The name of the active SMS gateway. `\"console\"` logs to stdout without sending. Must match a key in `SMS_GATEWAYS`. |\n| `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. |\n| `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\": [...]}`. |\n\n**Environment variables:** No environment variables are read directly by these endpoints."}],"servers":[{"description":"Omnitron Remote Proxy (external access — recommended)","url":"https://{omnitron_url}/api/v1/remote/{channel_id}","variables":{"omnitron_url":{"default":"sandbox.akinon.com","description":"Omnitron server URL (e.g., {omnitron.akinon.com})"},"channel_id":{"default":"1","description":"The channel identifier the remote request is routed through"}}},{"description":"Commerce API Server (internal / direct access only)","url":"https://{commerce_url}/api/v1","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Internal commerce server URL, reachable only from within the Omnitron network"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Token credential sent in the Authorization header, in the form: `Token <your-token>`. Requires a staff (admin) account."}},"schemas":{"OrderRequest":{"type":"object","description":"The body of an order full update request.","required":["number","status","currency","user_email","shipping_option","shipping_option_slug","payment_option","payment_option_slug","installment_count","installment_interest_amount","amount","discount_amount","shipping_amount","refund_amount","discount_refund_amount","shipping_refund_amount"],"properties":{"number":{"type":"string","maxLength":128,"description":"The unique order number."},"status":{"$ref":"#/components/schemas/OrderStatus"},"currency":{"$ref":"#/components/schemas/OrderCurrency"},"user":{"type":["integer","null"],"description":"The identifier of the registered customer."},"user_email":{"type":"string","format":"email","description":"The email address of the customer."},"basket":{"type":["integer","null"],"description":"The identifier of the source basket."},"shipping_option":{"type":"integer","description":"The identifier of the shipping option."},"shipping_option_slug":{"type":"string","maxLength":128,"description":"The slug of the shipping option."},"payment_option":{"type":"integer","description":"The identifier of the payment option."},"payment_option_slug":{"type":"string","maxLength":128,"description":"The slug of the payment option."},"card":{"type":["integer","null"]},"bin_number":{"type":["string","null"],"maxLength":8},"installment":{"type":["integer","null"]},"installment_count":{"type":"integer"},"installment_interest_amount":{"type":"string","format":"decimal"},"segment":{"type":["integer","null"]},"shipping_address":{"type":["integer","null"]},"billing_address":{"type":["integer","null"]},"checkout_provider":{"type":["integer","null"]},"amount":{"type":"string","format":"decimal"},"discount_amount":{"type":"string","format":"decimal"},"shipping_amount":{"type":"string","format":"decimal"},"shipping_tax_rate":{"type":["string","null"],"format":"decimal"},"refund_amount":{"type":"string","format":"decimal"},"discount_refund_amount":{"type":"string","format":"decimal"},"shipping_refund_amount":{"type":"string","format":"decimal"},"invoice_number":{"type":["string","null"],"maxLength":32},"invoice_date":{"type":["string","null"],"format":"date-time"},"e_archive_url":{"type":["string","null"],"format":"uri","maxLength":1024},"tracking_number":{"type":["string","null"],"maxLength":256},"defined_tracking_url":{"type":["string","null"],"format":"uri","maxLength":512},"shipping_company":{"oneOf":[{"$ref":"#/components/schemas/OrderShippingCompany"},{"type":"null"}]},"shipping_tracking_url":{"type":["string","null"],"format":"uri","maxLength":500},"has_gift_box":{"type":["boolean","null"]},"gift_box_note":{"type":["string","null"],"maxLength":160},"language_code":{"type":["string","null"],"maxLength":256},"notes":{"type":["string","null"],"maxLength":320},"delivery_range":{"type":["object","null"],"properties":{"lower":{"type":["string","null"],"format":"date-time"},"upper":{"type":["string","null"],"format":"date-time"}}},"extra_field":{"type":["object","null"]}}},"OrderStatus":{"type":"string","description":"The lifecycle status of an order. Values are numeric strings that increase as the order progresses through its lifecycle.\n\n| Value | Name | Description |\n|-------|------|-------------|\n| `50` | `cancellation_waiting` | Cancellation requested, pending. |\n| `100` | `cancelled` | Order cancelled. |\n| `200` | `waiting` | Order created; payment not yet confirmed. |\n| `300` | `payment_waiting` | Payment initiated, awaiting confirmation. |\n| `350` | `confirmation_waiting` | Awaiting manual confirmation. |\n| `400` | `approved` | Payment confirmed; order approved for fulfilment. |\n| `430` | `waiting_for_substitute` | Waiting for a substitute product. |\n| `450` | `preparing` | Order being prepared / packed. |\n| `500` | `shipped` | Order dispatched to carrier. |\n| `510` | `shipped_and_informed` | Order shipped and customer notified. |\n| `520` | `ready_for_pickup` | Ready for in-store collection. |\n| `540` | `attempted_delivery` | Delivery attempted; recipient unavailable. |\n| `544` | `review_started` | Trade-in review started. |\n| `545` | `review_waiting` | Trade-in review waiting. |\n| `546` | `waiting_for_payment` | Waiting for trade-in payment. |\n| `547` | `paid` | Trade-in payment received. |\n| `550` | `delivered` | Order delivered to customer. |\n| `600` | `refunded` | Order refunded. |\n| `700` | `merged` | Add-on order merged into main order. |","enum":["50","100","200","300","350","400","430","450","500","510","520","540","544","545","546","547","550","600","700"]},"OrderCurrency":{"type":"string","description":"ISO 4217 currency code used for the order.","enum":["try","eur","usd","egp","gbp","mad","pln","sar","ron","uah","czk","huf","rub","bgn","iqd","kwd","bhd","omr","qar"]},"OrderShippingCompany":{"type":"string","description":"Carrier company used to ship the order.","enum":["acs","apiship","aramex","aramex_express","aras","arvato","asil","ay_cargo","b2c_direct","birgunde","bolt","boomex","bovo","boxaty","bpost_24_7","bpost_athome","bpost_international","bpost_pickup","bringo","bringo_express","cainiao","cargus","carriyo","carrtell","cathedis","cdek","ceva_cargo","chrono","city_express","clickpost","deliverigo","dhlexpress","dincer","dpd","droplight","evdemo_lojistik","extension","falcon_flex","fancourier","fareye","fast_cargo","fero_ai","gelal","giz","gkn","gls","hbexpress","hjetxl","hoopkapida","horoz","iMile","in_post","ismail","jetizz","jetizz_v7","jetlogi","k_gelsin","k_sende","kargo_ist","loomis","mng","monist","murat_lgc","mylerz","mylerzsdd","netkargo","novaposhta","octovan_express","other","packupp","pakettaxi","pinkpost","pony_express","porter_express","pts_express","ptt","r2s","rupost","sameday","scotty","sendeo","shipx","sky_express","speedy","speeta","surat","svuum","tmmexpress","tnt_cargo","tyexpress","ups","ups_intl","yurtici"]},"Order":{"type":"object","description":"A customer order record.","properties":{"pk":{"type":"integer","description":"The unique identifier of the order. Assigned by the server; read-only.","readOnly":true},"number":{"type":"string","maxLength":128,"description":"The unique order number. Auto-generated on creation using the pattern defined by the `ORDER_NUMBER_GENERATOR_CONF` dynamic setting."},"status":{"$ref":"#/components/schemas/OrderStatus"},"currency":{"$ref":"#/components/schemas/OrderCurrency"},"user":{"type":["integer","null"],"description":"The identifier of the registered customer who placed the order. `null` for guest orders."},"user_email":{"type":"string","format":"email","description":"The email address of the customer, always present including for guest orders."},"basket":{"type":["integer","null"],"description":"The identifier of the basket from which the order was created."},"shipping_option":{"type":"integer","description":"The identifier of the shipping option selected for this order."},"shipping_option_slug":{"type":"string","maxLength":128,"description":"The slug of the shipping option at the time of ordering."},"payment_option":{"type":"integer","description":"The identifier of the payment option used for this order."},"payment_option_slug":{"type":"string","maxLength":128,"description":"The slug of the payment option at the time of ordering."},"card":{"type":["integer","null"],"description":"The identifier of the saved card used, if applicable."},"bin_number":{"type":["string","null"],"maxLength":8,"description":"The first 6-8 digits of the credit card used, for instalment lookup."},"installment":{"type":["integer","null"],"description":"The identifier of the instalment option selected, if applicable."},"installment_count":{"type":"integer","description":"Number of instalments. `1` indicates a single (non-instalment) payment."},"installment_interest_amount":{"type":"string","format":"decimal","description":"Additional amount charged as instalment interest. `\"0.00\"` for non-instalment orders."},"segment":{"type":["integer","null"],"description":"The identifier of the customer segment at the time of purchase."},"shipping_address":{"type":["integer","null"],"description":"The identifier of the delivery address."},"billing_address":{"type":["integer","null"],"description":"The identifier of the billing address."},"checkout_provider":{"type":["integer","null"],"description":"The identifier of the checkout provider used."},"amount":{"type":"string","format":"decimal","description":"Total order amount including shipping, before discounts."},"discount_amount":{"type":"string","format":"decimal","description":"Total discount applied to the order."},"shipping_amount":{"type":"string","format":"decimal","description":"Shipping charge applied to the order."},"shipping_tax_rate":{"type":["string","null"],"format":"decimal","description":"Tax rate applied to the shipping charge."},"refund_amount":{"type":"string","format":"decimal","description":"Total amount refunded."},"discount_refund_amount":{"type":"string","format":"decimal","description":"Discount portion of the refunded amount."},"shipping_refund_amount":{"type":"string","format":"decimal","description":"Shipping portion of the refunded amount."},"invoice_number":{"type":["string","null"],"maxLength":32,"description":"Invoice number, set when the invoice has been issued."},"invoice_date":{"type":["string","null"],"format":"date-time","description":"Date and time the invoice was issued."},"e_archive_url":{"type":["string","null"],"format":"uri","maxLength":1024,"description":"URL of the e-archive invoice document."},"tracking_number":{"type":["string","null"],"maxLength":256,"description":"Carrier tracking number."},"defined_tracking_url":{"type":["string","null"],"format":"uri","maxLength":512,"description":"An explicitly set tracking URL, used in preference to the carrier-derived tracking URL."},"shipping_company":{"oneOf":[{"$ref":"#/components/schemas/OrderShippingCompany"},{"type":"null"}],"description":"The carrier used to ship the order. `null` if not yet assigned."},"shipping_tracking_url":{"type":["string","null"],"format":"uri","maxLength":500,"description":"The full tracking URL for the shipment."},"remote_addr":{"type":["string","null"],"description":"The IP address of the customer's device at the time of ordering."},"has_gift_box":{"type":["boolean","null"],"description":"Whether the order includes a gift box."},"gift_box_note":{"type":["string","null"],"maxLength":160,"description":"The personal message included with the gift box."},"client_type":{"allOf":[{"$ref":"#/components/schemas/OrderClientType"}],"readOnly":true,"description":"The client channel through which the order was placed. Read-only; set by the server at checkout."},"language_code":{"type":["string","null"],"maxLength":256,"description":"The language code active during the customer's session at the time of ordering."},"notes":{"type":["string","null"],"maxLength":320,"description":"Delivery instructions or other notes from the customer."},"delivery_range":{"type":["object","null"],"description":"The requested delivery window expressed as a date-time range.","properties":{"lower":{"type":["string","null"],"format":"date-time"},"upper":{"type":["string","null"],"format":"date-time"}}},"extra_field":{"type":["object","null"],"description":"Unstructured JSON data attached to the order (e.g. campaign rewards, staff info for in-store orders)."},"is_payable":{"type":"boolean","readOnly":true,"description":"Computed field. `true` if the order uses a pay-later payment option and all eligible trade-in items are in a payment-waiting status."},"created_date":{"type":"string","format":"date-time","readOnly":true,"description":"The date and time the order was created."},"modified_date":{"type":"string","format":"date-time","readOnly":true,"description":"The date and time the order was last modified."}}},"OrderClientType":{"type":"string","description":"The type of client (channel) through which the order was placed.","enum":["default","android","ios","instore","b2b"]},"ValidationError":{"type":"object","description":"Returned when the request contains invalid or missing data. Errors are grouped by the field they apply to: each key is the name of a field from the request and its value is a list of one or more messages describing what is wrong with that field. Messages that do not belong to any single field are grouped under `non_field_errors`.","properties":{"non_field_errors":{"type":"array","description":"Error messages that apply to the request as a whole rather than to a specific field.","items":{"type":"string"}}},"additionalProperties":{"type":"array","description":"The list of error messages for the field named by the key.","items":{"type":"string"}}},"Error":{"type":"object","description":"An error response.","properties":{"detail":{"type":"string","description":"A human-readable description of the error."}},"additionalProperties":true}},"responses":{"ValidationError":{"description":"The request contains invalid or missing data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"Unauthorized":{"description":"Authentication credentials were not provided or are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The authenticated user does not have administrator privileges.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/orders/":{"post":{"tags":["Orders"],"operationId":"createOrder","summary":"Create an order","description":"Validates the submitted order payload against the `Order` schema.\n\n**Note:** The creation handler (`perform_create`) is intentionally a no-op on this endpoint — the order record is not persisted to the database. This endpoint exists to satisfy the Omnitron push protocol; actual order persistence is handled by the checkout flow.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderRequest"}}}},"responses":{"201":{"description":"The validated order data. No record is written to the database.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://apidocs.akinon.com/commerce-openapis/admin/orders/create-an-order.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
