@spree/docs 0.1.230 → 0.1.232

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

@@ -22,6 +22,7 @@ flowchart LR
 
 Every file in a store is in the library, whether or not it's currently placed on anything. That means a file can be uploaded ahead of time, browsed, searched, and reused.
 
+
 ```typescript Admin SDK
 // Browse everything in the store
 const { data: media } = await adminClient.media.list()
@@ -30,6 +31,17 @@ const { data: media } = await adminClient.media.list()
 const { data: usage } = await adminClient.media.usage('med_xxx')
 ```
 
+```bash cURL
+# Browse everything in the store
+curl 'https://api.mystore.com/api/v3/admin/media' \
+  -H 'X-Spree-API-Key: sk_xxx'
+
+# Where is this file being used?
+curl 'https://api.mystore.com/api/v3/admin/media/med_xxx/usage' \
+  -H 'X-Spree-API-Key: sk_xxx'
+```
+
+
 | Field | What it tells you |
 |---|---|
 | `attached` | Whether the file is placed on anything yet |
@@ -43,6 +55,7 @@ const { data: usage } = await adminClient.media.usage('med_xxx')
 
 Placing a library file on a product creates a **new media row that shares the same underlying file**:
 
+
 ```typescript Admin SDK
 await adminClient.products.media.create('prod_xxx', {
   source_media_id: 'med_xxx',
@@ -51,6 +64,14 @@ await adminClient.products.media.create('prod_xxx', {
 })
 ```
 
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/products/prod_xxx/media' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "source_media_id": "med_xxx", "alt": "Worn over a navy jumper", "position": 2 }'
+```
+
+
 The copy gets its own alt text, its own position, and its own variant links — because the same photograph might be the third image on one product and the hero on another, with different alt text describing what matters in each context. What it doesn't get is a second copy of the bytes.
 
 > **NOTE:** This is why there's no single "shared asset" record to manage. Each placement is independently editable, while storage is shared. Detaching a photo from one product has no effect on any other.
@@ -59,6 +80,7 @@ The copy gets its own alt text, its own position, and its own variant links —
 
 A file in use can't be deleted by accident:
 
+
 ```typescript Admin SDK
 // Returns 422 with the list of places it's used
 await adminClient.media.delete('med_xxx')
@@ -67,6 +89,17 @@ await adminClient.media.delete('med_xxx')
 await adminClient.media.delete('med_xxx', { detach: true })
 ```
 
+```bash cURL
+# Returns 422 with the list of places it is used
+curl -X DELETE 'https://api.mystore.com/api/v3/admin/media/med_xxx' \
+  -H 'X-Spree-API-Key: sk_xxx'
+
+# Remove it from everywhere, then delete
+curl -X DELETE 'https://api.mystore.com/api/v3/admin/media/med_xxx?detach=true' \
+  -H 'X-Spree-API-Key: sk_xxx'
+```
+
+
 The dashboard shows you the usage list and asks before doing the second one. Check `usage` before offering a delete in your own tooling.
 
 ## What can carry media
@@ -227,6 +260,7 @@ curl -X POST 'https://api.mystore.com/api/v3/admin/products/prod_86Rf07xd4z/medi
 
 A hosted video is uploaded the same way an image is, with `media_type` telling Spree what it is. Add `poster_signed_id` to give it a still frame:
 
+
 ```typescript Admin SDK
 const video = await client.products.media.create('prod_86Rf07xd4z', {
   media_type: 'video',
@@ -236,14 +270,36 @@ const video = await client.products.media.create('prod_86Rf07xd4z', {
 })
 ```
 
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/store/products/prod_86Rf07xd4z/media' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "media_type": "video",
+    "signed_id": "SIGNED_VIDEO_BLOB_ID",
+    "poster_signed_id": "SIGNED_POSTER_BLOB_ID",
+    "alt": "Product in use"
+  }'
+```
+
+
 A poster can also be added or replaced later, on its own:
 
+
 ```typescript Admin SDK
 await client.products.media.update('prod_86Rf07xd4z', 'media_k5nR8xLq', {
   poster_signed_id: signedPosterBlobId,
 })
 ```
 
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/store/products/prod_86Rf07xd4z/media/media_k5nR8xLq' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "poster_signed_id": "SIGNED_POSTER_BLOB_ID" }'
+```
+
+
 > **INFO:** Spree serves an uploaded video as you uploaded it — it does not transcode. Keep files web-friendly (H.264 MP4 or WebM) so they play everywhere, and prefer an external video for long footage so the provider handles streaming.
 
 #### Posters
@@ -262,6 +318,7 @@ Spree does not extract a frame from an uploaded video, so give hosted video and
 
 `focal_point_x` and `focal_point_y` mark the part of an image that must stay in frame when a storefront crops it to a different shape. Both are fractions between 0 and 1, measured from the top left, so `{ x: 0.5, y: 0.5 }` is dead centre — which is also what a storefront should assume when they are null.
 
+
 ```typescript Admin SDK
 await client.products.media.update('prod_86Rf07xd4z', 'media_k5nR8xLq', {
   focal_point_x: 0.25,
@@ -269,6 +326,14 @@ await client.products.media.update('prod_86Rf07xd4z', 'media_k5nR8xLq', {
 })
 ```
 
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/store/products/prod_86Rf07xd4z/media/media_k5nR8xLq' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "focal_point_x": 0.25, "focal_point_y": 0.4 }'
+```
+
+
 Spree stores the focal point and serves it; the cropping itself is the storefront's decision, since only it knows the shape it needs.
 
 ### Named Variant Sizes
@@ -349,7 +414,7 @@ curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=media,vari
 
 **Response (media object):**
 
-```json
+```json Response
 {
   "id": "media_k5nR8xLq",
   "media_type": "image",

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

@@ -170,7 +170,7 @@ A custom field can take part in product listings — but only if you ask, becaus
 
 Setting either flag also makes the field **filterable**. Filter and sort with the field's `cf_` key, on both APIs:
 
-```
+```http
 GET /api/v3/store/products?q[cf_properties_material_i_cont]=wool
 GET /api/v3/store/products?sort=-cf_properties_weight
 GET /api/v3/admin/products?q[cf_properties_weight_gteq]=3.5

package/dist/developer/core-concepts/order-totals.md

@@ -22,6 +22,7 @@ flowchart TB
 
 ## The totals
 
+
 ```typescript Store SDK
 const order = await client.orders.get('or_xxx')
 
@@ -33,6 +34,13 @@ order.display_tax_total      // "$22.60"   all tax
 order.display_total          // "$138.10"  what the customer pays
 ```
 
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/orders/or_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'Authorization: Bearer $CUSTOMER_JWT'
+```
+
+
 | Attribute | What it sums |
 |---|---|
 | `item_total` | Line item prices, before tax and discounts |
@@ -49,7 +57,7 @@ order.display_total          // "$138.10"  what the customer pays
 
 Every total comes twice: `total` is the raw value, `display_total` is formatted for the order's currency.
 
-```json
+```json Response
 {
   "total": "138.10",
   "display_total": "$138.10"
@@ -74,6 +82,7 @@ The two exist because the same order can carry both: VAT already inside the good
 
 Every change to a cart returns the whole cart, totals included:
 
+
 ```typescript Store SDK
 const cart = await client.carts.items.create(cartId, {
   variant_id: 'var_xxx',
@@ -83,6 +92,14 @@ const cart = await client.carts.items.create(cartId, {
 cart.display_total // already correct
 ```
 
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/items' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "variant_id": "variant_xxx", "quantity": 2 }'
+```
+
+
 There is never a second "recalculate" request to make, and never a moment where the summary on screen disagrees with what the server thinks. Adding an item, entering an address, applying a code — each response carries the new numbers.
 
 The totals are worked out again at the moment the cart is completed, so a price that changed while the customer sat on the review page can't lead to the wrong charge.

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

@@ -114,7 +114,8 @@ Back-office work happens through the Admin API.
 ```typescript Admin SDK
 // Find orders needing attention
 const orders = await adminClient.orders.list({
-  filter: { payment_status_eq: 'paid', fulfillment_status_eq: 'unfulfilled' },
+  payment_status_eq: 'paid',
+  fulfillment_status_eq: 'unfulfilled',
 })
 
 // Cancel an order, recording why from your own list of reasons

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

@@ -9,7 +9,7 @@ Spree has a highly flexible payments model which allows multiple payment methods
 
 Payment methods typically represent a payment gateway. Gateways will process card payments, online bank transfers, buy-now-pay-later, wallet payments, and other types of payments. Spree also comes with a Check option for offline processing.
 
-The `Payment` model in Spree tracks payments against [Orders](orders). Payments relate to a `source` which indicates how the payment was made, and a `PaymentMethod`, indicating the processor used for this payment.
+The `Payment` model in Spree tracks payments against [Orders](orders.md). Payments relate to a `source` which indicates how the payment was made, and a `PaymentMethod`, indicating the processor used for this payment.
 
 When a payment is created, it is given a unique, 8-character identifier. This is used when sending the payment details to the payment processor. Without this identifier, some payment gateways mistakenly reported duplicate payments.
 
@@ -153,7 +153,8 @@ Payment methods where `session_required?` returns `false` don't need a payment s
 
 For these methods, the Store API allows creating a payment directly without going through the payment session flow:
 
-```typescript
+
+```typescript Store SDK
 const options = { spreeToken: cart.token }
 
 // Create a payment for a non-session payment method
@@ -166,6 +167,19 @@ const payment = await client.carts.payments.create(cart.id, {
 }, options)
 ```
 
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/payments' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'X-Spree-Token: CART_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "payment_method_id": "pm_xyz789",
+    "amount": "99.99",
+    "metadata": { "purchase_order_number": "PO-12345" }
+  }'
+```
+
+
 The payment is created in `checkout` state. When the order transitions to `complete`, Spree calls `process_payments!` which runs the payment method's `authorize` (or `purchase` if auto-capture is enabled). For manual payment methods like Check, this is a no-op that succeeds immediately — the payment moves to `pending` (or `completed` with auto-capture), allowing the order to complete.
 
 The merchant can later capture or void the payment from the Admin Panel once the actual payment is received (e.g., check arrives, bank transfer clears, cash is collected on delivery).
@@ -349,7 +363,8 @@ stateDiagram-v2
 
 **Create a Payment Session:**
 
-```typescript
+
+```typescript Store SDK
 const options = { spreeToken: cart.token }
 
 // Create a payment session for the selected payment method
@@ -364,9 +379,18 @@ console.log(session.external_id)              // e.g. 'pi_3ABC123' (Stripe Payme
 console.log(session.external_data.client_secret) // Use with Stripe.js or Adyen Drop-in
 ```
 
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/payment_sessions' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'X-Spree-Token: CART_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -d '{ "payment_method_id": "pm_xyz789", "amount": "99.99", "external_data": {} }'
+```
+
+
 **Response shape (`StorePaymentSession`):**
 
-```json
+```json Response
 {
   "id": "ps_abc123",
   "status": "pending",
@@ -386,7 +410,8 @@ console.log(session.external_data.client_secret) // Use with Stripe.js or Adyen
 
 **Update a Payment Session** (e.g., after order total changes):
 
-```typescript
+
+```typescript Store SDK
 const updated = await client.carts.paymentSessions.update(
   cart.id, session.id,
   { amount: '149.99' },
@@ -394,9 +419,19 @@ const updated = await client.carts.paymentSessions.update(
 )
 ```
 
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/payment_sessions/ps_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'X-Spree-Token: CART_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -d '{ "amount": "149.99" }'
+```
+
+
 **Complete a Payment Session** (after customer confirms payment on the frontend):
 
-```typescript
+
+```typescript Store SDK
 const completed = await client.carts.paymentSessions.complete(
   cart.id, session.id,
   { session_result: '...', external_data: {} },
@@ -405,14 +440,31 @@ const completed = await client.carts.paymentSessions.complete(
 console.log(completed.status) // 'completed'
 ```
 
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/payment_sessions/ps_xxx/complete' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'X-Spree-Token: CART_TOKEN' \
+  -H 'Content-Type: application/json' \
+  -d '{ "session_result": "...", "external_data": {} }'
+```
+
+
 > **WARNING:** Completing a payment session does **not** complete the order. You must call `POST /carts/:id/complete` separately after the session is completed. This separation prevents race conditions between the frontend and payment webhooks.
 
 **Complete the Order** (after the payment session is completed):
 
-```typescript
+
+```typescript Store SDK
 const order = await client.carts.complete(cart.id, options)
 ```
 
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/complete' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'X-Spree-Token: CART_TOKEN'
+```
+
+
 ### Payment Webhooks
 
 Spree provides a generic webhook endpoint at `POST /api/v3/webhooks/payments/:payment_method_id` that payment gateway extensions can use. When a payment provider sends a webhook (e.g., Stripe `payment_intent.succeeded`), Spree:
@@ -427,7 +479,7 @@ The background job creates/updates the Payment record, marks the session as comp
 
 Gateway extensions implement `parse_webhook_event` to normalize provider-specific payloads:
 
-```ruby
+```ruby server/app/models/my_gateway.rb
 class MyGateway < Spree::Gateway
   def parse_webhook_event(raw_body, headers)
     # Verify signature — raise WebhookSignatureError if invalid
@@ -591,7 +643,8 @@ sequenceDiagram
 
 **Create a Payment Setup Session:**
 
-```typescript
+
+```typescript Store SDK
 const options = { token: jwtToken }
 
 // Create a setup session for saving a payment method
@@ -604,9 +657,18 @@ const setupSession = await client.customer.paymentSetupSessions.create({
 console.log(setupSession.external_client_secret) // e.g. 'seti_ABC123_secret_xyz'
 ```
 
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/store/customers/me/payment_setup_sessions' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'Authorization: Bearer $CUSTOMER_JWT' \
+  -H 'Content-Type: application/json' \
+  -d '{ "payment_method_id": "pm_xyz789", "external_data": {} }'
+```
+
+
 **Response shape (`StorePaymentSetupSession`):**
 
-```json
+```json Response
 {
   "id": "pss_abc123",
   "status": "pending",
@@ -622,13 +684,22 @@ console.log(setupSession.external_client_secret) // e.g. 'seti_ABC123_secret_xyz
 
 **Get a Payment Setup Session:**
 
-```typescript
+
+```typescript Store SDK
 const session = await client.customer.paymentSetupSessions.get('pss_abc123', options)
 ```
 
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/customers/me/payment_setup_sessions/pss_abc123' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'Authorization: Bearer $CUSTOMER_JWT'
+```
+
+
 **Complete a Payment Setup Session** (after the customer completes setup on the frontend using the gateway SDK and `external_client_secret`):
 
-```typescript
+
+```typescript Store SDK
 const completed = await client.customer.paymentSetupSessions.complete(
   'pss_abc123',
   { external_data: {} },
@@ -638,6 +709,15 @@ console.log(completed.status)             // 'completed'
 console.log(completed.payment_source_id)  // e.g. 'card_xyz789' - the saved payment method
 ```
 
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/store/customers/me/payment_setup_sessions/pss_abc123/complete' \
+  -H 'X-Spree-API-Key: pk_xxx' \
+  -H 'Authorization: Bearer $CUSTOMER_JWT' \
+  -H 'Content-Type: application/json' \
+  -d '{ "external_data": {} }'
+```
+
+
 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.
 
 ## Supported Gateways
@@ -678,14 +758,6 @@ Spree publishes events throughout the payment lifecycle that you can subscribe t
 
 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 lifecycle, payment and fulfillment status
-- [Checkout Customization](carts.md) - Customizing the checkout flow
-- [Events](events.md) - Subscribe to payment events
-
 ## Two paths to a completed order
 
 A payment can finish in two places, and both have to end at the same result.
@@ -697,3 +769,11 @@ Whichever arrives first completes the order; the other finds the work already do
 > **WARNING:** Never treat the browser returning from a redirect as proof of payment. The provider's webhook is the authoritative signal — a customer can close the tab, and a browser response can be forged.
 
 Both paths can be replaced if your integration needs different behaviour — see [Dependencies](../customization/dependencies.md).
+
+## 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 lifecycle, payment and fulfillment status
+- [Checkout Customization](carts.md) - Customizing the checkout flow
+- [Events](events.md) - Subscribe to payment events

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

@@ -268,7 +268,7 @@ curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=prior_pric
 
 The response includes a `prior_price` object when expanded:
 
-```json
+```json Response
 {
   "id": "prod_xxx",
   "name": "Spree Tote",
@@ -287,15 +287,20 @@ The response includes a `prior_price` object when expanded:
 
 Price history tracking is enabled by default. To disable it (e.g., for non-EU stores):
 
-```ruby
-# config/initializers/spree.rb
-Spree.config do |config|
-  config.track_price_history = false
-  config.price_history_retention_days = 30 # default
-end
+
+```typescript Admin SDK
+await client.store.update({ preferred_track_price_history: false })
+```
+
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/store' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "preferred_track_price_history": false }'
 ```
 
-Price history retention defaults to 30 days and can be configured globally. A Rake task is provided for cleanup:
+
+Retention defaults to 30 days, set per store with the `price_history_retention_days` preference. A Rake task prunes anything older:
 
 
 ```bash Spree CLI (Docker)

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

@@ -213,6 +213,7 @@ spree api post /products -d '{
 
 For something with no options at all, send prices directly and skip the variants array — Spree forwards them to the product's single variant:
 
+
 ```typescript Admin SDK
 await adminClient.products.create({
   name: 'The Spree Handbook',
@@ -221,6 +222,18 @@ await adminClient.products.create({
 })
 ```
 
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/products' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "name": "The Spree Handbook",
+    "status": "active",
+    "prices": [{ "currency": "USD", "amount": "19.99" }]
+  }'
+```
+
+
 Don't pass both.
 
 Update, clone, or archive a product (deleting soft-deletes it):
@@ -346,7 +359,7 @@ await client.products.approve('prod_xxx')
 await client.products.reject('prod_xxx', { reason: 'Please add a photo showing scale.' })
 
 // The review queue
-const pending = await client.products.list({ filter: { status_eq: 'proposed' } })
+const pending = await client.products.list({ status_eq: 'proposed' })
 
 // Who decided, and when
 const product = await client.products.get('prod_xxx', { expand: ['submission'] })
@@ -448,6 +461,7 @@ There's no such thing as a product without one. A book with no size or colour st
 
 `default_variant_id` names the variant that represents the product — the price shown on a listing page, and what "add to cart" means before anyone picks anything.
 
+
 ```typescript Store SDK
 const product = await client.products.get('spree-tote')
 
@@ -456,6 +470,12 @@ product.price              // that variant's price
 product.variant_count      // 6
 ```
 
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products/spree-tote' \
+  -H 'X-Spree-API-Key: pk_xxx'
+```
+
+
 For a single-variant product that's the only variant. For a product with options it's the first one, unless you say otherwise. If the default is ever removed, another is promoted automatically — a product is never left without one.
 
 Products can also carry `buy_box_variant_id`, naming the variant a marketplace has chosen to feature when several sellers offer the same listing.
@@ -583,6 +603,7 @@ erDiagram
     }
 ```
 
+
 ```typescript Admin SDK
 const shoes = await adminClient.productTypes.create({
   name: 'Footwear',
@@ -601,6 +622,19 @@ await adminClient.products.create({
 })
 ```
 
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/product_types' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "name": "Footwear",
+    "option_type_ids": ["optt_size", "optt_color"],
+    "category_ids": ["ctg_footwear"],
+    "delivery_profile_id": "dp_standard"
+  }'
+```
+
+
 ### A type is a template, not a controller
 
 This is the part that determines how you should think about them.
@@ -620,10 +654,17 @@ Seeding is also **additive** — it adds what's missing and never removes what a
 
 If you *do* want an edited type to reach the products already using it, that's an explicit action:
 
+
 ```typescript Admin SDK
 const { products_count } = await adminClient.productTypes.applyToProducts('pt_xxx')
 ```
 
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/product_types/pt_xxx/apply_to_products' \
+  -H 'X-Spree-API-Key: sk_xxx'
+```
+
+
 It runs in the background and is additive like the rest — never a side effect of saving a type.
 
 > **INFO:** `required` on a type's custom field is **advisory** — it marks the field in the dashboard but isn't enforced on write, since Spree saves the product and its fields in two steps. Validate in your own tooling if you need it enforced.
@@ -878,6 +919,7 @@ curl 'https://api.mystore.com/api/v3/store/categories/clothing/shirts/products?l
 
 Collections work the same way from a storefront's point of view:
 
+
 ```typescript Store SDK
 const { data: collections } = await client.collections.list()
 
@@ -886,6 +928,15 @@ const { data: products } = await client.collections.products.list('summer-2025',
 })
 ```
 
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/collections' \
+  -H 'X-Spree-API-Key: pk_xxx'
+
+curl 'https://api.mystore.com/api/v3/store/collections/summer-2025/products?limit=12' \
+  -H 'X-Spree-API-Key: pk_xxx'
+```
+
+
 A rule-based collection is defined once and maintains itself — set it to match everything tagged `sale` and under $50, and products appear and disappear as those facts change. Ordering can be manual or by a rule such as newest first.
 
 ## Publications and Sales Channels

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

@@ -28,7 +28,7 @@ flowchart LR
 
 A query names what to measure and how to slice it. This is the whole surface:
 
-```json
+```json Query
 {
   "metrics": ["total_sales", "orders"],
   "dimensions": [{ "name": "completed_at", "grain": "week" }],
@@ -76,7 +76,7 @@ different clocks, so a payment total beside a units-received count is two
 reports wearing one table — the query refuses the mix rather than inventing a
 join between grains that have no honest relationship.
 
-```ruby
+```ruby server/config/initializers/spree.rb
 Spree.reporting.metric :total_sales,
   sql: 'SUM(%{orders}.total)', base: :orders, format: :money
 ```
@@ -118,7 +118,7 @@ row and inflate every other metric in the same query.
 Core's sales metrics follow the sequence merchants and accountants already use,
 so a Spree figure means what the same word means everywhere else:
 
-```
+```text
 gross_sales − discounts − returns = net_sales
 net_sales + shipping + duties + fees + taxes = total_sales
 ```
@@ -137,7 +137,7 @@ zero and margin over an incompletely-costed catalogue reads high.
 A dimension groups and filters. Its definition owns every behaviour keyed off
 it, which is what lets an extension-registered dimension work end to end:
 
-```ruby
+```ruby server/config/initializers/spree.rb
 Spree.reporting.dimension :channel, base: :orders, column: :channel_id,
   lookup: :channel,
   subject: -> { Spree::Channel }, key_scope: 'read_channels',
@@ -179,7 +179,7 @@ fulfill", "Open returns" and "Low stock" are the state of the store right now,
 with no time range and no currency. The registry holds these as **counters**
 beside metrics and dimensions, and `GET /dashboard/counters` evaluates them:
 
-```json
+```json Response
 {
   "channel_id": null,
   "counters": [