Orders APIs

Modified on Wed, 1 Oct at 8:41 PM

Create Order

Endpoint URL

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

Example Request Body

Here is an example of a request body:

{
  "orderId": "1234",
  "pickupLocationCode": "jdd_wh",
  "createShipment": "true",
  "deliveryOptionId": 564,
  "payment_method": "paid",
  "amount": 100,
  "amount_due": 0,
  "currency": "SAR",
  "customsValue": "12",
  "customsCurrency": "USD",
  "packageCount": 2,
  "packageWeight": 1,
  "boxWidth": 10,
  "boxLength": 10,
  "boxHeight": 10,
  "orderDate": "31/12/2022 15:45",
  "deliverySlotDate": "31/12/2020",
  "deliverySlotTo": "12pm",
  "deliverySlotFrom": "2:30pm",
  "senderName": "Sender Company",
  "customer": {
    "name": "\u0639\u0628\u062f\u0627\u0644\u0644\u0647 \u0627\u0644\u063a\u0627\u0645\u062f\u064a",
    "email": "test@test.com",
    "mobile": "546607389",
    "address": "6832, Abruq AR Rughamah District, Jeddah 22272 3330, Saudi Arabia",
    "district": "Al Hamra",
    "city": "Jeddah",
    "country": "SA",
    "postcode": "12345",
    "lat": "40.706333",
    "lon": "29.888211",
    "refID": "1000012"
  },
  "items": [
    {
      "productId": 112,
      "name": "test product",
      "price": 100,
      "rowTotal": 100,
      "taxAmount": 15,
      "quantity": 1,
      "sku": "test-product",
      "image": "http://...."
    },
    {
      "name": "test product 2",
      "price": 100,
      "quantity": 1,
      "sku": "test-product-2"
    }
  ]
}

Request Parameters

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.
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
pickingType	no	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.
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
senderInformation	no	object	Sender Data
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
Name	Required	Type	Description
senderAddressName	no	string	Name of the sender address
senderId	yes	string	Id of the sender
senderFullName	yes	string	Full name of the sender
senderMobile	yes	string	Mobile number of sender
senderEmail	no	string	In format of [test@example.com](https://mailto:test@example.com)
senderCountry	yes	string	Country ISO2 code "SA","AE" etc.
senderState	no	string	State name of the sender
senderCity	yes	string	City name of the sender
senderDistrict	no	string	District name of the sender
senderPostcode	no	string	Postal code of the sender's address
senderAdressLine	yes	string	Detailed address of the sender
lat	no	number	Latitude, \*if not exist orders may not assigned to pickupLocations automatically
lon	no	number	Longitude, \* if not exist orders may not assigned to pickupLocations automatically
Name	Required	Type	Description
name	yes	string	Customer full name
email	no	string	Customer email address
mobile	yes	string	Mobile number of the customer
address	yes	string	Address of the customer
district	no	string	District or area name
city	yes	string	City name
state	no	string	State name
country	yes	string	Possible values can be _SA_,_EG_,_UAE_,_BHR_,_KWT_
shortAddressCode	no	string	A simplified version of the traditional address transformed into a unique code. It consists of 4 letters (e.g., RAGI) assigned based on postal codes and 4 digits representing the building number (e.g., 2929).
postcode	no	string	postal code of address
street	no	string	Street of the customer
lat	no	double	Latitude
lon	no	double	Longitude
refID	no	string	exp. customerId of ecommerce
W3WAddress	no	string	if you want to define the address with using [what3words.com](https://what3words.com/clear.clear.clear) you can use this option
Name	Required	Type	Description
productId	no	long	Id of the product
name	yes	string	Name of the product
price	yes	double	Unit price of the product
rowTotal	no	double	total amount of this line item
taxAmount	no	double	tax amount of this line item
quantity	yes	double	Quantity purchased
serialnumber	no	string	Serial number of the product
sku	yes	string	SKU number of the product
image	no	string	Http link of the product main photo
hsCode	no	string	a standardized numerical method of classifying traded products
itemOrigin	no	string	Origin of the item

Available Packages: All Packages

This API endpoint is a critical component in e commerce and logistics systems, enabling external applications to initiate and manage new orders seamlessly. This endpoint allows you to submit order details, such as customer information, product data, shipping preferences, and payment methods.

Request Parameters: |

Request Parameters for Sender Information Data |

Request Parameters for Customer Data |

Request Parameters for Items Data |

Update Order

Endpoint URL

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

Example Request Body

Here is an example of a request body:

{
  "orderId": "202111081227",
  "ref1": "1234ABCDE",
  "pickupLocationCode": "12364",
  "deliveryOptionId": "12364",
  "storeName": "Brand A English",
  "payment_method": "paid",
  "amount": 100,
  "amount_due": 0,
  "shippingAmount": 20,
  "subtotal": 100,
  "currency": "SAR",
  "customsValue": "12",
  "customsCurrency": "USD",
  "shippingNotes": "be careful. it is fragile",
  "packageSize": "small",
  "packageCount": 2,
  "packageWeight": 1,
  "boxWidth": 10,
  "boxLength": 10,
  "boxHeight": 10,
  "orderDate": "30/12/2022 15:45",
  "deliverySlotDate": "31/12/2022",
  "deliverySlotTo": "12pm",
  "deliverySlotFrom": "2:30pm",
  "customer": {
    "name": "\u0639\u0628\u062f\u0627\u0644\u0644\u0647 \u0627\u0644\u063a\u0627\u0645\u062f\u064a",
    "email": "test@test.com",
    "mobile": "546607389",
    "address": "6832, Abruq AR Rughamah District, Jeddah 22272 3330, Saudi Arabia",
    "district": "Al Hamra",
    "city": "Riyadh",
    "country": "SA",
    "postcode": "12345",
    "lat": "40.706333",
    "lon": "29.888211",
    "refID": "1000012",
    "W3WAddress": "alarmed.cards.stuffy"
  },
  "items": [
    {
      "productId": 112,
      "name": "test product",
      "price": 100,
      "quantity": 1,
      "sku": "test-product",
      "image": "http://...."
    },
    {
      "name": "test product 2",
      "price": 100,
      "quantity": 1,
      "sku": "test-product-2",
      "image": "http://...."
    }
  ]
}

Available Packages: All Packages

This API endpoint allows you update order info with this endpoint before shipment creation. If you created a shipment and need to update an information after that you have to cancel the shipment first then you can update.

Update Order Status

Endpoint URL

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

Example Request Body

Here is an example of a request body:

{
  "orderIds": [
    30846946
  ],
  "status": "delivered",
  "date": "2024-08-06T21:00:00.000Z",
  "description": "aaaaaa"
}

Request Parameters

Name	Required	Type	Description
orderIds	yes	string	Id of the order/s
status	yes	string	status of the shipment(delivered, returned, pickedUp)
description	no	string	description of the status change
date	no	date	the delivery date of the order

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

This API endpoint allows you to modify the current status of an order within the system.

You can update the order status to "delivered," "returned," or "picked up" if the order does not have an associated shipment. However, if a shipment exists, only statuses for integrator managed shipments can be updated.

Request Parameters: |

Cancel Order

Endpoint URL

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

Example Request Body

Here is an example of a request body:

{
  "orderId": "1234"
}

Request Parameters

Name	Required	Type	Description
orderId	yes	string	orderId from which you want to cancel.

Available Packages: All Packages This API endpoint allows users to cancel an existing order under specific conditions. It ensures smooth and efficient handling of cancellations while maintaining the integrity of related processes.

Important Note: If the order has an associated shipment, it cannot be canceled via this endpoint. Shipment related restrictions ensure the system prevents conflicts or inconsistencies in ongoing fulfillment processes.

Request Parameters: |

Get Orders

Endpoint URL

GET https://api.tryoto.com/rest/v2/orders?perPage=2&page=2&status=delivered

Request Parameters

Name	Required	Type	Description
perPage	no	number	Order count in the response. Max limit 100
page	no	number	Pagination number. You can iterate this field to get all items.
minDate	no	date	Starting "Order Creation Date" of your orders in "yyyy-mm-dd" format.
maxDate	no	date	Ending "Order Creation Date" of your orders in "yyyy-mm-dd" format.
status	no	string	Status of the orders.

Available Packages: All Packages

This API endpoint is designed to provide a comprehensive overview of orders in your system. This endpoint returns detailed information about each order, including pickup locations, order IDs, item details, and current statuses. It enables seamless tracking and management of orders, ensuring better visibility and control.

Request Parameters: |

Get Order Details

Endpoint URL

GET https://api.tryoto.com/rest/v2/orderDetails

Request Parameters

Name	Required	Type	Description
orderId	yes	string	Id of the Order

Available Packages: All Packages

This API endpoint provides detailed information about a specific order. By using this endpoint, you can retrieve comprehensive data about an order including status updates.

Request Parameters: |

Hold Order

Endpoint URL

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

Example Request Body

Here is an example of a request body:

{
  "orderId": "OID-20980-1146",
  "onHoldReason": "Fraud",
  "onHoldReasonLang": "en"
}

Request Parameters

Name	Required	Type	Description
orderId	yes	string	Id of the order that you will place on hold.
onHoldReason	yes	string	Reason for being an order on hold.
onHoldReasonLang	yes	string	Values can be: eng, tr, ar.

Available Packages: All Packages

This API endpoint allows you to place an order on hold, temporarily pausing its processing. This is useful for scenarios such as payment verification, inventory issues, or customer requests.

Request Parameters: |

Unhold Order

Endpoint URL

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

Example Request Body

Here is an example of a request body:

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

Request Parameters

Name	Required	Type	Description
orderId	yes	string	The orderId you want to unhold.

Available Packages: All Packages

This API endpoint allows users to release orders that are currently on hold. This endpoint is designed to resume the processing of held orders, making them available for fulfillment or further actions in the order management workflow.

Request Parameters: |