Why is my gift not showing?
The most common question, and the one most often answered in a single call.
Ask: "My free gift isn't showing on the storefront. What's wrong?"
Step 1 — Ask the store, not the theme
Call get_setup_health. It already reaches a conclusion, and its issues list names the cause.
Four codes cover almost everything:
| Code | What it means | Fix |
|---|---|---|
APP_EMBED_DISABLED | The app embed is off on the live theme, so nothing can render | Turn on the app embed in the theme editor |
THEME_NOT_OS2 | The live theme does not support app blocks | Switch to a theme that does |
NO_CAMPAIGN | The store has no campaigns at all | Create one |
NO_ACTIVE_CAMPAIGN | Campaigns exist, none of them is running | Activate one, or check its schedule |
If issues names one of these, stop here. That is the answer.
get_setup_health also reports which theme is live. A surprising number of "it disappeared"
reports are a theme that was published without the app embed being switched on in the new one —
settings do not carry across when you publish a different theme.
Step 2 — If setup is clean, look at the campaign
An empty issues list means the widget can render, so the problem is that the offer's own
conditions are not being met.
Take the campaign id from the activeCampaigns list that get_setup_health already returned, and
call get_campaign_details on it.
Check, in this order:
- Schedule — has it started, has it ended
- Target pages — the widget only appears where the campaign says it should
- Trigger conditions — cart value, quantity, or collection thresholds that the test cart may not be meeting
- Gift products — configured at all, and still existing
Step 3 — If the campaign looks right, check the gift itself
A campaign can be live and correct while the gift silently fails to add, because the product cannot be given. Take the gift product's handle and follow Can this product be gifted?.
What you finish holding
Either a named cause with a fix, or a specific ruling-out: setup is clean, the campaign is live and its conditions are X, and the gift product is available. That is a much better support ticket than "the gift isn't showing".