@spree/docs 0.1.177 → 0.1.178

package/dist/developer/core-concepts/taxes-discounts-fees.md

@@ -0,0 +1,199 @@
+---
+title: Taxes, Discounts & Fees
+description: How Spree records money added to or taken off an order — separate tax lines, discounts and fees, and the order totals you render in a storefront.
+---
+
+## Overview
+
+An order total is rarely just the sum of item prices. Tax gets added, a promo code takes something off, gift wrapping costs extra. Spree records each of those as its own row, of one of three kinds:
+
+| Kind | Effect | What it is |
+|---|---|---|
+| **Tax line** | adds | Tax charged on an item, on delivery, or on a fee |
+| **Discount** | subtracts | A promotion or a manual reduction |
+| **Fee** | adds | A surcharge — handling, gift wrap, cash on delivery |
+
+Keeping them apart means a direct question gets a direct answer. "What tax did we charge on this order?" is one request against tax lines, rather than filtering a mixed list and hoping you caught every case.
+
+```mermaid
+erDiagram
+    Order ||--o{ TaxLine : "has many"
+    Order ||--o{ Discount : "has many"
+    Order ||--o{ Fee : "has many"
+    LineItem ||--o{ TaxLine : "taxed by"
+    LineItem ||--o{ Discount : "reduced by"
+    Fulfillment ||--o{ TaxLine : "taxed by"
+    Fee ||--o{ TaxLine : "taxed by"
+
+    TaxLine {
+        string label
+        string rate
+        boolean included
+        string amount
+    }
+    Discount {
+        string label
+        string kind
+        string code
+        string amount
+    }
+    Fee {
+        string label
+        string kind
+        string amount
+    }
+```
+
+> **NOTE:** Money is sent as a **string** — `"15.99"`, not `15.99`. JavaScript numbers can't represent every decimal exactly, and `0.1 + 0.2` gives `0.30000000000000004`, which is not something you want inside a total. If you need to do arithmetic, use a decimal library or work in whole cents.
+
+## Building an order summary
+
+Most storefronts never need the individual rows. The order already carries a total for each kind, so you can render a summary directly:
+
+```typescript
+const order = await client.orders.get('or_xxx')
+
+order.display_item_total      // "$120.00"  items before tax and discounts
+order.display_discount_total  // "-$12.00"  everything taken off
+order.display_delivery_total  // "$5.00"    delivery
+order.display_tax_total       // "$22.60"   all tax
+order.display_total           // "$135.60"  what the customer pays
+```
+
+Every total comes in two forms: `total` is the raw value (`"135.60"`) and `display_total` is formatted for the order's currency (`"$135.60"`). Render the `display_` one — it handles the symbol, decimal separator and where the symbol goes.
+
+| Attribute | What it sums |
+|---|---|
+| `item_total` | Line item prices before tax and discounts |
+| `discount_total` | All discounts |
+| `tax_total` | All tax |
+| `included_tax_total` | Tax already inside displayed prices |
+| `additional_tax_total` | Tax added on top |
+| `delivery_total` | Delivery charges |
+| `total` | What the customer pays |
+
+> **WARNING:** If you add up a subtotal yourself, include `additional_tax_total` only. `included_tax_total` is **already inside** the item prices — adding it again counts the tax twice. This is the most common mistake when building a European storefront.
+
+## Tax lines
+
+A tax line records one tax charge and what it was charged on.
+
+| Attribute | Description |
+|---|---|
+| `label` | What the customer sees, e.g. `VAT 20%` |
+| `rate` | The rate applied, e.g. `"0.2"` |
+| `included` | Whether the tax was already inside the displayed price |
+| `amount` / `display_amount` | Tax charged |
+| `line_item_id` / `fulfillment_id` / `fee_id` | What was taxed — exactly one is set |
+| `tax_rate_id` | The configured rate, when tax came from Spree rather than an outside service |
+
+`included` is the field that trips people up. In most of Europe a €120 price already contains €20 of VAT, so the tax line is there for information — the customer pays €120, not €140. In the US, tax is added at checkout, so the same field is `false` and the amount really is extra.
+
+```typescript Admin SDK
+const taxLines = await adminClient.orders.taxLines.list('or_xxx')
+```
+
+You never create tax lines yourself. They're written whenever the order total is worked out — see [Taxes](taxes.md).
+
+## Discounts
+
+| Attribute | Description |
+|---|---|
+| `label` | What the customer sees, e.g. `Summer Sale` |
+| `kind` | `promotion` or `manual` |
+| `code` | The coupon code used, if any |
+| `value` / `value_type` | The rule behind it, e.g. `"10"` / `percent`. Accepts a string or a number on write. |
+| `amount` / `display_amount` | The reduction, as a negative amount |
+| `promotion_id` | The promotion it came from |
+| `line_item_id` / `fulfillment_id` | What it reduced |
+
+Most discounts come from [Promotions](promotions.md) — a customer applies a code and the rows appear. A **manual** discount is one an admin adds directly, for a goodwill gesture or a price match:
+
+
+```typescript Admin SDK
+// 10% off a single line item
+await adminClient.orders.discounts.create('or_xxx', {
+  label: 'Goodwill discount',
+  value: '10',
+  value_type: 'percent',
+  line_item_id: 'li_xxx',
+})
+
+// A flat amount across the order
+await adminClient.orders.discounts.create('or_xxx', {
+  label: 'Price match',
+  value: '15.00',
+  value_type: 'flat',
+})
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/orders/or_xxx/discounts' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "label": "Goodwill discount", "value": 10, "value_type": "percent" }'
+```
+
+
+Only manual discounts can be edited or deleted. Changing one that came from a promotion returns a `422` — those belong to the promotion that created them, and letting an order disagree with its own promotion is how reporting stops adding up.
+
+A discount on the whole order is shared out across the items rather than kept as one lump sum. So if the customer later returns one item, Spree knows how much of the discount belonged to it.
+
+## Fees
+
+| Attribute | Description |
+|---|---|
+| `label` | What the customer sees, e.g. `Gift wrapping` |
+| `kind` | `surcharge`, `handling`, `gift_wrap`, `cod`, `payment`, `duty`, or your own |
+| `amount` / `display_amount` | The charge |
+| `line_item_id` / `fulfillment_id` | What it applies to — both empty means the whole order |
+
+```typescript Admin SDK
+await adminClient.orders.fees.create('or_xxx', {
+  label: 'Gift wrapping',
+  kind: 'gift_wrap',
+  amount: '5.00',
+  line_item_id: 'li_xxx',
+})
+```
+
+Fees are always positive, and they're taxable by default — a fee can have its own tax lines. Customs duties are the one exception, described below. To take money off, create a discount instead. That way a refund never has to work out whether a negative fee was a charge or a credit.
+
+### Customs duties
+
+A `duty` fee is the one kind tax is **not** applied to automatically. A customs duty is an import charge levied by the destination country, not a sale that domestic tax applies to, so charging tax on top of it would invent tax the merchant never owed. Where import VAT is charged on a duty, whoever calculates the duty records that tax itself.
+
+A duty also keeps a copy of what it was calculated from — the HS code, the country of origin, the rate — in its `metadata`. Classification on a product can change next month; what the customer was charged must not.
+
+## Where rows attach
+
+Each row points at exactly the thing it applies to:
+
+- **Tax lines** → a line item, a [fulfillment](fulfillments.md), or a fee, so item tax and delivery tax stay separately visible
+- **Discounts** → a line item or a fulfillment
+- **Fees** → a line item, a fulfillment, or the order itself
+
+Rows also keep a copy of where they came from — the rate and label on a tax line, the code and promotion on a discount. If someone deletes that promotion next month, the order still says what the customer was actually given.
+
+## When totals change
+
+Totals are worked out again whenever something changes on a cart — an item added, an address entered, a code applied. The response to every cart change already includes the new totals, so a follow-up request is never needed:
+
+```typescript
+// The returned cart already has updated totals
+const cart = await client.carts.items.create(cartId, {
+  variant_id: 'var_xxx',
+  quantity: 2,
+})
+
+cart.display_total // already correct
+```
+
+Once an order is placed, the rows stop being regenerated. Editing a placed order re-adds its existing rows rather than starting from scratch, so today's promotions can't quietly rewrite what a customer agreed to last week.
+
+## Related
+
+- [Taxes](taxes.md) — how tax is worked out
+- [Promotions](promotions.md) — where most discounts come from
+- [Fulfillments](fulfillments.md) — delivery charges
+- [Orders](orders.md) — order totals and statuses

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

@@ -37,7 +37,7 @@ erDiagram
 - **Tax Category** groups products for tax purposes (e.g., "Clothing", "Food", "Digital")
 - **Tax Rate** defines the percentage and rules for a Tax Category within a [Zone](addresses.md#zones)
 - **Zone** defines geographic regions (countries or states) where taxes apply
-- **[Adjustments](adjustments.md)** are created on orders/line items to apply taxes
+- **[Adjustments](taxes-discounts-fees.md)** are created on orders/line items to apply taxes
 
 ## Tax Categories
 
@@ -127,7 +127,7 @@ During checkout, taxes are calculated based on the shipping address:
 
 1. The customer's shipping address determines their [Zone](addresses.md#zones)
 2. Spree finds matching tax rates for that zone and the product's tax category
-3. Tax [Adjustments](adjustments.md) are created on line items
+3. Tax [Adjustments](taxes-discounts-fees.md) are created on line items
 4. The order total is updated
 
 > **NOTE:** For complex tax requirements (interstate US sales, international VAT), consider using automated tax calculation. The [Stripe Tax integration](../../integrations/payments/stripe.md) handles this automatically.
@@ -158,6 +158,6 @@ Tax categories and rates are managed in the Admin Panel under **Settings → Tax
 
 - [Markets](markets.md) — Tax-inclusive pricing per market
 - [Addresses](addresses.md) — Zones and address-based taxation
-- [Adjustments](adjustments.md) — Tax adjustments
+- [Adjustments](taxes-discounts-fees.md) — Tax adjustments
 - [Orders](orders.md) — How taxes affect order totals
 - [Avalara integration](../../integrations/tax/avalara.md) — Automated tax calculation for complex jurisdictions

package/dist/developer/create-spree-app/quickstart.md

@@ -1,6 +1,6 @@
 ---
 title: "create-spree-app"
-sidebarTitle: Overview
+sidebarTitle: create-spree-app
 description: "Scaffold a new Spree Commerce project with a single command — bootstraps a full Rails backend, Docker dev stack, and the @spree/cli for customization."
 ---
 

package/dist/developer/customization/api.md

@@ -5,7 +5,7 @@ description: Add new Store API endpoints, customize existing JSON responses with
 
 Before you start customizing Spree API endpoints, make sure you reviewed all existing API endpoints in the [Spree API docs](../../api-reference/admin-api/endpoints.md).
 
-For a step-by-step walkthrough of adding a complete new resource (model, serializer, controller, routes), see the [API tutorial](../tutorial/api.md).
+For a step-by-step walkthrough of adding a complete new resource (model, serializer, controller, routes), see the [API tutorial](../tutorial/admin-api.md).
 
 ## Customizing JSON Responses
 
@@ -35,7 +35,7 @@ Restart the server and the Product API will include your new attribute.
 
 ### Adding an Association
 
-Let's say you've created a `Spree::Brand` model that belongs to `Product` (see the [tutorial](../tutorial/api.md) for the full example).
+Let's say you've created a `Spree::Brand` model that belongs to `Product` (see the [tutorial](../tutorial/admin-api.md) for the full example).
 
 Create a serializer for the new model:
 
@@ -173,20 +173,45 @@ end
 
 ### Permitted Attributes
 
-For endpoints that accept writes (create/update), add your attributes:
+For endpoints that accept writes (create/update), declare the attributes in your
+controller:
 
-```ruby config/initializers/spree.rb
-Spree::PermittedAttributes.brand_attributes = [:name, :slug, :description, :logo]
+```ruby
+def resource_permitted_attributes
+  [:name, :slug, :description, :logo]
+end
 ```
 
-Or override `permitted_params` in the controller:
+Entries are `params.permit` fragments, so collections and nested structures use
+the shapes you would pass there directly — `[:name, { region_ids: [] }]`.
 
-```ruby
-def permitted_params
-  params.permit(:name, :slug, :description, :logo)
-end
+> **NOTE:** Declare `resource_permitted_attributes`, not `permitted_attributes`. The
+>   latter is what appends extension-contributed attributes to your list, so
+>   overriding it replaces them.
+
+### Adding an Attribute to a Core Resource
+
+To make a new column writable on a Spree model without decorating the
+controllers that write it, append to the model's permitted attributes:
+
+```ruby config/initializers/spree.rb
+Spree::Product.additional_permitted_attributes += [:brand_id]
 ```
 
+Standard resource endpoints append these to their own allowlist, so one
+declaration covers the model's create and update endpoints.
+
+Use `+=`, never `=` — assigning replaces what another extension added — and
+declare only attributes of your own, since redeclaring a key the controller
+already permits replaces its filter rather than widening it.
+
+> **NOTE:** For merchant-managed data, prefer [Custom Fields](../core-concepts/metafields.md),
+>   which need no code and are filterable and sortable. This is for extensions
+>   that add real database columns.
+
+Two endpoints deliberately ignore this hook because their parameters are
+authorization data rather than resource data: API keys and invitations.
+
 ## Consuming Custom Endpoints with the SDK
 
-See the [SDK tutorial](../tutorial/sdk.md) for how to call custom endpoints from TypeScript and extend the generated types.
+See the [SDK tutorial](../tutorial/storefront.md) for how to call custom endpoints from TypeScript and extend the generated types.

package/dist/developer/customization/configuration.md

@@ -1,55 +1,225 @@
 ---
-title: "Configuration"
+title: Configuration
+description: Every global Spree setting that is actually read by Spree 6 — grouped by area, with defaults and what each one changes.
 ---
 
-Here is a list of all the configuration options that are available in Spree.
-
- | Configuration Key                  | Description                                                                                           | Default Value       |
-      |------------------------------------|-------------------------------------------------------------------------------------------------------|---------------------|
-      | `allow_checkout_on_gateway_error`  | Continues the checkout process even if the payment gateway error failed.                             | `false`             |
-      | `address_requires_phone`            | Determines whether a phone number is required for Addresses. | `false`              |
-      | `alternative_shipping_phone`       | Determines if an alternative phone number should be present for the shipping address on the checkout page. | `false`         |
-      | `always_include_confirm_step`      | Determines if the confirmation step is always included in the checkout process, regardless of the payment method. | `false`             |
-      | `auto_capture`                     | Depending on whether or not Spree is configured to "auto capture" the credit card, either a purchase or an authorize operation will be performed on the card (via the current credit card gateway). | `true` |
-      | `auto_capture_on_dispatch`         | Captures payment for each shipment in Shipment#after_ship callback, and makes Shipment.ready when payment authorized. | `false` |
-      | `company`                          | Determines whether or not a field for "Company" displays on the address form. | `false`            |
-      | `credit_to_new_allocation`         | Determines if a new allocation is created anytime store credit is added. If not set, it will update the store credit's amount in place. | `false`             |
-      | `disable_sku_validation`             | Determines if the built-in SKU uniqueness validation is disabled. | `false`             |
-      | `disable_store_presence_validation` | Determines if Store presence validation for Products and Payment Methods is disabled. | `false`             |
-      | `expedited_exchanges`               | Determines if an exchange shipment is kicked off upon return authorization save. Requires payment profiles to be supported on your gateway and a configured delayed job handler. | `false`             |
-      | `expedited_exchanges_days_window`   | The number of days the customer has to return their item after the expedited exchange is shipped to avoid being charged. | `14`                |
-      | `restock_inventory`                 | Determines if inventory should be restocked when an order is canceled or returned                              | `true`              |
-      | `return_eligibility_number_of_days` | The number of days after purchase within which a return can be initiated. | `365` |
-      | `show_products_without_price`      | Determines if products without a price are shown in the storefront and Storefront API | `false`             |
-      | `tax_using_ship_address`           | Determines if tax information should be based on shipping address, rather than the billing address.  | `true`              |
-      | `track_inventory_levels`           | Determines if inventory levels should be tracked when products are purchased at checkout. This option causes new `InventoryUnit` objects to be created when a product is bought. | `true` |
-
-## Spree Initializer
-
-To change values for these preferences, you need to edit your `config/initializers/spree.rb` file.
-
-For example, to disable the `expedited_exchanges` feature, you would add the following line:
+Global settings live in `config/initializers/spree.rb` and apply to the whole application. Anything that varies per store — currency, markets, delivery zones, languages — is data you change in the dashboard instead.
 
-```ruby
+```ruby config/initializers/spree.rb
 Spree.config do |config|
-  config.expedited_exchanges = false
+  config.minimum_password_length = 10
+  config.allow_empty_price_amount = true
 end
 ```
 
-> **NOTE:** Remember to restart your Rails server after making changes to the `config/initializers/spree.rb` file.
+> **NOTE:** Restart your Rails server after editing the initializer.
+
+## Deployment settings read the environment
+
+Settings that describe the deployment rather than commerce behavior can be set with an environment variable — no Ruby, no code change, no restart-after-edit dance. An explicitly configured value always wins over the environment.
+
+| Setting | Environment variable | What it configures |
+|---|---|---|
+| `dashboard_url` | `SPREE_DASHBOARD_URL` | Origin where the admin dashboard is hosted (e.g. `https://admin.my-shop.com`). Used for every link that sends someone into the dashboard: invitation emails, SSO redirects, and the first-run setup link printed by `db:seed`. |
+
+This page lists only settings Spree 6 actually reads. Settings that exist for backwards compatibility are listed under [Deprecated settings](#deprecated-settings) rather than mixed in with the rest.
+
+## Settings that belong to a store
+
+Settings that shape how a shop sells — when customers are charged, whether stock is counted, which products appear without a price — are properties of a store, not of the installation, so they live on `Spree::Store` and are edited in the dashboard under **Settings → Store**:
 
-## Accessing Configuration
+`capture_method`, `track_inventory_levels`, `stock_reservations_enabled`, `stock_reservation_ttl_minutes`, `track_price_history`, `show_products_without_price`, `disable_sku_validation`, `address_requires_phone`, `company_field_enabled`, `tax_using_ship_address`, plus `guest_checkout` and `storefront_access` — those last two are owned by the channel, and the store's value is what a channel falls back to.
 
-To access these preferences in your application, you can use the `Spree::Config` module. For example, to access the `expedited_exchanges` preference, you can do the following:
+They were global before Spree 6. The global versions still exist for one release but are no longer read, so setting one in the initializer changes nothing — run `bin/rake spree:store_settings:backfill_from_config` during the upgrade to copy your values onto every store.
 
 ```ruby
-Spree::Config.expedited_exchanges
+store = Spree::Current.store
+store.preferred_capture_method                # => "checkout"
+store.update!(preferred_track_inventory_levels: false)
 ```
 
-This will return the current value of the `expedited_exchanges` preference. You can also set the value of a preference using the `Spree::Config` module. For example, to set the `expedited_exchanges` preference to `true`, you can do the following:
+### When customers are charged
+
+`capture_method` says when a customer is charged rather than only authorized. It applies to every payment method, not just card gateways. It takes one of three values:
+
+| Value | What happens |
+|---|---|
+| `checkout` | The money is taken as soon as the order is placed. This is the default. |
+| `on_dispatch` | The amount is authorized at checkout and captured when the goods are dispatched. |
+| `manual` | The amount is authorized at checkout and staff capture it when they choose. |
+
+A payment method can override the store for its own payments by setting the same three values; leaving it blank inherits the store's choice. Ask a payment method what applies with `resolved_capture_method`, or use the `capture_at_checkout?`, `capture_on_dispatch?` and `capture_manually?` questions.
 
 ```ruby
-Spree::Config.expedited_exchanges = true
+payment_method.update!(capture_method: 'on_dispatch')
+payment_method.resolved_capture_method        # => "on_dispatch"
+
+payment_method.update!(capture_method: nil)   # back to inheriting
+payment_method.resolved_capture_method        # => "checkout"
 ```
 
-This will set the `expedited_exchanges` preference to `true` for the current process. After restarting the Rails server, the preference will return to the default value or the one set in the initializer.
+Before Spree 6 this was two separate booleans, `auto_capture` and `auto_capture_on_dispatch`, which could contradict each other. Two upgrade tasks carry existing installs over: `spree:store_settings:backfill_from_config` maps the old globals onto each store's `capture_method`, and `spree:migrate_capture_methods` converts the per-payment-method `auto_capture` column. A method left without a value inherits its store.
+
+## Checkout and payments
+
+| Setting | Default | What it does |
+|---|---|---|
+| `always_include_confirm_step` | `false` | Always shows a confirmation step, even when the payment method doesn't need one. |
+| `credit_to_new_allocation` | `false` | Records refunded store credit as a new entry each time instead of topping the original credit back up. |
+
+## Carts and stock reservations
+
+| Setting | Default | What it does |
+|---|---|---|
+| `guest_cart_expiry_days` | `30` | How long an abandoned guest cart is kept before deletion. |
+| `customer_cart_expiry_days` | `90` | How long a signed-in customer's abandoned cart is kept. |
+| `empty_cart_expiry_hours` | `48` | How long a cart with no items is kept. |
+
+## Products and pricing
+
+| Setting | Default | What it does |
+|---|---|---|
+| `allow_empty_price_amount` | `false` | Allows a price to be left blank instead of requiring an amount. Prices in a price list already allow blank. |
+| `price_history_retention_days` | `30` | How many days of price history the `spree:price_history:prune` task keeps. |
+| `always_use_translations` | `false` | Always read product, category and collection names from the translation tables, even in the store's own default language. |
+
+## Addresses
+
+| Setting | Default | What it does |
+|---|---|---|
+| `geocode_addresses` | `true` | Looks up latitude and longitude for saved addresses. |
+
+## Media
+
+| Setting | Default | What it does |
+|---|---|---|
+| `max_image_download_size` | `20971520` | Largest file size, in bytes, accepted when downloading an image from an external URL. |
+| `images_save_from_url_job_attempts` | `5` | How many times to retry fetching an external image before giving up. |
+
+## Promotions and gift cards
+
+| Setting | Default | What it does |
+|---|---|---|
+| `coupon_codes_web_limit` | `500` | How many coupon codes are created immediately when saving a promotion. Larger batches move to a background job so saving stays fast. |
+| `coupon_codes_total_limit` | `5000` | Maximum coupon codes a single promotion may generate. |
+| `gift_card_batch_web_limit` | `500` | How many gift card codes a batch creates immediately before switching to a background job. |
+| `gift_card_batch_limit` | `50000` | Maximum gift card codes in a single batch. |
+
+## Accounts and passwords
+
+| Setting | Default | What it does |
+|---|---|---|
+| `minimum_password_length` | `8` | Shortest password a customer or staff member may set. |
+| `maximum_password_length` | `72` | Longest password allowed. |
+| `max_failed_login_attempts` | `5` | Failed sign-ins before an account is temporarily locked. |
+| `lockout_duration` | `1800` | How long an account stays locked, in seconds. |
+| `customer_password_reset_expires_in` | `15` | How long a customer's password reset link stays valid, in minutes. |
+| `admin_password_reset_expires_in` | `15` | How long a staff password reset link stays valid, in minutes. |
+
+## URLs
+
+| Setting | Default | What it does |
+|---|---|---|
+| `dashboard_url` | `nil` | Where the React dashboard lives, so single sign-on can send staff back to it after they authenticate. |
+| `admin_url` | `nil` | Base address used to build staff invitation links in email. Invitation links are relative when this is unset. |
+
+## Imports and events
+
+| Setting | Default | What it does |
+|---|---|---|
+| `large_import_threshold` | `500` | Row count above which a CSV import switches to bulk processing — faster, with less live progress detail. |
+| `events_log_enabled` | `true` | Writes every Spree event to the Rails log. |
+| `disable_migration_check` | `false` | Silences the boot warning about pending engine migrations. |
+
+## API settings
+
+API settings live on their own configuration object:
+
+```ruby config/initializers/spree.rb
+Spree::Api::Config.jwt_expiration = 1800
+```
+
+### Authentication
+
+| Setting | Default | What it does |
+|---|---|---|
+| `jwt_expiration` | `3600` | How long a customer or store access token stays valid, in seconds. |
+| `admin_jwt_expiration` | `300` | How long a staff access token stays valid. Deliberately short — admin tokens carry far more privilege. |
+| `refresh_token_expiry` | `2592000` | How long a refresh token stays valid, in seconds (30 days). |
+| `jwt_secret_key` | `nil` | Signing key for tokens. Falls back to the Rails secret key base. |
+
+### Rate limits
+
+| Setting | Default | What it does |
+|---|---|---|
+| `rate_limit_window` | `60` | Length of the rate-limit window, in seconds. |
+| `rate_limit_per_key` | `300` | Requests allowed per window for each publishable API key + client IP pair (per visitor), and for keyless traffic per IP. Applies across the whole API, not per endpoint. |
+| `rate_limit_per_secret_key` | `600` | Requests allowed per secret API key per window, across the whole API. |
+| `rate_limit_login` | `5` | Sign-in attempts allowed per IP per window. |
+| `rate_limit_register` | `3` | Registration attempts per IP. |
+| `rate_limit_refresh` | `10` | Token refresh attempts per IP. |
+| `rate_limit_password_reset` | `3` | Password reset requests per IP. |
+| `max_request_body_size` | `102400` | Largest accepted request body, in bytes (100 KB). |
+
+### Webhooks
+
+| Setting | Default | What it does |
+|---|---|---|
+| `webhooks_enabled` | `true` | Whether webhooks fire at all. |
+| `webhooks_verify_ssl` | `true` | Verifies SSL certificates on webhook endpoints. Off in development. |
+
+## Reading a setting
+
+```ruby
+Spree::Config.minimum_password_length  # => 8
+Spree::Api::Config.jwt_expiration      # => 3600
+```
+
+Assigning at runtime affects only the current process and is lost on restart. Set values in the initializer to make them stick.
+
+## Deprecated settings
+
+These still exist so upgrades don't break, but Spree 6 either ignores them or reads them only from subsystems it has replaced. Don't use them in new code.
+
+| Setting | Use instead |
+|---|---|
+| `return_eligibility_number_of_days` | The `return_window_days` preference on [Market](../core-concepts/markets.md), or a `returns.create.validate` [hook](workflows.md) |
+| `restock_inventory` | Restocking is decided per return line item by its resellable flag — see [Returns](../core-concepts/returns-exchanges-claims.md#processing-a-return) |
+| `expedited_exchanges` | [Exchanges](../core-concepts/returns-exchanges-claims.md) |
+| `expedited_exchanges_days_window` | [Exchanges](../core-concepts/returns-exchanges-claims.md) |
+| `enable_legacy_default_price` | Compatibility switch for the old default-price behavior; leave off |
+| `use_user_locale` | Locale comes from the `x-spree-locale` header or the `locale` parameter |
+| `company` | The `company_field_enabled` setting on the store |
+| `address_requires_phone` | The `address_requires_phone` setting on the store |
+| `default_stock_reservation_ttl_minutes` | The `stock_reservation_ttl_minutes` setting on the store |
+| `auto_capture` | The `capture_method` setting on the store |
+| `auto_capture_on_dispatch` | The `capture_method` setting on the store |
+| `stock_reservations_enabled` | The `stock_reservations_enabled` setting on the store |
+| `track_inventory_levels` | The `track_inventory_levels` setting on the store |
+| `show_products_without_price` | The `show_products_without_price` setting on the store |
+| `disable_sku_validation` | The `disable_sku_validation` setting on the store |
+| `track_price_history` | The `track_price_history` setting on the store |
+| `tax_using_ship_address` | The `tax_using_ship_address` setting on the store |
+| `disable_store_presence_validation` | Every store-owned record now requires a store |
+
+> **WARNING:** These settings have no effect at all in Spree 6, and are scheduled for removal: `allow_checkout_on_gateway_error` (completion checks whether payments cover the total, so a failed gateway call never completes an order), `products_per_page`, `alternative_shipping_phone`, `show_variant_full_price`, `reserve_stock_on`, `storefront_products_path`, `storefront_taxons_path`, `storefront_pages_path`. Setting them changes nothing.
+
+## Settings removed in Spree 6
+
+These were deprecated in Spree 5 and are gone. Assigning one in your initializer now raises `NoMethodError`, so delete the line.
+
+| Setting | What to do instead |
+|---|---|
+| `send_core_emails` | The `send_consumer_transactional_emails` setting on the store, which turns a shop's customer emails on and off. |
+| `currency` | Currency belongs to the store and the market. |
+| `address_requires_state` | State requirements come from the address country. |
+| `checkout_zone` | Use [delivery zones](../core-concepts/fulfillments.md#delivery-methods-and-zones). |
+| `allow_guest_checkout` | Use the `guest_checkout` setting on the store or channel. |
+| `binary_inventory_cache` | A stock change always touches its variant. |
+| `logo`, `mailer_logo` | The store's own `logo` and `mailer_logo` images, uploaded in the dashboard. Only the global settings are gone; the images themselves are unchanged. |
+| `layout`, `always_put_site_name_in_title`, `title_site_name_separator`, `max_level_in_taxons_menu`, `show_raw_product_description`, `shipping_instructions`, `show_only_complete_orders_by_default` | These configured the removed Rails storefront and admin. A storefront owns its own presentation. |
+
+## Related
+
+- [Model preferences](model-preferences.md) — per-record settings
+- [Services & Workflows](workflows.md) — changing behavior rather than settings

package/dist/developer/customization/decorators.md

@@ -8,9 +8,9 @@ description: Use Spree decorators to add or modify behavior on core models, cont
 >   - **[Events & Subscribers](../core-concepts/events.md)** - For reacting to model changes (after save, create, update, delete)
 >   - **[Webhooks](../core-concepts/webhooks.md)** - For notifying external services when events occur
 >   - **[Dependencies](dependencies.md)** - For swapping out services, serializers, and abilities
->   - **[Admin Navigation](../admin/navigation.md)** - For adding menu items without controller decorators
->   - **[Admin Partials](../admin/extending-ui.md)** - For extending admin UI without view decorators
->   - **[Admin Tables](../admin/tables.md)** - For customizing admin list views
+>   - **[Admin Navigation](../dashboard/customization/navigation.md)** - For adding menu items without controller decorators
+>   - **[Admin Partials](../dashboard/customization/quickstart.md)** - For extending admin UI without view decorators
+>   - **[Admin Tables](../dashboard/customization/tables.md)** - For customizing admin list views
 >   - **[Ransack Configuration](../core-concepts/search-filtering.md#extending-ransackable-configuration)** - For adding searchable/sortable fields without model decorators
 
 ## When to Use Decorators vs Modern Alternatives
@@ -23,8 +23,8 @@ Before reaching for a decorator, check if your use case is better served by a mo
 | Notify external service on changes | Model decorator with callbacks | [Webhooks](../core-concepts/webhooks.md) |
 | Custom add-to-cart logic | Service decorator | [Dependencies injection](dependencies.md) |
 | Custom API responses | Serializer decorator | [Dependencies injection](dependencies.md) |
-| Add admin menu item | Controller decorator | [Admin Navigation API](../admin/navigation.md) |
-| Add section to admin form | View decorator/override | [Admin Partials injection](../admin/extending-ui.md) |
+| Add admin menu item | Controller decorator | [Admin Navigation API](../dashboard/customization/navigation.md) |
+| Add section to admin form | View decorator/override | [Admin Partials injection](../dashboard/customization/quickstart.md) |
 | Add searchable/filterable field | Model decorator with `ransackable_attributes` | [Ransack configuration](../core-concepts/search-filtering.md#extending-ransackable-configuration) |
 | Add association to core model | - | Decorator (still appropriate) |
 | Add validation to core model | - | Decorator (still appropriate) |
@@ -528,7 +528,7 @@ end
 - [Events](../core-concepts/events.md) - Learn about Spree's event system
 - [Webhooks](../core-concepts/webhooks.md) - HTTP callbacks for external integrations
 - [Dependencies](dependencies.md) - Swap core services with your own
-- [Admin Navigation](../admin/navigation.md) - Extend admin menu without decorators
-- [Admin Partials](../admin/extending-ui.md) - Extend admin UI without view decorators
-- [Extending Core Models Tutorial](../tutorial/extending-models.md) - Step-by-step guide to connecting custom models with Spree core
+- [Admin Navigation](../dashboard/customization/navigation.md) - Extend admin menu without decorators
+- [Admin Partials](../dashboard/customization/quickstart.md) - Extend admin UI without view decorators
+- [Extending Core Models Tutorial](../tutorial/model.md) - Step-by-step guide to connecting custom models with Spree core
 - [Customization Overview](quickstart.md) - General customization patterns