Marketplace Order Flow

This document describes the lifecycle of a marketplace order in OMS, from order creation through packaging and shipment status resolution.

Overview

Marketplace orders originate from channels such as Trendyol, Hepsiburada, Amazon, n11, Ciceksepeti, or Pazarama. Unlike web orders, the cargo carrier is managed by the marketplace itself. OMS does not interact with a cargo API to create or track shipments. Instead, OMS periodically reads the order status from Omnitron to determine whether the package has been shipped or delivered.

Flow at a Glance

Omnitron sends order
  |
  v
Order created in OMS  (status: approved)
Package created  (status: waiting)
  |
  v
Warehouse executes CHANNEL_BASED_COMPLETE_PACKAGING
Package -> packed
Shipment created  (tracking number from Omnitron order)
Order items reported to Omnitron as "preparing"
  |
  v
Background task checks Omnitron periodically
  |
  +-- Omnitron status 500 -> Package: shipped
  +-- Omnitron status 540 -> Package: attempted_delivery
  +-- Omnitron status 550 -> Package: delivered

Step 1 — Packaging

When the warehouse or store completes packing, the CHANNEL_BASED_COMPLETE_PACKAGING command must be executed on the package. This command is specifically designed for marketplace orders and must be used instead of the standard COMPLETE_PACKAGING command — it skips the external cargo API call and uses the tracking number already provided by the marketplace via Omnitron.

POST /packages/{package_id}/command/

{
  "slug": "CHANNEL_BASED_COMPLETE_PACKAGING",
  "input_parameters": {}
}

The following actions are performed:

1. Package status transitions to packed.

2. A Shipment record is created. The tracking number is taken from the order — it is the value Omnitron provides when the order is sent to OMS.

3. All package items are marked as packed.

4. Order items are reported to Omnitron with status preparing.

Step 2 — Shipment Status Resolution

After packaging, the shipment status is not yet known — the marketplace has not reported it. A background task runs periodically and checks the order status in Omnitron for all packed packages.

The order status returned by Omnitron is mapped as follows:

Omnitron Order Status	OMS Shipment Status
500	shipped
540	attempted_delivery
550	delivered
Anything else	No update

Since the marketplace manages its own shipping lifecycle, OMS does not execute the standard ship command. It updates the shipment and package statuses directly based on the Omnitron response.

Shipment Status	Package Status	Package Status Code
shipped	shipped	700
attempted_delivery	attempted_delivery	720
delivered	delivered	800

Setup Checklist

Channel

The channel must be registered in OMS with the correct type (e.g. trendyol, sales_channel). Channels are synced from Omnitron automatically or created on first order ingestion.

Cargo Company

A cargo company record must exist with carrier information matching what Omnitron sends on the order.

ChannelBasedOrdersCondition

The cargo company must have a condition configured to route marketplace orders to the correct shipment client. In the example below:

• cargo_company: 1 — the cargo company this condition is attached to.

• klass — tells OMS to use ChannelBasedOrdersCondition as the routing logic.

• channels: [42] — only orders coming from channel 42 will match this condition. Orders from other channels are not affected.

• conf.klass — instead of calling an external cargo API, OMS uses OmnitronShipmentClient, which reads the tracking number directly from the Omnitron order.

POST /cargo-company-conditions/

{
  "cargo_company": 1,
  "rules_configuration": {
    "rules": [
      {
        "klass": "oms.shipments.shipment_conditions.ChannelBasedOrdersCondition",
        "params": {
          "condition_type": "sales_channel",
          "channels": [
            42
          ],
          "conf": {
            "klass": "oms.shipments.clients.omnitron_shipment_client.OmnitronShipmentClient"
          }
        }
      }
    ]
  }
}

State Transitions

The following state transitions must be defined for the Package model:

Command	From	To
CHANNEL_BASED_COMPLETE_PACKAGING	waiting	packed
CHANNEL_BASED_COMPLETE_PACKAGING	preparing	packed
CHANNEL_BASED_COMPLETE_PACKAGING	ready_to_pack	packed

Application Setting

The AUTO_RUN_SHIP_THE_PACKAGE_COMMAND setting must be set to true for OMS to automatically check and update shipment statuses on packed packages.