# Welcome to Gift Card Factory!
Help all merchants save time and boost customer engagement by streamlining the creation, management, and delivery of gift cards at scale.
π Gift Card Factory β At a Glance
* **Core Functionality**: Enables merchants to create, import, update, and send gift cards in bulk. It also supports gift card refunds and balance reminders.
* **Scheduling and Messaging**: Offers a "Gift Card Postman" extension, allowing customers to schedule gift card delivery directly from the product page with custom messages.
* **Efficiency & Integration**: Designed for time-saving through features like auto-generating thousands of codes, importing from external platforms, and updating card properties (balance, expiry date, etc.). Works directly within the Shopify admin, supports latest themes, and integrates with tools like Shopify Flow and Klaviyo.
* **Plans & Pricing**: Offers a free trial period, followed by tiered subscription plans (Bronze, Silver, Gold, etc.) that vary in monthly limits for actions like sending scheduled emails or processing reminders/refunds.
# Gift Cards vs Discount Codes vs Store Credit
π€ Choosing between gift cards, discount codes, and store credit.
Gift Card Factory works with three types of value you can give to customers: **gift cards**, **discount codes**, and **store credit**. They look similar at first, but they behave very differently at checkout, in your accounting, and in how the customer experiences them. Picking the right one is usually the most important decision when planning a campaign.
### **π§ Quick Summary**
* **Gift card** β a code anyone holding it can spend. [Used as a payment method at checkout](https://shopify.dev/docs/api/admin-graphql/latest/objects/GiftCard). Best for transferable, prepaid balances.
* **Discount code** β a code that reduces the price of an order. Treated as a discount, not a payment. Best for promotions and incentives.
* **Store credit** β [a monetary balance attached to a customer record, redeemable at checkout](https://shopify.dev/docs/api/admin-graphql/latest/objects/StoreCreditAccount). Best for refunds, compensation, and account-bound rewards.
{% hint style="warning" %}
**Store credit has an important prerequisite.** Per Shopify, *"the account balance is redeemable at checkout only when the owner is authenticated via **new customer accounts** authentication"* ([source](https://shopify.dev/docs/api/admin-graphql/latest/objects/StoreCreditAccount)). If your store still uses classic customer accounts, customers won't be able to spend their store credit at checkout. You can check or change this in **Shopify Admin β Settings β Customer accounts**.
{% endhint %}
### **π Side-by-Side Comparison**
| Attribute | Gift Card | Discount Code | Store Credit |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Shopify resource** | [`GiftCard`](https://shopify.dev/docs/api/admin-graphql/latest/objects/GiftCard) | [`DiscountCodeBasic`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/DiscountCodeBasicInput) and related types | [`StoreCreditAccount`](https://shopify.dev/docs/api/admin-graphql/latest/objects/StoreCreditAccount) |
| **What it is** | Stored value (a Shopify gift card) | A coupon-style code with rules | Account balance on a customer record |
| **Treated at checkout as** | Payment method | Discount on the order | Payment method (account balance) |
| **Account requirement** | None β anyone with the code can redeem | None β depends on eligibility rules | **Customer must be logged in via new customer accounts** ([Shopify docs](https://shopify.dev/docs/api/admin-graphql/latest/objects/StoreCreditAccount)) |
| **Tied to a customer?** | Optional (recipient/customer fields) | Optional (eligibility can target customers or segments) | Yes β always tied to one customer record (or a `CompanyLocation` for B2B, but Gift Card Factory only supports Customer) |
| **Transferable?** | Yes β anyone with the code can redeem it | Yes β any customer matching the eligibility rules can use the code | No β *"the accountβ¦has an owner that cannot be transferred"* ([source](https://shopify.dev/docs/api/admin-graphql/latest/objects/StoreCreditAccount)) |
| **Code required at checkout?** | Yes (the gift card code) | Yes (the discount code) | No β applies automatically when the customer is logged in |
| **Reduces order subtotal?** | No (it's a payment, not a discount) | Yes | No (it's a payment) |
| **Has an expiry option?** | Yes (`expiresOn`, never / relative / specific) | Yes (`startsAt` / `endsAt`) | Yes (per-credit-transaction `expiresAt`, or never) |
| **Multiple uses?** | Until the balance is depleted | `usageLimit` (total) and `appliesOncePerCustomer` (per customer) | Until the balance is depleted |
| **Counts as revenue when?** | When redeemed at checkout | Reduces revenue per order at checkout | When redeemed at checkout |
| **Refund-friendly?** | Yes (issue a new card) | Less so (codes are not designed for refunds) | Yes β common channel for refunds |
| **Native Shopify email?** | Yes β Gift card created notification | No β emailing is up to the merchant | Yes β Store credit issued notification |
| **Re-enable after disabling?** | **No.** *"After a gift card is deactivated, it can't be used for further purchases or re-enabled"* ([source](https://shopify.dev/docs/api/admin-graphql/latest/objects/GiftCard)) | Codes can be disabled and re-enabled in Shopify Admin | Balance can be debited but the account itself cannot be deactivated |
### **π― When to Use Which**
#### Use a **gift card** whenβ¦
* Someone is paying for a value voucher (you sell gift cards as products).
* You're running a giveaway, contest, or influencer campaign and want recipients to get prepaid balance.
* You're rewarding employees or partners with transferable value.
* Refunds need to remain transferable (e.g. the original buyer was a third party).
* The recipient may not be logged in (or may not exist as a customer record).
β See: [Autogenerate](/bulk-operations/autogenerate), [Bulk Send](/bulk-operations/bulk-send), [Bulk Update](/bulk-operations/bulk-update), [Import From File](/bulk-operations/import-from-file)
#### Use a **discount code** whenβ¦
* You want to offer a percentage- or fixed-amount discount on purchases.
* You're driving acquisition (welcome codes), conversion (flash sales), or retention (VIP codes).
* You want stacking rules (combine with product / order / shipping discounts), minimum-purchase requirements, or product/collection targeting.
* You want unique tracking codes for influencers, channels, or partner campaigns.
β See: [Discount Codes Bulk Create](/bulk-operations/discount-codes-bulk-create), [Discount Codes Bulk Send](/bulk-operations/discount-codes-bulk-send), [Discount Codes Import From File](/bulk-operations/discount-codes-import-from-file)
#### Use **store credit** whenβ¦
* You're issuing a refund as in-store value rather than cash back.
* You're compensating a known customer for a service issue.
* You're rewarding loyalty members with account-bound balance.
* You want the value to apply automatically at checkout, without the customer having to enter a code.
* **Your store uses new customer accounts** β without this, customers can't redeem the credit.
β See: [Store Credit Bulk Add](/bulk-operations/store-credit-bulk-add), [Store Credit Import From File](/bulk-operations/store-credit-import-from-file)
### **π οΈ Available Operations Per Type**
| Need | Gift Card | Discount Code | Store Credit |
| --------------------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Generate codes (no email) | [Autogenerate](/bulk-operations/autogenerate) | [Discount Codes Bulk Create](/bulk-operations/discount-codes-bulk-create) | *N/A β store credit always targets a customer* |
| Generate + email recipients | [Bulk Send](/bulk-operations/bulk-send) | [Discount Codes Bulk Send](/bulk-operations/discount-codes-bulk-send) | [Store Credit Bulk Add](/bulk-operations/store-credit-bulk-add) |
| Update existing | [Bulk Update](/bulk-operations/bulk-update) | *Edit individually in Shopify Admin β Discounts* | *Adjust individually in Shopify Admin β Customers* |
| Import from CSV | [Import From File](/bulk-operations/import-from-file) | [Discount Codes Import From File](/bulk-operations/discount-codes-import-from-file) | [Store Credit Import From File](/bulk-operations/store-credit-import-from-file) |
| Per-row scheduling in CSV | [Multiple Imports From a Single File](/bulk-operations/import-from-file/multiple-imports-from-a-single-file) | *Not supported* | *Not supported* |
### **β Common Points of Confusion**
**"Which one is best for refunds?"**\
Usually **store credit** when the original buyer is the same person being refunded β Shopify treats it cleanly as account balance, and there's a native "Store credit issued" notification. Use **gift cards** if the buyer was a third party (corporate buyers, gift purchasers) since gift cards are transferable and don't require a customer account.
**"Can a customer share their store credit with someone else?"**\
No. Per Shopify, a store credit account *"has an owner that cannot be transferred"* ([docs](https://shopify.dev/docs/api/admin-graphql/latest/objects/StoreCreditAccount)). It applies only when that owner is logged in. If you need transferable value, use a gift card.
**"Will a discount code work alongside a gift card or store credit?"**\
Yes β discount codes reduce the order subtotal, then gift cards / store credit apply as payment for whatever's left. Stacking with *other* discount codes depends on the **Combines with** flags ([`DiscountCombinesWithInput`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/DiscountCombinesWithInput)) on each code.
**"Does store credit count as a discount for accounting?"**\
No. Both gift cards and store credit are recognized as **payment** at checkout, not as a price reduction. Discount codes are the only one of the three that reduce reported order revenue.
**"Can I email a discount code only to the people I list, not to everyone?"**\
Yes. With [Discount Codes Bulk Send](/bulk-operations/discount-codes-bulk-send), each recipient gets a unique code. You can additionally set per-code usage limits (e.g. one use per customer via Shopify's `appliesOncePerCustomer`) so even if the code is shared, only one redemption per customer is allowed.
**"What if my customer doesn't have a Shopify customer record yet?"**\\
* For **gift cards**, recipients without a customer record can be skipped or auto-created (configurable per operation).
* For **discount codes**, no customer record is needed β codes are independent of customers (unless you set Eligibility to specific customers/segments).
* For **store credit**, a customer record is required. Imports from file auto-create one from email if needed; the bulk-add form skips recipients without an existing record.
**"My store still uses classic customer accounts. Can I issue store credit?"**\
You can issue it, but customers won't be able to redeem it at checkout until you switch to **new customer accounts**. Per Shopify's docs, store credit is only spendable when the owner is authenticated via new customer accounts. Switch under **Settings β Customer accounts** in Shopify Admin.
**"I issued a gift card for the wrong amount β can I just edit it?"**\
You can edit the balance via [Bulk Update](/bulk-operations/bulk-update) (using the `balance` column). However, you **cannot re-enable a gift card** once it's been deactivated β Shopify explicitly disallows this ([docs](https://shopify.dev/docs/api/admin-graphql/latest/objects/GiftCard)). If you need to fix a deactivated card, issue a new one.
### **π Related Reading**
* [Recipients Selector](/misc/recipients-selector) β the four ways to pick recipients across operations.
* [Customers Query Selector](/misc/customers-query-selector) β the syntax for dynamic recipient queries.
* [Sending Customer Notifications](/misc/sending-customer-notifications) β how email delivery works for each method.
* Shopify reference: [GiftCard](https://shopify.dev/docs/api/admin-graphql/latest/objects/GiftCard), [StoreCreditAccount](https://shopify.dev/docs/api/admin-graphql/latest/objects/StoreCreditAccount), [DiscountCombinesWithInput](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/DiscountCombinesWithInput).
# Autogenerate
π Auto-Generate Gift Cards
With autogenerate you can quickly generate any number of gift card codes. After creation you can have the codes emailed to you, made available as a downloadable file, or both.
### π‘ **Common Use Cases**
* **Partner Stores**: Collaborate with third-party sellers to distribute gift cards for resale or promotions, expanding your market reach.
* **Printed Gift Cards**: Create physical gift cards with unique codes for distribution in retail locations or events as tangible reminders for redemption.
* **Giveaways & Contests**: Use gift cards as prizes in online contests or social media campaigns to boost brand visibility and attract new customers.
* **Influencer Campaigns**: Send gift cards to influencers to try your products and promote your store, reaching broader audiences through their credibility.
These strategies make gift cards a key component of your promotional efforts, helping to engage customers and drive sales.
### **π Form Fields Explained**
* **Value**: The initial balance of each gift card. Only your store's main currency is supported.\
If the card is used in a different market, the value is automatically converted at checkout.
* **Count**: The number of gift cards you want to generate.
* **Code Length**: The number of characters in each code (between **8 and 16**).\
Codes consist of random **letters and numbers**.
* **Gift card expiry**: Choose one of three options:
* **Gift cards never expire** β codes have no expiration.
* **Gift cards expire relative to creation date** β set a duration in days, weeks, months, or years from the moment each card is created.
* **Gift cards expire on a specific date** β pick an exact calendar date.
* **Internal Note**: A private note attached to the gift card.\
This is **only visible to store staff**, not customers. Maximum length is 255 characters.
* **Prefix**: Optional. Enable the **Prefix gift card** checkbox to add a fixed prefix to every generated code.\
Up to **4 characters**, alphanumeric (`a-z`, `0-9`) only.
### **π€ Internal Delivery Options**
After the codes are generated you can choose how to receive them:
* **Allow gift cards data download**: Creates a download link in the **Bulk Operations** section. The link expires after **3 days** and is accessible to anyone with access to the app.
* **Send internal email with all generated gift cards codes**: Sends the full list of codes to an email address you specify. You can enter multiple addresses separated by a comma.
You can enable either option, both, or neither.
### **βΆοΈ Running the Operation**
Two buttons are available at the bottom of the form:
* **Create now**: Runs the operation immediately.
* **Schedule**: Runs the operation at a future date and time you select.
### **FAQ**
**I didn't receive the email with my gift cards. What should I do?**\
First, check your spam or junk folder.\
If you still can't find it, please contact us at **** for help
# Bulk Send
π Send multiple gift cards in one go β fast, personalized, and automated.
The **Bulk Send** feature lets you quickly send personalized gift cards to multiple recipients at once. You can customize the gift card value, expiration, and message, and decide how each card is assigned to a customer record. If a recipient doesn't have a customer record in your store, you can choose to skip them or create one on the fly. Ideal for promotions, rewards, and seasonal campaigns.
### π‘ **Common Use Cases**
* **Employee Benefits and Recognition**: Boost morale with gift cards as one-time rewards or part of a monthly allowance.
* **Celebratory Occasions**: Offer birthday gift cards to employees or customers for a personalized touch.
* **Seasonal and Holiday Celebrations**: Run gift card campaigns during holidays to reward employees and engage customers.
* **Customer Loyalty and Retention**: Use gift cards to retain loyal customers or win back inactive ones.
* **Apology and Compensation**: Provide gift cards as compensation for service disruptions to maintain customer trust.
* **Product Launches and Store Openings**: Distribute gift cards to create buzz and attract customers to new products or stores.
* **Event Participation Encouragement**: Offer gift cards to boost participation and engagement at events.
### **π Form Fields Explained**
* **Value**: Initial balance of each gift card, in the store's main currency. Conversion happens automatically at checkout if the card is used in a different market.
* **Code Length**: Number of characters in each code (between **8 and 16**). Codes are random letters and numbers.
* **Gift card expiry**: Choose one of three options:
* **Gift cards never expire** β codes have no expiration.
* **Gift cards expire relative to creation date** β set a duration in days, weeks, months, or years from the moment each card is created.
* **Gift cards expire on a specific date** β pick an exact calendar date.
* **Recipients**: Choose how to provide who receives the gift cards (see [Recipient Input Methods](#recipient-input-methods) below).
* **Message**: Custom message included in the gift card email. Maximum 200 characters.
* **Internal Note**: Private note attached to each gift card. Visible only to store staff, not customers. Maximum 255 characters.
### **π₯ Recipient Input Methods**
There are four ways to specify recipients. Switch between them using the tabs above the recipients field.
* **Manual list of emails**: Paste or type a list of email addresses, separated by commas or new lines.
* **Select customers**: Pick individual customers from your Shopify store using the customer picker modal.
* **Select customer segment**: Pick an existing Shopify customer segment. All members of the segment become recipients.
* **Customers query**: Enter a Shopify customer search query (for example `tag:vip` or `orders_count:>5`). The recipient list is resolved at execution time, so any customer matching the query when the operation runs will receive a card.
> See the [Recipients Selector](/misc/recipients-selector) page for a deep dive on each method, including limits and recommended use cases. For query syntax, see the [Customers Query Selector](/misc/customers-query-selector).
### **πͺͺ Customer Handling**
Two settings control how each gift card is associated with a customer record.
**If a customer doesn't exist in your store** β choose one:
* **Skip creating gift card**: Recipients without a matching customer record are skipped entirely.
* **Create customer and create gift card**: A new customer record is created on the fly, then the gift card is issued to them.
**Assign recipients to gift card** β choose where the recipient is attached on the gift card record:
* **Recipient field**: The customer is set as the recipient of the gift card (they receive a notification with the message).
* **Customer field**: The customer is set as the owner of the gift card. *Note: assigning to the customer field ignores the message.*
* **Customer and Recipient field**: The customer is set as both.
### βοΈ **Sending Method**
You can choose how recipient emails are sent: **Shopify Email**, **App Email**, **Shopify Flow**, or **Klaviyo**.\
Read more about each option in [Sending Customer Notifications](/misc/sending-customer-notifications).
When **App Email** is selected, you also choose an email template (built from the **Bulk send** or **Custom** template types) and can preview it before sending.
### **π€ Internal Delivery Options**
These options control how *you* (the merchant) receive a record of the operation β they are independent of how recipients are notified.
* **Allow gift cards data download**: Creates a download link in the **Bulk Operations** section. The link expires after **3 days** and is accessible to anyone with access to the app.
* **Send internal email with all generated gift cards codes**: Sends the full list of codes to an email address you specify. You can enter multiple addresses separated by a comma.
You can enable either option, both, or neither.
### **βΆοΈ Running the Operation**
Two buttons are available at the bottom of the form:
* **Send now**: Runs the operation immediately.
* **Schedule**: Runs the operation at a future date and time. You select a timezone, start date, and start time.
**The recipient doesn't exist as a customer β what happens?**\
It depends on your **If a customer doesn't exist in your store** choice. With **Skip**, that recipient is left out. With **Create**, a new customer is created and the gift card is issued to them.
**Why is my message ignored?**\
You've selected **Customer field** under "Assign recipients to gift card". This setting attaches the gift card to the customer record only and does not trigger a recipient email β switch to **Recipient field** or **Customer and Recipient field** to include the message.
# Bulk Update
βοΈ Update many existing gift cards at once via a CSV file.
With **Bulk Update** you can update many existing gift cards at once by uploading a CSV file. The fields you can update include:
* Expiry date
* Balance
* Note
* Message (sent in the recipient email)
* Customer (by `customer_id` or `email`)
* Recipient (by `recipient_id` or `recipient_email`)
* Gift card state (only changes from *enabled* to *disabled* are allowed β Shopify does not allow re-enabling a disabled gift card)
To update a gift card, you need its **gift card ID**.
{% hint style="info" %}
Gift card ID is different from gift card code. You can export gift card IDs by going to **Products β Gift Cards**, selecting gift cards and clicking **Export** at the top. We also include gift card IDs in the CSV every time you import or autogenerate gift cards.
{% endhint %}
### π‘ **Common Use Cases**
* **Reloading gift card balances**: Top up partially used cards for customer retention or promotional campaigns. You can increase the balance of multiple cards in one action.
* **Extending gift card validity**: Honor expired cards or adjust expiry dates after a policy change. Gives customers more time to redeem.
* **Bulk disabling unused gift cards**: Deactivate cards to prevent unauthorized use and keep active inventory clean.
### **π CSV Columns**
Only `gift_card_id` is required. Remove any columns you don't want to update.
| Column | Required | Notes |
| ----------------- | :------: | --------------------------------------------------------------------------------------------------- |
| `gift_card_id` | β | Numeric gift card ID (not the code). |
| `disabled` | | Set to `true` to disable the card. You can only disable cards β Shopify does not allow re-enabling. |
| `expires_on` | | Expiry date in `YYYY-MM-DD` format. |
| `customer_id` | | Numeric customer ID. Sets the **Customer** field on the gift card. |
| `email` | | Customer email. Used as an alternative to `customer_id` to set the customer. |
| `recipient_id` | | Numeric customer ID. Sets the **Recipient** field on the gift card. |
| `recipient_email` | | Recipient email. Used as an alternative to `recipient_id`. |
| `message` | | Custom message sent in the recipient email. |
| `note` | | Internal note, visible to staff only. |
| `balance` | | New balance for the card. |
### **πͺ Step-by-Step Instructions**
1. **Download the CSV template.**\
Use the file below as a starting point.
{% file src="/files/UUR8tclWG7c3weu8bO5P" %}
Optionally you can open and copy our Google Sheet template:
* [Template](https://docs.google.com/spreadsheets/d/1z-BAHW_JUGbPbClAzIGfiqLb1GD5gkWPpCNsnxJJqS4/edit?usp=sharing)
2. **Remove unused columns and populate rows.**\
Only `gift_card_id` is required. Remove any columns you don't want to update, then fill in your data.
3. **Upload the file in the app.**\
The form accepts `.csv`, `.tsv`, and `.txt` files, up to **10 MB**. After upload, a summary shows the detected separator, row count, and column names. Columns highlighted in green match the expected names.
4. **Choose whether to receive a summary email.**\
Enable **Send a summary with process results** to get a one-time email with a CSV showing the result of each update. You can enter multiple email addresses separated by a comma.
5. **Click Update now or Schedule.**\
**Update now** runs the operation immediately. **Schedule** runs it at a future date and time you select.
### **βΆοΈ Running the Operation**
Two buttons are available at the bottom of the form:
* **Update now**: Runs the operation immediately.
* **Schedule**: Runs the operation at a future date and time. You select a timezone, start date, and start time.
The submit button stays disabled until a valid file with no row-level errors is uploaded.
### **FAQ**
**My file uploaded but the app says "No matching columns found".**\
The column header names in your file don't match the expected names. Compare against the template above β column names are case-sensitive.
**Why can't I re-enable a disabled gift card?**\
Shopify does not allow re-enabling gift cards once disabled. The `disabled` column only supports going from enabled to disabled.
**I didn't get the summary email.**\
The summary is only sent if **Send a summary with process results** was enabled before the operation ran. Check your spam folder, or contact us at ****.
# Import From File
π Use a CSV source file to import gift cards.
The **Import from File** feature creates Shopify gift cards in bulk from a CSV file. You define value, code, expiration date, recipient, and message per row. Optionally, the app can email each gift card to its recipient after creation. Ideal for migrating from another platform, fulfilling corporate orders, or processing batches collected from external systems.
### π‘ **Common Use Cases**
* **Migrating gift cards from another platform** β bring existing gift cards into Shopify when moving from another e-commerce or POS system.
* **Corporate or bulk orders** β issue large numbers of gift cards for corporate clients, employee rewards, or event giveaways.
* **Physical gift card fulfillment** β upload pre-generated codes to be printed on physical cards for in-store or retail distribution.
* **External system handoff** β import orders collected via spreadsheets, forms, or tools like Typeform or Airtable without retyping.
### **πͺ Step-by-Step Instructions**
1. **Download a template.** A simple template (just the basics) and an extended template (every supported column) are available below.
{% hint style="info" %}
You can **remove** any column you don't need. The only required column is: `initial_value`.
{% endhint %}
{% file src="/files/osKFMemnvYY9zTBspw4g" %}
{% file src="/files/UmSs0AJ81vQqC6KsA4N4" %}
Optionally, copy our Google Sheet templates:
* [Simple](https://docs.google.com/spreadsheets/d/1dGLJE-ZTzG6AKl8Rz1xxXtbbwBZ2pWd9YcKv-OVGuvo/edit?usp=sharing)
* [Extended](https://docs.google.com/spreadsheets/d/1WTtCELmw76rVc0yN38Pka0XvT4U0HmWAyyrphxXcPvg/edit?usp=sharing)
2. **Fill in your data.** See [CSV Columns](#csv-columns) below for all supported fields.
3. **Upload the file.** The form accepts `.csv`, `.tsv`, and `.txt` files up to **10 MB**. After upload, a summary shows the detected separator, row count, and column names. Validation errors (if any) are listed.
4. **Resolve ambiguous dates.** If `expires_on` contains dates like `01/05/2026`, the form asks whether the first number is the day or the month, and applies that to all rows.
5. **Configure customer handling and delivery (optional).** When the file contains an `email` or `customer_id` column, additional options appear (see below).
6. **Choose internal delivery options.** Allow data download and / or send yourself a summary email.
7. **Click Import now or Schedule.**
### **π CSV Columns**
#### Required
* **`initial_value`** β The value of the gift card in your store's main currency. Use a dot as the decimal separator (e.g. `25.50`). Commas are auto-converted to dots, but more than two decimal places will be rejected.
#### Optional
* **`code`** β The gift card code. Must be **8β20 characters**, letters / numbers / hyphens only. Must be unique and not already used in your store. If empty or omitted, a code is auto-generated.
* **`prefix`** β Adds a fixed prefix to auto-generated codes (or to the imported code). Used for organizing or branding.
* **`email`** β Recipient email address. Required if you want to email this row's gift card to a person.
* **`customer_id`** β Numeric Shopify customer ID. Alternative to `email`.
* **`expires_on`** β Expiration date. Supported formats: `YYYY-MM-DD` (recommended), `DD/MM/YYYY`, `MM/DD/YYYY`, `DD-MM-YYYY`, or `MM-DD-YYYY`. Leave blank for no expiration.
* **`note`** β Internal note attached to the gift card. Visible to staff only, not customers.
* **`message`** β Custom message included in the gift card email. Wrap multi-word messages in double quotes in the CSV to avoid parsing errors.
### **πͺͺ Customer Handling (when `email` or `customer_id` is in the file)**
When the file includes one of these columns, two extra sections appear in the form:
**If a customer doesn't exist in your store** β choose what happens for rows whose customer can't be matched:
* **Skip creating gift card** β that row is skipped.
* **Create customer and create gift card** β a new customer is created and the gift card is issued to them.
**Assign recipients to gift card** β choose where the customer is attached on each gift card:
* **Recipient field** β the customer is set as the recipient (they get the notification with the message).
* **Customer field** β the customer is set as the owner of the gift card. *Note: assigning to the customer field ignores the message.*
* **Customer and Recipient field** β both.
### **βοΈ Sending the Gift Cards (when `email` or `customer_id` is in the file)**
Enable **Send to customer** to email each row's gift card to its recipient. Choose a sending method:
* **Shopify Email** β uses Shopify's built-in gift card notification email.
* **App Email** β uses Gift Card Factory's email infrastructure with a customizable template (built from the **Import from file** or **Custom** template type). Preview before sending.
* **Shopify Flow** β fires a Flow trigger; you configure the action that sends the email.
* **Klaviyo** β fires a Klaviyo metric; you configure a flow that responds to the metric.
[Read more about each sending option](/misc/sending-customer-notifications).
### **π€ Internal Delivery Options**
Independent of customer notifications:
* **Allow gift cards data download**: Creates a download link in the **Bulk Operations** section. Expires after **3 days**.
* **Send internal email with all generated gift cards codes**: Sends the full list of codes to an email address you specify (multiple addresses allowed, comma-separated).
### **βΆοΈ Running the Operation**
* **Import now**: Runs the operation immediately.
* **Schedule**: Runs the operation at a future date and time you select.
The submit button stays disabled until a file is uploaded. You can still proceed with rows that have validation warnings β the warning banner lets you choose to fix and re-upload, or run the import as-is (rows with errors will be skipped during execution).
### **π Multiple Imports per File**
If you need to split a single CSV across multiple imports (for example, to schedule batches at different times), see [Multiple Imports From a Single File](/bulk-operations/import-from-file/multiple-imports-from-a-single-file).
### **FAQ**
**Can I upload more than one file?**\
Only one file at a time. If you have multiple sources, combine them in a spreadsheet first or run separate imports.
**My `initial_value` rows are being rejected.**\
Use a dot as the decimal separator (`25.50`, not `25,50`). Currency symbols and more than two decimal places are not accepted.
**Imported codes don't match what I had in my CSV.**\
Codes you supply must be 8β20 characters, letters / numbers / hyphens only. Rows with invalid codes are flagged before import.
**No customer-handling options appeared.**\
Those options only appear if the uploaded file contains an `email` or `customer_id` column.
**The recipient didn't get their gift card email.**\
Confirm **Send to customer** was enabled, the row had a valid `email` or `customer_id`, and your sending method is configured (Shopify Email enabled / App Email domain validated / Flow configured / Klaviyo flow listening on the metric). Have the recipient check spam.
# Multiple Imports From a Single File
π Schedule multiple gift card imports from a single CSV file.
You can schedule **multiple gift card imports** to run at different dates and times by adding a `scheduled_on` column to your CSV file. Optionally, you can also use a `template_id` column to override the email template per scheduled batch.
> **Where this works:** This feature is available for **gift card** [Import from File](/bulk-operations/import-from-file) only. It is **not** available for store credit or discount codes imports.
### **πͺ How It Works**
1. Add a `scheduled_on` column to your CSV. Rows with the same `scheduled_on` value are grouped into one scheduled import.
2. Upload the file via **Bulk Operations β Import from File**.
3. The app creates one **SCHEDULED** import per unique `scheduled_on` value, each containing the matching subset of rows.
4. A toast confirms how many scheduled imports were created (e.g. "Created 3 scheduled imports").
5. Each scheduled import appears in your Bulk Operations list and runs automatically at its scheduled time, in your **Shopify store's timezone**.
### **π The `scheduled_on` Column**
#### Supported formats
| Format | Example | Notes |
| ----------- | --------------------- | -------------------------------------------------------------------------------------------- |
| Date only | `2025-12-25` | Time defaults to **12:00** (noon). |
| Date + time | `2025-12-25 14:30` | 24-hour format. |
| ISO 8601 | `2025-12-25T10:15:00` | Timezone offsets like `Z` or `+02:00` are accepted but ignored β the store timezone is used. |
#### Timezone
Scheduled times are interpreted in your **Shopify store's timezone** (the IANA timezone configured in your Shopify settings). Verify it before scheduling.
#### Grouping rules
* Rows with the **exact same** `scheduled_on` string are grouped together. `2025-12-25` and `2025-12-25T00:00:00` are treated as different values and create two separate imports.
* Rows with an empty `scheduled_on` are ignored.
* Rows with an unrecognized format are reported as errors and excluded from scheduling.
#### Example
```csv
initial_value,email,scheduled_on
50,customer1@example.com,2025-12-25
100,customer2@example.com,2025-12-25
75,customer3@example.com,2025-12-26 14:30
```
Result:
* One scheduled import for `2025-12-25` at 12:00 β 2 gift cards
* One scheduled import for `2025-12-26 14:30` β 1 gift card
### **βοΈ The `template_id` Column (Optional)**
Add a `template_id` column to override the email template for each scheduled batch.
#### How to find a template ID
1. Go to **Email β Templates** in the app.
2. Click the template you want to use.
3. The ID is the last segment of the URL, e.g. for `β¦/app/templates/abc123/edit` the ID is `abc123`.
#### Behavior
* When `template_id` is present, the **sender for that scheduled batch is automatically set to App Email** β the form's sender selection is overridden.
* For each `scheduled_on` group, the `template_id` value of the **first row in that group** is used. Other rows in the same group ignore their `template_id`.
* Different `scheduled_on` groups can use different templates (one per group).
* `template_id` is only honored when `scheduled_on` is also present. Without `scheduled_on`, the form's template selection is used instead.
#### Example
```csv
initial_value,email,scheduled_on,template_id
50,c1@example.com,2025-12-25,holiday_template
50,c2@example.com,2025-12-25,holiday_template
100,c3@example.com,2026-01-01,newyear_template
```
Result: two scheduled imports β one for Christmas using `holiday_template`, one for New Year using `newyear_template`.
### **π‘ Use Cases**
* **Holiday calendar** β schedule gift cards for Christmas, New Year, Valentine's, etc. in one upload.
* **Birthday rewards** β upload a list of birthdays and let each card go out on the matching date.
* **Recurring rewards** β pre-schedule monthly or quarterly gift cards.
* **Drip campaigns** β schedule cards to send on Day 1, Day 7, and Day 30 of a customer journey.
### **FAQ**
**Can I mix scheduled and immediate rows in one file?**\
No. If the file contains a `scheduled_on` column, every row must have a value in it (rows without one are ignored). To run an immediate import alongside scheduled ones, upload a separate file without the `scheduled_on` column.
**What if my date format is invalid?**\
Rows with unrecognized `scheduled_on` values are reported in the response (e.g. "Invalid date format: β¦") and excluded from the scheduled imports. Other rows are processed normally.
**Can I cancel or reschedule an import after uploading?**\
Yes β open the entry in Bulk Operations and abort it before it runs. To reschedule, create a new import (you can't edit a scheduled one in place).
**Do all scheduled imports share the same form settings?**\
Yes. Sender, customer-handling options, allowDownload, internal email, etc. apply to every scheduled batch from one upload. The only per-batch override is `template_id`, and it forces the sender to App Email for that batch.
**Within one scheduled date, can different rows use different templates?**\
No. Within a single `scheduled_on` group, only the first row's `template_id` is used β the rest of the rows are sent with the same template. To use different templates within the same date, use a slightly different time (e.g. `2025-12-25T09:00:00` and `2025-12-25T09:00:01`) so they become separate groups, or split into multiple uploads.
**Does this work for store credit or discount code imports?**\
No β `scheduled_on` and `template_id` columns are only supported for **gift card** Import from File.
### **β Tips**
* **Test with 2β3 rows first** to confirm your date format is parsed as expected.
* **Use ISO 8601** (`2025-12-25T10:00:00`) when in doubt β it's unambiguous.
* **Verify your store timezone** in Shopify settings before scheduling.
* **Use descriptive template names** (`Holiday_2025`, `Birthday_Reward`) to make `template_id` easy to identify.
# Store Credit Bulk Add
π° Add Shopify store credit to many customers at once.
The **Bulk Add Store Credit** feature adds Shopify store credit to multiple customer accounts β or [B2B company locations](#b2b-company-recipients) β in a single operation. Store credit is a monetary balance attached directly to a customer record β it applies automatically at checkout when the customer is logged in, requires no code, and cannot be transferred between customers.
> **Store credit vs. gift cards:** Store credit lives on the customer record and applies to their account at checkout. Gift cards are codes that anyone holding the code can redeem, regardless of which customer record (if any) they're attached to. Use store credit for refunds, compensation, loyalty rewards, and account-bound promotions; use gift cards for transferable value. See [Gift Cards vs Discount Codes vs Store Credit](/comparison) for a full comparison.
{% hint style="warning" %}
**Prerequisite: new customer accounts.** Per Shopify, store credit can only be redeemed at checkout when the customer is authenticated via [**new customer accounts**](https://shopify.dev/docs/api/admin-graphql/latest/objects/StoreCreditAccount). If your store uses classic customer accounts, recipients won't be able to spend the credit. Check or switch under **Shopify Admin β Settings β Customer accounts**.
{% endhint %}
### π‘ **Common Use Cases**
* **Service compensation** β credit customers affected by shipping delays, quality issues, or outages.
* **Refunds as credit** β push refunds back as store credit so the customer shops with you again.
* **Seasonal promotions** β credit a customer segment for a campaign window.
* **Loyalty rewards** β credit customers who hit a milestone (e.g. 10+ orders).
* **Win-back campaigns** β credit dormant customers to re-engage them.
* **Contest / giveaway prizes** β credit a list of winners.
* **B2B allowances & rebates** β credit your wholesale companies so their buyers spend it at B2B checkout.
### **π Form Fields Explained**
#### Value
* **Amount** (required, minimum 1).
* **Currency** β any of the \~130 ISO 4217 currencies supported by Shopify. Defaults to your store's primary currency.
#### Store credit expiry
Choose one of three options:
* **Store credit never expires** β no expiration.
* **Store credit expires relative to creation date** β set a duration in days, weeks, months, or years from when the credit is added.
* **Store credit expires on a specific date** β pick an exact future calendar date (past dates are disabled).
#### Recipients
The **Add store credit to** toggle switches between two audiences: **Customers** (default) and **B2B companies** (see [B2B Company Recipients](#b2b-company-recipients) below).
For **Customers**, choose how to provide who receives the credit. Switch between methods using the tabs:
* **Manual list of emails** β paste or type emails separated by commas or new lines.
* **Select customers** β pick individual customers from your store via the customer picker.
* **Select customer segment** β pick a Shopify customer segment; all members become recipients.
* **Customers query** β enter a Shopify customer search query (e.g. `tag:vip` or `orders_count:>5`). The list is resolved at execution time.
> See the [Recipients Selector](/misc/recipients-selector) page for a deep dive on each method, including limits and recommended use cases. For query syntax, see the [Customers Query Selector](/misc/customers-query-selector).
> Store credit can only be added to existing Shopify customer records. Recipients without a matching customer in your store are skipped.
### π’ **B2B Company Recipients**
Switch the **Add store credit to** toggle to **B2B companies** to credit your wholesale companies instead of individual customers. Credit is added per **company location** β the level where Shopify B2B checkout looks for it β so buyers ordering on behalf of that location can see and spend it at checkout.
{% hint style="info" %}
Requires **B2B on Shopify** (Shopify Plus). The first time you switch to the companies audience, the app asks for permission to read your companies β the toggle activates once you grant it.
{% endhint %}
Choose how to provide the companies using the tabs:
* **Select companies** β pick companies from a searchable list. Checking a company selects **all** of its locations; expand a company to check or uncheck individual locations.
* **Companies query** β enter a Shopify company search query (e.g. `name:Acme*` or `external_id:1234`). It's resolved at execution time β every location of each matching company receives credit. Great for scheduled runs that should pick up newly added companies.
* **Manual list of companies** β paste company **external IDs** or **exact company names**, one per line. Each line is matched at execution time (external ID first, then name) and expanded to all of that company's locations. Lines that don't match β or match more than one company β are reported as errors, never guessed.
Things to know for company credits:
* **Currency matters** β use the currency the company locations order in; credit in another currency won't be spendable at their checkout.
* **No notification emails** β company credits never send emails (the notification section is hidden for this audience). Buyers see the balance at checkout.
* **Result file** β company runs produce a result CSV with **Company** and **Location** columns instead of customer name and email.
* Expiry, scheduling, internal delivery options, and resume after limit errors all work exactly as they do for customers.
### **βοΈ Notification Settings**
The **Send store credit notification** checkbox controls whether recipients are emailed about the credit. When enabled, choose a sending method:
* **Shopify Email** β uses Shopify's built-in **Store credit issued** notification email. (This is Shopify's native template; you can edit it from your Shopify Admin.)
* **App Email** β uses Gift Card Factory's email infrastructure with a customizable template (built from the **Store credit bulk add** or **Custom** template type). Preview before sending.
* **Shopify Flow** β fires a Flow trigger; you configure the action that sends the email.
* **Klaviyo** β fires a Klaviyo metric; you configure a flow that responds to the metric.
[Read more about each sending option](/misc/sending-customer-notifications).
### **π€ Internal Delivery Options**
Independent of customer notifications:
* **Allow store credits data download**: Creates a download link in the **Bulk Operations** section. The link expires after **3 days**.
* **Send internal email with all generated store credits**: Sends a list of the credit transactions (with the matching recipients) to an email address you specify (multiple addresses allowed, comma-separated).
### **βΆοΈ Running the Operation**
* **Add now**: Runs the operation immediately.
* **Schedule**: Runs the operation at a future date and time you select. The credit is added to each recipient's account at the scheduled time.
### **FAQ**
**A recipient doesn't have a customer record β what happens?**\
Store credit can only be issued to existing customer records. Recipients with no matching customer are skipped. To add the customer first, create them in Shopify or use [Bulk Send](/bulk-operations/bulk-send) (gift cards) which can create customers on the fly.
**Why can't I pick a past expiry date?**\
The specific-date option only allows future dates β past dates would result in already-expired credit.
**A recipient didn't receive a notification.**\
Confirm the **Send store credit notification** checkbox was enabled and the chosen sender is configured: for **Shopify Email** check that the Store credit issued template is enabled in Shopify; for **App Email** confirm sending is enabled and your domain is validated; for **Shopify Flow** confirm a Flow is responding to the trigger; for **Klaviyo** confirm a flow is responding to the metric.
**Can I add credit in a different currency from my store's primary currency?**\
Yes β the currency selector lets you choose any supported currency. Behavior at checkout depends on Shopify's multi-currency configuration for your store.
**Can I remove or reverse store credit added in bulk?**\
This bulk operation only **adds** credit (it uses Shopify's `storeCreditAccountCredit` mutation). To deduct credit in bulk, use [Store Credit Import from File](/bulk-operations/store-credit-import-from-file) with negative amounts; for one-offs, debit the customer directly in Shopify Admin.
**Why can't buyers spend credit I added to their company?**\
Check three things: the credit was added to the **company location** the buyer orders for (a company can have several locations, each with its own balance), the credit currency matches the location's checkout currency, and your buyers sign in with **new customer accounts**.
**Do company recipients get a notification email?**\
No β company credits never send emails. Buyers see the available balance at B2B checkout.
**I switched to "B2B companies" but the picker shows no companies.**\
B2B on Shopify is a Shopify Plus feature β on non-Plus stores there are no companies to list. Also confirm you granted the companies permission when prompted.
# Store Credit Import From File
π₯ Import store credit transactions from a CSV file.
The **Store Credit Import from File** feature adjusts Shopify store credit balances for multiple customers β and [B2B company locations](#b2b-company-rows) β from a CSV file. Each row becomes one transaction β positive amounts **add** credit, negative amounts **subtract** credit β and you can configure amount, currency, and expiry independently per row. Positive and negative rows, and customer and company rows, can be mixed in the same file. Optionally, the app can send a notification email per transaction (customer rows only).
> **When to use this vs other store credit operations:**
>
> * Use this when amounts, currencies, or expiry dates differ per customer.
> * Use [**Store Credit Bulk Add**](/bulk-operations/store-credit-bulk-add) when every recipient should receive the same amount and configuration.
{% hint style="warning" %}
**Prerequisite: new customer accounts.** Per Shopify, store credit can only be redeemed at checkout when the customer is authenticated via [**new customer accounts**](https://shopify.dev/docs/api/admin-graphql/latest/objects/StoreCreditAccount). If your store uses classic customer accounts, recipients won't be able to spend the credit. Check or switch under **Shopify Admin β Settings β Customer accounts**.
{% endhint %}
### π‘ **Common Use Cases**
* **Bulk refunds** β issue store credit to many customers from a refund report.
* **Loyalty rewards** β different credit amounts per customer tier.
* **Compensation campaigns** β credits sized per affected order.
* **Account migrations** β bring in credit balances from another platform.
* **Migration corrections** β subtract amounts customers redeemed on your old system after the initial import.
* **Bulk debits / clawbacks** β remove credit from many customers at once (e.g. after a promotional error or refund reversal).
* **Multi-currency stores** β different currencies per customer market.
* **Referral / affiliate payouts** β credit referrers based on a tracked list.
### **πͺ Step-by-Step Instructions**
1. **Download a template.**
{% file src="/files/JIDqhHSlSejV82cAjBYd" %}
{% file src="/files/vA2q3lSlNKIj2JglXitZ" %}
2. **Fill in your data.** See [CSV Columns](#csv-columns) below.
3. **Upload the file.** The form accepts `.csv`, `.tsv`, and `.txt` files up to **10 MB**. After upload, a summary shows the detected separator, row count, and column names. Validation errors (if any) are listed.
4. **Resolve ambiguous dates.** If `expires_at` contains dates like `01/05/2026`, the form asks whether the first number is the day or month and applies it to all rows.
5. **Configure customer notification (optional).** When the file contains an `email` or `customer_id` column, a **Send store credit notification** checkbox appears. Enable it and choose a sending method.
6. **Choose internal delivery options.** Allow data download and / or send yourself a summary email.
7. **Click Import now or Schedule.**
### **π CSV Columns**
#### Required
* **`amount`** β The transaction value. Use a **positive number** (e.g. `25.50`) to add store credit, or a **negative number** (e.g. `-25.50`) to subtract from the customer's existing balance. Use a dot as the decimal separator. Commas are auto-converted to dots, but more than two decimal places are rejected. See [Subtracting Store Credit (Debits)](#subtracting-store-credit-debits) for details on how negative rows are processed.
#### Identifying the recipient (one of these is needed)
**Customer rows:**
* **`email`** β Customer email. If a customer with this email exists, store credit is added to them. **If no matching customer exists, a new customer record is created with that email and the credit is issued to them.**
* **`customer_id`** β Numeric Shopify customer ID. Use this to avoid creating a new customer when an existing one matches the email.
**Company rows** (B2B on Shopify β see [B2B Company Rows](#b2b-company-rows)):
* **`company_location_id`** β Numeric Shopify company location ID. Credits exactly that location.
* **`company_id`** β Numeric Shopify company ID. Credits **all** locations of that company.
* **`company_external_id`** β The company's external ID. Credits **all** locations of the matching company.
> **Precedence:** a row with a non-blank `email` or `customer_id` is always treated as a **customer row** β company columns on that row are ignored. Company columns apply only when both customer columns are blank. Among company columns: `company_location_id` wins over `company_id`, which wins over `company_external_id`.
> Rows with no recipient column filled in are skipped (logged as errors in the operation report).
#### Optional
* **`currency_code`** β 3-letter ISO 4217 currency code (e.g. `USD`, `EUR`, `GBP`). If omitted, the store's default currency is used. The currency must be enabled in your Shopify store.
* **`expires_at`** β Expiry date for the credit. Supported formats: `YYYY-MM-DD` (recommended), `DD/MM/YYYY`, `MM/DD/YYYY`, `DD-MM-YYYY`, `MM-DD-YYYY`. If omitted, the credit never expires.
### **π€ Customer Lookup & Creation**
The import uses the following resolution order per row:
1. If `customer_id` is present, look up that customer.
2. Otherwise, search by `email`.
3. If no customer matches by email, create a new customer with that email and issue the credit to them.
> Creating a customer here is the same Shopify operation as adding a customer manually β Shopify's standard "welcome" behavior applies based on your store's settings.
### π’ **B2B Company Rows**
Rows identified by `company_location_id`, `company_id`, or `company_external_id` add store credit to **B2B company locations** β the level where Shopify B2B checkout looks for it β instead of individual customers. Customer and company rows can be freely mixed in one file.
{% hint style="info" %}
Requires **B2B on Shopify** (Shopify Plus). When the app detects company columns in your file, it asks for permission to read your companies β grant it before running the import, otherwise company rows will fail.
{% endhint %}
**How company rows are processed:**
1. The location(s) are resolved: `company_location_id` β that exact location; `company_id` or `company_external_id` β **every** location of the company. Companies repeated across rows are only looked up once.
2. Positive amounts credit each resolved location; negative amounts debit each location's balance (same [cap / zero-out behavior](#subtracting-store-credit-debits) as customer debits).
3. The result CSV gets **one row per location** β so a `company_id` row for a 3-location company produces 3 result rows. Success/error counts still track CSV rows, not locations.
4. Unresolvable identifiers (no match, or an ambiguous `company_external_id`) log the row as an error β the app never guesses.
**Things to know:**
* **No notification emails** β company rows never send notifications, regardless of the notification checkbox.
* **Currency matters** β use the currency the company location orders in; credit in another currency won't be spendable at their B2B checkout.
* `expires_at` works for company credits exactly as for customers; buyers need **new customer accounts** to spend the credit.
### **β Subtracting Store Credit (Debits)**
Any row with a **negative** `amount` subtracts from the customer's existing store credit balance instead of adding to it. The same file can mix positive (credit) and negative (debit) rows freely β each row is processed independently.
**How debit rows are processed:**
1. The customer is looked up via `email` or `customer_id`. If no customer exists, the row is logged as an error (debits cannot create new customers β there'd be nothing to debit).
2. The customer's store credit account in the requested `currency_code` is fetched.
3. **If the customer has no store credit balance in that currency**, the row is logged as an error and skipped.
4. **If the requested debit is greater than the available balance** (e.g. row says `-50` but the customer only has `30` left), the account is **zeroed out** and an info-level message is logged. The row is counted as a success β over-debit never fails the row.
5. The amount actually debited and the new balance are written to the result CSV. Debits show as negative numbers in the **Balance Change** column.
> Debit rows ignore the `expires_at` column β debits don't have an expiry date.
### **βοΈ Customer Notification (Optional)**
When the file contains an `email` or `customer_id` column, you can choose to email each customer about their transaction. Enable **Send store credit notification** and pick a sending method. Notifications are sent for **both increases and decreases** when opted in. Company rows are never notified β the setting only applies to customer rows.
* **Shopify Email** β uses Shopify's built-in **Store credit issued** notification email. (Note: Shopify's built-in template only covers credits; for debit notifications use App Email, Flow, or Klaviyo.)
* **App Email** β uses Gift Card Factory's email infrastructure with a customizable template (built from the **Store credit import from file** or **Custom** template type). Preview before sending.
* **Shopify Flow** β fires a Flow trigger; you configure the action that sends the email.
* **Klaviyo** β fires a Klaviyo metric; you configure a flow that responds to the metric.
To differentiate copy for credits vs debits in your App Email / Klaviyo template, branch on `{{ issued_store_credit.transaction_type }}` β its value is either `"credit"` or `"debit"`. Example:
```liquid
{% if issued_store_credit.transaction_type == "debit" %}
We've adjusted your store credit balance down by {{ issued_store_credit.amount | format_money: shop.currency_formats.money_format }}.
{% else %}
We've added {{ issued_store_credit.amount | format_money: shop.currency_formats.money_format }} of store credit to your account.
{% endif %}
Your new balance is {{ issued_store_credit.balance_after_transaction | format_money: shop.currency_formats.money_format }}.
```
[Read more about each sending option](/misc/sending-customer-notifications).
### **π€ Internal Delivery Options**
Independent of customer notifications:
* **Allow store credits data download**: Creates a download link in the **Bulk Operations** section. Expires after **3 days**.
* **Send internal email with all generated store credits**: Sends a list of credit transactions to an email address you specify (multiple addresses allowed, comma-separated).
### **βΆοΈ Running the Operation**
* **Import now**: Runs the operation immediately.
* **Schedule**: Runs the entire operation at a future date and time you select.
> Per-row scheduling via a `scheduled_on` column is **not** supported for store credit imports β only for [gift card imports](/bulk-operations/import-from-file/multiple-imports-from-a-single-file).
### **π§ͺ Examples**
#### Simple credits
```csv
amount,email
25.00,customer1@example.com
50.00,customer2@example.com
10.00,customer3@example.com
```
#### Credits with expiry
```csv
amount,email,expires_at
25.00,customer1@example.com,2027-12-31
50.00,customer2@example.com,2027-06-30
```
#### Multi-currency credits
```csv
amount,email,currency_code,expires_at
25.00,us-customer@example.com,USD,2027-12-31
20.00,uk-customer@example.com,GBP,2027-12-31
30.00,eu-customer@example.com,EUR,2027-12-31
```
#### Using customer IDs
```csv
amount,customer_id,currency_code
25.00,123456789,USD
50.00,987654321,USD
```
#### Mixed credits and debits (e.g. migration corrections)
```csv
amount,email,currency_code
-25.00,jane@example.com,USD
-10.50,john@example.com,USD
50.00,sarah@example.com,USD
```
#### B2B company rows (mixed with customers)
```csv
amount,email,company_id,company_location_id,company_external_id,currency_code
100.00,,123456789,,,USD
250.00,,,987654321,,USD
75.00,,,,ACME-01,USD
25.00,vip@example.com,,,,USD
```
> Row 1 credits **all** locations of company `123456789`; row 2 credits one specific location; row 3 matches a company by external ID; row 4 is a regular customer row.
### **π Result File Output**
After the operation finishes, a result CSV is generated with one row per transaction (company rows produce one row **per credited location**):
| Column | Description |
| -------------------- | -------------------------------------------------------------------------- |
| **Id** | Store credit account ID. |
| **Recipient** | Customer first + last name, or the company name for company rows. |
| **Email / Location** | Customer email, or the company location name for company rows. |
| **Currency** | Currency code of the transaction. |
| **Balance Change** | Amount applied. **Positive** for credits, **negative** for debits. |
| **Current Balance** | The account's store credit balance in that currency after the transaction. |
### **π« Limitations**
* **File size**: 10 MB maximum.
* **Currency must be enabled** in your Shopify store settings to be valid for that customer.
* **Debits require an existing store credit account** in the requested currency β debit rows for customers with no balance are skipped.
* **Debits ignore `expires_at`** β only credit transactions can have an expiry date.
* **No per-row scheduling** β use the Schedule button to run the whole import later, but every row runs together.
### **FAQ**
**My CSV has decimals like `25,50` and they're being rejected.**\
The decimal separator must be a dot (`.`). Commas are auto-converted, but check for currency symbols (`$`, `β¬`) or thousands separators in the same field β those are rejected.
**A row was skipped β why?**\
Rows are skipped if `amount` is missing or invalid, or if neither `email` nor `customer_id` resolves to (or creates) a customer. Check the operation log under Bulk Operations β details.
**A customer didn't get a notification email.**\
Confirm **Send store credit notification** was enabled, the row had an `email` or `customer_id` column with a valid value, and your sending method is configured (Shopify Email's Store credit issued template enabled / App Email domain validated / Flow configured / Klaviyo flow listening on the metric).
**I imported the same file twice β did customers get double credit?**\
Yes β the import always processes each row as a new transaction, it doesn't deduplicate. If you re-ran an import, each customer in the file will have been credited (or debited) twice. To reverse a duplicate run, re-upload the same file with the `amount` values negated.
**Can I use this to remove (debit) store credit?**\
Yes. Use a negative number in the `amount` column (e.g. `-25.00`) to subtract from a customer's existing balance. See [Subtracting Store Credit (Debits)](#subtracting-store-credit-debits).
**What happens if I try to debit more than the customer has?**\
The customer's account is zeroed out β only the available balance is debited β and the over-debit is recorded in the operation log. The row is counted as a success, not an error.
**Can I debit a customer who has never had store credit?**\
No. Debits require an existing store credit account in the requested currency. Rows trying to debit a customer with no balance in that currency are logged as errors and skipped. The same applies to company locations.
**My row has both an email and a company ID β who gets the credit?**\
The customer. Customer columns (`email` / `customer_id`) always take precedence; company columns on that row are ignored. Leave both customer columns blank to make it a company row.
**Why did one CSV row produce several result rows?**\
`company_id` and `company_external_id` credit **every** location of the company β the result file shows one row per location. Use `company_location_id` to target a single location.
**My company rows all failed with a permission error.**\
The app needs permission to read your companies. Re-upload the file and grant the permission when prompted (the app asks as soon as it detects company columns), then run the import again.
# Discount Codes Bulk Create
ποΈ Generate many Shopify discount codes at once for manual distribution.
The **Bulk Create Discount Codes** feature generates a batch of generic Shopify discount codes that share the same rules. The codes are not tied to specific customers β you distribute them however you want (social media, print, influencers, partners, QR codes, etc.).
> **Bulk Create vs. Bulk Send:** **Bulk Create** generates codes only β you handle delivery yourself. [**Bulk Send**](/bulk-operations/discount-codes-bulk-send) generates codes *and* sends a personalized email to each recipient. Use Bulk Create when you don't have a recipient list.
### π‘ **Common Use Cases**
* **Social media giveaways** β share codes on Instagram, TikTok, etc.
* **Influencer partnerships** β assign one code per influencer to track performance.
* **Print and packaging** β flyers, postcards, package inserts, business cards.
* **In-store and event handouts** β drive online traffic from physical touchpoints.
* **QR codes** β embed codes in QR-linked landing pages.
* **Partner / affiliate programs** β give partners codes to distribute downstream.
### **π Form Fields Explained**
#### Top section
* **Title** (required): Internal name for the batch in Shopify Admin β Discounts. Be descriptive β you'll have many discount campaigns.
* **Count** (required): Number of codes to generate. Minimum 1.
#### Discount Value
* **Discount Type**: **Fixed amount** (e.g. $10 off, in your store currency) or **Percentage** (e.g. 20% off).
* **Value**: The discount amount or percentage.
* **Usage Type**: Restrict the discount to specific **collections** or specific **products**. If nothing is selected, the discount applies to all products and collections (a banner confirms this).
* **Purchase Type**: **One-time purchase**, **Subscription**, or **Both**.
* **Once Per Order** (Fixed amount only): If checked, the fixed discount is applied once per order. If unchecked, it is applied to each eligible item in the order.
#### Code
* **Prefix** (optional, up to 4 characters): A fixed prefix added to every generated code.
#### Eligibility
Choose who can use these codes:
* **All customers**
* **Specific customer segments** β select one or more Shopify customer segments.
* **Specific customers** β select individual customers using the customer picker.
#### Minimum purchase requirements
* **No minimum requirements** (default).
* **Minimum purchase amount** β customer must spend at least this amount (in store currency).
* **Minimum quantity of items** β customer must purchase at least this many items.
#### Usage limits
* **Limit number of times each discount code can be used in total** β when checked, set a per-code total usage limit.
* **Limit to one use per customer** β when checked, each customer can redeem the code only once.
#### Combines with
Controls Shopify's discount stacking rules:
* **Product discounts**
* **Order discounts**
* **Shipping discounts**
Each option independently determines whether this code can be combined with that discount type.
#### Active dates
Set when the codes are valid. Click **From** or **To** to open a modal where you choose timezone, date, and time. Both start and end are stored with timezone, so they behave correctly across markets.
### **π€ Internal Delivery Options**
These options control how *you* (the merchant) receive the generated codes:
* **Allow discount codes data download**: Creates a download link in the **Bulk Operations** section. The link expires after **3 days** and is accessible to anyone with access to the app.
* **Send internal email with all generated discount codes**: Sends the full list of codes to an email address you specify. You can enter multiple addresses separated by a comma.
You can enable either option, both, or neither. We recommend at least one β otherwise you have no easy way to retrieve the codes after the operation runs.
### **βΆοΈ Running the Operation**
Two buttons are available at the bottom of the form:
* **Create now**: Runs the operation immediately.
* **Schedule**: Runs the operation at a future date and time you select. The codes only become *usable* once their **Active dates β From** is reached, even if the operation runs earlier.
### **FAQ**
**Can I choose the exact code text?**\
No β Shopify generates the code body automatically. You can add a fixed **Prefix** of up to 4 characters, but the rest of each code is random.
**Can I edit codes after they are created?**\
No, individual codes cannot be edited from the app. You can disable codes in Shopify Admin β Discounts and create a new batch with the corrected settings.
**Can the operation create codes for a future launch?**\
Yes β either schedule the operation for the future, or run it now and set **Active dates β From** to your launch date.
**My download link expired β how do I get the codes?**\
The download link is valid for 3 days. If it expired and you didn't enable the internal email option, the individual codes still exist in Shopify Admin β Discounts under your batch title. Contact us at **** if you need help.
**How do refunds affect usage limits?**\
Shopify restores a code's usage count when an order using it is refunded, so the customer (or another customer) can use the code again within the configured limits.
# Discount Codes Bulk Send
π¨ Send a unique Shopify discount code to each recipient via email.
The **Bulk Send Discount Codes** feature creates a unique Shopify discount code for each recipient and sends it to them via email. Each recipient gets their own code, which prevents sharing and lets you track redemption per person.
> **Bulk Send vs. Bulk Create:** **Bulk Send** generates codes *and* delivers them via email β one unique code per recipient. [**Bulk Create**](/bulk-operations/discount-codes-bulk-create) generates a batch of generic codes that you distribute yourself. Use Bulk Send when you have a list of customers or emails.
### π‘ **Common Use Cases**
* **Welcome discounts** β send a one-time discount to new subscribers or customers.
* **VIP appreciation** β reward top spenders with exclusive codes.
* **Birthday or anniversary offers** β personalized codes timed to customer milestones.
* **Win-back campaigns** β re-engage dormant customers with a unique incentive.
* **Event follow-up** β thank attendees of webinars, conferences, or in-store events.
* **Loyalty program rewards** β distribute tier-based discounts.
* **Segmented promotions** β target a specific customer segment with a tailored offer.
### **π Form Fields Explained**
#### Discount configuration
The discount section is identical to [Bulk Create](/bulk-operations/discount-codes-bulk-create#form-fields-explained). All fields apply:
* **Title** (required) β internal name shown in Shopify Admin β Discounts.
* **Discount Value** β Fixed amount or Percentage; restrict to specific products or collections; pick purchase type (one-time / subscription / both); optional Once Per Order.
* **Code Prefix** β optional, up to 4 characters.
* **Eligibility** β All customers, specific segments, or specific customers.
* **Minimum purchase requirements** β none, minimum amount, or minimum quantity.
* **Usage limits** β total per code and / or one use per customer.
* **Combines with** β product, order, and shipping discounts.
* **Active dates** β start and end (with timezone, date, time).
> Number of codes generated equals the number of recipients β there is no separate **Count** field.
#### Recipients
Choose how to provide the recipient list. Switch between methods using the tabs:
* **Manual list of emails** β paste or type emails separated by commas or new lines.
* **Select customers** β pick individual customers from your store using the customer picker.
* **Select customer segment** β pick a Shopify customer segment; all members become recipients.
* **Customers query** β enter a Shopify customer search query (e.g. `tag:vip` or `orders_count:>5`). The list is resolved at execution time, so any customer matching when the operation runs will receive a code.
> See the [Recipients Selector](/misc/recipients-selector) page for a deep dive on each method, including limits and recommended use cases. For query syntax, see the [Customers Query Selector](/misc/customers-query-selector).
### βοΈ **Sending Method**
Choose how the discount code email is delivered. For discount codes the available senders are:
* **App Email** β uses Gift Card Factory's email infrastructure with a customizable template. Pick a template using the Email template selector. You can preview before sending.
* **Shopify Flow** β fires a Flow trigger; you configure the action that sends the email.
* **Klaviyo** β fires a Klaviyo metric; you configure a flow that responds to the metric.
> Shopify Email is **not** available for discount codes (Shopify does not have a native discount code email like it does for gift cards). See [Sending Customer Notifications](/misc/sending-customer-notifications) for setup details for each method.
### **π€ Internal Delivery Options**
These options control how *you* (the merchant) get a copy of the codes β separate from how recipients are notified.
* **Allow discount codes data download**: Creates a download link in the **Bulk Operations** section. The link expires after **3 days** and is accessible to anyone with access to the app.
* **Send internal email with all generated discount codes**: Sends the full list of codes (with the matching recipient) to an email address you specify. You can enter multiple addresses separated by a comma.
You can enable either option, both, or neither.
### **βΆοΈ Running the Operation**
Two buttons are available at the bottom of the form:
* **Send now**: Runs the operation immediately.
* **Schedule**: Runs the operation at a future date and time. You select a timezone, start date, and start time. The codes only become *usable* once their **Active dates β From** is reached β so if you want recipients to be able to redeem immediately, set Active dates β From to "now or earlier".
### **FAQ**
**Does the recipient need to be an existing customer?**\
No. The discount code itself is created in Shopify, and the email is sent to whatever address you supply. However, the **Eligibility** setting on the discount can restrict who can *redeem* it β for example, "Specific customer segments" requires the redeemer to be in that segment.
**A recipient didn't get the email β what should I check?**\
Confirm your **Sending Method** is set up: for **App Email** check that sending is enabled and the template is selected; for **Shopify Flow** check that a Flow is responding to the trigger; for **Klaviyo** check that a flow is responding to the metric. Also have the recipient check spam.
**Can I edit the codes after they're sent?**\
No, individual codes can't be edited. You can disable codes from Shopify Admin β Discounts and run a new bulk send if needed.
**Can I send the same generic code to all recipients?**\
No - Bulk Send always generates a unique code per recipient. If you want one shared code, use [Bulk Create](/bulk-operations/discount-codes-bulk-create) and distribute it yourself.
**My download link expired - how do I retrieve the codes?**\
The download link is valid for 3 days. If it expired and you didn't enable the internal email option, the individual codes still exist in Shopify Admin β Discounts under the title you set. Contact us at **** if you need help.
# Discount Codes Import From File
π₯ Import discount codes from a CSV file with full per-row configuration.
The **Import from File** feature lets you bulk-import discount codes from a CSV file. Each row in the file becomes one discount code, and you can configure value, dates, usage limits, minimum requirements, and combinations independently for each row. Optionally, the app can also email each code to the customer specified in the row.
> **When to use this vs other discount operations:**
>
> * Use this when you have a list of codes (or per-row settings) coming from another system.
> * Use [**Bulk Create**](/bulk-operations/discount-codes-bulk-create) to generate a batch of codes that share the same rules.
> * Use [**Bulk Send**](/bulk-operations/discount-codes-bulk-send) to generate codes *and* email a unique one to each recipient with shared rules.
### π‘ **Common Use Cases**
* **Import from another system** β load codes generated outside Shopify.
* **Per-customer welcome codes** β each row holds a unique customer email and a one-time code.
* **Mixed campaigns in one upload** β different rules per row (different discount values, dates, limits).
* **Pre-staging seasonal campaigns** β import codes with future `starts_at` so they activate automatically.
* **Bulk-order incentives** β different `minimum_purchase_amount` tiers per row.
### **πͺ Step-by-Step Instructions**
1. **Download a template.** A simple template with the most common columns and an advanced template with every supported column are available below.
{% file src="/files/nmCTaj4iHCZ2VC8moYHm" %}
{% file src="/files/ucgfQ1qdjSiExtB77hMW" %}
2. **Fill in your data.** Only `title`, `discount_type`, and `discount_value` are required. Remove columns you don't use.
3. **Upload the file.** The form accepts `.csv`, `.tsv`, and `.txt` files up to **10 MB**. After upload, a summary shows the detected separator, row count, and column names. Validation errors (if any) are listed.
4. **Resolve ambiguous dates.** If your `starts_at` or `ends_at` columns contain dates like `01/05/2026`, you'll be asked whether the first number is the day or the month.
5. **Configure customer delivery (if applicable).** When the file contains an `email` or `customer_id` column, a **Send discount codes to customers** checkbox appears. Enable it and choose a sending method to email each row's code to that row's customer.
6. **Choose internal delivery options.** Allow data download and / or send yourself a summary email.
7. **Click Import now or Schedule.**
### **π CSV Columns**
#### Required
| Column | Notes |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title` | Internal title shown in Shopify Admin β Discounts. Helps you identify the discount. |
| `discount_type` | `fixed` or `percentage` (lowercase). |
| `discount_value` | Numeric. For `fixed` it's the amount in your store currency; for `percentage` it's the percent (e.g. `20` for 20%). Decimal commas are auto-converted to dots. |
#### Code
| Column | Notes |
| -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `code` | The discount code. **3β20 characters**, letters/numbers/hyphens/underscores only. If empty or omitted, a code is auto-generated. |
| `prefix` | Optional prefix (max 4 characters) used only when `code` is empty. |
#### Date & Time
| Column | Notes |
| ----------- | ------------------------------------------------------------ |
| `starts_at` | Date when the discount becomes active. See formats below. |
| `ends_at` | Date when the discount expires. Leave blank for no end date. |
Supported date formats:
* `YYYY-MM-DD` (recommended): `2026-12-25`
* `DD/MM/YYYY` or `DD-MM-YYYY`: `25/12/2026` / `25-12-2026`
* `MM/DD/YYYY` or `MM-DD-YYYY`: `12/25/2026` / `12-25-2026`
If the file contains ambiguous dates (e.g. `01/05/2026`), the form asks you whether the first number represents day or month, and applies that interpretation to all rows.
#### Usage limits
| Column | Notes |
| ------------------- | ------------------------------------------------------------------------------- |
| `usage_limit` | Total number of times this code can be used. Leave blank for unlimited. |
| `once_per_customer` | `true` / `false`. Limits each customer to one redemption. |
| `once_per_order` | `true` / `false`. For **fixed** discounts: applies once per order vs. per item. |
#### Minimum requirements
| Column | Notes |
| ------------------------- | -------------------------------------------- |
| `minimum_purchase_amount` | Minimum order amount in your store currency. |
| `minimum_quantity` | Minimum number of items in the order. |
> Only one minimum requirement applies per discount code. If both columns are populated for the same row, behavior follows Shopify's rules β pick one per row to be safe.
#### Purchase type
| Column | Notes |
| --------------- | ------------------------------------------------ |
| `purchase_type` | `one-time` (default), `subscription`, or `both`. |
#### Combinations
`true` / `false` flags controlling whether the discount can be combined with other discount types:
* `combines_with_product_discounts`
* `combines_with_order_discounts`
* `combines_with_shipping_discounts`
#### Customer notification
| Column | Notes |
| ------------- | ------------------------------------------------------------------------------------ |
| `email` | Customer email. Used to send the row's code to that customer if delivery is enabled. |
| `customer_id` | Numeric Shopify customer ID. Alternative to `email`. |
> Adding `email` or `customer_id` to your file enables the **Send discount codes to customers** option in the form. Without one of these columns, codes are still imported but no recipient emails are sent.
### **π¨ Customer Notification (Optional)**
If your file has an `email` or `customer_id` column, you can email each row's code to its customer. Enable **Send discount codes to customers**, then pick a sending method:
* **App Email** β uses Gift Card Factory's email infrastructure with a customizable template (built from the **Discount codes import from file** or **Custom** template type). Preview before sending.
* **Shopify Flow** β fires a Flow trigger; you configure the action that sends the email.
* **Klaviyo** β fires a Klaviyo metric; you configure a flow that responds to the metric.
> Shopify Email is **not** available for discount codes β Shopify has no native discount-code email template. See [Sending Customer Notifications](/misc/sending-customer-notifications) for setup details.
### **π€ Internal Delivery Options**
Independent of customer notifications, you can also receive the import results yourself:
* **Allow discount codes data download**: Creates a download link in the **Bulk Operations** section. The link expires after **3 days**.
* **Send internal email with all generated discount codes**: Sends the full list of codes to an email address you specify (multiple addresses allowed, comma-separated).
### **βΆοΈ Running the Operation**
* **Import now**: Runs the operation immediately.
* **Schedule**: Runs the operation at a future date and time. The discount codes still respect each row's own `starts_at` / `ends_at` for when they are usable.
The submit button stays disabled until a file is uploaded.
### **π§ͺ Examples**
#### Simple seasonal discounts
```csv
title,discount_type,discount_value,starts_at,ends_at
Summer Sale 2026,percentage,20,2026-06-01,2026-08-31
Fall Discount,fixed,10,2026-09-01,2026-11-30
Winter Special,percentage,25,2026-12-01,2027-02-28
```
#### Customer-specific welcome codes (one-time per customer)
```csv
title,discount_type,discount_value,email,usage_limit,once_per_customer
Welcome Discount,percentage,15,newcustomer@example.com,1,true
Welcome Discount,percentage,15,another@example.com,1,true
```
#### Tiered bulk-order incentives
```csv
title,discount_type,discount_value,minimum_purchase_amount,starts_at,ends_at
Bulk 10% off,percentage,10,100,2026-01-01,2026-12-31
Bulk 15% off,percentage,15,200,2026-01-01,2026-12-31
Bulk 20% off,percentage,20,300,2026-01-01,2026-12-31
```
#### Auto-generated codes with a brand prefix
```csv
title,discount_type,discount_value,prefix
Flash Sale,percentage,20,FLSH
```
Generated codes will start with `FLSH` followed by random characters.
### **π« Limitations**
* **Product / collection targeting**: Imported codes apply to all products and collections. For product- or collection-specific discounts, use [Bulk Create](/bulk-operations/discount-codes-bulk-create).
* **Customer eligibility**: Imported codes are available to all customers. Per-segment or per-customer eligibility is not supported via import.
* **Code format**: Codes must be 3β20 characters, letters / numbers / hyphens / underscores only.
### **FAQ**
**Why was my row rejected with "code length must be between 3 and 20 characters"?**\
Codes you supply yourself must be 3β20 characters long, using letters, numbers, hyphens, and underscores only. Auto-generated codes (when `code` is empty) always conform.
**Why doesn't `discount_value=$10` work?**\
The value must be numeric β no currency symbols or `%`. Use `10`, not `$10` or `10%`.
**My file has dates like `05/06/2026` and the import got the months and days swapped.**\
The form asks for a "Date format" only when it detects ambiguous dates. If you imported with the wrong choice, fix the dates (or change the column to `YYYY-MM-DD`) and re-import. There's no way to retroactively flip the interpretation on already-imported codes.
**Recipients didn't get their emails.**\
Confirm **Send discount codes to customers** is enabled, your file actually contains the `email` or `customer_id` column with valid values, and the chosen sender is configured (App Email enabled / Flow configured / Klaviyo flow listening on the metric).
**Can I update or edit the imported codes later?**\
Imported codes can't be edited from the app. Use Shopify Admin β Discounts to disable an individual code, then re-import or use [Bulk Create](/bulk-operations/discount-codes-bulk-create) for the corrected version.
# Gift Card Postman
Let customers send gift cards to friends and loved ones
Gift Card Postman lets shoppers buy a gift card for someone else, write a personal message and choose a delivery date. The recipient gets the gift card by email on that date.
This section covers:
* [Introduction](/campaigns/gift-card-postman/introduction) β what the feature does and why to use it
* [Setup](/campaigns/gift-card-postman/setup) β how to add the app block, create the gift card product and configure the campaign
* [Dashboard](/campaigns/gift-card-postman/dashboard) β monitoring runs, reading metrics and managing individual sends
* [FAQ](/campaigns/gift-card-postman/faq) β common questions and how to handle support cases
# Introduction
{% hint style="info" %}
Check out this feature live on our[ demo store](https://fifty-seven-apps.myshopify.com/products/gift-card-1?_bt=BAh7BkkiC19yYWlscwY6BkVUewhJIglkYXRhBjsAVEkiI2ZpZnR5LXNldmVuLWFwcHMubXlzaG9waWZ5LmNvbQY7AEZJIghleHAGOwBUSSIdMjAyNS0wOC0yOVQwOTozOTozNy4wODhaBjsAVEkiCHB1cgY7AFRJIh5wZXJtYW5lbnRfcGFzc3dvcmRfYnlwYXNzBjsARg%3D%3D--966aed66aabdb94c39b72fe6dd38d6c7a29aea48).
{% endhint %}
Gift Card Postman is an innovative feature that enhances the customer experience in your store by allowing users to send gift cards to their friends and loved ones. It adds tremendous value to your service by enabling customers to personalize the gifting process during their purchases.
### Key Features:
1. **Custom Delivery Date**:
* Customers can select a specific delivery date for the gift card, ensuring it arrives precisely on the occasion, whether it's a birthday, anniversary, or any significant event.
2. **Personalized Message**:
* Customers can add a heartfelt custom message to the gift card, allowing them to express their sentiments and make the gift even more special for the recipient.
3. **Editable Email Template**:
* Make use of our convenient email content editor to tailor the gift card email template to match your storeβs branding and tone. It ensures a seamless fit with your overall communication strategy.
4. **Custom Gift Card Amounts**:
* Let customers enter their own gift card amount on the product page instead of choosing from fixed denominations. The amount they enter sets both the price they pay and the value of the issued gift card. See [Setup](/campaigns/gift-card-postman/setup#custom-gift-card-value) for details.
### Benefits:
* **Customer Satisfaction**:
* Elevate customer satisfaction by offering a feature that allows them to thoughtfully send gift cards to friends. A personalized and well-timed gift card can lead to positive customer experiences that reinforce loyalty.
* **Acquisition of New Customers**:
* Increase your customer base as recipients of these gift cards are likely to become new customers. Their positive initial interaction with your brand through the gift card experience can pave the way for future purchases and recommendations.
Incorporating the Gift Card Postman feature into your store not only enhances the shopping experience for existing customers but also acts as an organic marketing tool to attract new customers through thoughtful gifting.
# Setup
Setting Up Gift Card Postman Campaign
Setting up a Gift Card Postman campaign is easy and involves the following steps. All steps can be completed from campaign configuration screen, so first navigate to *Campaigns* -> *New Campaign* -> *Gift Card Postman*.
1. **Add App Block to Product Page**
* The app checks if the block is installed in your theme. If not, select your theme and click *Add*.
* You'll be redirected to the Product Page Customizer with the App Block added. Move it above the Buy Buttons.
* Use Verify button to check if app block was successfully added
2. **Create App Gift Card Product**
* Mimic your current Gift Card Product and add fields for scheduling and friend-sending.
* Select your Store Gift Card Product and click *Create App Product*. Find your current Gift Card Product, select it and click *Add* button:
* Initially, the product is in Draft. You will set set it to Active when campaign setup is ready.
3. **Configure Campaign Settings**
* Adjust settings:
* **Set Expiry Dates**: Specify expiration dates for purchased gift cards.
* **Value Matching**: Align the gift card value with the amount paid, ideal for situations where a discount code is used.
* **Custom Gift Card Value**: Let customers enter their own gift card amount on the product page. See [Custom Gift Card Value](#custom-gift-card-value) below.
* **Assign to Customer**: Assign the gift card to the purchasing customer.
* **Assign to Recipient**: Directly assign the gift card to the intended recipient.
* **Fulfillment Options**: Determine when to update the fulfillment status of the purchased items.
* **Order Tags**: Optionally add tags to gift card orders for easy tracking.
* **Delivery Methods**: Choose how gift cards will be delivered to recipients. Learn more about delivery options [here](/misc/sending-customer-notifications).
* When done, click Create button to create your new Gift Card Postman campaign
4. **Activate Campaign**
* Activate the campaign and change the App Gift Card product status from Draft to Active.
* Your product page will now show additional scheduling and sending fields.
## Custom Gift Card Value
By default customers pick from the fixed denominations on your gift card product. Enable **custom gift card value** to also let them enter their own amount.
When you turn on **Enable custom gift card value** in the campaign settings:
* You'll be asked to grant a one-time permission so the app can set the cart price. This uses Shopify's Cart Transform (replacing the deprecated Shopify Scripts) and needs no manual code or setup.
* The app adds a **Custom** denomination to your app gift card product.
* On the product page, when the buyer selects the **Custom** denomination, a **Gift Card Value** field appears. The amount they enter sets **both** the cart price and the value of the issued gift card, so the two always match.
* Custom amounts are capped by your plan's gift card issue limit.
{% hint style="info" %}
The custom value field is shown only when customers are shopping in your store's **default currency**, because the gift card is always issued in that currency.
{% endhint %}
# Dashboard
Monitoring and managing your Gift Card Postman campaign
Once a Gift Card Postman campaign is created, the campaign dashboard becomes your single screen for activating, monitoring and managing it. Open it from **Campaigns β Your campaign name**.
The dashboard is split into three areas:
* **Header** β campaign title, status badge and activation control
* **Performance** β summary metrics and time-series charts
* **Runs** β every gift card the campaign has produced, with row-level actions
* **Settings panel** β slide-out editor for the campaign configuration
### Header
The page title shows the campaign name with an **Active** or **Inactive** badge and the date the campaign was created.
* **Activate / Deactivate** β toggles the campaign on or off. While inactive, no new gift cards are scheduled or sent.
* **Back to Campaigns** β returns to the campaigns list. If the settings panel has unsaved changes you'll be asked to confirm.
### Toolbar
* **Date range** β filters the metrics and charts. Available ranges: *Last 7 days*, *Last 30 days*, *Last 90 days*, *Last 365 days* and *Year to date*. The default is *Last 30 days*.
* **Settings** (gear icon) β opens the slide-out settings panel on the right.
{% hint style="info" %}
Statistics are collected starting **April 4th, 2026**. Data from before that date is not available, even when a wider date range is selected.
{% endhint %}
### Performance metrics
Five summary cards show totals for the selected date range:
| Metric | What it counts |
| ----------------------- | ----------------------------------------------------------- |
| **Gift cards sent** | Number of gift cards created by this campaign |
| **Value issued** | Total monetary value of those gift cards |
| **Gift cards redeemed** | Number of issued gift cards that customers have used |
| **Redeemed value** | Total monetary value redeemed |
| **Order total** | Total value of orders that used those gift cards as payment |
Below the cards, the same five metrics are plotted as daily line charts so you can see trends over the selected period. Hover over any point to see the exact date and value. If there is no data in the range, the chart shows an empty state.
### Runs
The runs table lists every individual gift card the campaign has produced. Each row is a single *campaign run*.
**Columns**
* **#** β sequential run number
* **Date** β when the run was created
* **Status** β current state (see below). Scheduled runs also show the planned send date and timezone.
* **Recipient** β recipient email entered by the buyer (falls back to the order's customer email)
* **Order** β links to the originating order in Shopify Admin
* **Gift Card** β links to the issued gift card in Shopify Admin (last 4 characters shown). Refunded gift cards are flagged with a **Refunded** badge.
* **Emails** β links to every email sent for this run
**Statuses**
| Badge | Meaning |
| ------------- | ------------------------------------------------ |
| *Scheduled* | Waiting until the buyer's chosen delivery date |
| *Queued* | Picked up by the queue, waiting to be processed |
| *In progress* | Currently being processed |
| *Completed* | Gift card was created and delivered |
| *Error* | Processing failed β open *Show logs* for details |
| *Cancelled* | Run was cancelled before it was sent |
**Search and filter**
* Search box β match by recipient email or order
* Status filter β narrow the list to one or more statuses
* Pagination β 25 runs per page
The table updates in real time, so newly created runs and status changes appear without a refresh.
#### Row actions
Select a row to reveal actions for that run:
* **Send now** β sends (or resends) the gift card to the recipient immediately. When resending, Shopify's default gift card email is used.
* **Update** β opens a dialog to change the **recipient email**, **scheduled delivery date** or **gift card value** before the run is sent.
* **Cancel** β only available for **Scheduled** runs. Stops the run from ever being sent.
* **Show logs** β opens the run's processing log, useful for diagnosing *Error* runs.
*Send now* and *Update* are hidden for runs that are already *In progress*.
### Settings panel
Click the gear icon in the toolbar to slide open the campaign settings panel. From here you can edit every option that was available during setup β expiry dates, value matching, customer/recipient assignment, fulfillment, order tags, delivery methods and the email template β without leaving the dashboard. Changes are saved with the panel's *Save* bar.
# FAQ
#### 1. Customer didn't receive the purchased gift card
Open the campaign dashboard (**Campaigns β Your campaign name**) and find the run in the runs table. You can search by **recipient email** or **order**.
* Check the **Status** column. If it is **Error**, select the row and click **Show logs** to view the processing log.
* From the same row actions you can also use **Send now** to resend the gift card.
***
#### 2. Customer entered an incorrect recipient email or delivery date
Open the campaign dashboard, find the run in the runs table and select it.
* Click **Update** to change the recipient email, scheduled delivery date or gift card value.
***
#### 3. I need to resend the gift card to a customer
Open the campaign dashboard, find the run in the runs table and select it.
* Click **Send now** to resend the gift card.
* **Important:** When resending, the **default Shopify gift card email** is used, not the campaign's email template.
***
#### 4. I need to stop a scheduled gift card from being sent
Open the campaign dashboard, find the **Scheduled** run in the runs table and select it.
* Click **Cancel** to stop the run from being processed.
***
#### 5. Why are my dashboard metrics empty or partial?
Statistics are only collected from **April 4th, 2026** onwards. Runs created before that date are still listed in the runs table but are not reflected in the summary cards or charts.
***
#### 6. The custom gift card value field isn't showing on my product page
* Make sure **Enable custom gift card value** is turned on in your campaign settings and the campaign is **active**.
* The field only appears once the **Custom** denomination is selected on the product page.
* It is shown only to customers shopping in your store's **default currency**.
* Confirm the Gift Card Postman app block is added to your product page (see [Setup](/campaigns/gift-card-postman/setup)).
# Gift Card Rewards
Reward customers with free gift cards
{% hint style="info" %}
Explore our Flow Template library to find a flow similar to the Gift Card Rewards flow. It is ideal for creating more complex campaigns.
{% endhint %}
### Overview
Gift Card Rewards is an automated campaign that issues gift cards to customers when they complete a qualifying purchase. A gift card code is dispatched right after the order is paid, creating an immediate incentive to encourage repeat business.
**Common use cases:**
* Reward loyal customers with gift cards on every purchase
* Encourage larger orders through tiered spending thresholds
* Run time-limited promotions (e.g., "Get a $10 gift card on orders over $50 this weekend")
* Target specific customer segments or product collections
### π‘Common Use Cases
**Cashback on Every Order** β Give 5% back as a gift card on every purchase, with no minimum. Perfect for: Stores wanting a simple loyalty mechanic that brings customers back.
**Tiered Spending Incentive** β Set tiers at $50/$5, $100/$15, $200/$30 to reward larger baskets. Perfect for: Encouraging customers to add more items to hit the next reward level.
**Weekend Flash Promotion** β Use active dates to run a Friday-to-Sunday campaign offering a $10 gift card on orders over $75. Perfect for: Short-term sales events without creating discount codes.
**Collection-Specific Reward** β Apply the campaign only to a "New Arrivals" collection with a 10% reward. Perfect for: Driving traffic to specific product lines or clearing seasonal inventory.
**VIP Customer Appreciation** β Restrict eligibility to a "VIP" customer segment and offer higher reward tiers. Perfect for: Rewarding your best customers differently from the general audience.
**First Purchase Welcome Gift** β Set max gift cards per customer to 1 and offer a $10 reward on any order. Perfect for: Turning first-time buyers into repeat customers with a guaranteed second visit.
### Creating a Campaign
Navigate to **Campaigns** in the app and click **New Campaign** > **Gift Card Rewards**.
#### Title
Give your campaign a descriptive name (e.g., "Holiday 10% Cashback" or "VIP $20 Reward"). This title is visible only to you and your staff.
***
#### Gift Card Value
This section controls how the gift card value is calculated and which products qualify.
**Value Type**
Choose between two modes using the tabs:
**Fixed Amount** β Define tiers with minimum order values and corresponding gift card amounts. When an order qualifies, the highest matching tier is used.
**Percentage of Order** β The gift card value is calculated as a percentage of the qualifying line items total.
**Tiers (Fixed Amount only)**
Each tier has:
* **Minimum value** β The minimum line items total required to qualify
* **Gift card value** β The gift card amount issued when this tier is reached
Tiers are evaluated from highest to lowest. The first tier where the order total meets the minimum is used. You must have at least one tier.
**Example:**
| Minimum Value | Gift Card Value |
| ------------- | --------------- |
| $100 | $15 |
| $50 | $5 |
An order of $120 would receive a $15 gift card. An order of $75 would receive a $5 gift card. An order of $30 would not qualify.
**Applies To**
Control which products count toward the qualifying total:
* **All products** β Every product in the order counts
* **Specific collections** β Only products from selected collections count
* **Specific products** β Only selected products and their variants count
When using specific products or collections, only the matching line items are used to calculate the order total and gift card value.
***
#### Minimum Purchase Requirements
Set additional conditions the order must meet before a gift card is issued:
* **No minimum requirements** β Any qualifying order receives a gift card
* **Minimum purchase amount** β The qualifying line items total must reach a specified amount
* **Minimum quantity of items** β The order must contain at least a specified number of qualifying items
***
#### Eligibility
Control which customers can receive gift cards from this campaign:
* **All customers** β Any customer who places a qualifying order
* **Specific customer segments** β Only customers belonging to a selected Shopify customer segment
* **Specific customers** β Only individually selected customers
***
#### Active Dates
Set a time window during which the campaign is active. Orders placed outside this window will not trigger gift cards, even if the campaign status is Active.
* **Start date** β When the campaign begins accepting qualifying orders
* **End date** β When the campaign stops (optional β leave blank for no end date)
Each date includes a time and timezone picker for precise control.
***
#### Gift Cards
Configure the gift card properties:
* **Auto-expiration** β Set when the issued gift card expires (never, or after a specified period from creation)
* **Max gift cards per customer** β Limit how many gift cards a single customer can receive from this campaign (e.g., set to 1 for one-time promotions)
* **Gift card message** β A customer-visible message attached to the gift card (max 200 characters)
* **Gift card note** β An internal note not visible to the customer
***
#### Delivery
Choose how the gift card is delivered to the customer:
* **Shopify Email** β Uses Shopify's built-in gift card notification. Free, no additional setup required.
* **App Email** β Sends a custom-designed email using your configured email template. Allows full control over design and branding. Uses App Email credits (1 per email)
* **Klaviyo** β Triggers a Klaviyo event with gift card data. You design the email in Klaviyo.
* **Shopify Flow** β Triggers a Flow event. Use Shopify Flow to build custom delivery logic.
When using App Email, select an email template from your configured templates.
Read more about different gift card delivery options in [Sending Customer Notifications](/misc/sending-customer-notifications) section
***
#### Test Mode
Enable test mode to validate your campaign before going live. When test mode is on, only orders placed with the specified test email address will be processed. All other orders are ignored.
***
### Activating the Campaign
After creating the campaign, it starts in **Inactive** status. To activate:
1. Go to **Campaigns** and find your campaign
2. Click into the campaign detail
3. Toggle the status to **Active**
When activated, the app registers a Shopify webhook to listen for paid orders. The webhook includes a price filter so only potentially qualifying orders trigger processing.
***
### How It Works
When a customer places an order:
1. **Active dates check** β Is the current time within the campaign's active window?
2. **Customer eligibility** β Does the customer match the eligibility criteria?
3. **Line item filtering** β Which products in the order match the "Applies to" setting?
4. **Minimum requirements** β Do the qualifying items meet the minimum purchase amount or quantity?
5. **Value calculation** β What gift card value does the order qualify for (tier match or percentage)?
6. **Per-customer limit** β Has the customer already reached the maximum gift cards for this campaign?
7. **Gift card issuance** β A gift card is created and delivered via the configured method
Each step is logged in the campaign run history for troubleshooting.
***
### Storefront Display (Optional)
You can show customers the potential gift card they'll earn before they complete their purchase. Two extension options are available:
#### Theme Extension (Cart Page)
Add the **Gift Card Reward Banner** block to your theme. It automatically:
* Calculates the potential gift card based on current cart contents
* Updates in real time as items are added or removed
* Hides when no gift card is available
* Supports customizable colors (background, text, accent)
#### Checkout Extension
The **Gift Card Reward** checkout extension displays a banner at checkout showing the potential gift card amount. It uses the same calculation logic as the theme extension.
***
### Campaign Runs
Every time the campaign processes an order, a **Campaign Run** is created. View runs from the campaign detail page to see:
* **Status** β Finished, Error, Skipped, or Limits Error
* **Sent** β Number of gift cards issued
* **Skipped** β Number of orders that didn't qualify
* **Gift card details** β ID and last 4 characters of issued gift cards
***
### Tips
* **Start with test mode** β Always validate with a test order before activating
* **Use tiers for upselling** β Show customers the next threshold to encourage larger orders (e.g., "Spend $50 more to get a $15 gift card instead of $5")
* **Combine with active dates** β Run weekend-only or holiday promotions without manually toggling the campaign
* **Percentage mode for simplicity** β Use a flat percentage (e.g., 5%) when you don't need tiered thresholds
* **Check campaign runs** β If a customer reports not receiving a gift card, check the run logs to see which step filtered them out
# Store Credit Rewards
Reward purchases with store credit cashback
Store Credit Rewards automatically adds store credit to a customer's account when they place a qualifying order. It works exactly like Gift Card Rewards, but instead of issuing a gift card, the reward is credited straight to the customer's Shopify store credit balance β no codes to lose, applied automatically at checkout.
### How It Works
The campaign listens for paid orders in your store. When an order qualifies (based on your reward rules, conditions, and eligibility settings), the configured store credit amount is added to the customer's account and an optional notification email is sent.
**Each store credit reward costs 5 campaign credits.**
{% hint style="info" %}
Store credit is issued in your store's currency and is redeemable at checkout when the customer is signed in to their customer account (new customer accounts).
{% endhint %}
### π‘Common Use Cases
**Percentage Cashback** β Give 5% of every order back as store credit. Perfect for: A simple, always-on loyalty program that brings customers back.
**Tiered Order Rewards** β $5 credit for orders over $50, $15 over $100, $30 over $200. Perfect for: Encouraging larger baskets.
**VIP Segment Rewards** β 10% cashback limited to a customer segment. Perfect for: Loyalty tiers and rewarding your best customers.
**Product Launch Boost** β Reward store credit only for orders containing specific products or collections, within active dates. Perfect for: Driving sales of a new collection for a limited time.
### Creating a Campaign
Navigate to **Campaigns > New Campaign > Store Credit Rewards** to create a new rewards campaign.
#### Title
Give your campaign a descriptive name (e.g., "5% Store Credit Cashback"). This is for your own reference β customers won't see it.
#### Reward
Choose how the store credit value is calculated:
* **Fixed amount (tiers)** β Define one or more tiers with a minimum order value and the store credit amount awarded. The highest tier the order reaches determines the reward.
* **Percentage of order** β Award a percentage of the qualifying order total as store credit.
**Applies to**
Limit which products count towards the reward:
* **All products** β The whole order qualifies
* **Specific collections** β Only items from selected collections count
* **Specific products** β Only selected products count
When limited to specific products or collections, both the minimum requirements and the reward value are calculated from the qualifying items only. Item prices are taken after discounts, so cashback matches what the customer actually paid.
#### Conditions
**Minimum purchase requirements**
* **No minimum requirements**
* **Minimum purchase amount** β Qualifying items must total at least this amount
* **Minimum quantity of items** β The order must contain at least this many qualifying items
**Eligibility**
* **All customers**
* **Specific customer segments** β Only members of a selected Shopify customer segment qualify
* **Specific customers** β Only individually selected customers qualify
#### Limits & Expiry
* **Active dates** β Optional start and end date/time for the campaign. Orders outside this window are skipped.
* **Store credit expiry** β Never expires, a period after creation, or a fixed date. Expired credit is automatically removed from the customer's balance by Shopify.
* **Max store credit rewards per customer** β Caps how many times a single customer can be rewarded by this campaign.
#### Delivery
Choose how the customer is notified:
* **App Email** β Uses Gift Card Factory's email sending (requires email configuration in Settings)
* **Klaviyo** β Triggers a Klaviyo event for use in Klaviyo flows
* **Shopify Email (store credit)** β Shopify sends its own store credit notification when the credit is added
You also select an **email template**. Available template types:
* **Store Credit Rewards** β Pre-built template designed for reward notifications
* **Custom** β Any custom template you've created
**Template Variables**
The following variables are available in your email template:
* `issued_store_credit.amount` β The store credit amount awarded
* `issued_store_credit.currency_code` β Currency code
* `issued_store_credit.balance_after_transaction` β The customer's store credit balance after the reward
* `customer.email` β Customer's email
* `customer.first_name` β Customer's first name
* `customer.last_name` β Customer's last name
* `customer.id` β Shopify customer ID
Read more about different delivery options in [Sending Customer Notification](/misc/sending-customer-notifications) section.
#### Test Mode
Enable test mode to process rewards only for orders placed with a specific email address. Use this to safely verify your configuration before going live β orders from any other email are skipped.
### Campaign Dashboard
After creating a campaign, access its dashboard from the campaigns list. The dashboard shows:
#### Metrics
* **Rewards sent** β Total number of store credit rewards issued
* **Store credit issued** β Total store credit value issued by this campaign
Each metric includes a line chart showing trends over a selectable time range (7 days, 30 days, 90 days, 1 year, or year-to-date).
#### Campaign Runs
A table showing each processed order, including:
* Run number and date
* Status (In Progress, Finished, Error)
* Store credit amount with a link to the rewarded customer
* The triggering order
#### Settings
The campaign configuration can be edited directly from the dashboard using the settings panel.
#### Activate / Deactivate
Toggle the campaign on or off. Activating registers the order webhook; deactivating removes it, so no further orders are processed.
### Tips
* **Start with test mode** β Place a test order with your own email to confirm the reward value, expiry, and email look right before activating for everyone
* **Use expiry to drive urgency** β Store credit that expires in 60-90 days nudges customers to return sooner; pair it with a [Store Credit Reminders](/campaigns/store-credit-reminders) campaign so nobody forgets
* **Cap per-customer rewards** β Use the per-customer limit to keep percentage cashback campaigns predictable
* **Store credit vs gift cards** β Store credit can't be transferred or gifted, which makes it ideal for personal loyalty rewards; use [Gift Card Rewards](/campaigns/gift-card-rewards) when the reward should be shareable
# Gift Card Reminders
Turn unused gift cards into profit
Gift Card Reminders automatically sends reminder emails to customers about their unused or expiring gift cards. This helps recover unredeemed gift card value and drives customers back to your store.
### How It Works
The campaign runs on a schedule you define. Each time it runs, it queries your Shopify store for gift cards that match your selection criteria, then sends a reminder email to each eligible customer.
**Each reminder email costs 1 campaign credit.**
### π‘Common Use Cases
**Expiring Gift Card Alert** β Run daily, targeting gift cards expiring in the next 30 days. Perfect for: Making sure customers don't lose their gift card value by forgetting to use it before it expires.
**Post-Holiday Follow-Up** β Use fixed dates to target gift cards created during Black Friday / Christmas, sent 60 days later. Perfect for: Re-engaging holiday gift card recipients who haven't returned to shop yet.
**Monthly Unused Balance Nudge** β Run monthly with dynamic dates (created 60-90 days ago) and a minimum balance of $10. Perfect for: Gently reminding customers about gift cards that have been sitting unused without over-emailing.
**Recipient Reminder** β Set email recipient to "Recipient or customer" and target gift cards created 14-30 days ago. Perfect for: Reminding the actual gift recipient (not just the buyer) that they have a gift card waiting.
**High-Value Recovery** β Set a high minimum balance (e.g., $50) and target gift cards created 30+ days ago. Perfect for: Prioritizing outreach to customers with significant unredeemed value.
### Creating a Campaign
Navigate to **Campaigns > New Campaign > Gift Card Reminders** to create a new reminder campaign.
#### Title
Give your campaign a descriptive name (e.g., "30-day expiry reminder" or "Monthly unused gift card nudge"). This is for your own reference β customers won't see it.
#### Schedule
Configure when and how often the campaign runs:
* **Start date** β The first date the campaign should run
* **Start time** β Hour and minute (in 15-minute increments)
* **Timezone** β The timezone used for scheduling
* **Repeat** β Optional recurrence:
* **Non-recurring** β Runs once at the specified date/time
* **Recurring** β Runs repeatedly at a set interval (e.g., every 1 day, every 2 weeks, every 1 month)
#### Selection Criteria
Define which gift cards should trigger a reminder. Only **enabled** gift cards are included.
**Minimum Balance**
Set a minimum remaining balance (e.g., `5.00`). Gift cards with a balance below this amount will be skipped. Leave empty or set to `0` to include all balances.
**Trigger Type**
Choose what date property determines which gift cards are selected:
**Option 1: Send based on created at date**
Select gift cards by when they were created. Two sub-modes are available:
* **Dynamic date** β Relative to the current run date. You specify a "from" and "to" in days ago. For example, setting "from: 61" and "to: 60" means each time the campaign runs, it picks gift cards created between 61 and 60 days before that run. This is useful for recurring campaigns that should always target a specific age range.
* **Fixed date** β A specific calendar date range. Gift cards created between the "from" and "to" dates will be included. This is useful for one-time campaigns targeting a known batch of gift cards.
**Option 2: Send based on expiry date**
Select gift cards that are about to expire. You specify how many days before expiry the reminder should be sent. For example, setting "30 days" means gift cards expiring within the next 30 days from the run date will be included.
#### Email Recipient
Choose who receives the reminder email:
* **Customer assigned to gift card** β The customer linked to the gift card in Shopify
* **Recipient assigned to gift card** β The recipient field on the gift card (if one was set when the gift card was created/sent)
* **Recipient or (if not found) customer** β Tries the recipient first, falls back to the customer if no recipient is available
#### Delivery
Choose how the reminder email is sent:
* **Shopify Email** β Uses Shopify's built-in email (default, no additional setup)
* **App Email** β Uses Gift Card Factory's email sending (requires email configuration in Settings)
* **Shopify Flow** β Triggers a Shopify Flow event instead of sending directly (you build the email in Flow)
* **Klaviyo** β Triggers a Klaviyo event for use in Klaviyo flows
You also select an **email template** for the reminder. Available template types:
* **Gift Card Reminders** β Pre-built template designed for reminders
* **Custom** β Any custom template you've created
**Template Variables**
The following variables are available in your email template:
* `gift_card.last_characters` β Last 4 characters of the gift card code
* `gift_card.initial_value.amount` β Original gift card value
* `gift_card.initial_value.currency` β Currency code
* `gift_card.balance.amount` β Current remaining balance
* `gift_card.balance.currency` β Currency code
* `gift_card.expires_on` β Expiry date (if set)
* `gift_card.image` β Gift card image URL
* `customer.email` β Customer's email
* `customer.first_name` β Customer's first name
* `customer.last_name` β Customer's last name
* `customer.id` β Shopify customer ID
* `recipient.name` β Recipient's name
* `recipient.email` β Recipient's email
Read more about different delivery options in [Sending Customer Notification](/misc/sending-customer-notifications) section.
### Campaign Dashboard
After creating a campaign, access its dashboard from the campaigns list. The dashboard shows:
#### Metrics
* **Reminders sent** β Total reminder emails delivered
* **Remaining balance** β Combined balance of gift cards that were reminded
* **Gift cards redeemed** β Number of reminded gift cards that were subsequently used
* **Redeemed value** β Monetary value of those redeemed gift cards
* **Order total** β Total order value from orders where reminded gift cards were used
Each metric includes a line chart showing trends over a selectable time range (7 days, 30 days, 90 days, 1 year, or year-to-date).
#### Campaign Runs
A table showing each time the campaign ran, including:
* Run number and date
* Status (In Progress, Finished, Error)
* Number of emails sent
* Number of skipped gift cards
#### Settings
The campaign configuration can be edited directly from the dashboard using the settings panel.
#### Activate / Deactivate
Toggle the campaign on or off. When deactivated, the campaign will not run on its next scheduled time. When reactivated, the next run is recalculated based on the schedule.
### Tips
* **Expiry reminders** β Schedule a recurring campaign (e.g., daily) with a 30-day expiry window to catch all upcoming expirations
* **Re-engagement** β Use dynamic dates with a recurring schedule (e.g., weekly) to remind customers about gift cards created 60-90 days ago that haven't been fully used
* **One-time blast** β Use fixed dates with a non-recurring schedule to target a specific batch (e.g., all gift cards from a holiday promotion)
* **Minimum balance** β Set a reasonable minimum (e.g., $5) to avoid sending reminders for nearly depleted gift cards
* **Space out your reminders** β Be mindful of how often the same customer receives a reminder. Sending too many emails in a short period can feel overwhelming β a well-timed single reminder is more effective than frequent ones
# Store Credit Reminders
Bring customers back to spend their store credit
Store Credit Reminders automatically sends reminder emails to customers about their unused or expiring store credit. Store credit is applied automatically at checkout, but customers often forget they have it β a well-timed reminder drives them back to your store.
### How It Works
The campaign runs on a schedule you define. Each time it runs, it finds customers whose store credit accounts match your selection criteria, then sends a reminder email to each eligible customer. Before sending, the customer's live balance is re-checked so reminders always reflect the current amount.
**Each reminder email costs 1 campaign credit.**
{% hint style="info" %}
Store credit is matched in your store's currency. Customers redeem store credit at checkout when they are signed in to their customer account.
{% endhint %}
### π‘Common Use Cases
**Expiring Credit Alert** β Run daily, targeting store credit expiring in exactly 30 days. Perfect for: Making sure customers use their credit before it expires.
**Post-Reward Follow-Up** β Use dynamic dates to target credit added 60 days ago. Perfect for: Re-engaging customers who earned cashback or a reward but haven't returned to spend it.
**High-Value Recovery** β Set a high minimum balance (e.g., $50). Perfect for: Prioritizing outreach to customers with significant unspent credit.
**Subscribers-Only Nudge** β Enable the marketing consent filter. Perfect for: Stores that prefer to email only customers subscribed to email marketing.
### Creating a Campaign
Navigate to **Campaigns > New Campaign > Store Credit Reminders** to create a new reminder campaign.
#### Title
Give your campaign a descriptive name (e.g., "30-day expiry reminder"). This is for your own reference β customers won't see it.
#### Schedule
Configure when and how often the campaign runs:
* **Start date** β The first date the campaign should run
* **Start time** β Hour and minute (in 15-minute increments)
* **Timezone** β The timezone used for scheduling
* **Repeat** β Optional recurrence:
* **Non-recurring** β Runs once at the specified date/time
* **Recurring** β Runs repeatedly at a set interval (e.g., every 1 day, every 2 weeks, every 1 month)
#### Selection Criteria
Define which store credit balances should trigger a reminder.
**Minimum Balance**
Set a minimum store credit balance (e.g., `10.00`). Customers with a balance below this amount will be skipped. Leave empty or set to `0` to include all balances.
**Trigger Type**
Choose what date property determines which customers are selected:
**Option 1: Send based on last credited date**
Select customers by when store credit was last added to their account. Two sub-modes are available:
* **Dynamic date** β Relative to the current run date. You specify a "from" and "to" in days ago. For example, setting "from: 61" and "to: 60" means each time the campaign runs, it picks customers whose credit was last added between 61 and 60 days before that run. This is useful for recurring campaigns that should always target a specific age range.
* **Fixed date** β A specific calendar date range. Customers whose credit was last added between the "from" and "to" dates will be included. This is useful for one-time campaigns targeting a known batch of credits.
**Option 2: Send based on expiry date**
Select customers whose store credit is about to expire. You specify in how many days the credit expires. For example, setting "30 days" means customers with credit expiring exactly 30 days from the run date will be included. These dates are recalculated on every run, so a daily recurring campaign catches every upcoming expiry.
**Marketing Consent**
Optionally enable **Only send to customers subscribed to email marketing** to skip customers who haven't opted in to marketing emails. By default, reminders are treated as account notifications and sent to all matching customers.
#### Delivery
Choose how the reminder email is sent:
* **App Email** β Uses Gift Card Factory's email sending (requires email configuration in Settings)
* **Klaviyo** β Triggers a Klaviyo event for use in Klaviyo flows
You also select an **email template** for the reminder. Available template types:
* **Store Credit Reminders** β Pre-built template designed for reminders
* **Custom** β Any custom template you've created
**Template Variables**
The following variables are available in your email template:
* `store_credit.balance` β Current store credit balance
* `store_credit.currency_code` β Currency code
* `store_credit.expires_at` β Soonest expiry date of the customer's credit (empty when the credit doesn't expire)
* `customer.email` β Customer's email
* `customer.first_name` β Customer's first name
* `customer.last_name` β Customer's last name
* `customer.id` β Shopify customer ID
Read more about different delivery options in [Sending Customer Notification](/misc/sending-customer-notifications) section.
### Campaign Dashboard
After creating a campaign, access its dashboard from the campaigns list. The dashboard shows:
#### Metrics
* **Reminders sent** β Total reminder emails delivered
* **Remaining balance** β Combined store credit balance of customers that were reminded
Each metric includes a line chart showing trends over a selectable time range (7 days, 30 days, 90 days, 1 year, or year-to-date).
#### Campaign Runs
A table showing each time the campaign ran, including:
* Run number and date
* Status (In Progress, Finished, Error)
* Number of emails sent
* Number of skipped customers
#### Settings
The campaign configuration can be edited directly from the dashboard using the settings panel.
#### Activate / Deactivate
Toggle the campaign on or off. When deactivated, the campaign will not run on its next scheduled time. When reactivated, the next run is recalculated based on the schedule.
### Tips
* **Expiry reminders** β Schedule a recurring daily campaign with a 30-day expiry window to catch every upcoming expiration
* **Re-engagement** β Use dynamic dates with a recurring schedule to remind customers about credit added 60-90 days ago
* **Minimum balance** β Set a reasonable minimum (e.g., $5) to avoid sending reminders for nearly depleted balances
* **Recently added credit** β The customer index Shopify uses for matching can lag a few minutes behind very recent credits; balances are always re-checked live before sending
* **Space out your reminders** β Be mindful of how often the same customer receives a reminder. A well-timed single reminder is more effective than frequent ones
# Scheduled Gift Cards
Scheduled Gift Cards sends a gift card to matching customers on a recurring schedule. The campaign resolves recipients (via a customer query, segment, or explicit list) each time it runs, then creates and delivers a personalized gift card to each one. Useful for birthdays, anniversaries, loyalty rewards, or any other recurring occasion.
**Each scheduled gift card costs 5 campaign credits.**
### π‘Common Use Cases
**Daily Birthday Campaign** β Send a $10 gift card to every customer on their actual birthday, every day at 9:00 AM. Perfect for: Stores with a large customer base who want to celebrate every customer's birthday.
**Monthly Birthday Campaign** β Send a $15 gift card to all customers with birthdays in the current month, on the 1st day of each month. Perfect for: Smaller stores or those who want to batch birthday communications.
**VIP Birthday Rewards** β Send a $25 gift card to VIP customers only on their birthdays. Perfect for: Rewarding your most valuable customers with special birthday treatment.
**Birthday Month Welcome** β Send a gift card at the beginning of the month to all customers with birthdays that month. Perfect for: Building anticipation and encouraging purchases throughout the birthday month.
**Regional Birthday Campaign** β Send birthday gift cards to customers in specific locations with region-appropriate values. Perfect for: Stores with different strategies for different markets.
### How It Works
1. The campaign runs on your configured schedule (e.g., daily at 9 AM)
2. It executes a Shopify customer query that you define β this query is evaluated with today's date to match customers whose birthday is today (or this month, etc.)
3. For each matching customer, a gift card is created and delivered via your chosen method
4. Results are logged in the campaign run history
### Creating a Campaign
Navigate to **Campaigns > New Campaign > Scheduled Gift Cards** to create a new campaign.
#### Title
Give your campaign a descriptive name (e.g., "Daily Birthday $10 Gift Card"). This is for your own reference only.
#### Customer Query
This is the most important field β it defines which customers receive a gift card each time the campaign runs.
The query uses **Shopify's customer search syntax** with **Liquid date filters** that are evaluated at run time. This lets you write dynamic queries that match customers based on today's date.
**Example β match customers whose birthday is today:**
**Example β tags in `birthday-MM-DD` format** (e.g., `birthday-06-07`):
```
tag:birthday-{{ "now" | date: "%m-%d"}}
```
When the campaign runs on June 7th, the Liquid template renders to `tag:birthday-06-07`, matching customers with that exact tag. This is the recommended tag format because it allows a clean exact match.
**Important: Shopify search only supports prefix wildcards** (e.g., `birthday-*`), not suffix wildcards (e.g., `*06-07`). This means you cannot use a wildcard to match the date portion at the end of a tag. Your tag format must put the known prefix first, followed by the dynamic date part.
**What about `dob:YYYY-MM-DD` tags?** (e.g., `dob:1992-06-07`)
This is a common format used by birthday collection apps. However, because the year varies per customer, you cannot match just the month-day part with a Shopify search query β suffix wildcards like `dob:*06-07` are not supported.
If your customers have `dob:` tags, you have two options:
* **Add a second tag** in `birthday-MM-DD` format (e.g., use Shopify Flow to automatically add `birthday-06-07` alongside `dob:1992-06-07`)
* **Replace the tag format** β re-tag customers using the `birthday-MM-DD` format instead
**How to set up birthday tags:**
Customer birthday tags need to be added to your customers in Shopify. Common approaches:
* Collect birthdays via a form on your storefront and tag customers automatically using Shopify Flow
* Import birthday tags via CSV
* Use a third-party app that collects and tags customer birthdays
You can use the **Test Query** button next to the field to verify how many customers currently match your query. The campaign supports up to 250 matching customers per run.
Need help writing a query? Contact us at or read our [Customer Query documentation](https://docs.giftcardfactory.app/misc/customers-query-selector).
#### Gift Card Value
The fixed monetary value of the gift card (e.g., `10.00` for a $10 gift card). Every customer receives the same value.
#### Gift Card Message
An optional customer-visible message attached to the gift card (max 200 characters). For example: "Happy Birthday! Here's a gift from us."
#### Gift Card Expiry
Control when the gift card expires:
* **Never expire** β The gift card has no expiration date
* **Expire relative to creation date** β The gift card expires after a set period (e.g., 30 days, 6 months, 1 year after creation)
* **Expire on a specific date** β The gift card expires on a fixed calendar date
#### Schedule
Configure when and how often the campaign runs:
* **Start date** β The first date the campaign should run
* **Start time** β Hour and minute (in 15-minute increments)
* **Timezone** β The timezone used for scheduling
* **Repeat** β Optional recurrence:
* **Non-recurring** β Runs once at the specified date/time
* **Recurring** β Runs repeatedly at a set interval (e.g., every 1 day, every 1 week, every 1 month)
For birthday campaigns, a **daily recurring schedule** is the most common setup β it ensures every customer gets their gift card on their actual birthday.
#### Delivery
Choose how the gift card is delivered:
* **Shopify Email** β Uses Shopify's built-in gift card notification (default, no setup required)
* **App Email** β Sends a custom-designed email using your configured email template. Allows full control over branding and design.
* **Shopify Flow** β Triggers a Shopify Flow event with gift card data. Build your own delivery logic in Flow.
* **Klaviyo** β Triggers a Klaviyo event for use in Klaviyo flows
When using App Email, select an email template. Available template types:
* **Scheduled Gift Cards** β Pre-built template designed for scheduled gift card campaigns
* **Custom** β Any custom template you've created
**Template Variables**
The following variables are available in your email template:
* `gift_card.code` β Full gift card code
* `gift_card.initial_value.amount` β Gift card value
* `gift_card.balance.amount` β Current balance (same as initial value at creation)
* `gift_card.expires_on` β Expiry date (if set)
* `customer.first_name` β Customer's first name
* `customer.last_name` β Customer's last name
* `customer.email` β Customer's email
* `shop.name` β Your store name
* `shop.url` β Your store URL
### Campaign Dashboard
After creating a campaign, access its dashboard from the campaigns list. The dashboard shows:
#### Metrics
* **Gift cards sent** β Total gift cards delivered
* **Value issued** β Combined monetary value of all sent gift cards
* **Gift cards redeemed** β Number of gift cards that were subsequently used
* **Redeemed value** β Monetary value of redeemed gift cards
* **Order total** β Total order value from orders where these gift cards were used
Each metric includes a line chart showing trends over a selectable time range (7 days, 30 days, 90 days, 1 year, or year-to-date).
#### Campaign Runs
A table showing each time the campaign ran, including:
* Run number and date
* Status (In Progress, Finished, Error, Limits Error)
* Number of gift cards sent
* Number of skipped customers
#### Settings
The campaign configuration can be edited directly from the dashboard using the settings panel.
#### Activate / Deactivate
Toggle the campaign on or off. When deactivated, the campaign will not run on its next scheduled time. When reactivated, the next run is recalculated based on the schedule.
### Tips
* **Run daily** β For the best customer experience, run the campaign daily so every customer gets their gift card on their actual birthday
* **Test your query first** β Always use the "Test Query" button to verify your customer query returns the expected results before activating
* **Set a reasonable expiry** β A 30-90 day expiry creates urgency while giving customers enough time to shop
* **Personalize the message** β A warm message makes the gift card feel personal, not automated
* **Monitor your dashboard** β Track the redeemed rate to understand how effective your campaign is at driving repeat purchases
***
### Troubleshooting
#### "Found 0 customers matching the query"
**Possible causes:**
* Customers aren't tagged with birthdays
* Tag format doesn't match query format
* Liquid syntax error in query
* No customers have birthdays today (for daily campaigns)
**Solutions:**
* Verify customers have birthday tags: `tag:birthday-*`
* Check tag format matches: `birthday-MM-DD` with leading zeros (e.g., `birthday-03-05` for March 5th)
* Test query with a fixed date first: `tag:birthday-06-15`
* Check a few customer records manually in Shopify Admin
#### "Found more than 250 customers"
**Possible causes:**
* Query is too broad
* Using wildcard incorrectly
* Missing date filters
**Solutions:**
* Add more specific filters: `AND email_marketing_consent:subscribed`
* Check your Liquid syntax β make sure the date format is correct
* Verify the query when tested versus when running
* Segment customers across multiple campaigns
***
### Need More Help?
* [Customer Query Selector Guide](https://docs.giftcardfactory.app/misc/customers-query-selector) β Detailed query creation
* [Email Template Guide](https://docs.giftcardfactory.app) β Customize email design
* [Klaviyo Integration](https://docs.giftcardfactory.app) β Set up Klaviyo
* [Shopify Flow Integration](https://docs.giftcardfactory.app) β Set up Flow
* Contact support:
# Scheduled Store Credit
## Scheduled Store Credit
The **Scheduled Store Credit** campaign automatically adds store credit to your customers' accounts on a recurring schedule. Unlike gift cards that require a code, store credit is added directly to the customer's account β no redemption step needed.
This is perfect for:
* Birthday and anniversary rewards
* Loyalty programs and VIP perks
* Seasonal customer appreciation
* Win-back campaigns for inactive customers
* Subscription-style recurring credits
#### How it works:
1. You set up the campaign with your targeting criteria, store credit amount, and schedule
2. The campaign runs automatically at your scheduled time
3. It finds customers matching your query (e.g., customers with a birthday today)
4. It adds store credit directly to each customer's account
5. It sends a notification email with the store credit details
6. Customers see the credit in their account and can use it on their next purchase
### Common Use Cases
**Daily Birthday Store Credit** β Send $10 in store credit to every customer on their actual birthday, every day at 9:00 AM. Store credit is instantly available in their account with no code to remember.
**Monthly Loyalty Reward** β Add $5 store credit to all VIP customers on the 1st of each month. A simple way to reward your best customers and keep them coming back.
**Anniversary Appreciation** β Send store credit to customers on the anniversary of their first purchase. Celebrate milestones and encourage continued loyalty.
**Seasonal Customer Win-Back** β Target customers who haven't purchased in 90+ days with store credit to bring them back.
**Regional Rewards** β Send store credit to customers in specific locations with region-appropriate values and currencies.
### Step-by-Step Instructions
#### Step 1: Navigate to Campaign Creation
1. Open the Gift Card Factory app in your Shopify admin
2. Click **Campaigns** in the left sidebar
3. Click **New Campaign**
4. Select **Scheduled Store Credit** from the campaign type list
#### Step 2: Configure Basic Settings
**Campaign Title**
Give your campaign a descriptive name that helps you identify it later.
**Guidelines:**
* Use a clear, recognizable name
* Include the purpose or audience (e.g., "VIP Birthday Store Credit", "Monthly Loyalty Reward")
**Examples:**
* `Birthday Store Credit - Daily`
* `VIP Monthly Loyalty Credit`
* `Anniversary Appreciation - $15`
**Customer Query**
The customer query is the most important setting β it determines which customers receive store credit each time the campaign runs. Queries use Shopify's customer search syntax and support Liquid for dynamic dates. Read more about Customer Query Selector [here](/campaigns/scheduled-store-credit).
**Examples:**
* Birthday today: `tag:birthday-{{ "now" | date: "%m-%d" }} AND email_marketing_consent:subscribed`
* VIP monthly birthdays: `tag:birthday-{{ "now" | date: "%m" }}* AND tag:vip AND email_marketing_consent:subscribed`
* Regional targeting: `tag:birthday-{{ "now" | date: "%m-%d" }} AND country:Canada AND email_marketing_consent:subscribed`
**Tips:**
* Always include `AND email_marketing_consent:subscribed` to respect customer preferences
* Test your query with a single test customer first before activating the campaign
* Campaigns will pause if more than 250 customers match the query to prevent accidental mass sending
**B2B Company Recipients**
The **Add store credit to** toggle switches the campaign between **Customers** (default) and **B2B companies**. Company campaigns credit **company locations** β the level where Shopify B2B checkout looks for store credit β on every run. Requires B2B on Shopify (Shopify Plus); the app asks for permission to read your companies the first time you switch.
Choose companies via the tabs:
* **Select companies** β pick companies from a list; expand a company to check or uncheck individual locations. The same locations are credited on every run.
* **Companies query** β a Shopify company search query (e.g. `name:Acme*`) re-resolved at every run, so newly added companies are picked up automatically.
* **Manual list of companies** β company external IDs or exact names, one per line, re-resolved at every run.
> Company campaigns don't send notification emails β the Notification step is hidden. Buyers see the balance at B2B checkout. Campaigns pause if more than 250 company locations match, mirroring the customer limit.
#### Step 3: Configure Store Credit Settings
**Store Credit Amount**
The amount of store credit to add to each customer's account. The currency is automatically set to your shop's default currency.
**Guidelines:**
* Consider your average order value (10-20% typically works well)
* Balance generosity with profitability
**Common values:**
* Budget-friendly: $5 - $10
* Standard: $10 - $15
* Premium / VIP: $20 - $50
**Store Credit Expiry**
Choose when the store credit expires. Three options are available:
1. **Never expires** (recommended) β Store credit remains in the customer's account indefinitely
2. **Expires relative to creation date** β Set a number of days, weeks, months, or years after which the credit expires
3. **Expires on a specific date** β Choose a fixed expiration date
**Guidelines for relative expiry:**
* 30 days β Creates urgency, encourages quick purchases
* 90 days β Balanced approach (recommended if using expiry)
* 6 months β Generous, good for customer experience
* 1 year β Very generous, minimal pressure
**Tips:**
* Check your local laws regarding store credit expiration β some jurisdictions prohibit or restrict expiration
* Longer expiration improves customer experience but reduces urgency
* Communicate the expiration clearly in your email template
#### Step 4: Set Up Schedule
**Timezone**
Select the timezone for your campaign schedule. Defaults to your store's primary timezone.
**Start Date & Time**
When the campaign should first run.
**Guidelines:**
* Daily campaigns: Start tomorrow at 8-10 AM
* Monthly campaigns: Start the 1st of next month at 8-10 AM
**Tips:**
* 8-10 AM works well for most e-commerce stores
* Avoid sending in the middle of the night
* Consider when your customers typically check email
**Repeat Schedule**
How often the campaign should run.
**Common configurations:**
* **Daily birthday credits:** Repeat every 1 day
* **Weekly rewards:** Repeat every 1 week
* **Monthly loyalty credits:** Repeat every 1 month
* **One-time:** Don't set a repeat schedule
#### Step 5: Choose Email Delivery Method
Select how customers are notified about their store credit. Unlike gift card campaigns, the **Shopify Email** sender is not available for store credit campaigns.
**Available options:**
* **App Email** (recommended) β Uses the built-in Scheduled Store Credit email template. Fully customizable with the drag-and-drop email editor. Supports Liquid template variables.
* **Klaviyo** β Send notifications through Klaviyo. Requires a Klaviyo API key and an active flow triggered by the "Gift Card Factory - Scheduled Store Credit" metric.
* **Shopify Flow** β Trigger a Shopify Flow when store credit is added.
**Tips:**
* App Email is the easiest to set up and works out of the box
* Use Klaviyo if you want advanced email design and analytics
* You can customize the email template under **Emails > Templates > Campaigns > Scheduled Store Credit**
#### Step 6: Review and Create
Review all your settings and click **Create** to save the campaign. The campaign starts in an **Inactive** state β you need to activate it from the campaign details page.
**Before activating:**
* Test with a single test customer to verify everything works correctly
* Check the email template to make sure it looks right
* Confirm the schedule and timezone are correct
### Email Template Variables
The Scheduled Store Credit email template supports these Liquid variables:
| Variable | Description | Example |
| ----------------------------------------------------- | ----------------------------------------- | --------------------- |
| `{{ issued_store_credit.amount }}` | The store credit amount added | `10.00` |
| `{{ issued_store_credit.currency_code }}` | The currency code | `USD` |
| `{{ issued_store_credit.balance_after_transaction }}` | Customer's total balance after the credit | `25.00` |
| `{{ customer.first_name }}` | Customer's first name | `John` |
| `{{ customer.last_name }}` | Customer's last name | `Doe` |
| `{{ customer.email }}` | Customer's email | `john@example.com` |
| `{{ shop.name }}` | Your store name | `My Store` |
| `{{ shop.url }}` | Your store URL | `https://mystore.com` |
| `{{ shop.email }}` | Your store email | `support@mystore.com` |
Use the `format_money` filter to display amounts with your store's currency format:
```
{{ issued_store_credit.amount | format_money: shop.currency_formats.money_format }}
```
### Examples and Templates
#### Example 1: Simple Daily Birthday Store Credit
* **Title:** Birthday Store Credit - Daily
* **Customer Query:** `tag:birthday-{{ "now" | date: "%m-%d" }} AND email_marketing_consent:subscribed`
* **Amount:** $10.00
* **Expiry:** Never expires
* **Schedule:** Every day at 9:00 AM
* **Sender:** App Email
Every morning at 9 AM, any customer tagged with today's birthday date receives $10 store credit directly in their account.
#### Example 2: Monthly VIP Loyalty Credit
* **Title:** VIP Monthly Loyalty Credit
* **Customer Query:** `tag:vip AND email_marketing_consent:subscribed`
* **Amount:** $5.00
* **Expiry:** 90 days from creation
* **Schedule:** Every month on the 1st at 8:00 AM
* **Sender:** App Email
On the first of each month, all VIP customers receive $5 store credit as a loyalty reward.
#### Example 3: Anniversary Appreciation
* **Title:** First Purchase Anniversary Credit
* **Customer Query:** `tag:anniversary-{{ "now" | date: "%m-%d" }} AND email_marketing_consent:subscribed`
* **Amount:** $15.00
* **Expiry:** 6 months from creation
* **Schedule:** Every day at 10:00 AM
* **Sender:** Klaviyo
Customers receive $15 store credit on the anniversary of their first purchase.
#### Example 4: Regional Birthday Campaign
* **Title:** Canada Birthday Store Credit
* **Customer Query:** `tag:birthday-{{ "now" | date: "%m-%d" }} AND country:Canada AND email_marketing_consent:subscribed`
* **Amount:** $10.00
* **Expiry:** Never expires
* **Schedule:** Every day at 9:00 AM (EST)
* **Sender:** App Email
Canadian customers receive $10 CAD store credit on their birthday.
### Setting Up Customer Tags
For birthday and anniversary campaigns, customers need to be tagged with the appropriate date format.
#### Recommended Tag Format
**Birthday tags:** `birthday-MM-DD` (e.g., `birthday-06-20` for June 20th)
**Anniversary tags:** `anniversary-MM-DD` (e.g., `anniversary-03-15` for March 15th)
**Guidelines:**
* Always use two-digit months and days (e.g., `birthday-01-05`, not `birthday-1-5`)
* Tags can be added manually, via Shopify Flow, through a customer form, or via API
* Make sure the date format in the tag matches the Liquid date format in your query
### Store Credit vs Gift Cards
| Feature | Store Credit | Gift Cards |
| ------------ | ---------------------------------- | ------------------------------- |
| Redemption | Automatic β applied at checkout | Customer enters a code |
| Transferable | No β tied to customer account | Yes β code can be shared |
| Visibility | Shows in customer account page | Customer needs the code |
| Partial use | Remaining balance stays in account | Remaining balance stays on card |
| Expiration | Optional | Optional |
| Best for | Loyalty rewards, account credits | Gifting, promotions with codes |
### Best Practices
1. **Start with a test customer.** Create a test customer with a birthday tag for today, run the campaign manually, and verify the store credit appears in their account and the email is received.
2. **Respect email preferences.** Always include `AND email_marketing_consent:subscribed` in your customer query.
3. **Set appropriate amounts.** Consider your margins and average order value. A credit that's 10-20% of AOV encourages a purchase without eroding profitability.
4. **Monitor campaign runs.** Check the campaign runs page regularly to ensure credits are being sent successfully. Look for skipped customers or errors.
5. **Choose expiry carefully.** If your local laws allow it, a 90-day expiry creates a good balance between urgency and customer experience.
6. **Customize your email template.** Edit the default Scheduled Store Credit email template to match your brand. Mention the store credit amount and how to use it.
7. **Use descriptive campaign titles.** When you have multiple scheduled store credit campaigns, clear titles help you manage them.
8. **Combine with other campaigns.** Scheduled Store Credit works well alongside Scheduled Gift Cards β use gift cards for gift-giving occasions and store credit for loyalty programs.
9. **Check your customer tags.** The most common issue is missing or incorrectly formatted tags. Verify tags use the `birthday-MM-DD` format with zero-padded months and days.
10. **Keep queries under 250 matches.** Campaigns will automatically pause if more than 250 customers match the query. If you have a large customer base, consider segmenting by region or customer group.
### Troubleshooting
#### Store credit not being added
**Possible causes:**
1. Campaign is still in **Inactive** state
2. Customer query returns no matching customers
3. Customer tags are missing or incorrectly formatted
4. Campaign has hit the subscription limit
**Solutions:**
1. Go to the campaign details page and activate the campaign
2. Test your customer query in Shopify's customer search to verify it returns results
3. Check that customer tags use the correct format (e.g., `birthday-06-20`)
4. Check your subscription limits under Settings
#### Customer not receiving email notification
**Possible causes:**
1. Customer has no email address
2. Email template is not configured
3. Sender settings are incorrect
4. Email was caught by spam filters
**Solutions:**
1. Verify the customer has a valid email address in Shopify
2. Check that the Scheduled Store Credit email template exists under Emails > Templates
3. Verify your sender settings (App Email, Klaviyo, or Shopify Flow)
4. Check the email deliveries page for bounce or spam reports
#### Campaign showing errors in runs
**Possible causes:**
1. Store credit API error from Shopify
2. Customer query syntax error
3. Network timeout during execution
**Solutions:**
1. Check the campaign run logs for specific error messages
2. Verify your customer query syntax β test it in Shopify admin first
3. If errors persist, try running the campaign again; transient issues usually resolve
### Frequently Asked Questions
**Can I send different store credit amounts to different customer groups?** Yes β create separate campaigns with different customer queries and amounts. For example, one campaign for VIP customers at $25 and another for regular customers at $10.
**Will the same customer receive store credit every time the campaign runs?** Yes, if they match the query each time. For birthday campaigns this is typically once per year. For loyalty campaigns running monthly, the customer will receive credit each month.
**Can I use store credit with Klaviyo?** Yes. Select Klaviyo as the sender and configure a flow triggered by the "Gift Card Factory - Scheduled Store Credit" metric. The event properties include store credit amount, currency, and balance.
**What happens if the campaign finds more than 250 customers?** The campaign will pause and show an error. This safety limit prevents accidental mass sending. Refine your customer query to target a smaller group, or split into multiple campaigns.
**Can I schedule a one-time store credit campaign?** Yes β set up the schedule without a repeat interval. The campaign will run once at the scheduled time and then remain inactive.
**Does store credit work with all Shopify plans?** Store credit requires Shopify to have the store credit feature enabled. This is available on most Shopify plans. Check your Shopify admin under Settings > Payments for store credit options.
### Need More Help?
If you have questions or run into issues:
* Email us at ****
# Introduction
πΈ Refund any Shopify order to a gift card instead of the original payment method.
Gift card refunds let you refund a Shopify order **as a gift card** instead of returning money to the original payment method. The customer gets immediate redeemable balance, and you keep the value inside your store. The feature appears as a **"Refund on gift card"** action on every order's detail page.
> **Prefer keeping value inside the store?** Compare [gift cards, discount codes, and store credit](/comparison) to decide which value type fits your refund flow best. Gift cards are transferable; [store credit](/bulk-operations/store-credit-bulk-add) is account-bound.
### **β Benefits**
* **Encourages repeat purchases** β refund value stays in your store.
* **Faster than processing a card refund** β no payment gateway round-trip.
* **Transferable for the customer** β they can give the gift card to someone else.
* **Trackable** β every refunded order is tagged and tagged with the gift card ID, making it easy to audit.
### **βοΈ Prerequisites**
Before you can issue a gift card refund:
1. **App Email sending must be enabled** for your shop. The refund email is sent via App Email and uses one of your **Refund** (or **Custom**) email templates. See [App Emails](/misc/app-emails) for setup.
2. **Your subscription plan must allow refunds.** Refunds count against the plan's refund limit. The form shows how many refunds you have remaining.
3. **Your trial must not be expired** (if you're on a trial).
4. **The order must have at least one returnable / refundable line item.** Fully-refunded orders show "No line items to refund".
If any of these fail, the refund button is disabled and a banner explains why.
### **πͺ How to Issue a Gift Card Refund**
1. **Open the order** in Shopify Admin β Orders β click the order you want to refund.
2. **Click the "Refund on gift card" admin action.** (This is added by the app's admin link extension.)
3. **Configure the refund** in the form that opens:
* **Line items**: For each fulfillment, set the quantity to refund per line item. Items are grouped by fulfillment status (Fulfilled / Unfulfilled) and assigned location.
* **Restock items**: When checked, returned items go back into inventory (RETURN for fulfilled items, CANCEL for unfulfilled items). When unchecked, no restock happens.
* **Refund shipping**: Tick a shipping line to include its full original price in the refund.
* **Reason for refund**: Internal-only note β visible to staff (and stored on the order), not to the customer.
* **Refund amount** (right sidebar): Auto-calculated from your selections, but editable. Capped at the maximum refundable amount.
* **Auto-expiration**: Choose when the issued gift card expires β never, relative to creation date (days/weeks/months/years), or a specific date.
* **Email template**: Choose which **Refund** or **Custom** template to send. The app remembers your last choice as the default for next time.
4. **Click "Refund {amount}"**. The app:
* Issues the refund in Shopify (calling Shopify's `refundCreate` mutation).
* Creates a new gift card for the refund amount.
* Sends the customer an email with the gift card code via App Email using your selected template.
* Tags and annotates the order (see [What gets recorded on the order](#what-gets-recorded-on-the-order)).
5. The page redirects you back to the order in Shopify Admin once the refund completes.
### **π§ The Refund Email**
The customer receives a single email containing the gift card code, sent through **App Email** with the template you selected. The template has access to these variables:
* `customer` β the customer's name, email, etc.
* `gift_card` β the new gift card's code, balance, expiry, etc.
* `refund.line_items`, `refund.reason`, `refund.shipping_refund`, `refund.total_refunded`
* `order.number`, `order.id`
* `shop` β your shop's name, URL, currency formats, etc.
> The sender is hardcoded to **App Email** for refunds β Shopify Email, Shopify Flow, and Klaviyo are not available for this flow. Make sure App Email sending is enabled and a sending domain is configured (see [App Emails β Sending Domain](/misc/app-emails/sending-domain)).
### **π₯ Email Without an Address on the Order**
If the order doesn't have an email associated (e.g. POS orders, abandoned-and-recovered orders), a banner appears at the top of the form with an **Email** input. Provide an address there before clicking refund β the gift card email will go to that address.
### **π·οΈ What Gets Recorded on the Order**
When a refund succeeds, the app updates the order with:
* **Tag**: `gift-card-factory-refund`.
* **Tag**: `Refund ID: {refund-run-id}` β uniquely identifies this refund operation.
* **Custom attribute**: `GC Refund: {timestamp}` with a value containing the reason, the new gift card's ID, and the refunded line items.
* **Metafield**: `gcf.gcf_shipping_refunded` β tracks the cumulative shipping amount refunded across all gift card refunds for this order.
If the refund fails, the app instead applies the tag `gift-card-factory-refund-error`.
### **π Reviewing Past Refunds**
There are several ways to find and audit gift card refunds:
* **Per-order**: open the order in Shopify Admin and check:
* The **Timeline** for the refund event.
* The **Tags** section for `gift-card-factory-refund` and the `Refund ID` tag.
* The **Additional details** (custom attributes) section for the `GC Refund: {timestamp}` entry containing the gift card ID and refund details.
* **Across all orders**: filter the Orders list by the tag `gift-card-factory-refund` to see every order refunded via gift card.
* **Find the gift card itself**: open Shopify Admin β Products β Gift Cards. The gift card created for the refund is listed there with its balance, code, and customer assignment.
### **β When a Refund Fails**
The refund button is disabled and a banner explains the cause if any of the following apply:
* **No line items selected** β set at least one line item quantity above 0.
* **Refund amount is 0** β set a positive amount.
* **Subscription refunds limit reached** β upgrade your plan or wait for the limit to reset.
* **Trial expired** β upgrade to a paid plan.
* **App Email sending disabled for the shop** β contact support to enable it.
If a refund fails *during* execution (e.g. Shopify rejects the underlying refund), the order is tagged `gift-card-factory-refund-error` and a toast shows the error message.
### **β FAQ**
**Can I refund only the shipping?**\
Yes β leave all line item quantities at 0, tick the shipping line you want to refund, and the refund amount in the sidebar will reflect just shipping. Then click **Refund**.
**Can I refund more than the maximum refundable amount?**\
No. The form caps the refund amount at the order's remaining refundable balance (Shopify's `maximumRefundableSet`). The "available for refund" hint under the amount field shows the cap.
**Does the gift card require a customer record?**\
No β the gift card is created and emailed to the address on the order (or the address you supplied in the email field). The gift card is also assigned to the order's customer if one exists, so it appears in their account.
**Can the customer use the gift card immediately?**\
Yes. The gift card is enabled and available at checkout as soon as the refund completes.
**Can I refund an order that has already been partially refunded by other means?**\
Yes. The form respects what's already been refunded β only the remaining refundable line items and shipping are shown.
**Why is the sender locked to App Email? Can I use Klaviyo instead?**\
For refunds, App Email is required because the refund flow handles the email synchronously and needs delivery confirmation in the same request. If your store relies on Klaviyo, you can still set up a webhook listener on the order tag (`gift-card-factory-refund`) and trigger your own flow from there.
**Can I undo a gift card refund?**\
No. The refund and the new gift card are real Shopify operations. To reverse, you would need to manually re-charge the customer (e.g. via a draft order) and deactivate the gift card from Shopify Admin β Products β Gift Cards. Note that **disabled gift cards cannot be re-enabled** ([Shopify docs](https://shopify.dev/docs/api/admin-graphql/latest/objects/GiftCard)).
### **π Related Reading**
* [App Emails](/misc/app-emails) β how the refund email is sent and how to customize the template.
* [Email Template Editor](/misc/app-emails/template-editor) β building a Refund template.
* [Sending Domain setup](/misc/app-emails/sending-domain) β configure your domain for App Email.
* [Gift Cards vs Discount Codes vs Store Credit](/comparison) β picking the right value type.
* [Subscription Plans](/misc/subscription-plans) β refund limits per plan.
# Unused Gift Card Balance Report
## Unused Gift Card Balance Report
The Unused Gift Card Balance Report helps you identify all gift cards in your store that still have remaining balance. This is useful for financial reconciliation, liability tracking, and understanding your outstanding gift card obligations.
### Overview
This report scans all gift cards created within your selected date range and finds those with a balance greater than zero. It compiles detailed information about each gift card, including customer and recipient data, into a downloadable CSV file.
### When to Use This Report
* **Financial reporting**: Track outstanding gift card liabilities for accounting purposes
* **Year-end reconciliation**: Identify unredeemed gift card balances
* **Customer outreach**: Find customers with unused gift cards to send reminder campaigns
* **Expiration management**: Review gift cards approaching expiration with remaining balances
### Creating a Report
1. Navigate to **Reports** in the Gift Card Factory app
2. Click the **New Report** button
3. Select **Unused Gift Card Balance** from the report options
4. Configure your report settings:
* **Date Range**: Select the start and end dates. The report will include gift cards created within this period
* **Filters** (optional): Narrow down which gift cards are included β see [Filters](#filters) below
* **Email Notification** (optional): Check this option to receive the report results via email when complete
5. Click **Create** to generate the report
### Filters
| Filter | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Gift card status | **With remaining balance** (default) includes every card that still has balance. **Unused (full balance)** β cards not spent at all. **Partially used** β cards with some balance spent. **Fully used** β cards with zero balance. **Disabled** β deactivated cards. **All** β no status filter. |
| Initial value | Only include gift cards created with this exact value (e.g. `25` for all $25 cards). Leave empty for all values. |
| Minimum balance | Only include gift cards with at least this remaining balance. |
With the status filter you can also use this report as a general gift card list β for example, select **All** with an initial value of `25` to export every $25 gift card created in a period, used or not.
### Report Contents
The generated CSV file includes the following columns:
| Column | Description |
| -------------------- | --------------------------------------------------------- |
| Gift Card ID | The unique identifier for the gift card |
| Enabled | Whether the gift card is currently active (Yes/No) |
| Last 4 Characters | The last 4 characters of the gift card code |
| Initial Value | The original value when the gift card was created |
| Current Balance | The remaining balance on the gift card |
| Expires On | The expiration date, if set |
| Note | Any notes attached to the gift card |
| Created At | When the gift card was created |
| Customer Email | Email address of the customer who purchased the gift card |
| Customer First Name | First name of the purchasing customer |
| Customer Last Name | Last name of the purchasing customer |
| Recipient Email | Email address of the gift card recipient |
| Recipient First Name | First name of the recipient |
| Recipient Last Name | Last name of the recipient |
### Viewing Report Progress
Once created, your report appears in the Reports list. You can monitor its status:
* **Queued**: The report is waiting to be processed
* **In Progress**: The report is actively scanning gift cards
* **Finished**: The report is complete and ready for download
A progress bar shows how much of the report has been completed.
### Downloading Results
After the report finishes:
1. Find your report in the Reports list
2. Click the **Result** link in the Download Links column
3. The CSV file will download to your computer
If the report encountered errors while running, an additional **Errors** link is shown next to **Result** with a CSV listing the failed rows.
**Note**: Download links expire after 72 hours. Make sure to download your report within this timeframe.
### Stopping a Report
If you need to stop a report that's in progress:
1. Select the report by clicking on its row
2. Click the **Stop** button in the bulk actions bar
3. The report will be marked as "Stopping" and then "Aborted"
Even if stopped, you can still download partial results that were collected before stopping.
### Viewing Logs
To see detailed processing information:
1. Select the report by clicking on its row
2. Click the **Show Logs** button in the bulk actions bar
3. A modal will display the processing logs, including any errors encountered
### Tips
* Start with a smaller date range to estimate processing time before running larger reports
* Use the email notification option for large reports so you don't have to monitor the progress
* Schedule reports during off-peak hours for faster processing
* Download reports promptly as links expire after 72 hours
### Related Features
* Gift Card Usage Report - Track how gift cards are being used in orders
* Bulk Operation Gift Card Usage Report - Analyze gift card usage from specific bulk operations
* [Gift Card Summary Report](/reports/gift-card-summary-report) - Aggregate totals instead of a card-by-card list
* [Expiring Gift Cards Report](/reports/expiring-gift-cards-report) - Cards with remaining balance that expire soon
# Bulk Operation Gift Card Usage
## Bulk Operation Gift Card Usage Report
Track how gift cards from your bulk operations are being used by customers. This report shows detailed redemption data for gift cards created through Import from File, Autogenerate, or Bulk Send operations.
### Overview
The Bulk Operation Gift Card Usage Report helps you understand the ROI of your gift card campaigns by showing:
* Which gift cards have been redeemed
* Order details where gift cards were used
* Current balances of distributed gift cards
* Transaction amounts and dates
This is particularly useful for measuring the success of promotional campaigns, loyalty programs, or bulk gift card distributions.
### Requirements
To generate this report, you need:
* At least one completed bulk operation (Import from File, Autogenerate, or Bulk Send)
* The bulk operation must have been created **after October 25, 2025** (when usage tracking was enabled)
* Gift cards from the operation must have been redeemed in orders
### Creating a Report
#### Step 1: Navigate to Reports
From your Gift Card Factory dashboard, click on **Reports** in the navigation menu.
#### Step 2: Create New Report
Click the **New Report** button and select **Bulk Operation Gift Card Usage** from the available report types.
#### Step 3: Select Bulk Operation
Choose the bulk operation you want to analyze from the dropdown. The selector shows:
* **Operation number** (e.g., #1042)
* **Operation type** (Import from file, Autogenerate, or Bulk send)
After selecting an operation, you'll see the number of gift cards that were successfully created in that operation.
#### Step 4: Configure Email Delivery (Optional)
Enable **Send report via email** if you want to receive the CSV file directly in your inbox. Enter one or more email addresses separated by commas.
#### Step 5: Generate Report
Click **Create** to start generating your report. The report will be queued and processed in the background.
### Report Contents
The generated CSV file includes the following columns:
| Column | Description |
| -------------------------- | --------------------------------------------- |
| Gift card last 4 digits | Last 4 characters of the gift card code |
| Gift card initial value | Original value when the gift card was created |
| Gift card current balance | Remaining balance on the gift card |
| Gift card ID | Shopify gift card ID |
| Gift card note | Any notes attached to the gift card |
| Transaction date | When the gift card was used |
| Transaction amount | Amount deducted in the transaction |
| Order ID | Shopify order ID |
| Order name | Order reference number (e.g., #1001) |
| Customer email address | Email of the customer who placed the order |
| Order created at | When the order was placed |
| Order total price | Total order value |
| Order subtotal price | Order subtotal before taxes and shipping |
| Order total refunded | Total refunded amount (if any) |
| Order total tax | Tax amount on the order |
| Order total shipping price | Shipping cost |
| Order total discount | Discounts applied to the order |
### Downloading Your Report
Once the report is complete:
1. Go to the **Reports** page
2. Find your report in the list
3. Click the **Result** link in the **Download Links** column to get the CSV file
If the report encountered errors while running, an additional **Errors** link is shown next to **Result** with a CSV listing the failed rows.
**Note**: Download links expire after 72 hours. After that the row shows **Expired** β re-run the report if you still need the data.
### Use Cases
#### Measuring Campaign ROI
After running a promotional gift card campaign, use this report to:
* See how many gift cards were actually used
* Calculate total revenue generated from gift card orders
* Identify which customers engaged with your promotion
#### Tracking Loyalty Program Performance
For gift cards distributed as loyalty rewards:
* Monitor redemption rates over time
* Identify your most engaged customers
* Understand average order values when gift cards are used
#### Financial Reconciliation
Use the report for accounting purposes:
* Track gift card liability (unredeemed balances)
* Reconcile gift card transactions with orders
* Export data for financial reporting
### Frequently Asked Questions
#### Why don't I see my bulk operation in the dropdown?
Your bulk operation may not appear if:
* It was created before October 25, 2025
* It hasn't finished processing yet
* It was a different operation type (e.g., Bulk Update)
#### Why is my report empty?
An empty report means no gift cards from that bulk operation have been redeemed yet. Customers haven't used any of the distributed gift cards in orders.
#### How often can I generate reports?
You can generate reports as often as needed. Each report captures usage data up to the moment it's created.
#### Can I automate this report?
Currently, reports are generated on-demand. For recurring reports, you'll need to manually create a new report each time.
#### What subscription plan do I need to generate the report
All reports can be generated without a paid subscription
### Need Help?
If you have questions about the Bulk Operation Gift Card Usage Report or need assistance, contact our support team at .
# Gift Cards Usage
Detailed Order Report Guide
The Gift Cards Usage report exports every order transaction in your store that was paid (in part or in full) with a gift card. It covers gift cards issued through Gift Card Factory **and** any external/native Shopify gift cards used in transactions, so you have one place to reconcile gift card revenue.
### When to Use This Report
* **Financial reconciliation**: tie gift card transactions back to the orders they paid for
* **Revenue analysis**: see how much of your sales were paid with gift cards over a period
* **Audit trail**: keep a record of which gift cards were used, on which orders, and for how much
### Creating a Report
1. Navigate to **Reports** in the Gift Card Factory app.
2. Click the **New Report** button.
3. Select **Gift Card Usage** from the report options.
4. Configure your report settings:
* **Date Range**: select the start and end dates. Orders whose gift card transactions occurred in this range will be included.
* **Email Notification** (optional): check **Send an email with report results** to receive the CSV in your inbox when the report is finished.
5. Click **Create** to queue the report.
### Report Contents
The generated CSV file includes the following columns:
| Column | Description |
| -------------------------- | ---------------------------------------------- |
| Gift card last 4 digits | Last 4 characters of the gift card code |
| Gift card initial value | Original value when the gift card was created |
| Gift card current balance | Remaining balance on the gift card |
| Gift card ID | Shopify gift card ID |
| Gift card note | Any notes attached to the gift card |
| Transaction date | When the gift card was used in the transaction |
| Transaction amount | Amount deducted from the gift card |
| Order ID | Shopify order ID |
| Order name | Order reference (e.g., #1001) |
| Customer email address | Email of the customer who placed the order |
| Order created at | When the order was placed |
| Order total price | Total order value |
| Order subtotal price | Subtotal before taxes and shipping |
| Order total refunded | Total refunded amount, if any |
| Order total tax | Tax amount on the order |
| Order total shipping price | Shipping cost |
| Order total discount | Discounts applied to the order |
One row is written per gift card transaction, so an order paid with two gift cards produces two rows.
### Viewing Report Progress
Once created, your report appears in the Reports list. You can monitor its status:
* **Queued**: the report is waiting to be processed
* **In Progress**: the report is actively scanning orders
* **Finished**: the report is complete and ready for download
* **Stopping** / **Aborted**: shown when you stop a report (see below)
A progress bar in the row shows how much of the report has been completed. The list updates in real time, so you don't need to refresh.
### Downloading Results
After the report finishes:
1. Find your report in the Reports list.
2. Click the **Result** link in the **Download Links** column.
3. The CSV file will download to your computer.
If the report encountered errors while running, an additional **Errors** link is shown next to **Result** so you can download a CSV listing the failed rows.
**Note**: download links expire after 72 hours. After that the row shows **Expired** and the file is no longer available β re-run the report if you still need the data.
### Stopping a Report
If you need to stop a report that's in progress:
1. Select the report by clicking on its row.
2. Click the **Stop** button in the bulk actions bar.
3. The report will be marked as **Stopping** and then **Aborted**.
Even if stopped, you can still download the partial CSV that was collected before stopping.
### Viewing Logs
To see detailed processing information:
1. Select the report by clicking on its row.
2. Click the **Show Logs** button in the bulk actions bar.
3. A modal will display the processing logs, including any errors encountered.
### Tips
* Start with a smaller date range if you have a high order volume β it lets you estimate processing time before running larger reports.
* Use the email notification option for long-running reports so you don't have to keep the page open.
* Download reports promptly β links expire after 72 hours.
### Related Reports
* [Unused Gift Card Balance Report](/reports/unused-gift-card-balance-report) β list gift cards that still have remaining balance
* [Bulk Operation Gift Card Usage](/reports/bulk-operation-gift-card-usage) β limit usage tracking to a single bulk operation
# Store Credit Balance Report
## Store Credit Balance Report
The Store Credit Balance Report exports every customer in your store who currently holds store credit. Use it for financial reconciliation, liability tracking, or as a source list for store credit campaigns.
### Overview
The report scans all customers in your store and lists every store credit account with a positive balance. Customers holding credit in more than one currency get one row per currency. Balances reflect the moment the report runs, so there is no date range to configure.
### When to Use This Report
* **Financial reporting**: Track outstanding store credit liabilities for accounting purposes
* **Reconciliation**: Verify store credit balances after bulk operations or migrations
* **Customer outreach**: Find customers with unspent credit to re-engage them
* **Audits**: Get a complete snapshot of who holds credit and how much
### Creating a Report
1. Navigate to **Reports** in the Gift Card Factory app
2. Click the **New Report** button
3. Select **Store Credit Balance** from the report options
4. Optionally check **Send an email with report results** and enter the destination address
5. Click **Create** to generate the report
### Report Contents
The generated CSV file includes the following columns:
| Column | Description |
| -------------------- | ----------------------------------------------- |
| Customer ID | The unique Shopify identifier for the customer |
| Customer Email | Email address of the customer |
| Customer First Name | First name of the customer |
| Customer Last Name | Last name of the customer |
| Currency | Currency of the store credit account |
| Store Credit Balance | Current balance of the account in that currency |
### Processing Time
Because Shopify does not allow searching customers by store credit, the report scans your entire customer base. For stores with many customers this can take a while β the progress bar tracks customers scanned, and the email notification option lets you close the app while it runs.
### Downloading Results
After the report finishes, click the **Result** link in the Download Links column. Download links expire after 72 hours.
### Related Features
* [Store Credit Bulk Add](/bulk-operations/store-credit-bulk-add) β add store credit to many customers at once
* [Scheduled Store Credit](/campaigns/scheduled-store-credit) β add store credit on a recurring schedule
# Gift Card Summary Report
## Gift Card Summary Report
The Gift Card Summary Report answers "how many?" questions in a single small CSV: how many gift cards were created in a period, what they were worth, how much has been redeemed, and how much liability is outstanding. Unlike the other reports, it produces aggregate totals instead of one row per gift card.
### Overview
The report aggregates all gift cards created within your selected date range into per-currency totals, and adds a count of orders paid with gift cards in the same period.
### When to Use This Report
* **Quick health check**: "How many gift cards were used last month?"
* **Financial reporting**: Outstanding balance (liability) and redeemed value per period
* **Campaign evaluation**: Compare created vs. redeemed value after a promotion
### Creating a Report
1. Navigate to **Reports** in the Gift Card Factory app
2. Click the **New Report** button
3. Select **Gift Card Summary** from the report options
4. Configure your report settings:
* **Date Range**: Select the start and end dates. The report aggregates gift cards created within this period
* **Email Notification** (optional): Check this option to receive the report results via email when complete
5. Click **Create** to generate the report
### Report Contents
The generated CSV contains one row per metric, per currency:
| Metric | Description |
| --------------------------- | ---------------------------------------------------------- |
| Gift cards created | Number of gift cards created in the period |
| Total initial value | Sum of the original values of those cards |
| Total remaining balance | Sum of their current balances (your outstanding liability) |
| Total redeemed value | Initial value minus remaining balance, summed |
| Unused cards (full balance) | Cards that have not been spent at all |
| Partially used cards | Cards with some balance spent |
| Fully used cards | Cards with zero balance |
| Disabled cards | Cards that have been deactivated |
| Expired cards | Cards whose expiry date has passed |
| Cards without expiry date | Cards that never expire |
The final row, **orders paid with gift cards in period**, counts orders in the date range that were paid (fully or partially) with *any* gift card β including cards created outside the selected period.
### Downloading Results
After the report finishes, click the **Result** link in the Download Links column. Download links expire after 72 hours.
### Related Features
* [Unused Gift Card Balance Report](/reports/unused-gift-card-balance-report) β the card-by-card list behind these totals
* [Gift Cards Usage](/reports/gift-cards-usage) β order-level detail of gift card redemptions
# Expiring Gift Cards Report
## Expiring Gift Cards Report
The Expiring Gift Cards Report finds gift cards that still have remaining balance but are about to expire. Use it to warn customers before their balance is lost β or to measure how much value is about to expire.
### Overview
The report lists enabled gift cards with a remaining balance whose expiry date falls between today and a number of days you choose (30 by default).
### When to Use This Report
* **Customer outreach**: Contact holders of soon-to-expire balances
* **Reminder campaigns**: Build a target list before setting up [Gift Card Reminders](/campaigns/gift-card-reminders)
* **Liability forecasting**: See how much outstanding balance will expire soon
### Creating a Report
1. Navigate to **Reports** in the Gift Card Factory app
2. Click the **New Report** button
3. Select **Expiring Gift Cards** from the report options
4. Configure your report settings:
* **Expiring within (days)**: How far ahead to look, counted from today (default 30)
* **Email Notification** (optional): Check this option to receive the report results via email when complete
5. Click **Create** to generate the report
### Report Contents
The generated CSV uses the same columns as the Unused Gift Card Balance Report:
| Column | Description |
| -------------------- | --------------------------------------------------------- |
| Gift Card ID | The unique identifier for the gift card |
| Enabled | Whether the gift card is currently active (Yes/No) |
| Last 4 Characters | The last 4 characters of the gift card code |
| Initial Value | The original value when the gift card was created |
| Current Balance | The remaining balance on the gift card |
| Expires On | The expiration date |
| Note | Any notes attached to the gift card |
| Created At | When the gift card was created |
| Customer Email | Email address of the customer who purchased the gift card |
| Customer First Name | First name of the purchasing customer |
| Customer Last Name | Last name of the purchasing customer |
| Recipient Email | Email address of the gift card recipient |
| Recipient First Name | First name of the recipient |
| Recipient Last Name | Last name of the recipient |
### Downloading Results
After the report finishes, click the **Result** link in the Download Links column. Download links expire after 72 hours.
### Related Features
* [Gift Card Reminders](/campaigns/gift-card-reminders) β automatically email customers before their gift cards expire
* [Unused Gift Card Balance Report](/reports/unused-gift-card-balance-report) β all cards with remaining balance, regardless of expiry
# Gift Card API
REST API for Custom Integrations
Our REST API allows you to easily develop any custom integration you need. It is specifically designed to update native Shopify gift cards efficiently and effortlessly. By utilizing our comprehensive API, you can connect various applications and services, enhancing your e-commerce capabilities. Whether integrating third-party services, creating automated workflows, or building new applications, our API provides the flexibility and functionality required.
#### Key Features
* **Seamless Integration:** Quickly connect your platform with Shopify to sync gift card details.
* **Automated Processes:** Utilize our API to automate updates, ensuring your data is always current.
* **Scalability:** Easily scalable to meet the growing needs of your business.
* **Reliable Performance:** Built for reliability to ensure consistent connectivity and data integrity.
* **Comprehensive Documentation:** Includes step-by-step guides and examples to facilitate easy implementation.
#### Getting Started
1. **Obtain Your API Key:** Go to app settings and create your unique API key.
2. **Review Documentation:** Visit our comprehensive documentation to understand endpoints and usage.
3. **Develop Your Integration:** Use the API to develop and test your custom integration.
{% hint style="info" %}
Gift Card API is available during the Trial and on Silver and higher plans. It is not available on the Bronze plan.
{% endhint %}
# Authentication
To make REST API requests, you need a valid API token. To generate a token, open the app, go to Settings, and find **API Access**. Here, you can create a new token. Remember, the token is shown only once when it's created.
Include your token as a `x-gcf-access-token` header on all API queries.
# Endpoints and requests
Direct all requests to the app proxy on your myshopify.com domain.
```
https://{store_name}.myshopify.com/apps/gcf/api/{resource}
```
There are 4 different endpoints for creating and updating gift cards
* POST https\://{store\_name}.myshopify.com/apps/gcf/api/gift\_card
* PUT https\://{store\_name}.myshopify.com/apps/gcf/api/gift\_card/{gift\_card\_id}
* GET https\://{store\_name}.myshopify.com/apps/gcf/api/gift\_card/{gift\_card\_id}
* GET https\://{store\_name}.myshopify.com/apps/gcf/api/gift\_card?last\_characters={last-characters}\&email={email}
# Creates a gift card
```
POST https://{store_name}.myshopify.com/apps/gcf/api/gift_card
```
There are additional optional parameters that can be specified in the body of the request when creating a gift card:
* `initial_value` - value of the gift card
* `expires_on` - gift card expiry date
* `email` - email of the customer. This customer will be assigned to gift card customer field. If email does not exist in Shopify backend - app will create one
* `recipient_email` - email of the recipient. This recipient will be assigned to gift card recipitn field. If email does not exist in Shopify backend - app will create one
* `note` - internal note, not visible to customers
* `message` - message sent in gift card email
{% hint style="info" %}
Only initial\_value parameter is required.
{% endhint %}
Response:
```json
HTTP/1.1 201 Created
{
"gift_card": {
"id": 634370326821,
"balance": "4.0",
"created_at": "2025-08-15T12:37:38Z",
"currency": "AUD",
"initial_value": "15.00",
"disabled_at": null,
"line_item_id": null,
"api_client_id": null,
"user_id": null,
"customer_id": 9042221203749,
"customer_email": "customer@test.com",
"recipient_id": null,
"recipient_email": null,
"note": null,
"expires_on": "2025-10-10",
"message": null,
"last_characters": "262f",
"order_id": null,
"code": "awap262f"
}
}
```
# Updates a gift card
```
PUT https://{store_name}.myshopify.com/apps/gcf/api/gift_card/{gift_card_id}
```
Following paramters might be included in body of your request to update existing gift card
* `disable` - set to true if you want to disable gift card
* `balance` - new gift card balance
* `expires_on` - new expiry date of a gift card
* `note` - new internal note, not visible to customers
Response:
```json
HTTP/1.1 200 OK
{
"gift_card": {
"id": 634370326821,
"balance": "4.0",
"created_at": "2025-08-15T12:37:38Z",
"currency": "AUD",
"initial_value": "15.00",
"disabled_at": null,
"line_item_id": null,
"api_client_id": null,
"user_id": null,
"customer_id": 9042221203749,
"customer_email": "customer@test.com",
"recipient_id": null,
"recipient_email": null,
"note": null,
"expires_on": "2025-10-10",
"message": null,
"last_characters": "262f",
"order_id": null
}
}
```
# Retrieves a single gift card
```
GET https://{store_name}.myshopify.com/apps/gcf/api/gift_card/{gift_card_id}
```
Response:
```json
HTTP/1.1 200 OK
{
"gift_card": {
"id": 634370326821,
"balance": "4.0",
"created_at": "2025-08-15T12:37:38Z",
"currency": "AUD",
"initial_value": "15.00",
"disabled_at": null,
"line_item_id": null,
"api_client_id": null,
"user_id": null,
"customer_id": 9042221203749,
"customer_email": "customer@test.com",
"recipient_id": null,
"recipient_email": null,
"note": null,
"expires_on": "2025-10-10",
"message": null,
"last_characters": "262f",
"order_id": null
}
}
```
# Searches for gift card
```
GET https://{store_name}.myshopify.com/apps/gcf/api/gift_card?last_characters={last-characters}&email={email}
```
Response:
```json
HTTP/1.1 200 OK
{
"gift_card": {
"id": 634370326821,
"balance": "4.0",
"created_at": "2025-08-15T12:37:38Z",
"currency": "AUD",
"initial_value": "15.00",
"disabled_at": null,
"line_item_id": null,
"api_client_id": null,
"user_id": null,
"customer_id": 9042221203749,
"customer_email": "customer@test.com",
"recipient_id": null,
"recipient_email": null,
"note": null,
"expires_on": "2025-10-10",
"message": null,
"last_characters": "262f",
"order_id": null
}
}
```
# Gift Card Balance Lookup
Let customers check their gift card balance on your storefront
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).
{% 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 %}
# Theme App Embeds
Optional storefront blocks for Gift Card Factory β what they do, and why most stores don't need them
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 and we'll help you set it up.
{% endhint %}
## Related pages
* [Gift Card Postman](/campaigns/gift-card-postman) β the campaign that uses the Postman block.
* [Gift Card Balance Lookup](/integrations/gift-card-balance-lookup) β full settings reference for the lookup block.
* [Gift Card Rewards](/campaigns/gift-card-rewards) β the campaign the reward banner promotes.
# Shopify Flow
You can use Shopify Flow to send your gift card emails or configure other actions in response to gift card creation.\
\
We also give you access to our Flow Templates library, where you can use one of our pre-configured gift card flows.
# Actions
Shopify Flow Actions with Gift Card Factory
After installing Gift Card Factory, you will have access to 4 new actions in Shopify Flow:
* **Create Gift Card**
* **Create Gift Card V2**
* **Get Gift Card**
* **Disable Gift Card**
All actions use app credits. Anytime action is taken - app will use **one** Flow credit.
### Create Gift Card
This action is deprecated. Use **Create Gift Card V**2 instead
### Create Gift Card V2
This action creates native Shopify Gift Card and optionally sends it to selected customer.
#### Action Options
* **Skip sending**: Create the gift card without sending it.
* **Recipient email**: Enter the recipient's email address.
* **Value**: Define the initial value in the store's main currency.
* **Message**: Include a custom message with the gift card email.
* **Days to expiry**: Specify the validity period in days from creation.
* **Expires on**: Set a fixed expiry date (format: YYYY-MM-DD). Ignored if Days to expiry field is set and different from 0
* **Days to send**: Dispatches the gift card after a set number of days. Ignored if Send on field is set.
* **Send on**: Schedule the exact date to send the gift card (format: YYYY-MM-DDTHH:mm:ss format, e.g. 2025-01-30T14:15:00)
* **Note**: Add internal notes, invisible to customers.
### Get Gift Card
The **Get Gift Card** action retrieves properties of a gift card. You need to provide the gift card ID. This action is useful for checking current gift card properties and planning subsequent actions.
### Disable Gift Card
To disable a gift card, provide its ID. For an example of usage, you might refer to our template flow: **Disable a Gift Card After First Use**.
# Templates
Our flow template library offers you a number of different, predefined flows. To install flow from our template, follow these steps:
* Go to the Flow Templates section in the app.
* Find and download your desired flow template.
* Open Shopify Flow.
* Click the **Import** button.
* Select the downloaded file to import the flow.
{% hint style="info" %}
If you can't find the flow you need, contact us to create a custom solution tailored to your requirements.
{% endhint %}
# Triggers
There are 3 different triggers you can use in Shopify Flow to extend the functionality of the app. These are:
* **Bulk Operation** - Fires when a gift card is created via bulk actions.
* **Gift Card Reminder** - Fires for gift cards matching reminder campaign criteria.
* **Gift Card Reward** - Fires when an order meets rewards campaign criteria.
You can select the trigger anywhere the app shows the dialog in the screenshot below.
When selected, the app will send the data to Shopify Flow. Next, you can configure further actionsβfor example, add tags to the gift-card customer, send a gift-card email, or send internal emails any time a gift card is issued.
### Bulk Operation
This trigger is used any time a gift card is created via one of the appβs Bulk Operation features: Bulk Send, Import from File, Auto-generate, or Bulk Update.\
\
The operation type is sent as part of the trigger payload. By using if conditions, you can filter out operations you don't need to respond to and take action only when a certain operation takes place. For example, you might only respond to a gift card created in Bulk Send with the following flow:
### Gift Card Reminder
Triggers any time a gift card is found for which the campaign conditions are met. For this trigger to work, you need to first configure the Gift Card Reminders campaign.
Next, you can respond to the trigger and take appropriate action. Gift card data is sent as part of the trigger payload.
{% hint style="info" %}
Only the last four digits of the gift card are included in the trigger payload.
{% endhint %}
### Gift Card Reward
Triggers any time an order meeting Gift Card Rewards campaign conditions is placed. For this trigger to work, you need to first configure Gift Card Rewards campaign.
You can access all the gift card data (including the gift card code) through the trigger payload.
# Klaviyo
To start sending gift card emails through Klaviyo you will need to:
1. [Connect Klaviyo](/integrations/klaviyo/connect-klaviyo)
2. [Configure Klaviyo Flow](/integrations/klaviyo/klaviyo-flows) that will respond to metric sent by the app.
# Connect Klaviyo
To connect Klaviyo follow these steps:
1. **Open app settings and select Klaviyo in integration section.**\
In Gift Card Factory, navigate to Settings. Next turn on Klaviyo integrartion:
2. **Find your Klaviyo Public API Key**\
Open your Klaviyo dashboard. Navigate to Account Settings -> API Keys. You will find your API Key inside Public API Key section.
3. **Add the key to Gift Card Factory**\
Copy the Public API Key and add it to app settings under *Klaviyo Public API Key.* Click save. Lastly send placeholder metrics by clicking on Send test metrics button and providing Contact email address. This will register all app metrics in your Klaviyo account. As a next step you can configure a flow that will take actions based on metrics sent by the app.\
You can use any of the metrics to trigger Klaviyo flow. Different metric is sent for different app feature.\
\
Klaviyo Metrics Reference
This document maps each Klaviyo metric to the app feature (campaign or bulk operation) that triggers it.
### Quick Reference Table
| Klaviyo Metric | Feature Type | Feature Name |
| ----------------------------------------- | -------------- | ----------------------------------------------------------------------- |
| Gift Card Factory - Bulk Send | Bulk Operation | [Bulk Send](/bulk-operations/bulk-send) |
| Gift Card Factory - Import From File | Bulk Operation | [Import From File](/bulk-operations/import-from-file) |
| Gift Card Factory - Store Credit Bulk Add | Bulk Operation | [Store Credit Bulk Add](/bulk-operations/store-credit-bulk-add) |
| Gift Card Factory - Rewards | Campaign | [Gift Card Rewards](/campaigns/gift-card-rewards) |
| Gift Card Balance Reminder | Campaign | [Gift Card Reminders](/campaigns/gift-card-reminders) |
| Gift Card Factory - Scheduled Gift Cards | Campaign | [Scheduled Gift Cards](/campaigns/scheduled-gift-cards) |
| GCP Gift Card Email | Campaign | [Gift Card Postman](/campaigns/gift-card-postman) (recipient) |
| GCP Gift Card Sender Email | Campaign | [Gift Card Postman](/campaigns/gift-card-postman) (sender notification) |
| Gift Card Factory - Refund | Campaign | [Refund](/misc/app-emails/sending-domain/postmark) |
{% hint style="info" %}
App does not send Klaviyo metrics from **Shopify Flow**. If you need to send Klaviyo metric from Shopify Flow, you need to use Track an Event block as per screenshot below
{% endhint %}
### Next steps
[Learn how to create Klaviyo Flows](/integrations/klaviyo/klaviyo-flows)
# Klaviyo Flows
Send customized gift card emails with Klaviyo
With Klaviyo Flows, you can send emails using Klaviyo templates in response to Gift Card Factory events.
### Prerequisites
* [Klaviyo account connected with Gift Card Factory](/integrations/klaviyo/connect-klaviyo)
### Available Metrics
If selected, Gift Card Factory sends following events as metrics to Klaviyo:
* **Gift Card Factory - Bulk Send**: Sent anytime a gift card is created using [Bulk Operations - Bulk Send](/bulk-operations/bulk-send)
* **Gift Card Factory - Import From File**: Sent anytime a gift card is created using [Bulk Operations - Import From File](/bulk-operations/import-from-file)
* **Gift Card Factory - Rewards**: Sent when a gift card is created and sent through a [Gift Card Rewards](/campaigns/gift-card-rewards) campaign
* **Gift Card Factory - Refund:** Sent when a [Refund on Gift Card](/gift-card-refunds/introduction) is created.
* **Gift Card Balance Reminder:** Sent when gift card is created and sent through a [Gift Card Reminders](/campaigns/gift-card-reminders) campaign
* **GCP Gift Card Email:** Sent to the recipient of a purchased gift card ([Gift Card Postman](/campaigns/gift-card-postman))
* **GCP Gift Card Sender Email:** Sent to the sender of a purchased gift card ([Gift Card Postman](/campaigns/gift-card-postman))
### Creating a Klaviyo Flow
To create a Klaviyo Flow you need to follow these steps:
1. In Klaviyo navigate to Flows and create a new flow
2. Select a trigger
3. Add an action
4. Enable the flow
5. *(Optional)* Apply for transactional status
#### 1. Navigate to Klaviyo to create a new flow
Open the Klaviyo dashboard, then go to **Flows β Create Flow β Build Your Own**. You should then see a new screen where you can select the trigger.
#### 2. Select trigger
From the tabbed menu on the right, select **Your Metrics β API**.\
Now find the Gift Card Factory metrics for which you want to send emails.\
For the purpose of this guide, we will use **GCP Gift Card Email**. This metric is registered against a contact in Klaviyo whenever someone purchases a gift card for someone else.
#### 3. Add action
From left hand side navigation select Email action.
Now you can configure all your email properties, such as:
* Subject
* Preview text
* Template
When editing the template, you can use any variables that were sent alongside the metric.
#### 4. Enable flow
Now you can enable your newly created flow. Click the **button** in the top-right section. Whenever Gift Card Factory sends the metric, the email will be sent to the contact who received the metric.
#### 5. (Optional) Apply for transactional status
By default, Klaviyo considers all emails sent through flows as marketing emails. To send transactional emails, you need to apply for a review. To apply for transactional status, select your Email action and, on the right panel, select the **Apply for transactional status** checkbox.
{% hint style="info" %}
It might take up to few hours for the status to be approved.
{% endhint %}
***
### Additional resources
* [Builing Klaviyo Flows](https://help.klaviyo.com/hc/en-us/articles/115002774932)
# App Emails
Email templates and sending domain configuration
Gift Card Factory sends emails on your behalf β gift card deliveries, reminders, refund confirmations and more. This section covers how to customize those emails and how to control which domain they're sent from.
* [Template Editor](/misc/app-emails/template-editor) β edit the default templates with our drag-and-drop editor and use Liquid variables to personalize the content
* [Sending Domain](/misc/app-emails/sending-domain) β switch from the default app domain to your own store domain
* [SendGrid](/misc/app-emails/sending-domain/sendgrid) β send via SendGrid using your API key
* [Postmark](/misc/app-emails/sending-domain/postmark) β send via Postmark using your API key
* [Domain Ownership Validation](/misc/app-emails/sending-domain/domain-ownership-validation) β validate your domain via DKIM and Return-Path DNS records
You can monitor every email the app has sent in **Emails β Deliveries**, and manage your templates from **Emails β Templates**.
# Sending Domain
By default, all emails are sent from the app's domain. This means your recipients will see **** as the "From" address.
To improve email deliverability and build trust with your customers, you can configure your own store domain as the sending domain.
There are two ways to do this:
1. **Use a supported email delivery service**\
Send emails through a third-party service like [**Postmark**](/misc/app-emails/sending-domain/postmark) or [**SendGrid**](/misc/app-emails/sending-domain/sendgrid).
2. **Verify ownership of your store domain**\
[Add DNS records](/misc/app-emails/sending-domain/domain-ownership-validation) to your domain to validate ownership and authorize it for sending emails.
To update your sending domain, go to **Settings β App Emails Sending**:
You'll see three options:
* **Default** β emails are sent from `mailer@giftcardfactory.app`. No setup required.
* **API Keys** β send via [SendGrid](/misc/app-emails/sending-domain/sendgrid) or [Postmark](/misc/app-emails/sending-domain/postmark) using your own account and API key.
* **DNS Validation** β send from your own domain after [validating ownership via DNS records](/misc/app-emails/sending-domain/domain-ownership-validation).
### Supported delivery services
To configure sending via a supported delivery service, you will need to add your API key in the app settings. Detailed instructions are available here:
* [SendGrid](/misc/app-emails/sending-domain/sendgrid)
* [Postmark](/misc/app-emails/sending-domain/postmark)
### Domain ownership validation
To validate ownership of your domain via DNS records, follow our instructions [here](/misc/app-emails/sending-domain/domain-ownership-validation).
# SendGrid
SendGrid sends your app emails through your own [SendGrid](https://sendgrid.com/) account. You'll need a SendGrid account with a verified sender identity (single sender or authenticated domain) before you start.
### 1. Create a SendGrid API key
In your SendGrid dashboard, navigate to **Settings β API Keys**.
Click **Create API Key** and select **Restricted Access** (or **Custom Access**, depending on your account version).
Under **Access Details**, give the key **Full Access** for **Mail Send**, then click **Create & View**. Copy the API key β you won't be able to see it again.
### 2. Add the API key to Gift Card Factory
1. Open **Settings β App Emails Sending** in the Gift Card Factory app.
2. Select **API Keys**.
3. In **From**, enter the address you want emails to come from in the format `My Store `. The address must be on a domain that is already authenticated in your SendGrid account.
4. Set **Provider** to **Sendgrid**.
5. Paste your API key into **Provider API key**.
6. Save the settings.
From now on, all app emails will be delivered through your SendGrid account, using your domain in the **From** address.
{% hint style="warning" %}
If the **From** domain is not authenticated in SendGrid, sends will fail. Make sure domain authentication is set up on the SendGrid side first.
{% endhint %}
# Postmark
Postmark sends your app emails through your own [Postmark](https://postmarkapp.com/) account. You'll need a Postmark account with an authenticated sender domain before you start.
### 1. Get your Postmark Server API token
In your Postmark dashboard, navigate to **Servers β \[Your Server Name] β API Tokens** and copy the **Server API token**.
### 2. Add the API token to Gift Card Factory
1. Open **Settings β App Emails Sending** in the Gift Card Factory app.
2. Select **API Keys**.
3. In **From**, enter the address you want emails to come from in the format `My Store `. The address must be on a domain that is already verified in your Postmark account.
4. Set **Provider** to **Postmark**.
5. Paste your Server API token into **Provider API key**.
6. Save the settings.
From now on, all app emails will be delivered through your Postmark account, using your domain in the **From** address.
{% hint style="warning" %}
If the **From** domain is not verified in Postmark, sends will fail. Make sure DKIM and Return-Path are validated on the Postmark side first.
{% endhint %}
# Domain Ownership Validation
DNS Validation lets you send app emails from your own store domain without having to bring your own SendGrid or Postmark account. Behind the scenes, Gift Card Factory provisions a sender for you and gives you two DNS records (DKIM and Return-Path) to add to your domain.
### 1. Generate the DNS records
1. Open **Settings β App Emails Sending** in the Gift Card Factory app.
2. Select **DNS Validation**.
3. In **Custom outbound email**, enter the address you want emails to come from (for example `hello@yourstore.com`).
4. Click **Generate DNS Records**.
The page will populate two records:
* a **DKIM** record (type `TXT`)
* a **Return-Path** record (type `CNAME`)
Each record shows the host (name) and value you'll need to copy into your DNS provider.
### 2. Add the records to your DNS provider
Log in to your DNS provider (Cloudflare, Route 53, GoDaddy, Shopify-managed DNS, etc.) and add both records exactly as shown β the host and value must match.
{% hint style="info" %}
DNS changes can take up to a few hours to propagate, although most providers update within 15β30 minutes.
{% endhint %}
### 3. Verify each record
Once the records are in place, come back to **Settings β App Emails Sending** and click the **Verify** button next to each record. A success banner appears when the record is found:
* **DKIM Verified!**
* **Return Path Verified!**
When both records are verified, all app emails will be sent from your custom outbound email.
If a record can't be found, the banner shows *"DNS Record Not Found"* β wait a little longer for propagation, double-check the host and value, and try again.
If you need help setting up the records, contact us at .
# Template Editor
When you send your gift card emails, you can use one of our default templates. These templates are fully editable through **Emails β Templates**.
You can use our drag-and-drop interface to modify or build new templates. Our template engine is powered by [Liquid](https://shopify.github.io/liquid/) and supports dynamic variables.
{% hint style="info" %}
All variables are exposed in **snake\_case**. For example, the shop's currency code is `shop.currency_code`, not `shop.currencyCode`.
{% endhint %}
### Variables available in every template
```
shop.name
shop.myshopify_domain
shop.email
shop.domain
shop.url
shop.currency_code
shop.currency_formats.money_format
shop.currency_formats.money_with_currency_format
customer.id
customer.email
customer.first_name
customer.last_name
```
### Gift card emails
Available in all gift card-related emails (Postman, Bulk Send, Import From File, Scheduled Gift Cards, Reminders, Rewards, etc.):
```
gift_card.code (not available in Gift Card Reminders emails)
gift_card.last_characters
gift_card.initial_value.amount
gift_card.initial_value.currency
gift_card.balance.amount
gift_card.balance.currency
gift_card.expires_on
gift_card.message
gift_card.image
gift_card.qr_code (not available in Gift Card Reminders emails)
gift_card.resend_url
```
### Gift card resend link
`gift_card.resend_url` is a secure link that re-sends the customer their gift card. When they click it, Shopify's native gift card email β containing the **full code** and a redeem link β is re-sent to the email on file. This is the recommended way to give customers their code again (Reminders emails don't include `gift_card.code`, and Shopify never re-exposes the code via API).
Use it as a button or link, for example:
```liquid
Resend my gift card
```
Notes:
* The link is signed and expires 30 days after the email is sent.
* The code is never in the link itself β clicking only re-emails the cardholder, so it's safe to include in any email.
* Available in App Email templates and Klaviyo events (`event.gift_card.resend_url`).
* The link points to `/apps/gcf/gift-card-resend` on the store's own domain (served via Shopify App Proxy).
### Gift card QR code
`gift_card.qr_code` renders a **QR code image** for the gift card. Drop the variable wherever you want the QR to appear in the email body:
```liquid
{{ gift_card.qr_code }}
```
The QR encodes `shopify-giftcard-v1-` (where `` is the gift card code). It is generated at send time and embedded directly in the email as an **inline image** β nothing is hosted externally and the raw code is never stored on our side. Because it depends on the gift card code, it is **not available in Gift Card Reminders** emails (which don't expose the code).
### Gift Card Postman emails
In addition to the gift card variables above, Postman emails expose the recipient and sender entered by the buyer on the product page:
```
recipient.name
recipient.email
sender.name
sender.email
```
### Store credit emails
Available in Scheduled Store Credit and Store Credit Bulk Add emails:
```
issued_store_credit.amount
issued_store_credit.currency_code
issued_store_credit.balance_after_transaction
```
### Discount code emails
Available in Discount Codes Bulk Send and Discount Codes Import From File emails:
```
discount_code.code
discount_code.discount_type
discount_code.discount_value
discount_code.starts_at
discount_code.ends_at
```
### Gift Card Refund emails
Refund emails expose information about the order and the refund itself:
```
order.number
order.id
refund.reason
refund.total_refunded
refund.shipping_refunded
refund.line_items[]
refund.line_items[0].image
refund.line_items[0].title
refund.line_items[0].amount
refund.line_items[0].price
refund.line_items[0].quantity
```
### Formatting money
Money amounts are exposed as raw numeric strings. Use the `format_money` filter together with the shop's money format to render them with the right currency symbol:
```liquid
{{ gift_card.initial_value.amount | format_money: shop.currency_formats.money_format }}
```
# Sending Customer Notifications
Flexible options for gift cards, discount codes or store credit delivery
### ποΈ **Shopify Email**
The standard Shopify gift card email is sent. This is the same email customers receive when purchasing a gift card through your store.\
You can edit the content in **Shopify Admin β Settings β Notifications β Customer Notifications β Gift card receipt / New gift card**.\
β *Best for stores that want a simple, no-setup delivery option.*\
\
**How it works:**
* Uses Shopify's default gift card notification email
* Sent directly from Shopify, not the app
* Uses your Shopify email settings
**When to use:**
* You want to use Shopify's native email system
* You've already customized Shopify's gift card email template
* You want consistent branding with other Shopify emails
**Setup:** You can customize the email template in Shopify Admin: Settings β Notifications β Customer notifications β Gift card created
**Note:** This uses Shopify's generic gift card email, not a campaign-specific template.
***
### π§ **App Email**
Gift cards are sent using the appβs built-in email templates. All templates are customizable via the app settings (**Email β Templates**).\
You can create your own templates using our powerful content editor with dynamic variables.\
π [Learn more about the templating engine and variables.](/misc/app-emails)\
β *Ideal for merchants who want custom-designed gift card emails with flexible formatting.*\
β οΈ *Requires more setup than Shopify Email.*
**How it works:**
* Gift Card Factory sends the email using the built-in scheduled-gift-cards.html template
* Fully managed, no additional setup required
* Includes a beautifully designed gift card email
**When to use:**
* You want a quick, simple setup
* You're satisfied with the default gift card email design
* You don't have other email marketing tools
**What's included in the email:**
* "A gift for you, \[Customer Name]" greeting
* Your custom gift card message
* Gift card value prominently displayed
* Gift card image
* Gift card code (formatted for easy copying)
* "Visit online store" button
* Expiration date (if applicable)
* Store contact information
**Template Selection:** Once you select App Email, choose your template
* **Default email templates** (default) - Pre-designed emails, depending on campaign
* **Custom templates** - Any custom templates you've created
**Preview Your Email:** Click the "Preview" link next to the template selector to see exactly what customers will receive.
**Email Sending Options:**
1. **Default App Domain** ()
* Ready to use immediately
* No setup required
* May have lower deliverability than custom domains
2. **Custom Domain** (Recommended)
* Emails sent from your own domain (e.g., )
* Better deliverability and trust
* Requires DNS configuration
* [Learn how to set up custom domain](https://docs.giftcardfactory.app/misc/app-emails/sending-domain)
3. **API Keys** (SendGrid, Postmark, etc.)
* Use your own email service provider
* Best deliverability
* Requires API configuration
* Full control over email infrastructure
***
### π¬ **Klaviyo**
When this option is selected, our app sends a **metric event** to Klaviyo. You can then configure a **flow** in Klaviyo to send a custom email in response.\
To use this option, you must connect your Klaviyo account by providing your **Public API key** in the app settings.\
π [Learn more about Klaviyo integration.](/integrations/klaviyo)\
β *Great for advanced email marketers using Klaviyo workflows.*\
β οΈ *Requires setup both in the app and in Klaviyo.*
**How it works:**
* App sends a metric to Klaviyo
* You create a Flow in Klaviyo that responds to the metric
* Full control over email design and timing in Klaviyo
**When to use:**
* You already use Klaviyo for email marketing
* You want advanced email personalization
* You want to include scheduled gift card emails in your Klaviyo analytics
**Requirements:**
* Active Klaviyo account
* Klaviyo integration enabled in Gift Card Factory
* Flow configured to respond to "Scheduled Gift Card Created" metric
**Setup Steps:**
1. Connect Klaviyo in Gift Card Factory settings
2. Create a Flow in Klaviyo triggered by the metric
3. Design your email in Klaviyo
4. [See detailed Klaviyo setup guide](https://docs.giftcardfactory.app/integrations/klaviyo/klaviyo-flows)
***
### π Shopify Flow
The app sends a **trigger event** to Shopify Flow. You can use this to build custom workflowsβlike sending emails or performing actions across apps or services.\
π [Learn more about our Shopify Flow integration.](#shopify-flow)\
β *Best for stores that want full control over automation, logic, and third-party integrations.*\
β οΈ *Requires setting up flows in Shopify Flow.*\
\
**How it works:**
* App sends a trigger to Shopify Flow
* You create a workflow in Shopify Flow to handle the email
* Most flexible option, can integrate with any email platform
**When to use:**
* You want to use a different email platform not listed
* You want to add additional workflow logic
* You need to send to multiple platforms
* You want to trigger other actions beyond email
**Requirements:**
* Shopify Plus plan (Flow is a Plus feature)
* Shopify Flow app installed
* Flow configured to respond to Gift Card Factory triggers
**Setup Steps:**
1. Create a new Flow in Shopify Flow
2. Use Gift Card Factory trigger
3. Add actions (send email, update customer tags, etc.)
4. [See Shopify Flow trigger documentation](https://docs.giftcardfactory.app/integrations/shopify-flow/triggers)
\
**π§Ύ Setup Complexity Summary**
| Method | Description | Setup Complexity | Customization | Integration Required |
| ----------------- | --------------------------------------------- | ---------------- | ------------- | -------------------- |
| **Shopify Email** | Sends default Shopify gift card email | π’ Easy | π΄ Limited | β No |
| **App Email** | Sends gift card via customizable app template | π‘ Medium | π’ High | β No |
| **Klaviyo** | Triggers a Klaviyo metric for email flows | π΄ Advanced | π’ High | β Yes (Klaviyo) |
| **Shopify Flow** | Sends a trigger to build custom logic | π΄ Advanced | π’ High | β Yes (Shopify Flow) |
# Customers Query Selector
The Customer Query selector is a powerful tool that helps you target specific customers for your campaigns. This guide will show you how to create queries to find exactly the right customers at the right time.
### What is a Customer Query?
A Customer Query is a search filter that automatically finds customers based on specific criteria when your campaign runs. It combines two powerful features:
1. **Shopify's search syntax** - The same search language used throughout Shopify
2. **Liquid templating** - Dynamic values that change based on when the campaign runs (like dates)
### How to Use the Customer Query Field
#### 1. Testing Your Query
Before saving your campaign, always use the **Test Query** button. This shows you:
* How many customers currently match your query
* If there are any errors in your query syntax
**Important:** The test runs with today's date and time, so results may differ when your campaign actually executes.
#### 2. Query Structure
A basic query looks like this:
```
tag:birthday-06-15
```
A dynamic query with Liquid looks like this:
```
tag:*{{ "now" | date: "%m-%d" }}
```
### Common Use Cases & Examples
#### Birthday Campaigns
**Find customers with birthdays today:**
```
tag:*{{ "now" | date: "%m-%d" }}
```
* `tag:*` searches for tags containing the pattern
* `{{ "now" | date: "%m-%d" }}` generates today's date in month-day format (e.g., "06-15")
* Requires customers to have tags like `birthday-06-15` for June 15th birthdays
**Find customers with birthdays this month:**
```
tag:*{{ "now" | date: "%m" }}
```
* Uses only the month (e.g., "06" for June)
* Works with tags like `birthday-month-06`
#### Anniversary Campaigns
**Find customers who joined exactly 1 year ago:**
```
tag:*{{ "now" | date: "%Y" | minus: 1 }}-{{ "now" | date: "%m-%d" }}
```
* Calculates last year's date dynamically
* Works with tags like `joined-2024-06-15`
#### Tag-Based Targeting
**Find VIP customers:**
```
tag:vip
```
**Find customers with multiple tags:**
```
tag:vip AND tag:email-subscriber
```
**Find customers with any of several tags:**
```
tag:gold OR tag:platinum OR tag:diamond
```
#### Location-Based Targeting
**Find customers in specific city:**
```
city:London
```
**Find customers in specific country:**
```
country:Canada
```
**Combine location with tags:**
```
country:USA AND tag:vip
```
#### Email Subscription Status
**Find customers who accept marketing:**
```
email_marketing_consent:subscribed
```
**Find customers who don't accept marketing:**
```
email_marketing_consent:unsubscribed
```
### Understanding Liquid Templating
Liquid is the templating language that makes your queries dynamic. It's enclosed in double curly braces: `{{ }}`
#### Date Formatting
The most common use is formatting dates:
| Format | Output | Example |
| ------ | ----------------------------- | ------- |
| `%Y` | Year (4 digits) | 2025 |
| `%y` | Year (2 digits) | 25 |
| `%m` | Month (01-12) | 06 |
| `%-m` | Month (1-12, no leading zero) | 6 |
| `%d` | Day (01-31) | 15 |
| `%-d` | Day (1-31, no leading zero) | 5 |
| `%B` | Full month name | June |
| `%b` | Short month name | Jun |
#### Date Filters
**Get current date/time:**
```liquid
{{ "now" | date: "%Y-%m-%d" }}
```
**Get tomorrow's date:**
```liquid
{{ "now" | date: "%s" | plus: 86400 | date: "%m-%d" }}
```
(86400 is the number of seconds in a day)
**Get date from 7 days ago:**
```liquid
{{ "now" | date: "%s" | minus: 604800 | date: "%m-%d" }}
```
(604800 is the number of seconds in 7 days)
### Advanced Query Examples
#### Seasonal Campaigns
**Summer birthday customers (June-August):**
```
tag:birthday-06* OR tag:birthday-07* OR tag:birthday-08*
```
**Holiday season customers:**
```
tag:*12-* AND email_marketing_consent:subscribed
```
#### Customer Engagement
**Customers who haven't purchased in 90 days but are tagged:**
```
tag:at-risk AND orders_count:>0
```
**High-value customers:**
```
tag:high-value AND email_marketing_consent:subscribed
```
#### Dynamic Monthly Campaigns
**First day of current month:**
```
tag:*{{ "now" | date: "%m" }}-01
```
**Last week of current month:**
```
tag:*{{ "now" | date: "%m" }}-2* OR tag:*{{ "now" | date: "%m" }}-3*
```
### Query Operators
#### AND Operator
Customers must match **all** conditions:
```
tag:vip AND city:London
```
#### OR Operator
Customers must match **at least one** condition:
```
tag:gold OR tag:platinum
```
#### NOT Operator
Exclude customers matching a condition:
```
tag:customer NOT tag:exclude-from-campaigns
```
#### Wildcards (\*)
Match partial patterns:
```
tag:birthday-*
```
Finds all tags starting with "birthday-"
### Setting Up Customer Tags
For date-based campaigns (like birthdays), you need to tag your customers in Shopify first:
#### Birthday Tag Format
Recommended format: `birthday-MM-DD`
Examples:
* `birthday-01-15` (January 15)
* `birthday-06-30` (June 30)
* `birthday-12-25` (December 25)
#### How to Tag Customers
1. Go to Shopify Admin β Customers
2. Select a customer
3. In the Tags field, add: `birthday-MM-DD` (replace with actual date)
4. Save the customer
**Tip:** You can bulk tag customers by:
* Importing a CSV with tags
* Using Shopify Flow
* Using a third-party app
### Best Practices
#### 1. Always Test Your Query
Click the **Test Query** button before saving. This prevents errors and shows you how many customers will be targeted.
#### 2. Start Simple
Begin with basic queries and add complexity gradually:
* Start: `tag:birthday`
* Add date: `tag:birthday-{{ "now" | date: "%m-%d" }}`
* Add consent: `tag:birthday-{{ "now" | date: "%m-%d" }} AND email_marketing_consent:subscribed`
#### 3. Use Consistent Tag Formats
Stick to one format for similar tags:
* β Good: `birthday-01-15`, `birthday-02-20`
* β Bad: `birthday-01-15`, `bday-2-20`, `birthday_march_10`
#### 4. Consider Email Consent
Always consider adding email consent to avoid sending to customers who opted out:
```
your-query AND email_marketing_consent:subscribed
```
#### 5. Watch Your Customer Count
If your test shows more than 250 customers, consider:
* Narrowing your query with additional filters
* Checking if your tag format is too broad
* Splitting into multiple campaigns
### Troubleshooting
#### "Query returned an error"
* **Problem:** Syntax error in your query
* **Solution:** Check for:
* Typos in operators (AND, OR, NOT)
* Missing or extra curly braces `{{ }}`
* Incorrect date format codes
#### "Found 0 customers"
* **Problem:** No customers match your criteria
* **Solution:**
* Verify your customers have the required tags
* Test without Liquid first: replace dynamic dates with fixed dates
* Check for typos in tag names
#### "Found more than 250 customers"
This is a safety limit. If you see this:
* **Your query might be too broad**
* **Check for wildcards** that match too many tags
* **Add more specific filters** to narrow results
Example fix:
```
β tag:customer
β tag:customer AND tag:birthday-{{ "now" | date: "%m-%d" }}
```
#### Query works in test but not during campaign
* **Problem:** Time-based queries may differ between test and execution
* **Solution:**
* Remember that `{{ "now" }}` uses the campaign's execution time
* Test queries will use the current moment
* Scheduled campaigns run at specific times, affecting date-based filters
### Examples by Campaign Type
#### Scheduled Gift Cards Campaign
**Daily birthday campaign:**
```
tag:birthday-{{ "now" | date: "%m-%d" }} AND email_marketing_consent:subscribed
```
**Birthday month campaign:**
```
tag:birthday-{{ "now" | date: "%m" }}* AND email_marketing_consent:subscribed
```
#### Anniversary Campaign
**Customer join anniversary:**
```
tag:joined-{{ "now" | date: "%m-%d" }} AND orders_count:>0
```
#### VIP Customer Campaign
**VIP customers in specific region:**
```
tag:vip AND country:United States AND email_marketing_consent:subscribed
```
#### Re-engagement Campaign
**Customers tagged for re-engagement this month:**
```
tag:reengage-{{ "now" | date: "%Y-%m" }}
```
### Getting Help
If you need assistance creating the right query for your campaign:
* **Email Support:**
When contacting support, include:
1. What you're trying to achieve
2. Your current query
3. The error message or unexpected result
4. How many customers you expect vs. actual results
***
{% hint style="info" %}
**Pro Tip:** Save successful queries in a document for future reference. You can reuse and adapt them for different campaigns!
{% endhint %}
# Recipients Selector
The recipients selector lets you choose who should receive gift cards, discount codes, or store credit. There are **four input methods**, each suited to a different scenario.
> Used by: [Gift Card Bulk Send](/bulk-operations/bulk-send), [Discount Codes Bulk Send](/bulk-operations/discount-codes-bulk-send), [Store Credit Bulk Add](/bulk-operations/store-credit-bulk-add), and several campaigns.
**Method 1: Manual List of Emails (Default)**
**How it works:** Type or paste a list of email addresses or customer IDs directly into the text field.
**Format:**
* Separate entries with commas OR new lines
* Mix of emails and customer IDs is allowed
* Extra spaces are automatically removed
**Examples:**
Comma-separated:
```
john@example.com, jane@example.com, bob@example.com
```
New line separated:
```
john@example.com
jane@example.com
bob@example.com
```
Mixed format:
```
john@example.com, jane@example.com
bob@example.com
```
Using customer IDs:
```
123456789
987654321
```
**When to use:**
* You have a specific list of customers
* You're copying emails from a spreadsheet
* You have 50 or fewer customers
* You need precise control over recipients
**Tips:**
* Copy from Excel/Google Sheets directly - the app handles formatting
* If you have customer IDs from Shopify exports, you can use those
* The app will create new customer records if emails don't exist yet
* Always double-check for typos in email addresses
***
**Method 2: Select Customers**
**How it works:** Click a button to open a customer selector where you can browse and choose specific customers from your store.
**Steps:**
1. Click **"Select customers"** button
2. Browse or search for customers in the modal
3. Check the boxes next to customers you want to include
4. Click **"Confirm"** to apply your selection
**Features:**
* Search by name, email, or customer details
* See customer information before selecting
* Multi-select - choose as many as needed
* Change selection anytime before creating the operation
* Clear all selections with one click
**When to use:**
* You want to browse your customer list
* You need to verify customer details before selection
* You're not sure of exact email addresses
* You want a visual selection process
* You have 10-200 customers to select
**Display:** After selection, you'll see a green banner showing:
* "X customers selected"
* Buttons to change or clear your selection
***
**Method 3: Select Customer Segment**
**How it works:** Choose an entire customer segment that you've already created in Shopify, and all members of that segment will receive gift card, discount code or store credit.
**Steps:**
1. Click **"Select segment"** button
2. Browse available segments from your Shopify store
3. Select the segment you want
4. Click **"Confirm"** to apply
**Features:**
* Uses your existing Shopify customer segments
* Automatically includes all segment members
* Shows member count before confirmation
* Perfect for large groups
* Updates dynamically if segment membership changes before execution
**What are Shopify Segments?** Customer segments are groups of customers in Shopify based on criteria like:
* Purchase history (e.g., "Customers who spent $500+")
* Location (e.g., "Customers in California")
* Engagement (e.g., "Subscribed to marketing")
* Custom tags or attributes
**Creating Segments:** If you haven't created segments yet:
1. Go to Shopify Admin β Customers
2. Click "Segments" or "Create segment"
3. Set your criteria
4. Save the segment
5. Return to Gift Card Factory and select it
**When to use:**
* You have existing segments in Shopify
* You're targeting large groups (100+ customers)
* You want dynamic membership (segment updates automatically)
* You run regular campaigns to the same groups
* You need consistent targeting across operations
**Display:** After selection, you'll see a green banner showing:
* "Segment: \[Segment Name] (X members)"
* Buttons to change or clear your selection
**Important:** The segment members are evaluated at the time the operation runs, not when you create it. If you schedule the operation for the future, the segment membership may change between now and then.
***
**Method 4: Customers Query**
**How it works:** Enter a Shopify customer search query (e.g. `tag:vip`, `orders_count:>5`, or a Liquid expression like `tag:birthday-{{ "now" | date: "%m-%d" }}`). The recipient list is **resolved at execution time** β every customer matching the query when the operation runs becomes a recipient.
**Steps:**
1. Switch to the **Customers query** tab.
2. Enter your query in the input field.
3. Use the **Test Query** button to preview the matching customers.
4. The query is saved with the operation; the actual list is computed when the operation executes.
**Features:**
* **Dynamic recipients** β the same query produces different recipients on different days (e.g. `tag:birthday-{{ "now" | date: "%m-%d" }}` matches today's birthdays each time it runs).
* Uses [Shopify's customer search syntax](https://shopify.dev/docs/api/usage/search-syntax), supporting `AND` / `OR` / `NOT`, wildcards, and many fields (tags, location, orders count, marketing consent, etc.).
* Supports [Liquid templating](/misc/customers-query-selector#understanding-liquid-templating) for date-based queries.
* No upfront list β recipients can be added/removed by tagging or untagging customers in Shopify.
**When to use:**
* **Recurring or scheduled campaigns** where the audience changes over time (birthday campaigns, anniversary campaigns, "customers tagged X this month").
* **Tag-driven workflows** where you (or another system) maintain audience membership via Shopify tags.
* **Targeting by attribute** (location, marketing consent, order count) without manually building a list.
* **Pairing with the** [**Customers Query Selector docs**](/misc/customers-query-selector) for in-depth syntax reference and examples.
**Limitations:**
* Shopify's search returns up to **250 matching customers** per execution. If your query matches more, narrow it (more specific tags, additional `AND` conditions).
* You won't see the actual recipient list until the operation runs (use **Test Query** to preview, but remember the test runs against today's date β scheduled runs will use the date at execution time).
**See also:** [Customers Query Selector](/misc/customers-query-selector) for the full query syntax, Liquid filters, and worked examples.
***
#### Comparing Recipient Methods
| Feature | Manual List | Select Customers | Select Segment | Customers Query |
| -------------------------- | ----------------------- | ----------------------- | ---------------------------------- | ---------------------------------- |
| **Best for** | Small, specific lists | Medium-sized selections | Large groups | Recurring / dynamic campaigns |
| **Size limit** | Any | 50β200 practical | Unlimited | Up to 250 per execution |
| **Requires preparation** | List of emails | No | Segment must exist | Tags / attributes set on customers |
| **Visual selection** | No | Yes | Yes | No (preview via Test Query) |
| **Dynamic at run time?** | No (static list) | No (snapshot) | Yes (segment members re-evaluated) | Yes (query re-runs) |
| **Supports Liquid dates?** | No | No | No | Yes |
| **Speed to set up** | Fast for small lists | Moderate | Very fast | Moderate (query authoring) |
| **Accuracy** | Requires careful typing | High | High | High (assuming correct query) |
**Recommendation:**
* **One-off, small list (1β50)** β Manual list, if you have the emails.
* **One-off, medium browse-and-pick** β Select customers.
* **One-off, large pre-defined group** β Select segment.
* **Recurring / scheduled with changing audience** β Customers query.
* **Date-driven (birthdays, anniversaries)** β Customers query with Liquid.
# Subscription Plans
Usage & Credits System
### Overview
The app uses a credit-based billing system. Each subscription plan includes a set number of credits across 5 categories. Credits are consumed when operations are performed and reset at the start of each billing cycle.
### Credit Types
| Credit Type | What It Covers |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| **Bulk Operation** | All bulk operations: bulk send, autogenerate, import from file, bulk update, store credit bulk add, discount code operations |
| **Campaign** | All campaign types with weighted costs (see below) |
| **Refund** | Gift card refunds created through the order page |
| **Flow** | Shopify Flow actions (create, get, resend, disable gift cards) |
| **App Email** | Every email sent via Postmark/SendGrid across all features |
### Campaign Credit Weights
Campaign credits use a weighted system. Different campaign types consume different amounts of credits per operation, reflecting their complexity and cost.
| Campaign Type | Credits Per Operation | What Happens |
| -------------------------- | --------------------- | ---------------------------------------------------------------------------------------------- |
| **Gift Card Reminders** | 1 | Sends a reminder email about an existing gift card |
| **Store Credit Reminders** | 1 | Sends a reminder email about a customer's store credit balance |
| **Gift Card Rewards** | 5 | Creates a gift card + sends email on qualifying order |
| **Store Credit Rewards** | 5 | Adds store credit + sends email on qualifying order |
| **Scheduled Gift Cards** | 5 | Creates a gift card + sends notification email |
| **Scheduled Store Credit** | 5 | Adds store credit to customer + sends notification |
| **Gift Card Postman** | 25 | Creates a gift card from order line item + sends email(s) to recipient (and optionally sender) |
**Example**: A Bronze plan shop (1,000 campaign credits) could use:
* 500 Reminders (500 credits) + 20 Postman (500 credits) = 1,000 credits
* 200 Reminders (200 credits) + 80 Rewards (400 credits) + 80 Scheduled Gift Cards (400 credits) = 1,000 credits
### App Email Credits
App Email credits are tracked separately from campaign/operation credits. They count every email sent via the app's email infrastructure (Postmark or SendGrid).
App emails are **not** consumed when using:
* **Shopify Email** (native Shopify notification) - free
* **Klaviyo** (event API call) - free
* **Shopify Flow** (webhook trigger) - free
App emails **are** consumed when using:
* **App Email** sender (Postmark/SendGrid) - 1 credit per email sent
This means a campaign operation can consume both campaign credits AND app email credits if it uses the App Email sender. If the shop uses Shopify Email or Klaviyo as the sender, only campaign credits are consumed.
### Plan Limits
| Plan | Price | Refund | Bulk Operation | Campaign | Flow | App Email |
| -------- | ------- | --------- | -------------- | --------- | --------- | --------- |
| Trial | $0 | 50 | 1,000 | 500 | 500 | 500 |
| Bronze | $19.99 | 50 | 1,000 | 1,000 | 500 | 1,000 |
| Silver | $49.99 | 150 | 3,000 | 3,000 | 1,500 | 3,000 |
| Gold | $99.99 | 350 | 10,000 | 8,000 | 5,000 | 10,000 |
| Platinum | $199.99 | Unlimited | 40,000 | Unlimited | Unlimited | 40,000 |
* **Unlimited** means no limit is enforced.
* **API access** is available during the Trial and on the Silver, Gold, and Platinum plans (not on Bronze).
* **Trial** plans have an expiration date. Once expired, all operations are blocked regardless of remaining credits.
# FAQ
#### 1. I didn't receive an email with the generated gift card codes
If a bulk operation finished but no email arrived:
* **Check spam / junk folders** β provider filters sometimes flag bulk emails.
* **Confirm the recipient address** β typos in the operation form prevent delivery.
* **Check Emails β Deliveries** β every email the app sends is logged there with its status (delivered, bounced, spam, etc.). Use this to confirm whether the email actually left the app.
* **Add our sending address to your safe-sender list** to prevent future emails from being filtered.
* If the email still doesn't arrive, contact with the operation number and the recipient address.
***
#### 2. Why can't I re-import gift cards with the same codes?
**Short answer:** Shopify does not allow gift cards to be deleted or recreated using the same code.
Once a gift card is created in Shopify, its code is permanently reserved. Even if the gift card is disabled, the code cannot be reused. Apps cannot delete, overwrite, or re-import gift cards using codes that already exist in Shopify.
**Your options:**
* Contact **Shopify Support** to ask if they can remove the existing gift cards (not guaranteed).
* Re-import using a **new code format** β for example, prefixing the original codes with `PS` β and notify customers of the updated codes.
This is a Shopify platform limitation and applies to all gift card apps.
***
#### 3. My emails keep landing in spam β what can I do?
By default, emails are sent from `mailer@giftcardfactory.app`. To improve deliverability, send emails from your own store domain instead:
* [Send via SendGrid](/misc/app-emails/sending-domain/sendgrid) using your SendGrid API key.
* [Send via Postmark](/misc/app-emails/sending-domain/postmark) using your Postmark API key.
* [Validate ownership of your store domain](/misc/app-emails/sending-domain/domain-ownership-validation) by adding DKIM and Return-Path DNS records.
Configure the option you want under **Settings β App Emails Sending**. See [App Emails β Sending Domain](/misc/app-emails/sending-domain) for the full guide.
***
#### 4. A customer can't redeem their store credit at checkout
Store credit is only redeemable when the customer is logged in via **new customer accounts**. If your store still uses classic customer accounts, customers won't be able to spend the balance.
Switch to new customer accounts under **Shopify Admin β Settings β Customer accounts**. See [Gift Cards vs Discount Codes vs Store Credit](/comparison) for the full explanation.
***
#### 5. My report shows "Expired" β can I still download it?
No. Report download links (both **Result** and **Errors** CSVs) expire **72 hours** after the report was created. Once expired, the file is no longer available.
Re-run the report from **Reports β New Report** to get a fresh CSV.
***
#### 6. Can I cancel a scheduled gift card or store credit send?
Yes. Open the relevant campaign or operation, find the **Scheduled** run in the runs table, select it, and click **Cancel**. The run will not be processed.
For Gift Card Postman runs, see [Gift Card Postman β Dashboard](/campaigns/gift-card-postman/dashboard).
***
#### 7. I deactivated a gift card by mistake β can I re-enable it?
No. Per Shopify's API: *"After a gift card is deactivated, it can't be used for further purchases or re-enabled"* ([Shopify docs](https://shopify.dev/docs/api/admin-graphql/latest/objects/GiftCard)). This is a Shopify platform limitation.
If you need to restore the value to the customer, issue a new gift card or store credit for the same amount.
***
#### 8. Where can I see every email the app has sent?
Open **Emails β Deliveries** in the app. Every email the app sends is logged there with its delivery status, recipient, template, and timestamp. From a delivery row you can also resend the email.
***
#### 9. I still need help
If your question isn't answered here, contact us at . Include your shop domain and any relevant operation, run, or report numbers so we can locate the issue quickly.
