Creating a shipment for an order in OTO through the API is a simple process when you understand the required fields and the proper API calls. This guide will walk you through the steps necessary to create a shipment using OTO's REST API.
Instructions
Step 1: Obtain the Required Authentication
- Before making any API request, ensure that you have a valid access Token. The token is necessary for authentication and must be included in the headers of all API requests.
To obtain the token, log in to the OTO dashboard and navigate to Settings → Developers → API Integrations. Retrieve your refresh token and then use it to get an access token.
Step 2: Understand the Required API Endpoint
- The endpoint for creating a shipment is as follows:
https://api.tryoto.com/rest/v2/createShipmentThis endpoint requires certain fields to be passed in the request body. This endpoint requires specific fields in the request body, including order details, delivery company selection, and other shipment-related metadata.
Step 3: Prepare the Request Body
- The request body must be in JSON format and should include the following fields:
| Name | Required | Type | Description |
|---|---|---|---|
| deliveryOptionId | no | number | The Id of the shipping company we wish to create the shipment with. If it is not sent, the shipment is assigned to the delivery company that matches your feasibility rule. |
| orderId | yes (if there is no otoId) | text | Order ID for transactions of a single Order |
| otoId | yes (if there is no orderId) | text | Unique ID created by OTO |
| packageWeight | no | double | Total weight of the shipment |
| boxWidth | no | double | Width of the package (used for OTO rates) |
| boxLength | no | double | Length of the package (used for OTO rates) |
| boxHeight | no | double | Height of the package (used for OTO rates) |
| packageCount | no | integer | Number of packages in the order |
| pickingType | no | enum | Possible values: PICKUP_BY_DC (the shipping company offers free pickup from origin), BRANCH_DROP_OFF (the package must be delivered to a branch of the shipping company) |
| whoPays | no | enum | Who will pay for the shipment. Possible values: marketplacePaysDeliveryFee, sellerPaysDeliveryFee |
| frontSideIDCard | no | text | URL of the front side of the recipient’s national ID card. Required for international shipments to Kuwait, Oman and Qatar. |
| backSideIDCard | no | text | URL of the back side of the recipient’s national ID card. Required for international shipments to Kuwait, Oman and Qatar. |
Step 4: Make the API Call
- Use the following cURL command to send the request:
curl --location 'https://api.tryoto.com/rest/v2/createShipment' \ --header 'Authorization: Bearer {{token}}' \ --data '{ "orderId": "1232464", "deliveryOptionId":"12345" }'
Step 5: Handle the Response
- A successful response will look like this:
{ "success": true, "message": "create shipment request is received." }
Note:
To create shipments, you need a valid delivery option ID, which refers to a delivery company. There are two ways to obtain valid delivery options:
A. OTO-Provided Delivery Options
- You do not need contracts with delivery companies.
- OTO provides pre-integrated delivery company options.
- Use the Check OTO Delivery Fee endpoint to view available options.
B. Integrated Delivery Options (Your Own Accounts)
- If you have contracts with one or more delivery companies, you can integrate them with OTO.
- You provide OTO with your delivery company credentials.
- Each delivery company you integrate is assigned a Delivery Option ID.
- Use the Get Delivery Options endpoint to retrieve these IDs.
