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
Added new gift card plan
Damian Legawiecda38ba0f69a9
diff --git a/docs/docs.json b/docs/docs.jsonindex 7187fb8fae..9339ef8d6e 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -920,27 +920,6 @@"user/user-quickstart-guide"]},- {- "group": "Migration",- "pages": [- "user/migration/migrate-from-shopify"- ],- "icon": "arrow-right-left"- },- {- "group": "How-to Guides",- "pages": [- "user/how-to/multi-currency-pricing",- "user/how-to/multiple-languages",- "user/how-to/multi-region-pricing",- "user/how-to/wholesale-pricing",- "user/how-to/volume-pricing",- "user/how-to/regional-wholesale",- "user/how-to/regional-volume",- "user/how-to/schedule-sale-pricing"- ],- "icon": "compass"- },{"group": "Products","pages": [@@ -1054,6 +1033,27 @@],"icon": "settings"},+ {+ "group": "How-to Guides",+ "pages": [+ "user/how-to/multi-currency-pricing",+ "user/how-to/multiple-languages",+ "user/how-to/multi-region-pricing",+ "user/how-to/wholesale-pricing",+ "user/how-to/volume-pricing",+ "user/how-to/regional-wholesale",+ "user/how-to/regional-volume",+ "user/how-to/schedule-sale-pricing"+ ],+ "icon": "compass"+ },+ {+ "group": "Migration",+ "pages": [+ "user/migration/migrate-from-shopify"+ ],+ "icon": "arrow-right-left"+ },{"group": "Security","pages": [diff --git a/docs/plans/6.0-6.1-loyalty-gift-cards-store-credits.md b/docs/plans/6.0-6.1-loyalty-gift-cards-store-credits.mdnew file mode 100644index 0000000000..0ad89f6f72--- /dev/null+++ b/docs/plans/6.0-6.1-loyalty-gift-cards-store-credits.md@@ -0,0 +1,146 @@+# Loyalty: Gift Cards, Store Credits and Purchasable Gift Card Products++**Status:** Design finalized — nothing built yet+**Target:** Spree 6.0 (phase 1: Loyalty group, store credit list) · Spree 6.1 (phase 2: purchasable gift card products)+**Depends on:** `6.0-admin-spa.md` (nav registry, resource tables), `6.0-service-workflows.md` (gift card workflows), `6.0-digital-assets.md` (digital delivery profile, no shipment), decisions.md 2026-08-18 (store credits lose category and type)+**Author:** Damian + Claude+**Last updated:** 2026-09-13+**Tracking:** Linear V-3629 · GitHub spree/spree#14629++## Summary++Gift cards are filed under Promotions in the dashboard nav and in the user docs, and store credits are only visible one customer at a time. Neither placement matches what the records are. A promotion is marketing: the merchant gives up margin to change behaviour. A gift card or a store credit is prepaid money the store owes, a balance on the liability side of the books that happens to reduce an order total at checkout. Every platform we compare against keeps the two apart, and so does our own data model (balances, redemption statuses, a ledger of events, and no rules or actions). This plan gives the stored-value records their own top-level **Loyalty** group holding Gift Cards and a new cross-customer **Store Credits** list, backed by a read-only admin endpoint, so a merchant can answer "how much do we owe, to whom, and why" without opening every customer. Phase 2 closes the gap every other platform already covers: a gift card as a **product a shopper can buy**, issued and emailed to a recipient when the order is paid.++## Key Decisions (do not deviate without discussion)++- **Gift cards are not promotions.** They leave the Promotions group in the nav, in the dashboard routes and in the docs. Promotions keeps the discount machinery (rules, actions, coupon codes) and nothing else.+- **The group is named Loyalty**, not "Gift Cards & Credits". It ships with two real children on day one (Gift Cards, Store Credits) and is the home for a rewards or points programme later. A merchant opening it finds stored value, which is what every loyalty mechanism spends. Precedent: the hosted-platform competitor set bundles gift cards and store credit under the same word.+- **Store credits get a cross-customer list, read-only at the top level.** `GET /api/v3/admin/store_credits` and `GET /api/v3/admin/store_credits/:id` list and show across customers. Creating, editing and deleting a credit stay nested under the customer, where they are today. A credit always belongs to one customer; the list is for seeing, filtering and auditing, the way the inventory index shows stock across products while stock is still edited per product.+- **The permission keys do not change; their group does.** `gift_cards` and `store_credits` move from the `orders` permission group to a new `loyalty` group so the role sheet mirrors the nav. Key names stay, so existing roles keep working (a role holds the keys it was created with and is never re-read, see decisions.md 2026-09-09).+- **A purchasable gift card is a product with a flag, priced by its variants.** Each variant is a denomination and its price is the card's face value. The flag is what switches off everything that does not apply to prepaid money: inventory tracking, sales tax, promotions, shipping, and paying with another balance.+- **A card is issued when the order is paid, one per unit, by a workflow.** Not at checkout completion: an order placed with a pending offline payment has not been paid for, and issuing a spendable code for it would hand out money the store has not received. `Spree::GiftCards::IssueFromOrder` runs on `order.paid` and is idempotent.+- **One gift card per order stays in 6.1.** The `gift_card_id` column on carts and orders is not replaced by a join table in this plan. Buying a gift card product needs no change to how cards are redeemed. Lifting the limit is a separate question with its own plan.+- **2026-09-13: Phase 1 ships in 6.0, before the dashboard's first release.** The `/promotions/gift-cards` route and the docs URLs under `user/promotions/` have never been public, so they move without a redirect and the docs are restructured once. Accepted cost: more on the 6.0 list.+- **2026-09-13: The outstanding balance is `meta.totals` on the filtered list.** One grouped sum per currency, computed over the same scope as the page, so a customer filter shows that customer's balance and no filter shows the store's liability. Rejected: a separate balances resource (a second request that cannot follow the filters) and waiting for Reports (the list would answer "who" but not "how much"). Accepted cost: one aggregate query per list request and a `totals` member on the list meta that the SDK types carry.+- **2026-09-13: The gift card marker is a boolean on the product.** `spree_products.gift_card`, one predicate for tax, promotions, inventory, shipping and balance-payment rules; every variant of such a product is a denomination. Rejected: a `kind` on the product type (types are optional, so every check becomes a nil-safe chain and a merchant must create a type first) and a variant-level flag (moves every per-product rule to the variant and no compared platform does it). Accepted cost: one product cannot mix gift card and physical variants.+- **2026-09-13: Recipient details get their own table.** `spree_gift_card_recipients`, one row per gift card line item, validated and queryable, with the cart items endpoint taking a nested `recipient` object. Rejected: four nullable columns on `spree_line_items` (empty on every ordinary line of the hottest commerce table) and line item `metadata` (no validation, no index, merchant data and system data in one bag).++## Design Details++### Phase 1a: the Loyalty group++**Dashboard nav** (`packages/dashboard/src/nav/default.ts`). A new top-level entry:++```ts+nav.add({+ key: 'loyalty',+ labelKey: 'admin.nav.loyalty',+ path: '/loyalty/gift-cards',+ icon: GiftIcon,+ subject: Subject.GiftCard,+ position: 475, // after Sellers (450), before Promotions (500)+ children: [+ { key: 'loyalty.gift-cards', labelKey: 'admin.nav.gift_cards', path: '/loyalty/gift-cards', subject: Subject.GiftCard, position: 100 },+ { key: 'loyalty.store-credits', labelKey: 'admin.nav.store_credits', path: '/loyalty/store-credits', subject: Subject.StoreCredit, position: 200 },+ ],+})+```++The `promotions` entry loses its only child. The group's own visibility follows the usual rule: it shows when the staff member may read either child.++**Routes.** `routes/_authenticated/$storeId/promotions/gift-cards.tsx` moves to `routes/_authenticated/$storeId/loyalty/gift-cards.tsx`. No redirect: the old path has never shipped. The global search's create action for gift cards and every in-app link follow the move. `Subject.StoreCredit` joins the subject map in `@spree/dashboard-core`.++**Translations.** `admin.nav.loyalty` and `admin.nav.store_credits` in every locale file of `packages/dashboard` (en, de, fr, pl, ar, zh-CN).++**Permissions.** In `Spree::Core::PermissionConfiguration`, `gift_cards` and `store_credits` register with `group: :loyalty`. The group is presentation only (it drives the role sheet sections); the keys and their subjects are unchanged.++**Docs.** The User Guide gets a **Loyalty** group between Customers and Promotions holding `user/loyalty/gift-cards` (moved from `user/promotions/`), `user/loyalty/issue-gift-card` and `user/loyalty/store-credits` (moved from `user/customers/`), plus a new page for the store credits list. The moved pages get `redirects` entries in `docs.json` because the docs site is already live for 6.0 previews. The developer page `developer/core-concepts/store-credits-gift-cards` stays where it is and gains a short section on the admin list endpoint. The `v5` tree is untouched.++### Phase 1b: the store credit list++**Admin API.** `Spree::Api::V3::Admin::StoreCreditsController < ResourceController`, `scoped_resource :store_credits`, routed `only: [:index, :show]`. Scope is `current_store.store_credits`. `collection_includes` preloads `customer`, `created_by` and `originator`. The nested `Customers::StoreCreditsController` is unchanged and remains the only write path.++Filters are Ransack on the model, extended on `Spree::StoreCredit`:++| Filter | Why a merchant asks |+| --- | --- |+| `customer_id`, `customer_email_cont` | who holds credit |+| `currency` | the books are per currency |+| `created_by_id` | who issued it |+| `originator_type`, `originator_id` | why it exists: return, exchange, claim, gift card, or manual (no originator) |+| `created_at` range | when it was issued |+| `memo_cont` | the free-text reason |+| scopes `available`, `exhausted`, `with_gift_card`, `without_gift_card` | what is still owed versus spent |++The admin serializer gains `amount_authorized`, `display_amount_authorized`, `originator_type` (the polymorphic shorthand, via `Spree::Base.polymorphic_api_type`) and `originator_id` (prefixed). Typelizer, Zod and OpenAPI regenerate from that.++**Outstanding balance.** The list's `meta` carries `totals`: one row per currency with `amount`, `amount_used`, `amount_authorized` and `amount_remaining`, computed over the **filtered** scope with a grouped SQL sum. Filtering by a customer therefore shows that customer's balance; the unfiltered list shows the store's liability. The dashboard renders the totals above the table.++**Ledger.** `GET /api/v3/admin/store_credits/:store_credit_id/events` lists the credit's `Spree::StoreCreditEvent` rows (action, amount, authorization code, originator, date) so the drill-in shows how a balance got to where it is. Read-only, gated by the `store_credits` key.++**Dashboard.** `routes/_authenticated/$storeId/loyalty/store-credits.tsx` renders a `ResourceTable` registered in `tables/store-credits.tsx` with columns customer (link to the profile), amount, remaining, currency, origin (return/exchange/claim/gift card/manual, linking to the originator where it has a page), issued by, memo, created. Filters match the table above. A row opens a sheet with the credit's details and its ledger. The sheet has no create form; "Issue store credit" stays on the customer profile and the empty state links there. SDK: `adminClient.storeCredits.list`, `.get`, `.events.list`; hook `use-store-credits.ts`.++### Phase 2: purchasable gift card products (6.1)++**Catalog.** `spree_products.gift_card` boolean, `null: false, default: false`, exposed on the store and admin product serializers and writable on the admin products controller. A gift card product:++- has its variants as denominations (the variant price is the face value in the variant's currency); option type "Amount" is the convention, not a requirement;+- does not track inventory (`track_inventory` forced false on its variants);+- is not taxable (no tax category; a gift card sale is a prepayment, the tax is due on what the card later buys);+- is excluded from promotions (`promotionable` forced false; the existing eligibility check in `Spree::Promotion` already honours it) and from price lists;+- uses a digital delivery profile, so it never creates a shipment;+- cannot be paid for with a gift card or store credit (prevents turning one balance into another); `Spree::GiftCards::Apply` and the store credit payment path refuse a purchase containing a gift card product;+- on a marketplace belongs to the operator only; a seller cannot create one.++The dashboard product form shows a "This product is a gift card" switch that hides the inventory, tax and shipping sections when on.++**Recipient.** A new table `spree_gift_card_recipients`, one row per line item that is a gift card purchase: `line_item_id`, `email` (required), `name`, `message`, `send_at` (optional, store time zone), `store_id`. Kept off `spree_line_items` because recipient details exist for gift card lines only, and off `metadata` because they are validated, emailed and queried. The store cart items endpoint accepts `recipient: { email, name, message, send_at }` when the variant's product is a gift card and rejects it otherwise.++**Issuance.** `Spree::GiftCards::IssueFromOrder` runs from an `order.paid` subscriber. For each gift card line item it issues `quantity` cards: `amount` = variant price, `currency` = order currency, `expires_at` from a store preference (`gift_card_default_validity_days`, nil for never), `customer` nil (the code is the bearer instrument; restricting a card to a customer remains a manual admin action), `created_by` nil. Each card records `line_item_id` so the order page lists what it issued and a cancellation can find them. The workflow is idempotent: a line item that already has its cards issues nothing. `gift_card.issued` events carry the recipient so `spree_emails` (and any webhook consumer) can send the code; the buyer's confirmation shows the cards masked, never the full code.++**Cancellation and refunds.** `Spree::Orders::Cancel` cancels unused cards issued by the order through the existing cancel workflow. A card that has been partly or fully redeemed blocks a refund to the original payment for that line; the admin is offered a store credit refund instead.++**Store API and storefront.** Product and variant serializers expose `gift_card`. Cart items accept the recipient. The storefront's product page renders a denomination picker plus recipient fields for `gift_card` products. The customer account page lists cards the customer bought and cards assigned to them.++## Migration Path++**Phase 1 (6.0, before release)**++1. Add `Subject.StoreCredit`; add the `loyalty` nav group; move the gift cards route; translations in all six locales.+2. Move `gift_cards` and `store_credits` to the `loyalty` permission group.+3. Extend `Spree::StoreCredit` Ransack allowlists; add the admin store credits index/show controller, the events endpoint, the `meta.totals` aggregate; serializer fields; regenerate types, Zod and OpenAPI.+4. Admin SDK methods, `use-store-credits` hook, `tables/store-credits.tsx`, the route and the detail sheet.+5. Docs: Loyalty group in the User Guide, moved pages with redirects, the new store credits list page, the developer page section.++**Phase 2 (6.1)**++6. Migration: `spree_products.gift_card`, `spree_gift_card_recipients`, `spree_gift_cards.line_item_id`. Product model rules for the flag; admin and store serializers and controllers.+7. Store cart items recipient payload; `Spree::GiftCards::IssueFromOrder` with its `order.paid` subscriber; `gift_card.issued` event serializer; cancellation hook.+8. `spree_emails` gift card mailer; dashboard product form switch and order page issued-cards card; storefront product page and account page.+9. Docs: user guide page "Selling gift cards", developer page update, OpenAPI.++## Constraints on Current Work++- Do not add anything new under the Promotions nav group or docs group unless it is a discount mechanism. Stored value (gift cards, credits, future points) goes to Loyalty.+- Do not link to `/promotions/gift-cards` in new dashboard code; use the route constant for the gift cards page so the move is one edit.+- New writes to store credits stay nested under the customer. Do not add a top-level create.+- Any new field on `Spree::StoreCredit` or `Spree::GiftCard` that a merchant would filter on must be added to the Ransack allowlist and the list's filter panel in the same change.+- Product-level behaviour that should not apply to prepaid money (tax, promotions, inventory, shipping) must check a single predicate on the product, so phase 2 can flip it in one place. Do not introduce a second "digital-only" or "non-physical" flag that would have to be reconciled with `gift_card`.+- Gift card codes never appear in events, logs or the buyer-facing order payload. Only the recipient email carries the code.++## Open Questions++The four design questions (phase 1 target, balance totals shape, gift card marker, recipient storage) were settled on 2026-09-13 and live in Key Decisions. Deferred, each with what would unblock it:++- **Several gift cards on one order.** Deliberately out of scope here. Unblocked by a plan of its own once phase 2 has shipped and there is demand from merchants who sell cards in small denominations.+- **Open-value gift cards** (the shopper types the amount). Unblocked by a decision on how a variant without a fixed price is represented; until then denominations are variants.+- **A rewards or points programme under Loyalty.** Unblocked by its own plan; this one only reserves the group.++## References++- `docs/plans/6.0-admin-spa.md` (nav registry, resource tables)+- `docs/plans/6.0-service-workflows.md` (gift card apply, redeem, cancel workflows)+- `docs/plans/6.0-digital-assets.md` (digital delivery profile)+- `docs/plans/decisions.md` 2026-08-18 "Store credits lose their category and type", 2026-09-09 (permission keys are never re-read)+- `docs/developer/core-concepts/store-credits-gift-cards.mdx`+- Competitor survey (2026-09-13, session notes): every compared platform sells gift cards as a product and none files them under discounts; the two that ship store credit pair it with gift cards.diff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex b5aa1f406d..16945c5972 100644--- a/docs/plans/decisions.md+++ b/docs/plans/decisions.md@@ -5415,3 +5415,38 @@ seller ledger endpoints authorize `:seller_earnings` and root inaudience; and a new `q[<column>_eq]` filter on either ledger model needs thatcolumn in `whitelisted_ransackable_attributes` — a whitelisted associationname does not make its foreign key filterable.++## 2026-09-13 — Stored value is not a promotion: gift cards and store credits live under Loyalty++Plan: `6.0-6.1-loyalty-gift-cards-store-credits.md`.++Gift cards sat under Promotions in the dashboard nav and in the user docs+because both reduce an order total at checkout. That is where the likeness+ends. A promotion is marketing: margin given up to change behaviour. A gift+card or a store credit is prepaid money the store owes, a liability with a+balance, redemption statuses and a ledger, and no rules or actions. Every+platform in the comparison keeps the two apart; so does our model.++**Decision.** A top-level **Loyalty** group holds Gift Cards and a new+cross-customer Store Credits list, and is the home for any rewards or points+programme later. Promotions keeps only the discount machinery. The+`gift_cards` and `store_credits` permission keys move to a `loyalty` group;+the key names do not change, so existing roles keep working.++**Store credits are edited per customer and listed across customers.**+`GET /admin/store_credits` (index, show) is read-only; create, update and+destroy stay nested under `/customers/:id/store_credits`. The list carries+`meta.totals`, one grouped sum per currency over the filtered scope, so the+same list answers "this customer's balance" and "the store's liability"+depending on the filter. A separate balances resource was rejected because it+could not follow the filters; waiting for Reports was rejected because the+list would then answer "who" but not "how much".++**Consequences for other work.** Anything that should not apply to prepaid+money (tax, promotions, inventory, shipping, paying a balance with a balance)+must check one predicate on the product, `gift_card?`, which phase 2 adds as+a boolean on `spree_products`. Do not introduce a second "non-physical" flag+that would need reconciling with it. Gift card codes never appear in events,+logs or the buyer's order payload; only the recipient email carries the code.+Recipient details get their own table rather than columns on+`spree_line_items` or keys in `metadata`.diff --git a/docs/user/what-is-spree-commerce.mdx b/docs/user/what-is-spree-commerce.mdxindex 8283856560..8c8b6d8889 100644--- a/docs/user/what-is-spree-commerce.mdx+++ b/docs/user/what-is-spree-commerce.mdx@@ -15,24 +15,6 @@ If SaaS solutions don't give you the control and flexibility your business needsSpree is trusted by thousands of businesses around the world, including GoDaddy, Huckberry, Craftsman, DieHard, Kenmore, Paccar, Maisonette, Goop, Garmentory, and Blue Bottle Coffee.-Spree comes in two flavors - as a free Community Edition or as a paid Enterprise Edition.--## Community Edition vs Enterprise Edition--<CardGroup cols={2}>- <Card title="Community Edition" href="https://github.com/spree/spree/">- Spree Community Edition is free. It's the DIY version of Spree. It comes with community support only.- </Card>-- <Card title="Enterprise Edition" href="https://spreecommerce.org/enterprise/">- Spree Enterprise Edition comes with more features, more security, more integrations and enterprise support.- </Card>-</CardGroup>--TL;DR The Community Edition gives you freedom. The Enterprise Edition saves you time.--So what sets both versions apart? Here's a [feature comparison](https://spreecommerce.org/enterprise/) of the two editions and here's an [in-depth overview](https://spreecommerce.org/spree-commerce-version-comparison-community-edition-vs-enterprise-edition/).-## Looking for Developer Documentation?This Spree user documentation is intended for business owners and site administrators of Spree e-commerce sites. Everything you need to know to configure and manage your Spree store can be found here.@@ -47,6 +29,6 @@ Thank you for supporting Spree open-source! <Icon icon="heart" iconType="solid"To join the Spree Community and over 6000+ Spree users and developers, please join our [Discord](https://discord.spreecommerce.org/)-## Contact us+## Contacting us-If you'd like to get in touch to share your feedback, request features, or start a new project, please fill out this contact form: [https://spreecommerce.org/get-started/](https://spreecommerce.org/get-started/)+If you'd like to get in touch to share your feedback, request features, or start a new project, please fill out the [Contact form](https://spreecommerce.org/get-started/)