Most stores let the checkout block handle free gifts. Some brands want the gift visible earlier: the buyer types a code on the cart page and sees the gift in the cart before checkout starts. This guide is for the developer or agency building that. It needs theme work, so if you have no developer on the store, the checkout block alone is the better choice.
How the pieces fit
Smart Checkout Widgets answers one question for the theme: what is this gift code worth? The theme does the rest.
- The theme asks the app for the offer through the store's app proxy.
- The theme shows the gift, or the choice of gifts, and adds the line to the cart.
- The theme applies the code and reads Shopify's answer on whether it applies.
- The checkout block and discount function take over at checkout.
Looking up an offer
The request goes to your own store's domain:
GET https://your-store.com/apps/scw/gift?code=HAPPY60A match returns { found: true, offer: { ... } } with the code, the gifts, how many the buyer can choose, the requirement, and the line properties to use. Anything else returns 404 with { found: false }.
That 404 covers every way a code can fail: unknown, ended, not started, an automatic gift, or a discount that was deleted or switched off in Shopify. The response doesn't tell a guesser which, and the endpoint answers for one code at a time and never lists your catalog, so codes for a promotion that hasn't started stay private.
Stamping the gift line
Add the gift to the cart with the line properties from the offer. They tell the checkout block and the discount function that this line is a gift. Without them the line is an ordinary product at full price, and it counts toward the buyer's spend threshold.
Checking whether the cart qualifies
The lookup doesn't say whether this cart qualifies. Apply the code, then read discount_codes[].applicable from /cart.js. That value comes from the discount function, so it already covers customer eligibility and currency conversion. Don't rebuild those rules in the theme, because the two will drift apart.
Keep the checkout block on
Nothing removes a gift on the cart page. If a buyer drops below the threshold or removes the code, the line stays in the cart until something takes it out. The checkout block does that, so leave it placed in checkout even when the cart page does all the visible work.
One gap remains. Express checkout buttons can skip the block, and a cart-page gift can travel with them. If your store leans on express checkout, test that path with a real order before launch.
Before you launch
- Try a live code, an ended code and a made-up code. The last two should look identical to the theme.
- Place a test order and confirm the gift line carries its properties.
- Remove the qualifying product at checkout and confirm the gift comes off.
- Handle a
503quietly. It means the app could not answer right now, and the cart should carry on without the gift prompt.
The same lookup returns 404 when a store is paused for going over its plan's order limit, since the discount would not apply. For the gift itself, see how automatic gifts work in checkout.
Frequently asked questions
Do I need a developer for cart-page gifts?
Yes. The app provides the offer lookup, but the theme has to call it, show the gift and add the line. Without theme work, use the checkout block on its own.
Can buyers list every gift code through the endpoint?
No. It answers for one code at a time and returns the same 404 for every code that isn't a live gift offer.
Does the checkout block still need to be installed?
Yes. Nothing removes a gift on the cart page, so the checkout block is what takes a gift off when the buyer no longer qualifies.
How do I know if the cart qualifies?
Apply the code and read discount_codes[].applicable from /cart.js. That is the discount function's own answer.