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 |
| Gift Card | Store credit created from gift card redemption |
Categories can be configured as non-expiring. By default, the “Gift Card” category is 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.
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.
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
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 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 order (works for guests and registered customers)
const order = await client.orders.couponCodes.apply('or_abc123', 'abc1234def', {
orderToken: '<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
