Store Credits & Gift Cards - Spree Commerce documentation

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	Never expire	Optional, 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`

Why a Credit Exists

Store credits carry no category and no type. Two fields cover it instead:

Field	What it tells you
`originator`	The return, exchange, claim or gift card that issued the credit, or nothing when an admin issued it by hand
`memo`	The free-text reason, written by the refund workflows or by the admin

Store credits do not expire; only gift cards carry an expiry, on their own record. Which credit is spent first is decided by Spree::StoreCredit.oldest_first.

Spree::StoreCreditCategory and Spree::StoreCreditType still exist as deprecated shells for compatibility. Nothing writes them.

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, currency, 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',
  memo: 'Goodwill credit for delayed shipment',
})

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

Listing Store Credits Across Customers

Credits are written per customer, but read across them. The Admin API exposes a read-only list so an integration can answer what the store owes without walking every customer:

const { data: credits, meta } = await client.storeCredits.list({
  outstanding: true,
  expand: ['customer', 'created_by'],
})

// One row per currency, summed over the same filter as the page.
meta.totals.forEach((total) => {
  console.log(total.currency, total.display_amount_remaining)
})

spree api get /store_credits -q 'outstanding=true'

Filters mirror the questions a merchant asks: customer_id, customer_email_cont, currency, created_by_id, memo_cont, a created_at range, and two scopes — outstanding (money still owed versus money spent) and from_gift_card (whether a gift card redemption created it). Each credit’s ledger is its own endpoint:

const { data: events } = await client.storeCredits.events.list('credit_xxx')

spree api get /store_credits/credit_xxx/events

Creating, updating and deleting a credit remain nested under the customer that holds it — a credit without an owner has nobody to pay.

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`
`status`	Current status	`active`
`currency`	Currency code	`USD`
`expires_at`	Optional expiration date	`2025-12-31`

Gift Card Statuses

Status	Description	How it gets there
`active`	Available for redemption	The status a card is created with
`partially_redeemed`	Some value has been redeemed	`Spree::GiftCards::Redeem`, when a balance remains
`redeemed`	Fully redeemed	`Spree::GiftCards::Redeem`, when nothing is left
`canceled`	Voided, and no longer spendable	`Spree::GiftCards::Cancel`

Redemption does not need the caller to choose: Spree::GiftCards::Redeem looks at what is left on the card and marks it partially or fully redeemed accordingly. A card can be partially redeemed more than once, and each spend publishes its own event. Cancelling is refused once a card has been spent against, so cancellation can never take back value a customer has already used.

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

Both are applied before the customer chooses how to pay, and neither appears among the cart’s payment methods. An order uses one or the other, never both. A gift card covers as much of the total as its balance allows and keeps up as the total changes. See the cart & checkout SDK guide for the calls.

Checkout Flow

Store Credit Priority

When a registered customer holds several store credits, the oldest is spent first (Spree::StoreCredit.oldest_first). Store credits do not expire — only gift cards carry an expiry, on their own record.

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

​Overview

​Store Credits

​Store Credit Model

​Store Credit Attributes

​Why a Credit Exists

​Store Credit Events

​Assigning Store Credits

​Listing Store Credits Across Customers

​Store Credit Events

​Gift Cards

​Gift Card Model

​Gift Card Attributes

​Gift Card Statuses

​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

Why a Credit Exists

Store Credit Events

Assigning Store Credits

Listing Store Credits Across Customers

Store Credit Events

Gift Cards

Gift Card Model

Gift Card Attributes

Gift Card Statuses

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