# Introduction

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.md) to decide which value type fits your refund flow best. Gift cards are transferable; [store credit](/bulk-operations/store-credit-bulk-add.md) 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.md) 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.)

   <figure><img src="/files/5wq54z04d5MtxB57nwi4" alt=""><figcaption></figcaption></figure>
3. **Configure the refund** in the form that opens:

   <figure><img src="/files/kODlsZPh31LbTJMdypaN" alt=""><figcaption></figcaption></figure>

   * **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.md)).

### **📥 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.md) — how the refund email is sent and how to customize the template.
* [Email Template Editor](/misc/app-emails/template-editor.md) — building a Refund template.
* [Sending Domain setup](/misc/app-emails/sending-domain.md) — configure your domain for App Email.
* [Gift Cards vs Discount Codes vs Store Credit](/comparison.md) — picking the right value type.
* [Subscription Plans](/misc/subscription-plans.md) — refund limits per plan.


---

# Agent Instructions: Querying This Documentation

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

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

```
GET https://docs.giftcardfactory.app/gift-card-refunds/introduction.md?ask=<question>
```

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

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