Store Credits & Gift Cards

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

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

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

Store Credit Categories

Categories help organize store credits by their purpose:

Store Credit Types

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

Store Credit Events

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

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:

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

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

Gift Card States

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

Gift Card Lifecycle

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

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.

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.

// 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>',
})

# 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" }'

Gift Card Events

The gift card system publishes lifecycle events:

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

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 — Payment processing and methods
• Orders — Order management
• Customers — Customer management
• Events — Event system and subscribers