> ## 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. # Order sync: how orders get into OTO > The four ways orders reach OTO, from automatic sync with your sales channels to manual entry and bulk upload, and how to re-sync a single order. > [!NOTE] > > **Where to find it:** Main → Integrations → Sales Channels — [Open in OTO ↗](https://app.tryoto.com/sales-channels) Order sync is how orders get into OTO. Most arrive on their own from a connected sales channel; the rest you create by hand or upload in bulk. Everything downstream — routing, fulfillment, shipping — starts here, so this is also where bad data does the most damage. ## The four ways an order arrives | Route | Use it when | | - | - | | **Connected sales channel** | The normal case. Orders flow in automatically from your store or marketplace. | | **Manual entry** | A phone order, a walk-in, a one-off replacement. | | **Bulk upload** | Migrating history, or a channel OTO doesn't integrate with yet. | | **API** | A custom storefront or an ERP that owns order creation. See [the REST API](https://docs.tryoto.com/developers/rest-api-reference.md). | ## Features 7 features in this function. ### Order sync from sales channels Connecting a channel is self-serve. **Main → Integrations → Sales Channels** opens a searchable catalog of every platform OTO integrates with; pick one and choose **Explore Channel** to start its connection flow. ![The All Channels catalog on the Sales Channels page](https://mintcdn.com/oto/ft-bRlLvOnJkbVoC/images/ordersync-1-all-channels.png?fit=max\&auto=format\&n=ft-bRlLvOnJkbVoC\&q=85\&s=43e84f1b06936eba738b93a33a683c47) Fig. 1 — The catalog spans global storefront platforms, regional builders and marketplaces side by side — Shopify, Salla, WooCommerce, Zid, Adobe Commerce, OpenCart, BigCommerce, Sylius and Ikas through to Makane, Shahbandr, 3S Cart, Matjrah, T-Soft and KMK, alongside Noon, Jumia, Jahez and Fooder. Once connected, a channel appears under **Connected Channels** with its store name, an **Active** or **Inactive** badge, and a toggle to switch it on or off without disconnecting it. Each channel's **⋯** menu is where everything about that connection is managed. ![The Connected Channels tab with a channel's action menu open](https://mintcdn.com/oto/YkJay8Y-1RDv8ciw/images/ordersync-2-connected-channels.png?fit=max\&auto=format\&n=YkJay8Y-1RDv8ciw\&q=85\&s=dde45a46c5f20af8d771118ff256c343) Fig. 2 — Per channel: Edit Credentials, Match Pickup Locations, Inventory Sync Settings, Sync Orders, Synchronize Products, Status Mapping and Remove. The Active/Inactive toggle pauses a channel without losing its configuration. | Action | What it's for | | - | - | | **Edit Credentials** | Re-authenticate after a token expires or a password changes. | | **Match Pickup Locations** | Map the channel's own locations onto your OTO warehouses and branches, so routing knows where a channel order should come from. | | **Inventory Sync Settings** | Control how stock levels flow back to the channel — see [Inventory sync](https://docs.tryoto.com/modules/inventory-management/inventory-sync.md). | | **Sync Orders** | Pull orders from the channel on demand, for the whole connection. | | **Synchronize Products** | Re-import the catalog so SKUs and names match. | | **Status Mapping** | Decide what the channel is told as an order moves through OTO. | > [!NOTE] > > **Two different syncs** > > **Sync Orders** here pulls orders for an entire channel. **Synchronize Order**, further down this page, re-syncs one specific order. They are different actions in different places. ### Marketplace order sync Marketplaces behave differently from your own storefront: they own the customer relationship, impose their own SLA, and expect status to flow back on their terms. OTO treats them as first-class channels in the same catalog rather than a separate class of connector — **Noon**, **Jumia** and **Jahez** sit alongside the storefront platforms, and Amazon and Trendyol are integrated as well. Jahez is worth calling out as a different shape: orders are pulled into OTO, prepared there, then handed back to Jahez couriers for delivery. OTO runs fulfillment while the marketplace runs the last mile. ### Custom status mapping Every platform names its order states differently, and none of them match OTO's. **Status Mapping** is the translation table, configured per connected channel. Each row answers four questions: which **OTO Status** fires the update, what **Update Type** to send, which **Ecom Status** the channel should be set to, and what **Ecom Comment** to write alongside it. **Add New Row** adds a mapping; the bin icon removes one. ![The Status Mapping dialog for a connected channel](https://mintcdn.com/oto/ft-bRlLvOnJkbVoC/images/ordersync-3-status-mapping.png?fit=max\&auto=format\&n=ft-bRlLvOnJkbVoC\&q=85\&s=1c2313a320798e124e7aa2566ec3e593) Fig. 3 — A real mapping table. Shipment Processing sets the channel to executed, Collected to shipped, Out for Delivery to delivery, and the two return states to restoring and restored. Comments are templated — :deliveryCompany and the tracking number are substituted at send time. > [!TIP] > > **Comments carry the useful part** > > The Ecom Comment field accepts variables, so the message the customer sees on the storefront can name the carrier and tracking number: *"Shipped with :deliveryCompany"*. This is often more valuable than the status itself, because storefront status vocabularies are coarse. ### Conditional status-update triggers **Update Type** is what makes the mapping conditional rather than a blunt mirror. The same OTO status can push a different kind of update — an order comment, an order shipment record — and a status you don't map at all is simply never reported. That matters because pushing every internal transition to the storefront makes the order history unreadable and can trigger duplicate customer emails from the platform. Map the transitions the customer benefits from seeing, and leave the operational ones inside OTO. Note that one OTO status can appear on more than one row with different Update Types — in the mapping above, `Shipment Processing` sends both a comment and an Order Shipment record. ### Automatic retry on failed updates Channel APIs fail — rate limits, timeouts, brief outages. When an update to a sales channel doesn't land, OTO retries rather than dropping it, so a transient failure doesn't leave an order permanently showing the wrong status on the storefront. Failures and retries surface under **Settings → Logs → Integration Logs**, which is the first place to look when a channel's statuses drift out of step with OTO. ### Manual order entry From **Main → Shipping → Shipments**, choose **Add Order**. The form is two steps. **Step 1 — Receiver Details.** First name and phone number are required, along with country; last name and email are optional. The address can be entered three ways: type a **Short Address Code** (the Saudi National Address format, four letters and four numbers such as `RRRD2929`), fill the **Full Address Line** and its component fields by hand, or use **Fill from Map** to pick the point visually. ![Step 1 of Add Order — Receiver Details](https://mintcdn.com/oto/ft-bRlLvOnJkbVoC/images/ordersync-4-add-order-receiver.png?fit=max\&auto=format\&n=ft-bRlLvOnJkbVoC\&q=85\&s=6c91241a252899a02551f182ea2ea5ee) Fig. 4 — Required fields carry a red asterisk. Note the address block: Short Address Code, Full Address Line, Building No, Street Name, Secondary Address Number, City, District and ZIP Code — the structure the Saudi National Address uses, rather than a single free-text field. **Step 2 — Order Details and Products.** Leave **Order Number** blank and OTO generates one. **Order Date** and **Order Value** are required — the value field carries its own note that it determines the compensation amount if a claim is ever needed, which is a good reason not to leave it approximate. **Warehouse** or **Branch** sets the origin, and **Brands**, **Invoice Number** and **Ref No** are there for matching the order back to your own systems. Products Details then takes **Package Size** and a required **Item Description**. ![Step 2 of Add Order — Order Details](https://mintcdn.com/oto/ft-bRlLvOnJkbVoC/images/ordersync-5-add-order-details.png?fit=max\&auto=format\&n=ft-bRlLvOnJkbVoC\&q=85\&s=36f3fa853edecd83c138f52912998260) Fig. 5 — Order Value sets the declared value used for compensation. Warehouse defaults to your default location. Previous returns to the receiver step; Add creates the order, which then enters routing like any other. > [!TIP] > > **Use the Short Address Code** > > Where the customer knows it, the Short Address Code is faster to type and far more accurate than a street address — it resolves to exact coordinates, which is what [Order routing](https://docs.tryoto.com/modules/omnichannel-oms/order-routing.md) needs to pick the closest location. See [Address and data correction](https://docs.tryoto.com/modules/omnichannel-oms/order-data-correction.md). ### Bulk order import **Upload Multiple Orders** on the Shipments page opens the **Upload Orders** dialog. Download the template, fill it in, and upload — the file is validated before anything is created, and rows with problems are reported back for correction while the valid rows still process. On a large migration that matters: one bad row doesn't cost you the batch. ![The Upload Orders dialog](https://mintcdn.com/oto/YkJay8Y-1RDv8ciw/images/ordersync-6-upload-orders.png?fit=max\&auto=format\&n=YkJay8Y-1RDv8ciw\&q=85\&s=d4f5e037a694126f1e9597a8546539d2) Fig. 6 — Download Template, then drag and drop or Browse. One file per upload, XLSX or XLS, up to 100 MB. The optional Description is a note for your own team, useful when several people are loading files. | Requirement | Detail | | - | - | | **Format** | XLSX or XLS, one file per upload | | **File size** | Up to 100 MB | | **Required columns** | Customer Name · Phone Number (with country code) · Address · City · Country · Order Number · Order Date · Payment Method (`Paid` or `Cash on Delivery`) · Grand Total · Currency | | **Optional columns** | Zip code · item descriptions · SKUs · comments · item images · weight · warehouse | | **Order numbers** | Must be unique. Duplicates are rejected. | | **Template** | Don't rename columns or change formatting — validation matches on them. | ## Re-syncing a single order When a channel update is missed or arrives late, one order can fall behind the platform. Pull it back into line from **Shipments → Pending Orders**: select the order, open **Orders**, and choose **Synchronize Order**. ![The Orders menu on the Shipments page](https://mintcdn.com/oto/YkJay8Y-1RDv8ciw/images/ordersync-7-orders-menu.png?fit=max\&auto=format\&n=YkJay8Y-1RDv8ciw\&q=85\&s=ee5c0c54d29238831ed321fc642198e2) Fig. 7 — Synchronize Order sits among the per-order actions. Several of the others belong to functions documented elsewhere — Update Sender Location and Split Order under Order routing, Put on hold under Pre-fulfillment checks, and Inter Depot Transfer under Order fulfillment. > [!NOTE] > > **Scope** > > This pulls the current status from the platform and applies it. It does not overwrite other order data, does not trigger customer notifications, works only on orders in **Pending Orders**, and handles one order at a time. To refresh a whole channel, use **Sync Orders** from that channel's menu instead. ## Limits and prerequisites | Requirement | Detail | | - | - | | **A connected channel** | Automatic sync needs the channel connected and **Active**. Manual entry and bulk upload work without one. | | **Pickup locations matched** | Until **Match Pickup Locations** is set, channel orders have no origin to route from. | | **Warehouse or branch** | At least one location must exist before an order can be assigned. | | **Phone format** | Country code is required on manual entry and on bulk upload. | | **Upload size** | 100 MB per file, one file at a time. | | **Manual re-sync** | One order at a time, and only while the order is still pending. | ## Related * [Sales Channels](https://docs.tryoto.com/modules/sales-channels/overview.md) — the module covering connection, updates and the checkout API in depth. * [Address and data correction](https://docs.tryoto.com/modules/omnichannel-oms/order-data-correction.md) — cleans what sync brings in, before routing reads it. * [Order routing](https://docs.tryoto.com/modules/omnichannel-oms/order-routing.md) — the next step for every order that arrives here. * [Inventory sync](https://docs.tryoto.com/modules/inventory-management/inventory-sync.md) — the other half of the channel connection, pushing stock back. * [REST API](https://docs.tryoto.com/developers/rest-api-reference.md) — the fourth route in, for custom storefronts and ERPs. ## Related topics - [Sync order status and tracking to your store](https://docs.tryoto.com/modules/sales-channels/updates.md) - [Add and configure warehouses and branches](https://docs.tryoto.com/modules/hubs-management/hubs-management.md) - [What is OTO](https://docs.tryoto.com/get-started/what-is-oto.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.