> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryoto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API reference

> All 76 OTO REST API endpoints in 20 groups, with what each one does and the lowest plan that includes it. Full schemas are on apis.tryoto.com.

Every endpoint on the platform, what it is for, and the lowest plan that includes it. Request and response schemas live on [apis.tryoto.com](https://apis.tryoto.com), which is generated from the collection itself and is always current.

> [!NOTE]
>
> **How to read the plan column**
>
> The pill names the **lowest** plan that includes the endpoint, so Starter+ means Starter, Scale, Pro and Enterprise. Notes beside it are additional conditions — an add-on, a quota, or a restriction on what the endpoint will accept.
>
> Base URL for all of them: `https://api.tryoto.com`. Every call needs `Authorization: Bearer <access_token>` — see [Authentication](https://docs.tryoto.com/developers/authentication.md).

**76 endpoints** in **20 groups**.

### Authorization

| Endpoint | Path | Plan |
| - | - | - |
| **Refresh Token** Exchange your permanent refresh token for a one-hour access token. | `POST` `/rest/v2/refreshToken` | Free+ |
| **Health Check** Is the platform up. No auth required in practice; useful as a connectivity probe. | `GET` `/rest/v2/healthCheck` | Free+ |

### Account

| Endpoint | Path | Plan |
| - | - | - |
| **Account Info** Your account's profile and current balance. | `GET` `/rest/v2/accountInfo` | Free+ |
| **Buy Credit** Top up the shipping wallet. | `POST` `/rest/v2/buyCredit` | Free+ |
| **Request Mobile Verification** Send a verification code to a mobile number. | `POST` `/rest/v2/requestMobileVerification` | Free+ |
| **Verify Mobile Number** Confirm the code. Added for marketplace sub-accounts, March 2026. | `POST` `/rest/v2/verifyMobileNumber` | Free+ |

### Transactions

| Endpoint | Path | Plan |
| - | - | - |
| **Get Shipping Price Transactions List** What each shipment was charged, with the price row that produced it. | `POST` `/rest/v2/getShippingPriceTransactionsList` | Starter+ |
| **Credit Transactions** Wallet movements. | `GET` `/rest/v2/creditTransactions` | Free+ |
| **Shipment Transactions** Shipment-level charges, filterable by date and order. | `GET` `/rest/v2/shipmentTransactions` | Free+ |
| **COD Transactions** COD wallet balance, upcoming transfers, withdrawals and history. Added September 2026. | `GET` `/rest/v2/codTransactions` | Free+ |

### Marketplace

| Endpoint | Path | Plan |
| - | - | - |
| **Register** Create a seller sub-account under a marketplace master account. | `POST` `/rest/v2/marketplace/register` | Free+ *marketplace token required* |
| **Client Info** Update a sub-account's details. | `POST` `/rest/v2/marketplace/clientInfo` | Free+ *marketplace token required* |
| **Client Info** Read a sub-account's details. | `GET` `/rest/v2/marketplace/clientInfo` | Free+ *marketplace token required* |

### Orders

| Endpoint | Path | Plan |
| - | - | - |
| **Create Order** The entry point. Customer, address, items, payment method. | `POST` `/rest/v2/createOrder` | Free+ |
| **Update Order** Change an order before a shipment exists for it. | `POST` `/rest/v2/updateOrder` | Free+ |
| **Update Order Status** Force a status — delivered, returned, pickedUp — from your own system. | `POST` `/rest/v2/updateOrderStatus` | Scale+ |
| **Cancel Order** Cancel before shipping. | `POST` `/rest/v2/cancelOrder` | Free+ |
| **Get Orders** Paginated, filterable list. | `GET` `/rest/v2/orders` | Free+ |
| **Hold Order** Park an order without cancelling it. | `POST` `/rest/v2/holdOrder` | Free+ |
| **Unhold Order** Release it back into the queue. | `POST` `/rest/v2/unHoldOrder` | Free+ |
| **Get Order Details** Everything held against one order. | `GET` `/rest/v2/orderDetails` | Free+ |
| **Check Order Availability** Can this order be fulfilled, and from where, before you commit to it. | `POST` `/rest/v2/checkOrderAvailability` | Pro+ |

### Shipping Prices

| Endpoint | Path | Plan |
| - | - | - |
| **Check OTO Delivery Fee** Rates, delivery estimates and cut-off times for a prospective parcel. This is the checkout endpoint. | `POST` `/rest/v2/checkOTODeliveryFee` | Free+ |
| **Check Delivery Fee** Rates against your own negotiated carrier contracts. | `POST` `/rest/v2/checkDeliveryFee` | Starter+ |
| **Get Delivery Fee** Fee for an order that already exists. | `POST` `/rest/v2/getDeliveryFee` | Free+ |
| **Get Delivery Options** The delivery options configured on your account. | `GET` `/rest/v2/getDeliveryOptions` | Starter+ |

### Shipments

| Endpoint | Path | Plan |
| - | - | - |
| **Create Shipment** Book the parcel with a carrier. Takes a deliveryOptionId, or picks for you. | `POST` `/rest/v2/createShipment` | Free+ |
| **Cancel Shipment** Cancel with the carrier. | `POST` `/rest/v2/cancelShipment` | Free+ |

### Return Shipments

| Endpoint | Path | Plan |
| - | - | - |
| **Create Return Shipment** Book the reverse leg. | `POST` `/rest/v2/createReturnShipment` | Free+ |
| **Get Return Link** A customer-facing return portal link for one order. | `POST` `/rest/v2/getReturnLink` | Starter+ |
| **Get Return Details** State of a return. | `POST` `/rest/v2/getReturnDetails` | Free+ |
| **Trigger Return SMS** Send the customer the return link by SMS. | `POST` `/rest/v2/triggerReturnSms` | Starter+ |

### Print

| Endpoint | Path | Plan |
| - | - | - |
| **Print AWB** The air waybill for an order. | `GET` `/rest/v2/print/orderId` | Free+ |
| **Print Label** An order's documents: AWB, proforma, order details or return document. | `POST` `/rest/v2/printLabel` | Free+ *not in the plan matrix* |

### Tracking

| Endpoint | Path | Plan |
| - | - | - |
| **Order Tracking** Current status of an order. | `POST` `/rest/v2/orderStatus` | Free+ |
| **Order History** The full event trail, normalized across carriers. | `POST` `/rest/v2/orderHistory` | Free+ |
| **Track Shipment** Carrier-level shipment tracking. | `POST` `/rest/v2/trackShipment` | Enterprise+ |

### Customer Notifications

| Endpoint | Path | Plan |
| - | - | - |
| **Customer Notifications** Which messages were sent to the customer for an order, and what happened to them. | `GET` `/rest/v2/orders/{orderId}/customer-notifications` | Scale+ |

### Carrier Integrations

| Endpoint | Path | Plan |
| - | - | - |
| **Get Delivery Estimation** Expected delivery window for a lane. | `POST` `/rest/v2/getDeliveryEstimation` | Scale+ |
| **AI Estimated Delivery Dates** Model-predicted delivery dates, rather than the carrier's stated service level. | `POST` `/rest/v2/aiEstimatedDeliveryDates` | Scale+ |
| **Check Coverage** Will anyone deliver to this destination. | `POST` `/rest/v2/checkCoverage` | Starter+ |
| **Available Cities** Cities your active carriers cover. | `POST` `/rest/v2/availableCities` | Free+ |
| **Available Time Slots** Bookable delivery windows. | `POST` `/rest/v2/availableTimeslots` | Starter+ |
| **DC List** The carrier catalog. | `POST` `/rest/v2/dcList` | Free+ |
| **DC Config** The credential template a given carrier needs. | `POST` `/rest/v2/dcConfig` | Starter+ |
| **DC Activation** Activate a carrier contract. | `POST` `/rest/v2/dcActivation` | Starter+ *3 / 7 / 20 / unlimited contracts by plan* |
| **Get Cities** City reference data. | `POST` `/rest/v2/getCities` | Free+ |
| **Check DC Branch List** Carrier drop-off branches and lockers. | `POST` `/rest/v2/checkDCBranchList` | Free+ |

### Pickup Locations

| Endpoint | Path | Plan |
| - | - | - |
| **Create Pickup Location** Create a hub. Carries the national-address fields, servingRadius and preparationSla. | `POST` `/rest/v2/createPickupLocation` | Free+ *branch type is Enterprise only* |
| **Update Pickup Location** Change one. | `POST` `/rest/v2/updatePickupLocation` | Free+ *branch type is Enterprise only* |
| **Get Pickup Location List** List them. | `GET` `/rest/v2/getPickupLocationList` | Free+ *branch type is Enterprise only* |

### Brands

| Endpoint | Path | Plan |
| - | - | - |
| **Get List of Brands** Brands on the account. | `GET` `/rest/v2/getBrandList` | Starter+ |
| **Create Brand** Add one. | `POST` `/rest/v2/createBrand` | Starter+ |

### Sales Channels

| Endpoint | Path | Plan |
| - | - | - |
| **Sales Channels List** The catalog, with each channel's integration code. | `GET` `/rest/v2/salesChannel/getSalesChannelsList` | Free+ |
| **Sales Channel Config** The credential template for one channel. | `POST` `/rest/v2/salesChannel/getSalesChannelConfig` | Free+ |
| **Sales Channel Activation** Connect it. | `POST` `/rest/v2/salesChannel/salesChannelActivation` | Free+ *1 / 3 / 5 / unlimited channels by plan* |

### Products

| Endpoint | Path | Plan |
| - | - | - |
| **Create Product** Add a SKU. | `POST` `/rest/v2/createProduct` | Free+ |
| **Product List** List SKUs. | `POST` `/rest/v2/productList` | Free+ |
| **Add Box** Define a packaging box. | `POST` `/rest/v2/addBox` | Free+ |
| **Update Box** Change one. | `POST` `/rest/v2/updateBox` | Free+ |
| **Get Box** Read one. | `GET` `/rest/v2/getBox` | Free+ |

### Stock Management

| Endpoint | Path | Plan |
| - | - | - |
| **Update Stock Quantity** Set stock for a SKU at a location. | `POST` `/rest/v2/updateStockQuantity` | Starter+ *WMS add-on required* |
| **Check Inventory Stock** Stock at one location. | `GET` `/rest/v2/checkInventoryStock` | Starter+ *WMS add-on required* |
| **Check Global Stock** Stock across all locations. | `GET` `/rest/v2/checkGlobalStock` | Starter+ *WMS add-on required* |
| **Create Inventory Order** An inbound or transfer order. | `POST` `/rest/v2/createInventoryOrder` | Starter+ *WMS add-on required* |
| **Update Packing Status** Report packing progress from your own WMS. | `POST` `/rest/v2/updatePackingStatus` | Starter+ *WMS add-on required* |
| **Get Orders Ready For Packing** The pick-and-pack queue for one warehouse code. | `POST` `/rest/v2/getPackingOrders` | Starter+ *WMS add-on required* |
| **Check Available Stores For Pickup** Which branches hold the items and can hand them over. | `POST` `/rest/v2/availableStoresForPickup` | Starter+ *WMS add-on required* |
| **Available Cities For Pickup** Cities where click-and-collect is possible. | `POST` `/rest/v2/availableCitiesForPickup` | Starter+ *WMS add-on required · not in the plan matrix* |

### National Address

| Endpoint | Path | Plan |
| - | - | - |
| **Get National Address From Short Code** Expand a Saudi short address code into a full address. | `POST` `/rest/v2/getNationalAddressFromShortCode` | Free+ |

### Webhook

| Endpoint | Path | Plan |
| - | - | - |
| **Register a webhook** Subscribe a URL to an event type. | `POST` `/rest/v2/webhook` | Starter+ |
| **List webhooks** Your registered subscriptions. | `GET` `/rest/v2/webhook` | Starter+ |
| **Update a webhook** Change one in place, by id. | `PUT` `/rest/v2/webhook` | Starter+ |
| **Delete a webhook** Remove one. | `DELETE` `/rest/v2/webhook` | Starter+ |

### OTO FLEX

| Endpoint | Path | Plan |
| - | - | - |
| **Assign Driver** Put an order on one of your own drivers. | `POST` `/rest/v2/assignDriver` | Starter+ |
| **Track Driver** Where that driver is. | `POST` `/rest/v2/trackDriver` | Starter+ |

## Related

* [Authentication](https://docs.tryoto.com/developers/authentication.md) — how to call any of these.
* [Webhooks](https://docs.tryoto.com/developers/webhook-events.md) — the events that come back.
* [apis.tryoto.com](https://apis.tryoto.com) — full schemas and runnable examples.


## Related topics

- [OTO API Postman collection](https://docs.tryoto.com/developers/postman-collection.md)
- [OTO API overview](https://docs.tryoto.com/developers/overview.md)
- [Plans, pricing and add-ons](https://docs.tryoto.com/pricing/plans-and-packaging.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.