Menu

Claims API Routes

An admin creates a claim for an order when a customer reports that an item is defective or incorrect.

Using these API routes, admin users manage order claims, their items, and more.

GET /admin/claims#

List Claims

Retrieve a list of claims. The claims can be filtered by fields such as id. The claims 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 the claim's deletion date. Accepts the filter operators.
idstring | string[]Optional
The claim's ID.
order_idstring | string[]Optional
The claim's order id.
statusstring | string[]Optional
Filter by the claim's status.
created_atobjectOptional
Filter by the claim's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by the claim's update date. 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.
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.
claimsobject[]
The list of claims.
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/claims#

Create a Claim

Create a claim. The claim is still in the request state, and the changes are only applied on the order once the claim 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.
idstring | string[]Optional
Filter by the claim's ID.
statusstring | string[]Optional
Filter by the claim's status.
created_atobjectOptional
Filter by a claim's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by a claim's update date. Accepts the filter operators.
deleted_atobjectOptional
Filter by a claim's deletion date. Accepts the filter operators.

Request body (application/json)

type"refund" | "replace"
The claim's type.
order_idstring
The ID of the order the claim is created for.
descriptionstringOptional
The claim's description.
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

orderobject
The order change's order.
claimobject
The claim's details.

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

GET /admin/claims/{id}#

Get a Claim

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

claimobject
The claim's details.

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

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

Cancel a Claim

Cancel a claim and its associated return.

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

Path parameters

idstring
The claim's ID.

Request body (application/json)

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

Request examples

Responses

200 OK

claimobject
The claim'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/claims/{id}/claim-items#

Add Claim Items to a Claim

Add order items to a claim as claim items. These claim items will have the action WRITE_OFF_ITEM.

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

Path parameters

idstring
The claim'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
Filter by the claim's ID.
statusstring | string[]Optional
Filter by the claim's status.
created_atobjectOptional
Filter by a claim's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by a claim's update date. Accepts the filter operators.
deleted_atobjectOptional
Filter by a claim's deletion date. Accepts the filter operators.

Request body (application/json)

itemsobject[]Optional
The item's 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.
claimobject
The claim's details.

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

POST /admin/claims/{id}/claim-items/{action_id}#

Update a Claim Item

Update an order item in a claim by the ID of the item's WRITE_OFF_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 claim's ID.
action_idstring
The ID of the order item's WRITE_OFF_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[]Optional
Filter by the claim's ID.
statusstring | string[]Optional
Filter by the claim's status.
created_atobjectOptional
Filter by a claim's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by a claim's update date. Accepts the filter operators.
deleted_atobjectOptional
Filter by a claim's deletion date. Accepts the filter operators.

Request body (application/json)

quantitynumberOptional
The item's quantity.
reason_idstringOptional
The ID of the return reason associated with the item.
internal_notestringOptional
A note that's 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.
claimobject
The claim's details.

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

DELETE /admin/claims/{id}/claim-items/{action_id}#

Remove a Claim Item from a Claim

Remove an order item from a claim by the ID of the item's WRITE_OFF_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 claim's ID.
action_idstring
The ID of the order item's WRITE_OFF_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.
claimobject
The claim's details.

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

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

Add Inbound Items to a Claim

Add inbound (or return) items to a claim. These inbound items will have a RETURN_ITEM action.

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

Path parameters

idstring
The claim's ID.

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/claims/{id}/inbound/items/{action_id}#

Update Inbound Items of a Claim

Update an inbound (or return) item of a claim 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 claim'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 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/claims/{id}/inbound/items/{action_id}#

Remove an Inbound Item from Claim

Remove an inbound (or return) item from a claim 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 claim'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/claims/{id}/inbound/shipping-method#

Add an Inbound Shipping Method to a Claim

Add an inbound (or return) shipping method to a claim. 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 claim'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/claims/{id}/inbound/shipping-method/{action_id}#

Update Inbound Shipping Method of a Claim

Update the shipping method for returning items in the claim 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 claim'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[]Optional
Filter by the claim's ID.
statusstring | string[]Optional
Filter by the claim's status.
created_atobjectOptional
Filter by a claim's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by a claim's update date. Accepts the filter operators.
deleted_atobjectOptional
Filter by a claim's deletion date. Accepts the filter operators.

Request body (application/json)

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

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

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

Remove Inbound Shipping Method from Claim

Remove the shipping method for returning items in the claim 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 claim'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/claims/{id}/outbound/items#

Add Outbound Items to a Claim

Add outbound (or new) items to a claim. These outbound items will have an ITEM_ADD action.

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

Path parameters

idstring
The claim'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
Filter by the claim's ID.
statusstring | string[]Optional
Filter by the claim's status.
created_atobjectOptional
Filter by a claim's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by a claim's update date. Accepts the filter operators.
deleted_atobjectOptional
Filter by a claim's deletion date. Accepts the filter operators.

Request body (application/json)

itemsobject[]Optional
The outbound item's 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.
claimobject
The claim's details.

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

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

Update Outbound Item of a Claim

Update an outbound (or new) item of a claim 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 claim's ID.
action_idstring
The ID of the new claim 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.
idstring | string[]Optional
Filter by the claim's ID.
statusstring | string[]Optional
Filter by the claim's status.
created_atobjectOptional
Filter by a claim's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by a claim's update date. Accepts the filter operators.
deleted_atobjectOptional
Filter by a claim's deletion date. Accepts the filter operators.

Request body (application/json)

quantitynumberOptional
The item's quantity.
reason_idstringOptional
The ID of the return reason associated with the item.
internal_notestringOptional
A note that's 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.
claimobject
The claim's details.

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

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

Remove an Outbound Item from Claim

Remove an outbound (or new) item from a claim 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 claim's ID.
action_idstring
The ID of the new claim 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.
claimobject
The claim's details.

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

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

Add Outbound Shipping Methods to a Claim

Add an outbound shipping method to a claim. 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 claim'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
Filter by the claim's ID.
statusstring | string[]Optional
Filter by the claim's status.
created_atobjectOptional
Filter by a claim's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by a claim's update date. Accepts the filter operators.
deleted_atobjectOptional
Filter by a claim's deletion date. Accepts the filter operators.

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 only viewed by admin users.
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.
claimobject
The claim's details.

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

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

Update Outbound Shipping Method of a Claim

Update the shipping method for delivering outbound items in a claim 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 claim'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[]Optional
Filter by the claim's ID.
statusstring | string[]Optional
Filter by the claim's status.
created_atobjectOptional
Filter by a claim's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by a claim's update date. Accepts the filter operators.
deleted_atobjectOptional
Filter by a claim's deletion date. Accepts the filter operators.

Request body (application/json)

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

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

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

Remove Outbound Shipping Method from Claim

Remove the shipping method for delivering outbound items in the claim 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 claim'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.
claimobject
The claim's details.

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

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

Confirm a Claim Request

Confirm a claim request, applying its changes on the associated order.

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

Path parameters

idstring
The claim'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
Filter by the claim's ID.
statusstring | string[]Optional
Filter by the claim's status.
created_atobjectOptional
Filter by a claim's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by a claim's update date. Accepts the filter operators.
deleted_atobjectOptional
Filter by a claim's deletion date. Accepts the filter operators.

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.
claimobject
The claim's details.

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

Emitted events

  • order.claim_created: Emitted when a claim is created for an order.
  • reservation-item.created: Emitted when reservations are created.

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

Cancel Claim Request

Cancel a requested claim.

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

Path parameters

idstring
The claim's ID.

Request examples

Responses

200 OK

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

Default: "claim"

deletedboolean
Whether the claim 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