For the complete documentation index, see llms.txt. This page is also available as Markdown.

Shipment Status Polling Cycle and Stop Conditions

This guide explains how OMS polls cargo companies for shipment status updates after a package is shipped, how often polling runs, which fields are used in queries, and under which conditions polling stops.

Overview

After a package is shipped, OMS periodically queries the cargo company for status updates. Polling is performed by scheduled tasks that are separated by shipment age:

Scope
Shipment Age
Default Frequency
Limit per Run

New shipments

0–7 days

Every 15 minutes

500 shipments

Old shipments

7–30 days

Every 30 minutes

500 shipments

Transfer shipments

No limit

Every 4 hours

No limit

Shipment age is calculated from the date the shipment record (tracking number / cargo label) was created.

Polling ends in the following cases:

  1. The shipment reaches a final status (delivered, failed, cancelled).

  2. The package moves to a status other than shipped or attempted_delivery (for example, delivered, ready_for_customer_pickup, delivery_failed).

  3. 30 days have passed since the shipment record was created. No warning is generated in this case.

In addition, when consecutive errors occur on a query endpoint, all queries that use that endpoint are temporarily suspended for up to 60 minutes.

There is no retry limit per shipment. Shipments that return an error or an empty response are queried again in every run until the 30-day period expires.

When Polling Starts

Polling starts when the package moves to the shipped status. A shipment is included in polling only if it meets all of the following conditions:

Condition
Value

Package status

shipped or attempted_delivery

Shipment status

waiting_for_pick_up, shipped, or attempted_delivery

Shipment age

Last 30 days (configurable)

Cargo company

A cargo integration that supports status queries is defined

A package moves to the shipped status in one of two ways:

  • Manually or via integration: The store or an integration performs the Shipped action.

  • Automatic shipping: If the setting is enabled, OMS queries the cargo company every 2 hours (by default) for packages that are in the packed status and were updated within the last 15 days. If the cargo company returns shipped, attempted_delivery, delivered, or failed, the package is automatically moved to the shipped status.

Note: If a package remains in the packed status and automatic shipping is not enabled, status polling does not start, even if the cargo company has already picked up the package.

Polling Frequency

Scheduling

Task
Default Interval

New shipments (0–7 days)

15 minutes

Old shipments (7–30 days)

30 minutes

Transfer shipments

4 hours

Automatic shipping

2 hours

Intervals can be changed per environment, and tasks can be disabled when needed.

Polling Interval per Shipment

Up to 500 shipments are queried in each run. The remaining shipments are queried in subsequent runs, continuing from where the previous run left off. Shipments are processed from the newest record to the oldest; once all shipments have been processed, the sequence starts over.

As a result, the time between two queries for the same shipment depends on the number of shipments in scope.

When the number of shipments is an exact multiple of 500, the run following the last batch has no shipments left to query, and the sequence restarts only in that run. The interval is therefore calculated as follows:

Shipments in Scope (0–7 days)
Polling Interval per Shipment

Fewer than 500

15 minutes

500

30 minutes

2,000

1 hour 15 minutes

9,000

4 hours 45 minutes

20,000

10 hours 15 minutes

For shipments aged 7–30 days, the same calculation applies with a 30-minute task interval.

To avoid overloading the cargo company, queries are not sent all at once. They are sent in batches of 20, with a 1-second wait between batches. With default settings, 500 queries complete in approximately 25 seconds.

Application Settings

Setting
Default
Description

SHIPPED_THRESHOLD_DAYS

30

Maximum period (in days) during which shipments are queried. Shipments older than this are not queried.

SHIPMENT_QUERY_DISPATCH_CONF

500 shipments, batches of 20, 1-second interval

Number of shipments queried per run and the query dispatch rate.

CIRCUIT_BREAKER_CONF

25 errors, 60 minutes

Number of consecutive errors per query endpoint that triggers suspension, and the suspension duration.

AUTO_RUN_SHIP_THE_PACKAGE_COMMAND

Disabled

Automatic shipping for packages in the packed status.

PRE_PACKAGE_CLICK_AND_COLLECT

Disabled

For Click & Collect orders, moves the package to ready_for_customer_pickup when the cargo company returns delivered.

SYNC_SHIPPING_STATUS

Enabled

Sends status changes to Omnitron.

Stop Conditions

#
Condition
Behavior
Permanent

1

Shipment status is delivered

Polling ends. The package moves to delivered (ready_for_customer_pickup for Click & Collect orders).

Yes

2

Shipment status is failed

Polling ends. The package moves to delivery_failed.

Yes

3

Shipment status is cancelled

Polling ends.

Yes

4

Package moved to a status other than shipped or attempted_delivery

Polling ends (for example, when the package is manually set to delivered, cancelled, or moved to ready_for_customer_pickup).

Yes

5

Shipment record is older than 30 days

Polling ends and no warning is generated. The package remains in the shipped status.

Yes

6

Consecutive errors on the query endpoint

The error count is tracked per query endpoint, not per cargo company record. When 25 consecutive errors occur on an endpoint, polling is suspended for all shipments that use it. Multiple cargo company records that share the same endpoint (for example, records connected to the same Akinon Shipment endpoint), as well as transfer shipment and automatic shipping queries, share the same error count. The suspension is lifted automatically 60 minutes after the first error; a successful query in the meantime resets the error count.

No

7

Cargo company returned an error or a timeout occurred

The error is logged and the shipment is queried again in the next run. If the cargo integration propagates the error, it is added to the error count described in condition 6. For integrations that handle errors internally (for example, Yurtiçi v1.3), the error is not counted and is treated as an empty response, as described in condition 8.

No

8

Cargo company returned an empty response (a response with no status, tracking URL, or cargo company information)

A warning is logged and no changes are made. The shipment is queried again in the next run.

No

9

Cargo company returned a status that has no mapping in OMS

The OMS status does not change and polling continues.

No

10

The cargo company is configured with an integration that does not support status queries (test/demo)

The shipment is not queried.

Yes

Retry limit: No retry count is kept per shipment. In cases 7, 8, and 9, the shipment continues to be queried until condition 5 (30 days) is met.

Start of the 30-day period: The period is calculated from the time the shipment record (tracking number / cargo label) was created, not from the time the package was shipped. For packages that remain in the packed status for a long time after the label is created, the post-shipping polling period is shortened by that waiting time.

Fields Used in Polling

Query Number

Status queries use the query number on the shipment record. The tracking number is not used in the query; it is populated or updated based on the query response and sent to Omnitron as the tracking number.

The query number is determined during shipment creation in the following order of priority:

  1. The query number returned by the cargo company in the shipment creation response.

  2. If not available, the query number sent during shipment creation.

  3. If that is also not available, the tracking number.

Query Number by Cargo Company

Cargo Integration
Query Number
How the Tracking Number Is Set

Aras, Yurtiçi, MNG, Jetizz

Package number (integration / reference code)

From the first successful query response

Yurtiçi v1.3

First 20 characters of the order's Omnitron ID concatenated with the package ID

From the first successful query response

GLS

First 20 characters of the order's Omnitron ID concatenated with the package ID

Set to the same value as the query number during shipment creation; the query response does not change the tracking number.

Akinon Shipment

Waybill number from the shipment creation response; if not available, the package number

From the query response

ACS, Speeta, Kolay Gelsin, Nova Poshta, Scotty, Sendeo, PackUp, Aramex, UPS, Deliverigo, Hoop Kapıda, Kargo İst

Shipment code / barcode returned by the cargo company in the shipment creation response

From the shipment creation or query response

Cargo that receives status via Omnitron

Not used. Status is read from Omnitron through the order information (shipped, attempted_delivery, delivered).

—

Cargo created outside OMS (tracking number sent to OMS during the shipping action)

The submitted tracking number

The submitted tracking number

Label query: In the Akinon Shipment integration, the cargo label is queried by package number by default; the mapping between the package number and the tracking number is maintained on the cargo integration side. If the shipment was created outside OMS, this mapping does not exist on the cargo integration side, so the label is queried by tracking number. The cargo company settings can also be configured to query the label by waybill number.

Empty Field Scenarios

Scenario
Behavior

Query number is empty, tracking number is populated

Because the tracking number is used when the query number is empty at shipment creation, this scenario occurs only in legacy records. For these records, cargo company–specific migration processes populate the query number with the tracking number or package number.

Both query number and tracking number are empty

No field validation is performed before the query; the query is sent to the cargo company with an empty value. If the cargo company returns an error, the error is logged and, if the cargo integration propagates errors, added to the error count described in condition 6 of Stop Conditions. If the cargo company returns an empty response, or the integration handles the error internally, a warning is logged. The shipment continues to be queried for 30 days and its status is not updated.

Tracking number is empty, query number is populated

Expected behavior. The tracking number is written to the shipment record after the first successful query. While the tracking number is empty, only the delivered status is sent to Omnitron.

Status Mapping and Impact on Packages and Orders

Each cargo integration converts the cargo company's statuses into the common shipment statuses in OMS. The impact of these statuses on packages and order items is as follows:

Shipment Status
Package Status
Omnitron Order Item Status

shipped

shipped

shipped

attempted_delivery

attempted_delivery

attempted_delivery

delivered

delivered

delivered

delivered (Click & Collect order with the related setting enabled)

ready_for_customer_pickup

ready_for_pickup

failed

delivery_failed

attempted_delivery

cancelled

Not applied through query responses; a shipment moves to cancelled only through cancellation operations.

—

When the status changes, a shipment status notification (webhook) is sent to the relevant systems, and if the related setting is enabled, order items in Omnitron are updated.

Click & Collect: The "your order is ready" notification sent to the customer depends on the package moving to the ready_for_customer_pickup status. Through cargo polling, this transition occurs only when the cargo company returns delivered. In the default mapping of the Akinon Shipment integration, the cargo company's READY_FOR_PICKUP status is mapped to shipped; therefore, this status alone does not trigger the notification. If needed, this mapping can be changed in the status mapping definition in the cargo company settings.

Transfer Shipments

  • Frequency: Queried every 4 hours by default.

  • Scope: Records where the transfer order is in the in_transit status and the transfer shipment is in the waiting_for_pick_up, shipped, attempted_delivery, or failed status.

  • Limits: No limits apply to shipment age, the number of queries per run, or the query rate; all records in scope are queried in every run.

  • Empty response: If the response contains no status information, a warning is logged and no changes are made.

Last updated

Was this helpful?