SaaS Metering and Billing Design: [Product name]

Design document for usage metering and billing in a software-as-a-service product: the pricing model, billable metrics, the usage event contract (CloudEvents 1.0.2), the metering pipeline with idempotent ingestion and late-event handling, entitlements and plans, rating and aggregation, quotas and overage, integration with the invoicing and payment systems, revenue recognition hooks, reconciliation, audit and operations. Tenant cost and tiering considerations follow the themes of the AWS Well-Architected SaaS Lens (publication of 4 April 2023). Replace every [bracketed] value and every row marked Example. Revenue recognition rows are a documentation format, not accounting advice.

Document control

Approvals

Revision history

Contents

1. Scope and context
2. Pricing model
3. Billable metrics
4. Usage event contract
5. Metering pipeline
6. Entitlements and plans
7. Rating and aggregation
8. Quotas, limits and overage
9. Invoicing and billing integration
10. Revenue recognition hooks
11. Accuracy, reconciliation and audit
12. Tenancy, security and privacy
13. Operations and service levels
14. Trade-offs, decisions and risks
15. Glossary and references

1. Scope and context

1.1 Scope

1.2 Context

1.3 Requirements

2. Pricing model

2.1 Plans

3. Billable metrics

Rules for metric definitions:

• Measure at the point where the action is complete and its outcome is known, not at request receipt.
• Prefer metrics the customer can verify from their own logs or console.
• State the time zone and the period boundary; an event at 23:59:59 UTC must fall in one period only.
• Version metric definitions. A definition change applies from a stated period and never re-rates closed periods silently.

4. Usage event contract

Usage events use the CloudEvents 1.0.2 format. CloudEvents requires the context attributes id, source, specversion and type, and requires producers to keep the combination of source and id unique for each distinct event; consumers may treat events with the same source and id as duplicates. The metering pipeline uses that pair as the idempotency key.

{
  "specversion": "1.0",
  "id": "4f1c2a9e-7b1d-4d8e-9a55-2f0c1e7d9b10",
  "source": "//api.example.com/regions/eu-west/gateway-07",
  "type": "com.example.api.request.completed",
  "subject": "tenant/t-10442",
  "time": "2026-10-23T09:14:07.512Z",
  "datacontenttype": "application/json",
  "dataschema": "https://schemas.example.com/usage/api-request/2",
  "data": {
    "tenantId": "t-10442",
    "subscriptionId": "sub-88310",
    "metric": "MET-001",
    "quantity": 1,
    "dimensions": { "region": "eu-west", "apiProduct": "search" },
    "statusClass": "2xx"
  }
}

Corrections are new events of a correction type (for example com.example.usage.adjustment) that reference the original id and carry a signed quantity and a reason code. Never edit or delete a stored usage event. Register the event types in the event catalogue described in the event-driven architecture design (architecture/event-driven-architecture-design).

5. Metering pipeline

5.1 Stage responsibilities

5.2 Late and out-of-order events

5.3 Capacity estimate

Example: 12,000 events per second on average gives 12,000 x 86,400 = 1,036,800,000 events per day. At 600 bytes per event that is about 622 GB of raw usage per day, or about 246 TB for 396 days (13 months) before compression. Consequence: pre-aggregate high-volume metrics at the producer in one-minute windows per tenant and dimension (keeping counts exact), and keep per-request events only where customers need line-level evidence. Size the deduplication store for the keys of the full 35-day horizon, or deduplicate pre-aggregated windows by window key instead.

6. Entitlements and plans

The entitlement service holds, per tenant, the active plan, features, included quantities, limits and contract terms. Products ask it, through a cached local client, whether a feature or quantity is allowed. The billing system is the commercial source; changes flow to the entitlement service as events, so the product never depends on the billing system being available.

Plan changes in the middle of a period are prorated by the billing system for fees; usage metrics switch rate at the effective timestamp of the change, which the rating engine reads from the subscription history. Design feature flags with the configuration service design (system-design/design-config-feature-flag-service).

7. Rating and aggregation

Rate with decimal arithmetic in the currency's minor units, round once per invoice line using the rounding rule agreed with finance ([half-up to 2 decimals]), and store the price book version, the quantities and the result with each rated line.

7.1 Worked example: graduated versus volume tiers

Example price book for MET-001 on PLN-TEAM: first 1,000,000 calls included; 1,000,001 to 10,000,000 at USD 0.20 per 1,000 calls; above 10,000,000 at USD 0.10 per 1,000 calls. Tenant t-10442 used 14,500,000 calls in the month.

With the platform fee of USD 500, the graduated invoice is USD 2,750. Under volume tiers, where all billable calls take the rate of the tier reached, the 13,500,000 calls above the included amount would cost 13,500 x USD 0.10 = USD 1,350, and the invoice would be USD 1,850 (here the included allowance is deducted before the volume rate applies; state this in the price book). The two models differ by USD 900 for the same usage, which is why the price book must name the tier mode explicitly.

7.2 Worked example: prepaid commitment with drawdown

Example: an Enterprise customer prepays USD 30,000 of credits for 12 months at the contract rate card. Monthly usage rated at the contract rate card is USD 2,750 (illustrative, and not the Team invoice of section 7.1, which includes a platform fee), so 12 months consume USD 33,000. Credits run out during the eleventh month (10 x 2,750 = 27,500 leaves 2,500, which covers most of month 11); the remaining USD 3,000 is overage billed monthly in arrears at the contract overage rate. Send a commitment alert at [75 %] drawdown (USD 22,500, reached during month 9) so the account team can propose a renewal or top-up.

8. Quotas, limits and overage

Quota decisions use the aggregator's running totals plus a local allowance per instance, so the hot path does not call a central service for every request. Accept a small overshoot (bounded by the allowance size) and state it in the terms. Rate limiting itself is designed with the rate limiter design (system-design/design-rate-limiter).

9. Invoicing and billing integration

Send rated usage as idempotent line items keyed by tenant, metric, period and price book version, so resending after a failure cannot double-bill. Record money movements with the double-entry patterns in the payment ledger design (system-design/design-payment-ledger). Marketplace sales (cloud marketplaces) need usage reported to the marketplace's own metering interface; treat each marketplace as another billing channel with its own reconciliation.

10. Revenue recognition hooks

Revenue recognition follows the organisation's accounting policies under ASC 606 (United States GAAP) or IFRS 15 (International Financial Reporting Standards), decided by revenue accounting. The metering and billing design supplies the data below; it does not decide the accounting treatment.

11. Accuracy, reconciliation and audit

Audit rules: keep raw events, price book versions, rating outputs and adjustments for the retention period; log every manual adjustment with requester, approver and reason; give customers a usage export that sums to their invoice lines; and test the reconciliation jobs with seeded errors (duplicates, late events, missing hours) before go-live.

12. Tenancy, security and privacy

• Derive the tenant from the authenticated context at the producer, never from client input, and validate it at ingestion against the subscription. Apply the tenancy patterns of the multi-tenancy design (architecture/multi-tenancy-design).
• Authenticate producers with workload identities; only registered sources may emit each event type.
• Separate duties: engineers deploy rating code; finance approves price books; nobody does both for the same change.
• Minimise personal data in usage events: use pseudonymous user IDs for seat metrics and keep the mapping in the product.
• Encrypt usage stores at rest; restrict raw event access to named roles, with access logged.
• Keep usage in region where residency commitments apply and move only aggregates across regions.

13. Operations and service levels

Write runbooks for replay from the raw store, re-rating a period before invoicing, issuing a correction after invoicing, and handling a producer that sent wrong quantities. Keep them with the service runbook (dev/runbook).

14. Trade-offs, decisions and risks

15. Glossary and references

Standard and licence note

Based on the CloudEvents 1.0.2 specification (Apache License 2.0) for the event envelope and on common SaaS metering and billing practice; tenant cost and tiering themes are aligned with the AWS Well-Architected SaaS Lens, which is cited and not reproduced. ASC 606 and IFRS 15 are named only; no text of either standard is used, and the revenue rows are a documentation format, not accounting advice. The structure, rules and worked examples are original to this collection. Check the current official specifications and your accounting policies before use. AWS and AWS Well-Architected are trademarks of their owners; this template is not affiliated with or endorsed by them. Template licence: MIT.