# Gift card balance

> A form where the visitor types a gift card code and reads what is left on the card, without buying anything and without touching the cart.

Status: Ready (Smootify 2.0)  
URL: https://www.smootify.io/docs/astro/features/gift-card-balance  
Updated: 2026-10-21

With a gift card balance form, a visitor types the code of a gift card and reads what is left on it, without adding anything to the cart. Smootify asks Shopify for the balance and writes it in the form’s `[form-done]` block. The visitor’s cart is never touched. A “Check your balance” page, a block in the footer or the cart, next to the gift card field, are the usual places for it.

> [!NOTE]
> It works on every Smootify plan, the free one too, with no add-on to turn on. Gift cards must be turned on in Shopify (**Products › Gift cards**). To sell them, see [Gift cards](https://www.smootify.io/docs/astro/build/gift-cards).

## 1. Add the form

Write a `gift-card-balance` element, and put a `<form>` inside it. The form must be inside the element: without one, Smootify removes the element.

Inside the form, add:

- a text input for the code. Set its `name` to `gift-card`. Smootify also reads `Code`, `Gift Card`, `gift_card`, `giftcard`, `giftcardcode` and `Gift card code`, in any case;
- a submit button.

```html
<gift-card-balance data-error-not-found="Code not found or already used">
  <form>
    <input name="gift-card" placeholder="Gift card code">
    <input type="submit" value="Check balance">
  </form>
  <div form-done hidden>Balance: <span gift-card="balance">€0.00</span> on <span gift-card="code">•••• 0000</span></div>
  <div form-fail hidden>Code not found or already used</div>
</gift-card-balance>
```

The visitor can type the code however they like: with or without capital letters, and with or without spaces or dashes between its groups (`ABCD EFGH IJKL MNOP`, `ABCD-EFGH-IJKL-MNOP`).

Labels, the placeholder, the layout and where the form goes are up to your design.

## 2. Show the balance

Smootify writes two values. Put them in the `[form-done]` block, which shows when the code is found:

- `gift-card="balance"`: what is left on the card. When the card is in the currency of the visitor’s market, it uses the site’s price format. When it is in another currency, such as a card in euros read on a Swiss franc market, it shows in the card’s own currency.
- `gift-card="code"`: the end of the code, such as ”•••• 4F2A”, so the page never repeats the whole code.

Each one goes on an element, or on a span inside an element, as in “Balance: €25.00 on •••• 4F2A”. Both are optional: use only the ones your design needs.

**A card used up.** Shopify does not apply a card with nothing left on it, and answers as it does for an unknown code. So the visitor sees the `[form-fail]` block, not a balance of 0: write the error to cover both (see step 3).

## 3. The error

When Shopify does not find the code, the `[form-fail]` block shows. Shopify does not say why: the code can be wrong, or the card disabled, expired or used up. So there is one message for all four, and it is worth saying so, such as “Code not found or already used”. A link to buy a gift card fits next to it.

Smootify writes the message in the element inside `[form-fail]`, in place of the text you type there. It is “Gift card not found” unless you write your own in the attribute `data-error-not-found` on `gift-card-balance`, such as `data-error-not-found="Code not found or already used"`. Use it to write the message in your site’s language. A form sent without a code shows the same message.

Example: `gift-card-balance` with `data-error-not-found="Code not found or already used"` and a code field named `Gift Card`.

| Result | What the visitor sees |
|---|---|
| Code found | the Success message in place of the Form: "Balance €25.00 on •••• 4F2A", from `gift-card="balance"` (site price format) and `gift-card="code"` (the last characters) |
| Not found or used up | the Error message with the text of `data-error-not-found`; Shopify gives no reason, so a wrong, disabled, expired or used-up card shows the same message |

## Where to put it

- **A “Check your balance” page**, linked from the footer or from the gift card’s product page.
- **The footer**, in a component every page uses.
- **In the cart**, next to the gift card field, so the visitor checks a card before applying it. The cart keeps the two forms apart: the balance form never applies the card, and the cart’s own field does that (see [Discounts, notes and progress bars](https://www.smootify.io/docs/astro/build/cart-extras)).

## Before you publish

> [!STUCK]
> - **The element disappears from the page.** The `<form>` is not inside `gift-card-balance`. Move it inside the element.
> - **A valid code is not found, in a form with more than one field.** The code field's `name` is not one Smootify reads, so it takes the first filled field instead. Set the `name` back to `gift-card`.
> - **The error message is in English.** Write your own in `data-error-not-found`.
> - **A customer asks why their code is "not found".** Shopify gives no reason: the code is wrong, or the card is disabled, expired or used up. Check the card in the Shopify admin, under **Products › Gift cards**.