@spree/docs 0.1.93 → 0.1.94

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

@@ -20,7 +20,7 @@ Every store ships with one default channel named *Online Store*. You can add mor
 | `code` | URL-safe slug, stable identifier sent via the `X-Spree-Channel` header | `pos` |
 | `active` | When `false`, the channel stops accepting orders | `true` |
 | `default` | Exactly one channel per store is the default. Used as a fallback when no channel header is present and as the auto-publish target for new products | `true` |
-| `preferred_order_routing_strategy` | Optional per-channel override of the store's [Order Routing](shipments.md#order-routing) strategy | `Rules` |
+| `preferred_order_routing_strategy` | Optional per-channel override of the store's [Order Routing](shipments.md#order-routing) strategy | `Spree::OrderRouting::Strategy::Rules` |
 
 `code` is normalized to a URL-safe slug on save — `POS` becomes `pos`, `Point of Sale!` becomes `point-of-sale`. Leaving `code` blank derives it from `name`.
 
@@ -37,10 +37,10 @@ The resolved channel is then available to controllers, models, and serializers t
 
 ### Selecting a channel from the Store SDK
 
-The Store SDK sends `X-Spree-Channel` on every request when configured. The value can be either the channel `code` (merchant-meaningful, recommended) or the prefixed ID (`ch_…`).
+The Store SDK sends `X-Spree-Channel` on every request when configured. The value can be either the channel `code` (merchant-meaningful, recommended) or the prefixed ID (`ch_…`). `setChannel` is a sticky setter that [mirrors `setLocale` / `setCurrency` / `setCountry`](../sdk/configuration.md).
 
 
-```typescript SDK
+```typescript Store SDK
 // Client-level default
 const client = createClient({
   baseUrl: 'https://api.mystore.com',
@@ -55,6 +55,11 @@ client.setChannel('wholesale')
 const products = await client.products.list({}, { channel: 'pos' })
 ```
 
+```typescript Admin SDK
+// admin filters 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' \
@@ -62,7 +67,7 @@ curl 'https://api.mystore.com/api/v3/store/products' \
 ```
 
 
-The Admin API does not consume `X-Spree-Channel` — admin endpoints return data across all channels for the current store. Filter by channel on the admin side via Ransack (`q[channel_id_eq]=ch_xxx` for orders, `q[channels_id_in][]=ch_xxx` for products).
+The Admin API does not consume `X-Spree-Channel` — admin endpoints return data across all channels for the current store. [Filter by channel on the admin side via Ransack](../../api-reference/admin-api/querying.md) (`q[channel_id_eq]=ch_xxx` for orders, `q[channels_id_in][]=ch_xxx` for products).
 
 ### Product visibility
 
@@ -103,7 +108,7 @@ Three endpoints cover the publishing surface:
 | `POST /api/v3/admin/products/bulk_add_to_channels` | Publish many products across many channels in a single request |
 
 
-```typescript SDK
+```typescript Admin SDK
 await adminClient.channels.addProducts('ch_xxx', {
   product_ids: ['prod_aaa', 'prod_bbb'],
   // Optional window — when omitted, existing schedules are preserved
@@ -129,7 +134,7 @@ curl -X POST 'https://api.mystore.com/api/v3/admin/channels/ch_xxx/add_products'
 For per-product updates, use `PATCH /api/v3/admin/products/:id` with a `product_publications` array:
 
 
-```typescript SDK
+```typescript Admin SDK
 await adminClient.products.update('prod_xxx', {
   product_publications: [
     { channel_id: 'ch_online' },
@@ -165,3 +170,5 @@ The write contract is **full-set**: the array represents the complete desired st
 - [Markets](markets.md) — Different from channels: markets segment geography/currency, channels segment selling surfaces
 - [Products](products.md) — Product catalog and publication
 - [Order Routing](shipments.md#order-routing) — Channels can override the store's routing strategy
+- [Store SDK: Products](../sdk/store/products.md) — Channel-scoped product listing and filtering
+- [Admin SDK: Resources](../sdk/admin/resources.md) — How `adminClient.channels.addProducts` and other resource methods are structured

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

@@ -45,7 +45,7 @@ erDiagram
 ## Registration
 
 
-```typescript SDK
+```typescript Store SDK
 const { token, user } = await client.customers.create({
   email: 'john@example.com',
   password: 'password123',
@@ -54,7 +54,7 @@ const { token, user } = await client.customers.create({
   last_name: 'Doe',
 })
 // token => JWT token for subsequent authenticated requests
-// user => { id: "usr_xxx", email: "john@example.com", first_name: "John", ... }
+// user => { id: "cus_abc123", email: "john@example.com", first_name: "John", ... }
 ```
 
 ```bash cURL
@@ -71,10 +71,28 @@ curl -X POST 'https://api.mystore.com/api/v3/store/customers' \
 ```
 
 
+> **NOTE:** The Store API flow above is **customer self-registration** — the customer sets a password and gets a JWT back. To [create a customer record from the back office](../sdk/admin/resources.md) (importers, CRM sync, phone orders), use the [Admin SDK](../sdk/admin/quickstart.md) instead. No password is set, so it's a managed record rather than a sign-up:
+> 
+> ```typescript
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+  baseUrl: 'https://store.example.com',
+  secretKey: 'sk_xxx',
+})
+
+const customer = await client.customers.create({
+  email: 'john@example.com',
+  first_name: 'John',
+  last_name: 'Doe',
+  tags: ['wholesale'],
+})
+```
+
 ## Login
 
 
-```typescript SDK
+```typescript Store SDK
 const { token, user } = await client.auth.login({
   email: 'john@example.com',
   password: 'password123',
@@ -93,22 +111,25 @@ curl -X POST 'https://api.mystore.com/api/v3/store/auth/login' \
 ```
 
 
-The response includes a JWT `token` and a `user` object. Pass the token in subsequent requests via the `Authorization: Bearer <token>` header.
+The response includes a JWT `token` and a `user` object. Pass the token in subsequent requests via the [`Authorization: Bearer <token>`](../../api-reference/store-api/authentication.md) header.
 
 ## Token Refresh
 
-Refresh an expiring token to keep the session alive:
+Refresh an expiring token to keep the session alive. For how `client.auth.login` and `client.auth.refresh` fit into configuring the SDK for guest vs customer (JWT) auth, see the [SDK authentication guide](../sdk/authentication.md):
 
 
-```typescript SDK
-const { token } = await client.auth.refresh({
-  token: existingToken,
+```typescript Store SDK
+const { token, refresh_token } = await client.auth.refresh({
+  refresh_token: existingRefreshToken,
 })
+// Persist the rotated refresh_token for the next refresh
 ```
 
 ```bash cURL
 curl -X POST 'https://api.mystore.com/api/v3/store/auth/refresh' \
-  -H 'Authorization: Bearer <jwt_token>'
+  -H 'X-Spree-Api-Key: pk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "refresh_token": "rt_xxx" }'
 ```
 
 
@@ -119,8 +140,8 @@ Password reset is a two-step flow. First, request a reset email. Then, use the t
 ### Step 1: Request Reset
 
 
-```typescript SDK
-await client.customer.passwordResets.create({
+```typescript Store SDK
+await client.passwordResets.create({
   email: 'john@example.com',
   redirect_url: 'https://myshop.com/reset-password',
 })
@@ -129,7 +150,7 @@ await client.customer.passwordResets.create({
 ```
 
 ```bash cURL
-curl -X POST 'https://api.mystore.com/api/v3/store/customer/password_resets' \
+curl -X POST 'https://api.mystore.com/api/v3/store/password_resets' \
   -H 'X-Spree-Api-Key: pk_xxx' \
   -H 'Content-Type: application/json' \
   -d '{
@@ -139,15 +160,15 @@ curl -X POST 'https://api.mystore.com/api/v3/store/customer/password_resets' \
 ```
 
 
-The optional `redirect_url` parameter specifies where the password reset link in the email should point to. The token will be appended as a query parameter (e.g., `https://myshop.com/reset-password?token=...`). If the store has [Allowed Origins](allowed-origins.md) configured, the `redirect_url` must match one of them.
+The optional `redirect_url` parameter specifies where the password reset link in the email should point to. The token will be appended as a query parameter (e.g., `https://myshop.com/reset-password?token=...`). If the store has Allowed Origins configured, the `redirect_url` must match one of them.
 
 This fires a `customer.password_reset_requested` event with the reset token in the payload. If you're using the `spree_emails` package, the email is sent automatically. Otherwise, subscribe to this event to send the reset email yourself (see [Events](events.md)).
 
 ### Step 2: Reset Password
 
 
-```typescript SDK
-const { token, user } = await client.customer.passwordResets.update(
+```typescript Store SDK
+const { token, user } = await client.passwordResets.update(
   'reset-token-from-email',
   {
     password: 'newsecurepassword',
@@ -158,7 +179,7 @@ const { token, user } = await client.customer.passwordResets.update(
 ```
 
 ```bash cURL
-curl -X PATCH 'https://api.mystore.com/api/v3/store/customer/password_resets/RESET_TOKEN' \
+curl -X PATCH 'https://api.mystore.com/api/v3/store/password_resets/RESET_TOKEN' \
   -H 'X-Spree-Api-Key: pk_xxx' \
   -H 'Content-Type: application/json' \
   -d '{
@@ -178,7 +199,7 @@ Headless storefronts often need to collect newsletter signups before account cre
 ### Step 1: Subscribe
 
 
-```typescript SDK
+```typescript Store SDK
 await client.newsletterSubscribers.create({
   email: 'guest@example.com',
   redirect_url: 'https://myshop.com/newsletter/confirm',
@@ -197,7 +218,7 @@ curl -X POST 'https://api.mystore.com/api/v3/store/newsletter_subscribers' \
 ```
 
 
-The optional `redirect_url` points at the storefront page that will receive the verification token. It is validated against the store's [Allowed Origins](allowed-origins.md) — URLs that do not match are silently dropped from the webhook payload (secure-by-default).
+The optional `redirect_url` points at the storefront page that will receive the verification token. It is validated against the store's Allowed Origins — URLs that do not match are silently dropped from the webhook payload (secure-by-default).
 
 This fires a `newsletter_subscriber.subscription_requested` event whose payload includes `email`, `verification_token`, and the validated `redirect_url`. Subscribe to this event from your storefront's webhook handler to send the confirmation email — the link in the email should point to `<redirect_url>?token=<verification_token>`. The bundled `spree_emails` package also listens to this event and sends a default confirmation email if you're not running a headless storefront.
 
@@ -206,7 +227,7 @@ If the request is authenticated via a customer JWT and the JWT's email matches t
 ### Step 2: Verify
 
 
-```typescript SDK
+```typescript Store SDK
 await client.newsletterSubscribers.verify({
   token: 'token-from-email',
 })
@@ -226,11 +247,11 @@ On success, the subscriber is marked verified. If the subscription is linked to
 ## Customer Profile
 
 
-```typescript SDK
+```typescript Store SDK
 // Get current customer
 const customer = await client.customer.get()
 // {
-//   id: "usr_xxx",
+//   id: "cus_xxx",
 //   email: "john@example.com",
 //   first_name: "John",
 //   last_name: "Doe",
@@ -248,11 +269,13 @@ const updated = await client.customer.update({
 
 ```bash cURL
 # Get current customer
-curl 'https://api.mystore.com/api/v3/store/customer' \
+curl 'https://api.mystore.com/api/v3/store/customers/me' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'Authorization: Bearer <jwt_token>'
 
 # Update profile
-curl -X PATCH 'https://api.mystore.com/api/v3/store/customer' \
+curl -X PATCH 'https://api.mystore.com/api/v3/store/customers/me' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'Authorization: Bearer <jwt_token>' \
   -H 'Content-Type: application/json' \
   -d '{ "first_name": "Jonathan", "accepts_email_marketing": true }'
@@ -279,6 +302,7 @@ Customers don't need to register to purchase. Guest checkout uses an order token
 
 ## Related Documentation
 
+- [Account (Store SDK)](../sdk/store/account.md) — Task-oriented walkthrough of registration, login, profile, addresses, and order history
 - [Addresses](addresses.md) — Customer address management
 - [Orders](orders.md) — Order history and checkout
 - [Authentication](../customization/authentication.md) — Custom authentication setup

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

@@ -163,7 +163,7 @@ def handle(event)
   event.name       # => "order.completed"
   event.store_id   # => 1 (ID of the store where the event originated)
   event.payload    # => { "id" => 1, "number" => "R123456", ... }
-  event.metadata   # => { "spree_version" => "5.1.0" }
+  event.metadata   # => { "spree_version" => "<spree_version>" }
   event.created_at # => Time when event was published
 
   # Helper methods
@@ -243,13 +243,15 @@ Models with lifecycle events enabled include: `Order`, `Payment`, `Price`, `Ship
 | `price.updated` | Price was updated |
 | `price.deleted` | Price was deleted |
 
-### Customer Events
+### User Events
 
 | Event | Description |
 |-------|-------------|
-| `customer.created` | Customer was created |
-| `customer.updated` | Customer was updated |
-| `customer.deleted` | Customer was deleted |
+| `user.created` | User was created |
+| `user.updated` | User was updated |
+| `user.deleted` | User was deleted |
+
+When `Spree.admin_user_class` differs from `Spree.user_class`, admin users publish the equivalent `admin.*` events (see the Admin Events table below).
 
 ### Admin Events
 
@@ -263,8 +265,8 @@ Models with lifecycle events enabled include: `Order`, `Payment`, `Price`, `Ship
 
 | Event | Description |
 |-------|-------------|
-| `product.activate` | Product status changed to active |
-| `product.archive` | Product status changed to archived |
+| `product.activated` | Product status changed to active |
+| `product.archived` | Product status changed to archived |
 | `product.out_of_stock` | Product has no stock left for any variant |
 | `product.back_in_stock` | Product was out of stock and now has stock again |
 
@@ -298,7 +300,7 @@ Spree::Events.publish(
 
 ## Event Serializers
 
-Event payloads are generated using the same [Store API V3 serializers](../../api-reference/introduction.md) used by the REST API. This means webhook payloads and API responses share the same schema, making it easy to reuse types in your integrations.
+Event payloads are generated using the same [Store API V3 serializers](../../api-reference/store-api/introduction.md) used by the REST API. This means webhook payloads and API responses share the same schema, making it easy to reuse types in your integrations.
 
 ### How Serializers Work
 
@@ -344,7 +346,7 @@ This means event payloads contain the same top-level attributes and unconditiona
 
 ### Overriding Event Serializers
 
-To customize the payload for existing events, create a custom V3 serializer and configure it via dependencies:
+To customize the payload for existing events, create a custom V3 serializer and configure it via [dependencies](../customization/dependencies.md):
 
 ```ruby app/serializers/my_app/order_serializer.rb
 module MyApp
@@ -488,7 +490,7 @@ end
 
 ### Testing Event Publishing
 
-Use the `emit_webhook_event` matcher (if available) or stub the events:
+Stub `Spree::Events.publish` to assert an event is published:
 
 ```ruby
 it 'publishes order.completed event' do
@@ -501,6 +503,8 @@ it 'publishes order.completed event' do
 end
 ```
 
+The `lifecycle events` shared examples in `spree/core/lib/spree/testing_support/lifecycle_events.rb` cover the standard `created`/`updated`/`deleted` lifecycle events.
+
 ## Best Practices
 
 
@@ -526,7 +530,7 @@ class InventoryAlertSubscriber < Spree::Subscriber
   def handle(event)
     stock_item = find_stock_item(event)
     return unless stock_item
-    return unless stock_dropped_below_threshold?(event, stock_item)
+    return unless low_stock?(event)
 
     send_low_stock_alert(stock_item)
   end
@@ -537,11 +541,8 @@ class InventoryAlertSubscriber < Spree::Subscriber
     Spree::StockItem.find_by_prefix_id(event.payload['id'])
   end
 
-  def stock_dropped_below_threshold?(event, stock_item)
-    previous_count = event.payload['count_on_hand_before_last_save']
-    current_count = stock_item.count_on_hand
-
-    previous_count >= LOW_STOCK_THRESHOLD && current_count < LOW_STOCK_THRESHOLD
+  def low_stock?(event)
+    event.payload['count_on_hand'].to_i < LOW_STOCK_THRESHOLD
   end
 
   def send_low_stock_alert(stock_item)
@@ -554,6 +555,8 @@ class InventoryAlertSubscriber < Spree::Subscriber
 end
 ```
 
+> **NOTE:** A lifecycle event payload carries only the resource's current serialized state, not its previous values. If you need a true "just dropped below the threshold" check that compares the count before and after the change, record or cache the prior count separately rather than reading it from the event payload.
+
 ## Custom Event Adapters
 
 Spree's event system uses an adapter pattern, making it possible to swap the underlying event infrastructure. By default, Spree uses [`ActiveSupport::Notifications`](https://api.rubyonrails.org/classes/ActiveSupport/Notifications.html), but you can create custom adapters for other backends like Kafka, RabbitMQ, or Redis Pub/Sub.
@@ -626,14 +629,16 @@ The `Spree::Events::Adapters::Base` class defines the required interface:
 
 The base class also provides helper methods:
 - `build_event(name, payload, metadata)` - Creates a `Spree::Event` instance
-- `subscriptions_for(event_name)` - Finds matching subscriptions from the registry
+- `invoke_subscribers(event)` - Finds and invokes matching subscribers (internally calling `registry.subscriptions_for`)
 - `registry` - Access to the `Spree::Events::Registry` instance
 
 > **INFO:** See `Spree::Events::Adapters::ActiveSupportNotifications` for a complete reference implementation.
 
 ## Related Documentation
 
+- [Events Tutorial](../tutorial/events.md) - Hands-on, step-by-step walkthrough of building an event subscriber
 - [Webhooks](webhooks.md) - HTTP callbacks for external integrations
+- [Webhooks & Events Reference](../../api-reference/webhooks-events.md) - Catalog of event and webhook payloads
 - [Customization Quickstart](../customization/quickstart.md) - Overview of all customization options
 - [Decorators](../customization/decorators.md) - When to use decorators vs events
 - [Checkout Flow](../customization/checkout.md) - Using events in checkout customization

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

@@ -42,7 +42,7 @@ erDiagram
     Export {
         string number
         string type
-        string format
+        integer format
         jsonb search_params
     }
 
@@ -80,10 +80,12 @@ Exports generate CSV files from filtered database records.
 | Type | Description | Multi-line |
 |------|-------------|------------|
 | `Spree::Exports::Products` | Products with all variants | Yes |
+| `Spree::Exports::ProductTranslations` | Product translations for non-default store locales | Yes |
 | `Spree::Exports::Orders` | Orders with line items | Yes |
 | `Spree::Exports::Customers` | Customer accounts | No |
 | `Spree::Exports::GiftCards` | Gift cards | No |
 | `Spree::Exports::NewsletterSubscribers` | Newsletter subscribers | No |
+| `Spree::Exports::CouponCodes` | Promotion coupon codes | No |
 
 ### Export Model
 
@@ -219,7 +221,7 @@ end
 
 ### Export Filtering
 
-Exports support Ransack filtering via `search_params`:
+Exports support [Ransack filtering via `search_params`](../../api-reference/admin-api/querying.md):
 
 ```ruby
 # In admin, users can filter before exporting
@@ -242,6 +244,8 @@ Imports process CSV files to create or update database records.
 | Type | Description |
 |------|-------------|
 | `Spree::Imports::Products` | Products and variants |
+| `Spree::Imports::ProductTranslations` | Product translations (matched by slug) |
+| `Spree::Imports::Customers` | Customers |
 
 ### Import Workflow
 
@@ -538,7 +542,7 @@ The products import handles variants intelligently:
 
 ```csv
 slug,sku,name,price,option1_name,option1_value,option2_name,option2_value
-my-tshirt,TSHIRT-001,My T-Shirt,29.99,,,
+my-tshirt,TSHIRT-001,My T-Shirt,29.99,,,,
 my-tshirt,TSHIRT-S-RED,My T-Shirt,29.99,Size,Small,Color,Red
 my-tshirt,TSHIRT-M-RED,My T-Shirt,29.99,Size,Medium,Color,Red
 my-tshirt,TSHIRT-L-RED,My T-Shirt,29.99,Size,Large,Color,Red
@@ -560,16 +564,16 @@ Both imports and exports support metafields dynamically:
 
 Parses CSV and creates ImportRow records:
 
+All import jobs inherit from `Spree::Imports::BaseJob`, which sets `queue_as Spree.queues.imports` once and is shared across the pipeline.
+
 ```ruby
 module Spree
   module Imports
-    class CreateRowsJob < Spree::BaseJob
-      queue_as Spree.queues.imports
-
+    class CreateRowsJob < Spree::Imports::BaseJob
       def perform(import_id)
         import = Spree::Import.find(import_id)
         # Stream CSV, batch insert rows
-        # Then enqueue ProcessRowsJob
+        # Then enqueue ProcessRowsJob via import.process_rows_async
       end
     end
   end
@@ -578,20 +582,64 @@ end
 
 ### ProcessRowsJob
 
-Processes pending rows through row processors:
+Fans the pending rows out into groups, each processed by a separate `ProcessGroupJob`:
 
 ```ruby
 module Spree
   module Imports
-    class ProcessRowsJob < Spree::BaseJob
-      queue_as Spree.queues.imports
+    class ProcessRowsJob < Spree::Imports::BaseJob
+      BATCH_SIZE = 100
 
       def perform(import_id)
         import = Spree::Import.find(import_id)
-        import.rows.pending_and_failed.find_each do |row|
-          row.process!
+        dispatch_groups(import)
+      end
+
+      private
+
+      def dispatch_groups(import)
+        # When the import defines a group_column (e.g. ProductTranslations groups
+        # by slug) and that field is mapped, group rows by the column value.
+        # Otherwise, fall back to slicing pending_and_failed rows into batches of
+        # BATCH_SIZE. Either way: pluck the row IDs, set processing_groups_count /
+        # completed_groups_count up front so workers can't complete prematurely,
+        # then enqueue one ProcessGroupJob per group.
+        import.rows.pending_and_failed.in_batches(of: BATCH_SIZE) do |batch|
+          ProcessGroupJob.perform_later(import.id, batch.ids)
         end
-        import.complete!
+      end
+    end
+  end
+end
+```
+
+### ProcessGroupJob
+
+Processes one group of rows and reports completion:
+
+```ruby
+module Spree
+  module Imports
+    class ProcessGroupJob < Spree::Imports::BaseJob
+      def perform(import_id, row_ids)
+        import = Spree::Import.find(import_id)
+        rows = import.rows.where(id: row_ids).pending_and_failed
+
+        # Large imports process with events disabled and use bulk_process!;
+        # otherwise each row is processed individually via row.process!.
+        rows.each { |row| row.process! }
+
+        check_import_completion(import)
+      end
+
+      private
+
+      # Increments completed_groups_count, then completes the import only once the
+      # last group has finished and no rows are still in flight.
+      def check_import_completion(import)
+        # completed_groups_count += 1
+        import.complete! if import.completed_groups_count >= import.processing_groups_count &&
+                            import.rows.in_flight.none?
       end
     end
   end
@@ -609,7 +657,7 @@ module Spree
       queue_as Spree.queues.exports
 
       def perform(export_id)
-        export = Spree::Export.find(export_id)
+        export = Spree::Export.find_by_prefix_id!(export_id)
         export.generate
       end
     end
@@ -621,6 +669,8 @@ end
 
 ## Events
 
+Import and export lifecycle events such as [`import.completed` and `export.created`](../../api-reference/webhooks-events.md) can be delivered as webhooks to react when an asynchronous import or export finishes.
+
 ### Import Events
 
 | Event | Trigger |
@@ -696,3 +746,8 @@ can :manage, Spree::Export
 ```
 
 Records are filtered by `current_ability` ensuring users only export data they have access to.
+
+## Related Documentation
+
+- [Admin imports/exports endpoints](../../api-reference/admin-api/endpoints.md) — REST routes and required scopes to trigger imports and exports programmatically.
+- [Admin SDK resources](../sdk/admin/resources.md) — typed TypeScript client for driving these back-office operations.

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

@@ -115,6 +115,38 @@ Stock Locations can be easily used for tracking warehouses and other physical lo
 
 You can easily use them with your Point of Sale (POS) system to track inventory at different locations.
 
+Create and manage stock locations via the [Admin API](../../api-reference/admin-api/introduction.md):
+
+
+```typescript Admin SDK
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+  baseUrl: 'https://store.example.com',
+  secretKey: 'sk_xxx',
+})
+
+const location = await client.stockLocations.create({
+  name: 'Warehouse 1',
+  admin_name: 'WH1 Domestic',
+  default: true,
+  country_iso: 'US',
+  propagate_all_variants: 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
+}'
+```
+
+
 ### 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.
@@ -126,6 +158,25 @@ Stock Items represent the inventory at a stock location for a specific variant.
 | `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:
+
+
+```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' })
+
+await client.stockItems.update('si_xxx', {
+  count_on_hand: 150,
+  backorderable: true,
+})
+```
+
+```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}'
+```
+
+
 ### 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.
@@ -141,6 +192,30 @@ Here's the list of attributes for the Stock Transfer model:
 | `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:
+
+
+```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 },
+  ],
+})
+```
+
+```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 Stock Transfer will hold a list of Stock Movements.
@@ -191,7 +266,7 @@ Reservations attach to each line item; when a line item or order is removed, the
 |---|---|---|
 | `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` | inherits global | Per-Store override. |
+| `store.preferred_stock_reservation_ttl_minutes` | `10` | Per-Store override. Falls back to the global default only when explicitly unset/blank. |
 
 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.
 
@@ -230,6 +305,7 @@ Inventory Units states are:
 * `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
 
 > **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.
 
@@ -245,3 +321,5 @@ If you don't need to track inventory, you can disable it:
 - [Products](products.md) - Product and variant management
 - [Shipments](shipments.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