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

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

spree api post /customers/cus_xxx/store_credits -d '{
  "amount": "25.00",
  "currency": "USD",
  "category_id": "sccat_xxx",
  "memo": "Goodwill credit"
}'

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

spree api post /gift_cards -d '{
  "amount": "50.00",
  "currency": "USD",
  "expires_at": "2026-12-31"
}'

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

spree api post /gift_card_batches -d '{
  "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.

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

# 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:

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

Payments — Payment processing and methods
Orders — Order management
Customers — Customer management
Events — Event system and subscribers
Admin SDK Quickstart — Set up and authenticate the Admin SDK
Monetary Amounts — How the API represents amount, amount_used, and other money fields

Getting started

Platform

Catalog

Cart & Checkout

Fulfillment

Extensibility

Overview

Store Credits

Store Credit Model

Store Credit Attributes

Store Credit Categories

Store Credit Types

Store Credit Events

Assigning Store Credits

Store Credit Events

Gift Cards

Gift Card Model

Gift Card Attributes

Gift Card States

Gift Card Lifecycle

Creating Gift Cards

Single Gift Card

Batch Gift Card Generation

Redeeming Gift Cards

Gift Card Events

Using at Checkout

Checkout Flow

Store Credit Priority

​Overview

​Store Credits

​Store Credit Model

​Store Credit Attributes

​Store Credit Categories

​Store Credit Types

​Store Credit Events

​Assigning Store Credits

​Store Credit Events

​Gift Cards

​Gift Card Model

​Gift Card Attributes

​Gift Card States

​Gift Card Lifecycle

​Creating Gift Cards

​Single Gift Card

​Batch Gift Card Generation

​Redeeming Gift Cards

​Gift Card Events

​Using at Checkout

​Checkout Flow

​Store Credit Priority

​Related Documentation

Overview

Store Credits

Store Credit Model

Store Credit Attributes

Store Credit Categories

Store Credit Types

Store Credit Events

Assigning Store Credits

Store Credit Events

Gift Cards

Gift Card Model

Gift Card Attributes

Gift Card States

Gift Card Lifecycle

Creating Gift Cards

Single Gift Card

Batch Gift Card Generation

Redeeming Gift Cards

Gift Card Events

Using at Checkout

Checkout Flow

Store Credit Priority

Related Documentation