> For the complete documentation index, see [llms.txt](https://docs.roadmap.so/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roadmap.so/subscriptions/troubleshooting/stock-issues-on-a-subscription-what-they-mean-and-how-to-fix-them.md). # 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 Failed payment retries (dunning). #### 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** Open the contract and use Edit subscription product in the per-cycle ••• menu (for a one-time swap on the next order) or in the Manage subscription ▾ menu (for a permanent swap to all future orders). See Editing a customer's subscription for the full walkthrough. This is the right call when you don't expect the variant to come back in stock soon. **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 * Editing a customer's subscription * Adjusting an upcoming subscription order * Failed payment retries (dunning) * Manually charging a subscription (Order Now) --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.roadmap.so/subscriptions/troubleshooting/stock-issues-on-a-subscription-what-they-mean-and-how-to-fix-them.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.