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
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 (also the default reimbursement category) |
| Expiring | Store credit that may expire |
| Non-expiring | Store credit that does not expire |
“Gift Card” is not a seeded category but a special name recognized by the model: any category named “Gift Card” (or one listed in Spree::Config[:non_expiring_credit_types]) is treated as non-expiring via StoreCreditCategory#non_expiring?.
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:
- Navigate to Customers in the Admin Panel
- Select a customer
- Go to the Store Credits tab
- Click Add Store Credit
- Enter the amount, category, and optional memo
- Click Create
Store credits can also be created via the Admin API, as a nested resource under the customer:
import { createAdminClient } from '@spree/admin-sdk'
const client = createAdminClient({
baseUrl: 'https://store.example.com',
secretKey: 'sk_xxx',
})
const credit = await client.customers.storeCredits.create('cus_xxx', {
amount: '25.00',
currency: 'USD',
category_id: 'sccat_xxx',
memo: 'Goodwill credit for delayed shipment',
})
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
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
| State | Description |
|---|
active | Available for redemption |
partially_redeemed | Some value has been redeemed |
redeemed | Fully redeemed |
canceled | Canceled by admin |
Gift cards can also be expired if expires_at date has passed and the card hasn’t been fully redeemed.
Gift Card Lifecycle
Creating Gift Cards
Single Gift Card
- Navigate to Gift Cards in the Admin Panel
- Click Create Gift Card
- Enter the amount and optional expiration date
- Click Create
- Share the generated code with the recipient
Gift cards can also be created via the Admin API. The code is generated automatically if you don’t supply one:
import { createAdminClient } from '@spree/admin-sdk'
const client = createAdminClient({
baseUrl: 'https://store.example.com',
secretKey: 'sk_xxx',
})
const giftCard = await client.giftCards.create({
amount: '50.00',
currency: 'USD',
expires_at: '2026-12-31',
})
console.log(giftCard.code) // share this with the recipient
Batch Gift Card Generation
For promotions or bulk distribution, you can create multiple gift cards at once using Gift Card Batches:
- Navigate to Gift Cards in the Admin Panel
- Click Create Batch
- Enter:
- Prefix - Code prefix for easy identification (e.g.,
HOLIDAY)
- Count - Number of cards to generate
- Amount - Value per card
- Expiration - Optional expiration date
- Click Create
Batches can also be created via the Admin API:
const batch = await client.giftCardBatches.create({
prefix: 'HOLIDAY',
codes_count: 1000,
amount: '25.00',
currency: 'USD',
expires_at: '2026-12-31',
})
Large batches are processed in the background to avoid timeout issues.
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.
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.
- 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 via a dedicated POST /api/v3/store/carts/:cart_id/gift_cards endpoint (separate from the discount_codes endpoint used for promotion codes); the discount-codes endpoint does not handle gift cards. See the cart & checkout SDK guide for the full cart flow these calls belong to.
// 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>',
})
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
Store Credit Priority
When a registered customer has multiple store credits, they are applied in order of priority:
- Expiring credits - Applied first to ensure they’re used before expiration
- Non-expiring credits - Applied after expiring credits
