@spree/docs 0.1.228 → 0.1.230

package/dist/api-reference/store.yaml

@@ -879,8 +879,8 @@ paths:
               example:
                 data:
                 - id: prod_UkLWZg9DAJ
-                  name: Product 2116979
-                  slug: product-2116979
+                  name: Product 2506979
+                  slug: product-2506979
                   meta_title:
                   meta_description:
                   meta_keywords:
@@ -1054,8 +1054,8 @@ paths:
               example:
                 data:
                 - id: prod_UkLWZg9DAJ
-                  name: Product 2589085
-                  slug: product-2589085
+                  name: Product 2979085
+                  slug: product-2979085
                   meta_title:
                   meta_description:
                   meta_keywords:
@@ -1086,8 +1086,8 @@ paths:
                   original_price:
                   seller_id:
                 - id: prod_gbHJdmfrXB
-                  name: Product 2598209
-                  slug: product-2598209
+                  name: Product 2988209
+                  slug: product-2988209
                   meta_title:
                   meta_description:
                   meta_keywords:
@@ -1216,8 +1216,8 @@ paths:
             application/json:
               example:
                 id: prod_UkLWZg9DAJ
-                name: Product 2866885
-                slug: product-2866885
+                name: Product 3256885
+                slug: product-3256885
                 meta_title:
                 meta_description:
                 meta_keywords:
@@ -1576,8 +1576,8 @@ paths:
                     preorder_ships_at:
                     quantity: 1
                     currency: USD
-                    name: Product 185715
-                    slug: product-185715
+                    name: Product 224715
+                    slug: product-224715
                     options_text: ''
                     price: '10.0'
                     display_price: "$10.00"
@@ -1695,8 +1695,8 @@ paths:
                     preorder_ships_at:
                     quantity: 1
                     currency: USD
-                    name: Product 1862171
-                    slug: product-1862171
+                    name: Product 2252171
+                    slug: product-2252171
                     options_text: ''
                     price: '10.0'
                     display_price: "$10.00"
@@ -2004,7 +2004,7 @@ paths:
                 total_quantity: 0
                 warnings:
                 - code: line_item_removed
-                  message: Product 190307 was removed because it was sold out
+                  message: Product 229307 was removed because it was sold out
                   line_item_id: li_UkLWZg9DAJ
                   variant_id: variant_UkLWZg9DAJ
                 coupon_code:
@@ -2244,8 +2244,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 1913263
-                  slug: product-1913263
+                  name: Product 2303263
+                  slug: product-2303263
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -2530,8 +2530,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 1938992
-                  slug: product-1938992
+                  name: Product 2328992
+                  slug: product-2328992
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -2562,7 +2562,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 234 Lovely Street
+                  address1: 252 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -2584,7 +2584,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 233 Lovely Street
+                  address1: 251 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -2743,8 +2743,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 1964794
-                  slug: product-1964794
+                  name: Product 2354794
+                  slug: product-2354794
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -2878,7 +2878,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 240 Lovely Street
+                  address1: 258 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -2900,7 +2900,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 239 Lovely Street
+                  address1: 257 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -3083,8 +3083,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 2252614
-                  slug: product-2252614
+                  name: Product 2642614
+                  slug: product-2642614
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -3282,8 +3282,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 2263461
-                  slug: product-2263461
+                  name: Product 2653461
+                  slug: product-2653461
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -3469,8 +3469,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 2288182
-                  slug: product-2288182
+                  name: Product 2678182
+                  slug: product-2678182
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -3580,7 +3580,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 336 Lovely Street
+                  address1: 354 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -3766,8 +3766,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 2305702
-                  slug: product-2305702
+                  name: Product 2695702
+                  slug: product-2695702
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -4020,8 +4020,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 2349569
-                  slug: product-2349569
+                  name: Product 2739569
+                  slug: product-2739569
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -4174,10 +4174,10 @@ paths:
                 total_quantity: 2
                 warnings:
                 - code: delivery_unavailable
-                  message: Product 23763 cannot be delivered to the selected address
+                  message: Product 27663 cannot be delivered to the selected address
                   line_item_id: li_UkLWZg9DAJ
                 - code: delivery_unavailable
-                  message: Product 238298 cannot be delivered to the selected address
+                  message: Product 277298 cannot be delivered to the selected address
                   line_item_id: li_gbHJdmfrXB
                 coupon_code:
                 item_total: '29.99'
@@ -4235,8 +4235,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 23763
-                  slug: product-23763
+                  name: Product 27663
+                  slug: product-27663
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -4266,8 +4266,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 238298
-                  slug: product-238298
+                  name: Product 277298
+                  slug: product-277298
                   options_text: ''
                   price: '19.99'
                   display_price: "$19.99"
@@ -4496,8 +4496,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 2449165
-                  slug: product-2449165
+                  name: Product 2839165
+                  slug: product-2839165
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -5326,8 +5326,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 3069789
-                  slug: product-3069789
+                  name: Product 3459789
+                  slug: product-3459789
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -5544,8 +5544,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 308179
-                  slug: product-308179
+                  name: Product 347179
+                  slug: product-347179
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -5723,8 +5723,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 248496
-                  slug: product-248496
+                  name: Product 287496
+                  slug: product-287496
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -5842,7 +5842,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 392 Lovely Street
+                  address1: 410 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -5864,7 +5864,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 393 Lovely Street
+                  address1: 411 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -5970,7 +5970,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 198 Lovely Street
+                  address1: 216 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -5991,7 +5991,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 199 Lovely Street
+                  address1: 217 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -6012,7 +6012,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 200 Lovely Street
+                  address1: 218 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -6270,7 +6270,7 @@ paths:
                 first_name: John
                 last_name: Doe
                 full_name: John Doe
-                address1: 212 Lovely Street
+                address1: 230 Lovely Street
                 address2: Northwest
                 postal_code: '10118'
                 city: New York
@@ -6352,7 +6352,7 @@ paths:
                 first_name: John
                 last_name: Doe
                 full_name: John Doe
-                address1: 218 Lovely Street
+                address1: 236 Lovely Street
                 address2: Northwest
                 postal_code: '10118'
                 city: Los Angeles
@@ -6847,8 +6847,8 @@ paths:
                     preorder_ships_at:
                     quantity: 1
                     currency: USD
-                    name: Product 2135270
-                    slug: product-2135270
+                    name: Product 2525270
+                    slug: product-2525270
                     options_text: ''
                     price: '10.0'
                     display_price: "$10.00"
@@ -6966,7 +6966,7 @@ paths:
                     first_name: John
                     last_name: Doe
                     full_name: John Doe
-                    address1: 284 Lovely Street
+                    address1: 302 Lovely Street
                     address2: Northwest
                     postal_code: '10118'
                     city: New York
@@ -6988,7 +6988,7 @@ paths:
                     first_name: John
                     last_name: Doe
                     full_name: John Doe
-                    address1: 285 Lovely Street
+                    address1: 303 Lovely Street
                     address2: Northwest
                     postal_code: '10118'
                     city: New York
@@ -7169,8 +7169,8 @@ paths:
                   preorder_ships_at:
                   quantity: 1
                   currency: USD
-                  name: Product 2155633
-                  slug: product-2155633
+                  name: Product 2545633
+                  slug: product-2545633
                   options_text: ''
                   price: '10.0'
                   display_price: "$10.00"
@@ -7288,7 +7288,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 290 Lovely Street
+                  address1: 308 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -7310,7 +7310,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 291 Lovely Street
+                  address1: 309 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -7531,7 +7531,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 296 Lovely Street
+                  address1: 314 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -7552,7 +7552,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 297 Lovely Street
+                  address1: 315 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -7574,7 +7574,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 297 Lovely Street
+                  address1: 315 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -7596,7 +7596,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 296 Lovely Street
+                  address1: 314 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -7688,7 +7688,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 298 Lovely Street
+                  address1: 316 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -7709,7 +7709,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 299 Lovely Street
+                  address1: 317 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -7731,7 +7731,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 299 Lovely Street
+                  address1: 317 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -7753,7 +7753,7 @@ paths:
                   first_name: John
                   last_name: Doe
                   full_name: John Doe
-                  address1: 298 Lovely Street
+                  address1: 316 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -9732,7 +9732,7 @@ paths:
                 variant:
                   id: variant_gbHJdmfrXB
                   product_id: prod_gbHJdmfrXB
-                  sku: SKU-366
+                  sku: SKU-435
                   options_text: ''
                   track_inventory: true
                   media_count: 0
@@ -10663,7 +10663,7 @@ paths:
                   first_name:
                   last_name:
                   full_name: ''
-                  address1: 257 Lovely Street
+                  address1: 275 Lovely Street
                   address2: Northwest
                   postal_code: '10118'
                   city: New York
@@ -10734,7 +10734,7 @@ paths:
                 first_name:
                 last_name:
                 full_name: ''
-                address1: 260 Lovely Street
+                address1: 278 Lovely Street
                 address2: Northwest
                 postal_code: '10118'
                 city: New York
@@ -10913,8 +10913,8 @@ paths:
                     preorder_ships_at:
                     quantity: 1
                     currency: USD
-                    name: Product 2125649
-                    slug: product-2125649
+                    name: Product 2515649
+                    slug: product-2515649
                     options_text: ''
                     price: '10.0'
                     display_price: "$10.00"
@@ -11032,7 +11032,7 @@ paths:
                     first_name: John
                     last_name: Doe
                     full_name: John Doe
-                    address1: 268 Lovely Street
+                    address1: 286 Lovely Street
                     address2: Northwest
                     postal_code: '10118'
                     city: New York
@@ -11054,7 +11054,7 @@ paths:
                     first_name: John
                     last_name: Doe
                     full_name: John Doe
-                    address1: 269 Lovely Street
+                    address1: 287 Lovely Street
                     address2: Northwest
                     postal_code: '10118'
                     city: New York

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

@@ -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,
@@ -88,12 +90,20 @@ Spree.reporting.metric :total_sales,
   a `:percent` metric arrives as the number a merchant reads (`42.5`), not the
   fraction.
 
-  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 its
   channel 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, computed
   after aggregation so it is correct for both rows and totals. Average order
   value is `ratio: %i[total_sales orders]`, never `AVG()`.

package/dist/developer/how-to/extend-reporting.md

@@ -198,6 +198,18 @@ These are limits of the compiler, not of registration:
 Registering a base is otherwise ordinary: declare its family, its table, a
 store-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
+}
+```
+
 ```ruby
 Spree.reporting.base :subscriptions, family: :subscriptions,
   table: '%{subscriptions}',

package/package.json

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