API reference

Returns API

Manage return requests: create, approve, and reject customer return requests, and track them through to reverse shipment. Covers the lookup reference data merchants configure for the returns workflow — reasons, rejection reasons, resolutions, refund types, and item conditions.

Serverhttps://api.carriyo.comAuthOAuth 2.0 + API KeySpecreturns.yaml

Return Requests

A Carriyo return object represents a customer return request. A return is created when a customer requests to return an item for some reason, such as the item arriving damaged, the product not matching its description, or the customer simply changing their mind.

When a return is initiated, a business user can approve the request, which may result in the creation of a reverse shipment.

The Carriyo Returns API allows the merchant to create, approve, reject and manage return requests. It also allows the merchant to define allowed return reasons, resolutions, and other return settings.

17 operations · 1 object

Object

The Return Request object

The return request object represents a customer return — the items being returned, the reason and resolution, refund information, and the linked reverse shipment that brings the goods back to your warehouse.

Return requests flow through a workflow: created → approved (or rejected) → received → completed. Each transition emits a webhook event so your downstream systems stay in sync.

For the high-level reverse-logistics walkthrough, see Returns and Reverse shipments.

Properties

return_request_idstring
shipmentsstring[]
List of shipment ids associated with this return request.
partner_order_referencestring
merchantstring
statusstring
Click here for the list of Return Request Status Codes
pickuppickup-object
customer_commentstring
channelstring
notesobject[]
itemsreturn-request-item[]
refund_methodstring
refund_inforeturn-refund-info
creation_datestring
update_datestring
approval_datestring
cancellation_datestring
rejection_datestring
completion_datestring
return_items_updatesreturn-items-update[]
collectionreturn-collection
Scheduled collection window. Set when the return is collected from the customer.
assigned_to_userstring
Email or user identifier of the dashboard user the return request is assigned to.
auto_closedboolean
True when the return request was automatically closed by the auto-close job (no progress within the configured window).
auto_closed_datestringformat: date-time
Timestamp when the return request was auto-closed.
creation_sourcerequest-source
Identifies the system or actor that created the return request.
update_sourcerequest-source
Identifies the system or actor that last updated the return request.
updated_by_userstring
Email or user identifier of the dashboard user who last updated the return request.

Create return request — POST /return-requests
Approve return request — POST /return-requests/{return_request_id}/approve
Reject return request — POST /return-requests/{return_request_id}/reject
Returns guide — when to use the Returns API vs reverse shipments

post/returns/requests

Create return request

Creates a new return request. A pickup location is required so the reverse shipment can be created when the return request is approved.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

Content type: application/jsonSchema: create-return-request

merchantstringrequired
pickuppickup-request
Pickup request must contain all the neccessary information about the sender: their name, phone number, email, address, city and country. These properties will be given from the corresponding partner location, if either of following fields are specified instead: partner_location_id, partner_location_name, partner_location_code.
channelstring
partner_order_referencestringrequired
itemsobject[]required
commentsobject[]
resolutionstringrequired

Responses

200Return request created.Schema: return-request

return_request_idstring
shipmentsstring[]
List of shipment ids associated with this return request.
partner_order_referencestring
merchantstring
statusstring
Click here for the list of Return Request Status Codes
pickuppickup-object
customer_commentstring
channelstring
notesobject[]
itemsreturn-request-item[]
refund_methodstring
refund_inforeturn-refund-info
creation_datestring
update_datestring
approval_datestring
cancellation_datestring
rejection_datestring
completion_datestring
return_items_updatesreturn-items-update[]
collectionreturn-collection
Scheduled collection window. Set when the return is collected from the customer.
assigned_to_userstring
Email or user identifier of the dashboard user the return request is assigned to.
auto_closedboolean
True when the return request was automatically closed by the auto-close job (no progress within the configured window).
auto_closed_datestringformat: date-time
Timestamp when the return request was auto-closed.
creation_sourcerequest-source
Identifies the system or actor that created the return request.
update_sourcerequest-source
Identifies the system or actor that last updated the return request.
updated_by_userstring
Email or user identifier of the dashboard user who last updated the return request.

400Returns 400 when * duplicated SKU found in request * the requested quantity is missing for some SKU

Need the full machine-readable spec? Download the OpenAPI document →

get/returns/available-items

Get remaining items

Returns the items on the order that are still eligible for return.

Query parameters

Name	Type	Required	Description
merchant	string	Yes	—
email_or_phone	string	Yes	—
partner_order_ref	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Items still eligible for return on the order.

skustring
quantityinteger
descriptionstring
delivery_datestring

Need the full machine-readable spec? Download the OpenAPI document →

get/returns/available-locations

Get available locations

Returns the customer's available collection locations, derived from delivered shipments.

Query parameters

Name	Type	Required	Description
merchant	string	Yes	—
email_or_phone	string	Yes	—
partner_order_ref	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Drop-off locations available for the return.

partner_location_idstring
ID of the dropoff location if it's provided by the merchant
collection_point_idstring
ID of the carrier collection point
contact_namestring
Name of the contact person
contact_phonestring
Phone number of the contact person in E164 format with country code. e.g., +442071234567
contact_emailstring
Email address of the contact person
alternate_phonestring
Alternate phone number of the contact person in E164 format with country code. e.g., +442071234567
address1string
Line 1 of the adddress
address2string
Line 2 of the adddress
areastring
District, suburb or neighbourhood, represented by the Carriyo Area Code if known. If not, it's a free text. Please refer to the Carriyo Geo List for more information.
input_areastring
(Ready-only) Preserves the original input provided for "area". It is useful when Carriyo is instructed to automatically recognise the Carriyo area code.
area_coordsnumber[]
(Read-only) Approximate latitude and longitude for the area, if found in Carriyo's database. e.g., [25.1949849, 55.2784141]
input_citystring
Original input city name from the client which get resolved into Carriyo city code.
citystring
City part of the adddress - usually a Carriyo city code
city_coordsnumber[]
(Read-only) Approximate latitude and longitude for the city, if found in Carriyo's database. e.g., [25.1949849, 55.2784141]
statestring
State part of the adddress
input_statestring
(Ready-only) Preserves the original input provided for "state". It is useful when Carriyo is instructed to automatically recognise the Carriyo state code.
postcodestring
Postal code part of the adddress
countrystring
Country of the adddress represented as a 2-letter ISO code
coordsnumber[]
Latitude and longitude of the address represented in decimal degrees
typestring
Type of address
Values:residentialbusiness
notesstring
Any additional notes
what3wordsstringformat: ///three.word.address
personal_idpersonal_id
streetstring
Street number or name
buildingstring
Building number or name
floorstring
Floor number
flatstring
Flat number
po_boxstring
Box number if the address is a PO Box
custom_fieldscustom-fields
Custom address fields in the form of a map: {"field1" : ["value1", "value2"], "field2" : ["value1", "value2"]}

Need the full machine-readable spec? Download the OpenAPI document →

get/returns/requests/{return_request_id}

Get return request

Returns the specified return request.

Path parameters

Name	Type	Required	Description
return_request_id	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Returns the requested return request.Schema: return-request

return_request_idstring
shipmentsstring[]
List of shipment ids associated with this return request.
partner_order_referencestring
merchantstring
statusstring
Click here for the list of Return Request Status Codes
pickuppickup-object
customer_commentstring
channelstring
notesobject[]
itemsreturn-request-item[]
refund_methodstring
refund_inforeturn-refund-info
creation_datestring
update_datestring
approval_datestring
cancellation_datestring
rejection_datestring
completion_datestring
return_items_updatesreturn-items-update[]
collectionreturn-collection
Scheduled collection window. Set when the return is collected from the customer.
assigned_to_userstring
Email or user identifier of the dashboard user the return request is assigned to.
auto_closedboolean
True when the return request was automatically closed by the auto-close job (no progress within the configured window).
auto_closed_datestringformat: date-time
Timestamp when the return request was auto-closed.
creation_sourcerequest-source
Identifies the system or actor that created the return request.
update_sourcerequest-source
Identifies the system or actor that last updated the return request.
updated_by_userstring
Email or user identifier of the dashboard user who last updated the return request.

Need the full machine-readable spec? Download the OpenAPI document →

patch/returns/requests/{return_request_id}

Update return request

Update properties of an existing return request. Allowed only while the request is in PENDING status; once approved, it cannot be modified.

Path parameters

Name	Type	Required	Description
return_request_id	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

Content type: application/jsonSchema: edit-return-request

pickuppickup-request
Pickup request must contain all the neccessary information about the sender: their name, phone number, email, address, city and country. These properties will be given from the corresponding partner location, if either of following fields are specified instead: partner_location_id, partner_location_name, partner_location_code.
itemsobject[]
resolutionstring

Responses

200Return request updated.Schema: return-request

return_request_idstring
shipmentsstring[]
List of shipment ids associated with this return request.
partner_order_referencestring
merchantstring
statusstring
Click here for the list of Return Request Status Codes
pickuppickup-object
customer_commentstring
channelstring
notesobject[]
itemsreturn-request-item[]
refund_methodstring
refund_inforeturn-refund-info
creation_datestring
update_datestring
approval_datestring
cancellation_datestring
rejection_datestring
completion_datestring
return_items_updatesreturn-items-update[]
collectionreturn-collection
Scheduled collection window. Set when the return is collected from the customer.
assigned_to_userstring
Email or user identifier of the dashboard user the return request is assigned to.
auto_closedboolean
True when the return request was automatically closed by the auto-close job (no progress within the configured window).
auto_closed_datestringformat: date-time
Timestamp when the return request was auto-closed.
creation_sourcerequest-source
Identifies the system or actor that created the return request.
update_sourcerequest-source
Identifies the system or actor that last updated the return request.
updated_by_userstring
Email or user identifier of the dashboard user who last updated the return request.

400Returns 400 when * RMA is not in `PENDING` status.

Need the full machine-readable spec? Download the OpenAPI document →

patch/returns/requests/{return_request_id}/approve

Approve return request

Approves the return request, sets its status to APPROVED, and creates the associated reverse shipment. The return request must have pickup and dropoff details at this point. Payment, if not supplied, is computed from the shipment items in the request.

Path parameters

Name	Type	Required	Description
return_request_id	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

Content type: application/jsonSchema: approve-return-request

itemsobject[]

Responses

200Return request approved.Schema: return-request

return_request_idstring
shipmentsstring[]
List of shipment ids associated with this return request.
partner_order_referencestring
merchantstring
statusstring
Click here for the list of Return Request Status Codes
pickuppickup-object
customer_commentstring
channelstring
notesobject[]
itemsreturn-request-item[]
refund_methodstring
refund_inforeturn-refund-info
creation_datestring
update_datestring
approval_datestring
cancellation_datestring
rejection_datestring
completion_datestring
return_items_updatesreturn-items-update[]
collectionreturn-collection
Scheduled collection window. Set when the return is collected from the customer.
assigned_to_userstring
Email or user identifier of the dashboard user the return request is assigned to.
auto_closedboolean
True when the return request was automatically closed by the auto-close job (no progress within the configured window).
auto_closed_datestringformat: date-time
Timestamp when the return request was auto-closed.
creation_sourcerequest-source
Identifies the system or actor that created the return request.
update_sourcerequest-source
Identifies the system or actor that last updated the return request.
updated_by_userstring
Email or user identifier of the dashboard user who last updated the return request.

400Returns 400 when: * dropoff location is missing in the resulted RMA object. * RMA is not in `PENDING` status.

Need the full machine-readable spec? Download the OpenAPI document →

patch/returns/requests/{return_request_id}/cancel

Cancel return request

Cancels the return request, sets its status to CANCELLED, and cancels the associated reverse shipment.

Path parameters

Name	Type	Required	Description
return_request_id	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Return request cancelled.Schema: return-request

return_request_idstring
shipmentsstring[]
List of shipment ids associated with this return request.
partner_order_referencestring
merchantstring
statusstring
Click here for the list of Return Request Status Codes
pickuppickup-object
customer_commentstring
channelstring
notesobject[]
itemsreturn-request-item[]
refund_methodstring
refund_inforeturn-refund-info
creation_datestring
update_datestring
approval_datestring
cancellation_datestring
rejection_datestring
completion_datestring
return_items_updatesreturn-items-update[]
collectionreturn-collection
Scheduled collection window. Set when the return is collected from the customer.
assigned_to_userstring
Email or user identifier of the dashboard user the return request is assigned to.
auto_closedboolean
True when the return request was automatically closed by the auto-close job (no progress within the configured window).
auto_closed_datestringformat: date-time
Timestamp when the return request was auto-closed.
creation_sourcerequest-source
Identifies the system or actor that created the return request.
update_sourcerequest-source
Identifies the system or actor that last updated the return request.
updated_by_userstring
Email or user identifier of the dashboard user who last updated the return request.

Need the full machine-readable spec? Download the OpenAPI document →

patch/returns/requests/{return_request_id}/reject

Reject return request

Rejects the return request with a reason.

Path parameters

Name	Type	Required	Description
return_request_id	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

Content type: application/json

itemsobject[]

Responses

200Return request rejected.Schema: return-request

return_request_idstring
shipmentsstring[]
List of shipment ids associated with this return request.
partner_order_referencestring
merchantstring
statusstring
Click here for the list of Return Request Status Codes
pickuppickup-object
customer_commentstring
channelstring
notesobject[]
itemsreturn-request-item[]
refund_methodstring
refund_inforeturn-refund-info
creation_datestring
update_datestring
approval_datestring
cancellation_datestring
rejection_datestring
completion_datestring
return_items_updatesreturn-items-update[]
collectionreturn-collection
Scheduled collection window. Set when the return is collected from the customer.
assigned_to_userstring
Email or user identifier of the dashboard user the return request is assigned to.
auto_closedboolean
True when the return request was automatically closed by the auto-close job (no progress within the configured window).
auto_closed_datestringformat: date-time
Timestamp when the return request was auto-closed.
creation_sourcerequest-source
Identifies the system or actor that created the return request.
update_sourcerequest-source
Identifies the system or actor that last updated the return request.
updated_by_userstring
Email or user identifier of the dashboard user who last updated the return request.

Need the full machine-readable spec? Download the OpenAPI document →

patch/returns/requests/{return_request_id}/receive

Receive return request

Records receipt of the return request with the specified item quantities.

Path parameters

Name	Type	Required	Description
return_request_id	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

Content type: application/json

itemsobject[]

Responses

200Return request marked as received.Schema: return-request

return_request_idstring
shipmentsstring[]
List of shipment ids associated with this return request.
partner_order_referencestring
merchantstring
statusstring
Click here for the list of Return Request Status Codes
pickuppickup-object
customer_commentstring
channelstring
notesobject[]
itemsreturn-request-item[]
refund_methodstring
refund_inforeturn-refund-info
creation_datestring
update_datestring
approval_datestring
cancellation_datestring
rejection_datestring
completion_datestring
return_items_updatesreturn-items-update[]
collectionreturn-collection
Scheduled collection window. Set when the return is collected from the customer.
assigned_to_userstring
Email or user identifier of the dashboard user the return request is assigned to.
auto_closedboolean
True when the return request was automatically closed by the auto-close job (no progress within the configured window).
auto_closed_datestringformat: date-time
Timestamp when the return request was auto-closed.
creation_sourcerequest-source
Identifies the system or actor that created the return request.
update_sourcerequest-source
Identifies the system or actor that last updated the return request.
updated_by_userstring
Email or user identifier of the dashboard user who last updated the return request.

Need the full machine-readable spec? Download the OpenAPI document →

patch/returns/requests/{return_request_id}/complete

Complete return request

Marks the return request as completed.

Path parameters

Name	Type	Required	Description
return_request_id	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Return request completed.Schema: return-request

return_request_idstring
shipmentsstring[]
List of shipment ids associated with this return request.
partner_order_referencestring
merchantstring
statusstring
Click here for the list of Return Request Status Codes
pickuppickup-object
customer_commentstring
channelstring
notesobject[]
itemsreturn-request-item[]
refund_methodstring
refund_inforeturn-refund-info
creation_datestring
update_datestring
approval_datestring
cancellation_datestring
rejection_datestring
completion_datestring
return_items_updatesreturn-items-update[]
collectionreturn-collection
Scheduled collection window. Set when the return is collected from the customer.
assigned_to_userstring
Email or user identifier of the dashboard user the return request is assigned to.
auto_closedboolean
True when the return request was automatically closed by the auto-close job (no progress within the configured window).
auto_closed_datestringformat: date-time
Timestamp when the return request was auto-closed.
creation_sourcerequest-source
Identifies the system or actor that created the return request.
update_sourcerequest-source
Identifies the system or actor that last updated the return request.
updated_by_userstring
Email or user identifier of the dashboard user who last updated the return request.

Need the full machine-readable spec? Download the OpenAPI document →

post/returns/requests/{return_request_id}/notes

Add note

Adds a note to the return request.

Path parameters

Name	Type	Required	Description
return_request_id	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Header parameters

Name	Type	Required	Description
x-user	string	Yes	—

Request body

Content type: application/json

textstringrequired

Responses

200Note added to the return request.Schema: return-request

return_request_idstring
shipmentsstring[]
List of shipment ids associated with this return request.
partner_order_referencestring
merchantstring
statusstring
Click here for the list of Return Request Status Codes
pickuppickup-object
customer_commentstring
channelstring
notesobject[]
itemsreturn-request-item[]
refund_methodstring
refund_inforeturn-refund-info
creation_datestring
update_datestring
approval_datestring
cancellation_datestring
rejection_datestring
completion_datestring
return_items_updatesreturn-items-update[]
collectionreturn-collection
Scheduled collection window. Set when the return is collected from the customer.
assigned_to_userstring
Email or user identifier of the dashboard user the return request is assigned to.
auto_closedboolean
True when the return request was automatically closed by the auto-close job (no progress within the configured window).
auto_closed_datestringformat: date-time
Timestamp when the return request was auto-closed.
creation_sourcerequest-source
Identifies the system or actor that created the return request.
update_sourcerequest-source
Identifies the system or actor that last updated the return request.
updated_by_userstring
Email or user identifier of the dashboard user who last updated the return request.

Need the full machine-readable spec? Download the OpenAPI document →

delete/returns/requests/{return_request_id}/notes/{note_id}

Delete note

Deletes a note from the return request by ID.

Path parameters

Name	Type	Required	Description
return_request_id	string	Yes	—
note_id	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Note deleted from the return request.Schema: return-request

return_request_idstring
shipmentsstring[]
List of shipment ids associated with this return request.
partner_order_referencestring
merchantstring
statusstring
Click here for the list of Return Request Status Codes
pickuppickup-object
customer_commentstring
channelstring
notesobject[]
itemsreturn-request-item[]
refund_methodstring
refund_inforeturn-refund-info
creation_datestring
update_datestring
approval_datestring
cancellation_datestring
rejection_datestring
completion_datestring
return_items_updatesreturn-items-update[]
collectionreturn-collection
Scheduled collection window. Set when the return is collected from the customer.
assigned_to_userstring
Email or user identifier of the dashboard user the return request is assigned to.
auto_closedboolean
True when the return request was automatically closed by the auto-close job (no progress within the configured window).
auto_closed_datestringformat: date-time
Timestamp when the return request was auto-closed.
creation_sourcerequest-source
Identifies the system or actor that created the return request.
update_sourcerequest-source
Identifies the system or actor that last updated the return request.
updated_by_userstring
Email or user identifier of the dashboard user who last updated the return request.

Need the full machine-readable spec? Download the OpenAPI document →

patch/returns/requests/{return_request_id}/assign-to-user

Assign return request to a user

Assigns the return request to a Carriyo dashboard user. The user identifier is typically an email.

Path parameters

Name	Type	Required	Description
return_request_id	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

Content type: application/jsonSchema: return-assign-to-user-requestrequired

assigned_to_userstringrequired
Email or user identifier of the dashboard user to assign the return request to.

Responses

200Return request assignment updated.Schema: return-request

return_request_idstring
shipmentsstring[]
List of shipment ids associated with this return request.
partner_order_referencestring
merchantstring
statusstring
Click here for the list of Return Request Status Codes
pickuppickup-object
customer_commentstring
channelstring
notesobject[]
itemsreturn-request-item[]
refund_methodstring
refund_inforeturn-refund-info
creation_datestring
update_datestring
approval_datestring
cancellation_datestring
rejection_datestring
completion_datestring
return_items_updatesreturn-items-update[]
collectionreturn-collection
Scheduled collection window. Set when the return is collected from the customer.
assigned_to_userstring
Email or user identifier of the dashboard user the return request is assigned to.
auto_closedboolean
True when the return request was automatically closed by the auto-close job (no progress within the configured window).
auto_closed_datestringformat: date-time
Timestamp when the return request was auto-closed.
creation_sourcerequest-source
Identifies the system or actor that created the return request.
update_sourcerequest-source
Identifies the system or actor that last updated the return request.
updated_by_userstring
Email or user identifier of the dashboard user who last updated the return request.

404Return request not found for the supplied `return_request_id` and `tenant-id`.

Need the full machine-readable spec? Download the OpenAPI document →

patch/returns/requests/{return_request_id}/split

Split return request items

Splits selected items out of the return request into a new return request, optionally assigning a pickup location.

Path parameters

Name	Type	Required	Description
return_request_id	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

Content type: application/jsonSchema: split-return-request-items-request

itemsreturn-split-item[]
partner_location_idstring
Pickup location to assign to the new (split) return request.

Responses

200Items split into a new return request.Schema: return-request

return_request_idstring
shipmentsstring[]
List of shipment ids associated with this return request.
partner_order_referencestring
merchantstring
statusstring
Click here for the list of Return Request Status Codes
pickuppickup-object
customer_commentstring
channelstring
notesobject[]
itemsreturn-request-item[]
refund_methodstring
refund_inforeturn-refund-info
creation_datestring
update_datestring
approval_datestring
cancellation_datestring
rejection_datestring
completion_datestring
return_items_updatesreturn-items-update[]
collectionreturn-collection
Scheduled collection window. Set when the return is collected from the customer.
assigned_to_userstring
Email or user identifier of the dashboard user the return request is assigned to.
auto_closedboolean
True when the return request was automatically closed by the auto-close job (no progress within the configured window).
auto_closed_datestringformat: date-time
Timestamp when the return request was auto-closed.
creation_sourcerequest-source
Identifies the system or actor that created the return request.
update_sourcerequest-source
Identifies the system or actor that last updated the return request.
updated_by_userstring
Email or user identifier of the dashboard user who last updated the return request.

Need the full machine-readable spec? Download the OpenAPI document →

patch/returns/requests/{return_request_id}/status

Set return request status

Directly sets the status of the return request to the value supplied in the status query parameter.

Path parameters

Name	Type	Required	Description
return_request_id	string	Yes	—

Query parameters

Name	Type	Required	Description
status	string	Yes	The target return status.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Return request status updated.Schema: return-request

return_request_idstring
shipmentsstring[]
List of shipment ids associated with this return request.
partner_order_referencestring
merchantstring
statusstring
Click here for the list of Return Request Status Codes
pickuppickup-object
customer_commentstring
channelstring
notesobject[]
itemsreturn-request-item[]
refund_methodstring
refund_inforeturn-refund-info
creation_datestring
update_datestring
approval_datestring
cancellation_datestring
rejection_datestring
completion_datestring
return_items_updatesreturn-items-update[]
collectionreturn-collection
Scheduled collection window. Set when the return is collected from the customer.
assigned_to_userstring
Email or user identifier of the dashboard user the return request is assigned to.
auto_closedboolean
True when the return request was automatically closed by the auto-close job (no progress within the configured window).
auto_closed_datestringformat: date-time
Timestamp when the return request was auto-closed.
creation_sourcerequest-source
Identifies the system or actor that created the return request.
update_sourcerequest-source
Identifies the system or actor that last updated the return request.
updated_by_userstring
Email or user identifier of the dashboard user who last updated the return request.

400Returns 400 when the supplied status is not a recognised return status.

Need the full machine-readable spec? Download the OpenAPI document →

post/returns/requests/{return_request_id}/refunds

Add return refund

Records a refund against the return request.

Path parameters

Name	Type	Required	Description
return_request_id	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

Content type: application/jsonSchema: refund-add-request

referencestring
typestring
amountnumber
currencystring
notestring
refund_datestringformat: date-time

Responses

200Refund recorded against the return request.Schema: return-refund-info

refundsreturn-refund[]

Need the full machine-readable spec? Download the OpenAPI document →

delete/returns/requests/{return_request_id}/refunds/{refund_id}

Delete return refund

Removes a previously recorded refund from the return request.

Path parameters

Name	Type	Required	Description
return_request_id	string	Yes	—
refund_id	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Refund removed from the return request.Schema: return-refund-info

refundsreturn-refund[]

Need the full machine-readable spec? Download the OpenAPI document →

Return Reasons

The merchant can configure a custom list of return reasons based on their business requirements. These reasons are presented as options to the customer on the return portal. Common examples include "Not as described online", "Arrived damaged", "Wrong colour or size".

4 operations · 0 objects

post/returns/reasons

Create return reason

Creates a new return reason.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

Content type: application/jsonSchema: return-reason

codestring
namestring
merchantstring
require_commentsboolean
If this is enabled and user selects this return reason while creating the return request then they have to provide the comments.
require_imagesboolean
If this is enabled and user selects this return reason while creating the return request then they have to upload the images of the product.
require_item_conditionboolean
If this is enabled and user selects this return reason while creating the return request then user has to choose one of the return item conditions.
reverse_shipment_create_enabledboolean
If this is enabled and user selects this return reason while creating the return request then Carriyo will create a reverse shipment after the return request is approved.
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Responses

200Return reason created.Schema: return-reason

codestring
namestring
merchantstring
require_commentsboolean
If this is enabled and user selects this return reason while creating the return request then they have to provide the comments.
require_imagesboolean
If this is enabled and user selects this return reason while creating the return request then they have to upload the images of the product.
require_item_conditionboolean
If this is enabled and user selects this return reason while creating the return request then user has to choose one of the return item conditions.
reverse_shipment_create_enabledboolean
If this is enabled and user selects this return reason while creating the return request then Carriyo will create a reverse shipment after the return request is approved.
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Need the full machine-readable spec? Download the OpenAPI document →

get/returns/reasons

List return reasons

Returns the available return reasons for the merchant.

Query parameters

Name	Type	Required	Description
merchant	string	Yes	—
language	string	No	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Return reasons configured for the merchant.

codestring
namestring
merchantstring
require_commentsboolean
If this is enabled and user selects this return reason while creating the return request then they have to provide the comments.
require_imagesboolean
If this is enabled and user selects this return reason while creating the return request then they have to upload the images of the product.
require_item_conditionboolean
If this is enabled and user selects this return reason while creating the return request then user has to choose one of the return item conditions.
reverse_shipment_create_enabledboolean
If this is enabled and user selects this return reason while creating the return request then Carriyo will create a reverse shipment after the return request is approved.
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Need the full machine-readable spec? Download the OpenAPI document →

put/returns/reasons/{reason_code}

Update return reason

Updates an existing return reason.

Path parameters

Name	Type	Required	Description
reason_code	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

Content type: application/jsonSchema: return-reason

codestring
namestring
merchantstring
require_commentsboolean
If this is enabled and user selects this return reason while creating the return request then they have to provide the comments.
require_imagesboolean
If this is enabled and user selects this return reason while creating the return request then they have to upload the images of the product.
require_item_conditionboolean
If this is enabled and user selects this return reason while creating the return request then user has to choose one of the return item conditions.
reverse_shipment_create_enabledboolean
If this is enabled and user selects this return reason while creating the return request then Carriyo will create a reverse shipment after the return request is approved.
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Responses

200Return reason updated.Schema: return-reason

codestring
namestring
merchantstring
require_commentsboolean
If this is enabled and user selects this return reason while creating the return request then they have to provide the comments.
require_imagesboolean
If this is enabled and user selects this return reason while creating the return request then they have to upload the images of the product.
require_item_conditionboolean
If this is enabled and user selects this return reason while creating the return request then user has to choose one of the return item conditions.
reverse_shipment_create_enabledboolean
If this is enabled and user selects this return reason while creating the return request then Carriyo will create a reverse shipment after the return request is approved.
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Need the full machine-readable spec? Download the OpenAPI document →

delete/returns/reasons/{reason_code}

Delete return reason

Deletes a return reason by code.

Path parameters

Name	Type	Required	Description
reason_code	string	Yes	—

Query parameters

Name	Type	Required	Description
merchant	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Return reason deleted.

Need the full machine-readable spec? Download the OpenAPI document →

Rejection Reasons

The merchant can also configure a custom list of rejection reasons to use when rejecting a customer's request for return. These reasons are presented to the merchant as options when rejecting a return, and are used to communicate the rejection back to the customer.

4 operations · 0 objects

post/returns/rejection-reasons

Create rejection reason

Creates a new rejection reason.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

Content type: application/jsonSchema: rejection-reason

codestring
namestring
merchantstring
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Responses

200Rejection reason created.Schema: rejection-reason

codestring
namestring
merchantstring
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Need the full machine-readable spec? Download the OpenAPI document →

get/returns/rejection-reasons

List rejection reasons

Returns the available rejection reasons for the merchant.

Query parameters

Name	Type	Required	Description
merchant	string	No	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Rejection reasons configured for the merchant.

codestring
namestring
merchantstring
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Need the full machine-readable spec? Download the OpenAPI document →

put/returns/rejection-reasons/{reason_code}

Update rejection reason

Updates a rejection reason.

Path parameters

Name	Type	Required	Description
reason_code	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

Content type: application/jsonSchema: rejection-reason

codestring
namestring
merchantstring
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Responses

200Rejection reason updated.Schema: rejection-reason

codestring
namestring
merchantstring
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Need the full machine-readable spec? Download the OpenAPI document →

delete/returns/rejection-reasons/{reason_code}

Delete rejection reason

Deletes a rejection reason by code.

Path parameters

Name	Type	Required	Description
reason_code	string	Yes	—

Query parameters

Name	Type	Required	Description
merchant	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Rejection reason deleted.

Need the full machine-readable spec? Download the OpenAPI document →

Return Resolutions

Return resolutions are outcomes that the customer is expecting from the return. The options can vary based on what the merchant offers but typically include "Credit card refund", "Store credit", or "Exchange".

4 operations · 0 objects

post/returns/resolutions

Create return resolution

Creates a new return resolution.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

Content type: application/jsonSchema: return-resolution

codestring
namestring
merchantstring
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Responses

200Return resolution created.Schema: return-resolution

codestring
namestring
merchantstring
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Need the full machine-readable spec? Download the OpenAPI document →

get/returns/resolutions

List return resolutions

Returns the available return resolutions for the merchant.

Query parameters

Name	Type	Required	Description
merchant	string	Yes	—
language	string	No	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Return resolutions configured for the merchant.

codestring
namestring
merchantstring
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Need the full machine-readable spec? Download the OpenAPI document →

put/returns/resolutions/{resolution_code}

Update return resolution

Updates a return resolution.

Path parameters

Name	Type	Required	Description
resolution_code	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

Content type: application/jsonSchema: return-resolution

codestring
namestring
merchantstring
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Responses

200Return resolution updated.Schema: return-resolution

codestring
namestring
merchantstring
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Need the full machine-readable spec? Download the OpenAPI document →

delete/returns/resolutions/{resolution_code}

Delete return resolution

Deletes a return resolution by code.

Path parameters

Name	Type	Required	Description
resolution_code	string	Yes	—

Query parameters

Name	Type	Required	Description
merchant	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Return resolution deleted.

Need the full machine-readable spec? Download the OpenAPI document →

Return Refund Types

The merchant can configure a custom list of return refund types based on their business requirements. These refund types are presented as options to the customer on the return portal.

4 operations · 0 objects

post/returns/refund-types

Create return refund type

Creates a new return refund type.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

Content type: application/jsonSchema: return-refund-type

codestring
namestring
merchantstring
allowed_return_reasonsstring[]
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Responses

200Refund type created.Schema: return-refund-type

codestring
namestring
merchantstring
allowed_return_reasonsstring[]
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Need the full machine-readable spec? Download the OpenAPI document →

get/returns/refund-types

List return refund types

Returns the available return refund types for the merchant.

Query parameters

Name	Type	Required	Description
merchant	string	No	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Refund types configured for the merchant.

codestring
namestring
merchantstring
allowed_return_reasonsstring[]
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Need the full machine-readable spec? Download the OpenAPI document →

put/returns/refund-types/{refund_type_code}

Update return refund type

Updates a return refund type.

Path parameters

Name	Type	Required	Description
refund_type_code	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

Content type: application/jsonSchema: return-refund-type

codestring
namestring
merchantstring
allowed_return_reasonsstring[]
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Responses

200Refund type updated.Schema: return-refund-type

codestring
namestring
merchantstring
allowed_return_reasonsstring[]
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Need the full machine-readable spec? Download the OpenAPI document →

delete/returns/refund-types/{refund_type_code}

Delete return refund type

Deletes a return refund type by code.

Path parameters

Name	Type	Required	Description
refund_type_code	string	Yes	—

Query parameters

Name	Type	Required	Description
merchant	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Refund type deleted.

Need the full machine-readable spec? Download the OpenAPI document →

Return Item Conditions

The merchant can configure a custom list of return item conditions based on their business requirements. These item conditions are presented as options to the customer on the return portal when describing the state of the item being returned.

4 operations · 0 objects

put/returns/item-conditions/{item_condition_code}

Update return item condition

Updates a return item condition.

Path parameters

Name	Type	Required	Description
item_condition_code	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

Content type: application/jsonSchema: return-item-condition

codestring
namestring
merchantstring
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Responses

200Return item condition updated.Schema: return-item-condition

codestring
namestring
merchantstring
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Need the full machine-readable spec? Download the OpenAPI document →

delete/returns/item-conditions/{item_condition_code}

Delete return item condition

Deletes a return item condition by code.

Path parameters

Name	Type	Required	Description
item_condition_code	string	Yes	—

Query parameters

Name	Type	Required	Description
merchant	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Return item condition deleted.

Need the full machine-readable spec? Download the OpenAPI document →

post/returns/item-conditions

Create return item condition

Creates a new return item condition.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

Content type: application/jsonSchema: return-item-condition

codestring
namestring
merchantstring
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Responses

200Return item condition created.Schema: return-item-condition

codestring
namestring
merchantstring
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Need the full machine-readable spec? Download the OpenAPI document →

get/returns/item-conditions

List return item conditions

Returns the available return item conditions for the merchant.

Query parameters

Name	Type	Required	Description
merchant	string	No	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Return item conditions configured for the merchant.

codestring
namestring
merchantstring
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Need the full machine-readable spec? Download the OpenAPI document →

Return Settings

The return settings hold the general configuration for returns at the merchant level.

4 operations · 0 objects

post/returns/settings

Create return settings

Creates the return settings for the merchant.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

Content type: application/jsonSchema: return-request-settings

merchantstring
allowed_days_for_returninteger
default_dropoff_locationsobject
Key-value map, where key is a country code and value is default dropoff location for this country code
allow_undelivered_itemsboolean
allow_pickup_location_selectionboolean
notification_usersobject[]
order_lookup_methodsstring[]
shopify_integration_enabledstring
shopify_connector_idstring

Responses

200Return settings created.Schema: return-request-settings

merchantstring
allowed_days_for_returninteger
default_dropoff_locationsobject
Key-value map, where key is a country code and value is default dropoff location for this country code
allow_undelivered_itemsboolean
allow_pickup_location_selectionboolean
notification_usersobject[]
order_lookup_methodsstring[]
shopify_integration_enabledstring
shopify_connector_idstring

Need the full machine-readable spec? Download the OpenAPI document →

get/returns/settings

Get return settings

Returns the merchant's return settings.

Query parameters

Name	Type	Required	Description
merchant	string	Yes	—
notification_user_scope	string	No	—
shopify_connector_id	string	No	—
notification_user_id	string	No	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Return settings for the merchant.Schema: return-request-settings

merchantstring
allowed_days_for_returninteger
default_dropoff_locationsobject
Key-value map, where key is a country code and value is default dropoff location for this country code
allow_undelivered_itemsboolean
allow_pickup_location_selectionboolean
notification_usersobject[]
order_lookup_methodsstring[]
shopify_integration_enabledstring
shopify_connector_idstring

Need the full machine-readable spec? Download the OpenAPI document →

put/returns/settings

Update return settings

Updates the merchant's return settings.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

Content type: application/jsonSchema: return-request-settings

merchantstring
allowed_days_for_returninteger
default_dropoff_locationsobject
Key-value map, where key is a country code and value is default dropoff location for this country code
allow_undelivered_itemsboolean
allow_pickup_location_selectionboolean
notification_usersobject[]
order_lookup_methodsstring[]
shopify_integration_enabledstring
shopify_connector_idstring

Responses

200Return settings updated.Schema: return-request-settings

merchantstring
allowed_days_for_returninteger
default_dropoff_locationsobject
Key-value map, where key is a country code and value is default dropoff location for this country code
allow_undelivered_itemsboolean
allow_pickup_location_selectionboolean
notification_usersobject[]
order_lookup_methodsstring[]
shopify_integration_enabledstring
shopify_connector_idstring

Need the full machine-readable spec? Download the OpenAPI document →

delete/returns/settings

Delete return settings

Deletes the merchant's return settings.

Query parameters

Name	Type	Required	Description
merchant	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Return settings deleted.

Need the full machine-readable spec? Download the OpenAPI document →

Return Comments

The merchant can configure a custom list of return comments. Comments can be scoped to specific return reasons and are presented as options on the return portal.

4 operations · 0 objects

post/returns/comments

Create return comment

Creates a new return comment.

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

Content type: application/jsonSchema: return-comment

codestring
namestring
merchantstring
allowed_return_reasonsstring[]
Return reason codes this comment applies to.
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Responses

200Return comment created.Schema: return-comment

codestring
namestring
merchantstring
allowed_return_reasonsstring[]
Return reason codes this comment applies to.
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Need the full machine-readable spec? Download the OpenAPI document →

get/returns/comments

List return comments

Returns the available return comments for the merchant.

Query parameters

Name	Type	Required	Description
merchant	string	Yes	—
language	string	No	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Return comments configured for the merchant.

codestring
namestring
merchantstring
allowed_return_reasonsstring[]
Return reason codes this comment applies to.
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Need the full machine-readable spec? Download the OpenAPI document →

put/returns/comments/{comment_code}

Update return comment

Updates an existing return comment.

Path parameters

Name	Type	Required	Description
comment_code	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
Content-Type	application/json	Yes	Media type of the request body.

Request body

Content type: application/jsonSchema: return-comment

codestring
namestring
merchantstring
allowed_return_reasonsstring[]
Return reason codes this comment applies to.
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Responses

200Return comment updated.Schema: return-comment

codestring
namestring
merchantstring
allowed_return_reasonsstring[]
Return reason codes this comment applies to.
translationstranslation
Key-value map, where key is a language (en, ru, uk etc.) and value is tranlsation.

Need the full machine-readable spec? Download the OpenAPI document →

delete/returns/comments/{comment_code}

Delete return comment

Deletes a return comment by code.

Path parameters

Name	Type	Required	Description
comment_code	string	Yes	—

Query parameters

Name	Type	Required	Description
merchant	string	Yes	—

Headers

Name	Value	Required	Description
Authorization	Bearer YOUR-ACCESS-TOKEN	Yes	OAuth 2.0 bearer token obtained from `POST /oauth/token`.
x-api-key	YOUR-API-KEY	Yes	Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.
tenant-id	YOUR-TENANT-ID	Yes	Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`.

Responses

200Return comment deleted.

Need the full machine-readable spec? Download the OpenAPI document →

Authentication

Every endpoint uses OAuth 2.0. Exchange your client credentials for an access token:

Get a token

curl -X POST 'https://api.carriyo.com/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "<your-client-id>",
    "client_secret": "<your-client-secret>"
  }'

Then send on every request

Authorization:Bearer <access-token>

tenant-id:<your-tenant-id>

x-api-key:<your-api-key>

Properties

Related

Headers

Request body

Responses

Query parameters

Headers

Responses

Query parameters

Headers

Responses

Path parameters

Headers

Responses

Path parameters

Headers

Request body

Responses

Path parameters

Headers

Request body

Responses

Path parameters

Headers

Responses

Path parameters

Headers

Request body

Responses

Path parameters

Headers

Request body

Responses

Path parameters

Headers

Responses

Path parameters

Headers

Header parameters

Request body

Responses

Path parameters

Headers

Responses

Path parameters

Headers

Request body

Responses

Path parameters

Headers

Request body

Responses

Path parameters

Query parameters

Headers

Responses

Path parameters

Headers

Request body

Responses

Path parameters

Headers

Responses

Headers

Request body

Responses

Query parameters

Headers

Responses

Path parameters

Headers

Request body

Responses

Path parameters

Query parameters

Headers

Responses

Headers

Request body

Responses