Menu

Returns API Routes

Admin users create a return when a customer returns an item to them.

Returns can also be created by customers through the storefront, and admins will be able to manage them and make refunds, if necessary. Refunds are made through the Payment API Routes

These API routes allow admin users to manage returns.

GET /admin/returns#

List Returns

Retrieve a list of returns. The returns can be filtered by fields such as id. The returns 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 a return's ID.
statusstring | string[]Optional
Filter by a return status.
created_atobjectOptional
Filter by the return's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by the return's update date. Accepts the filter operators.
with_deletedbooleanOptional
Whether to include deleted records in the result.
order_idstring | string[] | objectOptional
Filter by the return's order ID. Accepts the filter operators.

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.
returnsobject[]
The return's returns.

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

POST /admin/returns#

Create Return

Create a return. The return can later be requested or 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 the return belongs to.
location_idstringOptional
The ID of the location the items are returned to.
descriptionstringOptional
The return's description.
internal_notestringOptional
A note viewed only by admin users.
no_notificationbooleanOptional
Whether to send the customer a notification about the created return.
metadataobjectOptional
The return'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.
returnobject
The return's details.

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

GET /admin/returns/{id}#

Get a Return

Retrieve a return by its ID. You can expand the return'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 return'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.

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

POST /admin/returns/{id}#

Update a Return

Update a return's details.

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

Path parameters

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

location_idstringOptional
The ID of the location to return items to.
no_notificationbooleanOptional
Whether the customer should receive notifications about updates to the return.
metadataobjectOptional
The return'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/returns/{id}/cancel#

Cancel a return.

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

Path parameters

idstring
The return's ID.

Request body (application/json)

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

Request examples

Responses

200 OK

returnobject
The return's details.

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

POST /admin/returns/{id}/dismiss-items#

Add Damaged Items to Return

Add damaged items, whose quantity is to be dismissed, to a return. These items will have the action RECEIVE_DAMAGED_RETURN_ITEM.

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

Path parameters

idstring
The return'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 items details.

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/returns/{id}/dismiss-items/{action_id}#

Update Damaged Item of Return

Update a damaged item, whose quantity is to be dismissed, in the return by the ID of the item's RECEIVE_DAMAGED_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. return.

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

Path parameters

idstring
The return's ID.
action_idstring
The ID of the damaged item's RECEIVE_DAMAGED_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 body (application/json)

quantitynumberOptional
The item's quantity.
internal_notestringOptional
A note viewed only 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.
returnobject
The return's details.

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

DELETE /admin/returns/{id}/dismiss-items/{action_id}#

Remove Damaged Item from Return

Remove a damaged item, whose quantity is to be dismissed, in the return by the ID of the item's RECEIVE_DAMAGED_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. return.

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

Path parameters

idstring
The return's ID.
action_idstring
The ID of the damaged item's RECEIVE_DAMAGED_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.
idstring | string[] | objectOptional
Filter by a return's ID. Accepts the filter operators.
order_idstring | string[] | objectOptional
Filter by a return's order ID. Accepts the filter operators.
statusstring | string[] | objectOptional
Filter by a return's status.
updated_atobjectOptional
Filter by a return'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
The return's with deleted.
created_atobjectOptional
Filter by the return's creation date. Accepts the filter operators.

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/returns/{id}/receive#

Start Return Receival

Start a return receival process to be later confirmed using the /admin/returns/:id/receive/confirm API route.

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

Path parameters

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

internal_notestringOptional
A note viewed only by admin users.
descriptionstringOptional
The return's description.
metadataobjectOptional
The return'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.
returnobject
The return's details.

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

DELETE /admin/returns/{id}/receive#

Cancel Return Receival

Cancel the receival process previously started, and hasn't been confirmed, of a return.

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

Path parameters

idstring
The return's ID.

Request examples

Responses

200 OK

idstring
The return's ID.
objectstring
The name of the returned object.

Default: "return"

deletedboolean
Whether the return was deleted.

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

POST /admin/returns/{id}/receive-items#

Add Received Items to Return

Add received items in a return. These items will have the action RECEIVE_RETURN_ITEM.

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

Path parameters

idstring
The return'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 items details.

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/returns/{id}/receive-items/{action_id}#

Update a Received Item in a Return

Update a received item in the return by the ID of the item's RECEIVE_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. return.

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

Path parameters

idstring
The return's ID.
action_idstring
The ID of the received item's RECEIVE_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 body (application/json)

quantitynumberOptional
The item's quantity.
internal_notestringOptional
A note viewed only 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.
returnobject
The return's details.

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

DELETE /admin/returns/{id}/receive-items/{action_id}#

Remove a Received Item from Return

Remove a received item in the return by the ID of the item's RECEIVE_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. return.

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

Path parameters

idstring
The return's ID.
action_idstring
The ID of the received item's RECEIVE_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.
idstring | string[] | objectOptional
Filter by a return's ID. Accepts the filter operators.
order_idstring | string[] | objectOptional
Filter by a return's order ID. Accepts the filter operators.
statusstring | string[] | objectOptional
Filter by a return's status.
updated_atobjectOptional
Filter by a return'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
The return's with deleted.
created_atobjectOptional
Filter by the return's creation date. Accepts the filter operators.

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/returns/{id}/receive/confirm#

Confirm Return Receival

Confirm that a return has been received. This updates the quantity of the items received, if not damaged, and reflects the changes on the order.

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

Path parameters

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

no_notificationbooleanOptional
Whether to send the customer a notification about the confirmation.

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.

Emitted events

  • order.return_received: Emitted when a return is marked as received.
  • inventory-level.updated: Emitted when inventory levels are updated. This includes adjustments to the stocked or reserved quantity, such as during order fulfillment.

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

Confirm Return Request

Confirm a requested return. The changes are applied on the inventory quantity and the order only after the return has been confirmed as received using the /admin/returns/:id/received/confirm.

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

Path parameters

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

no_notificationbooleanOptional
Whether to send the customer a notification about the confirmation.

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.

Emitted events

  • order.return_requested: Emitted when a return request is confirmed.

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

Cancel Return Request

Cancel a requested return.

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

Path parameters

idstring
The return's ID.

Request examples

Responses

200 OK

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

Default: "return"

deletedboolean
Whether the return was deleted.

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

POST /admin/returns/{id}/request-items#

Add Requested Items to Return

Add items that are requested to be returned. These items will have the action RETURN_ITEM.

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

Path parameters

idstring
The return'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[]
The items' details.

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/returns/{id}/request-items/{action_id}#

Update Requested Item in Return

Update a requested item to be returned by 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. return.

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

Path parameters

idstring
The return's ID.
action_idstring
The ID of the 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 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 claim'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/returns/{id}/request-items/{action_id}#

Remove Item from Return

Remove a requested item to be returned by 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. return.

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

Path parameters

idstring
The return's ID.
action_idstring
The ID of the 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.
idstring | string[] | objectOptional
Filter by a return's ID. Accepts the filter operators.
order_idstring | string[] | objectOptional
Filter by a return's order ID. Accepts the filter operators.
statusstring | string[] | objectOptional
Filter by a return's status.
updated_atobjectOptional
Filter by a return'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
The return's with deleted.
created_atobjectOptional
Filter by the return's creation date. Accepts the filter operators.

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/returns/{id}/shipping-method#

Add a Shipping Method to a Return

Add a shipping method to a return. 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 return'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 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/returns/{id}/shipping-method/{action_id}#

Update a Shipping Method of a Return

Update a shipping method of the return by the ID of the item's SHIPPING_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 return'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
Set a custom price for the shipping method.
internal_notestringOptional
A note viewed only by admin users.
metadataobjectOptional
The return'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/returns/{id}/shipping-method/{action_id}#

Remove Shipping Method from Return

Remove a shipping method of the return by the ID of the item's SHIPPING_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 return'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.
idstring | string[] | objectOptional
Filter by a return's ID. Accepts the filter operators.
order_idstring | string[] | objectOptional
Filter by a return's order ID. Accepts the filter operators.
statusstring | string[] | objectOptional
Filter by a return's status.
updated_atobjectOptional
Filter by a return'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
The return's with deleted.
created_atobjectOptional
Filter by the return's creation date. Accepts the filter operators.

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.

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