Reference1 min read

Reference — Overview

Lookup material that does not belong anywhere else. The Scalar-rendered API Reference, the Error Codes table, and the Changelog.

Docs  Reference  Overview

Reference is the dry, accurate layer of the docs. The API Reference is the single source of truth for every public endpoint, generated from the live OpenAPI spec and rendered with try-it-out. Error Codes is the lookup for "what does HTTP 422 with this code actually mean." The Changelog is the record of what shipped, in date order. Three pages, all lookup-shaped.

What this section is for#

Reach for these when you already know what you're looking for. The narrative docs (every other section) explain a concept and walk a workflow; Reference answers a single, specific question — what does this endpoint take, what does this error code mean, what changed last week.

Pages in this section#

API Reference

Scalar-rendered OpenAPI. 17 endpoint families, try-it-out, multi-language code samples, auth-aware.

Open

Error Codes

Every error code Aforo returns. HTTP status, error code, message, what to do.

Open

Changelog

Date-ordered record of platform changes. Filter by category, RSS, email subscribe.

Open

How the API Reference is generated#

/api-reference renders a hand-curated OpenAPI spec via Scalar. The spec aggregates endpoints from every backend service that's in scope for external use — customer-facing storefront APIs plus operator management APIs — and intentionally hides internal-only paths (anything under /internal/* or /api/v1/admin/*).

What you'll find there

17 endpoint families — Authentication, Catalog, Subscriptions, Checkout, Embed widgets, Invoices & Payments, API keys, Agents & MCP, Coupons, Webhooks & Events, Usage ingestion, plus the operator management families (Customers, Products & Metrics, Rate Plans, Offerings, Entitlements, Quotes).
Try-It-Out panels — paste a token, send a request, see the live response.
Multi-language code samples — curl, Node, Python, Go, Java, PHP, Ruby.
Auth-aware — Bearer + X-Tenant-Id required on most endpoints.

 INFO

The Scalar surface has its own left-side endpoint navigator. The docs sidebar (this one) auto-hides on /api-reference so you're not staring at two competing sidebars — use the top nav to come back to the rest of the docs.

Error codes — what they mean#

Aforo returns errors as RFC 7807 Problem Detail. Every error body carries:

FieldMeaning

typeURI identifying the error class. Often points at the docs page that explains it.

titleShort, human-readable summary.

statusHTTP status repeated in the body for parsers.

detailSpecific to this occurrence. Safe to log.

codeStable string code (e.g. UNKNOWN_METRIC). Branch on this in client code, not on the message.

instanceCorrelation id — include this when filing a ticket.

See Error Codes for the full table of codes the platform returns, plus the recommended client behaviour (retry, surface to user, escalate).

Changelog — how to stay current#

Every shipped change gets a Changelog entry — new features, breaking changes, deprecations, bug fixes that touched a public surface. Three ways to follow it:

ChannelHow to subscribe

Web pageBookmark /changelog. Filter by category, search by keyword.

RSS/changelog.rss — drop into Feedly, Reeder, or your team's news channel.

EmailSubscribe from the /changelog page header. Per-category opt-in, weekly digest or per-release.

 PRO TIP

Breaking changes always ship behind a deprecation window. The changelog labels them explicitly and links to the migration guide. If you build against a public API, subscribing the Changelog is the cheapest way to never get surprised.