Menu

Order Edits API Routes

An order edit is a change to an order's details, such as items, shipping methods, and more.

Changes made by an order edit are only applied on the order once they're confirmed.

The order's previous version is retained due to versioning.

These API routes allow admin users to make edits to an order and manage those edits.

POST /admin/order-edits#

Create Order Edit

Create an order edit.

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

Request body (application/json)

order_idstring
The ID of the order this edit is for.
descriptionstringOptional
The order edit's description.
internal_notestringOptional
A note viewed only by admin users.
metadataobjectOptional
The order edit's metadata, can hold custom key-value pairs. Learn more in the Manage Metadata section.

Request examples

Responses

200 OK

order_changeobject
The order change's details.

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

DELETE /admin/order-edits/{id}#

Cancel Order Edit

Cancel a requested order edit.

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

Path parameters

idstring
The ID of the order that is being edited.

Request examples

Responses

200 OK

idstring
The order edit's ID.
objectstring
The name of the deleted object.

Default: "order-edit"

deletedboolean
Whether the order edit was deleted.

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

Emitted events

  • order-edit.canceled: Emitted when an order edit request is canceled.

POST /admin/order-edits/{id}/confirm#

Confirm Order Edit

Confirm an order edit request and apply the changes on the order.

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

Path parameters

idstring
The ID of the order that is being edited.

Request examples

Responses

200 OK

order_previewobject
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.

Emitted events

  • order-edit.confirmed: Emitted when an order edit request is confirmed.
  • reservation-item.created: Emitted when reservations are created.
  • reservation-item.deleted: Emitted when reservations are deleted.

POST /admin/order-edits/{id}/items#

Add Items to Order Edit

Add new items to an order edit. These items will have the action ITEM_ADD.

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

Path parameters

idstring
The ID of the order that is being edited.

Request body (application/json)

itemsobject[]Optional
The details of items to be edited.

Request examples

Responses

200 OK

order_previewobject
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.

POST /admin/order-edits/{id}/items/item/{item_id}#

Update Order Item Quantity of Order Edit

Update an existing order item's quantity of an order edit. You can also use this API route to remove an item from an order by setting its quantity to 0.

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

Path parameters

idstring
The ID of the order that is being edited.
item_idstring
The order edit's item id.

Request body (application/json)

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

Request examples

Responses

200 OK

order_previewobject
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.

POST /admin/order-edits/{id}/items/{action_id}#

Update an Item in an Order Edit

Update an added item in the 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 ID of the order that is being edited.
action_idstring
The ID of the new item's ITEM_ADD action.

Request body (application/json)

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

Request examples

Responses

200 OK

order_previewobject
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.

DELETE /admin/order-edits/{id}/items/{action_id}#

Remove Item from Order Edit

Remove an added item in the 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 ID of the order that is being edited.
action_idstring
The ID of the new item's ITEM_ADD action.

Request examples

Responses

200 OK

order_previewobject
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.

POST /admin/order-edits/{id}/request#

Request Order Edit

Change the status of an active order edit to requested.

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

Path parameters

idstring
The ID of the order that is being edited.

Request body (application/json)

no_notificationbooleanOptional
Whether to send notifications to the customer regarding the order edit's updates.

Request examples

Responses

200 OK

order_previewobject
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.

Emitted events

  • order-edit.requested: Emitted when an order edit is requested.

POST /admin/order-edits/{id}/shipping-method#

Add Shipping Method to Order Edit

Add a shipping method to an exchange. The shipping method will have a SHIPPING_ADD action.

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

Path parameters

idstring
The ID of the order that is being edited.

Request body (application/json)

shipping_option_idstring
The ID of the associated shipping option.
custom_amountnumberOptional
Set a custom price for the shipping method.
descriptionstringOptional
The shipping method's description.
internal_notestringOptional
A note viewed only by admin users.
metadataobjectOptional
The shipping method's metadata, can hold custom key-value pairs. Learn more in the Manage Metadata section.

Request examples

Responses

200 OK

order_previewobject
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.

POST /admin/order-edits/{id}/shipping-method/{action_id}#

Update Shipping Method of an Order Edit

Update a shipping method in the order edit by 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 ID of the order that is being edited.
action_idstring
The ID of the shipping method's SHIPPING_ADD action.

Request body (application/json)

custom_amountnumberOptional
Set a custom price for the shipping method.
internal_notestringOptional
A note viewed only by admin users.
metadataobjectOptional
The order edit's metadata, can hold custom key-value pairs. Learn more in the Manage Metadata section.

Request examples

Responses

200 OK

order_previewobject
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.

DELETE /admin/order-edits/{id}/shipping-method/{action_id}#

Remove Shipping Method from Order Edit

Remove a shipping method in the order edit by 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 ID of the order that is being edited.
action_idstring
The ID of the shipping method's SHIPPING_ADD action.

Request examples

Responses

200 OK

order_previewobject
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.

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