> 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 %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.giftcardfactory.app/integrations/gift-card-balance-lookup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.