Analytics and saved views

Every figure comes back three ways: its value for the range, the same figure for the comparison period, and the change between them. Money is minor units and a percent metric is basis points, where 250 is 2.5%. Null is not zero, so average order value over a range with no orders is null rather than a figure nobody measured. Refunds are never netted off revenue: a month with 10,000 of sales and 400 of refunds reports both numbers, because the second one is the one worth watching. cogs, margin and margin_rate need a costed catalogue, and a catalogue that is only partly costed reports a margin that is too high.

comparison is previous_period, previous_year or none, and reports.default_comparison picks which one a report opens on. A comparison is calendar arithmetic done in reports.timezone, not in UTC and not in the browser's zone, so a daylight-saving week really is an hour shorter than the week it is compared against and 29 February compares against 28 February the year before.

A filter set is a match mode of all or any and a list of field, operator and value clauses. GET /kahunacart/reports/vocabulary publishes every field with its operators, its grain and whether it can be broken down by, every metric with the sentence that defines it, and the two match modes, so a client draws the filter row without hardcoding any of it. A clause naming a field that is not on that list is refused with a 422 naming the field rather than quietly answering a different question. product and category are line-grain: filtering by one restricts the report to orders containing a matching line, and the money is still the whole order's.

Every payload says whether it was read from the nightly rollup or scanned from orders, per breakdown as well as overall, and never falls back without saying so. A filtered report always scans, because the rollup holds day rows with nothing on them to filter against.

Saved views are per user and a store keeps at most 50 per report. Somebody else's view answers 404 rather than 403, because whose it is is not information you are owed. A view stores the same filters, breakdown and range the Analytics URL carries, so a saved view and a copied link are the same state under two names.

view-configs/{entity} covers orders, products and customers. The choice is stored as a diff of the columns you turned off rather than as an allowlist, so a column added by a later release appears for everybody, and a PUT with no columns puts the code defaults back. Each screen has one column that cannot be turned off, because a row you cannot identify is not a row. PUT /kahunacart/property-labels renames a field everywhere the admin names it, stored per language and replaced whole, with a blank value meaning a removal rather than a rename to nothing. A key nobody declared is refused by name. Everything in this group needs kahunacart.reports except property labels, which need kahunacart.settings.