/gift-cards/lookup
{% form 'gift_card_lookup' %}
Checks a Gift Card's balance, status and expiry on the store's Gift Card page. The code itself is never shown back.
Form fields
-
codeRequired The Gift Card code, with or without dashes, in any letter case.
-
_formatOptional Set to json when submitting with fetch; omit for the normal browser redirect.
Validation
Requires the Gift Card code, not the recipient email or a matching customer account. Requires the CSRF token and a solved verification challenge for every lookup: the platform adds the script that solves it to the Gift Card page, so a plain form post from that page works in any browser with JavaScript. A wrong code, a code from another store, a card that is not delivered yet and a store that turned the Gift Card page off all return the same error, GIFT_CARD_NOT_FOUND, so a lookup never reveals why it failed. The code is matched like at checkout: letter case, dashes and surrounding spaces are ignored.
Limits
Lookups are limited per visitor address on each store and per store; past the limit the action returns CHECKOUT_GIFT_CARD_TOO_MANY_ATTEMPTS until the budget refills. One solved challenge allows one lookup.
Response
Form mode renders the gift_card template again (HTTP 200) with ctx.gift_card filled: code is null and code_masked shows the last four characters. A refusal renders it with ctx.gift_card null and the message in ctx.form_error. JSON: {success:true, gift_card} with gift_card in the ctx.gift_card shape, or HTTP 400 (not found), 403 (challenge_required: true, solve and resubmit) or 429 with success: false and user_errors.
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.