create-cartbase 0.1.13 → 0.1.15

package/template/app/docs/products.md

@@ -1,306 +1,316 @@
-# Products
-
-The catalog read surface. The product object documented here is THE
-canonical shape every discovery endpoint reuses (search results, collection
-membership pages, related products) — build one product-card renderer
-against it. Money is EUR decimal major units.
-
-SDK module: `@cartbase/storefront/api/products`.
-
-**Pricing context (applies to every endpoint here):** pass `currency_code`
-(or `region_id` — its region's currency is used; unknown region → 400
-`invalid_region`) to receive `variant.calculated_price`. Without either,
-`calculated_price` is `null` and only raw base prices are listed. Customer
-groups come ONLY from the optional `authorization: Bearer <jwt>` — never
-from params. **Cache rule:** any response carrying `calculated_price` varies
-by customer group — never cache it shared when a JWT was present.
-
-**Leak rule:** raw price rows in store responses contain ONLY base
-(non-price-list) rows. Price-list amounts surface exclusively through
-`calculated_price` for the caller's own context.
-
-**Publishable-key channel scope:** sending `x-publishable-api-key` restricts
-the catalog to products linked to the key's sales channels — a product
-outside them **404s on retrieve and disappears from lists** (invisible, not
-forbidden). A key with no channel links scopes nothing. Unknown/revoked/
-foreign key → 400 `invalid_publishable_key`.
-
----
-
-## GET /api/store/products
-
-- **Purpose** — the product listing: catalog pages, filtered grids.
-  Published products only (drafts are RLS-invisible).
-- **Auth** — anon: `x-client-id` required; `x-publishable-api-key` optional
-  (channel scope); `authorization: Bearer <jwt>` optional (group pricing).
-- **Request**
-
-```jsonc
-// query (all optional)
-{
-  "q": "linen",                  // case-insensitive substring on TITLE only
-  "id": "prod_a,prod_b",         // CSV of ids
-  "handle": "linen-shirt",       // exact
-  "collection_id": "pcol_a",     // CSV — products.collection_id (primary collection)
-  "category_id": "pcat_a",       // CSV — category membership
-  "tag_id": "ptag_a",            // CSV — tag membership
-  "type_id": "ptyp_a",           // CSV
-  "order": "-created_at",        // sort column, "-" prefix = desc (default -created_at)
-  "currency_code": "eur",        // pricing context
-  "region_id": "reg_…",          //   or region → currency
-  "limit": 50,                   // 1–200, default 50
-  "offset": 0
-}
-```
-
-- **Response** — `{ products, count, offset, limit }`; each product:
-
-```jsonc
-{
-  "id": "prod_01tst00000000000000000001",
-  "title": "Linen Shirt",
-  "subtitle": null,
-  "description": "Lightweight linen shirt, relaxed fit.",
-  "handle": "linen-shirt",
-  "status": "published",              // always — drafts never appear
-  "thumbnail": "https://…/600/800",
-  "is_giftcard": false,
-  "discountable": true,
-  "collection_id": "pcol_01tst00000000000000000001",
-  "type_id": null,
-  "external_id": null,
-  "weight": null, "length": null, "height": null, "width": null,
-  "hs_code": null, "origin_country": null, "mid_code": null, "material": null,
-  "seo_title": null,                  // null = fall back to title
-  "seo_description": null,            // null = fall back to plain-text description
-  "metadata": null,
-  "created_at": "2026-07-01T00:00:00.000Z",
-  "updated_at": "2026-07-01T00:00:00.000Z",
-  "variants": [
-    {
-      "id": "variant_01tst000000000000000001",
-      "title": "S",
-      "product_id": "prod_01tst00000000000000000001",
-      "sku": "LIN-SHIRT-S",
-      "barcode": null, "ean": null, "upc": null,
-      "thumbnail": null,
-      "allow_backorder": false,
-      "manage_inventory": true,
-      // Computed server-side by the platform's availability predicate:
-      // untracked or backorderable variants are always true; otherwise true
-      // iff available stock (kit-aware, reservations subtracted) is above
-      // zero. Read this — never re-derive stock client-side (the exact
-      // quantity is deliberately not exposed).
-      "in_stock": true,
-      "variant_rank": 0,
-      "metadata": null,
-      "options": [
-        { "value": { "id": "optv_…", "value": "S", "option_id": "opt_…",
-                     "option": { "id": "opt_…", "title": "Size", "product_id": "prod_…" } } }
-      ],
-      // Raw BASE prices via the price-set link embed (leak rule: price-list
-      // rows are stripped — price_list_id is always null here):
-      "prices": [
-        { "price_set": { "prices": [
-            { "id": "price_…", "amount": 45, "currency_code": "eur",
-              "min_quantity": null, "max_quantity": null,
-              "price_set_id": "pset_…", "price_list_id": null }
-        ] } }
-      ],
-      // Present when a pricing context was given; null otherwise or when no
-      // price matches. b2b-v1 shape (store-api.md §Pricing context):
-      "calculated_price": {
-        "calculated_amount": 45,
-        "original_amount": 45,
-        "currency_code": "eur",
-        "is_calculated_price_price_list": false,
-        "price_list_id": null,
-        "price_list_type": null
-      }
-    }
-  ],
-  "images": [ { "id": "pimg_…", "url": "https://…", "rank": 0 } ],
-  "options": [ { "id": "opt_…", "title": "Size",
-                 "values": [ { "id": "optv_…", "value": "S" } ] } ],
-  "collection": { "id": "pcol_…", "title": "Essentials", "handle": "essentials" },
-  "categories": [ { "category": { "id": "pcat_…", "name": "Apparel", "handle": "apparel" } } ],
-  "tags": [ { "tag": { "id": "ptag_…", "value": "summer" } } ],
-  "type": null
-}
-```
-
-- **Working curl**
-
-```bash
-PRODUCTS=$(curl -sf "$BASE/api/store/products?limit=5" -H "x-client-id: $CLIENT_ID")
-echo "$PRODUCTS" | grep -q '"products"'
-echo "$PRODUCTS" | grep -q '"count"'
-# The handle filter answers deterministically regardless of catalog size.
-curl -sf "$BASE/api/store/products?handle=linen-shirt" -H "x-client-id: $CLIENT_ID" \
-  | grep -q '"handle":"linen-shirt"'
-```
-
-- **Errors** — 400 `missing_client_id`, 400 `validation_failed`,
-  400 `invalid_publishable_key`, 400 `invalid_region`.
-- **SDK** — `listProducts(client, query?)`.
-- **Components** — product card grid (components.md).
-- **Settings** — sales-channel product links + publishable-key bindings
-  (channel scope), price lists (calculated_price).
-
----
-
-## GET /api/store/products/:idOrHandle
-
-- **Purpose** — the PDP read. Accepts a product id (`prod_…`) or a handle —
-  storefronts deep-link by handle.
-- **Auth** — as the list.
-- **Request** — query: pricing context only (`currency_code` / `region_id`).
-- **Response** — `{ "product": { ...shape above... } }`
-- **Working curl** — with pricing context; asserts the seeded base price
-  (Linen Shirt, EUR 45) and the leak rule structurally:
-
-```bash
-PRODUCT=$(curl -sf "$BASE/api/store/products/linen-shirt?currency_code=eur" \
-  -H "x-client-id: $CLIENT_ID")
-echo "$PRODUCT" | grep -q '"product"'
-echo "$PRODUCT" | grep -q '"calculated_price"'
-echo "$PRODUCT" | grep -q '"calculated_amount":45'
-echo "$PRODUCT" | grep -q '"seo_title"'
-```
-
-```bash
-# Leak rule, asserted structurally: every raw price row is a BASE row
-# (price_list_id null) — price-list amounts only ever ride calculated_price.
-echo "$PRODUCT" | node -e "
-const c=[];process.stdin.on('data',d=>c.push(d)).on('end',()=>{
-  const j=JSON.parse(Buffer.concat(c));
-  const rows=j.product.variants.flatMap(v=>v.prices??[]).flatMap(l=>l.price_set?.prices??[]);
-  if(!rows.length){console.error('no base price rows');process.exit(1)}
-  if(rows.some(r=>r.price_list_id!==null)){console.error('price-list row leaked');process.exit(1)}
-})"
-```
-
-- **Errors** — 404 `not_found` (unknown handle/id, draft, soft-deleted, or
-  outside the publishable key's channels), 400 `invalid_publishable_key`,
-  400 `invalid_region`.
-
-```bash
-STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
-  "$BASE/api/store/products/no-such-handle-$RUN" -H "x-client-id: $CLIENT_ID")
-test "$STATUS" = 404
-```
-
-```bash
-# Channel scope: the dev PUBLISHABLE_KEY is bound to the B2B channel, whose
-# catalog is Linen Shirt + Wool Beanie. The Leather Belt exists (anon read
-# works) but 404s under the key — invisible, not forbidden.
-curl -sf "$BASE/api/store/products/leather-belt" \
-  -H "x-client-id: $CLIENT_ID" | grep -q '"handle":"leather-belt"'
-STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
-  "$BASE/api/store/products/leather-belt" \
-  -H "x-client-id: $CLIENT_ID" -H "x-publishable-api-key: $PUBLISHABLE_KEY")
-test "$STATUS" = 404
-curl -sf "$BASE/api/store/products/linen-shirt" \
-  -H "x-client-id: $CLIENT_ID" -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
-  | grep -q '"handle":"linen-shirt"'
-```
-
-```bash
-# Unknown key → 400 invalid_publishable_key (never a silent unscoped read).
-BODY=$(curl -s "$BASE/api/store/products/linen-shirt" \
-  -H "x-client-id: $CLIENT_ID" -H "x-publishable-api-key: pk_bogus_$RUN")
-echo "$BODY" | grep -q '"code":"invalid_publishable_key"'
-```
-
-- **SDK** — `retrieveProduct(client, idOrHandle, query?)`.
-- **Components** — PDP family: gallery, option picker, price block.
-- **Settings** — as the list; SEO overrides (Admin → Product → SEO).
-
----
-
-## GET /api/store/products/:idOrHandle/selling-plans
-
-- **Purpose** — the subscription plans this product can be purchased with
-  (subscriptions add-on). Render as PDP purchase options (one-time vs each
-  plan); the chosen plan id goes on the cart line
-  (`POST /carts/:id/line-items` `selling_plan_id`) and the SERVER applies
-  the plan price. Empty list = one-time only.
-- **Auth** — anon `x-client-id`; publishable-key channel scope applies
-  (same visibility rule as the product read).
-- **Response** — `{ selling_plans: [{id, name, interval, interval_count,
-  pricing_type, pricing_value, min_cycles, max_cycles}], count }`.
-  `pricing_type` `percent` (percent off) | `fixed` (fixed unit price, EUR
-  major units) | `null` (catalog price — the plan only sets the cadence);
-  enabled plans only, merchant-defined order.
-- **Errors** — 404 `not_found` (same rules as the product read).
-- **SDK** — `products.listSellingPlans(client, idOrHandle)`.
-- **Components** — `PurchaseOptions` (products family): controlled radio
-  group, one-time + plans with display-only price preview
-  (`previewPlanPrice` mirrors the server's math; the server is truth).
-  NOTE: a cart with a plan line requires a logged-in customer at payment
-  (checkout.md `save_payment_method`) — surface login before checkout.
-
-```bash
-# The dev tenant seeds no plans — the endpoint contract still executes:
-# a valid product answers with the envelope, an unknown product 404s.
-SPLANS=$(curl -sf "$BASE/api/store/products/linen-shirt/selling-plans" \
-  -H "x-client-id: $CLIENT_ID")
-echo "$SPLANS" | grep -q '"selling_plans"'
-echo "$SPLANS" | grep -q '"count"'
-STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
-  "$BASE/api/store/products/no-such-handle-$RUN/selling-plans" \
-  -H "x-client-id: $CLIENT_ID")
-test "$STATUS" = 404
-```
-
----
-
-## GET /api/store/product-variants
-
-- **Purpose** — variant multi-lookup (cart-line hydration). `id` accepts a
-  CSV of variant ids in ONE param. Ordered by `variant_rank`.
-- **Auth** — anon: `x-client-id`; optional Bearer JWT (group pricing).
-  NOTE (code truth): this listing is NOT publishable-key channel-scoped —
-  scope applies to product reads.
-- **Request** — query `{ id?, product_id?, sku?, currency_code?, region_id?,
-  limit?, offset? }` (`limit` 1–200, default 50).
-- **Response** — `{ variants, count, offset, limit }`; variant shape exactly
-  as embedded in products above (options + prices + calculated_price).
-- **Working curl**
-
-```bash
-VARIANTS=$(curl -sf "$BASE/api/store/product-variants?sku=LIN-SHIRT-S&currency_code=eur" \
-  -H "x-client-id: $CLIENT_ID")
-echo "$VARIANTS" | grep -q '"variants"'
-echo "$VARIANTS" | grep -q '"sku":"LIN-SHIRT-S"'
-VARIANT_ID=$(echo "$VARIANTS" | grep -o '"id":"variant_[^"]*"' | head -1 | cut -d'"' -f4)
-test -n "$VARIANT_ID"
-```
-
-- **Errors** — 400 `missing_client_id`, 400 `validation_failed`,
-  400 `invalid_region`.
-- **SDK** — `listProductVariants(client, query?)`.
-- **Components** — cart line renderer.
-- **Settings** — price lists (calculated_price).
-
----
-
-## GET /api/store/product-variants/:id
-
-- **Purpose** — retrieve one variant with options + base prices hydrated.
-- **Auth** — anon: `x-client-id`; optional Bearer JWT.
-- **Request** — query: pricing context only.
-- **Response** — `{ "variant": { ... } }`
-- **Working curl**
-
-```bash
-VARIANT=$(curl -sf "$BASE/api/store/product-variants/$VARIANT_ID?currency_code=eur" \
-  -H "x-client-id: $CLIENT_ID")
-echo "$VARIANT" | grep -q '"variant"'
-echo "$VARIANT" | grep -q '"calculated_price"'
-```
-
-- **Errors** — 404 `not_found`, 400 `invalid_region`.
-- **SDK** — `retrieveProductVariant(client, variantId, query?)`.
-- **Components** — cart line renderer, option picker.
-- **Settings** — price lists.
+# Products
+
+The catalog read surface. The product object documented here is THE
+canonical shape every discovery endpoint reuses (search results, collection
+membership pages, related products) — build one product-card renderer
+against it. Money is EUR decimal major units.
+
+SDK module: `@cartbase/storefront/api/products`.
+
+**Pricing context (applies to every endpoint here):** pass `currency_code`
+(or `region_id` — its region's currency is used; unknown region → 400
+`invalid_region`) to receive `variant.calculated_price`. Without either,
+`calculated_price` is `null` and only raw base prices are listed. Customer
+groups come ONLY from the optional `authorization: Bearer <jwt>` — never
+from params. **Cache rule:** any response carrying `calculated_price` varies
+by customer group — never cache it shared when a JWT was present.
+
+**Leak rule:** raw price rows in store responses contain ONLY base
+(non-price-list) rows. Price-list amounts surface exclusively through
+`calculated_price` for the caller's own context.
+
+**Publishable-key channel scope:** sending `x-publishable-api-key` restricts
+the catalog to products linked to the key's sales channels — a product
+outside them **404s on retrieve and disappears from lists** (invisible, not
+forbidden). A key with no channel links scopes nothing. Unknown/revoked/
+foreign key → 400 `invalid_publishable_key`.
+
+---
+
+## GET /api/store/products
+
+- **Purpose** — the product listing: catalog pages, filtered grids.
+  Published products only (drafts are RLS-invisible).
+- **Auth** — anon: `x-client-id` required; `x-publishable-api-key` optional
+  (channel scope); `authorization: Bearer <jwt>` optional (group pricing).
+- **Request**
+
+```jsonc
+// query (all optional)
+{
+  "q": "linen",                  // case-insensitive substring on TITLE only
+  "id": "prod_a,prod_b",         // CSV of ids
+  "handle": "linen-shirt",       // exact
+  "collection_id": "pcol_a",     // CSV — collection membership (any of them)
+  "category_id": "pcat_a",       // CSV — category membership
+  "tag_id": "ptag_a",            // CSV — tag membership
+  "type_id": "ptyp_a",           // CSV
+  "order": "-created_at",        // sort column, "-" prefix = desc (default -created_at)
+  "currency_code": "eur",        // pricing context
+  "region_id": "reg_…",          //   or region → currency
+  "limit": 50,                   // 1–200, default 50
+  "offset": 0
+}
+```
+
+- **Response** — `{ products, count, offset, limit }`; each product:
+
+```jsonc
+{
+  "id": "prod_01tst00000000000000000001",
+  "title": "Linen Shirt",
+  "subtitle": null,
+  "description": "Lightweight linen shirt, relaxed fit.",
+  "handle": "linen-shirt",
+  "status": "published",              // always — drafts never appear
+  "thumbnail": "https://…/600/800",
+  "is_giftcard": false,
+  "discountable": true,
+  "type_id": null,
+  "external_id": null,
+  "vendor": null,                     // the brand, plain text
+  "weight": null, "length": null, "height": null, "width": null,
+  "hs_code": null, "origin_country": null, "mid_code": null, "material": null,
+  "seo_title": null,                  // null = fall back to title
+  "seo_description": null,            // null = fall back to plain-text description
+  "metadata": null,
+  // The store's custom fields under their definition keys, values as stored
+  // (string, number, boolean, array for a list, id for a metaobject
+  // reference). Public definitions only: Settings, Custom fields switches a
+  // field off the storefront. Always present, {} when the product has none.
+  "metafields": { "custom.product_label_1": "500 мл", "custom.product_label_2": "Испания" },
+  "created_at": "2026-07-01T00:00:00.000Z",
+  "updated_at": "2026-07-01T00:00:00.000Z",
+  "variants": [
+    {
+      "id": "variant_01tst000000000000000001",
+      "title": "S",
+      "product_id": "prod_01tst00000000000000000001",
+      "sku": "LIN-SHIRT-S",
+      "barcode": null, "ean": null, "upc": null,
+      "thumbnail": null,
+      "allow_backorder": false,
+      "manage_inventory": true,
+      // Computed server-side by the platform's availability predicate:
+      // untracked or backorderable variants are always true; otherwise true
+      // iff available stock (kit-aware, reservations subtracted) is above
+      // zero. Read this — never re-derive stock client-side (the exact
+      // quantity is deliberately not exposed).
+      "in_stock": true,
+      "variant_rank": 0,
+      "metadata": null,
+      "options": [
+        { "value": { "id": "optv_…", "value": "S", "option_id": "opt_…",
+                     "option": { "id": "opt_…", "title": "Size", "product_id": "prod_…" } } }
+      ],
+      // Raw BASE prices via the price-set link embed (leak rule: price-list
+      // rows are stripped — price_list_id is always null here):
+      "prices": [
+        { "price_set": { "prices": [
+            { "id": "price_…", "amount": 45, "currency_code": "eur",
+              "min_quantity": null, "max_quantity": null,
+              "price_set_id": "pset_…", "price_list_id": null }
+        ] } }
+      ],
+      // Present when a pricing context was given; null otherwise or when no
+      // price matches. b2b-v1 shape (store-api.md §Pricing context):
+      "calculated_price": {
+        "calculated_amount": 45,
+        "original_amount": 45,
+        "currency_code": "eur",
+        "is_calculated_price_price_list": false,
+        "price_list_id": null,
+        "price_list_type": null
+      }
+    }
+  ],
+  "images": [ { "id": "pimg_…", "url": "https://…", "rank": 0 } ],
+  "options": [ { "id": "opt_…", "title": "Size",
+                 "values": [ { "id": "optv_…", "value": "S" } ] } ],
+  // EVERY collection the product is in, the shape categories and tags have.
+  // It was one `collection` object read off products.collection_id until
+  // 2026-09-15; that column held one of a product's collections at most.
+  "collections": [
+    { "collection": { "id": "pcol_…", "title": "Essentials", "handle": "essentials" } }
+  ],
+  "categories": [ { "category": { "id": "pcat_…", "name": "Apparel", "handle": "apparel" } } ],
+  "tags": [ { "tag": { "id": "ptag_…", "value": "summer" } } ],
+  "type": null
+}
+```
+
+- **Working curl**
+
+```bash
+PRODUCTS=$(curl -sf "$BASE/api/store/products?limit=5" -H "x-client-id: $CLIENT_ID")
+echo "$PRODUCTS" | grep -q '"products"'
+echo "$PRODUCTS" | grep -q '"count"'
+# The handle filter answers deterministically regardless of catalog size.
+curl -sf "$BASE/api/store/products?handle=linen-shirt" -H "x-client-id: $CLIENT_ID" \
+  | grep -q '"handle":"linen-shirt"'
+```
+
+- **Errors** — 400 `missing_client_id`, 400 `validation_failed`,
+  400 `invalid_publishable_key`, 400 `invalid_region`.
+- **SDK** — `listProducts(client, query?)`.
+- **Components** — product card grid (components.md).
+- **Settings** — sales-channel product links + publishable-key bindings
+  (channel scope), price lists (calculated_price).
+
+---
+
+## GET /api/store/products/:idOrHandle
+
+- **Purpose** — the PDP read. Accepts a product id (`prod_…`) or a handle —
+  storefronts deep-link by handle.
+- **Auth** — as the list.
+- **Request** — query: pricing context only (`currency_code` / `region_id`).
+- **Response** — `{ "product": { ...shape above... } }`
+- **Working curl** — with pricing context; asserts the seeded base price
+  (Linen Shirt, EUR 45) and the leak rule structurally:
+
+```bash
+PRODUCT=$(curl -sf "$BASE/api/store/products/linen-shirt?currency_code=eur" \
+  -H "x-client-id: $CLIENT_ID")
+echo "$PRODUCT" | grep -q '"product"'
+echo "$PRODUCT" | grep -q '"calculated_price"'
+echo "$PRODUCT" | grep -q '"calculated_amount":45'
+echo "$PRODUCT" | grep -q '"seo_title"'
+```
+
+```bash
+# Leak rule, asserted structurally: every raw price row is a BASE row
+# (price_list_id null) — price-list amounts only ever ride calculated_price.
+echo "$PRODUCT" | node -e "
+const c=[];process.stdin.on('data',d=>c.push(d)).on('end',()=>{
+  const j=JSON.parse(Buffer.concat(c));
+  const rows=j.product.variants.flatMap(v=>v.prices??[]).flatMap(l=>l.price_set?.prices??[]);
+  if(!rows.length){console.error('no base price rows');process.exit(1)}
+  if(rows.some(r=>r.price_list_id!==null)){console.error('price-list row leaked');process.exit(1)}
+})"
+```
+
+- **Errors** — 404 `not_found` (unknown handle/id, draft, soft-deleted, or
+  outside the publishable key's channels), 400 `invalid_publishable_key`,
+  400 `invalid_region`.
+
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/products/no-such-handle-$RUN" -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 404
+```
+
+```bash
+# Channel scope: the dev PUBLISHABLE_KEY is bound to the B2B channel, whose
+# catalog is Linen Shirt + Wool Beanie. The Leather Belt exists (anon read
+# works) but 404s under the key — invisible, not forbidden.
+curl -sf "$BASE/api/store/products/leather-belt" \
+  -H "x-client-id: $CLIENT_ID" | grep -q '"handle":"leather-belt"'
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/products/leather-belt" \
+  -H "x-client-id: $CLIENT_ID" -H "x-publishable-api-key: $PUBLISHABLE_KEY")
+test "$STATUS" = 404
+curl -sf "$BASE/api/store/products/linen-shirt" \
+  -H "x-client-id: $CLIENT_ID" -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
+  | grep -q '"handle":"linen-shirt"'
+```
+
+```bash
+# Unknown key → 400 invalid_publishable_key (never a silent unscoped read).
+BODY=$(curl -s "$BASE/api/store/products/linen-shirt" \
+  -H "x-client-id: $CLIENT_ID" -H "x-publishable-api-key: pk_bogus_$RUN")
+echo "$BODY" | grep -q '"code":"invalid_publishable_key"'
+```
+
+- **SDK** — `retrieveProduct(client, idOrHandle, query?)`.
+- **Components** — PDP family: gallery, option picker, price block.
+- **Settings** — as the list; SEO overrides (Admin → Product → SEO).
+
+---
+
+## GET /api/store/products/:idOrHandle/selling-plans
+
+- **Purpose** — the subscription plans this product can be purchased with
+  (subscriptions add-on). Render as PDP purchase options (one-time vs each
+  plan); the chosen plan id goes on the cart line
+  (`POST /carts/:id/line-items` `selling_plan_id`) and the SERVER applies
+  the plan price. Empty list = one-time only.
+- **Auth** — anon `x-client-id`; publishable-key channel scope applies
+  (same visibility rule as the product read).
+- **Response** — `{ selling_plans: [{id, name, interval, interval_count,
+  pricing_type, pricing_value, min_cycles, max_cycles}], count }`.
+  `pricing_type` `percent` (percent off) | `fixed` (fixed unit price, EUR
+  major units) | `null` (catalog price — the plan only sets the cadence);
+  enabled plans only, merchant-defined order.
+- **Errors** — 404 `not_found` (same rules as the product read).
+- **SDK** — `products.listSellingPlans(client, idOrHandle)`.
+- **Components** — `PurchaseOptions` (products family): controlled radio
+  group, one-time + plans with display-only price preview
+  (`previewPlanPrice` mirrors the server's math; the server is truth).
+  NOTE: a cart with a plan line requires a logged-in customer at payment
+  (checkout.md `save_payment_method`) — surface login before checkout.
+
+```bash
+# The dev tenant seeds no plans — the endpoint contract still executes:
+# a valid product answers with the envelope, an unknown product 404s.
+SPLANS=$(curl -sf "$BASE/api/store/products/linen-shirt/selling-plans" \
+  -H "x-client-id: $CLIENT_ID")
+echo "$SPLANS" | grep -q '"selling_plans"'
+echo "$SPLANS" | grep -q '"count"'
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/products/no-such-handle-$RUN/selling-plans" \
+  -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 404
+```
+
+---
+
+## GET /api/store/product-variants
+
+- **Purpose** — variant multi-lookup (cart-line hydration). `id` accepts a
+  CSV of variant ids in ONE param. Ordered by `variant_rank`.
+- **Auth** — anon: `x-client-id`; optional Bearer JWT (group pricing).
+  NOTE (code truth): this listing is NOT publishable-key channel-scoped —
+  scope applies to product reads.
+- **Request** — query `{ id?, product_id?, sku?, currency_code?, region_id?,
+  limit?, offset? }` (`limit` 1–200, default 50).
+- **Response** — `{ variants, count, offset, limit }`; variant shape exactly
+  as embedded in products above (options + prices + calculated_price).
+- **Working curl**
+
+```bash
+VARIANTS=$(curl -sf "$BASE/api/store/product-variants?sku=LIN-SHIRT-S&currency_code=eur" \
+  -H "x-client-id: $CLIENT_ID")
+echo "$VARIANTS" | grep -q '"variants"'
+echo "$VARIANTS" | grep -q '"sku":"LIN-SHIRT-S"'
+VARIANT_ID=$(echo "$VARIANTS" | grep -o '"id":"variant_[^"]*"' | head -1 | cut -d'"' -f4)
+test -n "$VARIANT_ID"
+```
+
+- **Errors** — 400 `missing_client_id`, 400 `validation_failed`,
+  400 `invalid_region`.
+- **SDK** — `listProductVariants(client, query?)`.
+- **Components** — cart line renderer.
+- **Settings** — price lists (calculated_price).
+
+---
+
+## GET /api/store/product-variants/:id
+
+- **Purpose** — retrieve one variant with options + base prices hydrated.
+- **Auth** — anon: `x-client-id`; optional Bearer JWT.
+- **Request** — query: pricing context only.
+- **Response** — `{ "variant": { ... } }`
+- **Working curl**
+
+```bash
+VARIANT=$(curl -sf "$BASE/api/store/product-variants/$VARIANT_ID?currency_code=eur" \
+  -H "x-client-id: $CLIENT_ID")
+echo "$VARIANT" | grep -q '"variant"'
+echo "$VARIANT" | grep -q '"calculated_price"'
+```
+
+- **Errors** — 404 `not_found`, 400 `invalid_region`.
+- **SDK** — `retrieveProductVariant(client, variantId, query?)`.
+- **Components** — cart line renderer, option picker.
+- **Settings** — price lists.