@spree/docs 0.1.93 → 0.1.94

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

@@ -194,7 +194,7 @@ Limits the promotion to orders in a specific currency.
 Requires products with specific option values (e.g., size, color) to be in the order.
 
 **Configuration:**
-- `preferred_eligible_values` - Array of eligible variant IDs
+- `preferred_eligible_values` - Array of `Spree::OptionValueVariant` IDs (the option-value↔variant join records the rule matches against the order's variants), not variant IDs
 
 **Use case:** "10% off all red items", "Discount on size XL".
 
@@ -255,6 +255,61 @@ The action checks stock availability before adding items. Items are not automati
 
 **Use case:** "Free gift with purchase", "Buy 2 get 1 free", "Spend $100 get free sample".
 
+## Managing Promotions
+
+Create and manage promotions via the [Admin API](../../api-reference/admin-api/introduction.md). Rules and actions can be supplied inline on create — each is a `{ type, preferences }` draft using the rule/action types described above:
+
+
+```typescript Admin SDK
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+  baseUrl: 'https://store.example.com',
+  secretKey: 'sk_xxx',
+})
+
+// "20% off orders over $100 with code SUMMER20"
+const promotion = await client.promotions.create({
+  name: 'Summer Sale',
+  code: 'SUMMER20',
+  kind: 'coupon_code',
+  rules: [{ type: 'item_total', preferences: { amount_min: 100 } }],
+  actions: [
+    {
+      type: 'create_adjustment',
+      calculator: { type: 'flat_percent_item_total', preferences: { flat_percent: 20 } },
+    },
+  ],
+})
+```
+
+```bash CLI
+spree api post /promotions -d '{
+  "name": "Summer Sale",
+  "code": "SUMMER20",
+  "kind": "coupon_code",
+  "rules": [{ "type": "item_total", "preferences": { "amount_min": 100 } }]
+}'
+```
+
+
+You can also add rules and actions to an existing promotion, or update and remove the promotion itself:
+
+
+```typescript Admin SDK
+await client.promotions.rules.create('promo_xxx', {
+  type: 'first_order',
+})
+await client.promotions.update('promo_xxx', { expires_at: '2026-09-01T00:00:00Z' })
+await client.promotions.delete('promo_xxx')
+```
+
+```bash CLI
+spree api post /promotions/promo_xxx/promotion_rules -d '{"type": "first_order"}'
+spree api patch /promotions/promo_xxx -d '{"expires_at": "2026-09-01T00:00:00Z"}'
+```
+
+
 ## Coupon Codes
 
 Coupon codes track promotion usage and can be single-use or multi-use.
@@ -274,10 +329,10 @@ For bulk-generated codes, each code tracks its usage state:
 
 ## Applying Coupon Codes via Store API
 
-Customers apply coupon codes during checkout via the Store API:
+Customers [apply coupon codes during checkout](../sdk/store/cart-checkout.md) via the Store API:
 
 
-```typescript SDK
+```typescript Store SDK
 // Apply a discount code to the cart
 const cart = await client.carts.discountCodes.apply('cart_abc123', 'SUMMER20', {
   spreeToken: '<token>',
@@ -291,7 +346,7 @@ await client.carts.discountCodes.remove('cart_abc123', 'SUMMER20', {
 
 ```bash cURL
 # Apply a coupon code
-curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_abc123/coupon_codes' \
+curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_abc123/discount_codes' \
   -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: <token>' \
   -H 'Content-Type: application/json' \
@@ -320,3 +375,5 @@ How promotions are evaluated and applied:
 - [Calculators](calculators.md) - Learn about promotion calculators
 - [Orders](orders.md) - Understanding order processing
 - [Customization Quickstart](../customization/quickstart.md) - Overview of customization options
+- [Admin SDK Resources](../sdk/admin/resources.md) - The `client.promotions.*` resource-client pattern used in the examples above
+- [Spree CLI Admin API](../cli/admin-api.md) - The `spree api` command reference for the CLI examples above

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

@@ -100,7 +100,7 @@ The Products Performance report aggregates sales metrics by product for the spec
 ### Generation Flow
 
 1. **User creates report** via admin UI with date range, currency, and optional vendor
-2. **Report is saved** to database with status tracking
+2. **Report is saved** to the database
 3. **`report.created` event fires** via `publishes_lifecycle_events` concern
 4. **`Spree::ReportSubscriber` catches event** and enqueues `GenerateJob`
 5. **Background job runs `report.generate`**:
@@ -184,7 +184,7 @@ Spree::Admin::RuntimeConfig.reports_line_items_limit = 100
 
 ### Background Job Queue
 
-Reports use a dedicated queue. Configure your job processor:
+By default, report jobs run on the `:default` queue. To route them to a dedicated queue, configure your job processor:
 
 ```ruby
 # Sidekiq example
@@ -204,3 +204,5 @@ can :manage, Spree::Report
 
 - [Build a Custom Report](../how-to/custom-report.md) - Step-by-step guide to creating custom reports
 - [Events](events.md) - How report generation uses the events system
+- [Imports & Exports](imports-exports.md) - The broader async-export, ActiveStorage-attachment pattern reports share
+- [Admin API Endpoints](../../api-reference/admin-api/endpoints.md) - Endpoints for creating and downloading reports from an integration

package/dist/developer/core-concepts/search-filtering.md

@@ -9,7 +9,7 @@ import { Since } from '/snippets/since.mdx';
 
 Spree provides powerful search, filtering, and sorting capabilities for products and other resources. The Store API supports:
 
-- Full-text search across product names, descriptions, and SKUs
+- Full-text search across product names and SKUs
 - Attribute-based filtering (price range, availability, stock status)
 - Category and taxon filtering
 - Faceted search with filter counts
@@ -20,13 +20,20 @@ Spree provides powerful search, filtering, and sorting capabilities for products
 Use the `search` parameter for full-text search across product fields:
 
 
-```typescript SDK
+```typescript Store SDK
 const { data: products } = await client.products.list({
   search: 'tote bag',
   limit: 12,
 })
 ```
 
+```typescript Admin SDK
+const { data: products } = await adminClient.products.list({
+  search: 'tote bag',
+  limit: 12,
+})
+```
+
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products?q[search]=tote+bag&limit=12' \
   -H 'X-Spree-API-Key: pk_xxx'
@@ -38,13 +45,20 @@ curl 'https://api.mystore.com/api/v3/store/products?q[search]=tote+bag&limit=12'
 ### By Price Range
 
 
-```typescript SDK
+```typescript Store SDK
 const { data: products } = await client.products.list({
   price_gte: 20,
   price_lte: 100,
 })
 ```
 
+```typescript Admin SDK
+const { data: products } = await adminClient.products.list({
+  price_gte: 20,
+  price_lte: 100,
+})
+```
+
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products?q[price_gte]=20&q[price_lte]=100' \
   -H 'X-Spree-API-Key: pk_xxx'
@@ -54,12 +68,18 @@ curl 'https://api.mystore.com/api/v3/store/products?q[price_gte]=20&q[price_lte]
 ### By Availability
 
 
-```typescript SDK
+```typescript Store SDK
 const { data: products } = await client.products.list({
   in_stock: true,
 })
 ```
 
+```typescript Admin SDK
+const { data: products } = await adminClient.products.list({
+  in_stock: true,
+})
+```
+
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products?q[in_stock]=true' \
   -H 'X-Spree-API-Key: pk_xxx'
@@ -69,13 +89,8 @@ curl 'https://api.mystore.com/api/v3/store/products?q[in_stock]=true' \
 ### By Category
 
 
-```typescript SDK
-// Products in a specific category
-const { data: products } = await client.categories.products.list('clothing/shirts', {
-  limit: 12,
-})
-
-// Or filter by category ID (includes descendants)
+```typescript Store SDK
+// Filter by category ID (includes descendants)
 const { data: products } = await client.products.list({
   in_category: 'ctg_xxx',
 })
@@ -86,11 +101,19 @@ const { data: products } = await client.products.list({
 })
 ```
 
-```bash cURL
-# Products in a category
-curl 'https://api.mystore.com/api/v3/store/categories/clothing/shirts/products?limit=12' \
-  -H 'X-Spree-API-Key: pk_xxx'
+```typescript Admin SDK
+// Filter by category ID (includes descendants)
+const { data: products } = await adminClient.products.list({
+  in_category: 'ctg_xxx',
+})
 
+// Multiple categories (OR logic)
+const { data: products } = await adminClient.products.list({
+  in_categories: ['ctg_shirts', 'ctg_pants'],
+})
+```
+
+```bash cURL
 # Filter by category ID (includes descendants)
 curl 'https://api.mystore.com/api/v3/store/products?q[in_category]=ctg_xxx' \
   -H 'X-Spree-API-Key: pk_xxx'
@@ -104,14 +127,20 @@ curl 'https://api.mystore.com/api/v3/store/products?q[in_categories][]=ctg_shirt
 ### By Tags
 
 
-```typescript SDK
+```typescript Store SDK
 const { data: products } = await client.products.list({
-  tags_cont: 'sale',
+  tags_name_cont: 'sale',
+})
+```
+
+```typescript Admin SDK
+const { data: products } = await adminClient.products.list({
+  tags_name_cont: 'sale',
 })
 ```
 
 ```bash cURL
-curl 'https://api.mystore.com/api/v3/store/products?q[tags_cont]=sale' \
+curl 'https://api.mystore.com/api/v3/store/products?q[tags_name_cont]=sale' \
   -H 'X-Spree-API-Key: pk_xxx'
 ```
 
@@ -119,33 +148,45 @@ curl 'https://api.mystore.com/api/v3/store/products?q[tags_cont]=sale' \
 ## Sorting
 
 
-```typescript SDK
+```typescript Store SDK
 // Sort by price (low to high)
 const sorted = await client.products.list({
-  sort: 'price_low_to_high',
+  sort: 'price',
 })
 
-// Available sort options:
-// price_low_to_high, price_high_to_low, newest, name_a_z, name_z_a
+// Available sort options (prefix '-' for descending; use '-available_on' for newest):
+// price, -price, name, -name, available_on, -available_on, best_selling
+```
+
+```typescript Admin SDK
+const { data: products } = await adminClient.products.list({
+  sort: 'price',
+})
 ```
 
 ```bash cURL
-curl 'https://api.mystore.com/api/v3/store/products?sort=price_low_to_high' \
+curl 'https://api.mystore.com/api/v3/store/products?sort=price' \
   -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
 ## Product Filters (Faceted Search)
 
-Get available filter options for building a faceted search UI. Returns option values, price ranges, and categories with counts:
+Get available filter options for building a faceted search UI. Returns an array of typed filter objects (price range, availability, option types, categories) with counts, plus sort and pagination metadata:
 
 
-```typescript SDK
+```typescript Store SDK
 const filters = await client.products.filters()
 // {
-//   option_types: [{ name: "size", option_values: [{ name: "Small", count: 12 }, ...] }],
-//   price_range: { min: 9.99, max: 199.99 },
-//   categories: [{ id: "ctg_xxx", name: "Clothing", count: 45 }],
+//   filters: [
+//     { id: 'price', type: 'price_range', min: 9.99, max: 199.99, currency: 'USD' },
+//     { id: 'availability', type: 'availability', options: [{ id: 'in_stock', count: 42 }, { id: 'out_of_stock', count: 3 }] },
+//     { id: 'optt_xxx', type: 'option', name: 'size', label: 'Size', kind: 'dropdown', options: [{ id: 'optval_xxx', name: 'Small', label: 'Small', position: 1, color_code: null, image_url: null, count: 12 }] },
+//     { id: 'categories', type: 'category', options: [{ id: 'ctg_xxx', name: 'Clothing', permalink: 'clothing', count: 45 }] },
+//   ],
+//   sort_options: [{ id: 'manual' }, { id: 'price' }, { id: '-price' }],
+//   default_sort: 'manual',
+//   total_count: 120,
 // }
 
 // Scoped to a specific category
@@ -210,13 +251,20 @@ The Store API uses query parameters prefixed with `q[]` for filtering any resour
 All list endpoints support pagination:
 
 
-```typescript SDK
+```typescript Store SDK
 const { data: products, meta } = await client.products.list({
   page: 1,
   limit: 24,
 })
-// meta.total_count => 150
-// meta.total_pages => 7
+// meta.count => 150
+// meta.pages => 7
+```
+
+```typescript Admin SDK
+const { data: products, meta } = await adminClient.products.list({
+  page: 1,
+  limit: 24,
+})
 ```
 
 ```bash cURL
@@ -243,6 +291,8 @@ See [Build a Custom Search Provider](../how-to/custom-search-provider.md) for ar
 ## Related Documentation
 
 - [Products](products.md) — Product catalog and listing
-- [Querying](../../api-reference/store-api/querying.md) — API filtering, sorting, and pagination reference
+- [Store SDK Products](../sdk/store/products.md) — `client.products.list()` options and methods
+- [Querying](../../api-reference/store-api/querying.md) — Store API filtering, sorting, and pagination reference
+- [Admin API querying](../../api-reference/admin-api/querying.md) — Admin API filtering, sorting, and pagination reference
 - [Build a Custom Search Provider](../how-to/custom-search-provider.md) — Step-by-step guide
 - [Meilisearch Integration](../../integrations/search/meilisearch.md) — Setup guide

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

@@ -61,9 +61,9 @@ The Store API/SDK exposes shipments as `fulfillments` with these attributes:
 | `fulfillment_type` | `shipping` or `digital` | `shipping` |
 | `cost` | Delivery cost | `9.99` |
 | `fulfilled_at` | When the fulfillment was shipped | `2025-07-21T14:36:00Z` |
-| `stock_location` | Where items ship from | `Warehouse NYC` |
+| `stock_location` | Where items ship from | `{ id: "sloc_xxx", name: "Warehouse NYC" }` |
 | `delivery_method` | The selected delivery method | `{ id: "dm_xxx", name: "UPS Ground" }` |
-| `delivery_rates` | Available rates for the customer to pick from | `[{ id: "rate_xxx", cost: "9.99", selected: true, ... }]` |
+| `delivery_rates` | Available rates for the customer to pick from | `[{ id: "dr_xxx", cost: "9.99", selected: true, ... }]` |
 
 ## Shipment States
 
@@ -86,28 +86,30 @@ The shipment was canceled. All items are restocked.
 
 ## Selecting Shipping Rates
 
-During checkout, after the customer provides a shipping address, Spree calculates available shipping rates for each shipment. The customer must select a rate before proceeding.
+During checkout, after the customer provides a shipping address, Spree calculates available shipping rates for each shipment. The customer must select a rate before proceeding. See the [Cart & Checkout SDK](../sdk/store/cart-checkout.md) guide for the full storefront cart and fulfillment flow.
 
 
-```typescript SDK
-// Get fulfillments with available delivery rates
+```typescript Store SDK
+// Get the cart with its fulfillments and available delivery rates
 // (the Store API/SDK exposes shipments as `fulfillments`)
-const order = await client.orders.get(orderId, {
-  expand: ['fulfillments'],
-})
+const cart = await client.carts.get(cartId)
 
 // Each fulfillment has available delivery rates
-order.fulfillments?.forEach(fulfillment => {
+cart.fulfillments?.forEach(fulfillment => {
   console.log(fulfillment.number)         // "H12345678901"
-  console.log(fulfillment.delivery_rates) // [{ id: "rate_xxx", name: "UPS Ground", cost: "9.99", selected: true }, ...]
+  console.log(fulfillment.delivery_rates) // [{ id: "dr_xxx", name: "UPS Ground", cost: "9.99", selected: true }, ...]
 })
 
 // Select a delivery rate
 await client.carts.fulfillments.update(cartId, fulfillment.id, {
-  selected_delivery_rate_id: 'rate_xxx',
+  selected_delivery_rate_id: 'dr_xxx',
 })
 ```
 
+```typescript Admin SDK
+const order = await adminClient.orders.get(orderId)
+```
+
 ```bash cURL
 # Get fulfillments
 curl 'https://api.mystore.com/api/v3/store/carts/cart_xxx?expand=fulfillments' \
@@ -119,7 +121,7 @@ curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/fulfillments/
   -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: abc123' \
   -H 'Content-Type: application/json' \
-  -d '{ "selected_delivery_rate_id": "rate_xxx" }'
+  -d '{ "selected_delivery_rate_id": "dr_xxx" }'
 ```
 
 
@@ -195,7 +197,7 @@ A channel can also override the routing **strategy** entirely — useful when on
 
 ### When it fires
 
-Routing fires once, when the order transitions from `cart` to `address` (the start of checkout). It produces one or more `Shipment`s, each tied to a chosen stock location. The decision is sticky — once the shipments are created, their locations stay fixed unless the merchant edits them in the admin or the cart is cleared and re-routed.
+Routing fires once, when the order transitions into the `delivery` step of checkout (from `address`). The `cart`→`address` transition only assigns default addresses; routing runs on the next step. It produces one or more `Shipment`s, each tied to a chosen stock location. The decision is sticky — once the shipments are created, their locations stay fixed unless the merchant edits them in the admin or the cart is cleared and re-routed.
 
 Routing happens **after** stock reservations: by the time routing runs, the cart has already reserved the units it needs. Reservations and routing make their decisions at different layers — reservations protect the variant's total inventory across all locations, routing picks which location ships. They coexist correctly today, with a small inefficiency around location-pinning that's planned to be tightened in 6.0.
 
@@ -302,3 +304,4 @@ A store shipping from 2 locations (New York, Los Angeles) with 3 carriers and 3
 - [Addresses](addresses.md) — Shipping address and zones
 - [Build Custom Order Routing](../how-to/custom-order-routing.md) — Custom rules and strategies for choosing the fulfillment location
 - [Events](events.md) — Subscribe to shipment events (e.g., `shipment.shipped`)
+- [Admin API](../../api-reference/admin-api/introduction.md) — Inspect and manage shipments, shipping methods, and categories from the back office

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

@@ -7,10 +7,10 @@ description: How Spree generates SEO-friendly URL slugs for products, categories
 
 Spree generates SEO-friendly URL slugs for resources like products, categories, and stores. Instead of accessing resources by ID, you can use clean, readable URLs based on resource names.
 
-Both the Store API and Admin API accept slugs or IDs interchangeably for resource lookups.
+The Store API accepts slugs or prefixed IDs interchangeably for resource lookups. The Admin API resolves resources by prefixed ID only — slugs are not accepted.
 
 
-```typescript SDK
+```typescript Store SDK
 // Both work — slug or ID
 const product = await client.products.get('spree-tote')
 const product = await client.products.get('prod_86Rf07xd4z')
@@ -19,6 +19,11 @@ const product = await client.products.get('prod_86Rf07xd4z')
 const category = await client.categories.get('clothing/shirts')
 ```
 
+```typescript Admin SDK
+// Admin SDK accepts prefixed IDs only — not slugs
+const product = await adminClient.products.get('prod_86Rf07xd4z')
+```
+
 ```bash cURL
 # By slug
 curl 'https://api.mystore.com/api/v3/store/products/spree-tote' \
@@ -49,7 +54,6 @@ If a slug already exists, Spree appends the SKU or a unique identifier to ensure
 | Product | `slug` | Yes | No |
 | Category | `permalink` | Yes | Yes |
 | Store | `code` | No | No |
-| Post | `slug` | Yes | No |
 
 ### Category Permalinks
 
@@ -65,27 +69,31 @@ When a parent category is renamed, all child permalinks update automatically.
 
 ## Slug History
 
-When a slug changes (e.g., a product is renamed), Spree preserves the old slug. Requests using old slugs still find the resource, enabling:
+When a slug changes (e.g., a product is renamed), Spree records the old slug in its history table (`friendly_id_slugs`).
 
-- **SEO continuity** — no broken links when names change
-- **Bookmark compatibility** — saved URLs keep working
-- **Graceful URL migration** — old links resolve automatically
+Note: the Store API product and category endpoints look up the *current* slug only (`find_by!` on the slug/permalink column) and do not automatically resolve retired slugs — a request using an old slug returns `404`. To preserve SEO and avoid broken links, issue HTTP 301 redirects from old slugs to the current one in your storefront or application layer.
 
 ## Internationalization
 
-Products and categories support localized slugs — a different slug per locale:
+Products and categories support localized slugs — a different slug per locale. The locale is resolved from the request's [`X-Spree-Locale` header](../../api-reference/store-api/localization.md):
 
 
-```typescript SDK
+```typescript Store SDK
 // English
 const product = await client.products.get('red-shoes')
 
-// French (with locale header)
-const product = await client.products.get('chaussures-rouges', {
+// French — locale goes in the third (request options) argument,
+// which sends the X-Spree-Locale header
+const product = await client.products.get('chaussures-rouges', undefined, {
   locale: 'fr',
 })
 ```
 
+```typescript Admin SDK
+// Admin SDK accepts prefixed IDs only — not slugs
+const product = await adminClient.products.get('prod_86Rf07xd4z')
+```
+
 ```bash cURL
 # English
 curl 'https://api.mystore.com/api/v3/store/products/red-shoes' \
@@ -109,3 +117,4 @@ Spree prevents certain words from being used as slugs to avoid route conflicts:
 - [Products](products.md) — Product catalog
 - [Translations](translations.md) — Multi-language content
 - [Querying](../../api-reference/store-api/querying.md) — API resource lookup
+- [Store SDK Products](../sdk/store/products.md) — `client.products.get()` slug/ID lookup

package/dist/developer/core-concepts/staff-roles.md

@@ -63,6 +63,35 @@ spree user create --email admin@example.com --password secret123
 
 The created user gets the `admin` role on the default store.
 
+## Authentication & identity providers
+
+Staff authenticate against the Admin API, which issues a short-lived JWT used for subsequent requests. How a staff member proves who they are is **pluggable** — Spree ships email/password out of the box, and you can plug in any external identity provider (Okta, Microsoft Entra ID, Google Workspace, a custom JWT issuer, SAML, etc.) without changing the rest of the API.
+
+### How admin login works
+
+A staff member logs in via the `POST /api/v3/admin/auth/login` endpoint (see [Admin API Authentication](../../api-reference/admin-api/authentication.md)). The request's `provider` field selects a registered **authentication strategy**. When `provider` is omitted it defaults to `email`, the built-in email/password strategy (which you can also disable and restrict the admin to your preferred SSO provider).
+
+```mermaid
+flowchart TB
+    A["POST /api/v3/admin/auth/login"] --> B{"provider field"}
+    B -->|"omitted or email"| C["Built-in EmailPasswordStrategy"]
+    B -->|"okta, saml, ..."| D["Your custom strategy"]
+    C --> E["Strategy authenticates, returns the staff user"]
+    D --> E
+    E --> F["Spree issues a JWT (aud=admin_api) + HttpOnly refresh cookie"]
+```
+
+Whichever strategy authenticates the request, Spree issues the **same** credentials in return, so downstream code and the admin SPA never need to know which provider was used:
+
+- a JWT access token (`aud: admin_api`), short-lived by design;
+- a rotating refresh token, set as an `HttpOnly` cookie scoped to `/api/v3/admin/auth` (the admin flow keeps it out of the response body — see [Admin Auth & Cookie Refresh](../../api-reference/admin-api/authentication.md)).
+
+The same strategy registry exists on the customer side, so storefront sign-in is pluggable the same way — the only difference is the user class and that the Store API returns the refresh token in the body rather than a cookie.
+
+### Registering a custom identity provider
+
+Follow the [Custom API Authentication how-to](../how-to/custom-api-authentication.md) for details how to create a custom authentication strategy and register it with the admin API. Once registered, you can use it from the admin SPA or any API client by passing its name in the `provider` field of the login request.
+
 ## Inviting Admin Users
 
 You can invite new admins through the Admin Panel or programmatically.
@@ -74,7 +103,25 @@ You can invite new admins through the Admin Panel or programmatically.
 3. Enter the email address and select a role
 4. Click **Send Invitation**
 
-The invitee receives an email with an invitation link. If they already have an account, they log in to accept. Otherwise, they create an account first.
+**Programmatically:**
+
+Using the [Admin SDK](../sdk/admin/quickstart.md), call `client.invitations.create`:
+
+```typescript
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+  baseUrl: 'https://store.example.com',
+  secretKey: 'sk_xxx',
+})
+
+const invitation = await client.invitations.create({
+  email: 'new-admin@example.com',
+  role_id: 'role_xxx',
+})
+```
+
+Creating an invitation publishes `invitation.created`, which sends the email. Either way, the invitee receives an email with an invitation link. If they already have an account, they log in to accept. Otherwise, they create an account first.
 
 ```mermaid
 flowchart TB
@@ -117,6 +164,9 @@ See the [Customize Permissions guide](../customization/permissions.md) for detai
 
 ## Related Documentation
 
+- [Admin SDK](../sdk/admin/quickstart.md) — the TypeScript client for back-office automation
+- [Custom API Authentication](../how-to/custom-api-authentication.md) — implement a custom identity-provider strategy (the full guide)
+- [Admin API Authentication](../../api-reference/admin-api/authentication.md) — keys, JWTs, scopes, and the refresh-cookie flow
 - [Customers](customers.md) — Customer accounts and authentication
 - [Stores](stores.md) — Multi-store setup
 - [Permissions](../customization/permissions.md) — Roles and authorization