> For the complete documentation index, see [llms.txt](https://docs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.akinon.com/technical-guides/oms/fulfillment/shipments/shipment-status-polling-cycle-and-stop-conditions.md).

# 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:

```
Polling interval = (floor(Shipments in scope ÷ 500) + 1) × Task interval
```

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.akinon.com/technical-guides/oms/fulfillment/shipments/shipment-status-polling-cycle-and-stop-conditions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
