> For the complete documentation index, see [llms.txt](https://docs.giftcardfactory.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.giftcardfactory.app/integrations/gift-card-balance-lookup.md).

# Gift Card Balance Lookup

Gift Card Balance Lookup adds a small form to your storefront where customers can check how much they have left on a gift card — without contacting support. They enter the **last 4 characters** of the gift card code (and, optionally, their email address) and instantly see their remaining balance.

The lookup is a **theme app block**, so you can place it on any page that supports app blocks — a dedicated "Check your balance" page, the cart, the footer, or anywhere else that fits your store.

#### Key Features

* **Self-service balance checks:** Customers find their balance themselves, reducing support requests.
* **Fully customizable copy:** Header, placeholders, button label, and result/not-found messages are all editable from the theme editor.
* **Optional email verification:** Require the gift card's email alongside the code for an extra layer of confirmation.
* **No code required:** Add and configure it entirely from the Shopify theme editor.

## Adding the block to your theme

1. In the Shopify admin, go to **Online Store → Themes → Customize**.
2. Navigate to the page (or section) where you want the lookup to appear.
3. Click **Add block** → **Apps** and choose **Gift Card Balance Lookup**.
4. Position the block where you'd like it, then **Save**.

{% hint style="info" %}
The block is part of the Gift Card Factory theme app extension. If you don't see it under **Apps**, make sure Gift Card Factory is installed and its app embed/extension is enabled for the active theme.
{% endhint %}

## Configuring the block

Select the block in the theme editor to adjust its settings:

| Setting                                 | Description                                                                                                                                                   |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Use email field**                     | When enabled, customers must also enter the email associated with the gift card. Recommended for an extra verification step.                                  |
| **Header**                              | The heading shown above the form (default: *"Enter last 4 digits of your gift card"*).                                                                        |
| **Last 4 characters field placeholder** | Placeholder text for the code input.                                                                                                                          |
| **Email field placeholder**             | Placeholder text for the email input (shown only when *Use email field* is enabled).                                                                          |
| **Submit button label**                 | The text on the lookup button.                                                                                                                                |
| **Result**                              | The message shown on a successful lookup. Supports `{balance}` and `{currency}` placeholders — e.g. *"You have {balance} {currency} left on your gift card"*. |
| **Not found**                           | The message shown when no matching gift card is found.                                                                                                        |

## How it works

When a customer submits the form, the block calls the storefront balance lookup endpoint with the last characters they entered (and the email, if the field is enabled):

```
GET https://{store_name}.myshopify.com/apps/gcf/api/gift_card?last_characters={last-characters}&email={email}
```

If a matching gift card is found, its balance and currency are rendered into your **Result** message. Otherwise the **Not found** message is shown. This is the same public endpoint documented under [Searches for gift card](/integrations/gift-card-api/endpoints-and-requests/searches-for-gift-card.md).

{% hint style="warning" %}
Because customers only enter the last few characters of the code, enabling the **Use email field** option is recommended so a balance is only revealed to someone who also knows the associated email address.
{% endhint %}