Catalog1 min read

Catalog — Overview

Define what you sell. Products are the things customers buy; billable units are what you count per product. This section walks both.

Docs  Catalog  Overview

Everything you sell sits in the Catalog. A product is the thing a customer subscribes to — your Translation API, your Vision agent, your MCP search server. A billable unit is the meter you read off that product — calls, tokens, sessions, gigabytes. Get the catalog right and every page after it (rate plans, invoices, analytics) lines up. Get it wrong and you re-do work later.

What Catalog is for#

Catalog is the operator-facing inventory of products and meters. It is NOT pricing (that's Pricing Studio), NOT customers (that's Storefront → Customers), and NOT the storefront page they buy from (that's Storefront → Customize). Think of it as the menu — you list dishes here; you price them, plate them, and serve them elsewhere.

 INFO

Catalog data is the load-bearing object for every other section. Rate cards reference billable units, offerings bundle rate cards, invoices summarize products, and analytics rolls everything up by product. Most "the dashboard shows zero" tickets trace back to a billable unit that was never created or a product that was never associated.

Products and Billable Units#

Two entities, one relationship — many-to-many.

EntityWhat it representsYou typically have…

ProductA buyable unit of value. Maps 1:1 to something your customer would put on a contract — "Translation API v2", "GPT-4 Agent", "S3-compatible storage".5–30 in a typical tenant

Billable UnitA meter — the count you charge against. Per product type Aforo seeds industry-standard units (api_calls, tokens_in, tokens_out, tool_invocations, session_seconds, storage_gb_hours, …) and you add custom ones.2–10 attached per product; ~30 default units per product type before you customise

The many-to-many that catches people out

A billable unit is NOT owned by a product. The same api_calls unit can be attached to your Translation API AND your Vision API; the same tokens_out unit can attach to every AI agent you sell. The association is a junction (metric_products) — change a unit's definition once and every product using it picks it up.

Pages in this section#

Products

Create, edit, clone, and archive products. Four product types (API, AI Agent, MCP Server, Agentic API), per-type metadata, OpenAPI spec import at create-time, deletion guards.

Open

Billable Units

Default units per product type, custom units with aggregation rules (SUM, COUNT, MAX, P95, …), product associations, deletion + rate-plan dependency check, export/import.

Open

A worked example#

Say you sell a Translation API. The catalog entries are:

EntityNameWhy it's defined this way

ProductTranslation API v2One product — customers contract for "Translation API", not for the api_calls meter on its own.

Billable Unitapi_callsCOUNT aggregation. Tracks request volume — the main pricing dimension.

Billable Unitcharacters_translatedSUM aggregation. Tracks the actual work done — useful for an overage tier.

Billable Unitp95_latency_msP95 aggregation. Not billed (rate = $0); kept for SLA reporting in Analytics.

With that catalog in place you can move to and build a rate card that charges $0.05 per api_call with a 10k-call included quota, plus a $0.0001-per-character overage on characters_translated.

Product types in v1#

Aforo ships with four product types. Picking the right one auto-seeds the default billable units for that shape:

API

REST or GraphQL HTTP endpoints. Default units: api_calls, request_bytes, response_bytes, p95_latency_ms.

AI Agent

LLM-driven agents (LangChain, CrewAI, custom). Default units: agent_runs, tokens_in, tokens_out, session_seconds.

MCP Server

Model Context Protocol servers. Default units: tool_invocations, session_seconds, active_sessions, tokens_in, tokens_out.

Agentic API

HTTP endpoints that invoke an agent under the hood. Hybrid: api_calls + agent_runs + tokens.

Where Catalog feeds into next#

Once your products and billable units exist, every downstream section reads from them:

Pricing Studio — rate cards charge against billable units; offerings bundle rate cards per product.
Gateways & SDKs — every metered event references a billable unit name; the ingestor rejects names that don't exist in your catalog.
Intelligence — dashboards group revenue by product; usage drill-downs filter by billable unit.
Storefront — the public product card displays each product's name + description + feature list.

 PRO TIP

If you're starting fresh, build catalog before pricing. The wizard makes you pick a product type and pre-seeds the standard billable units for that shape — you almost always want those defaults rather than starting from a blank slate.