@spree/docs 0.1.229 → 0.1.231

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

@@ -62,6 +62,7 @@ Note the difference between `value` and `amount`. `value` is the rule — "10 pe
 
 Whatever produced them, the rows read the same way:
 
+
 ```typescript Store SDK
 const cart = await client.carts.get(cartId)
 
@@ -75,6 +76,12 @@ cart.discounts.forEach((discount) => {
 })
 ```
 
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx'
+```
+
+
 Applying a coupon code, and what decides whether it's accepted, belongs to [Promotions](promotions.md).
 
 ## Manual discounts

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

@@ -57,7 +57,7 @@ The distinction matters when choosing what to listen for. `order.updated` fires
 
 An event carries the record it's about, serialized:
 
-```json
+```json Event payload
 {
   "id": "or_86Rf07xd4z",
   "number": "R123456789",
@@ -78,13 +78,19 @@ Point a webhook at your endpoint and subscribe it to the events you care about.
 
 A subscriber is a small class that names the events it wants and does something when one arrives.
 
-```bash
+
+```bash Spree CLI (Docker)
+spree generate subscriber OrderPlaced order.placed
+```
+
+```bash Without Spree CLI
 bin/rails g spree:subscriber OrderPlaced order.placed
 ```
 
+
 The generator writes the class, a test, and — the step that's easy to forget — registers it.
 
-```ruby app/subscribers/order_placed_subscriber.rb
+```ruby server/app/subscribers/order_placed_subscriber.rb
 class OrderPlacedSubscriber < Spree::Subscriber
   subscribes_to 'order.placed'
 
@@ -99,14 +105,14 @@ end
 
 A subscriber can listen to several events, or to a whole family:
 
-```ruby
+```ruby server/app/subscribers/order_placed_subscriber.rb
 subscribes_to 'order.placed', 'order.canceled'
 subscribes_to 'order.*'
 ```
 
 Subscribers must be registered — they aren't discovered automatically, because a subscriber that starts running because of where its file sits is hard to reason about:
 
-```ruby config/initializers/spree.rb
+```ruby server/config/initializers/spree.rb
 Rails.application.config.after_initialize do
   Spree.subscribers << OrderPlacedSubscriber
 end
@@ -118,7 +124,7 @@ By default a subscriber runs as a background job, so a slow API call in your cod
 
 That's almost always what you want. If you genuinely need to run inside the same transaction, you can ask to:
 
-```ruby
+```ruby server/app/subscribers/order_placed_subscriber.rb
 subscribes_to 'order.placed', async: false
 ```
 
@@ -128,7 +134,7 @@ subscribes_to 'order.placed', async: false
 
 Anything in your own code can announce something, and subscribers and webhooks treat it like any built-in event:
 
-```ruby
+```ruby server/app/services/fraud_check.rb
 order.publish_event('order.flagged_for_review')
 ```
 

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

@@ -79,6 +79,7 @@ curl -X POST 'https://api.mystore.com/api/v3/admin/orders/or_xxx/fees' \
 
 Fees are visible to the storefront on the cart and the order, so a customer sees what they're being charged before they pay:
 
+
 ```typescript Store SDK
 const cart = await client.carts.get(cartId)
 
@@ -90,6 +91,12 @@ cart.fees.forEach((fee) => {
 cart.display_fee_total // "$7.50"
 ```
 
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx'
+```
+
+
 ## Fees and tax
 
 Fees are **taxable by default** — a handling charge in a VAT country is itself subject to VAT, and Spree writes tax lines against the fee accordingly.
@@ -122,6 +129,7 @@ For any of this to work, the goods have to be described in the language customs
 | `country_of_origin` | Where it was made, as an ISO country code — not where it ships from | `PT` |
 | `customs_description` | A plain description for the declaration, when the product name isn't clear enough | `Cotton t-shirt` |
 
+
 ```typescript Admin SDK
 await adminClient.products.variants.update('prod_xxx', 'var_xxx', {
   hs_code: '6109.10',
@@ -130,6 +138,18 @@ await adminClient.products.variants.update('prod_xxx', 'var_xxx', {
 })
 ```
 
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/products/prod_xxx/variants/var_xxx' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "hs_code": "6109.10",
+    "country_of_origin": "PT",
+    "customs_description": "Cotton t-shirt"
+  }'
+```
+
+
 > **WARNING:** `country_of_origin` is where the item was **manufactured**, not the warehouse it leaves from. Duty rates and trade agreements turn on origin, so getting this wrong produces the wrong charge — and can hold a parcel at the border.
 
 These fields are editable per variant and in the bulk product editor. They're also what a carrier integration puts on the customs declaration for an international label — required for cross-border parcels, ignored for domestic ones.

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

@@ -322,7 +322,7 @@ integration's metadata, not in the parcel's lifecycle vocabulary. What core
 needs to know is only *whether the parcel may go out yet*, and that is exactly
 what the fulfill workflow's validate hook expresses:
 
-```ruby
+```ruby server/config/initializers/spree.rb
 Spree.hooks.register('fulfillments.fulfill.validate') do |flow|
   work_order = MyApp::WorkOrder.find_by(fulfillment: flow.fulfillment)
   flow.reject!('still in production') unless work_order&.completed?
@@ -337,7 +337,7 @@ orders render `fulfilled` as "ready for pickup".
 by it, reports group by it, or webhooks fire on entering it, make it a
 first-class status:
 
-```ruby config/initializers/spree.rb
+```ruby server/config/initializers/spree.rb
 Spree::Fulfillment.add_status('in_production', after: 'unfulfilled')
 ```
 
@@ -346,7 +346,7 @@ a valid value. Moving into it is deliberately not declarative — write a small
 workflow, which is also where the printer submission or the workshop handoff
 belongs:
 
-```ruby
+```ruby server/app/workflows/my_app/fulfillments/start_production.rb
 class MyApp::Fulfillments::StartProduction < Spree::Workflow
   def perform(fulfillment:)
     super

package/dist/developer/core-concepts/imports-exports.md

@@ -40,7 +40,7 @@ An export is created, runs in the background, and produces a file to download.
 
 ```typescript Admin SDK
 const exportJob = await adminClient.exports.create({
-  type: 'Spree::Exports::Products',
+  type: 'products',
 })
 
 // Poll until it's done
@@ -50,7 +50,7 @@ status.download_url // available once completed
 ```
 
 ```bash CLI
-spree api post /exports -d '{"type": "Spree::Exports::Products"}'
+spree api post /exports -d '{"type": "products"}'
 spree api get /exports
 ```
 
@@ -59,13 +59,22 @@ spree api get /exports
 
 An export can carry the same filters as the listing it came from, so "export what I'm looking at" does what a merchant expects — this quarter's orders, this brand's products, not the entire table.
 
+
 ```typescript Admin SDK
 await adminClient.exports.create({
-  type: 'Spree::Exports::Orders',
+  type: 'orders',
   filters: { completed_at_gteq: '2026-01-01' },
 })
 ```
 
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/exports' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "type": "orders", "filters": { "completed_at_gteq": "2026-01-01" } }'
+```
+
+
 In the dashboard this is the Export button on any list — whatever filters are applied come along.
 
 ## Importing
@@ -76,7 +85,7 @@ Importing has an extra step, because a file from somewhere else won't have Spree
 
 ```typescript Admin SDK
     const importJob = await adminClient.imports.create({
-      type: 'Spree::Imports::Products',
+      type: 'products',
       file: uploadedFileId,
     })
     ```
@@ -117,9 +126,10 @@ Some rows will fail. A price with a currency symbol in it, a required field left
 
 **A failed row doesn't stop the import.** The good rows are imported; the bad ones are set aside with the reason.
 
+
 ```typescript Admin SDK
 const { data: failures } = await adminClient.imports.rows.list(importJob.id, {
-  filter: { status_eq: 'failed' },
+  status_eq: 'failed',
 })
 
 failures.forEach((row) => {
@@ -131,6 +141,12 @@ failures.forEach((row) => {
 await adminClient.imports.retryFailedRows(importJob.id)
 ```
 
+```bash cURL
+curl 'https://api.mystore.com/api/v3/admin/imports/imp_xxx/rows?q[status_eq]=failed' \
+  -H 'X-Spree-API-Key: sk_xxx'
+```
+
+
 Retrying re-runs only the failures, so a file where three rows out of ten thousand were wrong doesn't need re-importing whole.
 
 > **WARNING:** A value that isn't a number is rejected, never guessed at. A price written as `"12,50"` fails rather than being read as `1250` — which would be a hundredfold overcharge. Fix the file rather than hoping the import is lenient.

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

@@ -51,7 +51,17 @@ A stock level carries four counts, and a fifth is derived from them. Keeping the
 | `incoming_count` | How much is on its way here — on a purchase order placed with a supplier, or a transfer already in transit |
 | **`available_count`** | `count_on_hand − allocated_count` — what's actually sellable, before checkout holds |
 
-Reserved and incoming are kept as counters rather than worked out on every read, because the Inventory page in the dashboard reads them for every row, many times a day, and only a handful of things change them: entering or leaving checkout moves reserved; marking a purchase order ordered or a transfer in transit adds to incoming, and receiving, closing, cancelling or reopening the document takes the remainder back off. Nothing else writes them. If a figure ever looks wrong, `rake spree:stock:recount_levels` recomputes both from their sources and reports every row it corrected — the same task the 6.0 upgrade runs to fill them in for existing stock.
+Reserved and incoming are kept as counters rather than worked out on every read, because the Inventory page in the dashboard reads them for every row, many times a day, and only a handful of things change them: entering or leaving checkout moves reserved; marking a purchase order ordered or a transfer in transit adds to incoming, and receiving, closing, cancelling or reopening the document takes the remainder back off. Nothing else writes them. If a figure ever looks wrong, one task recomputes both from their sources and reports every row it corrected — the same task the 6.0 upgrade runs to fill them in for existing stock.
+
+
+```bash Spree CLI (Docker)
+spree rake spree:stock:recount_levels
+```
+
+```bash Without Spree CLI
+bundle exec rake spree:stock:recount_levels
+```
+
 
 A transfer counts as incoming from the moment it is marked in transit, not when it is drafted: until the van leaves, nothing is moving. Units a delivery rejects at the dock leave incoming too — they are recorded on the receipt, but they are not coming.
 
@@ -74,6 +84,7 @@ A stock location is somewhere stock physically sits: a warehouse, a shop, a thir
 | `pickup_enabled` | Whether customers can collect here |
 | `returns_enabled` | Whether customers can bring returns here |
 
+
 ```typescript Admin SDK
 const { data: locations } = await adminClient.stockLocations.list()
 
@@ -85,6 +96,12 @@ await adminClient.stockLocations.create({
 })
 ```
 
+```bash cURL
+curl 'https://api.mystore.com/api/v3/admin/stock_locations' \
+  -H 'X-Spree-API-Key: sk_xxx'
+```
+
+
 ## Reading and adjusting stock
 
 A stock level is the intersection of a variant and a location. They're created for you — for every variant when a location propagates all variants, or as variants are added.
@@ -131,6 +148,7 @@ Every change to stock is recorded as a movement, so "why is this number what it
 | `released` | An allocation is given back, because an order was cancelled |
 | `adjusted` | A manual correction, such as after a stock count |
 
+
 ```typescript Admin SDK
 // Everything that happened to one SKU, across every location
 const { data: movements } = await adminClient.stockMovements.list({
@@ -138,6 +156,12 @@ const { data: movements } = await adminClient.stockMovements.list({
 })
 ```
 
+```bash cURL
+curl 'https://api.mystore.com/api/v3/admin/stock_movements?q[stock_level_variant_id_eq]=variant_xxx' \
+  -H 'X-Spree-API-Key: sk_xxx'
+```
+
+
 Each movement points at what caused it — the order, the fulfillment, the transfer, the purchase order, and for stock that arrived, the delivery it came in on — so an audit trail reads as a sequence of business events rather than a list of numbers that changed.
 
 A movement that arrived through a purchase order also carries what the units cost, so "what did this stock cost us" is answerable from the ledger rather than reconstructed from the orders that bought it.
@@ -146,6 +170,7 @@ A movement that arrived through a purchase order also carries what the units cos
 
 For a storefront, all of the above collapses into one question, and the answer is already computed:
 
+
 ```typescript Store SDK
 const product = await client.products.get('spree-tote')
 
@@ -155,6 +180,12 @@ product.variants.forEach((variant) => {
 })
 ```
 
+```bash cURL
+curl 'https://api.mystore.com/api/v3/store/products/spree-tote' \
+  -H 'X-Spree-API-Key: pk_xxx'
+```
+
+
 `in_stock` already accounts for what's allocated and what other shoppers are holding in checkout. There is nothing to compute client-side, and no separate inventory request to make.
 
 ## Reservations during checkout
@@ -188,6 +219,7 @@ A stock transfer moves inventory from one location to another, and reflects that
 
 That is four steps, not one. A transfer is planned as a draft, packed, sent, and finally counted in:
 
+
 ```typescript Admin SDK
 const transfer = await adminClient.stockTransfers.create({
   source_location_id: 'sloc_xxx',
@@ -204,6 +236,14 @@ await adminClient.stockTransfers.stockReceipts.create(transfer.id, {
 })
 ```
 
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/stock_transfers' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "source_location_id": "sl_a", "destination_location_id": "sl_b" }'
+```
+
+
 | Status | What it means |
 |---|---|
 | `draft` | A plan. Lines can still change; nothing has moved |
@@ -220,6 +260,7 @@ Two things follow from the middle step. Availability at the destination does not
 
 Stock that comes from a supplier is a purchase order, not a transfer — it has a supplier, a cost per unit and a date it was promised for, none of which apply to moving goods you already own.
 
+
 ```typescript Admin SDK
 const order = await adminClient.purchaseOrders.create({
   supplier_id: 'sup_xxx',
@@ -238,6 +279,14 @@ await adminClient.purchaseOrders.stockReceipts.create(order.id, {
 })
 ```
 
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/purchase_orders' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "supplier_id": "sup_xxx", "stock_location_id": "sl_xxx" }'
+```
+
+
 | Status | What it means |
 |---|---|
 | `draft` | Being put together. Lines and costs can still change |
@@ -255,31 +304,54 @@ Purchase orders export to CSV, one row per line, which is the file a merchant se
 
 Suppliers themselves are an address book, kept per store:
 
+
 ```typescript Admin SDK
 const { data: suppliers } = await adminClient.suppliers.list()
 ```
 
+```bash cURL
+curl 'https://api.mystore.com/api/v3/admin/suppliers' \
+  -H 'X-Spree-API-Key: sk_xxx'
+```
+
+
 ## Counting a delivery in
 
 Transfers and purchase orders are received the same way: each delivery is a **stock receipt**, numbered and dated, carrying the packing-slip reference and — per line — what was accepted and what was refused, with a reason.
 
+
 ```typescript Admin SDK
 const { data: deliveries } = await adminClient.purchaseOrders.stockReceipts.list(order.id, {
   expand: ['items'],
 })
 ```
 
+```bash cURL
+curl 'https://api.mystore.com/api/v3/admin/purchase_orders/po_xxx/stock_receipts' \
+  -H 'X-Spree-API-Key: sk_xxx'
+```
+
+
 A receipt records *this delivery's* counts, not running totals: a second box adds to the first rather than restating it. Accepted units land on the destination's shelf, each as a `received` movement that names the receipt. Refused units are recorded and never stocked; the reason is one of `damaged`, `wrong_item`, `expired` or `other`. Omit `items` to count in everything still outstanding, intact.
 
 > **NOTE:** **Refused units count differently on the two documents.** A supplier's refused units are still owed — the goods go back, and the order stays `partially_received` until they are replaced. A transfer's refused units have *arrived*, in whatever state: a crushed unit is not still in the van, so it counts toward the trip being over.
 
 When the balance is not coming — the supplier is out of stock, the missing units fell off the van — the document is **closed short**: it settles in `received` with `closed_short_at` and the reason recorded, and the outstanding count stays on each line as the record of the gap. Nothing moves.
 
+
 ```typescript Admin SDK
 await adminClient.purchaseOrders.close(order.id, { reason: 'Supplier out of stock' })
 await adminClient.stockTransfers.close(transfer.id, { reason: 'Two fell off the van' })
 ```
 
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/purchase_orders/po_xxx/close' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "reason": "Supplier out of stock" }'
+```
+
+
 ## The Inventory page
 
 The dashboard's Inventory section opens on a list with one row per variant per location: on hand, allocated, reserved, available and incoming — the page uses the column names, with the location as a filter and SKU or product name as the search. Every figure on it is a column read off the stock level.

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

@@ -14,8 +14,8 @@ Markets let you segment a single [Store](stores.md) into distinct geographic reg
 ```mermaid
 erDiagram
     Store ||--o{ Market : "has many"
-    Market ||--o{ MarketCountry : "has many"
-    MarketCountry }o--|| Country : "belongs to"
+    Market ||--o{ MarketCountry : "covers"
+    Market ||--o{ Order : "records"
 
     Store {
         string name
@@ -31,9 +31,8 @@ erDiagram
         boolean default
     }
 
-    Country {
-        string iso
-        string name
+    MarketCountry {
+        string country_code
     }
 ```
 
@@ -53,7 +52,7 @@ erDiagram
 
 When a customer visits your store, their country determines which market applies. The market then sets the currency, locale, and tax behavior for that session.
 
-```
+```text
 Customer's Country → Market → Currency + Locale + Tax treatment
 ```
 

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