@spree/docs 0.1.181 → 0.1.183

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

@@ -1,325 +1,191 @@
 ---
 title: Inventory
-description: Stock locations, stock items, stock movements, and inventory tracking
+description: How Spree tracks stock across locations — what's on hand, what's spoken for, and what a shopper is allowed to buy.
 ---
 
-import { Since } from '/snippets/since.mdx';
-
 ## Overview
 
-Each [Variant](products.md#variants) has a `StockItem` that tracks its inventory at a specific location. A variant can have multiple stock items if it's available at multiple stock locations.
-
-When products are sold or returned, individual `InventoryUnit` records track each unit through the fulfillment process.
-
-Adding new inventory to an out-of-stock product that has backorders will first fill the backorders, then update the available count with the remainder.
-
-During checkout, Spree holds stock with time-limited [Stock Reservations](#stock-reservations) to prevent two customers from buying the same last unit simultaneously.
+Inventory answers one question a shopper cares about — *can I buy this?* — and several a merchant cares about: where is it, how much is left, and what happened to the rest.
 
-### Inventory Model Diagram
+Spree tracks stock **per location**. A variant doesn't have "a stock count"; it has a count at each warehouse or shop that carries it. That's what makes it possible to ship from the nearest location, or to let a customer collect in store.
 
 ```mermaid
 erDiagram
-    StockLocation {
-        string name
-        string admin_name
-        boolean active
-        boolean default
-        boolean backorderable_default
-        boolean propagate_all_variants
-    }
-
-    StockItem {
+    Variant ||--o{ StockLevel : "stocked at each location"
+    StockLocation ||--o{ StockLevel : "holds"
+    StockLevel ||--o{ StockMovement : "changed by"
+    StockLevel ||--o{ StockReservation : "held by checkouts"
+    Order ||--o{ Fulfillment : "ships as"
+    Fulfillment ||--o{ FulfillmentItem : "contains"
+
+    StockLevel {
         integer count_on_hand
+        integer allocated_count
         boolean backorderable
-        integer stock_location_id
-        integer variant_id
-    }
-
-    StockMovement {
-        integer quantity
-        string originator_type
-        integer originator_id
-        integer stock_item_id
-    }
-
-    StockTransfer {
-        string number
-        string reference
-        integer source_location_id
-        integer destination_location_id
-    }
-
-    InventoryUnit {
-        string state
-        integer variant_id
-        integer order_id
-        integer shipment_id
     }
-
-    StockReservation {
-        integer quantity
-        datetime expires_at
-        integer stock_item_id
-        integer line_item_id
-        integer order_id
+    StockLocation {
+        string name
+        boolean active
+        string country_code
     }
-
-    StockLocation ||--o{ StockItem : "has many"
-    StockLocation ||--o{ StockTransfer : "source"
-    StockLocation ||--o{ StockTransfer : "destination"
-    Variant ||--o{ StockItem : "has many"
-    Variant ||--o{ InventoryUnit : "has many"
-    StockItem ||--o{ StockMovement : "has many"
-    StockItem ||--o{ StockReservation : "has many"
-    StockTransfer ||--o{ StockMovement : "has many"
-    Order ||--o{ InventoryUnit : "has many"
-    Order ||--o{ StockReservation : "has many"
-    Shipment ||--o{ InventoryUnit : "has many"
 ```
 
-**Key relationships:**
-- **Stock Location** → Contains Stock Items (inventory per variant) and is the source/destination for Stock Transfers
-- **Stock Item** → Tracks quantity (`count_on_hand`) for a specific Variant at a specific Stock Location
-- **Stock Movement** → Records changes to Stock Item quantities (purchases, returns, transfers)
-- **Stock Transfer** → Moves inventory between Stock Locations, creating Stock Movements at source and destination
-- **Inventory Unit** → Represents individual units in [Orders](orders.md) and [Shipments](fulfillments.md)
-- **Stock Reservation** → Time-limited soft hold on a Stock Item during checkout, scoped to a specific Order and Line Item
-
-## Inventory Management
-
-### Stock Locations
-
-Stock Locations are the physical locations where your inventory is stored and shipped from.
-
-Stock Locations can be created in the Admin Panel under **Settings → Stock Locations**, or via the Admin API.
+## The three numbers
 
-Stock Locations have several attributes that define their properties and behavior within the Spree system. Below is a table outlining these attributes:
+A stock level carries two counts, and a third is derived from them. Keeping them apart is what stops a warehouse from disagreeing with a website.
 
-| Attribute         | Description                                                                 | Example Value       |
-|-------------------|-----------------------------------------------------------------------------|---------------------|
-| `name`            | The public name of the stock location. This is returned in Store API | Warehouse 1       |
-| `admin_name`       | The name used internally for the stock location. This is only returned in Admin API. | WH1 Domestic     |
-| `address1`        | The primary address line for the stock location.                           | 5th avenue     |
-| `address2`        | The secondary address line for the stock location.                         | Suite 100         |
-| `city`            | The city where the stock location is based.                                | New York        |
-| `state_id`        | The ID of the state where the stock location is based. This references the `State` model. | 1                 |
-| `country_id`      | The ID of the country where the stock location is based. This references the `Country` model. | 1                 |
-| `zipcode`         | The postal code for the stock location.                                    | 10001             |
-| `phone`           | The contact phone number for the stock location.                           | 555-1234          |
-| `active`          | A boolean indicating whether the stock location is active. Inactive stock locations will not be used in stock calculations or be available for selection during checkout. | `true`             |
-| `default`          | A boolean indicating whether the stock location is the default one used for new inventory operations. | `false`             |
-| `backorderable_default` | A boolean indicating whether new stock items in this location are backorderable by default. | `false` |
-| `propagate_all_variants` | A boolean indicating whether new stock items should be automatically created for all Store variants when a new stock location is added. | `false` |
+| | What it means |
+|---|---|
+| `count_on_hand` | What is physically on the shelf, right now |
+| `allocated_count` | How much of that is already spoken for by orders not yet shipped |
+| **`available_count`** | `count_on_hand − allocated_count` — what's actually sellable |
 
-Stock Locations can be easily used for tracking warehouses and other physical locations. They can be used to track separate sections of a warehouse (e.g. aisles, shelves, etc.) or to track different warehouses.
+> **NOTE:** **Selling an item does not reduce `count_on_hand`.** Placing an order raises `allocated_count`; the physical count only drops when the parcel actually ships.
+> 
+> This is deliberate. Until it leaves the building, the stock *is* still on the shelf — and a warehouse worker counting boxes should find the number Spree reports. Overselling shows up honestly as `allocated_count` exceeding what's on hand, rather than as an impossible negative count.
 
-You can easily use them with your Point of Sale (POS) system to track inventory at different locations.
+## Stock locations
 
-Create and manage stock locations via the [Admin API](../../api-reference/admin-api/introduction.md):
+A stock location is somewhere stock physically sits: a warehouse, a shop, a third-party fulfillment centre.
 
+| Attribute | Description |
+|---|---|
+| `name` | What staff call it |
+| `active` | Whether it can be used for new orders |
+| `default` | Used first when nothing else decides |
+| `country_code`, `state_code`, `city`, `postal_code` | Where it is — used for shipping rates and for finding the nearest one |
+| `backorderable_default` | Whether new stock levels here allow backorders |
+| `fulfillable` | Whether orders can ship from here, or it's display-only stock |
+| `pickup` | Whether customers can collect here |
 
 ```typescript Admin SDK
-import { createAdminClient } from '@spree/admin-sdk'
-
-const client = createAdminClient({
-  baseUrl: 'https://store.example.com',
-  secretKey: 'sk_xxx',
-})
+const { data: locations } = await adminClient.stockLocations.list()
 
-const location = await client.stockLocations.create({
-  name: 'Warehouse 1',
-  admin_name: 'WH1 Domestic',
-  default: true,
-  country_iso: 'US',
-  propagate_all_variants: true,
+await adminClient.stockLocations.create({
+  name: 'Berlin Warehouse',
+  country_code: 'DE',
+  city: 'Berlin',
+  active: true,
 })
-
-await client.stockLocations.update('sloc_xxx', { active: false })
-```
-
-```bash CLI
-spree api post /stock_locations -d '{
-  "name": "Warehouse 1",
-  "default": true,
-  "country_iso": "US",
-  "propagate_all_variants": true
-}'
 ```
 
+## Reading and adjusting stock
 
-### Stock Items
-
-Stock Items represent the inventory at a stock location for a specific variant. Stock item count on hand can be increased or decreased by creating stock movements.
-
-| Attribute         | Description                                                                 | Example Value       |
-|-------------------|-----------------------------------------------------------------------------|---------------------|
-| `stock_location_id` | References the stock location where the stock item belongs.                | `1`                 |
-| `variant_id`      | References the variant associated with the stock item.                     | `32`                |
-| `count_on_hand`   | The number of items available on hand.                                     | `150`               |
-| `backorderable`   | Indicates whether the stock item can be backordered.                       | `true`    |
-
-Stock items are created automatically — for all variants when a location has `propagate_all_variants`, or via a variant's `stock_items` on create. To adjust quantity or backorderable status, **update** the existing stock item via the Admin API. The example below uses a Ransack predicate (`stock_location_id_eq`) to [list a location's stock items](../../api-reference/admin-api/querying.md) before updating one:
+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.
 
 
 ```typescript Admin SDK
-// List a location's stock items, then adjust one
-const { data: items } = await client.stockItems.list({ stock_location_id_eq: 'sloc_xxx' })
+// Stock for one location
+const { data: levels } = await adminClient.stockLevels.list({
+  filter: { stock_location_id_eq: 'sl_xxx' },
+})
 
-await client.stockItems.update('si_xxx', {
+// Correct a single count
+await adminClient.stockLevels.update('slv_xxx', {
   count_on_hand: 150,
   backorderable: true,
 })
+
+// Set many at once — the right call for a nightly sync
+await adminClient.stockLevels.bulkUpsert({
+  stock_levels: [
+    { variant_id: 'var_xxx', stock_location_id: 'sl_xxx', count_on_hand: 40 },
+    { variant_id: 'var_yyy', stock_location_id: 'sl_xxx', count_on_hand: 12 },
+  ],
+})
 ```
 
 ```bash CLI
-spree api get /stock_items -q stock_location_id_eq=sloc_xxx
-spree api patch /stock_items/si_xxx -d '{"count_on_hand": 150, "backorderable": true}'
+spree api get '/stock_levels?q[stock_location_id_eq]=sl_xxx'
+spree api patch /stock_levels/slv_xxx -d '{"count_on_hand": 150}'
 ```
 
 
-### Stock Transfers
-
-Stock transfers allow you to move inventory in bulk from one stock location to another stock location. This is handy when you want to integrate with a POS system or other inventory management system. Or you can just rely on Spree being the source of truth for your inventory.
+> **WARNING:** Use `bulkUpsert` for feeds from a warehouse or ERP rather than a loop of single updates. It's one request instead of thousands, and it won't half-apply if the connection drops.
 
-> **INFO:** Stock Transfers can be created in the Admin dashboard or via the Admin API.
+## Stock movements
 
-Here's the list of attributes for the Stock Transfer model:
-
-| Attribute                | Description                                                                 | Example Value       |
-|--------------------------|-----------------------------------------------------------------------------|---------------------|
-| `number`                 | The unique number identifier for the stock transfer, generated automatically. | `T123456789`        |
-| `reference`              | An optional reference field for the stock transfer.                        | Transfer for Event |
-| `source_location_id`     | The ID of the stock location where the stock is transferred from.          | `2`                 |
-| `destination_location_id`| The ID of the stock location where the stock is transferred to.            | `3`                 |
-
-Create a transfer via the [Admin API](../../api-reference/admin-api/introduction.md), listing the variants and quantities to move. Omit `source_location_id` to record an incoming receipt from a vendor:
+Every change to stock is recorded as a movement, so "why is this number what it is" always has an answer.
 
+| Kind | When it happens |
+|---|---|
+| `received` | New stock arrives |
+| `allocated` | An order claims stock — `allocated_count` goes up |
+| `shipped` | A parcel leaves — `count_on_hand` goes down, the allocation is retired |
+| `released` | An allocation is given back, because an order was cancelled |
+| `adjusted` | A manual correction, such as after a stock count |
 
 ```typescript Admin SDK
-const transfer = await client.stockTransfers.create({
-  source_location_id: 'sloc_warehouse',
-  destination_location_id: 'sloc_store',
-  reference: 'Transfer for Event',
-  variants: [
-    { variant_id: 'variant_xxx', quantity: 20 },
-    { variant_id: 'variant_yyy', quantity: 5 },
-  ],
+const { data: movements } = await adminClient.stockMovements.list({
+  filter: { variant_id_eq: 'var_xxx' },
 })
 ```
 
-```bash CLI
-spree api post /stock_transfers -d '{
-  "source_location_id": "sloc_warehouse",
-  "destination_location_id": "sloc_store",
-  "variants": [{ "variant_id": "variant_xxx", "quantity": 20 }]
-}'
-```
-
-
-Stock transfers are crucial for managing inventory across multiple locations, ensuring that stock levels are accurate and up-to-date.
+Each movement points at what caused it — the order, the fulfillment, the transfer — so an audit trail reads as a sequence of business events rather than a list of numbers that changed.
 
-Each Stock Transfer will hold a list of Stock Movements.
+## What a shopper sees
 
-### Stock Movements
+For a storefront, all of the above collapses into one question, and the answer is already computed:
 
-Stock Movements track the movement of the inventory:
+```typescript Store SDK
+const product = await client.products.get('spree-tote')
 
-* when you move inventory between stock locations (via Stock Transfer)
-* when you add inventory to a stock location
-* when you remove inventory from a stock location
-* when customers purchase products
-* when customers return products
-
-Here's the list of attributes for the Stock Movement model:
-
-| Attribute         | Description                                                                 | Example Value       |
-|-------------------|-----------------------------------------------------------------------------|---------------------|
-| `stock_item_id`   | References the stock item that the movement belongs to.                     | `45`                |
-| `quantity`        | The quantity by which the stock item's count on hand is changed. Positive values indicate stock being added, while negative values indicate stock being removed. | `-10`               |
-| `originator_type` | The type of the originator of the stock movement. This is a polymorphic association. | `Spree::Shipment`      |
-| `originator_id`   | The ID of the originator of the stock movement. This is used in conjunction with `originator_type`. | `2`                 |
-
-Stock Movements are crucial for maintaining accurate inventory levels and for historical tracking of inventory adjustments.
-
-## Stock Reservations 
+product.variants.forEach((variant) => {
+  variant.in_stock     // can it be bought right now
+  variant.purchasable  // in stock, or backorderable
+})
+```
 
-Stock Reservations are a time-limited soft hold on stock during checkout. When a customer enters checkout, Spree holds the items in their cart for a limited time so other shoppers see reduced availability immediately. Two customers can no longer both pass the availability check on the same last unit only to have one of them fail at order completion.
+`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.
 
-### What changes for the storefront
+## Reservations during checkout
 
-Availability now subtracts the units other customers are holding in active checkouts. Whenever you read whether a variant is in stock — whether for a product page, cart line, or checkout summary — Spree returns the post-reservation number automatically. There's nothing for the storefront to compute and physical stock counts on each `StockItem` are never modified by reservations; reservations are an independent layer that's consulted at read time and cleaned up by background jobs.
+Without reservations, two customers can both see the last unit, both start checkout, and one discovers at the payment step that it's gone. That's a bad moment to find out.
 
-### Lifecycle
+A reservation is a short, time-limited hold placed when a customer enters checkout. Availability drops for everyone else immediately.
 
-| Trigger | Action |
+| Moment | What happens |
 |---|---|
-| Customer enters checkout | A reservation is created for each line item with an expiry timestamp |
-| Customer continues mutating the cart while in checkout | The expiry is pushed forward |
-| Customer completes the order | The reservation is released; physical stock is decremented as before |
-| Customer empties or abandons the cart | The reservation is released or expires automatically |
-
-Reservations attach to each line item; when a line item or order is removed, the reservation goes with it.
-
-### Configuration
+| Customer enters checkout | Their items are held, with an expiry |
+| They keep editing the cart | The expiry is pushed forward |
+| They complete the order | The hold becomes a real allocation |
+| They abandon it | The hold expires and stock returns |
 
-| Setting | Default | Purpose |
-|---|---|---|
-| `Spree::Config[:stock_reservations_enabled]` | `true` | Global kill switch. When `false`, reservations are not created and availability ignores them — behavior matches pre-5.5. |
-| `Spree::Config[:default_stock_reservation_ttl_minutes]` | `10` | Fallback hold duration when a Store doesn't override. |
-| `store.preferred_stock_reservation_ttl_minutes` | `10` | Per-Store override. Falls back to the global default only when explicitly unset/blank. |
+Reservations never touch `count_on_hand` — they're a separate layer consulted when availability is read. A backorderable item is skipped entirely, since unlimited supply needs no holding.
 
-TTL is a Store-level setting — it's a checkout-experience policy, not a warehouse property. A multi-location cart never has to merge conflicting TTLs from different warehouses.
+How long the hold lasts is a **store setting**, because it's a decision about the checkout experience rather than a property of a warehouse. Reservations can also be switched off entirely.
 
-### Insufficient stock during checkout
+> **INFO:** Expired reservations are cleaned up by a background job. Spree ships the job but does not schedule it — your app's job runner should run it every minute or so.
 
-When a cart change in checkout would push the order beyond available stock, the change is rejected up front. The customer sees a validation error immediately, instead of progressing through payment only to fail at the final submit.
+## Backorders
 
-### Background expiry
+A stock level marked `backorderable` can be sold past zero. Orders are accepted, allocated, and wait for stock.
 
-Abandoned checkouts leave behind expired reservation rows. Spree provides a job to clean them up but does **not** auto-schedule it — your application's job runner needs to invoke it periodically (every minute is typical). See the [5.4 to 5.5 upgrade guide](/v5/developer/upgrades/5.4-to-5.5#schedule-the-stock-reservations-expiry-job) for sidekiq-cron, solid_queue, and good_job snippets.
+When new stock arrives, backorders are filled first, and only the remainder becomes available to new customers — so the people who waited longest aren't overtaken by whoever happens to visit the site next.
 
-### Backorderable items
+## Moving stock between locations
 
-If a stock item is marked backorderable, it represents unlimited supply, so reservations are skipped entirely for that item. Availability is unaffected.
+A stock transfer moves inventory from one location to another, and reflects that this takes time: stock is booked out of the source, is in transit, and is received at the destination — where a partial receipt is a normal outcome, because sometimes not everything arrives.
 
-## Inventory Units
-
-As we mentioned above, back-ordered, sold, or shipped products are stored as individual `InventoryUnit` objects so they can have relevant information attached to them.
-
-We create `InventoryUnit` objects when:
-
-* a product is sold (they are added to the Shipment)
-* a product is returned
-
-Here's a list of attributes for the Inventory Unit model:
-
-| Attribute         | Description                                                                 | Example Value       |
-|-------------------|-----------------------------------------------------------------------------|---------------------|
-| `variant_id`      | References the variant associated with the inventory unit.                 | `32`                |
-| `order_id`        | References the order associated with the inventory unit.                   | `123`               |
-| `shipment_id`          | References the shipment associated with the inventory unit.                   | `77`                |
-| `state`           | The state of the inventory unit | `on_hand`      |
+```typescript Admin SDK
+const { data: transfers } = await adminClient.stockTransfers.list()
+```
 
-Inventory Units states are:
+## Turning tracking off
 
-* `on_hand` - the inventory unit is on hand
-* `backordered` - the inventory unit is backordered
-* `shipped` - the inventory unit is shipped
-* `returned` - the inventory unit has been returned
+Some things don't need counting — a service, a made-to-order item, a digital download. Tracking can be switched off, and those variants are always purchasable.
 
-> **NOTE:** As we noted before, when you add new Stock Items to a Variant (eg. via Admin Panel or Admin API), the first Inventory Units to fulfill are the backordered ones.
+This is a store-level setting, so a store that sells only digital goods needn't manage stock at all.
 
-## Disabling Inventory Tracking
+## Syncing from an external system
 
-If you don't need to track inventory, you can disable it:
+If your inventory truth lives in an ERP or a warehouse system, Spree can defer to it. The rule that matters: **the read path stays local.** Whether a variant is in stock is answered from Spree's own data, not by calling out to another system while a shopper waits for a product page.
 
-- **Per variant** — set `track_inventory` to `false` on a specific variant via the Admin Panel or Admin API
-- **Globally** — disable inventory tracking for the entire store in your Spree configuration
+Feeds come in through the bulk update above; live checks happen only at decision moments, like completing an order. See [Providers](../providers/overview.md).
 
-## Related Documentation
+## Related
 
-- [Products](products.md) - Product and variant management
-- [Shipments](fulfillments.md) - How inventory relates to shipments
-- [Orders](orders.md) - How inventory is allocated to orders
-- [Admin SDK resources](../sdk/admin/resources.md) - `stockLocations`, `stockItems`, and `stockTransfers` methods used in the examples above
-- [Admin API authentication](../../api-reference/admin-api/authentication.md) - How to obtain and scope the secret key (`sk_xxx`) used by these calls
+- [Products](products.md) — variants, the things stock is counted for
+- [Fulfillments](fulfillments.md) — how stock leaves the building
+- [Orders](orders.md) — where allocation happens
+- [Carts](carts.md) — checkout and reservations

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

@@ -3,9 +3,6 @@ title: Markets
 description: Configure Spree Markets to bundle geography, currency, and locale into distinct selling regions and run multi-region commerce from a single store.
 ---
 
-import { Since } from '/snippets/since.mdx';
-
-
 ## Overview
 
 Markets let you segment a single [Store](stores.md) into distinct geographic regions, each with its own currency, locale, and set of countries. For example, an international store might define:
@@ -50,14 +47,14 @@ erDiagram
 | `supported_locales` | All locales available in this market | `["en", "es"]` |
 | `tax_inclusive` | Whether prices include tax (affects display and checkout calculation) | `false` |
 | `default` | Whether this is the fallback market when no country match is found | `true` |
-| `countries` | List of countries in this market | `[{ iso: "US" }, { iso: "CA" }]` |
+| `country_codes` | Countries in this market, as ISO codes | `["US", "CA"]` |
 
 ## How Markets Work
 
 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.
 
 ```
-Customer's Country → Market → Currency + Locale + Tax Zone
+Customer's Country → Market → Currency + Locale + Tax treatment
 ```
 
 The resolution chain:
@@ -65,7 +62,7 @@ The resolution chain:
 1. Customer's country is detected (from URL, geolocation, `X-Spree-Country` header, or manual selection)
 2. Spree finds the market containing that country
 3. The market's currency and locale become the defaults for the session
-4. The market's tax zone determines whether prices are shown with or without tax
+4. The market's tax setting determines whether prices are shown with or without tax
 
 If no market matches the customer's country, the store's **default market** is used.
 
@@ -215,9 +212,9 @@ The `tax_inclusive` flag on a market controls how prices are displayed and calcu
 - **`tax_inclusive: true`** (common in Europe) — the price shown to the customer already includes tax
 - **`tax_inclusive: false`** (common in the US) — tax is added at checkout on top of the displayed price
 
-Each market also resolves a **tax zone** from its default country. This zone determines which tax rates apply when browsing products — before the customer enters a shipping address. Once the customer provides an address at checkout, the actual shipping address takes over for tax calculation.
+This matters because prices are shown long before anyone knows where the shopper lives. The market's own country supplies the assumed rate for browsing; once a shipping address is entered at checkout, that address takes over and the real rate applies.
 
-See [Taxes](taxes.md) for details on tax zones and rates.
+A market also chooses **which tax provider works out its numbers** — Spree's own rate tables in a simple market, an external tax service in a complicated one. See [Taxes](taxes.md).
 
 ## Pricing Integration
 
@@ -247,7 +244,7 @@ const northAmerica = await client.markets.create({
   name: 'North America',
   currency: 'USD',
   default_locale: 'en',
-  country_isos: ['US', 'CA'],
+  country_codes: ['US', 'CA'],
   default: true,
 })
 
@@ -258,7 +255,7 @@ const europe = await client.markets.create({
   default_locale: 'de',
   supported_locales: ['de', 'en', 'fr'],
   tax_inclusive: true,
-  country_isos: ['DE', 'FR', 'AT', 'NL'],
+  country_codes: ['DE', 'FR', 'AT', 'NL'],
 })
 ```
 
@@ -267,7 +264,7 @@ spree api post /markets -d '{
   "name": "North America",
   "currency": "USD",
   "default_locale": "en",
-  "country_isos": ["US", "CA"],
+  "country_codes": ["US", "CA"],
   "default": true
 }'
 ```
@@ -291,6 +288,6 @@ spree api delete /markets/market_xxx
 
 - [Markets (Store SDK)](../sdk/store/markets.md) — Listing, resolving, and reading markets from the Store SDK
 - [Pricing](pricing.md) — Price Lists, Price Rules, and the Pricing Context
-- [Addresses](addresses.md) — Countries, States, and Zones
+- [Addresses](addresses.md) — Countries, states, and address forms
 - [Localization](../../api-reference/store-api/localization.md) — Locale, currency, and country headers in API requests
 - [Translations](translations.md) — Resource and UI translations

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

@@ -4,8 +4,6 @@ sidebarTitle: "Media"
 description: Manage product media in Spree — images, hosted and external video, named variants, focal points, and how media is uploaded, resized, and served via the Store API.
 ---
 
-import { Since } from '/snippets/since.mdx';
-
 ## Overview
 
 Spree handles uploads, processing, and delivery for product media. Images are automatically converted to WebP format and preprocessed into multiple sizes for optimal performance.
@@ -21,7 +19,7 @@ A media record carries:
 - **Preprocessed named variants** for fast delivery
 - **`variant_ids`** — which product variants the media represents. An empty array means it represents the product as a whole.
 
-### Product-level Gallery 
+### Product-level Gallery
 
 In Spree 5.5 the **product** is the default owner of media. Before 5.5, every image was pinned to a specific variant (usually the master), and sharing the same image across variants meant re-uploading the file. From 5.5 onward, an image lives on the product, and any subset of variants can reference it through `variant_ids` — without duplicating the underlying file.
 
@@ -106,7 +104,7 @@ The Store API's `media` field on a product returns its gallery — product-level
 
 This dual rendering means existing storefronts keep working during the upgrade; new uploads attach to the product, and you opt into a [one-shot migration](/v5/developer/upgrades/5.4-to-5.5) to re-home legacy variant-pinned data when convenient.
 
-### Video 
+### Video
 
 A product gallery can hold video as well as images. Spree supports both ways merchants usually have it:
 
@@ -186,7 +184,7 @@ Where the poster comes from, in order:
 
 Spree does not extract a frame from an uploaded video, so give hosted video and Vimeo links a poster if you want them to show a still.
 
-### Focal Point 
+### Focal Point
 
 `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.
 
@@ -199,7 +197,7 @@ await client.products.media.update('prod_86Rf07xd4z', 'media_k5nR8xLq', {
 
 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 
+### Named Variant Sizes
 
 When an image is uploaded, Spree automatically generates optimized versions in the background:
 
@@ -319,13 +317,13 @@ curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=media,vari
 | `focal_point_x` | number \| null | Horizontal focal point (0.0–1.0) |
 | `focal_point_y` | number \| null | Vertical focal point (0.0–1.0) |
 | `external_video_url` | string \| null | External video URL (YouTube/Vimeo) |
-| `video_provider` | string \| null | `youtube` or `vimeo`, derived from the link  |
-| `video_embed_url` | string \| null | Embeddable player URL, derived from the link  |
-| `video_url` | string \| null | Uploaded video file URL  |
-| `poster_url` | string \| null | Still frame for a video  |
+| `video_provider` | string \| null | `youtube` or `vimeo`, derived from the link |
+| `video_embed_url` | string \| null | Embeddable player URL, derived from the link |
+| `video_url` | string \| null | Uploaded video file URL |
+| `poster_url` | string \| null | Still frame for a video |
 | `original_url` | string \| null | Full-size image URL (inline disposition) |
 | `mini_url` ... `xlarge_url` | string \| null | Named variant URLs |
-| `download_url` | string \| null | Same blob as `original_url` but with `Content-Disposition: attachment`. Admin API only.  |
+| `download_url` | string \| null | Same blob as `original_url` but with `Content-Disposition: attachment`. Admin API only. |
 
 ## Image Processing