> 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/renew-out-of-stock-packages.md).

# Renew Out-of-Stock Packages

`renew-out-of-stock-packages-cron` is a periodic task that retries planning for packages that have fallen into the out-of-stock (OOS) status because no stock was found. When stock becomes available again at any eligible stock location, the OOS package is cancelled and its order items are assigned to new packages. This guide explains which packages the task handles, how often it runs, and how its behavior can be changed.

For how OOS packages (`Contains Out-of-Stock Products`, 920) are created during planning, see [Package Splitting Rules](https://docs.akinon.com/technical-guides/oms/package-management/package-splitting-rules). OOS packages that should not wait indefinitely are handled by a separate task; see [Cancel Old OOS Packages](https://docs.akinon.com/technical-guides/oms/cancel-old-oos-packages).

### Overview

| Topic                 | Value                                                                                                   |
| --------------------- | ------------------------------------------------------------------------------------------------------- |
| Scheduled task name   | `renew-out-of-stock-packages-cron`                                                                      |
| Default run frequency | Every 3 hours (10,800 seconds, ±10 seconds of jitter)                                                   |
| Lookback period       | The package was last updated within the last `FULFILLMENT_MAX_DATE_RANGE` days (**15 days** by default) |
| Manual trigger        | `POST /api/v1/oms/tasks/retry-out-of-stock-packages/`                                                   |

### How the Task Works

Each run consists of two steps.

#### 1. Selection

Packages that meet **all** of the following conditions are selected:

* The package status is `Out of Stock Products` or `Defective Products`.
* The package was last updated within the lookback period (see Lookback Period).
* The package's order has not been cancelled.
* None of the order items in the package belongs to a shipping option group whose `shipping_option_slug` value is listed in the `DONOT_REPLAN_SHIPPING_OPTION_GROUPS` setting.

If the `DONOT_REPLAN_PACKAGES` setting is `true`, no packages are selected and the run does nothing.

#### 2. Renewal

A separate renewal job is queued for each selected package. This job runs the `renew_package_plan` command on the package:

1. The order and package records are locked.
2. Stock locations previously recorded as problematic for the package's items (active inventory discrepancy records) are excluded, so that planning does not select a location that has already failed.
3. Planning is rerun for the package's order items using the active packaging scenario and rules.
4. The outcome depends on whether stock is found:
   * **If stock is found:** The OOS package is cancelled with the cancellation reason `renew_plan` (or `oos_replan` if the package fell into OOS through the "out of stock" command). Its reservations are released, and new packages and transfer orders are created. If `predefined_package_state` is defined for the OOS transition, the new packages are moved to that status.
   * **If stock is still not found:** When `FORCE_NEW_OOS_PACKAGE = false` (default), the package remains as it is and is retried in the next run. When `FORCE_NEW_OOS_PACKAGE = true`, the package is cancelled and a new OOS package is created for the same items.

{% hint style="info" %}
Only packages in the `Out of Stock Products` and `Defective Products` statuses are selected. Packages in the `Needs Replan` and `Stale Waiting` statuses can be renewed with the same command, but they are not handled by this task. For stale waiting packages, see [Stale Waiting Process](https://docs.akinon.com/technical-guides/oms/stale-waiting-process).
{% endhint %}

The counterpart task, `renew-out-of-stock-transfers-cron`, does the same for transfer orders in the `Out of Stock` status. It uses the same default frequency and the same lookback setting.

### Run Frequency

The default interval is 3 hours. The scheduler adds a random jitter of ±10 seconds, so runs do not occur at a fixed minute. After a deployment, the first run takes place one interval after the scheduler (Celery beat) starts.

### Lookback Period

A package is selected only if its last update date is not older than `FULFILLMENT_MAX_DATE_RANGE` days. The default value is **15 days**. Because this is an application setting, it may differ between environments; check the value in the relevant environment before answering a partner question.

Using the last update date instead of the creation date has two consequences:

* The period is counted from the package's **last change**, not from the order date or the moment the package fell into OOS.
* A renewal attempt that finds no stock also saves the package (it writes the cancellation reason), which moves the last update date forward. As a result, a package that is retried at least once every `FULFILLMENT_MAX_DATE_RANGE` days stays within the window and continues to be retried until stock is found or the package is cancelled. A package leaves the scope only if it is not touched at all for longer than the window, for example, while the task is disabled or `DONOT_REPLAN_PACKAGES` is enabled.

Packages that should not wait indefinitely are handled by separate tasks that are disabled by default: `cancel_old_oos_packages` and `request_cancellation_for_old_oos_packages` (`OOS_ITEM_MAX_AGE_FOR_CANCELLATION_PLAN`, `OOS_ITEM_MAX_AGE_FOR_CANCELLATION_REQUEST`). For details, see [Cancel Old OOS Packages](https://docs.akinon.com/technical-guides/oms/cancel-old-oos-packages).

### Configuration

The task's behavior can be changed with the following application settings. When a setting is saved, its cached value is also updated; the change takes effect in the next run without a restart.

| Key                                   | Type                                  | Default | Effect                                                                                                                                                                                                                     |
| ------------------------------------- | ------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FULFILLMENT_MAX_DATE_RANGE`          | int (days, ≥ 1)                       | `15`    | Lookback period applied to the package's last update date. Also used when selecting unplanned orders and OOS transfers.                                                                                                    |
| `DONOT_REPLAN_PACKAGES`               | bool                                  | `false` | If `true`, all automatic package replanning stops; this task selects no packages.                                                                                                                                          |
| `DONOT_REPLAN_SHIPPING_OPTION_GROUPS` | List of `shipping_option_slug` values | `[]`    | A package is skipped if the shipping option group of any of its order items carries a `shipping_option_slug` value in this list. The match is made against the group's `shipping_option_slug` field, not the group itself. |
| `FORCE_NEW_OOS_PACKAGE`               | bool                                  | `false` | When the renewal finds no stock: `true` cancels the package and creates a new OOS package; `false` leaves the package as it is.                                                                                            |

Planning itself (which stock locations are eligible and in which order they are evaluated) is determined by the packaging scenario and rules, as with new orders. For details, see [Scenarios](https://docs.akinon.com/technical-guides/oms/scenarios).

### Manual Trigger

#### All OOS Packages

```
POST /api/v1/oms/tasks/retry-out-of-stock-packages/
```

This request requires an authenticated OMS user. It runs the selection step synchronously and queues the per-package renewal jobs; the `200` response is returned when the jobs are queued, not when they are completed. In case of an error, `406` is returned with a `detail` field.

If a scheduled run is in progress at that moment, the manual call is skipped because of the lock and still returns `200`. If a manual call appears to have done nothing, check the logs for the `Task … is already running..` line.

Transfer counterpart: `POST /api/v1/oms/tasks/retry-out-of-stock-transfers/`.

#### A Single Package

If the relevant status transition is defined for the package, the `renew_package_plan` command can be run through the package command endpoint (`POST /api/v1/oms/packages/{id}/command/`). The lookback period is not applied to manual commands.

To assign a package's items to specific locations manually instead of rerunning automatic planning, see [Manual Planning Command](https://docs.akinon.com/technical-guides/oms/commands/packages/manual-planning-command).

### Troubleshooting

| Symptom                                                    | What to Check                                                                                                                                                                                                                                                                          |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| An OOS package is never retried                            | Have more than `FULFILLMENT_MAX_DATE_RANGE` days passed since its last change? Is `DONOT_REPLAN_PACKAGES` enabled? Is the `shipping_option_slug` value of the shipping option group of any order item in the `DONOT_REPLAN_SHIPPING_OPTION_GROUPS` list? Has the order been cancelled? |
| The package is retried but remains in OOS                  | After locations with active inventory discrepancies for the items are excluded, no eligible location has stock. Check the stock map and the packaging scenario rules.                                                                                                                  |
| `InvalidStateTransitionConfigurationException` in the logs | No status transition is defined for `renew_package_plan` from the package's current status.                                                                                                                                                                                            |


---

# 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/renew-out-of-stock-packages.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.
