Products

The Product Catalog is the starting point for everything in Aforo. A product is the buyable unit of value — the thing a customer subscribes to and consumes over time. Rate plans price it, offerings package it, invoices summarize it, and analytics rolls up by it, so getting the catalog right first saves rework later.

Product types

Four product types are generally available. Picking a type when you create a product auto-seeds the standard billable units for that shape (see Billable Units).

Type	What it is	Credential
Standard API	REST / HTTP APIs	Bearer token (`sk_live_…`)
Agentic API	HTTP APIs invoked by AI agents, billed per request/step	Bearer token (`sk_live_…`)
AI Agent	Autonomous agents billed per session, step, and token	Client credentials (`client_id` + `client_secret`)
MCP Server	Model Context Protocol servers billed per tool call	Client credentials (`client_id` + `client_secret`)

Four more types — GraphQL API, gRPC API, WebSocket API, and MQTT Broker — appear in the create wizard marked Coming Soon and can't be created yet.

Status

A product's status tracks where it is in its own lifecycle:

Status	Meaning
`DRAFT`	Work in progress; not yet monetizable.
`ACTIVE`	Live; can be attached to rate plans and offerings.
`ARCHIVED`	Retired. Deleting a product archives it (a soft delete) — the record is kept, not dropped.

ℹ

A product also carries an informational lifecycleState label (PRODUCTION, BETA, DEPRECATED, SUNSET, RETIRED, …) that an operator can set directly. It's a label for your own reporting — Aforo does not enforce an order between states and does not block a product from being labeled retired while it still has subscribers. The real safety net is the delete check below, not the label.

Whether a product shows on your public storefront is controlled separately, by your storefront configuration and offering visibility — not by the product's status. See Customize Storefront.

Creating a product

Go to Catalog → Products and click New Product.
Pick a product type — this seeds the standard billable units for that shape.
Enter a name and description.
For Standard API / Agentic API, optionally paste an OpenAPI spec to generate reference docs. For AI Agent, you can instead import capabilities straight from a Git repository (below).
Save as a draft, then set it Active when you're ready to price it.

Import an AI Agent from a repository

For AI Agent products, Aforo can read an agent.yaml manifest from a Git repo and pre-fill the product's capabilities, so you don't hand-enter each one.

POST/api/v1/products/discover-ai-agentPreview — fetch and parse the manifest, no write

POST/api/v1/products/import-from-repositoryCreate the product from the manifest

PATCH/api/v1/products/{id}/sync-capabilitiesRe-read the repo and refresh capabilities

The product records where its capabilities came from in capabilitySource — MANUAL (hand-entered), AUTO_DISCOVERED (imported), or EDITED (imported, then changed by hand) — alongside the source repo URL and last-synced timestamp. Private repos authenticate with a per-host token you store once. Products discovered from an external API gateway follow the same import-then-refresh pattern via the product-sync endpoints.

Gateway sync status

A product linked to an external gateway (Kong, Apigee, AWS API Gateway, Azure APIM, MuleSoft) tracks a sync status:

Status	Meaning
`NOT_APPLICABLE`	No gateway mapping.
`SYNCED`	Aforo's record matches the gateway.
`PENDING`	A sync is in progress.
`FAILED`	The last sync attempt failed.
`CONFLICT`	Aforo and the gateway disagree and need reconciliation.
`STALE`	The gateway config has drifted from Aforo's record.

⚠

A STALE or CONFLICT mapping means gateway-level enforcement (rate limiting, access control) may not reflect your latest configuration. Billing is unaffected — it runs from Aforo's own record — but re-sync the mapping from the integration to bring the gateway back in line.

Deletion protection

Deleting a monetized product would strand live billing, so Aforo runs a two-step, dependency-aware check: ask for a verdict, then delete with the returned confirmation token.

GET/api/v1/products/{id}/deletion-checkReturns ALLOW / WARN / BLOCK + the blocking dependencies

DELETE/api/v1/products/{id}Requires X-Confirm-Token when the verdict was WARN

Verdict	When	What to do
`ALLOW`	Nothing references the product.	Delete (archives it).
`WARN`	Active rate plans reference it, but no active subscriptions.	Confirm with the returned `X-Confirm-Token`.
`BLOCK`	Active subscriptions or unsettled invoices exist.	Migrate or cancel subscriptions and settle invoices first.

ℹ

The check is fail-closed: if pricing, billing, or storefront can't be reached to confirm dependencies, the verdict is BLOCK, never a risky ALLOW. So a BLOCK during an outage doesn't mean the product is monetized — it means Aforo couldn't prove it's safe to delete.

ℹ

Cloning is available for billable units, not products — there's no product-clone action. To stand up a variant product, create a new one and attach the billable units you want; the units themselves are shared many-to-many, so you're not duplicating meters.