Gift Cards in your theme

Gift Cards are bearer cards: anyone with the code can redeem an active card at checkout when Gift Cards are enabled. Checkout does not check whether the shopper matches the recipient email or linked customer. Recipient details control delivery; they do not restrict who can redeem the card. Anyone with the code can use it. Keep the code and the View your gift card link safe. If a code is leaked, disable the card to pause redemption or cancel it to permanently revoke its remaining balance.

Gift Cards are sold as products and spent at checkout. The platform owns checkout, the Gift Card Delivery email and text message, balances, codes and every message about them. Your theme owns everything a shopper reads around them on the storefront: the form that sends a card to someone, the recipient on the cart line, the Gift Card page, the page a recipient opens from their email, and the Gift Cards list in the customer account. A theme that leaves a piece out leaves shoppers without it: a Gift Card product without the recipient form can only be bought for yourself, and a language your theme ships without the gift card strings shows those words in your default language. This guide lists every piece, the data and actions behind it, what the checks enforce and the strings to ship, with Canvas as the worked example.

To read Canvas's files, install Canvas from the Theme Store on a development store and download it with tringify theme pull --store STORE_ID --theme THEME_ID (leave out --theme to list the store's themes). The download is compiled: Canvas's recipient form is one shared snippet in its source, and it appears in each section that uses it.

The platform serves the Gift Card page on every store, so every theme needs a template for it, as it does for product and cart pages. Give the page one section of its own and list it in theme.json:

The checks do not judge the rest of this guide: they do not look for a recipient form on your product page, or for your gift card strings in each locale file. A Theme Store review does: test every piece below on a development store with a Gift Card product before you publish (Publish in the Theme Store).

When product.is_gift_card is true, put the recipient controls inside the product's {% form 'cart_add' %}, before the Add to cart and Buy now buttons, so both send them. A Buy now button that submits the same form with purchase_intent=buy_now keeps the fields. Bind each field's maxlength (and the message counter) to forms.cart_add.<field>.max_length, the same in forms.buy_now, and declare forms in the section's ctx_needs; never write the numbers yourself. Show the email field only while forms.cart_add.gift_card_recipient_email.available is true and the phone field only while forms.cart_add.gift_card_recipient_phone.available is true: each says whether the store can deliver a card that way now (an active Gift Card delivery email template and a ready sender for email; the Gift Card delivery message sending on SMS or WhatsApp for phone). When neither is true the store cannot send a card to anyone else: leave out the whole send-as-gift switch, so the card goes to the buyer. The platform works available out only when a template reads it, once per request. Pages that read it stay cached at the edge: changing the store's Gift Card delivery email template, its email sender or its Gift Card text message route refreshes them, so the value is always current. Leaving the switch off sends the card to the buyer's own checkout email or phone. Contract rule: gift_card.recipient.

Instead of the separate fields, a script may post one gift_card_recipient field holding the JSON object {name, email, phone, message, deliver_at}; unknown keys are refused. tringify.cart.add and tringify.checkout.buyNow accept the same object. Field details: Cart actions.

The platform refuses a recipient it cannot accept (no email or phone, an invalid email or phone, a name or message that is too long, a send time that has passed) with GIFT_CARD_INVALID, and nothing is added. The response carries one message in the shopper's language: in user_errors (field gift_card_recipient) for a script, or in form_notice after a plain form post. Show it as given. Checking the fields in the browser first is a courtesy that saves a round trip; the platform's answer is the one that counts.

A small script enables the inner fieldset while the switch is on. Without script the fieldset stays disabled and the card goes to the buyer, so either enable it in markup and rely on the platform's answer, or keep the switch and fields working without script as Canvas does. Before the form posts, a script that offers a local date picker writes the chosen moment into gift_card_deliver_at with the offset of that moment, so summer time is right:

Canvas: the snippet sits in the product form of sections/main-product.vasc and sections/product-spotlight.vasc. It shows the email and phone fields by their available, words the hint and its "add a contact" message for the fields shown, and leaves out the whole switch when neither is available. Its switch is a checkbox with role="switch"; the phone field is Canvas's shared phone field; the message has a live counter; every maxlength and the counter's limit come from forms.cart_add; and with script the native date and time field becomes a picker with Now (after payment), Tomorrow morning and Pick a date, which writes gift_card_deliver_at as RFC 3339 with the shopper's offset and says when the card will send and in which time zone.

A cart line for a card sent as a gift carries gift_card_recipient: name, email, phone (E.164, for machines), phone_display (the number in its country's international format), message, deliver_at (RFC 3339 in the store's timezone, for machines such as <time datetime>) and deliver_at_display: the same moment ready to show, in store time with the store's timezone named, in the shopper's language, such as "Fri, Oct 30, 9:00 AM (Hong Kong Time)" (the year appears when it is not this year). Both are null when the card sends right after payment. Show the whole recipient on the cart page and in the cart drawer, each part that is present: who the card is for, the email, phone_display, the message and when it sends. Print phone_display and deliver_at_display as given, never phone or a date you format yourself. A message can be long: clamp it to a couple of lines and keep the full text on the page (Canvas puts it in the element's title too). A line without a recipient (gift_card_recipient null) goes to the buyer.

/gift-cards checks a balance; /gift-cards/view/{token} opens one card from the View your gift card link in the Gift Card Delivery email or text message. Both work under the store's locale prefixes (such as /fr-ca/gift-cards), are marked noindex, are never cached, and return the store's 404 page when the merchant turns off the balance check in the Gift Card settings. Both render templates/gift_card.json. Declare gift_card, forms and form_error in the section's ctx_needs.

Checking a balance on the Gift Card page requires the code, not the recipient email or a matching customer account. The lookup posts the gift_card_lookup action with one field, code: trimmed, any letter case, dashes optional. Bind the input to forms.gift_card.code (required, max_length) rather than writing your own limits. The platform adds its own proof-of-work script to this page, so a plain form submits correctly. Lookups are rate limited per visitor and per store, and every refusal (unknown code, cancelled card, too many attempts) comes back as a message in form_error. Details: Gift Cards actions.

Canvas: sections/main-gift-card.vasc shows the card above the lookup form, a Copy code button that appears only when the browser can copy and the full code is on the page, and the code in <bdi dir="ltr"> so it reads correctly in right-to-left languages. All fields: Gift Card products and purchases and Shared data shapes.

In the account template, the section that shows the customer's account declares customer.gift_cards in ctx_needs; the list is loaded only for a section that declares it. It holds items, page_size, next_url, first_url and active. Items come newest first, page_size (20) at a time. Print next_url and first_url as given (next_url is empty on the last page), and open your Gift Cards tab or panel when active is true, which means the shopper is paging through the list.

delivery_status is scheduled, sending, sent or not_sent. sent means the card was handed off for delivery; the store does not know whether it arrived, so never word it as delivered: print delivery_status_label. Print kind_label if you label the two kinds. With no cards, show an empty state from your locale files. Canvas: the Gift Cards tab of sections/main-account.vasc.

Everything the platform does not word, your theme words, through t and keys in its locale files. Put every key in your default locale file and in every other storefront locale file you ship (locales/<language>.json). A key missing from one language is not an error: the shopper sees your default language's text there, so check the files yourself. Merchants can reword any of these keys in Store Admin without editing your theme. Canvas ships these keys in all ten of its languages:

The key names are yours; only the coverage matters. Do not add keys for what the platform words: status_label, expires_at_label, kind_label, delivery_status_label, form_error.message, user_errors and form_notice messages, and express.reason_label already arrive in the shopper's language. Gift Card send times arrive ready to show (deliver_at_display, sent_at_display, scheduled_at_display); print them as given. Other dates go through the date filter, which writes them in the shopper's language. The editor labels of your Gift Card section live in the *.schema.json files, which need en, de, es, fr and it (Theme Locale Files).

To list the keys a language is missing compared with your default locale (here en), using jq:

Related: Gift Card products and purchases for the data, Cart actions and Gift Cards actions for the forms, and Theme contract for every rule.

Merchant apps edit Gift Card recipients, messages, language and delivery schedules only when the card response allows it with can_edit_delivery. Sent or in-flight cards and cards with any redemption or debit lock those details; expired, depleted, cancelled and disabled cards also refuse Resend. Resend uses the saved recipient and language. Saving a future delivery schedule creates or moves its waiting send; clearing it cancels that send and sends nothing immediately. Use the Store API card capabilities and reason wording directly in merchant integrations; these permissions do not change the shopper-facing theme contract.

Buying a gift card creates a liability, not sales revenue: gift card lines are excluded from gross, net and total sales, product sales, frequently bought together and repeat purchases. They are never taxed or discounted. Spending a gift card pays for goods, which count as sales once on the order; the payment method is gift_card. Store credit is reported as store_credit. Completed refunds to either balance reduce sales once, on the day they complete; pending or failed refunds do not. Gift cards can't be bought with a gift card or store credit. In mixed carts, gift cards apply first to the non-gift-card payable amount. Store credit then applies to that eligible amount remaining after gift cards, subject to the customer's balance and the store's per-order limits. Neither field appears for a gift-card-only cart. A direct checkout attempt is refused with GIFT_CARD_PURCHASE_TENDER_FORBIDDEN: “Gift cards can’t be bought with a gift card or store credit”. The checkout editor's SAMPLEGIFT and sample store credit follow the same rule and never spend real balances. Gift-card-only orders count as orders but are excluded from average order value. Average order value = total sales ÷ recognized orders that have sales lines. Free merchandise and fully refunded merchandise orders still have sales lines. A mixed order contributes only its sales amount. A sale notification shows that same amount; a gift-card-only order says Gift card sold and shows the gift card purchase amount. Checkout started, payment chosen and purchase event values and items exclude gift card lines.

Order and payment webhooks remain complete transaction records: their order totals include gift card purchases and their payment records include stored-value tender. They are not sales totals. Sales analytics and advertising events exclude gift card lines. Gift card movement webhooks describe liability changes, never new merchandise revenue. Timestamps are RFC 3339 in the store timezone.

Merchant balance adjustments appear in the existing balance values on the Gift Card page and customer account. Always render the current server-provided balance and status; adjustment reasons are merchant-only and must not be shown to shoppers. Cards issued by CSV follow the same Gift Card display and delivery contract as cards issued by hand. CSV exports contain only the last four code characters. See the Store API Gift Cards reference and Bulk changes with CSV imports for merchant operations.