> ## 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.
# Subscription management
> Choose a plan, subscribe via checkout, manage add-ons, and handle cancellation using the API or console.
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](/api-reference/api-keys/create) 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.
```bash theme={null}
curl https://api.truthlocks.com/v1/billing/plans
```
```json theme={null}
[
{
"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](/billing/overview#plan-tiers) 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.
```bash theme={null}
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](/api-reference/billing/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:
```bash theme={null}
curl https://api.truthlocks.com/v1/billing/rates \
-H "X-API-Key: tl_live_..."
```
The response includes base rates and any regional pricing adjustments:
```json theme={null}
{
"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.
Call the checkout endpoint with the plan you want and redirect URLs:
```bash theme={null}
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.
Send the user to the `checkout_url` to complete payment.
```javascript theme={null}
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;
```
After payment, verify the subscription is active:
```bash theme={null}
curl https://api.truthlocks.com/v1/billing/subscription \
-H "X-API-Key: tl_live_..."
```
```json theme={null}
{
"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](/billing/provider-routing) for details.
## Attach add-ons
Add-ons extend your plan with extra capabilities. Attach them via the API:
```bash theme={null}
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/month in Nigeria (0.5x multiplier) instead of the $299 base price. See [regional add-on pricing](/billing/overview#regional-add-on-pricing) for the full tier table.
To remove an add-on:
```bash theme={null}
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](/api-reference/billing/addons) for the full add-on catalog and response details.
## Monitor usage
Track your current billing cycle consumption to stay within your plan limits:
```bash theme={null}
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:
```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}'
```
## Open the billing portal
Redirect users to their payment provider's self-service portal to update payment methods, view invoices, or manage their subscription:
```bash theme={null}
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.
```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/billing/cancel \
-H "X-API-Key: tl_live_..."
```
```json theme={null}
{
"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](/api-reference/billing/checkout).
You cannot undo a cancellation via the API. To resume your subscription, you need to go through checkout again.
## Related
Plan tiers, rates, entitlements, and add-ons.
How payments are routed by region.
Full billing API endpoint reference.
Check your active features and quotas.