Create order
Background processing
When you create an order, this happens asynchronously. You can use
Polling or Webhooks
for status updates.
In this endpoint, a new product variant is created implicitly for every order item. There is always a
reference on the requested data in the variant object.
You can also use all the design features from the design variant endpoint within the variant object
within an order item. See Design Variant.
Therefore, you will already receive the new order id in the header for later reference.
The current state of the asynchronous process is represented due the following states:
| State | Meaning |
|---|---|
draft | The initial state of a new order. |
checking | Order is processed automatically in background. For example images will be generated or downloaded or the variant will be designed. |
failed | Something went wrong during the checking process. The reason can be found in the failure_message attribute. For example, an image could not be downloaded. |
preparing | The order is processed manually by the producer. For example, digitalization tasks are in process. |
prepared | The manual process is finished and the production process is running. |
cancelled | The order is cancelled manually. |
completed | The production process is completed. The order will be delivered to the customer. |
The response is a 202 Accepted without a body: the X-Identifier header is the new generated order id
for later reference, the Location header points to the background job.
See the Further post order examples among the request examples: Create order with designing a variant with media ids and Create order with own shipping documents.
AuthorizationbearerAuth
Authorization
bearerAuth API token as bearer token — you receive a test and a live token, there is no switch between them. See Setup → Authentication and Setup → Test mode.
In: header
Header Parameters
The API only responds with JSON — this header is mandatory on every request (see Setup → Headers).
"application/json"Value in
- "application/json"
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
The attributes to create an order. The order is processed asynchronously — see Create order.
Response Body
application/json
application/json
curl -X POST "https://example.com/orders" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "customer": { "email": "[email protected]" }, "items": [ { "variant": { "type": "basic", "id": 25 }, "quantity": 3 } ], "shipping_address": { "first_name": "Max", "last_name": "Mustermann", "street1": "Am Wassermann 361", "zip": "508291", "city": "Köln", "country_code": "DE", "phone": "+49 123 456 789", "email": "[email protected]" }, "shipments": [ { "shipping_method": { "handle": "shipping-method-handle" } } ], "payments": [ { "payment_method": { "handle": "payment-method-handle" } } ] }'List orders GET
An order is created when the checkout process is complete. > See: [Expanding Objects](/docs/checkout/2022-02-01/basic/expanding-objects) Returns a collection of created orders. **Filtering** You can filter your results as follows — every `filter[...]` query parameter is documented below (ids can be combined with a comma, e.g. `/orders?filter[id]=1,2,3`). > See: [Pagination](/docs/checkout/2022-02-01/basic/pagination), [Filtering](/docs/checkout/2022-02-01/basic/filtering) **Expanding objects** Related objects can be expanded inline with the `expand` query parameter — all allowed values are listed on the parameter. See [Expanding Objects](/docs/checkout/2022-02-01/basic/expanding-objects).
Get order GET
Returns the order with `id` = **x**. **Expanding objects** Related objects can be expanded inline with the `expand` query parameter — all allowed values are listed on the parameter. See [Expanding Objects](/docs/checkout/2022-02-01/basic/expanding-objects).