Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
[Skip CI] document store credits and gift cards
Damian Legawiecc04f25feba43
diff --git a/docs/developer/core-concepts/payments.mdx b/docs/developer/core-concepts/payments.mdxindex f27b2a3ae2..2f60e62e59 100644--- a/docs/developer/core-concepts/payments.mdx+++ b/docs/developer/core-concepts/payments.mdx@@ -68,8 +68,8 @@ erDiagramPayment ||--o{ LogEntry : "has many"Payment ||--o{ Refund : "has many"PaymentMethod }o--|| Store : "belongs to"- CreditCard }o--|| User : "belongs to"- StoreCredit }o--|| User : "belongs to"+ CreditCard }o--|| Customer : "belongs to"+ StoreCredit }o--|| Customer : "belongs to"Refund }o--|| Payment : "belongs to"Refund }o--|| Reimbursement : "belongs to"```@@ -133,7 +133,7 @@ A `PaymentMethod` can have the following attributes:| `name` | The visible name for this payment method | `Check` || `description`| The description for this payment method | `Pay by check.` || `active` | Whether or not this payment method is active. Set it `false` to hide it in frontend. | `true` |-| `display_on` | Determines where the payment method can be visible. Values can be `front` (Storefr) for Storefront, `back` for Admin Panel only or `both` for both. | `both` |+| `display_on` | Determines where the payment method can be visible. Values can be `front` for Storefront, `back` for Admin Panel only or `both` for both. | `both` || `position` | The position of the payment method in lists. Lower numbers appear first. | `1` |<Info>@@ -175,25 +175,25 @@ The billing address and shipping address data is as follows:### Credit card data-Spree stores only necessary non-sensitive credit card information as a `Spree::CreditClass` record with the following attributes:+Spree stores only necessary non-sensitive credit card information as a `Spree::CreditCard` record with the following attributes:| Attribute | Description | Example Value ||---------------------|-----------------------------------------------------------------------------------------------|------------------------|| `month` | The month the credit card expires. Stored as an integer (1-12). | `6` || `year` | The year the credit card expires. Stored as a four-digit integer (e.g., 2024). | `2024` |-| `cc_type` | The type of credit card (e.g., Visa, MasterCard). | `Visa` |+| `cc_type` | The type of credit card (e.g., visa, mastercard). | `visa` || `last_digits` | The last four digits of the credit card number. | `1234` |-| `name` | The name of the credit card holder as it appears on the card. | John Doe |+| `name` | The name of the credit card holder as it appears on the card. | `John Doe` || `gateway_customer_profile_id` | The customer profile identifier from the payment gateway. Useful for recurring transactions.| `cust_123456789` || `gateway_payment_profile_id` | The payment profile identifier from the payment gateway. | `paym_987654321` |<Note>-We don't store the full credit card number, only the last 4 digits and the card type. This is a security precauation to protect the cardholder's privacy. For any post-purchase operations we authenticate the card using the `gateway_customer_profile_id` and `gateway_payment_profile_id`.+We don't store the full credit card number, only the last 4 digits and the card type. This is a security precaution to protect the cardholder's privacy. For any post-purchase operations we authenticate the card using the `gateway_customer_profile_id` and `gateway_payment_profile_id`.</Note>### Processing Walkthrough-When an order is completed in spree, each `Payment` object associated with the order has the `process!` method called on it unless `payment_required?` for the order returns `false`, in order to attempt to automatically fulfill the payment required for the order. If the payment method requires a source (eg. `Spree::CreditCard`), and the payment has a source associated with it, then Spree will attempt to process the payment. Otherwise, the payment will need to be processed manually.+When an order is completed in Spree, each `Payment` object associated with the order has the `process!` method called on it unless `payment_required?` for the order returns `false`, in order to attempt to automatically fulfill the payment required for the order. If the payment method requires a source (e.g., `Spree::CreditCard`), and the payment has a source associated with it, then Spree will attempt to process the payment. Otherwise, the payment will need to be processed manually.If the `PaymentMethod` object is configured to auto-capture payments, then the `Payment#purchase!` method will be called, which will call `PaymentMethod#purchase` like this:@@ -215,17 +215,26 @@ The returned object from both the `purchase` and `authorize` methods on the paympayment.log_entries```-If the `purchase!` route is taken and is successful, the payment is marked as `completed`. If it fails, it is marked as `failed`. If the `authorize` method is successful, the payment is transitioned to the `pending` state so that it can be manually captured later by calling the `capture!` method. If it is unsuccessful, it is also transitioned to the `failed` state.+If the `purchase!` route is taken and is successful, the payment is marked as `completed`. If it fails, it is marked as `failed`. If the `authorize!` method is successful, the payment is transitioned to the `pending` state so that it can be manually captured later by calling the `capture!` method. If it is unsuccessful, it is also transitioned to the `failed` state.- Once a payment has been saved, it also updates the order. This may trigger the \`payment_state\` to change, which would reflect the current payment state of the order. The possible states are: \* \`balance_due\`: Indicates that payment is required for this order \* \`failed\`: Indicates that the last payment for the order failed \* \`credit_owed\`: This order has been paid for in excess of its total \* \`paid\`: This order has been paid for in full.+Once a payment has been saved, it also updates the order. This may trigger the `payment_state` to change, which would reflect the current payment state of the order. The possible states are:- You may want to keep tabs on the number of orders with a \`payment_state\` of \`failed\`. A sudden increase in the number of such orders could indicate a problem with your credit card gateway and most likely indicates a serious problem affecting customer satisfaction. You should check the latest \`log_entries\` for the most recent payments in the store if this is happening.+| Payment State | Description |+|---------------|-------------|+| `balance_due` | Payment is required for this order |+| `failed` | The last payment for the order failed |+| `credit_owed` | This order has been paid for in excess of its total |+| `paid` | This order has been paid for in full |++<Warning>+You may want to keep tabs on the number of orders with a `payment_state` of `failed`. A sudden increase in the number of such orders could indicate a problem with your credit card gateway and most likely indicates a serious problem affecting customer satisfaction. You should check the latest `log_entries` for the most recent payments in the store if this is happening.+</Warning>### Log EntriesResponses from payment gateways within Spree are typically [ActiveMerchant::Billing::Response](https://github.com/activemerchant/active_merchant/blob/master/lib/active_merchant/billing/response.rb) objects. When Spree handles a response from a payment gateway, it will serialize the object as YAML and store it in the database as a log entry for a payment. These responses can be useful for debugging why a payment has failed.-You can get a list of these log entries by calling the `log_entries` on any `Spree::Payment` object. To get the `Active::Merchant::Billing::Response` out of these `Spree::LogEntry` objects, call the `details` method, eg.+You can get a list of these log entries by calling the `log_entries` on any `Spree::Payment` object. To get the `ActiveMerchant::Billing::Response` out of these `Spree::LogEntry` objects, call the `details` method:```rubypayment.log_entries.first.details@@ -241,8 +250,8 @@ Spree team maintains several payment gateways integrations. All of these gatewayStripe integration, supports all Stripe payment methods, including credit cards, bank transfers, Apple Pay, Google Pay, Klarna, Afterpay, and more. Also supports quick checkout.</Card>-<Card title="Adyen">- We're working on this, stay tuned! If you want to know more, please reach out to us via email at [[email protected]](mailto:[email protected]).+<Card title="Adyen" href="/integrations/payments/adyen" icon="link">+ Adyen integration, supports all Adyen payment methods, including credit cards, bank transfers, Apple Pay, Google Pay, Klarna, and more.</Card><Card title="PayPal" href="/integrations/payments/paypal" icon="link">@@ -284,7 +293,7 @@ With the `spree_gateway` gem included in your application's `Gemfile`, these gatIn order to make your own custom Payment Method show up on the backend list of available payment methods, you need to add it to the spree config list of payment methods first.-Firstly create a new model inheriting from `Spree::PaymentMethod` in your `app/models` directory:+First, create a new model inheriting from `Spree::PaymentMethod` in your `app/models` directory:```rubyclass FancyPaymentMethod < Spree::PaymentMethoddiff --git a/docs/developer/core-concepts/store-credits-gift-cards.mdx b/docs/developer/core-concepts/store-credits-gift-cards.mdxnew file mode 100644index 0000000000..d053402d57--- /dev/null+++ b/docs/developer/core-concepts/store-credits-gift-cards.mdx@@ -0,0 +1,423 @@+---+title: 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++```mermaid+erDiagram+ spree_store_credits ||--o{ spree_store_credit_events : "has many"+ spree_store_credits ||--o{ spree_payments : "source for"+ spree_store_credits }o--|| spree_users : "belongs to"+ spree_store_credits }o--|| spree_stores : "belongs to"+ spree_store_credits }o--o| spree_store_credit_categories : "belongs to"+ spree_store_credits }o--o| spree_store_credit_types : "belongs to"+ spree_store_credits }o--o| spree_admin_users : "created by"++ spree_store_credits {+ bigint id PK+ bigint user_id FK+ bigint store_id FK+ bigint category_id FK+ bigint type_id FK+ bigint created_by_id FK+ decimal amount+ decimal amount_used+ decimal amount_authorized+ string currency+ string memo+ datetime deleted_at+ }++ spree_store_credit_categories {+ bigint id PK+ string name+ }++ spree_store_credit_types {+ bigint id PK+ string name+ integer priority+ }++ spree_store_credit_events {+ bigint id PK+ bigint store_credit_id FK+ string action+ decimal amount+ string authorization_code+ decimal user_total_amount+ bigint originator_id+ string originator_type+ }+```++### 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 |++<Info>+Categories can be configured as non-expiring. By default, the "Gift Card" category is non-expiring.+</Info>++### 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++#### Via Admin Panel++1. Navigate to **Customers** in the Admin Panel+2. Select a customer+3. Go to the **Store Credits** tab+4. Click **Add Store Credit**+5. Enter the amount, category, and optional memo+6. Click **Create**++#### Via Code++```ruby+customer = Spree.user_class.find_by(email: "[email protected]")+store = Spree::Store.default+admin = Spree.admin_user_class.first++store_credit = Spree::StoreCredit.create!(+ user: customer,+ store: store,+ amount: 50.00,+ currency: store.default_currency,+ category: Spree::StoreCreditCategory.first,+ created_by: admin,+ memo: "Loyalty reward"+)+```++### Store Credit Methods++```ruby+store_credit = customer.store_credits.first++# Check remaining balance+store_credit.amount_remaining+# => 75.00++# Check if editable (no amount used or authorized)+store_credit.editable?+# => true++# Get total available store credit for a customer+customer.total_available_store_credit+# => 75.00+```++### 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++```mermaid+erDiagram+ spree_gift_cards }o--|| spree_stores : "belongs to"+ spree_gift_cards }o--o| spree_users : "belongs to"+ spree_gift_cards }o--o| spree_admin_users : "created by"+ spree_gift_cards }o--o| spree_gift_card_batches : "belongs to"+ spree_gift_cards ||--o{ spree_store_credits : "originator for"++ spree_gift_cards {+ bigint id PK+ bigint store_id FK+ bigint user_id FK+ bigint created_by_id FK+ bigint gift_card_batch_id FK+ string code+ string state+ decimal amount+ decimal amount_used+ decimal amount_authorized+ string currency+ datetime expires_at+ datetime redeemed_at+ }++ spree_gift_card_batches {+ bigint id PK+ bigint store_id FK+ bigint created_by_id FK+ string prefix+ integer codes_count+ decimal amount+ string currency+ datetime expires_at+ }+```++### 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++```mermaid+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+```++| State | Description |+|-------|-------------|+| `active` | Available for redemption |+| `partially_redeemed` | Some value has been redeemed |+| `redeemed` | Fully redeemed |+| `canceled` | Canceled by admin |++<Note>+Gift cards can also be `expired` if `expires_at` date has passed and the card hasn't been fully redeemed.+</Note>++### Gift Card Lifecycle++```mermaid+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]+```++### Creating Gift Cards++#### Single Gift Card via Admin Panel++1. Navigate to **Gift Cards** in the Admin Panel+2. Click **Create Gift Card**+3. Enter the amount and optional expiration date+4. Click **Create**+5. Share the generated code with the recipient++#### Single Gift Card via Code++```ruby+store = Spree::Store.default+admin = Spree.admin_user_class.first++gift_card = Spree::GiftCard.create!(+ store: store,+ amount: 50.00,+ created_by: admin,+ expires_at: 1.year.from_now+)++gift_card.code+# => "a1b2c3d4e5f6"+```++### Batch Gift Card Generation++For promotions or bulk distribution, you can create multiple gift cards at once using Gift Card Batches:++#### Via Admin Panel++1. Navigate to **Gift Cards** in the Admin Panel+2. Click **Create Batch**+3. Enter:+ - **Prefix** - Code prefix for easy identification (e.g., `HOLIDAY`)+ - **Count** - Number of cards to generate+ - **Amount** - Value per card+ - **Expiration** - Optional expiration date+4. Click **Create**++#### Via Code++```ruby+store = Spree::Store.default+admin = Spree.admin_user_class.first++batch = Spree::GiftCardBatch.create!(+ store: store,+ prefix: "PROMO",+ codes_count: 100,+ amount: 25.00,+ created_by: admin,+ expires_at: 6.months.from_now+)++# Gift cards are generated automatically+batch.gift_cards.count+# => 100++batch.gift_cards.first.code+# => "promoa1b2c3"+```++<Info>+Large batches are processed in the background via `Spree::GiftCards::BulkGenerateJob` to avoid timeout issues.+</Info>++### 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.++<Info>+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.+</Info>++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++#### Via Storefront API++```bash+# Apply gift card to current order (works for guests and registered customers)+POST /api/v2/storefront/cart/apply_gift_card+{+ "gift_card_code": "abc1234def"+}+```++#### Via Code++```ruby+gift_card = Spree::GiftCard.find_by(code: "abc1234def")+order = Spree::Order.find_by(number: "R123456")++# Apply gift card to order+order.gift_card = gift_card+order.save!+```++### 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++```mermaid+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+```++### Store Credit Priority++When a registered customer has multiple store credits, they are applied in order of priority:++1. **Expiring credits** - Applied first to ensure they're used before expiration+2. **Non-expiring credits** - Applied after expiring credits++## Related Documentation++- [Payments](/developer/core-concepts/payments) - Payment processing and methods+- [Orders](/developer/core-concepts/orders) - Order management+- [Users](/developer/core-concepts/users) - Customer management+- [Events](/developer/core-concepts/events) - Event system and subscribersdiff --git a/docs/docs.json b/docs/docs.jsonindex 6f35b08387..7d346081da 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -108,6 +108,7 @@"developer/core-concepts/products","developer/core-concepts/inventory","developer/core-concepts/payments",+ "developer/core-concepts/store-credits-gift-cards","developer/core-concepts/taxes","developer/core-concepts/promotions","developer/core-concepts/shipments",@@ -1204,6 +1205,7 @@"developer/core-concepts/products","developer/core-concepts/inventory","developer/core-concepts/payments",+ "developer/core-concepts/store-credits-gift-cards","developer/core-concepts/taxes","developer/core-concepts/promotions","developer/core-concepts/shipments",