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.
You can manage your entire billing lifecycle through the API or the console. This guide covers how to list plans, estimate costs, create a checkout session, check your subscription, attach add-ons, and cancel when needed.
Prerequisites
A Truthlocks account with an active tenant.
An API key with billing permissions. See API keys to create one.
Choose a plan Truthlocks offers five plan tiers. Use the plans endpoint to fetch the full catalog — this is a public endpoint and does not require authentication.
curl https://api.truthlocks.com/v1/billing/plans
[ { "key" : "plan_developer" , "name" : "Developer" , "price" : 0 , "currency" : "USD" , "interval" : "month" , "features" : [ "500 mints/month" , "Unlimited verifications" , "Community support" ], "highlight" : false }, { "key" : "plan_starter" , "name" : "Starter" , "price" : 29 , "currency" : "USD" , "interval" : "month" , "features" : [ "Higher quotas" , "3 webhook endpoints" , "Priority processing" ], "highlight" : true } ]
See billing overview for a comparison of all plans.
Estimate your costs Before subscribing, use the estimate endpoint to get a plan recommendation based on your expected usage. This is also a public endpoint.
curl -X POST https://api.truthlocks.com/v1/billing/estimate \ -H "Content-Type: application/json" \ -d '{ "country_code": "US", "expected_verifications_monthly": 10000, "team_seats": 5, "webhook_endpoints_needed": 5, "storage_gb": 10 }'
The response includes a recommended plan and estimated monthly total. For a line-item cost breakdown, use the projected invoice endpoint instead.
Check your current rates Your tenant’s effective per-use rates depend on your rate card and region. Fetch them with:
curl https://api.truthlocks.com/v1/billing/rates \ -H "X-API-Key: tl_live_..."
The response includes base rates and any regional pricing adjustments:
{ "rate_card" : { "id" : "rc_default" , "name" : "Standard Rates" , "currency" : "USD" }, "items" : [ { "metric" : "attestations.mint" , "unit_price" : 25 , "volume_min" : 0 , "volume_max" : 0 }, { "metric" : "verifications" , "unit_price" : 10 , "volume_min" : 0 , "volume_max" : 0 } ], "is_default" : true , "regional_rates" : { "region" : "TIER_1" , "multiplier" : 1.0 , "mint_rate_cents" : 25 , "verify_rate_cents" : 10 } }
If your organization has a custom rate card assigned by a platform admin, those rates appear here instead of the defaults.
Subscribe to a plan Create a checkout session to start or upgrade your subscription. The billing service selects the correct payment provider for your region automatically.
Create a checkout session
Call the checkout endpoint with the plan you want and redirect URLs: curl -X POST https://api.truthlocks.com/v1/billing/checkout \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "plan_key": "STARTER", "success_url": "https://yourapp.com/billing?success=true", "cancel_url": "https://yourapp.com/billing?canceled=true" }'
The response contains a checkout_url hosted by the payment provider.
Redirect to checkout
Send the user to the checkout_url to complete payment. const res = await fetch ( "https://api.truthlocks.com/v1/billing/checkout" , { method: "POST" , headers: { "X-API-Key" : "tl_live_..." , "Content-Type" : "application/json" , }, body: JSON . stringify ({ plan_key: "STARTER" , success_url: ` ${ window . location . origin } /billing?success=true` , cancel_url: ` ${ window . location . origin } /billing?canceled=true` , }), }); const { checkout_url } = await res . json (); window . location . href = checkout_url ;
Confirm the subscription
After payment, verify the subscription is active: curl https://api.truthlocks.com/v1/billing/subscription \ -H "X-API-Key: tl_live_..."
{ "status" : "active" , "plan_key" : "plan_starter" , "current_period_end" : "2026-05-01T00:00:00Z" , "cancel_at_period_end" : false }
You can optionally pass a provider parameter (stripe, paystack, or flutterwave) to override automatic region-based routing. See provider routing for details. Attach add-ons Add-ons extend your plan with extra capabilities. Attach them via the API:
curl -X POST https://api.truthlocks.com/v1/billing/addons/attach \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "addon_key": "addon_seat", "quantity": 2 }'
If the add-on has a price, the response includes a checkout_url to complete payment. Free add-ons activate immediately.
Add-on prices adjust automatically based on your organization’s billing country. Tenants in lower-cost regions pay a reduced rate — for example, the Compliance Pack costs 149.50 / m o n t h i n N i g e r i a ( 0.5 x m u l t i p l i e r ) i n s t e a d o f t h e 149.50/month in Nigeria (0.5x multiplier) instead of the 149.50/ m o n t hin N i g er ia ( 0.5 x m u lt i pl i er ) in s t e a d o f t h e regional add-on pricing for the full tier table. To remove an add-on:
curl -X POST https://api.truthlocks.com/v1/billing/addons/detach \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{"addon_key": "addon_seat"}'
See manage add-ons for the full add-on catalog and response details.
Monitor usage Track your current billing cycle consumption to stay within your plan limits:
curl https://api.truthlocks.com/v1/billing/usage \ -H "X-API-Key: tl_live_..."
To check whether a specific operation is within quota before performing 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}'
Open the billing portal Redirect users to their payment provider’s self-service portal to update payment methods, view invoices, or manage their subscription:
curl -X POST https://api.truthlocks.com/v1/billing/portal \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "return_url": "https://yourapp.com/settings/billing" }'
The response includes a portal_url. Redirect the user to that URL. Portal sessions expire quickly, so generate a fresh URL each time.
Cancel a subscription To cancel, call the cancel endpoint. The cancellation takes effect at the end of the current billing period — you keep full access until then.
curl -X POST https://api.truthlocks.com/v1/billing/cancel \ -H "X-API-Key: tl_live_..."
{ "status" : "active" , "plan_key" : "plan_starter" , "current_period_end" : "2026-05-01T00:00:00Z" , "cancel_at_period_end" : true }
After the period ends, your account downgrades to the Developer (free) plan. To resubscribe, create a new checkout session .
You cannot undo a cancellation via the API. To resume your subscription, you need to go through checkout again.
Billing overview Plan tiers, rates, entitlements, and add-ons.
Provider routing How payments are routed by region.
Billing API reference Full billing API endpoint reference.
Entitlements Check your active features and quotas.
