> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Billing System
> Pay-per-use pricing, plan tiers, and usage management for your Truthlocks organization.
Truthlocks uses a pay-per-use billing model where you only pay for what you consume. Every organization (tenant) has its own subscription, usage counters, and billing cycle. Features and quotas are enforced based on your active plan.
## Plan tiers
* **Tenant-Centric**: Each tenant (Organization) has its own subscription and billing cycle.
* **Entitlements**: Features and quotas are enforced based on the active plan key (`plan_developer`, `plan_starter`, `plan_business`, `plan_institutional`, `plan_enterprise`).
* **Multi-Provider**: We route payments through different gateways (Stripe, Paystack, Flutterwave) depending on the tenant's legal jurisdiction.
* **Regional Pricing**: Checkout automatically uses your account's country to apply the correct regional rates and currency. See [provider routing](/billing/provider-routing) for details.
## Plan Tiers
For hobbyists and proof-of-concept projects. Includes online verification and community support at no cost.
For SMBs and startups with production workloads. Higher quotas, up to 3 webhook endpoints, and priority processing.
For mid-market teams with compliance needs. SAML SSO, SCIM provisioning, full RBAC and audit logs, up to 10 webhook endpoints, and a 4-hour support SLA.
For large enterprises with advanced security needs. Private transparency log, HSM integration, and a 1-hour support SLA.
Custom pricing for governments and Fortune 500. Custom SLA, on-premise deployment options, 24/7 support, and tailored onboarding.
## Core concepts
* **Entitlements** — each plan unlocks specific features and quotas (mint limits, verification counts, seats, storage, API rate limits). The billing service enforces these limits at the API layer.
* **Usage counters** — all 16 metered products are tracked per billing cycle. You can monitor your consumption from the console usage dashboard or the [usage API](/api-reference/billing/usage).
* **Multi-provider routing** — payments are processed through the optimal gateway for your region. See [provider routing](/billing/provider-routing) for details.
## Metered products
Truthlocks meters 16 products organized into four categories. You can see all of them on the [pricing page](https://www.truthlocks.com/pricing) and track your consumption in the console at **Settings > Billing > Usage**.
### Core
| Product | Description | Default rate |
| :----------------- | :--------------------------------------- | :---------------------- |
| Attestation mints | Attestations created via the API or SDK | \$0.25 per mint |
| Verifications | Attestation verification requests | \$0.10 per verification |
| Storage | Total file and evidence storage consumed | Included per plan |
| Proof bundles | Cryptographic proof bundles generated | Included per plan |
| Webhook endpoints | Active webhook endpoint registrations | Included per plan |
| Webhook deliveries | Individual webhook delivery attempts | Included per plan |
| Seats | Team member seats in your organization | Included per plan |
### MAIP (Machine Identity)
| Product | Description | Default rate |
| :------------------- | :--------------------------------- | :------------ |
| Agents | Registered machine agents | Per plan tier |
| Sessions | Agent sessions created per month | Per plan tier |
| Trust score computes | On-demand trust score calculations | Per plan tier |
| Compliance checks | Compliance verification requests | Per plan tier |
### AI
| Product | Description | Default rate |
| :------------------- | :------------------------------------- | :------------ |
| Dataset attestations | Datasets attested for lineage tracking | Per plan tier |
| Model attestations | ML models attested for provenance | Per plan tier |
### Anti-Fraud
| Product | Description | Default rate |
| :--------------- | :--------------------------------------- | :------------ |
| Risk signals | Fraud signals ingested or generated | Per plan tier |
| Deepfake scans | Deepfake and impersonation scan requests | Per plan tier |
| Velocity records | Velocity scoring action records | Per plan tier |
The pricing calculator on [truthlocks.com/pricing](https://www.truthlocks.com/pricing) includes sliders for agents, receipts, and all metered products so you can estimate costs before subscribing.
## Rate cards
Per-use rates for mints and verifications are:
| Operation | Rate |
| :--------------- | :---------------------- |
| Attestation mint | \$0.25 per mint |
| Verification | \$0.10 per verification |
Rates are visible in the console under **Settings > Billing > Usage**.
Rates were reduced by 50% in the March 2026 release. The previous rates were $0.50 per mint and $0.20 per verification.
### Custom rate cards for partners
Platform administrators can create custom rate cards with per-operation pricing for partner tenants. Use this to offer negotiated pricing to strategic partners or volume customers without changing your standard plan rates.
Each rate card defines unit prices for mints and verifications, and can be assigned to one or more tenants with an effective date.
#### Creating a rate card
Navigate to **Billing > Partnership Pricing** in the platform console and click **Create Rate Card**.
| Field | Description |
| :-------------- | :------------------------------------------------------------------ |
| **Name** | A descriptive name for the rate card (e.g. "Enterprise Partner Q1") |
| **Description** | Optional notes about the pricing agreement |
| **Mint rate** | Per-mint price in dollars (e.g. `0.15`) |
| **Verify rate** | Per-verification price in dollars (e.g. `0.05`) |
Rate cards are created as **active** by default. You can deactivate a rate card at any time from its detail page.
#### Assigning a rate card to a tenant
Open the rate card detail page and use the **Assign Tenant** form:
| Field | Description |
| :----------------- | :-------------------------------------- |
| **Tenant ID** | The UUID of the tenant to assign |
| **Effective from** | Start date for the custom pricing |
| **Effective to** | End date (leave blank for indefinite) |
| **Reason** | Internal note explaining the assignment |
A tenant can have only one active rate card at a time. Assigning a new card replaces the previous assignment.
#### Rate card types
Rate cards are classified automatically based on their properties:
| Type | Description |
| :----------- | :----------------------------------------------------------------------- |
| **Standard** | The default rate card applied to all tenants without a custom assignment |
| **Pilot** | A rate card marked for pilot programs or limited trials |
| **Custom** | Any rate card created for specific partner agreements |
Use the search bar on the Partnership Pricing page to filter rate cards by name or ID. The page also shows a count of active, standard, and pilot cards.
### Usage projections
The console usage page now includes a projected monthly spend estimate based on your current consumption rate and active rate card. Use this to forecast costs before the billing cycle closes.
Navigate to **Settings > Billing > Usage** to see your current usage alongside the projection.
## Entitlement quotas
Your plan determines the following quotas:
| Quota | Developer | Starter | Business | Institutional | Enterprise |
| :----------------------- | :--------- | :------------ | :-------- | :------------ | :--------- |
| Attestation mints | 500/month | Higher | Custom | Custom | Custom |
| Monthly verifications | Unlimited | Unlimited | Unlimited | Unlimited | Unlimited |
| Issuers | 1 | Multiple | Custom | Custom | Unlimited |
| Seats | 1 | Multiple | Custom | Custom | Custom |
| Signing keys | 1 | Multiple | Custom | Custom | Unlimited |
| Webhook endpoints | 1 | 3 | 10 | 25 | 25+ |
| Storage | 1 GB | Higher | Custom | Custom | Custom |
| API rate limit | 60 req/min | Higher | Custom | Custom | Custom |
| SSO & SCIM | — | — | Included | Included | Included |
| Private transparency log | — | — | — | Included | Optional |
| HSM integration | — | — | — | Included | Optional |
| Support SLA | Community | 48-hour email | 4-hour | 1-hour | Custom |
## Add-ons
You can attach add-ons to your plan for additional capabilities. Add-ons are billed separately and stack on top of your base plan entitlements.
| Add-on | Key | Base price | What it unlocks |
| :----------------- | :------------------- | :----------- | :---------------------------------------------------------------------------------------------------------------------- |
| Extra Seats | `addon_seat` | \$25/seat/mo | +1 team member per unit beyond your plan limit. Supports quantity — set the number of extra seats you need at checkout. |
| Priority SLA | `addon_sla_priority` | \$199/mo | Upgrade to 4-hour response time SLA |
| Private Log | `addon_private_log` | \$499/mo | Dedicated transparency log namespace |
| Compliance Pack | `addon_compliance` | \$299/mo | SOC 2, GDPR, and HIPAA compliance reporting |
| White-Label | `addon_whitelabel` | \$199/mo | Remove Truthlocks branding from verification pages |
| Rate Limit Boost | `addon_ratelimit` | \$149/mo | 10x default API rate limits |
| Extended Retention | `addon_retention` | \$99/mo | 10-year audit log retention (default is 2 years) |
Manage add-ons in the console at **Settings > Billing > Add-ons**. The add-ons marketplace shows all available add-ons with your regional price, a description, and a one-click attach button. Add-ons that support quantity (like Extra Seats) let you choose the number of units before purchasing.
You can also check your active add-ons and resolved entitlements via the API:
```bash theme={null}
curl https://api.truthlocks.com/v1/billing/entitlements \
-H "X-API-Key: tl_live_..."
```
```json theme={null}
{
"plan_key": "plan_starter",
"features": {
"online_verification": true,
"offline_bundles": true,
"custom_metadata": true,
"sso_scim": false
},
"quotas": {
"attestations.mint": 5000,
"seats": 4,
"api_rate_limit": 1200,
"storage_bytes": 10737418240,
"webhook_endpoints": 3
}
}
```
Pricing for add-ons adjusts automatically based on your region and payment provider. Free add-ons (like Extra Seats on Enterprise plans) activate immediately without a checkout step.
### Regional add-on pricing
Add-on prices are adjusted automatically based on your organization's country. The billing system groups countries into pricing tiers and applies a multiplier to the base price.
| Region | Multiplier | Countries |
| :------------- | :---------------- | :--------------------------------------------------------------------- |
| Tier 1 | 1.0x (full price) | US, GB, DE, FR, CA, AU, NL, CH, JP, SG, IE, IT, ES, SE, NO, DK, FI, NZ |
| LATAM | 0.7x | BR, MX, AR, CO, CL, PE |
| MENA | 0.8x | AE, SA, EG, IL, TR, ZA |
| Southeast Asia | 0.6x | ID, TH, VN, PH, MY |
| Africa | 0.5x | NG, KE, GH, TZ, UG, RW |
| South Asia | 0.5x | IN, PK, BD, LK |
For example, the Compliance Pack add-on at a base price of $299/month costs $149.50/month for a tenant in Nigeria (0.5x multiplier).
Regional multipliers also apply to per-use rates for mints and verifications. A tenant in India (0.5x) pays $0.125 per mint and $0.05 per verification instead of the standard $0.25 and $0.10 rates. You can check your effective rates with the [rates endpoint](/api-reference/billing/rates).
Use the country selector on the add-ons page to preview pricing for a specific region. The selector does not change your billing country — it only adjusts the displayed prices.
## Purchase order billing
Enterprise tenants can pay via purchase order as an alternative to credit card or regional payment providers.
Navigate to **Settings > Billing** and select the purchase order option.
Upload your PO document (PDF), enter the PO number, amount, and expiry
date.
The Truthlocks billing team reviews your PO. Once approved, your account
is activated and invoices are issued against the PO balance.
View PO status, remaining balance, and associated invoices from the
billing settings page.
Purchase order billing is available on the Enterprise plan. Contact your
account manager if you need PO-based payment on a different plan.
## Accounting export
Enterprise tenants can export their invoice history as CSV or JSON for accounting and reconciliation. Exports include invoice number, status, issue and due dates, amounts, tax, currency, and PO references. If no date range is provided, the export defaults to the last 30 days.
```bash theme={null}
curl "https://api.truthlocks.com/v1/billing/exports/accounting?format=csv&from=2026-01-01&to=2026-06-30" \
-H "X-API-Key: tl_live_..."
```
| Parameter | Type | Description |
| :-------- | :----- | :--------------------------------------------------------------------- |
| `format` | string | Export format: `csv` or `json`. Defaults to `csv`. |
| `from` | string | Start date (`YYYY-MM-DD`, e.g. `2026-01-01`). Defaults to 30 days ago. |
| `to` | string | End date (`YYYY-MM-DD`, e.g. `2026-06-30`). Defaults to today. |
The response streams the file directly. For CSV exports, the `Content-Type` is `text/csv` with a `Content-Disposition` header for download.
You can also export invoices from the console at **Settings > Billing > Invoices > Export**.
Accounting export is available on the Enterprise plan. The export includes all
invoices within the specified date range, including paid, open, and void
invoices.
## Payment failures and grace periods
If a payment fails, Truthlocks follows a graduated access workflow so you have time to resolve the issue before losing access. You can check your current billing status at any time via the [`GET /v1/billing/status`](/api-reference/billing/status) endpoint.
```bash theme={null}
curl https://api.truthlocks.com/v1/billing/status \
-H "X-API-Key: tl_live_..."
```
```json theme={null}
{
"status": "ACTIVE",
"feature_mode": "NORMAL",
"grace_until": null,
"banner": null
}
```
The billing status progresses through three stages when a payment fails:
| Stage | `feature_mode` | Default grace window | What happens |
| :------------- | :------------- | :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- |
| **Degraded** | `DEGRADED` | 7 days | Payment failed. A grace period begins and a banner appears in the console. All features remain available while you update your payment method. |
| **Restricted** | `RESTRICTED` | 14 days | Grace period is running out. Write operations (minting, key creation) are disabled. Read operations and verification continue to work. |
| **Suspended** | `SUSPENDED` | — | Grace period expired. All API access is disabled until payment is resolved. |
The `grace_until` field shows the ISO 8601 timestamp when the current grace period ends. Resolve the payment before this date to restore full access automatically. The grace windows above apply to the Standard contract mode — Enterprise and Government modes use longer windows. See [contract modes](#contract-modes) for details.
### Contract modes
How the dunning lifecycle behaves depends on the tenant's contract mode. By default, all tenants use the Standard mode, but platform administrators can switch a tenant to a different mode from the [billing operations console](/guides/billing-operations#dunning-overrides).
| Mode | Retries | Grace period | When to use |
| :------------------------ | :---------------------------------------------- | :--------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------- |
| **Standard (Auto)** | Automatic retries at T+24h, T+48h, T+72h | 7 days (Degraded) then 14 days (Restricted) before suspension | Self-serve tenants paying by credit card or regional payment provider |
| **Enterprise (Manual)** | No automatic retries — billing admin intervenes | 21 days (Degraded) then 28 days (Restricted) — standard windows plus 14 extra days | Enterprise accounts paying by wire transfer or purchase order |
| **Government (No Retry)** | No automatic retries | Fixed 90-day grace period; no automatic suspension | Government procurement workflows where payment timelines are outside your control |
The Standard mode sends up to three payment reminders at 24-hour, 48-hour, and 72-hour intervals after each stage transition. Enterprise and Government modes skip automatic retries entirely — a billing administrator must resolve the payment manually.
Contract mode changes are audit-logged and require a reason. See [dunning overrides](/guides/billing-operations#dunning-overrides) for instructions on changing a tenant's mode.
When using the [estimate endpoint](/api-reference/billing/estimate), you can pass `contract_mode` as `ENTERPRISE_CONTRACT` or `GOVERNMENT_PROCUREMENT` to get a plan recommendation that accounts for the contract type. Omitting this field defaults to `STANDARD_SELF_SERVE`.
Check `feature_mode` in your integration to surface upgrade or payment prompts
to your users before access is restricted. A `banner` message is included when
action is needed. See the [billing status API reference](/api-reference/billing/status) for full response details and usage examples.
## Managing billing
All billing settings are managed in the console at **Settings > Billing**. From there you can:
* View your current plan and entitlements
* Monitor usage counters and rate consumption
* Upgrade or downgrade your plan
* View and download invoices
* Export invoices for accounting (Enterprise)
* Submit purchase orders (for enterprise accounts)
* Attach or detach add-ons
## Checking limits via the API
Before performing a billable operation, you can check whether your current quota allows it:
```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/limits/check \
-H "X-API-Key: tl_live_..." \
-H "Content-Type: application/json" \
-d '{"metric": "attestations.mint", "amount": 1}'
```
The response indicates whether the operation is allowed under your current plan:
```json theme={null}
{
"allowed": true,
"used": 158,
"limit": 500,
"delta": 1
}
```
### Grace period extensions in limit checks
If your usage exceeds your plan limit but a platform administrator has granted a [grace period](/guides/billing-operations#grace-period-controls) for that metric, the response includes a `grace` object with the temporary allowance details:
```json theme={null}
{
"allowed": true,
"used": 510,
"limit": 500,
"grace": {
"active": true,
"amount": 100,
"expires_at": "2026-04-15T12:00:00Z"
},
"delta": 1
}
```
## Related
Subscribe, upgrade, attach add-ons, and cancel via the API.
How payments are routed by region.
Fetch available plan tiers with pricing and features.
Your effective per-use rates with regional adjustments.
Get a plan recommendation based on expected usage.
Check your billing health, feature mode, and grace period status.
Configuration, entitlements, checkout, subscription, and invoice endpoints.
Check your current billing cycle usage counters.
Refunds, credits, invoices, and PO review for platform admins.