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:
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:
The shipment reaches a final status (
delivered,failed,cancelled).The package moves to a status other than
shippedorattempted_delivery(for example,delivered,ready_for_customer_pickup,delivery_failed).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:
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
packedstatus and were updated within the last 15 days. If the cargo company returnsshipped,attempted_delivery,delivered, orfailed, the package is automatically moved to theshippedstatus.
Note: If a package remains in the
packedstatus 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
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:
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
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
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
packedstatus 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:
The query number returned by the cargo company in the shipment creation response.
If not available, the query number sent during shipment creation.
If that is also not available, the tracking number.
Query Number by Cargo Company
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
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:
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_pickupstatus. Through cargo polling, this transition occurs only when the cargo company returnsdelivered. In the default mapping of the Akinon Shipment integration, the cargo company'sREADY_FOR_PICKUPstatus is mapped toshipped; 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_transitstatus and the transfer shipment is in thewaiting_for_pick_up,shipped,attempted_delivery, orfailedstatus.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?

