> ## Documentation Index
> Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Store Credits & Gift Cards

> Stored value mechanisms for refunds, loyalty rewards, and gifting

export const Since = ({version, from}) => {
  const knownPrevious = {
    '5.0': '4.10',
    '6.0': '5.4'
  };
  const previous = (from ?? knownPrevious[version]) ?? (() => {
    const [major, minor] = version.split('.').map(Number);
    if (Number.isNaN(major) || Number.isNaN(minor) || minor < 1) {
      throw new Error(`<Since version="${version}" />: cannot derive previous version automatically. ` + `Pass an explicit "from" prop, e.g. <Since version="${version}" from="X.Y" />.`);
    }
    return `${major}.${minor - 1}`;
  })();
  return <Tooltip tip={`Available since Spree ${version}+.`} cta="Upgrade instructions" href={`/developer/upgrades/${previous}-to-${version}`}>
      <Badge icon="lock">Spree {version}+</Badge>
    </Tooltip>;
};

<Since version="5.1" />

## Overview

Spree provides two stored value mechanisms that customers can use at checkout:

* **Store Credits** - Value assigned directly to a customer's account by admins (refunds, loyalty rewards, compensation)
* **Gift Cards** - Value with a redeemable code that can be shared and redeemed by anyone

| Feature          | Store Credit                           | Gift Card                       |
| ---------------- | -------------------------------------- | ------------------------------- |
| Purpose          | Refunds, loyalty rewards, compensation | Gifting, promotions, marketing  |
| Requires account | Yes (tied to customer account)         | No (guests can use at checkout) |
| Transferable     | No                                     | Yes (code can be shared)        |
| Has code         | No                                     | Yes                             |
| Created by       | Admin                                  | Admin                           |
| Assignment       | Directly to customer                   | Applied to order via code       |
| Expiration       | Configurable by type                   | Configurable per card           |

## Store Credits

Store Credits are monetary values assigned directly to a customer's account. They are commonly used for:

* Refunds (instead of returning money to original payment method)
* Loyalty rewards
* Customer compensation
* Promotional credits

### Store Credit Model

```mermaid theme={"theme":"night-owl"}
erDiagram
    StoreCredit ||--o{ StoreCreditEvent : "has many"
    StoreCredit ||--o{ Payment : "source for"
    StoreCredit }o--|| User : "belongs to"
    StoreCredit }o--|| Store : "belongs to"
    StoreCredit }o--o| StoreCreditCategory : "belongs to"
    StoreCredit }o--o| StoreCreditType : "belongs to"

    StoreCredit {
        decimal amount
        decimal amount_used
        decimal amount_authorized
        string currency
        string memo
    }

    StoreCreditCategory {
        string name
    }

    StoreCreditType {
        string name
        integer priority
    }

    StoreCreditEvent {
        string action
        decimal amount
        string authorization_code
    }
```

### Store Credit Attributes

| Attribute           | Description                                    | Example                  |
| ------------------- | ---------------------------------------------- | ------------------------ |
| `amount`            | Total credit amount                            | `100.00`                 |
| `amount_used`       | Amount already spent                           | `25.00`                  |
| `amount_authorized` | Amount currently authorized for pending orders | `0.00`                   |
| `currency`          | Currency code                                  | `USD`                    |
| `memo`              | Optional note about the credit                 | `Refund for order #R123` |

### Store Credit Categories

Categories help organize store credits by their purpose:

| Category  | Description                                    |
| --------- | ---------------------------------------------- |
| Default   | General purpose store credit                   |
| Gift Card | Store credit created from gift card redemption |

<Info>
  Categories can be configured as non-expiring. By default, the "Gift Card" category is non-expiring.
</Info>

### Store Credit Types

Types define the priority in which store credits are applied at checkout:

| Type         | Description                              |
| ------------ | ---------------------------------------- |
| Expiring     | Credits that may expire (applied first)  |
| Non-expiring | Credits that don't expire (applied last) |

### Store Credit Events

Every action on a store credit is recorded as an event for audit purposes:

| Action       | Description                                |
| ------------ | ------------------------------------------ |
| `allocation` | Initial credit was assigned                |
| `authorize`  | Credit was authorized for an order         |
| `capture`    | Authorized credit was captured             |
| `void`       | Authorization was voided                   |
| `credit`     | Credit was returned (e.g., order canceled) |

### Assigning Store Credits

Store credits are managed in the Admin Panel:

1. Navigate to **Customers** in the Admin Panel
2. Select a customer
3. Go to the **Store Credits** tab
4. Click **Add Store Credit**
5. Enter the amount, category, and optional memo
6. Click **Create**

Store credits can also be created via the Admin API.

### Store Credit Events

The store credit system publishes lifecycle events:

| Event                  | Description              |
| ---------------------- | ------------------------ |
| `store_credit.created` | Store credit was created |
| `store_credit.updated` | Store credit was updated |

## Gift Cards

Gift Cards are stored value codes created by admins that can be shared and redeemed by customers. When redeemed, they create a Store Credit on the customer's account.

### Gift Card Model

```mermaid theme={"theme":"night-owl"}
erDiagram
    GiftCard }o--|| Store : "belongs to"
    GiftCard }o--o| User : "belongs to"
    GiftCard }o--o| GiftCardBatch : "belongs to"
    GiftCard ||--o{ StoreCredit : "originator for"

    GiftCard {
        string code
        string state
        decimal amount
        decimal amount_used
        decimal amount_authorized
        string currency
        datetime expires_at
        datetime redeemed_at
    }

    GiftCardBatch {
        string prefix
        integer codes_count
        decimal amount
        string currency
        datetime expires_at
    }
```

### Gift Card Attributes

| Attribute     | Description              | Example      |
| ------------- | ------------------------ | ------------ |
| `code`        | Unique redemption code   | `abc1234def` |
| `amount`      | Total gift card value    | `50.00`      |
| `amount_used` | Amount already redeemed  | `0.00`       |
| `state`       | Current state            | `active`     |
| `currency`    | Currency code            | `USD`        |
| `expires_at`  | Optional expiration date | `2025-12-31` |

### Gift Card States

```mermaid theme={"theme":"night-owl"}
stateDiagram-v2
    [*] --> active: Created
    active --> partially_redeemed: Partial redemption
    active --> redeemed: Full redemption
    active --> canceled: Admin cancels
    partially_redeemed --> redeemed: Remaining redeemed
    partially_redeemed --> partially_redeemed: Another partial redemption
```

| State                | Description                  |
| -------------------- | ---------------------------- |
| `active`             | Available for redemption     |
| `partially_redeemed` | Some value has been redeemed |
| `redeemed`           | Fully redeemed               |
| `canceled`           | Canceled by admin            |

<Note>
  Gift cards can also be `expired` if `expires_at` date has passed and the card hasn't been fully redeemed.
</Note>

### Gift Card Lifecycle

```mermaid theme={"theme":"night-owl"}
flowchart TB
    A[Admin creates Gift Card] --> B[Code generated]
    B --> C[Admin shares code with recipient]
    C --> D[Recipient enters code at checkout]
    D --> E[Store Credit created for customer]
    E --> F[Gift Card marked as redeemed]
    F --> G[Customer uses Store Credit]
```

### Creating Gift Cards

#### Single Gift Card

1. Navigate to **Gift Cards** in the Admin Panel
2. Click **Create Gift Card**
3. Enter the amount and optional expiration date
4. Click **Create**
5. Share the generated code with the recipient

Gift cards can also be created via the Admin API.

#### Batch Gift Card Generation

For promotions or bulk distribution, you can create multiple gift cards at once using Gift Card Batches:

1. Navigate to **Gift Cards** in the Admin Panel
2. Click **Create Batch**
3. Enter:
   * **Prefix** - Code prefix for easy identification (e.g., `HOLIDAY`)
   * **Count** - Number of cards to generate
   * **Amount** - Value per card
   * **Expiration** - Optional expiration date
4. Click **Create**

<Info>
  Large batches are processed in the background to avoid timeout issues.
</Info>

### Redeeming Gift Cards

Gift cards can be redeemed by both **registered customers** and **guest visitors** at checkout. This is a key difference from Store Credits, which require a customer account.

<Info>
  Unlike Store Credits which are tied to a customer account, Gift Cards can be applied directly to an order during checkout - no account required. This makes them ideal for gifting to anyone.
</Info>

When a gift card is applied to an order:

* The gift card value is used to pay for the order
* The gift card is marked as redeemed (or partially redeemed)
* No Store Credit is created for guest checkouts

Gift cards are applied using the same coupon codes endpoint as promotion codes. The endpoint automatically detects whether the code is a promotion coupon or a gift card.

<CodeGroup>
  ```typescript SDK theme={"theme":"night-owl"}
  // Apply gift card code to cart (works for guests and registered customers)
  // Gift cards use a dedicated endpoint — they reduce amount_due, not total
  const cart = await client.carts.giftCards.apply('cart_abc123', 'abc1234def', {
    spreeToken: '<token>',
  })

  // Remove gift card (ID from cart.gift_card.id)
  await client.carts.giftCards.remove('cart_abc123', cart.gift_card.id, {
    spreeToken: '<token>',
  })
  ```

  ```bash cURL theme={"theme":"night-owl"}
  # Apply gift card to cart (works for guests and registered customers)
  curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_abc123/gift_cards' \
    -H 'X-Spree-Api-Key: pk_xxx' \
    -H 'X-Spree-Token: <token>' \
    -H 'Content-Type: application/json' \
    -d '{ "code": "abc1234def" }'
  ```
</CodeGroup>

### Gift Card Events

The gift card system publishes lifecycle events:

| Event                          | Description                      |
| ------------------------------ | -------------------------------- |
| `gift_card.created`            | Gift card was created            |
| `gift_card.redeemed`           | Gift card was fully redeemed     |
| `gift_card.partially_redeemed` | Gift card was partially redeemed |

## Using at Checkout

Store Credits and Gift Cards work differently at checkout:

* **Store Credits** - Require a customer account; applied from the customer's balance
* **Gift Cards** - Can be used by anyone (guests included); applied directly to the order via code

### Checkout Flow

```mermaid theme={"theme":"night-owl"}
flowchart TB
    A[Customer proceeds to payment] --> B{Guest or Registered?}
    B -->|Registered| C{Has Store Credit?}
    B -->|Guest| D{Has Gift Card code?}
    C -->|Yes| E[Display available balance]
    C -->|No| D
    D -->|Yes| F[Apply Gift Card to order]
    D -->|No| G[Show payment methods]
    E --> H{Apply Store Credit?}
    H -->|Yes| I[Authorize store credit]
    H -->|No| D
    F --> J{Covers order total?}
    I --> J
    J -->|Yes| K[Complete order]
    J -->|No| G
    G --> L[Customer pays remaining balance]
    L --> K
```

### Store Credit Priority

When a registered customer has multiple store credits, they are applied in order of priority:

1. **Expiring credits** - Applied first to ensure they're used before expiration
2. **Non-expiring credits** - Applied after expiring credits

## Related Documentation

* [Payments](/developer/core-concepts/payments) — Payment processing and methods
* [Orders](/developer/core-concepts/orders) — Order management
* [Customers](/developer/core-concepts/customers) — Customer management
* [Events](/developer/core-concepts/events) — Event system and subscribers