Menu

Draft Orders API Routes

A draft order is an order created by the admin user. This is useful for orders created offline or from clients other than a storefront, such as a third-party integration.

These API routes allow admin users to create and manage draft orders.

GET /admin/draft-orders#

List Draft Orders

Retrieve a list of draft orders. The draft orders can be filtered by fields such as id. The draft orders can also be sorted or paginated.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.
offsetnumberOptional
The number of items to skip when retrieving a list.
limitnumberOptional
Limit the number of items returned in the list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
idstring | string[] | objectOptional
Filter by a draft order's ID. Accepts the filter operators.
$andobject[]Optional
Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
$orobject[]Optional
Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
sales_channel_idstring[]Optional
Filter by the associated sales channels to retrieve its draft orders.
region_idstring | string[]Optional
Filter by region IDs to retrieve their associated draft orders.
qstringOptional
Search term to filter the order's searchable properties.
created_atobjectOptional
Filter by the draft order's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by the draft order's update date. Accepts the filter operators.
customer_idstring | string[]Optional
The draft order's customer id.
with_deletedbooleanOptional
Whether to include deleted records in the result.

Request examples

Responses

200 OK

limitnumber
The maximum number of items retrieved.
offsetnumber
The number of items skipped before retrieving the returned items.
countnumber
The total count of items available.
draft_ordersobject[]
The list of draft orders.
estimate_countnumberOptional
The estimated count retrieved from the PostgreSQL query planner, which may be inaccurate.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/draft-orders#

Create Draft Order

Create a draft order. This creates an order with the is_draft_order property enabled. You can later convert the draft order to an order.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

status"completed"Optional
The draft order's status.
sales_channel_idstring
The ID of the associated sales channel.
emailstring
The email of the draft order's customer.
customer_idstring
The ID of the draft order's customer.
billing_addressstring | objectOptional
The draft order's billing address.
shipping_addressstring | objectOptional
The draft order's shipping address.
itemsobject[]Optional
The draft order's items.
region_idstring
The ID of the associated region.
promo_codesstring[]Optional
The promotion codes applied on the draft order.
currency_codestring
The draft order's currency code.
no_notification_orderbooleanOptional
Whether to send the customer notifications on order changes.
shipping_methodsobject[]
The draft order's shipping methods.
metadataobject
The draft order's metadata.
additional_dataobjectOptional
Pass additional custom data to the API route. This data is passed to the underlying workflow under the additional_data parameter.

Request examples

Responses

200 OK

draft_orderobject
The draft order's details.

400, 401, 404, 409, 422, 500: an error response is returned.

GET /admin/draft-orders/{id}#

Get a Draft Order

Retrieve a draft order by its ID. You can expand the draft order's relations or select the fields that should be returned using the query parameters.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The draft order's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request examples

Responses

200 OK

draft_orderobject
The draft order's details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/draft-orders/{id}#

Update a Draft Order

Update a draft order's details. This doesn't include updating the draft order's items, shipping methods, or promotions. To update those, you need to create an edit that you can later request or confirm.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The draft order's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request body (application/json)

emailstringOptional
The customer email associated with the draft order.
shipping_addressobjectOptional
The address's details.
billing_addressobjectOptional
The address's details.
metadataobjectOptional
The draft order's metadata, can hold custom key-value pairs. Learn more in the Manage Metadata section.
customer_idstringOptional
The ID of the customer associated with the draft order.
sales_channel_idstringOptional
The ID of the sales channel associated with the draft order.
localestringOptional
The draft order's locale.

Request examples

Responses

200 OK

draft_orderobject
The draft order's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • order.updated: Emitted when the details of an order or draft order is updated. This doesn't include updates made by an edit.

DELETE /admin/draft-orders/{id}#

Delete a Draft Order

Delete a draft order.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The draft order's ID.

Request examples

Responses

200 OK

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/draft-orders/{id}/convert-to-order#

Convert a Draft Order to an Order

Convert a draft order to an order. This will finalize the draft order and create a new order with the same details.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The draft order's ID.

Request body (application/json)

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request examples

Responses

200 OK

orderobject
The order's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • order.placed: Emitted when an order is placed, or when a draft order is converted to an order.
  • reservation-item.created: Emitted when reservations are created.

POST /admin/draft-orders/{id}/edit#

Create a Draft Order Edit

Create an edit on a draft order. This will allow you to make changes to the draft order's items, shipping methods, or promotions. Once you've made the necessar changes, you can later either request the edit (which requires a confirmation from the customer), or force-confirm the edit.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The draft order's ID.

Request examples

Responses

200 OK

400, 401, 404, 409, 422, 500: an error response is returned.

DELETE /admin/draft-orders/{id}/edit#

Cancel Edit on Draft Order

Cancel an unconfirmed edit on a draft order.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The draft order's ID.

Request examples

Responses

200 OK

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/draft-orders/{id}/edit/confirm#

Confirm an Edit on a Draft Order

Confirm an edit on a draft order. This will apply the changes made to the draft order.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The draft order's ID.

Request examples

Responses

200 OK

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/draft-orders/{id}/edit/items#

Add Item to Draft Order Edit

Add an item to a draft order edit.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The draft order's ID.

Request body (application/json)

itemsobject[]Optional
The items to add to the draft order.

Request examples

Responses

200 OK

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/draft-orders/{id}/edit/items/item/{item_id}#

Update Existing Item in Draft Order Edit

Update an existing item in a draft order edit.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The draft order's ID.
item_idstring
The item's ID.

Request body (application/json)

quantitynumber
The item's quantity.
unit_pricenumberOptional
The item's unit price.
compare_at_unit_pricenumberOptional
The original price of the item before a promotion or sale.
internal_notestringOptional
A note viewed only by admin users about the item.
metadataobjectOptional
Key-value pairs of custom data.

Request examples

Responses

200 OK

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/draft-orders/{id}/edit/items/{action_id}#

Update New Item in Draft Order Edit

Update a new item that was added to a draft order edit by the ID of the item's ITEM_ADD action.

Every item has an actions property, whose value is an array of actions. You can check the action's name using its action property, and use the value of the id property.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The draft order's ID.
action_idstring
The ID of the item's ITEM_ADD action.

Request body (application/json)

quantitynumber
The item's quantity.
unit_pricenumberOptional
The item's unit price.
compare_at_unit_pricenumberOptional
The original price of the item before a promotion or sale.
internal_notestringOptional
A note viewed only by admin users about the item.

Request examples

Responses

200 OK

400, 401, 404, 409, 422, 500: an error response is returned.

DELETE /admin/draft-orders/{id}/edit/items/{action_id}#

Remove Item from Draft Order Edit

Remove an order item from a draft order edit by the ID of the item's ITEM_ADD or ITEM_UPDATE action.

Every item has an actions property, whose value is an array of actions. You can check the action's name using its action property, and use the value of the id property.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The draft order's ID.
action_idstring
The ID of the order item's ITEM_ADD or ITEM_UPDATE action.

Request examples

Responses

200 OK

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/draft-orders/{id}/edit/promotions#

Add Promotions to Draft Order Edit

Add promotions to a draft order edit.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The draft order's ID.

Request body (application/json)

promo_codesstring[]
The list promotion codes to add to the draft order.

Request examples

Responses

200 OK

draft_order_previewobject
The draft order preview's details.

400, 401, 404, 409, 422, 500: an error response is returned.

DELETE /admin/draft-orders/{id}/edit/promotions#

Remove Promotions from Draft Order Edit

Remove specified promotions from a draft order edit.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The draft order's ID.

Request body (application/json)

promo_codesstring[]
The promotion codes to remove from the draft order.

Request examples

Responses

200 OK

draft_order_previewobject
The draft order preview's details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/draft-orders/{id}/edit/request#

Request Edit on Draft Order

Change the status of a draft order's edit to be requested. Later, the edit can be confirmed or canceled.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The draft order's ID.

Request examples

Responses

200 OK

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/draft-orders/{id}/edit/shipping-methods#

Add Shipping Method to Draft Order Edit

Add a shipping method to a draft order edit.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The draft order's ID.

Request body (application/json)

shipping_option_idstring
The ID of the shipping option that this method is created from.
custom_amountnumberOptional
A custom amount to be charged for this shipping method. If not provided, the shipping option's amount will be used.
descriptionstringOptional
The shipping method's description.
internal_notestringOptional
A note viewed only by admin users about the shipping method.
metadataobjectOptional
The shipping method's metadata, can hold custom key-value pairs. Learn more in the Manage Metadata section.

Request examples

Responses

200 OK

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/draft-orders/{id}/edit/shipping-methods/method/{method_id}#

Update Existing Shipping Method in Draft Order Edit

Update an existing shipping method in a draft order edit.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The draft order's ID.
method_idstring
The ID of the shipping method.

Request body (application/json)

shipping_option_idstringOptional
The ID of the associated shipping option.
custom_amountnumberOptional
The custom amount of the shipping method. If not provided, the shipping option's amount will be used.
internal_notestringOptional
A note viewed only by admin users about the shipping method.

Request examples

Responses

200 OK

400, 401, 404, 409, 422, 500: an error response is returned.

DELETE /admin/draft-orders/{id}/edit/shipping-methods/method/{method_id}#

Remove Shipping Method from Draft Order Edit

Remove an existing shipping method from a draft order edit.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The draft order's ID.
method_idstring
The shipping method's ID.

Request examples

Responses

200 OK

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/draft-orders/{id}/edit/shipping-methods/{action_id}#

Update New Shipping Method in Draft Order Edit

Update a new shipping method that was added to a draft order edit using the ID of the method's SHIPPING_ADD action.

Every shipping method has an actions property, whose value is an array of actions. You can check the action's name using its action property, and use the value of the id property.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The draft order's ID.
action_idstring
The ID of the shipping method's SHIPPING_ADD action.

Request body (application/json)

shipping_option_idstring
The ID of the associated shipping option.
custom_amountnumberOptional
The custom amount of the shipping method. If not provided, the shipping option's amount will be used.
descriptionstringOptional
The shipping method's description.
internal_notestringOptional
A note viewed only by admin users about the shipping method.
metadataobjectOptional
The shipping method's metadata, can hold custom key-value pairs. Learn more in the Manage Metadata section.

Request examples

Responses

200 OK

400, 401, 404, 409, 422, 500: an error response is returned.

DELETE /admin/draft-orders/{id}/edit/shipping-methods/{action_id}#

Remove New Shipping Method from Draft Order

Remove a shipping method that was added to a draft order edit using the ID of the method's SHIPPING_ADD action.

Every shipping method has an actions property, whose value is an array of actions. You can check the action's name using its action property, and use the value of the id property.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The draft order's ID.
action_idstring
The ID of the shipping method's SHIPPING_ADD action.

Request examples

Responses

200 OK

400, 401, 404, 409, 422, 500: an error response is returned.

Found a problem with this page?Report Issue
Edited Nov 14·Edit this page