Creating 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 an order 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 the Sales Channel section under OTO API. Retrieve your refresh token and then use it to get an access token.
Step 2: Understand the Required API Endpoint
- The endpoint for creating an order is as follows:
https://api.tryoto.com/rest/v2/createOrderThis endpoint requires certain fields to be passed in the request body. These fields define the order's details, such as the customer information, items, delivery address, and additional 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 |
|---|---|---|---|
| orderId | yes | string | Id of the Order |
| parentOrderId | no | string | parent id of splitted orders. |
| ref1 | no | string | Reference for order optional |
| pickupLocationCode | no | string | predefined pickup address of stores/warehouses, if it doesn't exist then OTO will assign it to a pickup location automatically. it is required when serviceType is filled pickupfromStore |
| createShipment | no | boolean | if you fill it true then automatic shipment will be created for this order. pickupLocationCode is required when this field is true. |
| serviceType | no | string | pickupFromStore this is optional for orders customer pick it up from store |
| forReverseShipment | no | boolean | if it is true, order can be reverse shipped without forward shipment |
| deliveryOptionId | no | string | activated delivery company option id, if this exists OTO try to create shipment with this settings. if not exists try with possible active settings. |
| storeName | no | String | Name of the store |
| payment_method | yes | string | Possible values: - cod - paid |
| amount | yes | Double | Total value amount of the order |
| amount_due | yes | Double | Total due amount of the order. If order paid amount_due will be 0. Otherwise equal to amount. |
| currency | yes | String | Currency code of the order currency |
| shippingAmount | no | Double | shipping amount of this order |
| subtotal | no | Double | Subtotal of the order |
| shippingNotes | no | String | Notes of customer for shipping. I.e don’t ring the bell. |
| packageSize | no | String | Used for specifiying the maximum package size. Possible values smalbox |
| packageCount | no | Integer | States how many package in the order |
| packageWeight | no | Double | Total weight of the order |
| boxWidth | conditional | Double | width of the package, it is needed to use Aggregator shipping options |
| boxLength | conditional | Double | length of the package, it is needed to use Aggregator shipping options |
| boxHeight | conditional | Double | height of the package, it is needed to use Aggregator shipping options |
| deliverySlotDate | no | Date | Prefered Delivery date |
| deliverySlotFrom | no | String | “From” time for delivery time |
| deliverySlotTo | no | String | “To” time for delivery time |
| orderDate | no | DateTime | Date of the order |
| senderName | no | String | Sender name |
| customer | yes | Object | Customer Data |
| items | yes | Array | Items data |
| couponCode | no | text | Discount or special offer code. |
| codFee | no | Double | COD Fee |
| brandId | no | Long | Brand (Client Store) ID |
| whoPays | no | String | If implemented, annotates who wil pay for the shipment. Possible values: marketplacePaysDeliveryFee, sellerPaysDeliveryFee |
Example Request Body
Here is an example of a request body for creating an order:
POST /rest/v2/createOrder HTTP/1.1 Host: api.tryoto.com Accept: application/json Content-Length: 2585 { "orderId": "orderId", "createShipment": false, "payment_method": "paid", "amount": 100, "amount_due": 0, "brandId": 1233, "customsValue": "12", "customsCurrency": "USD", "shippingAmount": 20, "subtotal": 100, "currency": "SAR", "shippingNotes": "be careful. it is fragile", "packageSize": "small", "packageCount": 2, "packageWeight": 1, "boxWidth": 10, "boxLength": 10, "boxHeight": 10, "orderDate": "30/12/2020 15:45", "deliverySlotDate": "31/12/2020", "deliverySlotTo": "12pm", "deliverySlotFrom": "2:30pm", "senderName": "Sender Company", "senderInformation": { "senderAddressName": "Home - John Doe", "senderId": "123452", "senderFullName": "John Doe", "senderMobile": "905055055555", "senderEmail": "test@example.com", "senderCountry": "SA", "senderCity": "Riyadh", "senderBuildingNo": "3474", "senderPostcode": "12221", "senderStreet": "Abi Almahd", "senderDistrict": "Al Olaya", "senderSecondaryAddressNumber": "7026", "senderAddressLine": "3474, Abi Almahd, 7026, Al Olaya, 12221, Riyadh, Kingdom of Saudi Arabia", "senderShortAddressCode": "RHOD3474", "lat": "24.725785977255285", "lon": "46.659947654084974" }, "customer": { "name": "fatmanur yavuz", "email": "test@test.com", "mobile": "546607389", "address": "8089, Salam Ibn Salim, 4314, Al Mughaisilah Dist., 42315, Madinah, Kingdom of Saudi Arabia", "district": "Al Mughaisilah Dist.", "city": "Madinah", "buildingNo": "8089", "street": "Salam Ibn Salim", "secondaryAddressNumber": "4314", "shortAddressCode": "DMAJ8089", "country": "SA", "postcode": "42315", "lat": "24.467495523755485", "lon": "39.63732070540998", "refID": "1000012", "W3WAddress": "alarmed.cards.stuffy" }, "items": [ { "productId": 112, "name": "test product", "price": 100, "rowTotal": 100, "taxAmount": 15, "quantity": 1, "serialnumber": "ASD12312121333", "sku": "test-product", "image": "http://...." }, { "name": "test product 2", "price": 100, "rowTotal": 100, "taxAmount": 15, "quantity": 1, "sku": "test-product-2", "image": "http://...." } ] }
Step 4: Make the API Call
- Use the following cURL command to send the request:
curl --location 'https://api.tryoto.com/rest/v2/createOrder' \ --header 'Accept: application/json' \ --data-raw '{ "orderId": "12347772", "ref1": "1234ABCDE", "deliveryOptionId": "12364", "serviceType": "", "createShipment": false, "storeName": "Brand A English", "payment_method": "paid", "amount": 100, "amount_due": 0, "customsValue":"12", "customsCurrency":"USD", "shippingAmount":20, "subtotal":100, "currency": "SAR", "shippingNotes": "be careful. it is fragile", "packageSize": "small", "packageCount": 2, "packageWeight": 1, "boxWidth": 10, "boxLength": 10, "boxHeight": 10, "orderDate": "30/12/2020 15:45", "deliverySlotDate": "31/12/2020", "deliverySlotTo": "12pm", "deliverySlotFrom": "2:30pm", "senderName":"Sender Company", "senderInformation":{ "senderAddressName":"Home - John Doe", "senderId":"123452", "senderFullName":"John Doe", "senderMobile":"905055055555", "senderEmail":"test@example.com", "senderCountry":"SA", "senderCity":"Riyadh", "senderPostcode":"11564", "senderAddressLine":"الفرعي،، الطريق الدائري الجنوبي حي العزيزية،, Riyadh 11564, Saudi Arabia", "lat":"24.7310685013539", "lon":"46.70160835803429" }, "customer": { "name": "عبدالله الغامدي", "email": "test@test.com", "mobile": "546607389", "address": "6832, Abruq AR Rughamah District, Jeddah 22272 3330, Saudi Arabia", "district": "", "city": "Jeddah", "country": "SA", "postcode": "12345", "lat": "40.706333", "lon": "29.888211", "refID":"1000012", "W3WAddress":"alarmed.cards.stuffy" }, "items": [ { "productId": 112, "name": "test product", "price": 100, "rowTotal": 100, "taxAmount": 15, "quantity": 1, "serialnumber": "ASD12312121333", "sku": "test-product", "image": "http://...." }, { "name": "test product 2", "price": 100, "rowTotal": 100, "taxAmount": 15, "quantity": 1, "sku": "test-product-2", "image": "http://...." } ] }'
Step 5: Handle the Response
- A successful response will look like this:
{ "success": true, "otoId": 540789 }
The otoId returned in the above response is a unique internal identifier for the order in OTO's database, it is different from the Order ID used in the order payload.As part of the Saudi government regarding the national address, OTO now support boths the National Address and the Short Address Code, as required by TGA on API