@spree/docs 0.1.181 → 0.1.183

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

@@ -1,303 +1,126 @@
 ---
 title: Calculators
+description: The small pieces of arithmetic behind delivery charges and promotion discounts — what each one does and how to choose between them.
 ---
 
 ## Overview
 
-### Calculator Model Diagram
-
-```mermaid
-erDiagram
-    Calculator {
-        string type
-        string calculable_type
-        text preferences
-    }
-
-    TaxRate {
-        string name
-        decimal amount
-        boolean included_in_price
-    }
-
-    ShippingMethod {
-        string name
-        string display_on
-    }
-
-    PromotionAction {
-        string type
-    }
-
-    Adjustment {
-        decimal amount
-        string label
-    }
-
-    TaxRate ||--|| Calculator : "has one"
-    ShippingMethod ||--|| Calculator : "has one"
-    PromotionAction ||--|| Calculator : "has one"
-    TaxRate ||--o{ Adjustment : "creates"
-    ShippingMethod ||--o{ ShippingRate : "calculates"
-    PromotionAction ||--o{ Adjustment : "creates"
-```
-
-**Key relationships:**
-- **Calculator** computes amounts for various features
-- Used by **[Tax Rates](taxes.md)** to calculate tax amounts
-- Used by **[Shipping Methods](fulfillments.md)** to calculate shipping costs
-- Used by **[Promotion Actions](promotions.md)** to calculate discounts
-- Calculators store [preferences (rates, percentages, etc.)](../customization/model-preferences.md) for their calculations
-
-Spree makes extensive use of the `Spree::Calculator` model and there are several subclasses provided to deal with various types of calculations flat rate, percentage discount, sales tax, VAT, etc. All calculators extend the `Spree::Calculator` class and must provide the following methods:
-
-```ruby
-def self.description
-  # Human readable description of the calculator
-end
-
-def compute(object=nil)
-  # Returns the value after performing the required calculation
-end
-```
-
-Calculators link to a `calculable` object, which are typically one of `Spree::ShippingMethod`, `Spree::TaxRate`, or `Spree::Promotion::Actions::CreateAdjustment`. These three classes use the `Spree::CalculatedAdjustments` module described below to provide an easy way to calculate adjustments for their objects.
-
-## Available Calculators
-
-The following are descriptions of the currently available calculators in Spree. If you would like to add your own, please see the [Creating a New Calculator](#creating-a-new-calculator) section.
-
-### Default Tax
-
-For information about this calculator, please read the [Taxes](taxes.md) guide.
-
-### Flat Percent Per Item Total
-
-This calculator has one preference: `flat_percent` and can be set like this:
-
-```ruby
-calculator.preferred_flat_percent = 10
-```
-
-This calculator takes an order and calculates an amount using this calculation:
-
-```ruby
-[item total] x [flat percentage]
-```
-
-For example, if an order had an item total of `$31` and the calculator was configured to have a flat percent amount of `10`, the discount would be `$3.10`, because `$31 x 10% = $3.10`.
-
-### Flat Rate
-
-This calculator can be used to provide a flat rate discount.
-
-This calculator has two preferences: `amount` and `currency`. These can be set like this:
-
-```ruby
-calculator.preferred_amount = 10
-calculator.preferred_currency = "USD"
-```
-
-The currency for this calculator is used to check to see if a shipping method is available for an order. If an order's currency does not match the shipping method's currency, then that shipping method will not be displayed on the frontend.
-
-This calculator can take any object and will return simply the preferred amount.
-
-### Flexi Rate
-
-This calculator is typically used for promotional discounts when you want a specific discount for the first product, and then subsequent discounts for other products, up to a certain amount.
+A calculator works out an amount. "Charge $5 per item." "Take 15% off." "Free over $50, otherwise $7."
 
-This calculator takes three preferences:
+They exist because the rule and the number are different questions. A promotion decides *whether* a discount applies; a calculator decides *how much*. Keeping them apart means a merchant can change "10% off" to "$10 off" without touching the conditions that decide who qualifies.
 
-* `first_item`: The discounted price of the first items.
-* `additional_item`: The discounted price of subsequent items.
-* `max_items`: The maximum number of items this discount applies to.
+Two things use calculators:
 
-The calculator computes based on this:
+- **[Delivery methods](fulfillments.md)** — what delivery costs
+- **[Promotions](promotions.md)** — how big a discount is
 
-```text
-[first item discount] + (([items_count*] - 1) x [additional item discount])
-```
-
-* up to the `max_items`
-
-Thus, if you have ten items in your shopping cart, your `first_item` preference is set to `$10`, your `additional_items` preference is set to `$5`, and your `max_items` preference is set to `4`, the total discount would be `$25`:
-
-* `$10` for the first item
-* `$5` for each of the `3` subsequent items: `$5 \* 3 = $15`
-* `$0` for the remaining `6` items
-
-### Per Item
-
-The Per Item calculator (`Spree::Calculator::Shipping::PerItem`) is a shipping calculator that charges a flat amount for every item in a shipment.
-
-This calculator takes two preferences:
-
-* `amount`: The flat amount charged per item.
-* `currency`: The currency for this calculator.
-
-It computes a flat rate per item by multiplying the `amount` preference by the total item quantity in the shipment package:
-
-```text
-[amount] x [total item quantity in package]
-```
-
-For example, with an `amount` of `5` and a package containing `3` items in total, the calculator computes an amount of `15` (`5 x 3`).
-
-### Percent Per Item
-
-The Percent Per Item calculator (`Spree::Calculator::PercentOnLineItem`) applies a percentage discount to a single line item. It takes two preferences:
+> **INFO:** Tax does **not** use calculators. Tax is worked out by a [tax provider](taxes.md), which can be Spree's own rate tables or an external service.
 
-* `percent`: The percentage to apply to the line item's amount.
-* `apply_only_on_full_priced_items`: When enabled, skips line items that are already on sale.
+## Choosing a calculator
 
-For each line item, the calculator computes `line item amount` x `percent` / `100`, capped at the line item's amount so a promotion adjustment never pushes the total negative.
+Each calculator takes a few settings — the amount, the percentage, the threshold. A merchant picks one and fills in the settings when setting up a delivery method or a promotion.
 
-For example, a `$30` line item at `10%` yields a `$3` discount (`$30 x 10% = $3`).
+### For delivery charges
 
-### Price Sack
+| Calculator | What it charges | Settings |
+|---|---|---|
+| **Flat rate** | The same amount every time | `amount`, `currency` |
+| **Per item** | An amount for each item in the parcel | `amount`, `currency` |
+| **Percent of item total** | A percentage of what's in the parcel | `flat_percent` |
+| **Price sack** | One amount above a threshold, another below — the usual "free delivery over $50" | `minimal_amount`, `discount_amount`, `normal_amount` |
+| **Flexi rate** | A charge for the first item, less for each one after | `first_item`, `additional_item`, `max_items` |
+| **Digital delivery** | Nothing, for downloads | — |
 
-The Price Sack calculator is useful for when you want to provide a discount for an order which is over a certain price. The calculator has four preferences:
+### For promotion discounts
 
-* `minimal_amount`: The minimum amount for the line items total to trigger the calculator.
-* `discount_amount`: The amount to discount from the order if the line items total is equal to or greater than the `minimal_amount`.
-* `normal_amount`: The amount to discount from the order if the line items total is less than the `minimal_amount`.
-* `currency`: The currency for this calculator. Defaults to the store currency
+| Calculator | What it takes off | Settings |
+|---|---|---|
+| **Flat rate** | A fixed amount | `amount`, `currency` |
+| **Percent of item total** | A percentage of the order | `flat_percent` |
+| **Percent on line item** | A percentage of one item | `percent` |
+| **Flexi rate** | A sliding amount by quantity | `first_item`, `additional_item`, `max_items` |
+| **Tiered percent** | A percentage that grows with order value | tiers |
+| **Tiered flat rate** | A fixed amount that grows with order value | tiers |
 
-Suppose you have a Price Sack calculator with a `minimal_amount` preference of `$50`, a `normal_amount` preference of `$2`, and a `discount_amount` of `$5`. An order with a line items total of `$60` would result in a discount of `$5` for the whole order. An order of `$20` would result in a discount of `$2`.
+## Worked examples
 
-## Creating a New Calculator
+<details>
+<summary>Free delivery over $50, otherwise $7</summary>
 
-To create a new calculator for Spree, you need to do two things. The first is to inherit from the `Spree::Calculator` class and define `description` and `compute` methods on that class:
+**Price sack**, with `minimal_amount: 50`, `discount_amount: 0`, `normal_amount: 7`.
 
-```ruby
-class CustomCalculator < Spree::Calculator
-  def self.description
-    # Human readable description of the calculator
-  end
+    A $60 basket pays nothing. A $20 basket pays $7.
 
-  def compute(object=nil)
-    # Returns the value after performing the required calculation
-  end
-end
-```
+</details>
 
-If you are creating a new calculator for shipping methods, please be aware that you need to inherit from `Spree::ShippingCalculator` instead, and define a `compute_package` method:
+  <details>
+<summary>$3 to ship the first item, $1 for each extra</summary>
 
-```ruby
-class CustomCalculator < Spree::ShippingCalculator
-  def self.description
-    # Human readable description of the calculator
-  end
+**Flexi rate**, with `first_item: 3`, `additional_item: 1`.
 
-  def compute_package(package)
-    # Returns the value after performing the required calculation
-  end
-end
-```
+    Four items cost `$3 + (3 × $1)` = **$6**. Set `max_items` to stop charging beyond a point.
 
-The second thing is to register this calculator as a tax, shipping, or promotion adjustment calculator by calling code like this at the end of `config/initializers/spree.rb` inside your application `config` variable defined for brevity:
+</details>
 
-**Spree 5.2+:**
+  <details>
+<summary>10% off the order</summary>
 
-```ruby config/initializers/spree.rb
-    Rails.application.config.after_initialize do
-      Spree.calculators.tax_rates << CustomCalculator
-      Spree.calculators.shipping_methods << CustomCalculator
-      Spree.calculators.promotion_actions_create_adjustments << CustomCalculator
-    end
-    ```
+**Percent of item total**, with `flat_percent: 10`.
 
-  **Spree 5.1 and below:**
+    A $31 order gets **$3.10** off.
 
-```ruby config/initializers/spree.rb
-    Rails.application.config.spree.calculators.tax_rates << CustomCalculator
-    Rails.application.config.spree.calculators.shipping_methods << CustomCalculator
-    Rails.application.config.spree.calculators.promotion_actions_create_adjustments << CustomCalculator
-    ```
+</details>
 
+  <details>
+<summary>Spend more, save more</summary>
 
-For example if your calculator is placed in `app/models/spree/calculator/shipping/my_own_calculator.rb` you should call:
+**Tiered percent** — 5% over $100, 10% over $250, 15% over $500.
 
-**Spree 5.2+:**
+    The order total picks the tier. One promotion covers the whole ladder instead of three competing ones.
 
-```ruby config/initializers/spree.rb
-    Rails.application.config.after_initialize do
-      Spree.calculators.shipping_methods << Spree::Calculator::Shipping::MyOwnCalculator
-    end
-    ```
+</details>
 
-  **Spree 5.1 and below:**
 
-```ruby config/initializers/spree.rb
-    Rails.application.config.spree.calculators.shipping_methods << Spree::Calculator::Shipping::MyOwnCalculator
-    ```
+## Setting one up
 
+Calculators are configured as part of the thing that uses them. The available calculators for each are discoverable, so a dashboard or a script can present the real list rather than a hardcoded one:
 
-### Determining Availability
 
-By default, all shipping method calculators are available at all times. If you wish to make this dependent on something from the order, you can re-define the `available?` method inside your calculator:
+```typescript Admin SDK
+// What can price a delivery method?
+const calculators = await adminClient.deliveryMethods.calculators()
 
-```ruby app/models/custom_calculator.rb
-class CustomCalculator < Spree::Calculator
-  def available?(object)
-    object.currency == "USD"
-  end
-end
+// Set up a delivery method with a flat rate
+await adminClient.deliveryMethods.create({
+  name: 'Standard shipping',
+  delivery_zone_id: 'dz_xxx',
+  calculator_type: 'Spree::Calculator::Shipping::FlatRate',
+  calculator_attributes: {
+    preferences: { amount: '7.00', currency: 'USD' },
+  },
+})
 ```
 
-## Calculated Adjustments
-
-If you wish to use Spree's calculator functionality for your own application, you can include the `Spree::CalculatedAdjustments` module into a model of your choosing.
-
-```ruby app/models/plan.rb
-class Plan < ActiveRecord::Base
-  include Spree::CalculatedAdjustments
-end
+```bash CLI
+spree api get /delivery_methods/calculators
 ```
 
-To have calculators available for this class, you will need to register them. `Spree.calculators` is a fixed-member struct (`SpreeCalculators`, defined in `spree/core/lib/spree/core/engine.rb`) that exposes only the four built-in buckets:
-
-* `shipping_methods`
-* `tax_rates`
-* `promotion_actions_create_adjustments`
-* `promotion_actions_create_item_adjustments`
-
-`Plan.calculators` internally calls `Spree.calculators.send(:plans)` (the tableized model name), so both registration and lookup raise `NoMethodError` until you extend the struct to add a matching `plans` member. Ruby structs cannot gain members at runtime, so this means redefining the `SpreeCalculators` struct (or reassigning `Spree.calculators` to an object that responds to `plans`) before you register anything onto it.
-
-Once the struct exposes a `plans` member you can register calculators:
 
-**Spree 5.2+:**
+Each calculator declares which settings it takes, so a form can be built for it without knowing the calculator in advance — which is how the dashboard renders these.
 
-```ruby config/initializers/spree.rb
-    Rails.application.config.after_initialize do
-      Spree.calculators.plans << CustomCalculator
-    end
-    ```
+> **WARNING:** A calculator with an `amount` also has a **currency**. If it doesn't match the order's currency, the calculator contributes nothing rather than converting. Set up one calculator per currency you sell in, or a promotion will silently do nothing for some customers.
 
-  **Spree 5.1 and below:**
+## Writing your own
 
-```ruby config/initializers/spree.rb
-    Rails.application.config.spree.calculators.plans << CustomCalculator
-    ```
+When none of the built-in calculators expresses your pricing — dimensional weight, a contract rate card, a rule your finance team invented — you can add one. A calculator is a small class with a name and a method that returns an amount, registered so it appears alongside the built-in options.
 
+For delivery specifically, consider whether you want a calculator or a **delivery rate provider**. A calculator computes a number from what's in the parcel. A provider asks a carrier for real, live rates. If you want what UPS would actually charge today, that's a provider.
 
-Then you can access these calculators by calling this method:
-
-```ruby
-Plan.calculators
-```
-
-Using this method, you can then display the calculators as you please. Each object for this new class will need to have a calculator associated so that adjustments can be calculated on them.
-
-`Spree::CalculatedAdjustments` provides a `has_one :calculator` association (with `accepts_nested_attributes_for` and a presence validation), delegates `compute` to that calculator, exposes a `with_calculator` scope, `calculator_type` / `calculator_type=` accessors, and the `Plan.calculators` registry shown above. To work out what the calculator would compute an amount to be, call `compute` on an instance:
-
-```ruby
-plan.compute(<calculable object>)
-```
-
-The module does not define `create_adjustment`, `update_adjustment`, or `compute_amount`. If you also need to build adjustments, include `Spree::AdjustmentSource`, which adds `create_adjustment(order, adjustable, included = false)`. That method calls a `compute_amount` you define on the including model (as `Spree::TaxRate` and the `Spree::Promotion::Actions` classes do). There is no `update_adjustment` method in core.
+See [Custom promotions](../how-to/custom-promotion.md) and [Providers](../providers/overview.md).
 
-## Related Documentation
+## Related
 
-- [Adjustments](taxes-discounts-fees.md) — the records calculators compute amounts for.
-- [Dependencies](../customization/dependencies.md) — swap out calculators via the Dependencies system.
+- [Fulfillments](fulfillments.md) — delivery methods and rates
+- [Promotions](promotions.md) — the rules that decide when a discount applies
+- [Discounts](discounts.md) — the rows a promotion produces
+- [Taxes](taxes.md) — worked out by providers, not calculators

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

@@ -136,7 +136,7 @@ This is what lets you design your own checkout. Spree tells you what's missing;
       shipping_address: {
         first_name: 'John', last_name: 'Doe',
         address1: '123 Main St', city: 'Los Angeles',
-        country_code: 'US', state_abbr: 'CA', postal_code: '90001',
+        country_code: 'US', state_code: 'CA', postal_code: '90001',
       },
     })
     ```

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

@@ -3,9 +3,6 @@ title: Channels
 description: Per-store distribution surfaces — online storefront, POS, marketplace, wholesale — each with its own product catalog and order attribution.
 ---
 
-import { Since } from '/snippets/since.mdx';
-
-
 ## Overview
 
 Channels segment a single [Store](stores.md) into distinct selling surfaces. A channel represents *where* an order originates from — the online storefront, an in-person point-of-sale till, a marketplace integration (Amazon, eBay), a B2B wholesale portal, a mobile app — and *which* subset of the store's products is available there.
@@ -93,7 +90,6 @@ This attribution drives reporting (best-selling by channel, revenue per channel)
 
 ### Storefront Access Gating
 
-
 A channel's `storefront_access` decides what an **anonymous** visitor — a request with no authenticated customer — may see. Logged-in customers are never gated. The posture is one of three values:
 
 | Mode | Guest sees catalog | Guest sees prices | Use case |

package/dist/developer/core-concepts/companies-and-catalogs.md

@@ -54,7 +54,7 @@ Memberships stay always-active and always customer-backed: the pending state liv
 
 Carts and orders carry a `company_id` pointing at any node — buying *for* a division means pointing at it. A buyer with exactly one membership resolves to it automatically; a buyer with several names the node on their cart (the `company_id` param on cart update, validated against their standing). The node is frozen onto the order at completion, like every other order attribute, so a placed order's tax treatment stays explainable no matter how the tree changes later.
 
-Exemption certificates and the company's tax registration always resolve through `company.legal_entity` — see [Taxes, Discounts & Fees](/docs/developer/core-concepts/taxes-discounts-fees) for how they reach the tax provider.
+Exemption certificates and the company's tax registration always resolve through `company.legal_entity` — see [Taxes](taxes.md) for how they reach the tax provider.
 
 ## Catalogs
 

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

@@ -3,8 +3,6 @@ title: Customers
 description: How Spree models customer accounts — registration, authentication, addresses, order history, store credits, and guest checkout behavior.
 ---
 
-import { Since } from '/snippets/since.mdx';
-
 ## Overview
 
 Customers interact with your store through the Store API. They can register, log in, manage their profile, and view order history.
@@ -193,7 +191,6 @@ On success, the user is automatically logged in and a JWT token is returned. The
 
 ## Newsletter Subscriptions
 
-
 Headless storefronts often need to collect newsletter signups before account creation (footer forms, popup overlays). The Store API exposes a double opt-in subscription flow that mirrors the password reset webhook pattern.
 
 ### Step 1: Subscribe

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

@@ -0,0 +1,133 @@
+---
+title: Discounts
+description: The record of money taken off one order — where a discount comes from, and why it is spread across the items it applied to.
+---
+
+## Overview
+
+A discount is one line on one order saying money came off, and why.
+
+> **NOTE:** **A discount is not a promotion.** A [promotion](promotions.md) is a *rule* — "20% off shoes in July" — that exists on its own, before anybody buys anything. A discount is the *result* on a particular order.
+> 
+> Think of the promotion as the sign in the shop window and the discount as the line on the receipt. One promotion produces thousands of discounts over its life.
+
+That separation is what lets an order stay truthful. The promotion can be edited, paused or deleted next month; the discount row on last month's order still says exactly what that customer was given.
+
+It also means **not every discount has a promotion behind it.** When a support agent takes $10 off as a goodwill gesture, that's a discount with no campaign attached — which is what the `kind` field distinguishes.
+
+```mermaid
+erDiagram
+    Promotion ||--o{ Discount : "produces many, over time"
+    Order ||--o{ Discount : "has many"
+    LineItem ||--o{ Discount : "reduced by"
+    Fulfillment ||--o{ Discount : "reduced by"
+
+    Promotion {
+        string name
+        string code
+        datetime expires_at
+    }
+    Discount {
+        string label
+        string kind
+        string code
+        string value
+        string amount
+    }
+```
+
+| | [Promotion](promotions.md) | Discount |
+|---|---|---|
+| What it is | A campaign rule | A row on one order |
+| Exists | Before any order | Only once money comes off |
+| How many | One | One per order it applies to |
+| Can change later | Yes — edit or end it | No — it's a financial record |
+| Set up by | A merchant, in advance | Created automatically, or by staff |
+
+## Discount attributes
+
+| Attribute | Description |
+|---|---|
+| `label` | What the customer sees — `Summer Sale` |
+| `kind` | `promotion` or `manual` |
+| `code` | The coupon code used, if there was one |
+| `value` / `value_type` | The rule behind it — `"10"` and `percent` |
+| `amount` / `display_amount` | What actually came off, as a negative amount |
+| `promotion_id` | The promotion responsible, for promotion discounts |
+| `line_item_id` / `fulfillment_id` | What it reduced |
+
+Note the difference between `value` and `amount`. `value` is the rule — "10 percent". `amount` is the money — "-$12.00". You need the rule to explain the discount and the amount to add up the order.
+
+## Reading discounts on an order
+
+Whatever produced them, the rows read the same way:
+
+```typescript Store SDK
+const cart = await client.carts.get(cartId)
+
+cart.display_discount_total // "-$12.00"
+
+cart.discounts.forEach((discount) => {
+  discount.label          // "Summer Sale"
+  discount.kind           // "promotion" or "manual"
+  discount.code           // "SUMMER20", when a code was used
+  discount.display_amount // "-$12.00"
+})
+```
+
+Applying a coupon code, and what decides whether it's accepted, belongs to [Promotions](promotions.md).
+
+## Manual discounts
+
+Sometimes there's no promotion — a price match, an apology for a late delivery. Staff can add a discount directly:
+
+
+```typescript Admin SDK
+// 10% off one 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" }'
+```
+
+
+> **WARNING:** Only **manual** discounts can be edited or deleted. Changing one that came from a promotion returns a `422`.
+> 
+> That row belongs to the promotion that created it. If staff could edit it, an order would start disagreeing with the promotion it claims to have used — and the reporting behind "how did the summer sale do" stops adding up.
+
+## How a discount is spread
+
+An order-level discount isn't kept as one lump sum. It's divided across the items it applied to, in proportion to what they cost.
+
+This looks like an implementation detail until someone returns one item out of three. Then the question is: how much of that $30 discount belonged to the returned shirt? If the discount were one lump, you'd have to guess. Because it was spread at the time, the answer is already recorded, and the refund is right without anyone doing arithmetic on the phone.
+
+The same reasoning applies to tax — the tax on a partially returned order follows the same split.
+
+## Discounts on placed orders
+
+Once an order exists, its discounts stop being regenerated. Editing a placed order re-applies the rows it already has rather than re-running today's promotions.
+
+The alternative would mean an order quietly changing because a sale ended overnight — which is indefensible to a customer holding a confirmation email.
+
+## Related
+
+- [Promotions](promotions.md) — the rules that create most discounts
+- [Order totals](order-totals.md) — how discounts roll into the total
+- [Gift cards & store credit](store-credits-gift-cards.md) — payment, not discount
+- [Returns](returns-exchanges-claims.md) — how a discount is unwound on a return