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
Documented seller digital asset management
Damian Legawiec85317920957d
diff --git a/docs/developer/how-to/sell-digital-products.mdx b/docs/developer/how-to/sell-digital-products.mdxindex 814e28fb0b..fe27b67f28 100644--- a/docs/developer/how-to/sell-digital-products.mdx+++ b/docs/developer/how-to/sell-digital-products.mdx@@ -56,6 +56,35 @@ await adminClient.products.digitalAssets.create('prod_86Rf07xd4z', { signed_id }Leave `authorized_clicks` and `authorized_days` off to inherit the store's download limits, or set them per file to mix evergreen downloads with time-limited ones. See [the allowance](/developer/core-concepts/products#downloading-and-the-allowance) for how the limits resolve.+### On a marketplace++A [seller](/developer/core-concepts/sellers) attaches files to their own products the same way, from the **Digital files** card on the product page in their seller panel, or through the Seller API. They can upload, replace and delete files and set per-file download limits. A product belonging to another seller answers `404`.++Sellers upload files only. A [custom digital asset provider](/developer/how-to/custom-digital-asset-provider) is your own integration, so sellers cannot pick one. A file you attached with a provider still appears on the seller's product, without its provider settings.++<Tabs>+ <Tab title="Seller SDK">+ ```typescript+ const { signed_id } = await sellerClient.files.upload(file, { visibility: 'private' })++ await sellerClient.products.digitalAssets.create('prod_86Rf07xd4z', {+ signed_id,+ authorized_clicks: 5,+ authorized_days: 30,+ })+ ```+ </Tab>+ <Tab title="cURL">+ ```bash+ curl -X POST https://your-store.com/api/v3/seller/products/prod_86Rf07xd4z/digital_assets \+ -H "Authorization: Bearer <seller_jwt>" \+ -H "X-Spree-Seller-Id: sel_UkLWZg9DAJ" \+ -H "Content-Type: application/json" \+ -d '{ "signed_id": "<signed_id>", "authorized_clicks": 5, "authorized_days": 30 }'+ ```+ </Tab>+</Tabs>+<Tip>You can attach a file to a **physical** variant too — a manual or warranty PDF that ships alongside the goods. Carrying files and being digital are independent: the physical variant still needs an address, and it also grants a download link.</Tip>diff --git a/docs/plans/6.0-digital-assets.md b/docs/plans/6.0-digital-assets.mdindex ee270df47f..9e1f73caab 100644--- a/docs/plans/6.0-digital-assets.md+++ b/docs/plans/6.0-digital-assets.md@@ -4,7 +4,7 @@**Target:** Spree 6.0**Depends on:** `6.0-fulfillment-and-delivery.md` (Digital fulfillment provider, shipped), `6.0-admin-api.md` (endpoint conventions), `6.0-admin-spa.md` (dashboard architecture), `6.0-admin-rbac.md` (permission catalog), `6.0-store-scoped-configuration.md` (preference conventions)**Author:** Damian Legawiec-**Last updated:** 2026-08-27+**Last updated:** 2026-10-24## Summary@@ -38,6 +38,14 @@ Spree ships a complete digital products engine in core: `Spree::Digital` (a file- **Link-per-unit, resolve on download** (2026-08-12). Order completion still creates one `DigitalLink` per unit (the `FulfillmentProvider::Digital` code is unchanged); the provider is called only when the customer actually downloads. No `on_fulfillment` provider hook — that would add a second entry point whose failure lands *after* money is taken (a support incident, not a clean error). A provider that needs to pre-reserve a key does so on first authorized download. Accepted cost: for consumable keys, a link exists before a key is reserved; reservation happens at first download, which suits typical licensing flows.- **A provider failure must refuse, not 500, and must not spend the click.** The 6.0 controller already settles every refusal before `authorize!` increments the counter; wave 6 extends that so a provider exception is caught and returns the same 403 as an expired link, leaving the customer's allowance intact.+### Seller panel (decided 2026-10-24, GitHub #14965)++- **Sellers manage the files on their own products.** The Seller API mirrors the operator's nested endpoint under `/api/v3/seller/products/:product_id/digital_assets`, rooted in the seller's own catalog, so any other product is a 404. Changing files is a change to the product, so writes need `:update` on it.+- **Uploads only, no providers.** A provider is the operator's integration into their own systems; a seller can neither choose one nor read its settings. An operator-created provider asset on a seller's product is still listed.+- **Per-file download limits are the seller's to set**, with the same fallback to the store's settings.+- **Edit page only.** The card needs a saved product; attaching files on the seller's new-product form is deferred until requested.+- **One card for both panels.** The Digital files card lives in `@spree/dashboard-core` and talks through the registered panel client; the admin registers `providers`, the seller panel does not, and the card hides the provider menu.+### Wave 7 — license-code pools (design finalized 2026-08-12; deferred to 6.1)- **A license pool is its own wave, and open source** (2026-08-12). Selling a finite batch of codes (game keys, gift cards) is the common merchant case that needs *no* external system — the opposite of wave 6. It is built as a `LicensePool` provider on the wave-6 seam, so it reuses `deliver` / `DigitalDelivery` whole, but it is a real stateful feature: a `Spree::LicenseCode` table, reservation logic, CSV import, and admin. Ships in core, unlike the wave-6 licensing provider.@@ -196,6 +204,8 @@ Step numbers continue the shipped sequence; the design **waves** map to steps as8. **License-code pools** — **deferred to 6.1, open source**: `spree_license_codes` migration (value / attachment / nullable `digital_link_id`); the `LicensePool` provider (claim-once-pin-to-link, text or image); the `LicenseCodesRowProcessor` on the existing `Spree::Import` pipeline; the stock sync (`count_on_hand` ← `codes.available.count`, transactional on import + redeem) wired through `Stock::Quantifier`; admin (codes-remaining, import action, per-code list); docs. Builds on wave 6's provider seam, so it lands after it, in order: `LicenseCode` model + migration → `LicensePool` provider + the pin-then-reshow flow → stock sync → CSV import → admin → docs. The stock sync lands with its own test battery — it is the piece most able to drift.+9. **Seller panel management** — **in progress 2026-10-24** (GitHub #14965): Seller API nested endpoint, Seller SDK resource, the Digital files card moved to `@spree/dashboard-core` and mounted on the seller product page, a shared request shape and serializer fields for both branches.+## Constraints on Current Work- New code (including the admin API and dashboard work on this branch) uses `Spree::DigitalAsset` and `digital_assets` association names only; the legacy names are for the bridge layer.@@ -203,6 +213,7 @@ Step numbers continue the shipped sequence; the design **waves** map to steps as- The per-asset fallback is the only sanctioned fallback: never add a chain through global `Spree::Config`, and new digital behavior settings are born on Store (or the asset), never global.- Do not build a per-download log table, PDF stamping, or streaming features ad hoc — the `digital_link.downloaded` event is the extension point until a real need arrives.- Wave 7: keep a pool variant's `count_on_hand` and its unredeemed-code count in sync **transactionally** — import and redeem both write both, in one transaction. A drift silently blocks sellable stock or permits an oversell. Never compute one from the other lazily at read time in the checkout path.+- The seller branch never accepts `provider_type` or `provider_settings` and never serializes `provider_settings`; a provider stays the operator's own integration.- Do not assume `DigitalAsset#attachment` is present anywhere outside the model — a provider-backed asset has none. Reach for `deliver` / `downloadable?`, never `attachment` directly. (The 6.0 model already followed this; wave 6 is why it mattered.)- Wave 6 download-flow code treats the deliverable as opaque (a `DigitalDelivery` — URL or inline value), never as a storage URL. A digital-asset provider owns its own configuration (it is host-app glue into internal software) — do NOT add an `Integration` FK or credential surface to `DigitalAsset`. This deliberately differs from delivery-rate/tax providers, which connect to marketplace services; see the wave 6 decision.- Emailed download URLs are long-lived customer-facing artifacts: any route change must keep old URLs working for at least one release.diff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex 11c7be0b14..6af172b64e 100644--- a/docs/plans/decisions.md+++ b/docs/plans/decisions.md@@ -1,3 +1,13 @@+## 2026-10-24: Sellers manage the downloadable files on their own products, uploads only++**Context:** A marketplace seller could list a digital product, but only the operator could attach the file it delivers (GitHub #14965). The Seller API had a file upload endpoint and nothing to attach the upload to a product.++**Decision:** The Seller API gains `/api/v3/seller/products/:product_id/digital_assets` (index, show, create, update, destroy), rooted in `current_seller.products`, so another seller's or the marketplace's own product is a `404`. Writes need `:update` on the product, so a read-only seller role can list files but not change them. Sellers upload files and may set the per-file download limits. They cannot pick a digital asset provider and never see provider settings: a provider is the operator's own integration into internal systems, and letting a seller choose one would route the seller's sales through it. Files are added from the product's edit page only, not while creating a product. The admin and seller endpoints share their write logic, their request shape and their serialized fields, and both panels render one Digital files card from `@spree/dashboard-core`.++**Consequences:** An asset the operator created with a provider still appears on the seller's product, and the seller may change its limits or delete it. Opening providers to sellers later means adding them to the seller request shape and registering `providers` on the seller panel's client; nothing else changes. Pre-save file attachment on the seller's new product form remains open until a seller asks for it.++**Plan amended:** `6.0-digital-assets.md` (Seller panel decisions, Migration Path step 9).+## 2026-10-19: A self-service data request is confirmed from its email address before Spree acts on it**Context:** A customer's own access or erasure request covers the guest orders, carts, cards and consent recorded at the account's email address, so that someone who checked out as a guest and registered later receives their whole history. Spree never confirms that an account's email address belongs to the account holder, so a request should not reach rows at that address until the address itself confirms it.