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.
