Return Shipments APIs

Modified on Wed, 1 Oct at 8:41 PM

Create Return Shipment

Endpoint URL

POST https://api.tryoto.com/rest/v2/createReturnShipment

Example Request Body

Here is an example of a request body:

{
  "orderId": "202111080914",
  "deliveryOptionId": "156",
  "pickupLocationCode": "wh1",
  "items": [
    {
      "quantity": "1",
      "sku": "SKU045857"
    }
  ]
}

Request Parameters

Name	Required	Type	Description
orderId	yes	string	Order number for which you want to create a reverse shipment.
pickupLocationCode	no	string	Predefined pickup address of branches/warehouses from `Create Pickup Location` endpoint.
deliveryOptionId	yes	string	Activated delivery company option id.
pickingType		enum	Possible values: PICKUP_BY_DC: Shipping company offers free pickup from origin. BRANCH_DROP_OFF: Package must be delivered to a branch of the shipping company.
items	no	Array	Array of items.
Name	Required	Type	Description
quantity	yes	string	Return quantity of item.
sku	yes	string	Sku of return item.

Available Packages: All Packages

This API endpoint allows you create reverse shipment for delivered orders, while creating shipments need a valid delivery option id. You can get valid delivery options in two ways:

Delivery Options with OTO rates :

No contracted delivery companies or activation is required. OTO offers a range of delivery company options, which are available for use. You can view these options and their associated fees by using the `Check OTO Delivery Fee` endpoint.

Delivery Options with your own rates: In this case, you already have agreements with one or more delivery companies. Each delivery company you connect is linked to a specific delivery option ID. You can retrieve these IDs by using the `Get Delivery Options` or `checkDeliveryFee` endpoints.

Request Parameters: |

###### Item fields definitions:

Get Return Link

Endpoint URL

POST https://api.tryoto.com/rest/v2/getReturnLink

Example Request Body

Here is an example of a request body:

{
  "orderId": "123"
}

Request Parameters

Name	Required	Type	Description
orderId	yes	string	The order for which a return request is requested.

Available Packages: Starter Package, Scale Package, Enterprise Package, Marketplaces

This API endpoint generates a link that serves as a return request portal for end customers. The portal allows customers to initiate return requests seamlessly. Additionally, the portal's details and settings can be customized in the OTO Dashboard to align with your specific requirements.

Request Parameters: |

Get Return Details

Endpoint URL

POST https://api.tryoto.com/rest/v2/getReturnDetails

Example Request Body

Here is an example of a request body:

{
  "orderId": "OID-9616-1008"
}

Request Parameters

Name	Required	Type	Description
orderId	yes	string	Returned order id.

Available Packages: All Packages

This API endpoint allows you to retrieve detailed information about the reverse shipment associated with a specific order. Reverse shipments are typically created when an order is returned or exchanged. This endpoint provides comprehensive insights into the reverse shipment process, including: return reason, returned items etc.

Request Parameters: |

Global error codes are defined in the APPENDIX folder. These are the endpoint specific error codes.

Trigger Return SMS

Endpoint URL

POST https://api.tryoto.com/rest/v2/triggerReturnSms

Example Request Body

Here is an example of a request body:

{
  "orderId": "523939"
}

Request Parameters

Name	Required	Type	Description
orderId	yes	string	The orderId you want to trigger return sms.

Available Packages: Starter Package, Scale Package, Enterprise Package, Marketplaces

This API endpoint will trigger an SMS for a successful return request, If your SMS settings are configured correctly.

Please note that, since the SMS service operates asynchronously, the response does not confirm that the SMS has been delivered to the end customer. For a more detailed investigation of any SMS delivery issues, we recommend checking the SMS Logs under the Logs section in the OTO UI.

Request Parameters: |