@spree/docs 0.1.297 → 0.1.299

package/dist/api-reference/store-api/idempotency.md

@@ -25,6 +25,20 @@ curl -X POST https://api.mystore.com/api/v3/store/carts/cart_xxx/items \
 
 If the client retries this exact request with the same idempotency key, the API returns the original response with an `Idempotent-Replayed: true` header — without adding the item again.
 
+## Who A Cached Response Belongs To
+
+A cached response is only ever returned to the caller that produced it, so the request has to say who that caller is. One of these identifies them:
+
+- the **customer's access token** (`Authorization: Bearer ...`), for a signed-in shopper
+- the **cart token** (`X-Spree-Token`), for a guest working on a cart they already hold
+- a **secret key** (`sk_...`), for a server-to-server caller on the Admin API
+
+Retry with the same credentials you sent the first time. A replay answers from the cache without running the request again, so it never re-checks your access — a retry that drops or swaps a credential is treated as a different caller and runs for real.
+
+Your publishable key (`pk_...`) does not count. Every visitor to your storefront sends the same one, so a key value that two shoppers happen to share — `checkout-1`, an order number, a timestamp — would hand one shopper the other's response, cart token included.
+
+A request that carries none of the credentials above still runs exactly as it always has — it is simply never cached, so the `Idempotency-Key` header has no effect on it. Guests are not second-class here: a guest holds a cart token from the moment their cart exists, which covers the whole of checkout, including the steps where a duplicate costs money.
+
 ## Supported Endpoints
 
 | Endpoint | Actions |
@@ -38,13 +52,15 @@ If the client retries this exact request with the same idempotency key, the API
 | `POST /carts/:id/coupon_codes` | Applying coupon codes |
 | `POST /carts/:id/store_credits` | Applying store credits |
 
+Every one of these is replayable for a guest as well as for a signed-in shopper, because every one of them is reached with the cart's token. The exception is creating the cart itself: there is no cart yet, so a guest has no token to present and the key is ignored — a retry may leave behind a second, empty cart. Sign the shopper in, or accept the spare cart.
+
 Idempotency keys are ignored on `GET`, `DELETE`, and other non-supported actions.
 
 ## Key Requirements
 
 - Must be a string of **255 characters or less**
 - Should be unique per distinct operation (UUIDs are recommended)
-- Keys are scoped per API key — different API keys can use the same idempotency key without conflict
+- Keys are scoped to the caller and the store, so two callers can use the same key value without conflict
 - Cached responses expire after **24 hours**
 
 ## Response Headers

package/dist/api-reference/store.yaml

@@ -8461,7 +8461,7 @@ paths:
                   client_secret: secret_123
                 payment_method_id: pm_UkLWZg9DAJ
                 payment_source_id: card_UkLWZg9DAJ
-                payment_source_type: Spree::CreditCard
+                payment_source_type: credit_card
                 customer_id: cust_UkLWZg9DAJ
                 payment_method:
                   id: pm_UkLWZg9DAJ
@@ -12746,9 +12746,6 @@ components:
           type: string
         label:
           type: string
-        type:
-          type: string
-          deprecated: true
         field_type:
           type: string
           enum:
@@ -12765,7 +12762,6 @@ components:
       required:
       - id
       - label
-      - type
       - field_type
       - key
       - value

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

@@ -38,7 +38,7 @@ erDiagram
 | `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` |
 | `storefront_access` | Controls what an anonymous visitor may see: `public`, `prices_hidden`, or `login_required`. Unset inherits the store's setting. See [Storefront Access Gating](#storefront-access-gating) | `login_required` |
 | `guest_checkout` | Whether an order may be placed without an account on this channel. Unset inherits the store's setting | `false` |
-| `preferred_order_routing_strategy` | Optional per-channel override of the store's [Order Routing](../how-to/custom-order-routing.md) strategy | `Spree::OrderRouting::Strategy::Rules` |
+| `preferred_order_routing_strategy` | Optional per-channel override of the store's [Order Routing](../how-to/custom-order-routing.md) 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`.
 

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

@@ -243,7 +243,7 @@ split.
 ```typescript Admin SDK
 await adminClient.deliveryMethods.create({
   name: 'Pallet freight',
-  rate_provider: 'Spree::DeliveryRateProvider::Freight',
+  rate_provider: 'freight',
   rules: [
     { type: 'volume_rule', preferences: { minimum_volume: 1, maximum_volume: 15 } },
     { type: 'company_rule', preferences: { company_orders_only: true } },
@@ -257,7 +257,7 @@ curl -X POST 'https://api.mystore.com/api/v3/admin/delivery_methods' \
   -H 'Content-Type: application/json' \
   -d '{
     "name": "Pallet freight",
-    "rate_provider": "Spree::DeliveryRateProvider::Freight",
+    "rate_provider": "freight",
     "rules": [
       { "type": "volume_rule", "preferences": { "minimum_volume": 1, "maximum_volume": 15 } },
       { "type": "company_rule", "preferences": { "company_orders_only": true } }

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

@@ -257,6 +257,16 @@ curl 'https://api.mystore.com/api/v3/store/delivery_methods/dm_xxx/pickup_locati
 ```
 
 
+Third-party pickup points come from a pickup point provider — a locker network or partner-shop integration. Spree ships none; an extension registers its provider so a delivery method can select it by its short name (for example `inpost` for `SpreeInpost::PickupPointProvider`):
+
+```ruby server/config/initializers/spree.rb
+Rails.application.config.after_initialize do
+  Spree.pickup_point_providers << SpreeInpost::PickupPointProvider
+end
+```
+
+A delivery method can only use a registered provider.
+
 ## Managing fulfillments
 
 

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

@@ -71,7 +71,7 @@ Because the definition carries the type and the label, the dashboard can build a
 
 ```typescript Admin SDK
 const definition = await adminClient.customFieldDefinitions.create({
-  resource_type: 'Spree::Product',
+  resource_type: 'product',
   namespace: 'properties',
   key: 'material',
   label: 'Material',
@@ -83,7 +83,7 @@ const definition = await adminClient.customFieldDefinitions.create({
 
 ```bash CLI
 spree api post /custom_field_definitions -d '{
-  "resource_type": "Spree::Product",
+  "resource_type": "product",
   "namespace": "properties",
   "key": "material",
   "label": "Material",

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

@@ -686,7 +686,7 @@ sequenceDiagram
 | `external_client_secret` | Client secret for the frontend SDK | `seti_ABC123_secret_xyz` |
 | `external_data` | Provider-specific data | `{}` |
 | `payment_source_id` | The saved payment source created after completion | `card_xyz789` |
-| `payment_source_type` | The type of saved payment source | `Spree::CreditCard` |
+| `payment_source_type` | The type of saved payment source | `credit_card` |
 
 ### Payment Setup Session API
 

package/dist/developer/dashboard/recipes/custom-form-field.md

@@ -15,7 +15,7 @@ Create a definition for products (Settings → Custom fields, the in-place "Set
 
 ```bash
 npx spree api post custom_field_definitions --data '{
-  "resource_type": "Spree::Product",
+  "resource_type": "product",
   "namespace": "specs",
   "key": "tech_specs",
   "label": "Technical specifications",

package/dist/developer/how-to/build-a-b2b-store.md

@@ -808,7 +808,7 @@ A method priced by the **Freight** rate provider returns an unpriced rate. It re
 ```typescript Admin SDK
 await adminClient.deliveryMethods.create({
   name: 'Pallet freight',
-  rate_provider: 'Spree::DeliveryRateProvider::Freight',
+  rate_provider: 'freight',
   rules: [
     { type: 'volume_rule', preferences: { minimum_volume: 1, maximum_volume: 15 } },
     { type: 'company_rule', preferences: { company_orders_only: true } },
@@ -822,7 +822,7 @@ curl -X POST 'https://api.mystore.com/api/v3/admin/delivery_methods' \
   -H 'Content-Type: application/json' \
   -d '{
         "name": "Pallet freight",
-        "rate_provider": "Spree::DeliveryRateProvider::Freight",
+        "rate_provider": "freight",
         "rules": [
           { "type": "volume_rule", "preferences": { "minimum_volume": 1, "maximum_volume": 15 } },
           { "type": "company_rule", "preferences": { "company_orders_only": true } }

package/dist/developer/how-to/custom-digital-asset-provider.md

@@ -94,7 +94,7 @@ end
 
 Once registered, the provider appears as a source on the product's **Digital files** card: the **Add** button becomes a menu offering **Upload a file** alongside each registered provider. Picking your provider creates an asset with its `provider_type` set and no file attached.
 
-> **NOTE:** Registration is what makes a `provider_type` valid. An asset validates that its `provider_type` names a registered provider, so an unregistered or misspelled class name is rejected with a 422 rather than failing at download time. A blank `provider_type` is always the built-in `File` provider.
+> **NOTE:** Registration is what makes a `provider_type` valid. The Admin API names a provider by its shorthand — the class name's last segment, underscored, so `license_key` for the provider above and `file` for the built-in one — and an asset validates that its `provider_type` names a registered provider, so an unregistered or misspelled value is rejected with a 422 rather than failing at download time. A blank `provider_type` is always the built-in `File` provider.
 
 ## The download contract
 

package/dist/developer/how-to/custom-order-routing.md

@@ -236,7 +236,11 @@ First register the class so it's selectable (this is the allowlist the model val
 Spree.order_routing.strategies << 'Acme::Oms::Strategy'.constantize
 ```
 
-Then select it by class name string — set on `Spree::Store` (default) or `Spree::Channel` (override). Setting an unregistered class fails validation.
+Then select it — set on `Spree::Store` (default) or `Spree::Channel` (override). Setting an unregistered strategy fails validation. Ruby code may name the class; the Admin API and the dashboard name a strategy by its shorthand, `api_type` (the class name's last segment, underscored — `rules` for the built-in one). Override `self.api_type` on your strategy to give it a distinct, stable shorthand:
+
+```ruby
+def self.api_type = 'acme_oms'
+```
 
 Activate on the whole store:
 

package/dist/developer/sdk/admin/resources.md

@@ -122,7 +122,7 @@ await client.products.customFields.create('prod_xxx', {
 The generic escape hatch covers any owner type:
 
 ```typescript
-await client.customFields('Spree::Product', 'prod_xxx').list()
+await client.customFields('product', 'prod_xxx').list()
 ```
 
 ## Adding your own resources

package/dist/developer/upgrades/5.6-to-6.0.md

@@ -495,6 +495,19 @@ now returns `nil` for an ID with another model's prefix, the same as
 `find_by_prefix_id`. Call `Spree::PrefixedId.decode_prefixed_id` if you
 really need to decode any prefix.
 
+## Type values are short names, not class names
+
+The API no longer sends or accepts Ruby class names. Every value that used to name a class is now a short name (`Spree::CreditCard` becomes `credit_card`), so the API keeps the same shape whatever the server is built with. Records in the database are not touched.
+
+If your storefront or webhook receiver reads any of these fields, compare against the short name instead:
+
+| Field | Where | Before | After |
+|---|---|---|---|
+| `payment_source_type` | Store API payment setup sessions, `payment_setup_session.*` webhooks | `Spree::CreditCard` | `credit_card` |
+| `type` | Custom fields on products, variants, categories and collections | `Spree::CustomFields::ShortText` | removed — read `field_type` (`short_text`) |
+
+The Admin API follows the same rule everywhere: providers and strategies (`fulfillment_provider: 'manual'`, `preferred_order_routing_strategy: 'rules'`), custom field definition `resource_type` (`product`, `category`), tag `taggable_type`, the owner and originator types on records, and filters such as `q[type_eq]=orders`. An integration written against the Admin API preview sends and expects these short names; the [Admin SDK](../sdk/admin/resources.md) types list them.
+
 ## Every event is declared
 
 Events are now declared on the model that publishes them (`publishes_event`, `publishes_events`), and `publish_event` raises in development and test for a name nobody declared. Extensions that publish their own events need one line each — see [Publishing your own events](../core-concepts/events.md#publishing-your-own-events). In production an undeclared event is logged and still delivered.

package/dist/integrations/payments/stripe-connect.md

@@ -21,10 +21,10 @@ The same setting through the Admin API:
 
 ```typescript Admin SDK
 const { data: providers } = await adminClient.payoutProviders.list()
-// find the row with id 'SpreeStripe::PayoutProvider' — `available` says whether this store can use it
+// find the row with id 'stripe' — `available` says whether this store can use it
 
 await adminClient.store.update({
-  preferred_payout_provider: 'SpreeStripe::PayoutProvider',
+  preferred_payout_provider: 'stripe',
   preferred_default_payouts_schedule_interval: 'weekly',
   preferred_default_minimum_payout_amount: 50,
 })
@@ -34,7 +34,7 @@ await adminClient.store.update({
 curl -X PATCH https://your-store.com/api/v3/admin/store \
   -H "X-Spree-API-Key: sk_xxx" \
   -H "Content-Type: application/json" \
-  -d '{"preferred_payout_provider": "SpreeStripe::PayoutProvider", "preferred_default_payouts_schedule_interval": "weekly", "preferred_default_minimum_payout_amount": 50}'
+  -d '{"preferred_payout_provider": "stripe", "preferred_default_payouts_schedule_interval": "weekly", "preferred_default_minimum_payout_amount": 50}'
 ```
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.297",
+  "version": "0.1.299",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",