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
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 ProductsorDefective 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_slugvalue is listed in theDONOT_REPLAN_SHIPPING_OPTION_GROUPSsetting.
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:
The order and package records are locked.
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.
Planning is rerun for the package's order items using the active packaging scenario and rules.
The outcome depends on whether stock is found:
If stock is found: The OOS package is cancelled with the cancellation reason
renew_plan(oroos_replanif the package fell into OOS through the "out of stock" command). Its reservations are released, and new packages and transfer orders are created. Ifpredefined_package_stateis 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. WhenFORCE_NEW_OOS_PACKAGE = true, the package is cancelled and a new OOS package is created for the same items.
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_RANGEdays 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 orDONOT_REPLAN_PACKAGESis 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.
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
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?

