> 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/inventory-locations-and-engine/out-of-stock-root-causes.md).

# Out-of-Stock Root Causes

## Blacklist Flow, Reservations, and Stock Sync

This guide brings together all the sources that can cause a package or package item to fall into the out-of-stock (OOS) state in OMS. For each source, it explains when it applies, what effect it has, and where partners can check it. The goal is to let partners verify the root cause on their side instead of opening a ticket for every OOS case.

### Two Meanings of OOS

In OMS, the phrase "fell into OOS" describes two different events. Before starting a diagnosis, identify which one you are dealing with.

| Type            | What Happens                                                                                                                                                             | Status Codes                                                                       | Typical Root Cause                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Planning OOS    | While the order is being planned, no eligible location has enough available stock. OMS opens an OOS package at the scenario's default stock location.                    | Package: `out_of_stock_products`; item: `out_of_stock` (520)                       | The stock service returns 0, reservations (including discrepancy reservations) have consumed the stock, or a blacklist has closed the location. |
| Operational OOS | The package has been assigned to a store, but the store cannot find the product and marks the package or item as OOS ("out of stock", "add to blacklist", transfer OOS). | Package: `out_of_stock_products`; item: `out_of_stock` (520), followed by a replan | Physical stock in the store is lower than the stock in the ERP (phantom stock), or there is a sync delay.                                       |

An operational OOS often triggers a planning OOS: when an item is marked as OOS, OMS replans the order, and if no other location has available stock, the result is a planning OOS. For this reason, a single case usually requires investigating two root causes together: why the first store could not find the product, and why the replan could not find another location.

### How Planning Calculates Stock

When OMS plans an order, it calculates the available stock for each location at that moment:

1. The location's stock service (ERP/WMS) is queried to get the raw stock.
2. Reservations held in OMS are subtracted from this stock: pending package and transfer reservations, and inventory discrepancy (`discrepancy`) reservations.
3. If the product is blacklisted at that location, the stock is treated as 0.

If the result is 0, the location is not selected for that product. If no location has enough stock left, the order falls into OOS.

{% hint style="info" %}
OMS does not cache stock; it queries it live at every planning run. If outdated stock was observed, the delay comes from the system feeding the stock service, not from OMS.
{% endhint %}

### Blacklist Flow

#### What It Does

A blacklist closes a specific product at a specific location to planning. Each record stores the product, the location, the related package item (if any), the user who added the record, and its active status.

While an active blacklist record exists, the stock is treated as 0 regardless of what the stock service returns for the product at that location. Only that product is disabled at that location, not the entire location; other products at the same location are not affected.

#### When a Record Is Created

| Trigger                                           | How                                                                                                                            | Record Format                                                                                                                         |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| Store action: add to blacklist (`BLACKLIST_ITEM`) | While the package is in `waiting` (100) or `accepted` (110), the store marks the selected items as "out of stock + blacklist". | A separate record for each package item                                                                                               |
| Manual API                                        | The product and location are sent with `POST /api/v1/oms/products/blacklist/`.                                                 | The package item is empty. If a record already exists for the same product and location, it is reactivated; no new record is created. |

The add-to-blacklist action has the following effects:

1. The package moves to the `out_of_stock_products` status.
2. Unselected items (those in stock) are cancelled, their reservations are released, and they are manually replanned as a new package at the same location.
3. Selected items move to `out_of_stock` (520), their reservations are released, and a blacklist record is created for each of them.
4. The order is replanned. In this replan, the product now appears as 0 at that location; if no other location has available stock, the result is a planning OOS.

The regular "out of stock" action (`DETECTED_OUT_OF_STOCK_ITEM`) does not create a blacklist record; it creates an inventory discrepancy record instead. The difference between the two actions is that a discrepancy is short-term (1 day by default), while a blacklist is long-term or permanent.

#### Impact

* The product is not assigned to any order from that location until the record is deactivated, even if the store's stock is corrected later.
* If the only location with stock for a product is blacklisted, the product continues to be sold, but every order falls directly into a planning OOS. This is one of the most common causes of complaints such as "stock appears available, but orders keep going out of stock".
* Blacklist information is not written back to Omnitron or storefront stock; the sales channel continues to see the product as sellable.

#### Where to Check

| Question                                         | Where                                                                                                                    |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| Is this product blacklisted at this location?    | `GET /api/v1/oms/products/blacklist/?product__sku={sku}&stock_location__erp_code={erp}&is_active=true`                   |
| All active blacklist records at a location       | `GET /api/v1/oms/products/blacklist/?stock_location__erp_code={erp}&is_active=true` (export supported)                   |
| Who added it, when, and from which package item? | The user, package item, and date details in the blacklist record                                                         |
| Tracking blacklist changes in real time          | Webhooks: `blacklist_product.created`, `blacklist_product.updated`, `blacklist_product.deleted` (including deactivation) |
| Removing a record                                | `DELETE /api/v1/oms/products/blacklist/{id}/`                                                                            |

### OMS Internal Reservations

#### What It Does

To avoid promising the same stock unit twice, OMS holds a reservation at the location for every item it plans. These reservations are subtracted from the stock returned by the stock service. OMS stores both the total reserved quantity per (product, location) and the history of every reservation and release movement.

Reservation types: `allocation` (planned order), `transfer`, `buffer` (manually set aside buffer stock), `discrepancy` (stock that could not be found), and `manual`.

#### When Reservations Block Stock

A reservation is held while the package is in one of the following statuses (this can be changed with the `ALLOWED_PACKAGE_STATES_FOR_RESERVATION` tenant setting):

`waiting`, `accepted`, `waiting_remote_action`, `waiting_transfer_operation`, `preparing`, `ready_to_pack`, `blocked`

For transfers: `waiting`, `preparing`, `ready_to_shipment` (`ALLOWED_TRANSFER_STATES_FOR_RESERVATION`).

When the package leaves this set (packed, cancelled, moved to OOS, and so on), the reservation is released.

#### How Reservations Lead to OOS

| Scenario                                                           | Result                                                                                                                                                                                                                                                              |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A location has 3 units of stock and 3 pending package reservations | Available stock is 0, so a new order goes to another location or falls into OOS. This is expected behavior.                                                                                                                                                         |
| Packages waiting in `waiting` / `blocked` for a long time          | The stock remains reserved even though it has not actually been sold; new orders fall into OOS.                                                                                                                                                                     |
| `buffer` reservation                                               | Stock deliberately set aside by the partner or operations team; it is closed to planning.                                                                                                                                                                           |
| Reservation drift (anomaly)                                        | Due to a worker crash, an incomplete flow, or similar issues, the reserved quantity remains higher than the actual number of packages or transfers, creating a phantom reservation. An automatic correction task runs every 6 hours; OOS can occur in the meantime. |
| Double deduction                                                   | If the stock service already returns net stock with open orders deducted and OMS also deducts its own reservations, the same unit is deducted twice.                                                                                                                |

Reservations can be disabled per tenant with the `IS_RESERVATION_ACTIVE` setting. Per location, setting `SAVE_RESERVATION=false` stops OMS from holding reservations at that location.

### Inventory Discrepancy

#### What It Does

When a store marks an item as "out of stock" or "defective product", or marks a transfer as OOS, OMS opens an inventory discrepancy record for each item. It then queries the product's stock at that location live from the stock service and creates a `discrepancy` reservation equal to the returned quantity:

| Stock Returned by the Stock Service at the Time of the Discrepancy | Resulting Discrepancy Reservation                 |
| ------------------------------------------------------------------ | ------------------------------------------------- |
| N > 0                                                              | N units (the entire stock visible at that moment) |
| 0 or unreadable                                                    | 1 unit                                            |

A discrepancy does not set the stock directly to 0; its effect comes through this reservation. Planning subtracts this reservation from the value returned by the stock service (see How Planning Calculates Stock):

* If the stock service keeps returning the value it returned at the time of the discrepancy, the available stock is 0. OMS does not assign the same product to the same location again, even if the ERP still shows it as in stock.
* If new stock arrives at the location while the discrepancy is active and the stock service returns a higher value, the difference becomes available and the location can be included in planning again.
* If the stock service later returns a lower value, the reservation remains higher than the visible stock. The available stock does not go below 0, and the location is still not selected.
* When the discrepancy period expires (`INVENTORY_DISCREPANCY_DAY`) or the discrepancy is closed manually, the record is deactivated and the discrepancy reservation is released.
* If internal reservations are disabled for the tenant (`IS_RESERVATION_ACTIVE = false`), the stock is actually treated as 0 for any (product, location) pair with an active discrepancy.

#### Where to Check

| Question                                        | Where                                                                                                                  |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Is there an active discrepancy at the location? | `GET /api/v1/oms/inventory-discrepancies/?stock_location__erp_code={erp}&package_item__order_item__product__sku={sku}` |
| How much stock the discrepancy reserves         | `stock-search/list` / `detailed-query-product` → `reservation_count`; `reservationaction/detailed-reservation-count`   |
| Evidence photos                                 | `GET /api/v1/oms/discrepancy-images/?...`                                                                              |
| Closing a discrepancy early                     | `POST /api/v1/oms/inventory-discrepancies/{id}/clear/`                                                                 |

> **Note:** If new discrepancies keep being opened for the same (product, location) pair, the problem is not in OMS but in the stock record in the ERP/WMS. The permanent solution is a stock correction or a blacklist.

### WMS and Third-Party Reservations (Whippy, Omniens, etc.)

#### What OMS Sees and Does Not See

OMS learns a location's stock only through the stock service defined for that location. In a Whippy setup, this service is Whippy's stock query endpoint (`/api/v1/stocks/stock_query/`). Omniens and other WMS/ERP integrations also connect through their own stock service definitions.

As a result:

* Reservations held within the WMS itself (its own orders, B2B shipments, quarantine, stock count locks, allocations to other channels) are not sent to OMS as separate data. OMS sees only the number returned by the stock service.
* If the stock service returns net stock (physical stock minus WMS reservations), the quantity blocked by the WMS appears in OMS directly as "out of stock". OMS cannot tell that this comes from a reservation; `remote_stock_count` appears low or 0.
* OMS reservation records contain no WMS-originated records. This is why partners report that they "cannot see the source of the reservation" in OMS screens.

#### How WMS Reservations Lead to OOS

| Scenario                                                                                                       | Symptom                                                                                                                                       | Check                                                                                 |
| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| The WMS has allocated stock to another channel or task                                                         | `remote_stock_count` in OMS is 0 or lower than expected; there is no OMS reservation                                                          | The reservation/allocation breakdown for the product in the WMS panel                 |
| Double deduction: the WMS also reserves stock for OMS's own orders, and OMS holds its own internal reservation | `remote_stock_count` has already been reduced, and `reservation_count` reduces it further, so the available stock is actually low or negative | Whether the pending packages in `detailed-query-product` are also reserved in the WMS |
| The WMS shows more stock than the physical stock                                                               | Planning assigns the order, but the store cannot find the product, resulting in an operational OOS and a discrepancy                          | Inventory discrepancy records, WMS stock count records                                |

Two settings are available to prevent double deduction. In setups where the WMS already reserves OMS orders, choose between them deliberately:

* **Per location:** `SAVE_RESERVATION = false`. OMS does not hold order reservations at that location (inventory discrepancy reservations are still held).
* **Per environment:** `USE_INTERNAL_RESERVATIONS = false`. OMS's internal reservations are not subtracted from stock at all (for custom integrations).

#### Where to Check

* **OMS side:** `remote_stock_count` in the `stock-search/list` or `detailed-query-product` output is the value returned by the stock service at that moment, before OMS reservations are subtracted.
  * If `remote_stock_count` is low and there is no OMS reservation, the root cause is outside OMS (WMS/ERP).
  * If `remote_stock_count` is sufficient but `reservation_count` consumes the stock, the root cause is an OMS internal reservation.
* **WMS side:** The owner of the reservation (order, channel, transfer, quarantine) can be seen only in the WMS panel or reports. OMS does not store this information and cannot produce it.

### Stock Sync Delay and Stock Service Response

#### Sync Delay

OMS queries stock live at planning time; there is no stock cache on the OMS side. Delays occur in the chain that feeds the stock service:

```
Store/POS sale, stock count, return → ERP / WMS → (if any) Omnitron stock list / stock service → OMS stock query
```

| Delay Type                                                                                        | Result                                                                                                                |
| ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| A product sold in the store (POS) has not yet been reflected in the ERP/WMS                       | OMS sees stock and plans the order; the store cannot find the product, resulting in an operational OOS.               |
| Stock received by the store (transfer acceptance, return, stock count) has not yet been reflected | OMS sees no stock, resulting in a planning OOS (even though stock actually exists).                                   |
| Time between planning and the store processing the package                                        | While the package waits, the stock on the shelf can be sold through another channel, resulting in an operational OOS. |
| Reservation drift                                                                                 | A phantom reservation for up to the 6-hour correction interval                                                        |

#### Interpreting the Stock Service Response

If the stock service response does not include the location's ERP code, the stock for that location is treated as 0. As a result:

* If the location's ERP code in OMS does not exactly match the store code in the ERP/WMS, the location always appears to have no stock.
* If the stock service returns an error (timeout, connection error), planning cannot be completed. This is a planning error, not an OOS, but it can be confused with OOS in the replan chain.

#### Where to Check

| Question                                               | Where                                                                                                   |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| What does OMS currently see from the stock service?    | `stock-search/list` / `detailed-query-product` → `remote_stock_count` (live query)                      |
| Stock for the items of a specific package              | `GET /api/v1/oms/products/stock-check-for-package/?...`                                                 |
| Comparison with the ERP/WMS record                     | The stock value in the ERP/WMS at the same moment; if there is a difference, investigate the sync chain |
| Location code match                                    | The location's ERP code in OMS ↔ the store code in the ERP/WMS                                          |
| How long did the package wait before falling into OOS? | Package status history: the time between `waiting` and `out_of_stock_products`                          |

### Locations That Are Never Candidates in Planning

Some locations are never included in planning even if they have stock; the result is still a planning OOS:

* The location is inactive, has no stock service defined, or its stock service is inactive.
* The location is neither a fulfillment center nor a delivery location.
* The packaging scenario or rules filter out the location (tag, channel, distance, quota, and so on).
* During replanning, the location has been marked as "problematic" for this order because of a previous OOS or cancellation.

**Check:** Use `GET /api/v1/oms/stocklocations/?erp_code={erp}` to see the location's active status, type, and stock service information. Check scenario and rule settings in the OMS screens.

### Partner Checklist

| #  | Source                        | When It Applies                                                                                  | Duration of Effect                                            | Visible in OMS?                                | Partner Check Point                                                                           |
| -- | ----------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------- |
| 1  | Blacklist                     | The store's add-to-blacklist action or the manual API                                            | Until deactivated (the retention task is disabled by default) | Yes                                            | `products/blacklist/?product__sku=&stock_location__erp_code=&is_active=true`, webhooks        |
| 2  | OMS internal reservation      | While the package or transfer is in a reservation-holding status                                 | Until the package leaves these statuses                       | Yes                                            | `stock-search/list`, `detailed-query-product`, `reservationaction/detailed-reservation-count` |
| 2a | Reservation drift             | Incomplete flow, worker crash                                                                    | ≤ 6 hours (automatic correction)                              | Yes                                            | `reservationrecord/anomalous/`                                                                |
| 2b | Buffer stock                  | Manual buffer                                                                                    | Until removed                                                 | Yes                                            | `buffer_stock/`                                                                               |
| 3  | Inventory discrepancy         | Store "out of stock" / transfer OOS; a discrepancy reservation equal to the stock at that moment | `INVENTORY_DISCREPANCY_DAY` (1 day by default)                | Yes                                            | `inventory-discrepancies/`, `reservation_count`                                               |
| 4  | WMS / third-party reservation | The WMS's own allocations                                                                        | Depends on the WMS                                            | No; visible only as a low `remote_stock_count` | WMS panel + OMS `remote_stock_count`                                                          |
| 4a | Double deduction              | The WMS and OMS both reserve the same order                                                      | Continuous                                                    | Partially                                      | `remote_stock_count` vs. `reservation_count`, `SAVE_RESERVATION` setting                      |
| 5  | Sync delay                    | POS sales, stock counts, or transfers reach the ERP late                                         | For the duration of the sync                                  | Partially (current value)                      | `remote_stock_count` ↔ ERP/WMS value                                                          |
| 5a | Location code mismatch        | The ERP code is missing from the stock service response                                          | Until corrected                                               | Yes (always 0)                                 | `stocklocations/?erp_code=` ↔ ERP store code                                                  |
| 6  | Location is not a candidate   | Inactive, no stock service, or excluded by rules                                                 | Until the setting is corrected                                | Yes                                            | `stocklocations/`, scenario and rule screens                                                  |

All endpoints are under `{omnitron_host}/api/v1/oms/` and are called with Omnitron authorization.

### Appendix: Related Settings and Tasks

#### Application Settings

| Key                                       | Default                           | Effect                                                                                                  |
| ----------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `IS_RESERVATION_ACTIVE`                   | `true`                            | Enables or disables internal reservations tenant-wide (excluding discrepancy reservations).             |
| `ALLOWED_PACKAGE_STATES_FOR_RESERVATION`  | See When Reservations Block Stock | Package statuses that hold reservations.                                                                |
| `ALLOWED_TRANSFER_STATES_FOR_RESERVATION` | See When Reservations Block Stock | Transfer statuses that hold reservations.                                                               |
| `INVENTORY_DISCREPANCY_DAY`               | `1`                               | Number of days a discrepancy remains active.                                                            |
| `BLACKLIST_PRODUCT_RETENTION_DAY`         | `30`                              | Expiration period for blacklist records (if the task is enabled).                                       |
| `FORCE_NEW_OOS_PACKAGE`                   | `false`                           | In an OOS case, opens a new OOS package at the default location instead of moving the existing package. |

#### Location and Environment Settings

| Setting                     | Scope               | Effect                                                           |
| --------------------------- | ------------------- | ---------------------------------------------------------------- |
| `SAVE_RESERVATION`          | Location setting    | If `false`, order reservations are not held at the location.     |
| `USE_INTERNAL_RESERVATIONS` | Environment setting | If `false`, internal reservations are not subtracted from stock. |

#### Periodic Tasks

| Task                               | Default                                       | Frequency |
| ---------------------------------- | --------------------------------------------- | --------- |
| `clear_expired_blacklist_products` | Disabled (`CLEAR_EXPIRED_BLACKLIST_PRODUCTS`) | Hourly    |
| `clear_inventory_discrepancies`    | Enabled                                       | Hourly    |
| `fix_reservation_anomalies`        | Enabled                                       |           |


---

# 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/inventory-locations-and-engine/out-of-stock-root-causes.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.
