Menu

Exchanges API Routes

An exchange is the replacement of an item that the customer ordered with another.

These API routes allow admin users to create and manage exchanges.

GET /admin/exchanges#

List Exchanges

Retrieve a list of exchanges. The exchanges can be filtered by fields such as id. The exchanges 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 -.
deleted_atobjectOptional
Filter by an exchange's deletion date. Accepts the filter operators.
idstring | string[]Optional
Filter by an exchange ID.
order_idstring | string[]Optional
Filter by an exchange's order ID.
statusstring | string[]Optional
Filter by an exchange's status.
created_atobjectOptional
Filter by the exchange's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by the exchange's update date. Accepts the filter operators.
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 retrieving the returned items.
countnumber
The total number of items.
exchangesobject[]
The exchange's exchanges.

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

POST /admin/exchanges#

Create Exchange

Create an exchange request. Its changes aren't applied on the order until the exchange is confirmed.

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)

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

Request examples

Responses

200 OK

orderobject
The order change's order.
exchangeobject
The exchange's details.

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

GET /admin/exchanges/{id}#

Get an Exchange

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

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

Path parameters

idstring
The exchange'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

exchangeobject
The exchange's details.

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

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

Cancel an Exchange

Cancel an exchange and its associated return.

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

Path parameters

idstring
The exchange's ID.

Request body (application/json)

no_notificationbooleanOptional
Whether to send a notification to the customer about the exchange's cancelation.

Request examples

Responses

200 OK

exchangeobject
The exchange's details.

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

Emitted events

  • reservation-item.deleted: Emitted when reservations are deleted.

POST /admin/exchanges/{id}/inbound/items#

Add Inbound Items to an Exchange

Add inbound (or return) items to an exchange. These inbound items will have the action RETURN_ITEM.

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

Path parameters

idstring
The exchange'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)

itemsobject[]Optional
The details of the inbound (return) items.
location_idstringOptional
The ID of the location to which outbound items are sent from.

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.
returnobject
The return's details.

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

POST /admin/exchanges/{id}/inbound/items/{action_id}#

Update an Inbount Item of an Exchange

Update an inbound (or return) item from an exchange using the ID of the item's RETURN_ITEM 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 exchange's ID.
action_idstring
The ID of the return item's RETURN_ITEM action.

Request body (application/json)

quantitynumberOptional
The item's quantity.
internal_notestringOptional
A note viewed only by admin users.
reason_idstringOptional
The ID of the associated return reason.
metadataobjectOptional
The exchange'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.
returnobject
The return's details.

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

DELETE /admin/exchanges/{id}/inbound/items/{action_id}#

Remove Inbound Item from Exchange

Remove an inbound (or return) item from an exchange using the ID of the item's RETURN_ITEM 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 exchange's ID.
action_idstring
The ID of the return item's RETURN_ITEM action.

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

order_previewobject
A preview of an order if a change, such as exchange, return, edit, or claim is applied on it.
returnobject
The return's details.

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

POST /admin/exchanges/{id}/inbound/shipping-method#

Add an Inbound Shipping Method to an Exchange

Add an inbound (or return) shipping method to an exchange. The inbound shipping method will have a SHIPPING_ADD action.

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

Path parameters

idstring
The exchange's ID.

Request body (application/json)

shipping_option_idstring
The ID of the associated shipping option.
custom_amountnumberOptional
Set the price of the shipping method.
descriptionstringOptional
The shipping method's description.
internal_notestringOptional
A note viewed only by admin users.
metadataobjectOptional
The exchange'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.
returnobject
The return's details.

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

POST /admin/exchanges/{id}/inbound/shipping-method/{action_id}#

Update Inbound Shipping Method of an Exchange

Update the shipping method for returning items in the exchange 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 exchange's ID.
action_idstring
The ID of the shipping method's SHIPPING_ADD action.

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)

custom_amountnumberOptional
The shipping method's custom amount.
internal_notestringOptional
A note viewed by admin users only.
metadataobjectOptional
The exchange'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.
exchangeobject
The exchange's details.

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

DELETE /admin/exchanges/{id}/inbound/shipping-method/{action_id}#

Remove Inbound Shipping Method from Exchange

Remove the shipping method for returning items in the exchange 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 exchange's ID.
action_idstring
The ID of the shipping method's SHIPPING_ADD action.

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

order_previewobject
A preview of an order if a change, such as exchange, return, edit, or claim is applied on it.
returnobject
The return's details.

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

POST /admin/exchanges/{id}/outbound/items#

Add Outbound Items to Exchange

Add outbound (or new) items to an exchange. These outbound items will have the action ITEM_ADD.

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

Path parameters

idstring
The exchange'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)

itemsobject[]Optional
The details of outbound items.

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.
exchangeobject
The exchange's details.

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

POST /admin/exchanges/{id}/outbound/items/{action_id}#

Update Outbound Item of an Exchange

Update an outbound (or new) item from an exchange using 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 exchange's ID.
action_idstring
The ID of the new exchange item's ITEM_ADD action.

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)

quantitynumberOptional
The item's quantity.
internal_notestringOptional
A note only viewed by admin users.

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.
exchangeobject
The exchange's details.

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

DELETE /admin/exchanges/{id}/outbound/items/{action_id}#

Remove Outbound Item from Exchange

Remove an outbound (or new) item from an exchange using 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 exchange's ID.
action_idstring
The ID of the new exchange item's ITEM_ADD action.

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

order_previewobject
A preview of an order if a change, such as exchange, return, edit, or claim is applied on it.
exchangeobject
The exchange's details.

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

POST /admin/exchanges/{id}/outbound/shipping-method#

Add Outbound Shipping Method to Exchange

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

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

Path parameters

idstring
The exchange'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)

shipping_option_idstring
The ID of the associated shipping option.
custom_amountnumberOptional
Set a custom amount for the shipping method.
descriptionstringOptional
The shipping method's description.
internal_notestringOptional
A note viewed by admin users only.
metadataobjectOptional
The exchange'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.
exchangeobject
The exchange's details.

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

POST /admin/exchanges/{id}/outbound/shipping-method/{action_id}#

Update Outbound Shipping Method of Exchange

Update the shipping method for delivering outbound items in the exchange 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 exchange's ID.
action_idstring
The ID of the shipping method's SHIPPING_ADD action.

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)

custom_amountnumberOptional
The shipping method's custom amount.
internal_notestringOptional
A note viewed by admin users only.
metadataobjectOptional
The exchange'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.
exchangeobject
The exchange's details.

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

DELETE /admin/exchanges/{id}/outbound/shipping-method/{action_id}#

Remove Outbound Shipping Method from Exchange

Remove the shipping method for delivering outbound items in the exchange 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 exchange's ID.
action_idstring
The ID of the shipping method's SHIPPING_ADD action.

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

order_previewobject
A preview of an order if a change, such as exchange, return, edit, or claim is applied on it.
exchangeobject
The exchange's details.

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

POST /admin/exchanges/{id}/request#

Confirm an Exchange

Confirm an exchange request, applying its changes on the associated order.

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

Path parameters

idstring
The exchange'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

returnobject
The return's details.
order_previewobject
A preview of an order if a change, such as exchange, return, edit, or claim is applied on it.
exchangeobject
The exchange's details.

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

Emitted events

  • order.exchange_created: Emitted when an exchange is created for an order.
  • reservation-item.created: Emitted when reservations are created.

DELETE /admin/exchanges/{id}/request#

Cancel Exchange Request

Cancel a requested exchange.

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

Path parameters

idstring
The exchange's ID.

Request examples

Responses

200 OK

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

Default: "exchange"

deletedboolean
Whether the exchange was deleted.

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