1 min read

Core Concepts: Monetization as Infrastructure

Aforo is a decoupled orchestration plane. It handles pricing, margins, and access so your gateways only handle traffic.

The Mental Model#

Traditional billing systems sit at the end of the pipeline — they receive events after the fact and generate invoices days later. Aforo sits at the edge. It intercepts every API request, makes a fast edge decision (allow, throttle, or block), and asynchronously meters the usage. The gateway handles traffic. Aforo handles the business logic.

 INFO

Think of Aforo as a financial co-processor for your API infrastructure. Your gateway routes packets. Aforo routes revenue.

This separation means your engineering team never writes billing code. Pricing changes, new tiers, custom enterprise deals, margin floors — all configured by Product and Finance teams in the Aforo Admin UI. Zero Jira tickets. Zero deploys.

Pillar 1: Meters#

Meters are sensors that capture raw usage events. Every API call, token consumed, storage byte written, or agent session initiated generates a usage event that flows into the Metering Engine.

API Calls

POST /v1/search — 1 call

Token Consumption

GPT-4o: 2,400 input + 800 output

Storage Events

S3 PUT: 4.2 MB uploaded

Agent Sessions

MCP tool_call: SmartSearch.query

 PRO TIP

Meters are asynchronous and non-blocking. Usage ingestion happens after the API response is sent. Your P99 latency is never impacted by metering.

Pillar 2: Entitlements#

Entitlements are the real-time gatekeeper. Before an API request is processed, the gateway calls Aforo's edge cache to check: Does this customer have access to this feature? Have they exceeded their quota? Is their subscription active?

entitlement-check-response.json

GET /v1/entitlements/check?accessorId=app_abc123&productId=prod_xyz789

{
  "allowed": true,
  "quotaRemaining": 8420,
  "budgetRemaining": 42.50
}

This check reads from a Redis-backed cache at the gateway edge — single-digit milliseconds on a cache hit, falling back to a pricing-service call on a miss. The cache is refreshed roughly every 30 seconds by a background sync job.

Pillar 3: Margin Guards#

Margin Guards are circuit breakers for profitability. When a customer's usage cost (COGS) approaches or exceeds their contract revenue, Aforo intervenes — before the damage hits your P&L. You configure the warning / throttle / block thresholds in the margin policy; the gateway acts on the intervention level the policy check returns, not a hardcoded percentage.

Meters vs. Entitlements vs. Margin Guards

ConceptRoleWhen It RunsLatency Impact

MetersSensors that capture raw usage eventsPost-response (async)0ms — fully async

EntitlementsGatekeeper that checks access + quotaPre-request (sync)<5ms — edge cache

Margin GuardsCircuit breaker for profitabilityPre-request (sync)<5ms — same cache lookup

The Three Intervention Levels

MARGIN GUARD/ All Gateways

Level 1 — Warning: at your warning threshold, Aforo fires an alert (webhook / notification) to the account owner. The request proceeds normally and the customer is unaffected — but Finance knows a contract is trending unprofitable.

MARGIN GUARD/ All Gateways

Level 2 — Throttle: at your throttle threshold, the gateway starts rejecting a share of requests with HTTP 429 and the headers X-Margin-Guard: throttled / X-Margin-Guard-Level: L2. The rejection is probabilistic — the deeper the margin breach, the larger the share throttled — so traffic degrades gradually rather than stopping dead.

MARGIN GUARD/ All Gateways

Level 3 — Block: at your block threshold the gateway rejects the request with HTTP 429 and X-Margin-Guard: blocked / X-Margin-Guard-Level: L3. The request never reaches your backend — unprofitable traffic is stopped before it generates compute cost.

 WARNING

Margin Guards operate on real-time COGS data. If your AI provider raises prices mid-month, Aforo detects the margin compression immediately — not 45 days later when the invoice arrives.

The Data Flow#

<5ms

Edge Enforcement (cache hit)

Entitlement + margin check from a gateway-edge cache; on a miss it falls back to pricing-service. Metering is fully async — no impact on your P99.

Every API request follows a four-stage lifecycle:

request-lifecycle.txt

1. REQUEST HITS GATEWAY
   └── Kong / Apigee / AWS / Azure / MuleSoft receives the inbound request

2. AFORO EDGE CHECK (<5ms)
   ├── Redis cache lookup: workspace entitlements + quota + margin status
   ├── Decision: ALLOW | THROTTLE | BLOCK
   └── On a margin breach: X-Margin-Guard headers set (throttled / blocked)

3. API PROCESSES REQUEST
   └── Your application logic executes (Aforo is invisible here)

4. ASYNC USAGE INGESTION
   ├── Gateway plugin fires async POST to Aforo Metering Engine
   ├── Event validated, deduplicated, enriched
   ├── Rated against active Offer rules
   └── Routed to billing pipeline (wallet drawdown or invoice accrual)

The Latency Guarantee#

<5ms

Edge Decision

Entitlement + margin check at the gateway

0ms

Metering Overhead

Usage ingestion is fully async, post-response

30s

Cache Refresh

Entitlement cache synced from source of truth

 PRO TIP

The metering path adds no latency to your hot path — usage ingestion fires asynchronously after your response is returned, so your P99 is untouched. The inline entitlement + margin check is served from a gateway-edge cache, with a fallback to pricing-service on a cache miss.