Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Fix: stop scoping currency-free reporting metrics to one currency (#14623)
Damian Legawiecc979801448ff
diff --git a/docs/developer/core-concepts/reporting.mdx b/docs/developer/core-concepts/reporting.mdxindex d53ac86df4..9e140a59fa 100644--- a/docs/developer/core-concepts/reporting.mdx+++ b/docs/developer/core-concepts/reporting.mdx@@ -35,6 +35,7 @@ A query names what to measure and how to slice it. This is the whole surface:"filters": [{ "dimension": "channel", "op": "eq", "value": "ch_86Rf07xd4z" }],"time_range": { "preset": "last_4_weeks" },"compare": "previous_period",+ "currency": "EUR","sort": "-total_sales","limit": 50}@@ -47,6 +48,7 @@ A query names what to measure and how to slice it. This is the whole surface:| `filters` | `eq` or `in` against a dimension. Values are prefixed IDs where the dimension identifies a record. || `time_range` | A named preset, or `since`/`until` as ISO 8601. A bare date covers the store's whole day. || `compare` | `previous_period` adds `previous` and `growth` to every metric. |+| `currency` | ISO 4217 code, e.g. `"EUR"`. Defaults to the store's own. Applies only to a query containing money — see [Metrics](#metrics). The values a store accepts are in the schema's `supported_currencies`. || `sort` / `limit` | Ranking controls; ignored for time series, which are always chronological and complete. |Unknown members are rejected, never dropped. A malformed query answers 422,@@ -90,12 +92,20 @@ Spree.reporting.metric :total_sales,a `:percent` metric arrives as the number a merchant reads (`42.5`), not thefraction.- Amounts are **never converted**. A query answers in one currency — the one- it names, or the store's default — and every base a money metric reads must- filter by it, or two currencies end up added together under one symbol. A- store selling in several therefore has as many answers as it has- currencies, which is why the home screen offers a currency alongside its+ Amounts are **never converted**. A query containing money answers in one+ currency — the one it names, or the store's default — and every base a money+ metric reads filters by it, or two currencies end up added together under one+ symbol. A store selling in several therefore has as many money answers as it+ has currencies, which is why the home screen offers a currency alongside itschannel and date range.++ **A query with no money in it is not scoped to a currency at all.** Counts+ and quantities — orders, customers, units sold, payments taken — are not+ amounts, so narrowing them would answer "how many orders did we take" with+ only the share that happened to be priced in one currency. Ask for `orders`+ alone and you get every order; ask for `orders` beside `total_sales` and the+ whole query narrows, because the money figure has to. A ratio counts as+ money when either side is: average order value does, sell-through does not.- `ratio: [:numerator, :denominator]` defines a **derived** metric, computedafter aggregation so it is correct for both rows and totals. Average ordervalue is `ratio: %i[total_sales orders]`, never `AVG()`.diff --git a/docs/developer/how-to/extend-reporting.mdx b/docs/developer/how-to/extend-reporting.mdxindex afbbec6df4..dda444a18b 100644--- a/docs/developer/how-to/extend-reporting.mdx+++ b/docs/developer/how-to/extend-reporting.mdx@@ -198,6 +198,18 @@ These are limits of the compiler, not of registration:Registering a base is otherwise ordinary: declare its family, its table, astore-scoped relation, its time column and which bases its dimensions reach.+The relation's `currency` argument **is nil when the query contains no money+metric**, and a base must then not filter by it — a count restricted to one+currency is a wrong answer, not a narrower one. Guard the filter rather than+passing nil into `where`, which would match nothing:++```ruby+relation: lambda { |store, range, currency|+ scope = store.subscriptions.where(created_at: range)+ currency ? scope.where(currency: currency) : scope+}+```+```rubySpree.reporting.base :subscriptions, family: :subscriptions,table: '%{subscriptions}',diff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex 92752a4579..b5aa1f406d 100644--- a/docs/plans/decisions.md+++ b/docs/plans/decisions.md@@ -1,3 +1,11 @@+## 2026-09-12: Reporting scopes money to one currency and never converts; counts are not scoped at all++**Context:** Every sales and payments base filtered `currency` unconditionally, so a multi-currency store could not ask how many orders it took — only how many were priced in one currency. That is a wrong answer rather than a partial one. The wider question of cross-currency totals came up at the same time, so both were settled together after looking at how other platforms handle it.++**Decision:** Money stays per-currency and is never converted. `Query#scope_currency` returns the currency only when some aggregated component of the requested metrics is money-formatted, and the bases skip the filter when it is nil — so counts, quantities and money-free ratios span every currency, while any query containing money narrows as before. A ratio counts as money when either side is (average order value), and not when neither is (sell-through). The dashboard home screen carries a currency switcher, shown only where the store sells in more than one.++**Consequences:** No base-currency column on orders and no conversion anywhere in reporting. The market splits on this: Magento and Shopify store a second, converted amount per order and report on it, while Saleor's Pulse analytics, Medusa and Vendure keep money scoped per currency. The converted approach buys one aggregate number and pays for it in reconciliation — Shopify converts at each money movement rather than freezing the sale's rate, so a full refund need not net to zero in shop currency and their own documentation calls the reporting conversion "approximate and may differ slightly from actual captured amounts"; Magento's own Advanced Reporting only supports installations that kept a single base currency throughout. For a platform whose figures merchants may file, exactness beats a single headline number. If a cross-currency total is ever wanted it must be a separate, clearly labelled figure carrying its rate and date — never the same metric as the exact one. A base that registers its own relation must guard the currency filter against nil.+## 2026-09-11: Home-screen counters send a key and a number, never copy**Context:** The counters endpoint shipped with `label` and `description` resolved server-side through `Spree.t`, mirroring how the reporting schema labels metrics and dimensions. That reproduces exactly the defect the 2026-09-05 ruling was written to fix: `Spree.t` answers in the request locale, which the dashboard never sets, so a merchant reading the interface in one language could get a counter labelled in another. The low stock description also interpolated a store preference, putting a merchant setting into a translated sentence built on the server.diff --git a/spree/core/lib/spree/reporting/adapters/live.rb b/spree/core/lib/spree/reporting/adapters/live.rbindex 391881d66e..449a66885b 100644--- a/spree/core/lib/spree/reporting/adapters/live.rb+++ b/spree/core/lib/spree/reporting/adapters/live.rb@@ -92,7 +92,7 @@ module Spree# merge overwrites same-column wheres), and exclude canceled orders# explicitly: sales figures count what stayed sold.def base_relation(base, range)- scope = query.registry.base!(base).relation.call(query.store, range, query.currency)+ scope = query.registry.base!(base).relation.call(query.store, range, query.scope_currency)# Association default orderings break grouped selects on PostgreSQL.scope.reorder(nil)diff --git a/spree/core/lib/spree/reporting/default_vocabulary.rb b/spree/core/lib/spree/reporting/default_vocabulary.rbindex b93ff78833..63da98e408 100644--- a/spree/core/lib/spree/reporting/default_vocabulary.rb+++ b/spree/core/lib/spree/reporting/default_vocabulary.rb@@ -120,17 +120,22 @@ module Spree# when it was taken, and inventory on when stock moved. Mixing them# in one row would put three different clocks in one table.+ # `currency` is nil when the question does not involve money — see+ # Query#scope_currency. Counting orders in one currency and calling+ # it "orders" would understate a multi-currency store's trade.base :orders, family: :sales, table: '%{orders}',time_column: '%{orders}.completed_at',relation: lambda { |store, range, currency|- store.orders.not_canceled.where(currency: currency, completed_at: range)+ scope = store.orders.not_canceled.where(completed_at: range)+ currency ? scope.where(currency: currency) : scope}base :line_items, family: :sales, table: '%{line_items}', reaches: %i[line_items orders],time_column: '%{orders}.completed_at',relation: lambda { |store, range, currency|- store.line_items.merge(Spree::Order.not_canceled).- where(Spree::Order.table_name => { currency: currency, completed_at: range })+ scope = store.line_items.merge(Spree::Order.not_canceled).+ where(Spree::Order.table_name => { completed_at: range })+ currency ? scope.where(Spree::Order.table_name => { currency: currency }) : scope}# A payment carries no completion timestamp, so it is anchored on@@ -146,8 +151,8 @@ module Spreebase :payments, family: :payments, table: '%{payments}',time_column: '%{payments}.created_at',relation: lambda { |store, range, currency|- store.payments.where(Spree::Order.table_name => { currency: currency }).- where(Spree::Payment.table_name => { created_at: range })+ scope = store.payments.where(Spree::Payment.table_name => { created_at: range })+ currency ? scope.where(Spree::Order.table_name => { currency: currency }) : scope}# The movement table carries no store of its own; tenancy is the walkdiff --git a/spree/core/lib/spree/reporting/query.rb b/spree/core/lib/spree/reporting/query.rbindex 06a362c11f..fb31fe752d 100644--- a/spree/core/lib/spree/reporting/query.rb+++ b/spree/core/lib/spree/reporting/query.rb@@ -126,6 +126,20 @@ module Spreemetrics.flat_map { |metric| registry.components(metric) }.uniq(&:name)end+ # The currency a base should filter by, or nil when the question does not+ # involve money.+ #+ # Amounts in different currencies are never converted or added, so a+ # money metric has to be scoped to one. A count or a quantity is not+ # money and carries no such constraint — restricting it anyway would+ # answer "how many orders did we take" with only the share that happened+ # to be priced in one currency, which is wrong rather than partial. A+ # ratio counts as money when either side is (average order value), and+ # not when neither is (sell-through).+ def scope_currency+ currency if aggregated_metrics.any?(&:money?)+ end+privatedef normalize_metrics(names)diff --git a/spree/core/spec/lib/spree/reporting/query_spec.rb b/spree/core/spec/lib/spree/reporting/query_spec.rbindex 39ea89185f..e63dbc100a 100644--- a/spree/core/spec/lib/spree/reporting/query_spec.rb+++ b/spree/core/spec/lib/spree/reporting/query_spec.rb@@ -7,6 +7,10 @@ RSpec.describe Spree::Reporting::Query dodescribed_class.new(store: store, params: params).executeend+ def query_for(metrics)+ described_class.new(store: store, params: { metrics: metrics })+ end+describe 'validation' doit 'rejects unknown metrics naming the valid ones' doexpect { run(metrics: %w[nope]) }.to raise_error(Spree::Reporting::UnknownMember, /net_sales/)@@ -260,6 +264,38 @@ RSpec.describe Spree::Reporting::Query doendend+ # Money in different currencies is never converted or added, so a money+ # metric answers in one currency. A count is not money — scoping it would+ # answer "how many orders did we take" with only part of the trade.+ describe 'currency scope' do+ let!(:usd_order) { create(:completed_order_with_totals, store: store, completed_at: 2.days.ago) }+ let!(:eur_order) do+ create(:completed_order_with_totals, store: store, currency: 'EUR', completed_at: 2.days.ago)+ end++ it 'counts every currency when nothing in the question is money' do+ result = run(metrics: %w[orders])+ expect(result.totals[:orders][:value]).to eq(2)+ end++ it 'still answers money in one currency' do+ result = run(metrics: %w[total_sales])+ expect(result.totals[:total_sales][:value]).to eq(usd_order.total)+ end++ # The pair in one query: the money figure narrows, the count does not, so+ # asking for both must not silently narrow the count too.+ it 'narrows the whole query once any part of it is money' do+ result = run(metrics: %w[orders total_sales])+ expect(result.totals[:orders][:value]).to eq(1)+ end++ it 'treats a ratio as money when either side is' do+ expect(query_for(%w[average_order_value]).scope_currency).to eq(store.default_currency)+ expect(query_for(%w[orders customers]).scope_currency).to be_nil+ end+ end+describe 'time range bounds' doit 'refuses a range too wide to chart, however it was asked for' doexpect do