Troubleshooting & FAQ

Start Here#

Nine times out of ten, a discount that “isn’t working” fails one of four checks. Run these before anything else, they take about thirty seconds.

A Discount Isn’t Applying at Checkout#

Work down this list in order. It is sorted by how often each cause turns out to be the real one.

1. The Discount Is a Draft or Archived#

Only Active discounts are written into your store at all. Moving a discount to draft or archiving it takes it out of your products’ configuration, so checkout stops seeing it.

Fix: open the discount and click Activate discount in the page header, then confirm with Activate. Setting the Status dropdown in the right-hand column to Active and clicking Save does the same thing.

2. The Product in the Cart Isn’t Targeted#

Open the discount and read the Included products section.

• A product added whole covers every variant, including variants you add in Shopify later. Its line says All 4 variants, including any added later.
• A product narrowed to particular variants says 2 of 4 variants. Only those variants are discounted.

Fix: click Browse to reopen the picker, or expand Variants (4) on the product and tick the ones you want. Ticking the last unticked variant puts the product back to whole-product targeting.

3. A Condition Wasn’t Met#

Conditions live in the Conditions section of the discount, and there are exactly three.

Four things catch people out:

• Bounds are inclusive. A Minimum items of 3 means a cart of exactly 3 qualifies.
• There is no grouping. Rows fold from top to bottom. The first row is labelled When and has nothing to join to, every later row carries its own and or or, and there are no brackets and no precedence. An Inventory row’s join is locked to and.
• Negate this condition flips that one row only, not the whole set.
• An Inventory row does not judge the cart at all. It removes variants from the discount before checkout ever runs, so no other condition can rescue a skipped variant. See point 6.

4. The Discount Is Outside Its Period#

A start date of today is live today, and an end date of today runs until the end of your store’s day. If the timing looks a day out, remember the comparison uses your store’s timezone, not yours and not the shopper’s.

5. Another xDiscount Discount Won That Item#

Only one xDiscount discount applies per item, and the lowest priority number wins. New discounts default to priority 10.

Fix: open both discounts and give the one you want a lower Priority number.

6. An Inventory Condition or the Out-of-Stock Skip Excluded the Variant#

Both of these work the same way. xDiscount reads each targeted variant’s stock on the server, works out which variants fall outside your range, and writes that list into your products’ configuration. Checkout then skips them. Nothing is re-read in the cart.

That answer is a snapshot, and it can be up to a day old. It is refreshed:

• immediately, whenever you open the discount and click Save;
• once a day, at 03:00 UTC, for Active discounts that use Inventory or Skip products that are out of stock.

So a variant that sold out since the last check is still discounted, and a variant you restocked since the last check is still skipped. The builder says so next to the row: “Checked per product variant when this discount syncs, and once a day after that. Variants outside the range are skipped until the next check.”

Fix: open the discount and click Save. That takes a fresh stock reading straight away.

Two more things worth knowing. Stock is counted per variant, never summed across a product, so one size can be skipped while another is discounted. And variants that do not track inventory are never skipped, whatever bounds you set.

7. It Was a Subscription Order#

xDiscount applies to one-time purchases only. Subscription orders are excluded deliberately.

8. The xDiscount Entry in Your Shopify Discounts List Is Gone or Switched Off#

xDiscount registers one automatic discount in your Shopify admin, under Discounts, titled xDiscount. Every discount you build in the app runs through it.

Fix: open Shopify’s Discounts list and look for xDiscount. If it is there but inactive, activate it. If it is missing entirely, reinstall the app, which re-registers it.

9. Setup Never Finished#

If Home shows a red banner headed Your store isn’t fully set up, part of the install did not complete and discounts genuinely cannot apply. Click Retry setup on the banner. It runs the same setup again from inside the app, and the banner clears as soon as every step succeeds. If it still fails after a retry, reinstalling the app runs it once more with fresh permissions. The banner names the steps that failed, so keep that list if you need to report it.

Free Shipping Specifically#

Free shipping is handled separately from product discounts, so it has two extra requirements. A targeted product must be in the cart, because free shipping is attached to products like every other type, so an empty-handed cart gets nothing. And the cart must have shipping, because digital-only and local-pickup carts have no delivery options, so there is nothing to discount. When it does apply, it takes 100% off shipping, for every delivery group in the cart.

The Offer Card Isn’t Showing on a Product Page#

1. The Block Isn’t on Your Live Theme#

Go to Settings, then Storefront offer card, and read the badge.

Four situations count as not added: the block is on a theme that is not your live published theme, and publishing a new theme means adding it again; the block is present but switched off in the theme editor; your theme has no modern product template, as older “vintage” themes cannot take app blocks at all; or the block was added to a custom product template, and xDiscount checks the default product template only, so the badge can read Off while the card renders perfectly on the products using your custom template.

A theme read that fails inside Shopify’s own API lands on Couldn’t check, never on Off, and the card says in one line what went wrong. If you know the block is there and the badge still reads Off, click Check again before adding it a second time. If it persists, tell support which theme you use, because the check reads your live theme’s default product template, however large it is.

2. That Product Has No Live Offer Right Now#

The card is gated before it renders anything. No live, in-window discount on that product means no markup at all, no empty card and no heading. Check that the discount is Active, that the product is targeted, and that today falls inside the Discount period.

3. The Configuration Hasn’t Reached That Product Yet#

The card reads exactly the same configuration checkout reads. If the Sync column does not say Synced, the card is still showing the last configuration that did reach your store, or nothing at all if none ever did.

4. The Card Is There but Looks Wrong#

The card’s appearance is set in the theme editor, on the xDiscount offer block, under Text, Colours, Size and spacing and Display. A blank colour means “inherit your theme”, so if the card suddenly has a colour you did not want, look for a filled-in swatch under Colours and clear it. Card width set to anything but Full width caps the card’s width, and Full width caps nothing.

I Can’t Find Help#

There is a floating help button on every screen in the app, a round chat button in the bottom-right corner. It is there on Home, Discounts, the discount page, Analytics and Settings.

What to expect:

• Send message is never greyed out. If something is missing, clicking it marks every field that needs fixing at once and tells you why. It never withholds the reason.
• On success you get Message sent and a reference. Quote it if you write to us again about the same thing. Send another message clears the form.
• On failure you get Not sent with the reason, and everything you typed is still there. Click Send message again.
• Closing the panel, with the close button, the Escape key, or a click outside it, does not throw away a half-typed message. Reopen it and your draft is exactly where you left it.

A Change Isn’t Reaching the Storefront#

Your store’s configuration is rewritten every time you save or delete a discount, and once a day for discounts that depend on stock. Nothing else rewrites it, not a plan change and not a page view.

Re-saving a discount is the universal repair. It re-reads your plan, re-checks stock, and rewrites every product the discount targets.

Sync Says Failed or Too Large#

Saving always succeeds locally, and a failed push to Shopify never throws your work away. It is recorded on the row instead.

Home raises these for you with a red banner headed Some discounts aren’t reaching your store and a Review them button that opens Discounts already filtered. You can also filter yourself: the Filter button offers Status and Sync facets, and Sync lists Synced, Pending, Failed and Too large.

About Too large. The message gives you the exact size:

This discount configuration is 10,412 bytes, over Shopify’s 10,000-byte limit for discount functions. Shopify would store it but the discount would never apply at checkout. Reduce the number of targeted variants or rules and try again.

That limit applies to a product, counting every discount targeting it, not to one discount on its own. So target whole products instead of long lists of individual variants, use fewer conditions, use fewer gift products on a Buy X get Y, and run fewer discounts on the same product. An Inventory condition adds the list of skipped variants on top of everything else, so it costs bytes too.

xDiscount refuses the write rather than trimming it, because a stored but oversized configuration is the worst outcome of all: shoppers are shown an offer that can never apply, and nothing reports an error.

You’ve Hit a Plan Limit#

Drafts are never blocked by the active-discount limit, because only what is live at checkout counts. And a discounted order only counts when xDiscount actually reduced the price, so orders it did not touch never count.

Connect AI Is Refusing#

Other things worth checking. The endpoint is /mcp on this app’s URL, and Settings, then Connect AI, says so under the key status. The badge Key created, not used yet means no client has ever called with that key, so the problem is on the client side, while Not connected means no key exists at all. A key is shown once, under the banner Copy this now, it won’t be shown again, and only a hash of it is stored, so a lost key cannot be read back to you and you need a new one.

An Offer Is Dimmed and Says “Not Available for the Selected Variant”#

That is the card doing its job. The shopper has selected a variant the discount doesn’t cover — either you narrowed the discount to other variants, or that variant was skipped by Skip products that are out of stock or an Inventory condition at the last stock check. Checkout would charge full price on it, so the card says so instead of advertising the offer. Selecting a covered variant brings the tile back.

To cover the variant, open the discount, expand the product under Included products and tick it. For a stock skip, restock it; the next daily check, or opening the discount and clicking Save, picks it up.

Shoppers Can’t Add the Gift#

Buy X get Y is the one type with a hard dependency. A discount cannot put an item into a cart, so the storefront offer card is what puts the gift there. Without the card on your theme, a shopper has no way to claim it.

Work down this list:

1. Is the offer card on your live theme? See The offer card isn’t showing above. The card is included on every plan, Free included, so the question is only whether the block is on your live theme’s product template.
2. Did you pick gift products? The form warns “No gift chosen yet, shoppers cannot claim this offer until you pick one.” Saving it as Active with no gift is blocked outright.
3. Is a gift missing its variant? Validation says “One of your gifts has no variant. Remove it and pick it again.” A gift without a variant is skipped on the storefront, so its button never renders.
4. Does clicking a gift do nothing? The button disables itself, tries to add the item, then re-enables if the add failed. The usual causes are a gift product that is not published to your Online Store, or a variant that sold out since the window opened. A variant already sold out when the window opens does not get that far: it is greyed out as Sold out and cannot be clicked.
5. Did the cart not visibly update? The card adds the gift and then asks your theme to refresh its own cart. Some themes do not listen, so reload the page or open the cart to confirm the gift is there.
6. Was the gift added some other way? A gift added from its own product page, or restored from an old cart, is not marked as a gift and is not discounted. It has to come from the card’s gift buttons.
7. Is the trigger product still in the cart? The gift is only discounted while a product carrying that Buy X get Y discount is in the cart beside it.
8. How many gifts did you expect? Number of gift items caps the gift across the whole cart. If it is blank or unusable, the cap is 1, never unlimited.
9. Is the gift the right price? Buy X get Y is a percentage off the gift. For a genuinely free gift, set Percentage off the gift to 100.

Before You Ask for Help#

Use the floating help button in the bottom-right corner, then Questions. When you report a problem, have this ready:

• The discount’s name, Status and Sync badge from the Discounts table.
• The product page URL where you expected the offer, and your plan from Plans & billing in Settings.
• The exact wording of any banner or error message, including the step names listed if Home showed Your store isn’t fully set up.
• Your reference from a previous message, if this is a follow-up.