@spree/docs 0.1.93 → 0.1.95

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

@@ -77,7 +77,7 @@ erDiagram
 
     Refund {
         decimal amount
-        string reason
+        integer refund_reason_id
     }
 
     LogEntry {
@@ -128,7 +128,7 @@ A `PaymentMethod` can have the following attributes:
 | `name`       | The visible name for this payment method                                                      | `Check`                |
 | `description`| The description for this payment method                                                       | `Pay by check.`        |
 | `active`     | Whether or not this payment method is active. Set it `false` to hide it in the Store API.         | `true`                 |
-| `display_on` | Determines where the payment method can be visible. Values can be `front` for Store API, `back` for admin panel only or `both` for both. | `both`                 |
+| `display_on` | Determines where the payment method can be visible. Values can be `front_end` (Store API), `back_end` (admin panel only), or `both` (both). | `both`                 |
 | `position`   | The position of the payment method in lists. Lower numbers appear first.                      | `1`                    |
 
 > **INFO:** Each payment method is associated to a Store, so you can decide which Payment Method will appear on which Store. This allows you to create different experiences for your customers in different countries.
@@ -227,7 +227,7 @@ The frontend calls the API to create a Payment Session for a specific payment me
 
   **Step 2: Customer pays on the frontend**
 
-The frontend uses the gateway's JavaScript SDK (e.g., Stripe.js, Adyen Drop-in) with the `client_secret` to securely collect payment details. Card data never touches your server — it goes directly to the payment provider, ensuring **PCI compliance**. If the payment requires **3D Secure** authentication or redirects to an offsite gateway (CashApp, Klarna, etc.), the gateway SDK handles it automatically.
+The frontend uses the gateway's JavaScript SDK (e.g., Stripe.js, Adyen Drop-in) with the `client_secret` to securely collect payment details. Card data never touches your server — it goes directly to the payment provider, ensuring [PCI compliance](../security/pci_compliance.md). If the payment requires **3D Secure** authentication or redirects to an offsite gateway (CashApp, Klarna, etc.), the gateway SDK handles it automatically.
 
   **Step 3: Complete Payment Session**
 
@@ -291,14 +291,14 @@ sequenceDiagram
     participant Frontend
     participant Spree API
 
-    Frontend->>Spree API: GET /payment_methods
-    Spree API-->>Frontend: Payment methods (with session_required flag)
+    Frontend->>Spree API: GET /carts/:id
+    Spree API-->>Frontend: Cart (with embedded payment_methods, each carrying session_required)
 
     Frontend->>Spree API: POST /payments (payment_method_id)
     Spree API->>Spree API: Create Payment (checkout state)
     Spree API-->>Frontend: Payment created
 
-    Frontend->>Spree API: PATCH /orders/:id/complete
+    Frontend->>Spree API: POST /carts/:id/complete
     Spree API->>Spree API: process_payments! (authorize succeeds immediately)
     Spree API->>Spree API: Payment → pending/completed
     Spree API-->>Frontend: Order completed
@@ -306,7 +306,7 @@ sequenceDiagram
 
 **Step 1: List payment methods**
 
-The frontend calls `GET /payment_methods` and checks the `session_required` flag on each method. Methods with `session_required: false` use this direct flow.
+The frontend reads the cart's embedded `payment_methods` (returned by `GET /carts/:id`) and checks the `session_required` flag on each method. Methods with `session_required: false` use this direct flow.
 
   **Step 2: Create payment**
 
@@ -461,7 +461,7 @@ Once a Payment Session is completed, Spree creates a `Payment` record (`Spree::P
 
 | Attribute         | Description                                                                 | Example Value       |
 |-------------------|-----------------------------------------------------------------------------|---------------------|
-| `number`          | A unique identifier for the payment.                                        | `P123456789`        |
+| `number`          | A unique identifier for the payment.                                        | `PAB12CD34`         |
 | `source_type`     | The type of source used for the payment.                                    | `Spree::CreditCard` |
 | `source_id`       | The ID of the source used for the payment.                                  | `1`                 |
 | `amount`          | The amount of the payment.                                                  | `99.99`             |
@@ -590,12 +590,12 @@ sequenceDiagram
 | `external_id` | The provider-side session ID (e.g., Stripe SetupIntent ID) | `seti_ABC123` |
 | `external_client_secret` | Client secret for the frontend SDK | `seti_ABC123_secret_xyz` |
 | `external_data` | Provider-specific data | `{}` |
-| `payment_source_id` | The saved payment source created after completion | `ps_xyz789` |
+| `payment_source_id` | The saved payment source created after completion | `card_xyz789` |
 | `payment_source_type` | The type of saved payment source | `Spree::CreditCard` |
 
 ### Payment Setup Session API
 
-> **NOTE:** Payment Setup Sessions require customer authentication. The customer must be logged in.
+> **NOTE:** Payment Setup Sessions require [customer authentication](../../api-reference/store-api/authentication.md). The customer must be logged in.
 
 **Create a Payment Setup Session:**
 
@@ -624,7 +624,7 @@ console.log(setupSession.external_client_secret) // e.g. 'seti_ABC123_secret_xyz
   "payment_method_id": "pm_xyz789",
   "payment_source_id": null,
   "payment_source_type": null,
-  "customer_id": "usr_def456"
+  "customer_id": "cus_def456"
 }
 ```
 
@@ -643,7 +643,7 @@ const completed = await client.customer.paymentSetupSessions.complete(
   options
 )
 console.log(completed.status)             // 'completed'
-console.log(completed.payment_source_id)  // e.g. 'ps_xyz789' - the saved payment method
+console.log(completed.payment_source_id)  // e.g. 'card_xyz789' - the saved payment method
 ```
 
 Spree will verify the result with the provider and create a saved payment source (e.g., `Spree::CreditCard`) that can be used for future payments.
@@ -660,7 +660,7 @@ Spree team maintains several payment gateway integrations. All of these gateways
 
 ## Payment Events
 
-Spree publishes events throughout the payment lifecycle that you can subscribe to:
+Spree publishes events throughout the payment lifecycle that you can subscribe to. For the delivered payload schemas of these events (e.g. `payment.paid`, `payment_session.completed`), see the [Webhooks & Events reference](../../api-reference/webhooks-events.md):
 
 ### Payment Events
 | Event | Description |
@@ -688,6 +688,7 @@ See [Events](events.md) for more details on subscribing to events.
 
 ## Related Documentation
 
+- [Payments (Store SDK)](../sdk/store/payments.md) - SDK how-to for payment sessions, payments, and setup sessions
 - [Build a Custom Payment Method](../how-to/custom-payment-method.md) - Step-by-step guide to creating your own payment gateway integration
 - [Orders](orders.md) - Order management and state machine
 - [Checkout Customization](../customization/checkout.md) - Customizing the checkout flow

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

@@ -11,7 +11,7 @@ Spree's pricing system supports both simple single-currency pricing and advanced
 
 ## Prices
 
-Each variant has one or more `Price` records — one per currency. The API automatically returns the correct price based on the current currency and [Market](markets.md) context.
+Each variant has one or more `Price` records — one per currency. The API automatically returns the correct price based on the current currency and [Market](markets.md) context. See [monetary amounts](../../api-reference/store-api/monetary-amounts.md) for how money fields (decimal, cents, and display string) are formatted across the API.
 
 | Attribute | Description | Example |
 |-----------|-------------|---------|
@@ -26,19 +26,25 @@ Each variant has one or more `Price` records — one per currency. The API autom
 The Store API returns the resolved price (including Price List rules) for the current currency and market context:
 
 
-```typescript SDK
+```typescript Store SDK
 // Product price is included by default
 const product = await client.products.get('spree-tote')
-console.log(product.price)          // "15.99" — resolved for current currency
-console.log(product.original_price) // "19.99" — compare-at price (if set)
+console.log(product.price.amount)              // "15.99" — resolved for current currency
+console.log(product.price.compare_at_amount)   // "19.99" — compare-at/strikethrough price (if set)
 
 // Each variant has its own price
 const detailed = await client.products.get('spree-tote', {
   expand: ['variants'],
 })
 detailed.variants?.forEach(variant => {
-  console.log(variant.price)          // "15.99"
-  console.log(variant.original_price) // "19.99"
+  console.log(variant.price.amount)            // "15.99"
+  console.log(variant.price.compare_at_amount) // "19.99"
+})
+```
+
+```typescript Admin SDK
+const product = await adminClient.products.get('prod_86Rf07xd4z', {
+  expand: ['variants'],
 })
 ```
 
@@ -53,6 +59,41 @@ curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=variants'
 ```
 
 
+### Setting Prices via the Admin API
+
+Base prices are set per variant per currency. Use the [Admin API](../../api-reference/admin-api/introduction.md) — via the [Admin SDK](../sdk/admin/quickstart.md) — to set them individually or in bulk (`bulk_upsert` matches on variant + currency):
+
+
+```typescript Admin SDK
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+  baseUrl: 'https://store.example.com',
+  secretKey: 'sk_xxx',
+})
+
+// Set / change one variant's price in a currency
+await client.prices.create({ variant_id: 'variant_xxx', currency: 'USD', amount: 15.99 })
+
+// Upsert many at once
+await client.prices.bulkUpsert({
+  prices: [
+    { variant_id: 'variant_xxx', currency: 'USD', amount: 15.99 },
+    { variant_id: 'variant_xxx', currency: 'EUR', amount: 14.99 },
+  ],
+})
+```
+
+```bash CLI
+spree api post /prices/bulk_upsert -d '{
+  "prices": [
+    { "variant_id": "variant_xxx", "currency": "USD", "amount": 15.99 },
+    { "variant_id": "variant_xxx", "currency": "EUR", "amount": 14.99 }
+  ]
+}'
+```
+
+
 ## Price Lists  
 
 Price Lists allow you to create different pricing strategies based on various conditions. This enables advanced pricing scenarios like:
@@ -86,6 +127,44 @@ If no applicable Price List is found, the base price is used.
 | `match_policy` | How rules are evaluated: `all` (every rule must match) or `any` (at least one) |
 | `position` | Priority order (lower numbers = higher priority) |
 
+### Creating a Price List via the Admin API
+
+Rules and per-variant price overrides ride on the create/update payload. Each rule is a `{ type, preferences }` draft (see [Price Rules](#price-rules) below):
+
+
+```typescript Admin SDK
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+  baseUrl: 'https://store.example.com',
+  secretKey: 'sk_xxx',
+})
+
+const priceList = await client.priceLists.create({
+  name: 'EU wholesale',
+  match_policy: 'all',
+  rules: [
+    { type: 'customer_group_rule', preferences: { customer_group_ids: ['cg_xxx'] } },
+  ],
+  prices: [
+    { variant_id: 'variant_xxx', currency: 'EUR', amount: '19.99' },
+  ],
+})
+
+// Price Lists are draft until activated
+await client.priceLists.activate(priceList.id)
+```
+
+```bash CLI
+spree api post /price_lists -d '{
+  "name": "EU wholesale",
+  "match_policy": "all",
+  "prices": [{ "variant_id": "variant_xxx", "currency": "EUR", "amount": "19.99" }]
+}'
+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:
@@ -141,9 +220,9 @@ When resolving prices, Spree considers the full context of the request:
 | Quantity | Cart line item | The quantity for volume-based rules |
 | Date | Current time | For time-based Price List scheduling |
 
-The Store API automatically builds this context from the request headers (`X-Spree-Currency`, `X-Spree-Country`) and authentication state. You don't need to construct it manually — just make API requests and the correct price is resolved.
+The Store API automatically builds this context from the [request headers](../../api-reference/store-api/localization.md) (`X-Spree-Currency`, `X-Spree-Country`) and authentication state. You don't need to construct it manually — just make API requests and the correct price is resolved.
 
-> **INFO:** Price resolution results are cached for 15 minutes. Different context combinations are cached separately.
+> **INFO:** Price resolution runs per request — there is no in-process caching of resolved prices. The Store API instead relies on HTTP/CDN caching, with `Vary` headers keyed on the `X-Spree-Currency` and `X-Spree-Locale` request headers so each currency/locale combination is cached separately at the edge.
 
 ## Time-Based Pricing
 
@@ -170,7 +249,7 @@ Every time a base price amount changes, a `PriceHistory` record is created autom
 The prior price is available as an expandable field on product and variant endpoints:
 
 
-```typescript SDK
+```typescript Store SDK
 const product = await client.products.get('spree-tote', {
   expand: ['prior_price'],
 })
@@ -183,6 +262,12 @@ if (product.prior_price) {
 }
 ```
 
+```typescript Admin SDK
+const product = await adminClient.products.get('prod_86Rf07xd4z', {
+  expand: ['prior_price'],
+})
+```
+
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=prior_price' \
   -H 'X-Spree-API-Key: pk_xxx'
@@ -247,6 +332,7 @@ bundle exec rake spree:price_history:seed
 ## Related Documentation
 
 - [Products](products.md) — Products, Variants, and base prices
+- [Store SDK: Products](../sdk/store/products.md) — Fetching product and variant prices with the Store SDK
 - [Markets](markets.md) — Geographic regions with currency and locale
 - [Taxes](taxes.md) — Tax categories, tax rates, and zones
 - [Promotions](promotions.md) — Discount-based pricing via promotion rules

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

@@ -79,7 +79,7 @@ erDiagram
 ## Listing Products
 
 
-```typescript SDK
+```typescript Store SDK
 // List products with pagination
 const { data: products, meta } = await client.products.list({
   limit: 12,
@@ -100,7 +100,14 @@ const results = await client.products.list({
 
 // Sort products
 const sorted = await client.products.list({
-  sort: 'price_high_to_low',  // or: price_low_to_high, newest, name_a_z, name_z_a
+  sort: '-price',  // high to low; also: price, name, -name, available_on, -available_on, best_selling
+})
+```
+
+```typescript Admin SDK
+const { data: products, meta } = await adminClient.products.list({
+  limit: 12,
+  page: 1,
 })
 ```
 
@@ -124,7 +131,7 @@ See [Querying](../../api-reference/store-api/querying.md) for the full list of f
 ## Getting a Product
 
 
-```typescript SDK
+```typescript Store SDK
 // Get by slug
 const product = await client.products.get('spree-tote')
 
@@ -133,8 +140,13 @@ const detailed = await client.products.get('spree-tote', {
   expand: ['variants', 'media', 'option_types', 'categories'],
 })
 // detailed.variants => [{ id: "var_xxx", sku: "TOTE-S-R", price: { amount: "15.99", currency: "USD" }, ... }]
-// detailed.media => [{ id: "img_xxx", url: "https://cdn...", position: 1 }]
-// detailed.option_types => [{ name: "size", presentation: "Size", option_values: [...] }]
+// detailed.media => [{ id: "img_xxx", original_url: "https://cdn...", position: 1 }]
+// detailed.option_types => [{ name: "size", label: "Size", position: 1, kind: "..." }]
+// detailed.option_values => [{ name: "small", label: "S", option_type_name: "size", ... }]  // separate top-level array when expanded
+```
+
+```typescript Admin SDK
+const product = await adminClient.products.get('prod_86Rf07xd4z')
 ```
 
 ```bash cURL
@@ -143,17 +155,91 @@ curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=variants,m
 ```
 
 
+Pass `expand` to include related resources in a single response — see [expand relations](../../api-reference/store-api/relations.md) for how relation inclusion works.
+
+## Managing Products
+
+The examples above use the **Store API** (publishable key, read-only, customer-facing). To **create and manage** products, use the [Admin API](../../api-reference/admin-api/introduction.md) — via the [Admin SDK](../sdk/admin/quickstart.md) or the [Spree CLI](../cli/admin-api.md).
+
+A product's purchasable attributes (SKU, prices, stock) live on its **variants**, which you can create inline:
+
+
+```typescript Admin SDK
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+  baseUrl: 'https://store.example.com',
+  secretKey: 'sk_xxx',
+})
+
+const product = await client.products.create({
+  name: 'Premium T-Shirt',
+  description: 'Soft, organic cotton.',
+  status: 'active',
+  variants: [
+    {
+      sku: 'TSHIRT-S-NAVY',
+      options: [
+        { name: 'size', value: 'Small' },
+        { name: 'color', value: 'navy' },
+      ],
+      prices: [{ currency: 'USD', amount: 29.99 }],
+      stock_items: [{ stock_location_id: 'sloc_xxx', count_on_hand: 50 }],
+    },
+  ],
+})
+```
+
+```bash CLI
+spree api post /products -d '{
+  "name": "Premium T-Shirt",
+  "status": "active",
+  "variants": [{
+    "sku": "TSHIRT-S-NAVY",
+    "options": [{ "name": "size", "value": "Small" }],
+    "prices": [{ "currency": "USD", "amount": 29.99 }]
+  }]
+}'
+```
+
+
+Update, clone, or archive a product (deleting soft-deletes it):
+
+
+```typescript Admin SDK
+await client.products.update('prod_xxx', { name: 'Premium Tee', status: 'active' })
+await client.products.clone('prod_xxx')   // duplicate as a new draft
+await client.products.delete('prod_xxx')  // soft-delete
+```
+
+```bash CLI
+spree api patch /products/prod_xxx -d '{"name": "Premium Tee"}'
+spree api post /products/prod_xxx/clone
+spree api delete /products/prod_xxx
+```
+
+
+> **TIP:** Operating on many products at once? The Admin API has bulk actions — `bulkStatusUpdate`, `bulkAddToCategories`, `bulkAddTags`, `bulkDestroy`, and more. See the [Admin API endpoint index](../../api-reference/admin-api/endpoints.md).
+
 ## Product Filters
 
 Get available filter options for building a faceted search UI. Returns price ranges, option values, and categories with counts:
 
 
-```typescript SDK
+```typescript Store SDK
 const filters = await client.products.filters()
 // {
-//   option_types: [{ name: "size", option_values: [{ name: "Small", count: 12 }, ...] }],
-//   price_range: { min: 9.99, max: 199.99 },
-//   categories: [{ id: "ctg_xxx", name: "Clothing", count: 45 }],
+//   filters: [
+//     { id: "price", type: "price_range", min: 9.99, max: 199.99, currency: "USD" },
+//     { id: "availability", type: "availability", options: [{ id: "in_stock", count: 42 }] },
+//     { id: "opt_xxx", type: "option", name: "size", label: "Size", kind: "...",
+//       options: [{ id: "optv_xxx", name: "small", label: "Small", count: 12 }, ...] },
+//     { id: "categories", type: "category",
+//       options: [{ id: "ctg_xxx", name: "Clothing", permalink: "clothing", count: 45 }] },
+//   ],
+//   sort_options: [{ id: "price" }, ...],
+//   default_sort: "best_selling",
+//   total_count: 120,
 // }
 
 // Scoped to a specific category
@@ -206,6 +292,30 @@ When a product has option types, each unique combination of option values create
 
 The product's `default_variant_id` points to the first non-master variant (or the master variant if none exist).
 
+Add a variant to an existing product via the Admin API (SKU, prices, and stock all live on the variant):
+
+
+```typescript Admin SDK
+const variant = await client.products.variants.create('prod_xxx', {
+  sku: 'TEE-L-R',
+  options: [
+    { name: 'size', value: 'Large' },
+    { name: 'color', value: 'Red' },
+  ],
+  prices: [{ currency: 'USD', amount: 24.99 }],
+  stock_items: [{ stock_location_id: 'sloc_xxx', count_on_hand: 30 }],
+})
+```
+
+```bash CLI
+spree api post /products/prod_xxx/variants -d '{
+  "sku": "TEE-L-R",
+  "options": [{ "name": "size", "value": "Large" }],
+  "prices": [{ "currency": "USD", "amount": 24.99 }]
+}'
+```
+
+
 ## Option Types and Option Values
 
 Option types define the axes of variation for a product (e.g., Size, Color, Material). Option values are the specific choices within each type (e.g., Small, Medium, Large).
@@ -213,26 +323,62 @@ Option types define the axes of variation for a product (e.g., Size, Color, Mate
 A product must have at least one option type to have multiple variants. Option types and their values are included in the product response when requested:
 
 
-```typescript SDK
+```typescript Store SDK
 const product = await client.products.get('spree-tee', {
-  expand: ['option_types'],
+  expand: ['option_types', 'option_values'],
 })
 
+// Option types describe the axes of variation
 product.option_types?.forEach(optionType => {
-  console.log(optionType.presentation) // "Size"
-  optionType.option_values.forEach(value => {
-    console.log(value.presentation)    // "Small", "Medium", "Large"
-  })
+  console.log(optionType.label) // "Size"
+})
+
+// Option values are a separate flat array; each carries its parent's id/label
+product.option_values?.forEach(value => {
+  console.log(value.option_type_label, value.label) // "Size", "Small"
+})
+```
+
+```typescript Admin SDK
+const product = await adminClient.products.get('prod_k5nR8xLq', {
+  expand: ['variants'],
 })
 ```
 
 ```bash cURL
-curl 'https://api.mystore.com/api/v3/store/products/spree-tee?expand=option_types' \
+curl 'https://api.mystore.com/api/v3/store/products/spree-tee?expand=option_types,option_values' \
   -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
-> **INFO:** Option type `name` and `presentation` fields are translatable.
+> **INFO:** Option type `name` and `label` fields are translatable.
+
+Create option types (and their values) via the Admin API. Sending `option_values` replaces the full set, so include every value you want to keep:
+
+
+```typescript Admin SDK
+const optionType = await client.optionTypes.create({
+  name: 'size',
+  label: 'Size',
+  option_values: [
+    { name: 'small', label: 'Small', position: 1 },
+    { name: 'medium', label: 'Medium', position: 2 },
+    { name: 'large', label: 'Large', position: 3 },
+  ],
+})
+```
+
+```bash CLI
+spree api post /option_types -d '{
+  "name": "size",
+  "label": "Size",
+  "option_values": [
+    { "name": "small", "label": "Small" },
+    { "name": "medium", "label": "Medium" }
+  ]
+}'
+```
+
 
 ## Media
 
@@ -245,7 +391,7 @@ Every product response includes a `thumbnail_url` field — the URL to the first
 Use these fields for product listing pages to avoid loading all images:
 
 
-```typescript SDK
+```typescript Store SDK
 // List products — thumbnail_url is always included
 const { data: products } = await client.products.list({ limit: 12 })
 
@@ -254,6 +400,10 @@ products.forEach(product => {
 })
 ```
 
+```typescript Admin SDK
+const { data: products } = await adminClient.products.list({ limit: 12 })
+```
+
 ```bash cURL
 # thumbnail_url is always in the response — no ?expand needed
 curl 'https://api.mystore.com/api/v3/store/products?limit=12' \
@@ -268,22 +418,28 @@ curl 'https://api.mystore.com/api/v3/store/products?limit=12' \
 On the product detail page, expand `media` and `variants` to get the full set of images. Images are ordered by `position`:
 
 
-```typescript SDK
+```typescript Store SDK
 const product = await client.products.get('spree-tote', {
   expand: ['media', 'variants'],
 })
 
 // Product-level images (from master variant)
-product.media // [{ url: "https://cdn.../tote-front.jpg", position: 1 }, ...]
+product.media // [{ original_url: "https://cdn.../tote-front.jpg", position: 1 }, ...]
 
 // Each variant has its own thumbnail and media_count
 product.variants?.forEach(variant => {
-  variant.thumbnail    // "https://cdn.../tote-red.jpg" — always available
+  variant.thumbnail_url    // "https://cdn.../tote-red.jpg" — always available
   variant.media_count  // 3 — quick check without loading media
   variant.media        // full image array (only when ?expand=media)
 })
 ```
 
+```typescript Admin SDK
+const product = await adminClient.products.get('prod_86Rf07xd4z', {
+  expand: ['media'],
+})
+```
+
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=media,variants' \
   -H 'X-Spree-API-Key: pk_xxx'
@@ -322,7 +478,7 @@ For example:
 Products can belong to multiple categories.
 
 
-```typescript SDK
+```typescript Store SDK
 // List categories
 const { data: categories } = await client.categories.list()
 
@@ -335,6 +491,10 @@ const { data: products } = await client.categories.products.list('clothing/shirt
 })
 ```
 
+```typescript Admin SDK
+const { data: categories } = await adminClient.categories.list()
+```
+
 ```bash cURL
 # List categories
 curl 'https://api.mystore.com/api/v3/store/categories' \
@@ -371,7 +531,7 @@ Product `status` (`draft` / `active` / `archived`) is the **outer gate**: a Draf
 Publications appear in the API under `product_publications` when expanded; the same data is available through the `channels` association as a flat list of joined channels.
 
 
-```typescript SDK
+```typescript Admin SDK
 const product = await adminClient.products.get('prod_abc', {
   expand: ['product_publications', 'channels'],
 })
@@ -411,7 +571,7 @@ Two write surfaces serve different shapes:
 
   
 
-  ```typescript SDK
+  ```typescript Admin SDK
   await adminClient.products.update('prod_abc', {
     product_publications: [
       { channel_id: 'ch_online' },
@@ -438,7 +598,7 @@ Two write surfaces serve different shapes:
 
   
 
-  ```typescript SDK
+  ```typescript Admin SDK
   await adminClient.channels.addProducts('ch_online', {
     product_ids: ['prod_abc', 'prod_def'],
     published_at: '2026-07-01T00:00:00Z',
@@ -473,7 +633,7 @@ The two surfaces converge on the same `spree_product_publications` table — pic
 Storefronts and `client.products.list()` calls return only products published on the resolved channel (live within the publication window, with the product itself `active`). To scope a Store SDK request to a non-default channel — e.g. a POS app querying for the POS catalog — set the channel `code` on the client or per-request:
 
 
-```typescript SDK
+```typescript Store SDK
 // Client-level default
 const client = createClient({ baseUrl, publishableKey, channel: 'pos' })
 
@@ -481,6 +641,11 @@ const client = createClient({ baseUrl, publishableKey, channel: 'pos' })
 const posProducts = await client.products.list({}, { channel: 'pos' })
 ```
 
+```typescript Admin SDK
+// filter by the channel's code via Ransack (q[channels_code_eq])
+const { data: products } = await adminClient.products.list({ channels_code_eq: 'pos' })
+```
+
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products' \
   -H 'X-Spree-API-Key: pk_xxx' \
@@ -504,4 +669,5 @@ See [Sales Channels](channels.md) for the full channel lifecycle, including defa
 - [Media](media.md) — Image management
 - [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`
 - [Querying](../../api-reference/store-api/querying.md) — API filtering, sorting, and pagination