SaaS usage billing reconciliation API

Find where usage, contract terms, invoices, and payments stopped agreeing

For revenue operations, billing engineering, and finance systems teams at usage-based SaaS businesses. Send one billing period and receive exact discrepancy arithmetic, the supplied evidence behind each finding, and a bounded repair action.

Run the no-account demo Create a sandbox key

Free: 5 reconciliations/month. Developer: $499/month with 50 included. Compare allowances and pricing.

Realistic synthetic recordsNo API key for demoNo card for sandbox

Who this is for and when to use it

A metered customer used 1.25 million units, the invoice covers 1 million, the contract has a minimum commitment, and the payment is short.

Best-fit team

Billing engineers, RevOps, finance systems owners, and platform teams reconciling usage-based SaaS billing.

Input

Your period label plus contract, usage, invoice, and payment rows. Money stays in integer minor units; per-unit rates use integer micro-cents.

Output

Signed monetary impact, recoverable amount, severity counts, evidence-linked findings, and one repair action per finding.

Primary-value event

A successful authenticated POST /v1/reconciliations that returns discrepancy evidence and a repair plan for a supplied period.

From the problem to a useful result

Choose the part of the review you need to solve

Compare usage with billed quantities

Usage-based billing reconciliation starts by joining a completed period’s records. Compare metered quantities with invoice lines using the same SKU identifiers and the applicable supplied contract terms.

The fictional example records 1.25 million used units and 1 million invoiced units. The representative response connects the quantity difference to its monetary arithmetic and evidence.

Check contract rates and minimum commitments

Review billing rate discrepancies with the contract rate, included units and minimum commitment visible together. Keep money and rates in the integer units required by the request.

The sample includes 100,000 units and a 50,000-minor-unit commitment. Its minimum-commitment finding is separate from the quantity mismatch, so finance can inspect each calculation before approving a correction.

Review payments alongside the invoice evidence

Invoice payment reconciliation compares what the supplied invoice says with the recorded payment. A partial payment remains a review item even when the usage and rate calculation are understood.

In the synthetic example, 2,430 minor units invoiced minus 1,000 received leaves a 1,430-minor-unit underpayment. A finding or proposed collection action is not collected cash.

Run a repeatable close-period review

For the next billing close, prepare the same period label, SKU joins, invoice identifiers and integer units. Use complete meter aggregation and available payment records so the comparison has the intended scope.

The complete JSON example and authenticated path lead to /v1/reconciliations. Review findings in your existing finance process; the API does not issue invoices or move money.

Reconcile the sample billing period Review pricing

Interactive keyless demo

Reconcile a fictional billing period

The example uses invented records, runs the production reconciliation engine, stores nothing, and consumes no account quota. Edit it if useful. Do not paste secrets, personal data, or customer records into an evaluation demo.

Live response

Run the demo to see the unedited API response.

Look first at recoverableMinor, then open each finding's evidence and repair. A demo call is evaluation, not activation or customer evidence.

Copyable no-account path

Run the same example from a terminal

This block runs as written with curl. It contains only fictional data and no placeholder credential.

curl -sS -X POST https://revenueintegrity-api.com/v1/demo/reconcile \
  -H 'content-type: application/json' \
  -d '{"periodLabel":"2026-08","contract":[{"sku":"api-calls","ratePerUnitMicro":27,"includedUnits":100000,"minimumCommitmentMinor":50000}],"usage":[{"sku":"api-calls","quantity":1250000}],"invoices":[{"invoiceId":"INV-1001","sku":"api-calls","quantity":1000000,"amountMinor":2430}],"payments":[{"invoiceId":"INV-1001","amountMinor":1000}]}'

Expected contract-shaped result

What first useful value looks like

Representative response

{
  "periodLabel": "2026-08",
  "netImpactMinor": 49000,
  "recoverableMinor": 49000,
  "findingCount": 3,
  "severityCounts": {"high": 1, "medium": 1, "low": 1},
  "findings": [
    {
      "code": "quantity_mismatch",
      "severity": "low",
      "impactMinor": 675,
      "evidence": [{"kind": "usage", "reference": "api-calls"}],
      "repair": {"action": "issue_invoice", "deltaMinor": 675}
    },
    {
      "code": "minimum_commitment_shortfall",
      "severity": "high",
      "impactMinor": 46895,
      "repair": {"action": "true_up_commitment", "deltaMinor": 46895}
    },
    {
      "code": "underpayment",
      "severity": "medium",
      "impactMinor": 1430,
      "repair": {"action": "collect_payment", "deltaMinor": 1430}
    }
  ],
  "requestId": "req_example"
}

Summaries and request IDs can vary; the field names and value types shown here are the supported result shape.

First useful result

recoverableMinor quantifies the supported positive discrepancy in minor units. Each finding explains which supplied records produced the arithmetic and proposes a bounded next action.

Interpretation

A positive amount is a reconciliation finding, not a promise that cash will be recovered. Review evidence against your source systems before changing an invoice or attempting collection.

Authenticated first-value path

Verify the account, claim the key once, then reconcile

Request a product-scoped key.
Replace only you@example.com. The source tuple identifies this exact-intent page; upstream UTM values are also carried by the signup CTA.
Open the verification email and claim its one-time token.
Replace only PASTE_ONE_TIME_TOKEN_FROM_EMAIL; capture the API key from the claim response.
Call /v1/reconciliations with the bearer key.
The successful discrepancy/evidence/repair response is the primary-value event. Key issuance by itself is not activation.

curl -sS -X POST https://revenueintegrity-api.com/v1/keys \
  -H 'content-type: application/json' \
  -d '{"email":"you@example.com","source":{"source":"product_site","medium":"exact_intent","campaign":"search-revenue-integrity-exact-intent-v1","content":"saas-usage-billing-reconciliation-api-v1"}}'

curl -sS -X POST https://revenueintegrity-api.com/v1/keys/claim \
  -H 'content-type: application/json' \
  -d '{"token":"PASTE_ONE_TIME_TOKEN_FROM_EMAIL"}'

export KEY='PASTE_API_KEY_FROM_CLAIM_RESPONSE'

curl -sS -X POST https://revenueintegrity-api.com/v1/reconciliations \
  -H "Authorization: Bearer $KEY" \
  -H 'content-type: application/json' \
  -d '{"periodLabel":"2026-08","contract":[{"sku":"api-calls","ratePerUnitMicro":27,"includedUnits":100000,"minimumCommitmentMinor":50000}],"usage":[{"sku":"api-calls","quantity":1250000}],"invoices":[{"invoiceId":"INV-1001","sku":"api-calls","quantity":1000000,"amountMinor":2430}],"payments":[{"invoiceId":"INV-1001","amountMinor":1000}]}'

After the example works

Connect one reviewable billing period—not your whole billing stack

Map one period.
Translate contract rate, included units, meter quantity, invoice amount, and received payment into the same integer units as the example.
Route findings by code.
Use quantity_mismatch, minimum_commitment_shortfall, and underpayment to open a human review queue with the returned evidence.
Reconcile again after an approved correction.
Invoice, credit, or collection execution stays in your controlled billing workflow; the API does not move money.

Troubleshooting

The three most likely blockers

401 unauthorized

Use the API key returned once by /v1/keys/claim, not the email claim token. Send it exactly as Authorization: Bearer $KEY.

400 invalid_request or client-side 422

Include periodLabel, contract, usage, and invoices. Money is integer minor units and rates are integer micro-cents; do not send decimal currency strings.

429 rate limited

Read Retry-After when present, wait, then retry with bounded exponential backoff. Do not retry a validation error unchanged.

Need support?

Record the stable error.code and request ID. Share the request ID only—never the API key, claim token, or customer billing records.

Pricing and included usage

Choose a plan for recurring billing reconciliation

One reconciliation is one run over a supplied billing period. It is not one invoice, usage row or customer record; rerunning a period is another reconciliation.

Free

$0/month

5 reconciliations/month

No card required. The keyless demo consumes no account quota.

Developer

$499/month

50 reconciliations/month included

$12 per additional reconciliation. Overage charges capped at $1,000 per billing period, in addition to the base price.

Growth

$1,499/month

250 reconciliations/month included

$8 per additional reconciliation. Overage charges capped at $3,000 per billing period, in addition to the base price.

Scale

$4,999/month

1,200 reconciliations/month included

$5 per additional reconciliation. Overage charges capped at $10,000 per billing period, in addition to the base price.

Prices in USD, billed monthly. Choose a plan for the volume you expect to run. See full pricing and Enterprise options.

Create a key to reconcile your period Review the input contract

Trust, privacy, and limits

A reconciliation result is evidence for review, not an autonomous financial action

The keyless demo processes the supplied payload without storing or metering it. Authenticated use is governed by the privacy policy and terms. Start with fictional or minimized records and confirm your own data rights and controls before submitting production information.

The API has no native Square, Stripe, Paddle, or other billing connector; it does not issue invoices, collect payments, or modify a ledger.
Every finding is derived from the records you supply. It cannot establish that an upstream record is complete or legally authoritative.
No customer or revenue result is claimed. A live page, demo run, signup, key, or synthetic test is not commercial validation.

Create a sandbox key Read the API reference