Menu

Orders API Routes

An order is a purchase made by a customer through a storefront.

Orders can also originally be created as draft orders.

These API routes allow admin users to view and manage orders.

GET /admin/orders#

List Orders

Retrieve a list of orders. The orders can be filtered by fields such as id. The 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[]Optional
Filter by an order ID.
statusstring | string[]Optional
Filter by the order's status.
$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 sales channel IDs to retrieve the orders associated with them.
region_idstring | string[]Optional
Filter by region IDs to retrieve their associated orders.
qstringOptional
Search term to filter the order's searchable properties.
created_atobjectOptional
Filter by the order's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by the order's update date. Accepts the filter operators.
customer_idstring | string[]Optional
The 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 returned.
offsetnumber
The number of items skipped before the returned items.
countnumber
The total count of items.
ordersobject[]
The list of orders.

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

POST /admin/orders/export#

Export Orders

Start an order export process to retrieve a CSV of exported orders.

You'll receive in the response the transaction ID of the workflow generating the CSV file. To check the status of the execution, send a GET request to /admin/workflows-executions/export-orders/:transaction-id.

Once the execution finishes successfully, a notification is created for the export. You can retrieve the notifications using the /admin/notification API route to retrieve the file's download URL.

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

Query parameters

idstring | string[]Optional
The ID of the order to export.
sales_channel_idstring[]Optional
The IDs of the sales channels to export their orders.
region_idstring | string[]Optional
The ID of a region to export orders in it.
customer_idstring | string[]Optional
The ID of a customer to export their orders.
qstringOptional
A search query to filter exported orders by.
created_atobjectOptional
Filter by an order's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by an order's update date. Accepts the filter operators.
limitnumberOptional
Limit the number of items returned in the list.
offsetnumberOptional
The number of items to skip when retrieving a 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 -.
with_deletedbooleanOptional
Whether to include deleted orders in the export.
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.
status"canceled" | "completed" | "pending" | "draft" | "archived" | "requires_action" | ("canceled")[] | ("completed")[] | ("pending")[] | ("draft")[] | ("archived")[] | ("requires_action")[] | objectOptional
The status of the orders to export.
$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.

Request examples

Responses

202 OK

transaction_idstring
The ID of the workflow execution's transaction. Use it to check the status of the export by sending a GET request to /admin/workflows-executions/export-orders/:transaction-id

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

GET /admin/orders/{id}#

Get an Order

Retrieve an order by its ID. You can expand the order's relations or select the fields that should be returned.

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

Path parameters

idstring
The 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.
versionnumberOptional
The order's version.

Request examples

Responses

200 OK

orderobject
The order's details.

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

POST /admin/orders/{id}#

Update Order

Update an order's details.

Updating the order's shipping or billing address doesn't recalculate the order's taxes or totals; the existing tax lines are preserved as-is. You also can't change the address's country_code.

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

Path parameters

idstring
The order's ID.

Query parameters

versionnumberOptional
Retrieve a specific version of the order. If no version is provided, the latest version will be retrieved.
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 order's email.
shipping_addressobjectOptional
The address's details.
billing_addressobjectOptional
The address's details.
metadataobjectOptional
The order's metadata, can hold custom key-value pairs. Learn more in the Manage Metadata section.
localestringOptional
The order's locale in BCP 47 format.
Example: en-US

Request examples

Responses

200 OK

orderobject
The 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.

POST /admin/orders/{id}/archive#

Archive an Order

Change the status of an order to archived.

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

Path parameters

idstring
The 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.
versionnumberOptional
The order's version.

Request examples

Responses

200 OK

orderobject
The order's details.

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

Emitted events

  • order.archived: Emitted when an order is archived.

POST /admin/orders/{id}/cancel#

Cancel Order

Cancel an order. The cancelation fails if:

  • The order has captured payments.

  • The order has refund payments.

  • The order has fulfillments that aren't canceled.

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

Path parameters

idstring
The 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.
versionnumberOptional
The order's version.

Request examples

Responses

200 OK

orderobject
The order's details.

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

Emitted events

  • order.canceled: Emitted when an order is canceld.
  • reservation-item.deleted: Emitted when reservations are deleted.

GET /admin/orders/{id}/changes#

List Changes on an Order

Retrieve a list of changes made on an order, including returns, exchanges, etc...

The changes can be filtered by fields like created_at. The changes can also be paginated.

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

Path parameters

idstring
The 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.
created_atobjectOptional
Filter by the order change's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by the order change's update date. Accepts the filter operators.
deleted_atobjectOptional
Filter by the order change's deletion date. Accepts the filter operators.
idstring | string[] | objectOptional
Filter by an order change ID.
statusstring | string[] | objectOptional
Filter by the order change's status.
change_typestring | string[] | objectOptional
Filter by the order change's type.
$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.

Request examples

Responses

200 OK

order_changesobject[]
An order's changes.

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

POST /admin/orders/{id}/complete#

Complete Order

Mark an order as completed.

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

Path parameters

idstring
The 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.
versionnumberOptional
The order's version.

Request body (application/json)

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

orderobject
The order's details.

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

Emitted events

  • order.completed: Emitted when orders are completed.

POST /admin/orders/{id}/credit-lines#

Create Credit Line for Order

Create a credit line for an order.

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

Path parameters

idstring
The 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.
versionnumberOptional
The order's version.

Request body (application/json)

amountnumber
The amount of the credit line.
Example: 100
referencestring
The name of the table that the credit line is referencing.
Example: order
reference_idstring
The ID of a record in the table that the credit line is referencing.
Example: order_123
metadataobjectOptional
The credit line's metadata, can hold custom key-value pairs. Learn more in the Manage Metadata section.

Request examples

Responses

200 OK

orderobject
The order's details.

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

POST /admin/orders/{id}/fulfillments#

Create an Order Fulfillment

Create a fulfillment for an order. The creation fails if the order is canceled.

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

Path parameters

idstring
The 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.
versionnumberOptional
The order's version.

Request body (application/json)

itemsobject[]
The items to fulfill.
location_idstring
The ID of the location to fulfill the items from. If not provided, the location associated with the shipping option of the order's shipping method is used.
no_notificationbooleanOptional
Whether to send the customer a notification about the created fulfillment.
delivery_addressobjectOptional
The address to deliver the items to.
metadataobject
The order's metadata. Can hold custom key-value pairs.
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

orderobject
The order's details.

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

Emitted events

  • order.fulfillment_created: Emitted when a fulfillment is created for an order.
  • inventory-level.updated: Emitted when inventory levels are updated. This includes adjustments to the stocked or reserved quantity, such as during order fulfillment.
  • reservation-item.updated: Emitted when reservations are updated.
  • reservation-item.deleted: Emitted when reservations are deleted.

POST /admin/orders/{id}/fulfillments/{fulfillment_id}/cancel#

Cancel Fulfillment

Cancel an order's fulfillment. The fulfillment can't be canceled if it's shipped.

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

Path parameters

idstring
The order's ID.
fulfillment_idstring
The order's fulfillment id.

Request body (application/json)

no_notificationbooleanOptional
Whether the customer should receive a notification about this change.
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

orderobject
The order's details.

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

Emitted events

  • order.fulfillment_canceled: Emitted when an order's fulfillment is canceled.
  • inventory-level.updated: Emitted when inventory levels are updated. This includes adjustments to the stocked or reserved quantity, such as during order fulfillment.
  • reservation-item.created: Emitted when reservations are created.
  • reservation-item.updated: Emitted when reservations are updated.

POST /admin/orders/{id}/fulfillments/{fulfillment_id}/mark-as-delivered#

Mark a Fulfillment as Delivered.

Mark an order's fulfillment as delivered.

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

Path parameters

idstring
The order's ID.
fulfillment_idstring
The fulfillment'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.
versionnumberOptional
The order's version.

Request body (application/json)

no_notificationbooleanOptional
Whether to send a notification to the customer about the fulfillment being marked as delivered.

Request examples

Responses

200 OK

orderobject
The order's details.

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

Emitted events

  • delivery.created: Emitted when a fulfillment is marked as delivered.

POST /admin/orders/{id}/fulfillments/{fulfillment_id}/shipments#

Create Shipment for an Order's Fulfillment

Create a shipment for an order's fulfillment.

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

Path parameters

idstring
The order's ID.
fulfillment_idstring
The fulfillment'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.
versionnumberOptional
The order's version.

Request body (application/json)

itemsobject[]
The items to create shipment for.
labelsobject[]Optional
The labels to create for the shipment.
no_notificationbooleanOptional
Whether to send the customer a notification about the created shipment.
metadataobject
The shipment's metadata. Can hold custom key-value pairs.
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

orderobject
The order's details.

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

Emitted events

  • shipment.created: Emitted when a shipment is created for an order.

GET /admin/orders/{id}/line-items#

List Line Items

Retrieve a list of line items in a order. The line items can be filtered by fields like FILTER FIELDS. The line items can also be paginated.

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

Path parameters

idstring
The 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.
idstring | string[]Optional
The order's ID.
item_idstring | string[]Optional
The order's item id.
versionnumber | number[]Optional
The order's version.

Request examples

Responses

200 OK

order_itemsobject[]
The order's order items.

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

POST /admin/orders/{id}/payment-sessions/authorize#

Authorize Payment Session

Authorize a payment session for an order. This is useful for orders created from draft orders.

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

Path parameters

idstring
The order's ID.

Request body (application/json)

payment_session_idstring
The payment session's ID.

Request examples

Responses

200 OK

orderobject
The order's details.
is_authorizedboolean
Whether the payment session was successfully authorized.

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

GET /admin/orders/{id}/preview#

Get Preview

Retrieve a preview of an order using its associated change, such as an edit.

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

Path parameters

idstring
The order's ID.

Request examples

Responses

200 OK

orderobject
A preview of an order if a change, such as exchange, return, edit, or claim is applied on it.

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

GET /admin/orders/{id}/shipping-options#

List Shipping Options for Order

Retrieve a list of shipping options that can be used for outbound shipping in an order. This is especially useful when adding outbound shipping to order exchanges or claims.

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

Path parameters

idstring
The order's ID.

Request examples

Responses

200 OK

shipping_optionsobject[]
The list of shipping options.

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

POST /admin/orders/{id}/transfer#

Request Order Transfer

Request an order to be transfered to another customer. The transfer is confirmed by sending a request to the Accept Order Transfer Store API route.

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

Path parameters

idstring
The 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.
versionnumberOptional
The order's version.

Request body (application/json)

customer_idstring
The ID of the customer to transfer the order to.
descriptionstringOptional
The description of the order transfer, which can be shown to the customer receiving the order transfer request.
internal_notestringOptional
An internal note viewable only by admin users.
update_order_emailbooleanOptional
Whether to update the order's email to the email of the customer the order is being transferred to. By default, the order's email will not be updated.

Default: false

Request examples

Responses

200 OK

orderobject
The order's details.

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

Emitted events

  • order.transfer_requested: Emitted when an order is requested to be transferred to another customer.

POST /admin/orders/{id}/transfer/cancel#

Cancel Transfer Request

Cancel a request to transfer an order to another customer.

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

Path parameters

idstring
The 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.
versionnumberOptional
The order's version.

Request examples

Responses

200 OK

orderobject
The order's details.

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

POST /admin/orders/{id}/transfer/guest#

Transfer Order to Guest Customer

Transfer an order to a guest customer. This is useful when the order email was incorrectly entered and you want to set it to a guest customer. The order will be transferred to a new guest customer with the provided email. For transferring orders to registered customer, check out the Request Order Transfer API route instead.

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

Path parameters

idstring
The order's ID.

Query parameters

versionnumberOptional
Retrieve a specific version of the order. If no version is provided, the latest version will be retrieved.
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)

emailstring
The email to which the order will be transferred.
internal_notestringOptional
The internal note for the order transfer.
descriptionstringOptional
Details of the order transfer to a guest.

Request examples

Responses

200 OK

orderobject
The order's details.

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