@spree/docs 0.1.81 → 0.1.83

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

@@ -1,6 +1,6 @@
 ---
 title: Addresses
-description: Addresses, countries, states, and zones — how geography drives checkout, taxes, and shipping
+description: How Spree models addresses, countries, states, and zones, and how geographic data drives checkout, tax calculation, and shipping rates.
 ---
 
 ## Overview
@@ -129,14 +129,14 @@ await client.carts.update(cartId, {
 ```bash cURL
 # Use a saved address
 curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: order_token' \
   -H 'Content-Type: application/json' \
   -d '{ "shipping_address_id": "addr_xxx", "billing_address_id": "addr_yyy" }'
 
 # Or pass a new address inline
 curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: order_token' \
   -H 'Content-Type: application/json' \
   -d '{
@@ -189,15 +189,15 @@ const germany = await client.countries.get('DE', { include: 'market' })
 ```bash cURL
 # List all countries
 curl 'https://api.mystore.com/api/v3/store/countries' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # Get a country with states
-curl 'https://api.mystore.com/api/v3/store/countries/US?include=states' \
-  -H 'Authorization: Bearer pk_xxx'
+curl 'https://api.mystore.com/api/v3/store/countries/US?expand=states' \
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # Get a country with its market
-curl 'https://api.mystore.com/api/v3/store/countries/DE?include=market' \
-  -H 'Authorization: Bearer pk_xxx'
+curl 'https://api.mystore.com/api/v3/store/countries/DE?expand=market' \
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -207,7 +207,7 @@ Use the `states_required` and `zipcode_required` fields to build adaptive addres
 
 States (provinces, regions) belong to a country and are used for address validation and zone matching. Countries like the US, Canada, Australia, and India have predefined states — for these countries, customers must select a state from the list rather than typing a name.
 
-States are fetched via the country endpoint using `?include=states`:
+States are fetched via the country endpoint using `?expand=states`:
 
 
 ```typescript SDK
@@ -220,8 +220,8 @@ usa.states.forEach(state => {
 ```
 
 ```bash cURL
-curl 'https://api.mystore.com/api/v3/store/countries/US?include=states' \
-  -H 'Authorization: Bearer pk_xxx'
+curl 'https://api.mystore.com/api/v3/store/countries/US?expand=states' \
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 

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

@@ -1,6 +1,6 @@
 ---
 title: Adjustments
-description: How taxes, promotions, and other price modifications are applied to orders
+description: How Spree adjustments apply taxes, promotions, and other price modifications to orders, line items, and shipments, and how totals are recalculated.
 ---
 
 ## Overview
@@ -94,7 +94,7 @@ order.included_tax_total
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/orders/or_abc123?expand=items,fulfillments' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: <token>'
 ```
 

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

@@ -1,6 +1,6 @@
 ---
 title: Customers
-description: Customer accounts — registration, authentication, profiles, and guest checkout
+description: How Spree models customer accounts — registration, authentication, addresses, order history, store credits, and guest checkout behavior.
 ---
 
 import { Since } from '/snippets/since.mdx';
@@ -84,7 +84,7 @@ const { token, user } = await client.auth.login({
 
 ```bash cURL
 curl -X POST 'https://api.mystore.com/api/v3/store/auth/login' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'Content-Type: application/json' \
   -d '{
     "email": "john@example.com",

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

@@ -1,6 +1,6 @@
 ---
 title: Events
-description: Learn how Spree's event system works and how to subscribe to events.
+description: Spree's event system — publish and subscribe to lifecycle events from orders, products, and users to trigger background jobs and integrations.
 ---
 
 import { Since } from '/snippets/since.mdx';
@@ -65,7 +65,7 @@ module MyApp
 
     def handle(event)
       order_id = event.payload['id']
-      order = Spree::Order.find_by(id: order_id)
+      order = Spree::Order.find_by_prefix_id(order_id)
       return unless order
 
       # Your custom logic here
@@ -75,6 +75,14 @@ module MyApp
 end
 ```
 
+Then register it in an initializer — subscribers are not auto-discovered (see [Registering Subscribers](#registering-subscribers)):
+
+```ruby config/initializers/event_subscribers.rb
+Rails.application.config.after_initialize do
+  Spree.subscribers << MyApp::OrderCompletedSubscriber
+end
+```
+
 ### Subscriber DSL
 
 The `Spree::Subscriber` class provides a clean DSL for declaring subscriptions:
@@ -164,7 +172,7 @@ The payload contains serialized attributes, not the actual record. To get the re
 ```ruby
 def handle(event)
   record_id = event.payload['id']
-  record = Spree::Order.find_by(id: record_id)
+  record = Spree::Order.find_by_prefix_id(record_id)
   return unless record
 
   # Work with the record
@@ -395,9 +403,7 @@ Models without a matching serializer will use a minimal fallback payload contain
 
 ## Registering Subscribers
 
-Subscribers in `app/subscribers/` are automatically registered during application initialization.
-
-For subscribers in other locations, add them to the `Spree.subscribers` array in an initializer:
+Subscribers are not auto-discovered — every subscriber must be registered explicitly, regardless of where the class lives. Add it to the `Spree.subscribers` array in an initializer:
 
 ```ruby config/initializers/event_subscribers.rb
 Rails.application.config.after_initialize do
@@ -521,7 +527,7 @@ module MyApp
     private
 
     def find_stock_item(event)
-      Spree::StockItem.find_by(id: event.payload['id'])
+      Spree::StockItem.find_by_prefix_id(event.payload['id'])
     end
 
     def stock_dropped_below_threshold?(event, stock_item)

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

@@ -1,6 +1,6 @@
 ---
 title: Markets
-description: Multi-region commerce with Markets — bundle geography, currency, and locale into distinct selling regions within a single store.
+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';
@@ -96,7 +96,7 @@ const { data: markets } = await client.markets.list()
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/markets' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -112,7 +112,7 @@ const market = await client.markets.resolve('DE')
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/markets/resolve?country=DE' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -141,11 +141,11 @@ const usa = await client.markets.countries.get('mkt_k5nR8xLq', 'US', {
 ```bash cURL
 # List countries in a market
 curl 'https://api.mystore.com/api/v3/store/markets/mkt_k5nR8xLq/countries' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # Get a country with its states
-curl 'https://api.mystore.com/api/v3/store/markets/mkt_k5nR8xLq/countries/US?include=states' \
-  -H 'Authorization: Bearer pk_xxx'
+curl 'https://api.mystore.com/api/v3/store/markets/mkt_k5nR8xLq/countries/US?expand=states' \
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -164,11 +164,11 @@ const germany = await client.countries.get('DE', { include: 'market' })
 ```bash cURL
 # All countries across all markets
 curl 'https://api.mystore.com/api/v3/store/countries' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # Get a country with its market
-curl 'https://api.mystore.com/api/v3/store/countries/DE?include=market' \
-  -H 'Authorization: Bearer pk_xxx'
+curl 'https://api.mystore.com/api/v3/store/countries/DE?expand=market' \
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -189,10 +189,10 @@ const { data: locales } = await client.locales.list()
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/currencies' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 curl 'https://api.mystore.com/api/v3/store/locales' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 

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

@@ -1,7 +1,7 @@
 ---
 title: Media
 sidebarTitle: "Media"
-description: Product media (images, videos), named variants, focal points, and how media is served via the Store API
+description: Manage product media in Spree — images, videos, named variants, focal points, and how media is uploaded, resized, and served via the Store API.
 ---
 
 import { Since } from '/snippets/since.mdx';
@@ -114,7 +114,7 @@ products.forEach(product => {
 ```bash cURL
 # thumbnail_url is always in the response — no ?expand needed
 curl 'https://api.mystore.com/api/v3/store/products?limit=12' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -143,7 +143,7 @@ product.variants?.forEach(variant => {
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=media,variants' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 

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

@@ -1,6 +1,6 @@
 ---
 title: Orders
-description: Order lifecycle, checkout flow, line items, payments, and shipments
+description: How Spree models orders — the cart-to-completion lifecycle, checkout state machine, line items, payments, shipments, and order totals.
 ---
 
 ## Overview
@@ -109,30 +109,30 @@ await client.carts.items.delete(cart.id, 'li_xxx')
 ```bash cURL
 # Create a cart
 curl -X POST 'https://api.mystore.com/api/v3/store/carts' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # Get existing cart
 curl 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: abc123'
 
 # Add an item
 curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/items' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: abc123' \
   -H 'Content-Type: application/json' \
   -d '{ "variant_id": "var_xxx", "quantity": 2 }'
 
 # Update quantity
 curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/items/li_xxx' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: abc123' \
   -H 'Content-Type: application/json' \
   -d '{ "quantity": 3 }'
 
 # Remove an item
 curl -X DELETE 'https://api.mystore.com/api/v3/store/carts/cart_xxx/items/li_xxx' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: abc123'
 ```
 
@@ -206,7 +206,7 @@ await client.carts.complete(cartId)
 ```bash cURL
 # Set addresses
 curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: abc123' \
   -H 'Content-Type: application/json' \
   -d '{
@@ -221,14 +221,14 @@ curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
 
 # Select a delivery rate
 curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/fulfillments/ful_xxx' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: abc123' \
   -H 'Content-Type: application/json' \
   -d '{ "selected_delivery_rate_id": "rate_xxx" }'
 
 # Complete the order
 curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/complete' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: abc123'
 ```
 
@@ -249,14 +249,14 @@ await client.carts.discountCodes.remove(cartId, 'SAVE20')
 ```bash cURL
 # Apply a discount code
 curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/discount_codes' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: abc123' \
   -H 'Content-Type: application/json' \
   -d '{ "code": "SAVE20" }'
 
 # Remove a discount code
 curl -X DELETE 'https://api.mystore.com/api/v3/store/carts/cart_xxx/discount_codes/SAVE20' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: abc123'
 ```
 

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

@@ -45,11 +45,11 @@ detailed.variants?.forEach(variant => {
 ```bash cURL
 # Product price is always in the response
 curl 'https://api.mystore.com/api/v3/store/products/spree-tote' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # With variants
 curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=variants' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 

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

@@ -107,15 +107,15 @@ const sorted = await client.products.list({
 ```bash cURL
 # List products
 curl 'https://api.mystore.com/api/v3/store/products?limit=12&page=1' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # Filter by price and stock
 curl 'https://api.mystore.com/api/v3/store/products?q[price_gte]=10&q[price_lte]=50&q[in_stock]=true' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # Search
 curl 'https://api.mystore.com/api/v3/store/products?q[search]=tote+bag' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -139,7 +139,7 @@ const detailed = await client.products.get('spree-tote', {
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=variants,media,option_types,categories' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -164,11 +164,11 @@ const categoryFilters = await client.products.filters({
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products/filters' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # Scoped to a category
 curl 'https://api.mystore.com/api/v3/store/products/filters?category_id=ctg_xxx' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -228,7 +228,7 @@ product.option_types?.forEach(optionType => {
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products/spree-tee?expand=option_types' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -257,7 +257,7 @@ products.forEach(product => {
 ```bash cURL
 # thumbnail_url is always in the response — no ?expand needed
 curl 'https://api.mystore.com/api/v3/store/products?limit=12' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -286,7 +286,7 @@ product.variants?.forEach(variant => {
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=media,variants' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -338,15 +338,15 @@ const { data: products } = await client.categories.products.list('clothing/shirt
 ```bash cURL
 # List categories
 curl 'https://api.mystore.com/api/v3/store/categories' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # Get a category by permalink
 curl 'https://api.mystore.com/api/v3/store/categories/clothing/shirts' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # List products in a category
 curl 'https://api.mystore.com/api/v3/store/categories/clothing/shirts/products?limit=12' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 

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

@@ -1,6 +1,6 @@
 ---
 title: Promotions
-description: Learn about Spree's flexible promotion system for discounts, free shipping, and gifts.
+description: Build percentage and fixed-amount discounts, free shipping, BOGO offers, and coupon codes with Spree's rule and action-based promotion system.
 ---
 
 ## Overview
@@ -292,7 +292,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' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: <token>' \
   -H 'Content-Type: application/json' \
   -d '{ "code": "SUMMER20" }'

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

@@ -1,6 +1,6 @@
 ---
 title: Search & Filtering
-description: "Search, filter, and sort products and other resources via the Store API"
+description: "Use Ransack-style query parameters to search, filter, sort, and paginate products, taxons, and other resources through the Spree Store API."
 ---
 
 import { Since } from '/snippets/since.mdx';
@@ -29,7 +29,7 @@ const { data: products } = await client.products.list({
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products?q[search]=tote+bag&limit=12' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -47,7 +47,7 @@ const { data: products } = await client.products.list({
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products?q[price_gte]=20&q[price_lte]=100' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -62,7 +62,7 @@ const { data: products } = await client.products.list({
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products?q[in_stock]=true' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -89,15 +89,15 @@ 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 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # Filter by category ID (includes descendants)
 curl 'https://api.mystore.com/api/v3/store/products?q[in_category]=ctg_xxx' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # Multiple categories (OR logic)
 curl 'https://api.mystore.com/api/v3/store/products?q[in_categories][]=ctg_shirts&q[in_categories][]=ctg_pants' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -112,7 +112,7 @@ const { data: products } = await client.products.list({
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products?q[tags_cont]=sale' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -131,7 +131,7 @@ const sorted = await client.products.list({
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products?sort=price_low_to_high' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -157,11 +157,11 @@ const categoryFilters = await client.products.filters({
 ```bash cURL
 # All filters
 curl 'https://api.mystore.com/api/v3/store/products/filters' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # Scoped to a category
 curl 'https://api.mystore.com/api/v3/store/products/filters?category_id=ctg_xxx' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -221,7 +221,7 @@ const { data: products, meta } = await client.products.list({
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products?page=1&limit=24' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 

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

@@ -1,6 +1,6 @@
 ---
 title: Shipments
-description: Shipping methods, rates, split shipments, and fulfillment
+description: How Spree models shipments, shipping methods, calculators, stock locations, split shipments, and the fulfillment workflow from order to delivery.
 ---
 
 import { Since } from '/snippets/since.mdx';
@@ -111,12 +111,12 @@ await client.carts.fulfillments.update(cartId, fulfillment.id, {
 ```bash cURL
 # Get fulfillments
 curl 'https://api.mystore.com/api/v3/store/carts/cart_xxx?expand=fulfillments' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: abc123'
 
 # Select a delivery rate
 curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/fulfillments/ful_xxx' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Token: abc123' \
   -H 'Content-Type: application/json' \
   -d '{ "selected_delivery_rate_id": "rate_xxx" }'

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

@@ -22,11 +22,11 @@ const category = await client.categories.get('clothing/shirts')
 ```bash cURL
 # By slug
 curl 'https://api.mystore.com/api/v3/store/products/spree-tote' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # By ID
 curl 'https://api.mystore.com/api/v3/store/products/prod_86Rf07xd4z' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
@@ -89,11 +89,11 @@ const product = await client.products.get('chaussures-rouges', {
 ```bash cURL
 # English
 curl 'https://api.mystore.com/api/v3/store/products/red-shoes' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 
 # French
 curl 'https://api.mystore.com/api/v3/store/products/chaussures-rouges' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Locale: fr'
 ```
 

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

@@ -1,6 +1,6 @@
 ---
 title: Stores
-description: The Store is Spree's top-level tenant — products, orders, channels, markets, and stock locations all belong to exactly one store.
+description: The Store is Spree's top-level multi-tenant boundary — learn how products, orders, channels, markets, and stock locations are scoped to a store.
 ---
 
 ## Overview
@@ -42,7 +42,7 @@ const store = await client.store.get()
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/store' \
-  -H 'Authorization: Bearer pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 

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

@@ -1,6 +1,6 @@
 ---
 title: Translations
-description: Translate product content and other resources into multiple languages
+description: Translate Spree products, taxons, and other store content into multiple languages using Mobility-backed translations and locale-aware APIs.
 ---
 
 ## Overview
@@ -85,7 +85,7 @@ const { data: categories } = await client.categories.list({}, {
 ```bash cURL
 # Fetch product in French
 curl 'https://api.mystore.com/api/v3/store/products/spree-tote' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'X-Spree-Locale: fr'
 ```
 

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

@@ -1,6 +1,6 @@
 ---
 title: Users
-description: Customers and admin users — authentication, accounts, and permissions
+description: How Spree models customer and admin users — Devise authentication, account data, roles, abilities, and access permissions across stores.
 ---
 
 ## Overview
@@ -96,7 +96,7 @@ const { token, user } = await client.auth.login({
 
 ```bash cURL
 curl -X POST 'https://api.mystore.com/api/v3/store/auth/login' \
-  -H 'Authorization: Bearer pk_xxx' \
+  -H 'X-Spree-API-Key: pk_xxx' \
   -H 'Content-Type: application/json' \
   -d '{
     "email": "john@example.com",