Repository navigation
docs: document the analytics endpoints - #8
Merged
Merged
Conversation
The API gained four admin analytics endpoints (OpenTaberna/fastapi#44). Refreshing openapi.snapshot.json made the drift check fail with four undocumented paths, which is the check doing its job. Documents them in the endpoint reference along with the metric definitions — what counts as revenue and what does not — because those are choices rather than facts and leaving them implicit in a query is how two readers come away with different numbers. Carries across the limits rather than letting a reader infer something stronger: the funnel is an order funnel and cannot see browsing shoppers, partial refunds are not modelled, per-SKU return rate is an upper bound because returns are per order, and product revenue sums line values which need not match order totals. Also records why checkout is counted from payments rather than order status, that money is grouped by currency and must not be summed, and adds SHOP_TIMEZONE to the configuration reference. Closes #7 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YY1ekLLeFLkAU2kvdQ8Ey4
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #7 · documents OpenTaberna/fastapi#44
Four admin analytics endpoints landed in the API. Refreshing the OpenAPI snapshot made the
drift check fail with four undocumented paths — the check working as designed:
What's documented
The four endpoints, plus the parts a reader cannot recover from the schema:
The metric definitions. What counts as gross revenue, refunded, net, AOV and units, and
what is never counted. These are choices rather than facts, and leaving them implicit in a
query is how two people read the same dashboard and come away with different numbers.
Why money is a list keyed by currency, and that a client must not add the entries
together.
Why days are cut in
SHOP_TIMEZONErather than UTC, with the setting added to theconfiguration reference.
Why checkout is counted from
paymentsrather thanorders.status— status recordsonly where an order is now, so it cannot tell a cancelled checkout from one that never
happened.
What the numbers cannot tell you, stated plainly rather than left to inference: the
funnel is an order funnel and cannot see browsing shoppers, partial refunds are not
modelled, per-SKU return rate is an upper bound, and product revenue need not equal order
revenue.
Verification
Snapshot regenerated from a live instance carrying the merged analytics service (30 paths,
up from 26).