> ## 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.

# Core concepts: orders, shipments, stock and hubs

> The terms that carry most of OTO and how they relate: orders and shipments, the two stock numbers, hubs, identifiers, money, rules and user access.

A dozen words carry most of OTO. Several of them mean something more specific than they sound, and a few appear under two different names depending on whether you are looking at a screen or an API response. This page is the reference for both.

## Order and shipment are not the same thing

This is the distinction everything else rests on, and the one that most often trips people up.

| Term | What it is |
| - | - |
| **Order** | What the customer bought. It arrives from a [sales channel](https://docs.tryoto.com/modules/sales-channels/overview.md) or the API, and it exists whether or not anything has been shipped. |
| **Shipment** | The booking with a carrier to move goods. Created *from* an order, and carrying the tracking number and the AWB. |
| **Box** | One physical parcel. A shipment can have several, each with its own barcode and weight. |

> [!TIP]
>
> **One order is not necessarily one parcel**
>
> An order can be split across locations, shipped on more than one carrier, packed into several boxes, and returned in pieces. Each of those is a separate shipment or box against the same order.
>
> Which is why status questions have to name their subject. “Is it delivered?” is ambiguous for an order in three boxes; it is precise for a shipment.

## The same thing, under two names

Some objects are called one thing in the interface and another in the API or in older material. These are the ones worth knowing.

| In the dashboard | In the API and rules | What it is |
| - | - | - |
| **Warehouse** / **Branch** | **Pickup location** — `createPickupLocation`, with `type` of `warehouse` or `branch` | A place you hold stock and can ship from. The docs call both a **hub**. See [Hubs Management](https://docs.tryoto.com/modules/hubs-management/overview.md). |
| **Shipping partner** / **Carrier** | **Delivery company**, abbreviated **DC** — `dcList`, `dcActivation`, `deliveryCompany` | The company that carries the parcel. |
| **Service** | **Delivery option** — `deliveryOptionName` | One named service from a carrier, such as *Aramex Same Day*. This, not the carrier, is what a shipping rule selects. |
| **Customer notifications** | SMS, email and WhatsApp settings | Messages to *your customer*. Distinct from [notifications](https://docs.tryoto.com/platform/collaboration-and-notifications.md), which go to *your staff*. |

## Stock is two numbers, not one

Inventory carries **Available** and **On Hand**, and they move at different moments.

| Figure | What it means | Falls when |
| - | - | - |
| **Available** | What can still be promised to a customer. | The order is **assigned to a pickup location** — the stock is now reserved for it. |
| **On Hand** | What is physically in the building. | The goods actually leave, at fulfillment. |

> [!NOTE]
>
> **The gap between the two numbers is reserved stock**
>
> Between assignment and dispatch, an item is spoken for but has not moved. Available has dropped; On Hand has not. One order produces two separate movements, sometimes days apart.
>
> This is why a stock count that matches On Hand can still look wrong against Available, and why the right question is not “how much do we have” but “how much can we still sell”. See [Inventory tracking](https://docs.tryoto.com/modules/inventory-management/inventory-tracking.md).

## Places

| | |
| - | - |
| **Hub** | Anywhere you hold stock and can ship from — a warehouse, a shop, or a third party's site. One object, three configurations. |
| **Serving radius** | How far a hub will deliver, in kilometers. |
| **Preparation SLA** | How long that hub takes to get an order ready, in hours. With serving radius, one of the two fields [routing](https://docs.tryoto.com/modules/omnichannel-oms/order-routing.md) actually weighs. |
| **Area** | A delivery zone, drawn geographically and attached to hubs and rules. |
| **City group** | Several cities under one name, so a rule can name them together. |

## Inside a warehouse

| | |
| - | - |
| **Bin** | A specific location on a shelf. Carries a type, a capacity and sometimes a preferred SKU. |
| **Zone** | A group of bins, usually an aisle or an area, worked by one picker. |
| **Wave** | A batch of orders released to the floor together, so one walk serves many orders. |
| **Putaway** | Moving received goods into their bins. |
| **Dispatching unit** | A trolley, cage or pallet that groups packed parcels for one carrier's collection. |

All of these live in [Warehouse Management](https://docs.tryoto.com/modules/warehouse-management/overview.md) and are configured per hub.

## Your own fleet

| | |
| - | - |
| **Driver** | Someone on your own fleet, working in the [OTO FLEX](https://docs.tryoto.com/modules/oto-flex/overview.md) app. A user type in its own right. |
| **Route** | An ordered set of stops assigned to one driver. |
| **Task** | One stop on a route — a pickup or a delivery. |
| **Proof of pickup / delivery** | What the driver must capture to close a task: a photo, a code, a barcode, or a combination. |

## Identifiers

| Identifier | What it identifies |
| - | - |
| **SKU** | A product. The join between OTO and every other system you run. |
| **Hub code** | A place. The join for anything site-shaped — ERP plants, POS stores, channel locations. |
| **AWB** | Air waybill: the carrier's shipping label and its tracking reference. |
| **Tracking number** | The carrier's own reference for the parcel. Distinct from your order number. |

### Order numbers

Every order carries **two** identifiers, and they do different jobs.

| Identifier | What it is |
| - | - |
| **OTO ID** — `otoId` | OTO’s own internal reference. Unique across the platform, and never reused. |
| **Order number** — `incrementId` | The number people use: your team, your customer, your channel. This is the one on the label and in the tracking message. |

#### Where the order number comes from

| How the order arrived | Its number |
| - | - |
| **Synced from a sales channel** | **Unchanged.** A Shopify order keeps its Shopify number, a Salla order its Salla number. OTO does not renumber it. |
| **Created through the API** | Yours, if you supply one. Leave it blank and OTO generates one. |
| **Created by hand in OTO** | Generated, in the form `OID-…`. The **Order Number** field on **Add Order** reads *“leave blank to auto-generate”*, so you can type your own instead. |

> [!TIP]
>
> **Channel orders keeping their own number is the important part**
>
> When a customer emails about order `#1043`, that is the number on their confirmation from your storefront. Because OTO did not renumber it, it is also the number your agent searches, the number on the AWB, and the number in the tracking message.
>
> The alternative — a fulfillment system that assigns its own numbers — means every customer conversation needs a translation and every reconciliation against the channel needs a mapping table. `OID-` appears only where there was no channel number to keep.

#### Prefixes and suffixes

Related records are built *from* the order number rather than getting identities of their own — whatever that number happens to be.

| | |
| - | - |
| `…-R1` | A return against that order. `-R2` for a second return request against the same one. |
| `TR-…` · `IDT-…` | A transfer between your own locations. `IDT-` marks an inter-depot transfer built over an existing order, so the original number sits inside it. |

> [!NOTE]
>
> **The suffix carries information worth reading**
>
> Because a return is numbered from its order, it matches to the original sale without anyone looking anything up — and an order carrying `-R2` has been returned against twice, which is a pattern worth noticing on a customer or a product. See [Return Management](https://docs.tryoto.com/modules/return-management/overview.md).
>
> If a prefix in OTO does not suit a downstream system, webhook registration accepts an **orderPrefix** to strip before the payload is sent. See [Webhook events](https://docs.tryoto.com/developers/webhook-events.md).

## Money

| | |
| - | - |
| **COD** | Cash on delivery. The carrier collects payment from the customer at the door and remits it to you. Normal in this region rather than an edge case. |
| **COD ceiling** | The maximum order value a given carrier will collect in cash. |
| **Chargeable weight** | What a carrier actually bills for — the greater of actual weight and volumetric weight. Known as **Desi** in Türkiye. |
| **Surcharge** | A charge a carrier adds after the fact, usually when the parcel turns out heavier or larger than declared. See [invoice reconciliation](https://docs.tryoto.com/modules/shipping-management/shipping-invoices-reconciliation.md). |

> [!WARNING]
>
> **Volumetric weight is where shipping bills surprise people**
>
> A large, light parcel is billed on the space it occupies rather than what it weighs. Declare a pillow at its actual weight and the carrier will bill it at several times that.
>
> The difference arrives weeks later as a surcharge on an invoice, long after the order was priced — which is why the reconciliation exists, and why declared dimensions are worth getting right at packing rather than at invoicing.

## Rules and automation

| | |
| - | - |
| **Condition** | A test against an order — its value, weight, destination, brand, tags and much else. |
| **Rule** | Conditions plus what to do when they match. Evaluated in order. |
| **Feasibility** | Whether a carrier is *eligible* at all. Checked before selection, so a rule can match an order and still find no carrier available. |
| **Order OTOmation** | Rules that act on orders — routing, holds, splits. See [Order routing](https://docs.tryoto.com/modules/omnichannel-oms/order-routing.md). |
| **Shipping automation** | Rules that choose a carrier. See [Shipping automation](https://docs.tryoto.com/modules/shipping-management/shipping-automation.md). |

## Identity and access

| | |
| - | - |
| **Brand** | A trading identity within one account — its own logo, sender name and message templates. One business can run several. |
| **User type** | What kind of account a person has: Company Admin, Warehouse User, Branch User, Driver User, Customer Service User, Brand Manager User. |
| **Role template** | A named set of permissions applied to people. See [Users, roles & permissions](https://docs.tryoto.com/platform/users-roles-and-permissions.md). |

## Where to go next

> **[What is OTO](https://docs.tryoto.com/get-started/what-is-oto.md)**
>
> The platform in one page.

> **[Omnichannel OMS](https://docs.tryoto.com/modules/omnichannel-oms/overview.md)**
>
> Where an order lives.

> **[Developers](https://docs.tryoto.com/developers/overview.md)**
>
> The same objects, as an API.


## Related topics

- [What is OTO](https://docs.tryoto.com/get-started/what-is-oto.md)
- [Platform architecture](https://docs.tryoto.com/get-started/architecture.md)
- [Glossary of OTO terms](https://docs.tryoto.com/get-started/glossary.md)


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