Billing System - Truthlocks Documentation

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 for details.

Plan Tiers

Developer

For hobbyists and proof-of-concept projects. Includes online verification and community support at no cost.

Starter

For SMBs and startups with production workloads. Higher quotas, up to 3 webhook endpoints, and priority processing.

Business

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.

Institutional

For large enterprises with advanced security needs. Private transparency log, HSM integration, and a 1-hour support SLA.

Enterprise

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.
Multi-provider routing — payments are processed through the optimal gateway for your region. See provider routing for details.

Metered products

Truthlocks meters 16 products organized into four categories. You can see all of them on the pricing page 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 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:

curl https://api.truthlocks.com/v1/billing/entitlements \
  -H "X-API-Key: tl_live_..."

{
  "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.

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.

Submit a purchase order

Navigate to Settings > Billing and select the purchase order option. Upload your PO document (PDF), enter the PO number, amount, and expiry date.

Review and activation

The Truthlocks billing team reviews your PO. Once approved, your account is activated and invoices are issued against the PO balance.

Track PO status

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.

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 endpoint.

curl https://api.truthlocks.com/v1/billing/status \
  -H "X-API-Key: tl_live_..."

{
  "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 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.

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 for instructions on changing a tenant’s mode.

When using the estimate endpoint, 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 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:

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:

{
  "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 for that metric, the response includes a grace object with the temporary allowance details:

{
  "allowed": true,
  "used": 510,
  "limit": 500,
  "grace": {
    "active": true,
    "amount": 100,
    "expires_at": "2026-04-15T12:00:00Z"
  },
  "delta": 1
}

Subscription management

Subscribe, upgrade, attach add-ons, and cancel via the API.

Provider routing

How payments are routed by region.

List plans

Fetch available plan tiers with pricing and features.

Get rates

Your effective per-use rates with regional adjustments.

Estimate costs

Get a plan recommendation based on expected usage.

Billing status API

Check your billing health, feature mode, and grace period status.

Billing API reference

Configuration, entitlements, checkout, subscription, and invoice endpoints.

Usage API

Check your current billing cycle usage counters.

Billing operations

Refunds, credits, invoices, and PO review for platform admins.

​Plan tiers

​Plan Tiers

Developer

Starter

Business

Institutional

Enterprise

​Core concepts

​Metered products

​Core

​MAIP (Machine Identity)

​AI

​Anti-Fraud

​Rate cards

​Custom rate cards for partners

​Creating a rate card

​Assigning a rate card to a tenant

​Rate card types

​Usage projections

​Entitlement quotas

​Add-ons

​Regional add-on pricing

​Purchase order billing

​Accounting export

​Payment failures and grace periods

​Contract modes

​Managing billing

​Checking limits via the API

​Grace period extensions in limit checks

​Related

Subscription management

Provider routing

List plans

Get rates

Estimate costs

Billing status API

Billing API reference

Usage API

Billing operations

Plan tiers

Plan Tiers

Core concepts

Metered products

Core

MAIP (Machine Identity)

AI

Anti-Fraud

Rate cards

Custom rate cards for partners

Creating a rate card

Assigning a rate card to a tenant

Rate card types

Usage projections

Entitlement quotas

Add-ons

Regional add-on pricing

Purchase order billing

Accounting export

Payment failures and grace periods

Contract modes

Managing billing

Checking limits via the API

Grace period extensions in limit checks

Related