How to Create an Order

Modified on Sat, 1 Feb at 8:46 PM

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/createOrder
This 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:

{
    "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 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.