Core concepts: orders, shipments, stock and hubs

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

One order is not necessarily one parcelAn 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.
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, 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.

The gap between the two numbers is reserved stockBetween 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.

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 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 and are configured per hub.

Your own fleet


Driver	Someone on your own fleet, working in the OTO FLEX 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.

Channel orders keeping their own number is the important partWhen 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.

The suffix carries information worth readingBecause 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.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.

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.

Volumetric weight is where shipping bills surprise peopleA 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.
Shipping automation	Rules that choose a carrier. See Shipping automation.

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.

Where to go next

What is OTO

The platform in one page.

Omnichannel OMS

Where an order lives.

Developers

The same objects, as an API.

Get started

Modules

Integrations

Developers

Platform

Pricing

Core concepts: orders, shipments, stock and hubs

Order and shipment are not the same thing

The same thing, under two names

Stock is two numbers, not one

Places

Inside a warehouse

Your own fleet

Identifiers

Order numbers

Where the order number comes from

Prefixes and suffixes

Money

Rules and automation

Identity and access

Where to go next

What is OTO

Omnichannel OMS

Developers

​Order and shipment are not the same thing

​The same thing, under two names

​Stock is two numbers, not one

​Places

​Inside a warehouse

​Your own fleet

​Identifiers

​Order numbers

​Where the order number comes from

​Prefixes and suffixes

​Money

​Rules and automation

​Identity and access

​Where to go next

What is OTO

Omnichannel OMS

Developers

Order and shipment are not the same thing

The same thing, under two names

Stock is two numbers, not one

Places

Inside a warehouse

Your own fleet

Identifiers

Order numbers

Where the order number comes from

Prefixes and suffixes

Money

Rules and automation

Identity and access

Where to go next