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

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. OOS packages that should not wait indefinitely are handled by a separate task; see 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.

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.

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.

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.

Manual Trigger

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

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.

Last updated

Was this helpful?