@spree/docs 0.1.231 → 0.1.233

package/dist/api-reference/store.yaml

@@ -15251,6 +15251,34 @@ components:
       required:
       - id
       x-typelizer: true
+    StoreCreditEvent:
+      type: object
+      properties:
+        id:
+          type: string
+        action:
+          type: string
+        authorization_code:
+          type: string
+          nullable: true
+        display_action:
+          type: string
+          nullable: true
+        amount:
+          type: string
+        display_amount:
+          type: string
+        created_at:
+          type: string
+      required:
+      - id
+      - action
+      - authorization_code
+      - display_action
+      - amount
+      - display_amount
+      - created_at
+      x-typelizer: true
     StoreCredit:
       type: object
       properties:

package/dist/developer/core-concepts/store-credits-gift-cards.md

@@ -74,26 +74,22 @@ erDiagram
 | `currency` | Currency code | `USD` |
 | `memo` | Optional note about the credit | `Refund for order #R123` |
 
-### Store Credit Categories
+### Why a Credit Exists
 
-Categories help organize store credits by their purpose:
+Store credits carry no category and no type — both were retired in Spree 6.0
+because neither answered a question anything asked. Two fields cover it
+instead:
 
-| 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 |
+| 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 |
 
-> **INFO:** "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 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`.
 
-### 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) |
+> **NOTE:** `Spree::StoreCreditCategory` and `Spree::StoreCreditType` survive as deprecated
+> shells for one release and are removed in 6.1. Nothing writes them.
 
 ### Store Credit Events
 
@@ -115,7 +111,7 @@ Store credits are managed 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
+5. Enter the amount, currency, and optional memo
 6. Click **Create**
 
 Store credits can also be created via the [Admin API](../../api-reference/admin-api/introduction.md), as a nested resource under the customer:
@@ -132,7 +128,6 @@ const client = createAdminClient({
 const credit = await client.customers.storeCredits.create('cus_xxx', {
   amount: '25.00',
   currency: 'USD',
-  category_id: 'sccat_xxx',
   memo: 'Goodwill credit for delayed shipment',
 })
 ```
@@ -141,12 +136,55 @@ const credit = await client.customers.storeCredits.create('cus_xxx', {
 spree api post /customers/cus_xxx/store_credits -d '{
   "amount": "25.00",
   "currency": "USD",
-  "category_id": "sccat_xxx",
   "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:
+
+
+```typescript Admin SDK
+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)
+})
+```
+
+```bash CLI
+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:
+
+
+```typescript Admin SDK
+const { data: events } = await client.storeCredits.events.list('credit_xxx')
+```
+
+```bash CLI
+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:
@@ -387,10 +425,9 @@ flowchart TB
 
 ### 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
+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.
 
 ## Related Documentation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.231",
+  "version": "0.1.233",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",