Stock issues on a subscription — what they mean and how to fix them
What the Stock Issues Detected banner means on a subscription contract, what triggers it, and the three ways to recover.
When a subscription has upcoming orders containing products that are out of stock, Roadmap shows a Stock Issues Detected banner at the top of the contract page.
The banner is a heads-up, not an automatic block — billing will still attempt on the scheduled date, and if inventory is still zero at that point the charge will fail with an INSUFFICIENT_INVENTORY error. This article walks through what to do before that happens.
What the banner says
⚠ Stock Issues Detected
N products in upcoming orders have stock issues. Review the upcoming orders below to take action.
N is the total count of out-of-stock line items across all upcoming orders on this contract — not the number of orders affected. One contract with five upcoming orders, each containing the same out-of-stock product, will show "5 products" not "1 product".
What triggers it
Any line item on an upcoming order whose variant currently has zero on-hand inventory in Shopify. The check is binary — there's no low-stock threshold and no "back in 7 days" prediction. If the variant is out of stock right now, it's flagged.
You'll see the same status surfaced on individual upcoming orders too: each affected line item gets an Out of Stock badge in the order's product list.
What happens if you do nothing
When the order's billing date arrives and the variant is still out of stock, Shopify rejects the charge. Roadmap records a billing attempt with the reason Error: Insufficient inventory. (INSUFFICIENT_INVENTORY) and the order goes into the dunning state — visible as Billing Error + Dunning badges on the upcoming-orders list.
If the issue resolves before dunning exhausts (you restock, or the customer swaps to a product that is in stock), the next dunning retry will succeed and the contract carries on. If dunning exhausts, the contract moves to Failed — see How to set up payment retries.
Three ways to fix it
Pick the option that matches the situation.
1. Restock before the next billing date
The simplest fix. If you know the variant is being restocked imminently, do nothing — the banner will clear automatically once Shopify shows positive on-hand inventory, and the next billing attempt will succeed.
You can confirm by reloading the contract page after stock arrives.
2. Swap the customer to a different product
There are two versions of this, and the one you want depends on whether the product is coming back.
For one delivery only, use Edit on that order's line in the Orders list. It opens Edit upcoming order product, and the contract goes back to its usual products on the following order. See Adjusting an upcoming subscription order.
For every future order, use Edit on the contract's Products card. It opens Edit subscription product. See Changing the products on a subscription contract.
Swap one delivery when you expect the variant back soon, and swap the contract when you don't.
3. Skip the affected delivery
If the customer is okay with a delay, Skip next delivery from the Manage subscription ▾ menu defers the next charge to the cycle after. By then, the variant may be back in stock; if not, the banner will still be there and you can revisit. See Adjusting an upcoming subscription order.
What customers see
Customers don't see the Stock Issues Detected banner from their account page. They see the line-item products on their upcoming orders as normal, without an out-of-stock callout.
If the billing attempt eventually fails, however, customers do receive Roadmap's failed-payment notification (if you've configured it) and dunning behavior takes over. By the time the customer realizes there's a stock problem, they're often hearing about it from the dunning email rather than from a proactive notice.
This is why monitoring the Stock Issues banner during your normal admin workflow matters — it's the merchant-facing early-warning signal.
Common scenarios
"I just restocked but the banner is still there"
Reload the contract page. The check runs server-side and the banner reflects the most recent inventory snapshot at page load — it doesn't live-update.
"The banner says 14 products but I only see 3 affected orders"
The count is line items across all upcoming orders, not orders. If three upcoming orders each have a 4-unit subscription to the same out-of-stock variant, that's 12 line items + the other two affected items = 14.
"A customer's contract failed with INSUFFICIENT_INVENTORY but the variant is in stock now"
If the customer is currently in dunning, the next dunning retry will pick up the new inventory state and succeed. If dunning has already exhausted and the contract is Failed, you'll need to manually recover with Order Now after confirming inventory — see Manually charging a subscription (Order Now).
Related guides
Last updated