@spree/docs 0.1.177 → 0.1.178

package/dist/developer/how-to/custom-delivery-rate-provider.md

@@ -0,0 +1,242 @@
+---
+title: Build a Custom Delivery Rate Provider
+description: Connect a carrier or rate aggregator to Spree so checkout quotes live delivery rates instead of calculator-based prices.
+---
+
+## Overview
+
+A delivery rate provider decides **where a delivery method's price comes from**. Spree ships with one built-in provider, `Spree::DeliveryRateProvider::Internal`, which prices through the method's calculator — flat rates, per-item rates, and the rest. That is the default, and stores that never install a carrier integration keep using it.
+
+A custom provider replaces that arithmetic with a live quote: you call a carrier or an aggregator, and the rate that reaches checkout carries the carrier name, the service level, and an estimated delivery date.
+
+Use a provider when the price comes from outside Spree. If you only need different arithmetic on values Spree already has, write a calculator instead — it is far less work. See [Fulfillments](../core-concepts/fulfillments.md) for how delivery methods, rates and fulfillments fit together.
+
+## What you will build
+
+Three pieces, each with one job:
+
+| Piece | Responsibility |
+|---|---|
+| `Spree::Integration` subclass | Holds the store's credentials, managed from the admin dashboard |
+| `Spree::DeliveryRateProvider::Base` subclass | Turns a package into a rate quote |
+| An initializer | Registers both so admins can select them |
+
+Providers are stateless strategy objects. They never store credentials themselves — that is the integration's job, which is what gives merchants one place to see everything connected to their store.
+
+## 1. Store credentials in an integration
+
+```ruby
+module SpreeAcmeCarrier
+  class Integration < Spree::Integration
+    preference :api_key, :password
+    preference :account_number, :string
+    preference :test_mode, :boolean, default: true
+
+    def self.integration_group = 'shipping'
+
+    # Called when an admin activates the integration. Returning false blocks
+    # activation and shows your message in the dashboard.
+    def can_connect?
+      client.ping
+      true
+    rescue StandardError => e
+      self.connection_error_message = e.message
+      false
+    end
+
+    def client
+      @client ||= AcmeCarrier::Client.new(api_key: preferred_api_key, test: preferred_test_mode)
+    end
+  end
+end
+```
+
+Declare secrets as `:password` preferences. Spree masks them on read and guards the round-trip on write, so an API key never leaves the server in plain text.
+
+## 2. Implement the provider
+
+Implement `#estimates` — it receives a `Spree::Stock::Package` and returns an array of `Estimate` objects, one per carrier service you can quote. Every estimate becomes its own named option at checkout ("Acme Ground", "Acme Express"), and the merchant narrows, renames, or marks up individual services from the delivery method's carrier-services card. An empty array hides the method.
+
+(Single-quote providers can implement `#estimate` returning one `Estimate` or `nil` instead — the base class wraps it.)
+
+```ruby
+module SpreeAcmeCarrier
+  class DeliveryRateProvider < Spree::DeliveryRateProvider::Base
+    def self.integration_class = 'SpreeAcmeCarrier::Integration'
+
+    def estimates(package)
+      quotes_for(package).map do |quote|
+        Spree::DeliveryRateProvider::Estimate.new(
+          cost: quote.amount,
+          # ISO code of the currency the carrier quoted in. Estimates in a
+          # different currency than the cart's are dropped — never convert
+          # silently; nil means the store's own currency.
+          currency: quote.currency,
+          carrier: quote.carrier_name,
+          service_level: quote.service_name,
+          estimated_delivery_date: quote.delivery_date,
+          metadata: { quote_id: quote.id }
+        )
+      end
+    rescue AcmeCarrier::Error => e
+      # Never raise into checkout: report and hide this method instead.
+      Rails.error.report(e, context: { delivery_method_id: delivery_method.id }, source: 'acme.rating')
+      []
+    end
+
+    private
+
+    # One API call serves every delivery method sharing this provider within
+    # a request — carriers return all services in one response, so quoting
+    # five methods should not mean five round-trips.
+    def quotes_for(package)
+      key = [:acme_quotes, store.id, package.stock_location.id, package.order.id]
+      Spree::Current.provider_cache[key] ||= integration.client.rates(
+        from: package.stock_location,
+        to: package.order.ship_address,
+        parcel: { weight: package.weight }
+      )
+    end
+  end
+end
+```
+
+**Never let `estimates` raise.** It runs inside checkout's rate refresh, so an exception breaks the whole delivery step for the customer. Rescue your carrier's errors, report them (`Rails.error.report`), and return `[]` — the method disappears from the options while everything else keeps working.
+
+Optionally implement `def self.service_catalog(integration)` so the admin service picker can list the carrier's services as checkboxes. Fetch them live — a hardcoded list offers services the merchant has not enabled and hides the ones they have. Return one of three shapes, and never raise:
+
+```ruby
+def self.service_catalog(integration)
+  return Spree::DeliveryRateProvider::ServiceCatalog.none if integration.nil?
+
+  services = integration.client.services.map do |service|
+    { carrier: service.carrier, service: service.code, label: service.name }
+  end
+  Spree::DeliveryRateProvider::ServiceCatalog.listing(services)
+rescue AcmeCarrier::Error => e
+  # The merchant sees the carrier's own words — "no services" and "we
+  # could not ask" are different problems.
+  Spree::DeliveryRateProvider::ServiceCatalog.unavailable(e.message)
+end
+```
+
+`ServiceCatalog.none` is the default: the provider lists nothing and the merchant types identifiers free-form, which also stays available when a listing fails. Carrier and service values must match what your rates carry — the picker's rows are matched against quoted rates by exactly those two fields.
+
+**Returning `nil` hides the delivery method** for that package. This is the same contract calculators follow, and it is how you express "this carrier does not serve this destination" — the method simply does not appear at checkout rather than appearing at a wrong price.
+
+`cost` is pre-tax and pre-VAT. Spree applies the gross-up and resolves the tax rate afterwards, exactly as it does for calculator output, so you never handle tax yourself.
+
+Declaring `integration_class` is all the availability wiring you need: Spree derives `available_for_store?` from it, so your provider is hidden from the admin picker — and rejected on save — until the merchant connects the integration.
+
+### Optional lifecycle hooks
+
+`book` and `release` are part of the provider contract but Spree does not invoke them yet — they are reserved for the rate booking flow. Until then, call `book` yourself from your gem's fulfillment provider when the label is purchased:
+
+```ruby
+# Reserve the quote once your fulfillment provider dispatches.
+def book(delivery_rate)
+  integration.client.book(delivery_rate.metadata['quote_id'])
+end
+
+# Release a quote that is no longer wanted.
+def release(delivery_rate)
+  integration.client.release(delivery_rate.metadata['quote_id'])
+end
+```
+
+## 3. Register both classes
+
+```ruby
+# config/initializers/spree.rb
+Spree.delivery_rate_providers << 'SpreeAcmeCarrier::DeliveryRateProvider'.constantize
+Spree.integrations << 'SpreeAcmeCarrier::Integration'
+```
+
+Registration is what makes a provider selectable: Spree validates `rate_provider` against this list, so a typo fails when the method is saved rather than deep inside checkout.
+
+## 4. Use it
+
+A merchant connects the integration under **Settings → Integrations**, then picks the provider on a delivery method under **Settings → Delivery methods**. The provider field only appears once more than one provider is available, so stores without a carrier integration never see it.
+
+One delivery method is the carrier connection: every service your provider returns becomes its own option at checkout, so a single "Acme shipping" method is usually all a merchant creates. The method's carrier-services card narrows which services are offered, renames them ("Acme 1 day"), and adds per-service or method-wide markup.
+
+Providers and calculators coexist freely. A store can price "Free shipping" with a flat-rate calculator, "Express" through your carrier, and "Local pickup" with neither.
+
+## Feeding carrier tracking back in
+
+Once a parcel is moving, most carriers will tell you where it is. Spree keeps
+that on a separate field from the fulfillment's own status, so a bounced parcel
+never un-ships itself — see [Fulfillments](../core-concepts/fulfillments.md#statuses).
+
+Spree owns the endpoint: every integration gets one at
+`POST /api/v3/webhooks/fulfillments/:integration_id` — the merchant pastes
+that URL into the carrier's webhook settings. Your job is one method on the
+integration:
+
+```ruby
+class SpreeAcmeCarrier::Integration < Spree::Integration
+  preference :api_key, :password
+  preference :webhook_secret, :password
+
+  # Verify the signature against your secret, translate the payload, return
+  # UpdateTracking arguments plus the tracking code to match on — or nil for
+  # events you don't act on.
+  def parse_webhook_event(raw_post, headers)
+    raise Spree::Integration::WebhookSignatureError if preferred_webhook_secret.blank?
+
+    payload = AcmeCarrier.verify!(raw_post, headers, preferred_webhook_secret) # raises on a bad signature
+
+    return unless payload['type'] == 'shipment.status_changed'
+
+    {
+      tracking_code: payload['tracking_code'],
+      tracking_status: STATUS_MAP.fetch(payload['status'], 'unknown'),  # Spree::Fulfillment::TRACKING_STATUSES
+      estimated_delivery_at: payload['eta'],
+      delivered_at: payload['delivered_scan_at'],
+      details: payload.slice('status_detail', 'carrier')
+    }
+  rescue AcmeCarrier::SignatureError => e
+    raise Spree::Integration::WebhookSignatureError, e.message
+  end
+end
+```
+
+The endpoint does the rest: signature failures answer `401` so a misconfigured
+sender notices, unmatched tracking codes and `nil` events are acknowledged with
+`200` so the carrier never retries a payload that cannot succeed, and matched
+events run through `Fulfillments::UpdateTracking` — reporting `delivered` also
+confirms receipt on the fulfillment, and an update carrying only a scan leaves
+an earlier estimate alone.
+
+Three rules worth keeping:
+
+- **Verify or refuse.** Raise `WebhookSignatureError` when no secret is
+  configured rather than accepting unsigned reports — a forged `delivered`
+  starts the customer's return window and, in the EU, the withdrawal clock.
+- **Pass `delivered_at` from the carrier's delivering scan**, not the webhook's
+  arrival time. The webhook usually lands well after the parcel does.
+- **Translate in your gem, never in core.** Map unrecognised carrier statuses
+  to `unknown` so the report stays visible instead of being dropped.
+
+## Testing
+
+Your provider is a plain object, so test it directly:
+
+```ruby
+RSpec.describe SpreeAcmeCarrier::DeliveryRateProvider do
+  let(:delivery_method) { create(:delivery_method, rate_provider: described_class.to_s) }
+
+  it 'quotes every service the carrier returns' do
+    estimates = described_class.new(delivery_method).estimates(package)
+
+    expect(estimates.map(&:service_level)).to contain_exactly('Ground', 'Express')
+    expect(estimates.first.carrier).to eq('Acme')
+  end
+
+  it 'hides the method when the carrier does not serve the destination' do
+    expect(described_class.new(delivery_method).estimates(unservable_package)).to eq([])
+  end
+end
+```
+
+Stub the carrier client rather than calling the real API — quoting runs on every checkout, so a slow or flaky test here is a slow or flaky suite everywhere.

package/dist/developer/how-to/custom-document-numbers.md

@@ -0,0 +1,154 @@
+---
+title: Customize Document Numbers
+description: Change the shape of order, return and other document numbers — from the dashboard for order numbers, or in code for full control.
+---
+
+## Overview
+
+Every order, return, exchange, claim, stock transfer, import and export carries a **document number** — the short, human-readable reference a merchant reads out on a support call and a customer quotes in an email. Orders look like `R1001`, returns like `RET1001`.
+
+Numbers are separate from IDs. Every record also has a prefixed ID (`order_86Rf07xd4z`) which is what the API uses and what you should reference in code. The number exists purely so people can read, say and type it.
+
+There are two ways to change it. Merchants can reshape **order numbers** from the dashboard without any code. Developers can replace the generator for **any** document type when the settings are not enough.
+
+## Merchant settings
+
+**Settings → Store → Order numbers** controls four things:
+
+| Setting | Effect |
+|---|---|
+| Numbering format | Sequential (default) or random. Applies to every numbered document. |
+| Prefix | Leads each order number. Defaults to `R`. |
+| Suffix | Ends each order number. Empty by default. |
+| Start numbering at | The first order number. Defaults to `1001`. |
+
+Sequential numbering counts up: `R1001`, `R1002`, `R1003`. Random numbering produces nine unpredictable digits, which is what Spree did before 6.0. The trade-off is worth stating to merchants: sequential numbers are far easier to read back over the phone, but a customer who orders twice can see how many orders you took in between. Random numbers give that away nothing, at the cost of legibility.
+
+Two rules apply to every change:
+
+- **Changes affect future numbers only.** Numbers already issued are permanent — they are printed on invoices, quoted in emails, and stored at payment gateways.
+- **The starting value only applies before the first order.** Set it to `10001` on a new store and the first order is `R10001`, the second `R10002`. Once the counter has issued a number the field is locked in the dashboard, because raising it then would do nothing — the counter keeps going from where it is.
+
+Prefix and suffix have no such restriction. Change them whenever you like: `INV` with suffix `-EU` and a start of `5001` gives `INV5001-EU`, and existing orders keep the numbers they were issued.
+
+> **NOTE:** Sequential numbering is *mostly* gapless, not guaranteed gapless — an abandoned checkout or a rare collision consumes a value. Do not rely on it for legal invoice numbering, which in most jurisdictions requires a provably unbroken sequence.
+
+## Custom generators
+
+When the settings are not enough — you need the year in the number, a per-warehouse prefix, or a format your ERP already expects — register a generator class.
+
+A generator answers one question: what should this record's number be? Uniqueness is handled for you, so a generator only has to propose.
+
+```ruby
+# lib/my_app/branch_order_numbers.rb
+module MyApp
+  class BranchOrderNumbers < Spree::NumberGenerators::Base
+    # @param record [Spree::Order]
+    # @return [String]
+    def generate(record)
+      branch = record.number_store.code.upcase
+      year = Time.current.year
+
+      "#{branch}-#{year}-#{SecureRandom.random_number(10_000).to_s.rjust(4, '0')}"
+    end
+  end
+end
+```
+
+Register it in an initializer:
+
+```ruby
+# config/initializers/spree.rb
+Spree.number_generators[:order] = 'MyApp::BranchOrderNumbers'
+```
+
+That is the whole contract. Orders now get numbers like `NYC-2026-0042`; every other document type keeps following the store's settings.
+
+The resource key matches the model name, underscored: `:order`, `:return`, `:exchange`, `:claim`, `:stock_transfer`, `:import`, `:export`. Register the same class under several keys to share one format across document types.
+
+A registered generator wins over the store's format setting — that is the point of registering one. If you want merchants to keep some control, read their settings yourself through `prefix_for` and `suffix_for` (below).
+
+`Spree.number_generators.delete(:order)` removes the registration and hands numbering back to the store settings.
+
+### What a generator can read
+
+The record is passed to `generate`, so anything reachable from it is available:
+
+- `record.number_store` — the store whose settings apply, wherever it lives on the model
+- `record.class.number_prefix` — the model's built-in prefix (`R`, `RET`, …)
+- Any attribute of the record itself
+
+Inheriting from `Spree::NumberGenerators::Base` also gives you `prefix_for(record)` and `suffix_for(record)`, which return the merchant's configured values for orders and the code-level prefix for everything else. Use them when you want to extend the merchant's choice rather than override it.
+
+### Sequential counters
+
+If your generator needs its own counter, use the same one the built-in sequential generator uses rather than deriving a maximum from existing rows. This generator combines both — the merchant's prefix, a year, and a zero-padded counter:
+
+```ruby
+module MyApp
+  class YearScopedNumbers < Spree::NumberGenerators::Base
+    def generate(record)
+      sequence = Spree::NumberSequence.next_value(
+        store: record.number_store,
+        resource_type: 'order',
+        start_at: 1
+      )
+
+      "#{prefix_for(record)}-#{Time.current.year}-#{sequence.to_s.rjust(5, '0')}"
+    end
+  end
+end
+```
+
+With the default prefix that produces `R-2026-00001`; a merchant who changes their prefix to `ACME` gets `ACME-2026-00001` without you touching the class.
+
+Deriving the next value by parsing existing numbers looks simpler but breaks in three ways: legacy numbers from before your format existed do not parse, string columns sort `R999` above `R1000`, and two concurrent checkouts read the same maximum and produce the same number. The counter is locked for the increment, so it hands out distinct values under load.
+
+## Adding numbers to your own model
+
+Models you add can carry document numbers too:
+
+```ruby
+class MyApp::Consignment < Spree.base_class
+  has_spree_number prefix: 'CN'
+end
+```
+
+The record is numbered before validation on create, and the number follows the store's format setting like everything else. The model needs a `number` column with a unique index:
+
+```ruby
+add_column :my_app_consignments, :number, :string, null: false
+add_index :my_app_consignments, :number, unique: true
+```
+
+If the model does not respond to `store`, define `number_store` so the generator knows whose settings to read:
+
+```ruby
+def number_store
+  warehouse.store
+end
+```
+
+## Fulfillments and payments
+
+Fulfillments and payments do **not** have their own numbers. Theirs are derived from the order they belong to — `R1001-F1` for the first parcel, `R1001-P1` for the first payment — so they group visibly with their order and follow whatever format the merchant chose.
+
+This is not configurable and there is no generator to register. If you need a different shape, override `number` on the model.
+
+## Upgrading from Spree 5.x
+
+Two changes matter.
+
+**Numbers are sequential by default.** Stores upgrading from 5.x keep every existing number untouched, but new documents get sequential numbers starting at 1001. To keep the old behavior, set the store's numbering format to **Random** in Settings → Store → Order numbers.
+
+**`Spree::Core::NumberGenerator` is deprecated.** Models using it still work through Spree 6.0 and log a deprecation warning. Replace it with the concern:
+
+```ruby
+# before
+include Spree::Core::NumberGenerator.new(prefix: 'R', length: 9)
+
+# after
+has_spree_number prefix: 'R'
+```
+
+The `length:` and `letters:` options are gone — they described the random format, which is now the generator's business rather than the model's. If you were relying on a specific length, register a custom generator.

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

@@ -15,7 +15,7 @@ Order routing decides which [Stock Location](../core-concepts/inventory.md#stock
 
 This guide covers both. Most extensions are rules — they compose with the built-ins and don't require rewriting the pipeline.
 
-Before starting, make sure you understand [how order routing works in Spree](../core-concepts/shipments.md#order-routing).
+Before starting, make sure you understand [how order routing works in Spree](../core-concepts/fulfillments.md#order-routing).
 
 | If the answer is "yes" | Pick |
 |---|---|

package/dist/developer/how-to/custom-payment-method.md

@@ -368,7 +368,7 @@ For every gateway action (authorize, purchase, capture, void, credit), Spree pas
 ## Related Documentation
 
 - [Payments](../core-concepts/payments.md) - Payment architecture and core concepts
-- [Checkout Customization](../customization/checkout.md) - Customizing the checkout flow
+- [Checkout Customization](../core-concepts/carts.md) - Customizing the checkout flow
 - [Events](../core-concepts/events.md) - Subscribe to payment events
 - [Stripe Integration](../../integrations/payments/stripe.md) - Reference implementation using Stripe
 - [Adyen Integration](../../integrations/payments/adyen.md) - Reference implementation using Adyen