@spree/docs 0.1.193 → 0.1.195

package/dist/developer/core-concepts/catalogs.md

@@ -20,10 +20,8 @@ flowchart LR
 erDiagram
     Catalog ||--o{ CatalogProduct : "assortment"
     Catalog ||--o{ CatalogAssignment : "audiences"
-    Catalog }o--o| PriceList : "optional pricing"
-    CatalogAssignment }o--|| Channel : "one of"
+    Catalog ||--o| PriceList : "owns (optional)"
     CatalogAssignment }o--|| CustomerGroup : "one of"
-    CatalogAssignment }o--|| Market : "one of"
     CatalogAssignment }o--|| Company : "one of"
 
     Catalog {
@@ -60,6 +58,8 @@ const catalog = await adminClient.catalogs.create({
 
 The price list is optional. A catalog with an assortment and no price list restricts the range at normal prices; a catalog with a price list and no assortment adjusts prices without hiding anything.
 
+A price list is either **standalone** (matched by its own rules) or **owned by exactly one catalog** — attaching a list a catalog already claims moves it. Detaching (`price_list_id: null`) is an explicit act with a real consequence: a released list starts matching by its own rules again, and a rule-less one matches everyone.
+
 ### Filling the assortment
 
 ```typescript Admin SDK
@@ -71,7 +71,7 @@ const { data: products } = await adminClient.catalogs.products.list(catalog.id)
 await adminClient.catalogs.products.delete(catalog.id, 'prod_xxx')
 ```
 
-Products are positioned, so a catalog also controls the order they're presented in.
+Membership is all a catalog holds — it decides *what* a buyer sees, never the order they see it in. Presentation order stays with categories and collections.
 
 When a catalog should restrict to exactly what its price list covers, there's a shortcut that copies those products in rather than making someone add them by hand:
 
@@ -81,15 +81,15 @@ const { added_count } = await adminClient.catalogs.importProducts(catalog.id)
 
 ## Choosing the audience
 
-A catalog is assigned to one of four things:
+A catalog is assigned to a buyer audience:
 
 | Assign to | Meaning |
 |---|---|
-| **[Channel](channels.md)** | Everyone buying through this channel — an app, a retail till |
 | **[Customer group](customers.md)** | A segment — wholesale accounts, staff, a loyalty tier |
-| **[Market](markets.md)** | Everyone in a region |
 | **[Company](companies.md)** | One B2B organization |
 
+A [Channel](channels.md) is not assigned — it names its catalog directly via `default_catalog_id`, which applies to everyone buying through it when nothing narrower does.
+
 ```typescript Admin SDK
 await adminClient.catalogs.assign(catalog.id, {
   assignable_type: 'customer_group',
@@ -128,9 +128,9 @@ Prices are checked in order, and the first match wins:
 
 Nearest-first is what lets a subsidiary hold a better-negotiated rate than the group's, without disturbing anyone else.
 
-> **WARNING:** A price list attached to a catalog applies **because the catalog applies** — its own rules are not consulted, and it's excluded from ordinary rule matching.
+> **WARNING:** A price list owned by a catalog applies **because the catalog applies** — its own rules are not consulted, and it's excluded from ordinary rule matching.
 > 
-> That exclusion is load-bearing: a price list with no rules would otherwise match everyone, and one company's negotiated pricing would leak to the entire storefront.
+> That exclusion is load-bearing: a price list with no rules would otherwise match everyone, and one company's negotiated pricing would leak to the entire storefront. It also means a deactivated catalog's list goes **dormant** — turning the catalog off never releases its pricing to the whole store. Only explicitly detaching the list puts it back into rule matching.
 
 ## Related
 

package/dist/developer/core-concepts/pricing.md

@@ -142,7 +142,7 @@ const priceList = await client.priceLists.create({
   name: 'EU wholesale',
   match_policy: 'all',
   rules: [
-    { type: 'customer_group_rule', preferences: { customer_group_ids: ['cg_xxx'] } },
+    { type: 'market_rule', preferences: { market_ids: ['mkt_xxx'] } },
   ],
   prices: [
     { variant_id: 'variant_xxx', currency: 'EUR', amount: '19.99' },
@@ -165,16 +165,18 @@ spree api patch /price_lists/pl_xxx/activate
 
 ## Price Rules
 
-Price Rules define conditions that must be met for a Price List to apply. Spree includes five built-in rule types:
+Price Rules define conditions that must be met for a Price List to apply. Rules describe the *context* of a purchase — where, through what, how much:
 
 | Rule | Description | Use Case |
 |------|-------------|----------|
 | **Market Rule** | Matches based on the current [Market](markets.md) | Regional pricing across markets |
 | **Channel Rule** | Matches based on the [Channel](channels.md) the customer is buying through | App-only or in-store pricing |
-| **User Rule** | Matches specific customer accounts | VIP customers, wholesale accounts |
-| **Customer Group Rule** | Matches members of customer groups | Loyalty tiers, membership pricing |
 | **Volume Rule** | Matches based on quantity purchased | Bulk discounts, tiered pricing |
 
+*Who* gets a price list is not a rule — it's a [Catalog](catalogs.md): attach the list to a catalog assigned to the customer groups or companies it's for.
+
+> **NOTE:** The **User Rule** and **Customer Group Rule** kinds still work and are not going away, but they're no longer offered when adding a rule — targeting an audience through a catalog is the one way to do it now. Nothing needs migrating; rules you already have keep matching exactly as before.
+
 ### Market Rule
 
 Regional pricing. Applies the Price List when the customer is in one of the specified markets.
@@ -183,15 +185,7 @@ Regional pricing. Applies the Price List when the customer is in one of the spec
 
 ### Channel Rule
 
-Applies when the customer is buying through a particular sales channel — a discount that exists only in the mobile app, or a price that only applies at a retail till.
-
-### User Rule
-
-Limits the Price List to specific customer accounts. Useful for VIP customers, employee pricing, or wholesale accounts.
-
-### Customer Group Rule
-
-Applies to members of specific customer groups. Useful for wholesale tiers, loyalty programs, or membership-based pricing.
+Applies when the customer is buying through a particular sales channel — a discount that exists only in the mobile app, or a price that only applies at a retail till. For new setups, prefer giving the channel a default [Catalog](catalogs.md) that owns the price list — that is where channel-wide commercial terms live going forward.
 
 ### Volume Rule
 
@@ -214,7 +208,7 @@ When resolving prices, Spree considers the full context of the request:
 | Currency | Market or request header | The currency to price in |
 | Market | Customer's country | The [Market](markets.md) for market-based rules |
 | Channel | The API credential in use | The [Channel](channels.md) for channel-based rules |
-| Customer | Authentication | The signed-in customer for user-based rules |
+| Customer | Authentication | The signed-in customer, for resolving their [Catalogs](catalogs.md) |
 | Quantity | Cart line item | The quantity for volume-based rules |
 | Date | Current time | For time-based Price List scheduling |
 

package/dist/developer/core-concepts/products.md

@@ -716,6 +716,115 @@ The API automatically returns the correct price based on the current currency an
 
 See the [Pricing](pricing.md) guide for details on Price Lists, Price Rules, and market-specific pricing.
 
+## Digital products
+
+**A digital product is an ordinary product whose variant delivers without shipping — its [delivery profile](fulfillments.md) is a digital one, so buying it grants the customer a download instead of dispatching a parcel.** Nothing about the catalog model changes — you still have a product, its variants, and its prices. What that variant hands over is usually a **digital asset** it carries (an e‑book, a design file) or a value a provider mints on demand (a license key) — but the file is the optional deliverable, not what makes the product digital.
+
+Two ideas are worth separating up front, because they are independent:
+
+- **Being digital** is a delivery decision. A variant is digital when its [delivery profile](fulfillments.md) is a digital one — that variant needs no shipping address, and a cart made up entirely of digital variants skips the delivery step at checkout.
+- **Carrying downloadable files** is a catalog decision. Any variant can own digital assets — including a physical one, so a boxed product can ship a warranty PDF or a setup guide alongside the goods.
+
+Most digital products are both: a digital variant that carries the files it delivers. But the two are decoupled on purpose, so "ships nothing" and "hands over a file" can be mixed as a merchant needs.
+
+```mermaid
+erDiagram
+    Product ||--|{ Variant : "has"
+    Variant ||--o{ DigitalAsset : "carries"
+    DigitalAsset ||--o{ DigitalLink : "granted as"
+    LineItem ||--o{ DigitalLink : "purchased in"
+    DigitalAsset {
+        string provider_type "blank = uploaded file"
+        int authorized_clicks "nullable, falls back to store"
+        int authorized_days "nullable, falls back to store"
+    }
+    DigitalLink {
+        string token "the download credential"
+        int access_counter "downloads spent"
+    }
+```
+
+### Assets live on the variant
+
+A digital asset (`Spree::DigitalAsset`) belongs to a variant and holds either an uploaded file or a reference to a provider that produces the deliverable on demand (see [Where the file comes from](#where-the-file-comes-from) below). Uploaded files go to **private storage** — they are only ever served through a short‑lived, signed link, never a public URL.
+
+You attach assets to a variant from the product's **Digital files** card in the dashboard, or through the Admin API nested under the product:
+
+
+```typescript Admin SDK
+// 1. Ask for a private-storage upload slot, then PUT the file to the returned URL.
+const { direct_upload, signed_id } = await adminClient.directUploads.create({
+  private: true, // digital files are only ever served through a signed link
+  blob: { filename: 'guide.pdf', byte_size: file.size, checksum, content_type: 'application/pdf' },
+})
+await fetch(direct_upload.url, { method: 'PUT', headers: direct_upload.headers, body: file })
+
+// 2. Attach the uploaded blob to the product's default variant.
+await adminClient.products.digitalAssets.create('prod_86Rf07xd4z', {
+  signed_id,
+  authorized_clicks: 5, // optional — omit to inherit the store default
+  authorized_days: 30,
+})
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/products/prod_86Rf07xd4z/digital_assets' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "signed_id": "eyJfcmFpbHMi...", "authorized_clicks": 5, "authorized_days": 30 }'
+```
+
+
+> **WARNING:** Digital files must be uploaded to **private storage**. The Admin API refuses a blob that landed on the public service — attaching never moves a file between services, so a public upload would stay publicly readable while looking attached. Request the direct upload with `private: true`.
+
+Replacing an asset's file keeps every download link that was already issued working: links resolve through the asset, not the underlying blob, so a merchant can swap a corrected file mid‑sale without breaking anyone's access.
+
+### A purchase grants download links
+
+When an order is placed, digital assets fulfill themselves. The digital fulfillment provider runs automatically (it needs no address and no manual action) and, for each purchased unit, creates one **download link** (`Spree::DigitalLink`) per asset on the variant. Buy three copies of a two‑file bundle and the buyer gets six links. Re‑running fulfillment is idempotent — it never duplicates links.
+
+A download link is the customer's **grant**: a globally unique token, a counter of downloads spent, and its own copy of the allowance. The token *is* the credential — it identifies the store on its own, which is why an emailed link works without any API key.
+
+Customers reach their files two ways:
+
+- **By email.** On order placement, `Spree::DigitalAssetMailer` sends a "your files are ready" message with the links — a message of its own, separate from the order confirmation, so it can be re‑sent from the order page later.
+- **From their account.** A signed‑in customer sees every link they have ever been granted, across all their orders, through the customer downloads endpoint.
+
+> **NOTE:** The files-ready email is only sent when the order actually has digital links and the store has consumer transactional emails enabled. A store that delivers files through its own storefront or webhooks can leave it off.
+
+### Downloading, and the allowance
+
+A download is a `GET` against the link's token. Every download runs the same guarded sequence, and the customer's allowance is only spent once a deliverable is actually in hand:
+
+1. **The grant must be live** — attempts remaining, and not past its expiry.
+2. **The signed‑URL window must be open** — clamped to whatever is shorter, the store's link lifetime or the link's own remaining days.
+3. **The deliverable is produced** — see providers below. This step is allowed to fail.
+4. **The download is charged** — the counter is incremented under a lock.
+5. **The file is handed over** — a redirect to a signed URL, or an inline body.
+
+The ordering is deliberate: producing the deliverable comes *before* charging the click, so a provider outage or a missing file returns an honest error and **costs the customer nothing**. Two allowances govern access, both falling back to store settings when the asset leaves them blank:
+
+| Field | Meaning | Store default |
+| --- | --- | :---: |
+| `authorized_clicks` | How many times the file may be downloaded | `5` |
+| `authorized_days` | How long after purchase the link stays valid | `7` |
+
+Store‑wide defaults and their on/off switches live at **Settings → Store**; the separate `digital_asset_link_expire_time` preference caps how long a single signed URL lives (default 5 minutes, never more than an hour) because that URL is a bearer credential. When a customer runs out of downloads or a file was replaced mid‑flight, an admin can restore access by resetting the link from the order page, which zeroes the counter and restarts the clock.
+
+Each successful download publishes an event you can subscribe to:
+
+| Event | Published when |
+| --- | --- |
+| `digital_link.downloaded` | A customer successfully downloads a file (after the click is charged) |
+
+### Where the file comes from
+
+By default a digital asset delivers its uploaded file. But the last step — "hand something over" — is pluggable through a **digital asset provider**, so the deliverable can instead be minted on demand: a license key from your billing system, an entitlement from internal software, or a signed link to a file on your own host. The purchase, the grant, the allowance, and the email are identical either way; only the production of the deliverable changes.
+
+A blank `provider_type` on an asset means the built‑in file provider — the uploaded‑file behavior described above. Registering your own provider adds it as a source on the Digital files card, so a merchant can pick it when adding an asset.
+
+> **TIP:** To build one, see the [Build a Custom Digital Asset Provider](../how-to/custom-digital-asset-provider.md) how‑to. It covers the `#deliver` contract, per‑asset settings, and registration.
+
 ## Categories
 
 There are two ways to group products, and they answer different questions.
@@ -934,6 +1043,7 @@ See [Sales Channels](channels.md) for the full channel lifecycle, including defa
 - [Pricing](pricing.md) — Price Lists, Price Rules, and market-specific pricing
 - [Inventory](inventory.md) — Stock management and backorders
 - [Media](media.md) — Image management
+- [Build a Custom Digital Asset Provider](../how-to/custom-digital-asset-provider.md) — Deliver a license key or external file instead of an uploaded one
 - [Translations](translations.md) — Translating product content
 - [Search & Filtering](search-filtering.md) — Full-text search and Ransack filtering
 - [Store SDK Products](../sdk/store/products.md) — Listing, fetching, filtering, and categories via `client.products`

package/dist/developer/how-to/custom-digital-asset-provider.md

@@ -76,7 +76,7 @@ setting :region, :select, in: %w[us eu], default: 'us'
 setting :auto_revoke, :boolean, default: false
 ```
 
-Field types are `:string`, `:number`, `:boolean`, and `:select` (pass `in:` for the choices). The merchant's answers are stored on the asset and read back through `digital_asset.provider_settings`, a plain hash keyed by the setting name:
+Field types are `:string`, `:number`, `:boolean`, and `:select` (pass `in:` for the choices). Your declarations become the provider's `settings_schema`, which the admin `providers` endpoint exposes so the dashboard can render the form. The merchant's answers are stored on the asset — under one key, `metadata['provider']`, so they never collide with other developer metadata — and read back through `digital_asset.provider_settings`, a plain hash keyed by the setting name:
 
 ```ruby
 digital_asset.provider_settings['pool_name'] # => "winter-sale"
@@ -94,6 +94,8 @@ end
 
 Once registered, the provider appears as a source on the product's **Digital files** card: the **Add** button becomes a menu offering **Upload a file** alongside each registered provider. Picking your provider creates an asset with its `provider_type` set and no file attached.
 
+> **NOTE:** Registration is what makes a `provider_type` valid. An asset validates that its `provider_type` names a registered provider, so an unregistered or misspelled class name is rejected with a 422 rather than failing at download time. A blank `provider_type` is always the built-in `File` provider.
+
 ## The download contract
 
 Every download follows the same order, and a provider only participates in the last step:
@@ -130,4 +132,5 @@ Spree::DigitalDelivery.new(inline_value: 'ABCD-1234-EFGH', content_type: 'text/p
 ## Related documentation
 
 - [Digital products](/use-case/digital-products/capabilities) — what the feature does for merchants
-- [Build a Custom Delivery Rate Provider](/v6/developer/how-to/custom-delivery-rate-provider) — a provider strategy that *does* use an integration, for contrast
+- [Products](../core-concepts/products.md#digital-products) — how digital assets, links, and downloads fit together
+- [Build a Custom Delivery Rate Provider](custom-delivery-rate-provider.md) — a provider strategy that *does* use an integration, for contrast

package/dist/developer/how-to/sell-digital-products.md

@@ -3,18 +3,75 @@ title: Sell Digital Products
 description: Digital goods in Spree — a digital delivery profile, instant fulfillment without a shipping address, and delivering files or entitlements after payment.
 ---
 
-Digital products skip the warehouse: no stock to reserve, no address to collect, no carrier to call. In Spree 6 that behavior comes from the product's delivery profile — assign a digital profile and checkout, fulfillment and the customer experience adapt.
+Digital products skip the warehouse: no stock to reserve, no address to collect, no carrier to call. In Spree 6 that behavior comes from the product's delivery profile — assign a digital profile and checkout, fulfillment and the customer experience adapt. This guide walks through selling an uploaded file end to end.
+
+For the concepts behind each piece — assets, links, allowances, providers — see [Products → Digital products](../core-concepts/products.md#digital-products). This page is the practical walkthrough.
 
 ## What you will build
 
-- **Digital delivery profile** — products that require no shipping address and complete checkout without a delivery step.
-- **Instant fulfillment** — the digital fulfillment provider fulfills on payment rather than on dispatch.
-- **Delivery of the goods** — attaching files or granting entitlements, and notifying the customer.
-- **Mixed carts** — physical and digital items in one order, split into separate fulfillments automatically.
+- **A digital variant** — one whose delivery profile requires no shipping address, so a fully digital cart completes checkout without a delivery step.
+- **A downloadable file on it** — uploaded to private storage and attached as a digital asset.
+- **Automatic delivery** — a download link granted on order placement, and an email that sends it.
+- **Mixed carts** — physical and digital items in one order, handled without extra work.
+
+## 1. Make the product digital
+
+A variant is digital when its [delivery profile](../core-concepts/fulfillments.md) is a digital one. A store ships with a built-in **Digital** delivery profile; assign it to the product and the product's variants stop asking for a shipping address.
+
+
+```typescript Admin SDK
+// Assign the store's digital delivery profile to the product.
+const { data: profiles } = await adminClient.deliveryProfiles.list()
+const digital = profiles.find((p) => p.kind === 'digital')
+
+await adminClient.products.update('prod_86Rf07xd4z', {
+  delivery_profile_id: digital.id,
+})
+```
+
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/products/prod_86Rf07xd4z' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "delivery_profile_id": "dp_digital" }'
+```
+
+
+> **NOTE:** A product's delivery profile is auto-assigned when it is created — from its product type's template, or the store default. You only set it explicitly to change it. Selling from the dashboard, this is the **Shipping profile** field on the product page.
+
+## 2. Attach the file
+
+Upload the file to **private storage** and attach it to the variant as a digital asset. Private storage matters: a digital file is only ever served through a short-lived signed link, so the Admin API refuses a blob that landed on the public bucket.
+
+```typescript Admin SDK
+// Request a private upload slot, PUT the file, then attach the blob.
+const { direct_upload, signed_id } = await adminClient.directUploads.create({
+  private: true,
+  blob: { filename: 'guide.pdf', byte_size: file.size, checksum, content_type: 'application/pdf' },
+})
+await fetch(direct_upload.url, { method: 'PUT', headers: direct_upload.headers, body: file })
+
+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](../core-concepts/products.md#downloading-and-the-allowance) for how the limits resolve.
+
+> **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.
+
+## 3. Let the order deliver itself
+
+There is no step three to configure. When the order is placed, the digital fulfillment provider runs automatically — it needs no address and no manual dispatch — and grants the buyer one download link per file, per purchased unit. `Spree::DigitalAssetMailer` then emails the links as a message of its own, so it survives a replaced order-confirmation template and can be re-sent from the order page.
+
+The customer downloads by following the link's token; each download is counted against the allowance and publishes a `digital_link.downloaded` event. If they exhaust their downloads or you replace the file mid-sale, an admin restores access by resetting the link from the order page.
+
+> **NOTE:** To deliver something other than an uploaded file — a license key minted on demand, an entitlement from your own system — the delivery step is pluggable. See [Build a Custom Digital Asset Provider](custom-digital-asset-provider.md).
+
+## 4. Mixed carts work on their own
+
+A cart with both physical and digital items needs nothing special. Spree splits the order into separate fulfillments per delivery profile, so the physical items collect an address and ship while the digital items skip straight to granting links. The delivery step only appears when at least one item actually needs shipping; an all-digital cart never sees it.
 
-## Outline
+## Related documentation
 
-1. Create a digital delivery profile and assign products
-2. Configure the digital fulfillment provider
-3. Deliver files or entitlements on fulfillment
-4. Handle mixed physical and digital orders
+- [Products → Digital products](../core-concepts/products.md#digital-products) — the concepts: assets, links, allowances, providers
+- [Build a Custom Digital Asset Provider](custom-digital-asset-provider.md) — deliver a key or external file instead of an upload
+- [Fulfillments](../core-concepts/fulfillments.md) — delivery profiles, providers, and how orders are fulfilled

package/package.json

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