Usage and billing

The commercial ledger counts completed platform operations without copying applicant names, document data, images or biometric evidence. Access requires a human tenant administrator session. API keys cannot read billing data or seal a statement.

Every self-service workspace starts free with 50 Sandbox checks. No payment method is collected at registration. After the workspace passes the required security, workflow, capability, Country Assurance Pack and residency gates, an administrator can request independent activation for up to 10 complimentary Live checks. When that approved allowance reaches zero, Live application creation stops with 402 live_trial_exhausted; Sandbox remains available. The administrator chooses Build or Scale in Plan & billing to continue Live processing.

Read the current period

GET /v1/billing
Authorization: Bearer TENANT_ADMIN_SESSION

const billing = await proofline.billing.get();

console.log(billing.statement.periodStart);
console.log(billing.statement.estimatedAmountMinor);
console.log(billing.statement.projectedNetAmountMinor);
console.log(billing.statement.pricingVersionId);
for (const line of billing.statement.lines) {
  console.log(line.meterKey, line.quantity, line.billableQuantity);
}

Every meter line includes the observed quantity, allowance, billable quantity, list or contracted pricing mode, source event count and a SHA-256 digest of the contributing event identifiers. The statement also carries a digest across all meter lines.

The statement separates subtotalAmountMinor, minimumCommitAdjustmentMinor, estimatedAmountMinor, projectedCreditMinor and projectedNetAmountMinor. A preview can project an available credit but never consumes it. Credits are locked and consumed only inside a successful closed-period finalization transaction.

Meter	Counted event
verification_session	Application created
nfc_verification	NFC evidence package completed
attended_verification	Attended session completed
fraud_event	Transaction assessed
ongoing_screening	Scheduled screening run completed
wallet_credential	Holder-bound credential issued
agent_action	Governed agent action receipt written

Events use a tenant-and-meter idempotency key, so retries do not increase usage.

Seal a preview

const { reconciliation } = await proofline.billing.snapshot();
if (reconciliation.sourceSha256 !== billing.statement.sourceSha256) {
  throw new Error("Usage changed while the snapshot was being sealed");
}

POST /v1/billing/usage/reconcile
Authorization: Bearer TENANT_ADMIN_SESSION
Idempotency-Key: 9d4c1cf4-9c34-4472-bba2-a21f51f74d4f
Content-Type: application/json

{"mode":"preview"}

A preview can be refreshed. It is useful for finance review during an open billing period and cannot masquerade as a finalized period.

Finalize a closed period

const result = await proofline.billing.finalize({
  periodStart: "2026-05-01T00:00:00.000Z",
  periodEnd: "2026-06-01T00:00:00.000Z",
});

Finalization fails when the period has not ended or the same tenant and period is already final. The immutable line hashes, quantities and expected amounts become the reconciliation authority.

If an effective-dated commercial version begins inside the requested period, finalization fails and names the pricing boundary. Split the statement at that exact instant. Assayra never blends two rate cards silently.

Effective terms and credits

GET /v1/billing returns the tenant-readable commercial object:

• the active immutable price-book version;
• all version metadata and effective dates;
• included verification quantity and minimum commitment;
• meter rates, including negotiated null rates;
• credit grants, remaining balances and expiry; and
• the rules that pricing changes require a period boundary and credits consume only on finalization.

Only an Assayra Control Tower platform_admin or billing_operator can create terms or grant credit. Tenant administrators can inspect their commercial ledger but cannot rewrite it. Commercial records contain no applicant identity, document or biometric data.

Provider reconciliation

Stripe webhooks are verified against the exact raw request body before processing. Invoice line metadata may carry proofline_meter either directly or on its price. Assayra stores normalized invoice lines, compares them with the finalized period and marks the result:

• reconciled when every known meter amount matches;
• needs_review for missing, unexpected or different meter amounts;
• finalized while no matching provider invoice has arrived; or
• preview for an open-period snapshot.

Invoice mismatches never alter usage events, identity decisions or collected evidence. They create a commercial review item with an explicit difference and discrepancy list.

Money and contracted rates

Amounts ending in Minor use the currency's minor unit. unitAmountMicros is one millionth of the major currency unit, which preserves sub-cent event pricing. Enterprise rates return null and pricingMode: "contracted"; Assayra never invents an unconfigured contract price.

Start paid checkout

The customer administrator must explicitly accept the current versioned service terms and DPA. Render the legal.documents returned by GET /v1/billing before enabling checkout.

const result = await proofline.billing.checkout({
  plan: "scale",
  legalAccepted: true,
});

window.location.assign(result.url);

POST /v1/billing/checkout
Authorization: Bearer TENANT_ADMIN_SESSION
Idempotency-Key: 310fe3cf-2165-46dd-9c62-d9064fd15089
Content-Type: application/json

{"plan":"scale","legalAccepted":true}

Assayra records the administrator, tenant, time, IP hash, user agent, plan, document keys and exact document versions. Stripe metadata receives the same terms and DPA versions. Payment-card data stays in Stripe-hosted Checkout. If the deployment has not yet been connected to Stripe, provider.configurationPending is true and checkout remains disabled without affecting free Sandbox or complimentary Live access.

Errors

Code	Meaning
invalid_usage_period	Dates are invalid or start does not precede end.
usage_period_conflict	The period is open or was already finalized.
forbidden	A non-administrator or API key attempted commercial-ledger access.