Subscription management

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.

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/month in Nigeria (0.5x multiplier) instead of the

299 base price. See 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.

Getting Started

Guides

Trust & Compliance

Security

Operations

Enterprise Packs

Machine Identity (MAIP)

Risk & Fraud

Specification

SDKs

Prerequisites

Choose a plan

Estimate your costs

Check your current rates

Attach add-ons

Monitor usage

Open the billing portal

Cancel a subscription

Billing overview

Provider routing

Billing API reference

Entitlements

​Prerequisites

​Choose a plan

​Estimate your costs

​Check your current rates

​Subscribe to a plan

​Attach add-ons

​Monitor usage

​Open the billing portal

​Cancel a subscription

​Related

Billing overview

Provider routing

Billing API reference

Entitlements

Prerequisites

Choose a plan

Estimate your costs

Check your current rates

Subscribe to a plan

Attach add-ons

Monitor usage

Open the billing portal

Cancel a subscription

Related