Metering schema

Last updated Jun 14, 2026

This page is the authoritative metering schema. It defines what Matter bills for, what it does not, and how customers can introspect their consumption.

The schema is declared in the OpenAPI spec via x-matter-billable-units per operation. Codegen at apps/api/scripts/generate-metering.ts emits the runtime metering registry. The customer-facing GET /v1/account/usage reads from this registry.

Billable units

Matter bills in units. A unit is the smallest billable quantum of work. Different operations consume different unit counts.

What is NOT billable

• 4xx and 5xx responses. Errors do not count toward API call quota. The customer's misconfigured retry does not bill them.
• Webhook retries. Only the eventually-successful delivery counts. Retries are Matter's cost to bear.
• Idempotency-key replays. Replays return the original response without re-executing the side effect; the replay does not bill an additional unit.
• GET /v1/limits and GET /v1/me introspection. Free, always.
• GET /v1/health health check. Free, always.
• Status page probes. Free.
• Dry-run mutations (?dry_run=true). Bill 0.1 units (a tenth of the underlying mutation's cost), to deter abuse but not penalise legitimate planning.
• Test-mode operations. Free in test mode (sk_test_*). Test mode is for development; billing would discourage proper testing.
• Test Clocks. Free.

What IS billable

• 2xx responses to billable endpoints (most operations).
• Successful webhook deliveries (one unit per delivery, counted toward the customer's webhook-event quota).
• Composite saga executions (counted as one composite-unit regardless of how many sub-events the saga emits).
• Filings submitted to providers (one unit per accepted filing).
• AI categorisations for mail handling (one unit per categorisation).
• Customer data exports (one unit per export).
• Entity-months (the underlying entity's existence in the customer's portfolio).

Free tier specifics

The Free tier is intended for evaluation, individual founders pre-funding, and educational use. It includes:

• 5 entities (live mode).
• 5 entities (sandbox).
• 25 entities (test mode — unrestricted; test mode is for development).
• 100k API calls per month.
• 1k webhook events delivered per month.

Free-tier customers cannot:

• Access mTLS, M2M OAuth, SCIM, SAML.
• Use Enterprise tier features (dedicated cluster, custom rate limits).
• Get human support beyond docs + status page. (Auto-help via the in-browser console is available.)

Per-operation billable-unit declarations

In the spec:

paths:
  /v1/entities:
    post:
      x-matter-billable-units:
        - resource: api_call
          quantity: 1
        - resource: entity_month
          quantity: 1
          when: response.status == 202

Codegen reads these and emits the runtime metering registry. Every request that completes is metered against the customer's account in the same transaction as the response. Failures roll back the meter increment with the response.

Usage introspection

Customers query:

GET /v1/account/usage
Authorization: Bearer <token>

Returns:

{
  "object": "usage",
  "period": "2026-05-01..2026-05-31",
  "tier": "growth",
  "billable_units": {
    "api_call": { "consumed": 142_587, "included": 10_000_000, "over_quota": 0 },
    "entity_month": { "consumed": 47, "included": 500, "over_quota": 0 },
    "webhook_event": { "consumed": 12_403, "included": 100_000, "over_quota": 0 },
    "composite_saga": { "consumed": 3, "included": 500, "over_quota": 0 },
    "filing": { "consumed": 8, "included": 500, "over_quota": 0 },
    "ai_categorisation": { "consumed": 95, "included": 1_000, "over_quota": 0 },
    "data_export": { "consumed": 1, "included": 25, "over_quota": 0 }
  },
  "estimated_amount_due": "0.00",
  "currency": "USD"
}

The dashboard (P0.I7) surfaces this live. Customers can drill down to per-day consumption.

Invoice API

The full invoice surface lives at GET /v1/account/invoices/*. Read-only. Each invoice:

• Lists every billable line item (per-resource consumption + over-quota).
• Lists every credit issued (per the SLA enforcement engine + manual adjustments).
• Computes the net amount due.
• Includes the underlying timestamp range.

Invoices are immutable once issued. Disputes are tracked separately.

Why metering is published

Three reasons.

1. Customer trust. "What am I paying for?" is one of the first three questions every enterprise asks. Without a published schema, every conversation starts from zero.
2. Cost predictability. Customers building integrations want to forecast their bill. The schema enables it.
3. Engineering discipline. A published billable-units schema forces engineering to think about what consumes resources before declaring an endpoint. Cost-as-architecture (per the strategic frame) starts here.

Pricing transparency vs published prices

This page documents what is billed. Specific dollar amounts per unit (e.g., the over-quota price per entity-month) are at https://mattermode.com/pricing. We deliberately keep the dollar amounts on the marketing pricing page (which can move) and the schema on the docs page (which cannot).

See also

• SLA — availability commitments + credits.
• Quotas — per-tier limits.
• API design philosophy — commitment 15 (Cost is architecture)
• Customer dashboard usage page.