> 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/theme-app-embeds.md).

# Theme App Embeds

Gift Card Factory ships a few **storefront blocks** you can add to your Online Store theme. They surface gift-card features directly on your shop — a balance checker, the "send a gift card to a friend" fields, and a rewards banner.

{% hint style="success" %}
**You don't need these in general.** Gift Card Factory's core features — bulk operations, campaigns, Flow automations, rewards, reminders, and refunds — all run from the app admin and work **without touching your theme**. The storefront blocks below are only required for a couple of specific, storefront-facing features. If you're not using those features, you can safely ignore this page.
{% endhint %}

## When do I actually need a block?

| Block                        | Needed when…                                                                                                                                 | Otherwise                                      |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| **Gift Card Postman**        | You run a **Gift Card Postman** campaign and want shoppers to enter the recipient's details, a message, and a send date on the product page. | Not needed.                                    |
| **Gift Card Balance Lookup** | You want customers to **check their own gift card balance** on your storefront.                                                              | Optional — purely a convenience.               |
| **Gift Card Reward Banner**  | You want shoppers to see the **gift card reward they'll earn** — calculated from your active Gift Card Rewards campaign — in the cart.       | Optional — the rewards still apply without it. |

In short: **only the Gift Card Postman block is ever "required", and only while a Postman campaign is active.** Everything else is optional.

## What does NOT need a theme block

These features work entirely from the admin and never touch your theme:

* **Bulk operations** — creating, updating, and sending gift cards, store credit, and discount codes.
* **Gift Card Rewards** — issuing rewards after orders (the reward is applied automatically; the banner only *shows* the shopper what they'll earn).
* **Gift Card Reminders**, **Scheduled Gift Cards**, and **Scheduled Store Credit**.
* **Gift Card Refunds**.
* **Shopify Flow** triggers and actions.

If your use case is on this list, you're done — no theme changes required.

## Checking status from the dashboard

The **Theme app embeds** card in your dashboard (right rail) shows, per theme, which blocks are installed:

* Pick a theme from the selector — status is re-checked for that theme.
* Each block shows a **Required / Optional** tag and an **Installed / Not installed** tag.
* If a *required* block is missing on the selected theme, the card shows a red alert and an **Install** button.
* **Optional** blocks show an **Add to theme** button; installed blocks show **Manage**.

{% hint style="info" %}
"Required" is decided server-side: the Gift Card Postman block is only marked required while you have an **active Gift Card Postman campaign**. With no active Postman campaign, every block reads as **Optional**.
{% endhint %}

## Adding a block to your theme

All three are **theme app blocks** — you add them to a section from the theme editor (they are not global "app embed" toggles).

1. In the Shopify admin, go to **Online Store → Themes → Customize** (or use the **Install / Add to theme** button on the dashboard card, which opens the editor on the right template).
2. Navigate to the page or section where the block belongs:
   * **Gift Card Postman** → your gift card **product** page.
   * **Gift Card Reward Banner** → the **cart** page.
   * **Gift Card Balance Lookup** → any page that fits (a dedicated "Check your balance" page, the footer, etc.).
3. Click **Add block → Apps** and choose the block.
4. Position it, then **Save**.

{% hint style="warning" %}
If you don't see the block under **Apps**, make sure Gift Card Factory is installed and its theme app extension is enabled for the theme you're editing. Some older themes don't support app blocks — if that's the case, contact us at <support@code57.pl> and we'll help you set it up.
{% endhint %}

## Related pages

* [Gift Card Postman](/campaigns/gift-card-postman.md) — the campaign that uses the Postman block.
* [Gift Card Balance Lookup](/integrations/gift-card-balance-lookup.md) — full settings reference for the lookup block.
* [Gift Card Rewards](/campaigns/gift-card-rewards.md) — the campaign the reward banner promotes.