Store Credits & Gift Cards

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
    }

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

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
        date expires_at
        datetime redeemed_at
    }

    GiftCardBatch {
        string prefix
        integer codes_count
        decimal amount
        string currency
        date expires_at
    }

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

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]

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

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

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

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