Integrate Ledger

Ledger’s public API uses one organization-scoped secret key. Keep it on your application backend. The dashboard is for organization owners; your end customers should never see the Ledger key.

Sign up at dashboard.integrateledger.com and copy the generated API key.
Configure your application’s Checkout success and cancel URLs in the Checkout page.
Connect your Stripe test secret key in the Stripe page. Ledger configures its signed webhook endpoint and syncs paid plans.
Publish a sandbox catalog in the Catalog page, or call PUT /v1/catalog with the JSON shown below.

{
  "schemaVersion": 1,
  "environment": "sandbox",
  "currency": "usd",
  "plans": [
    {
      "id": "starter",
      "name": "Starter",
      "monthlyCredits": 100,
      "monthlyPriceCents": 1900
    },
    {
      "id": "pro",
      "name": "Pro",
      "monthlyCredits": 500,
      "monthlyPriceCents": 4900
    }
  ],
  "features": [{ "id": "api_call", "name": "API call", "creditCost": 1 }],
  "addOns": [
    {
      "id": "extra_credits",
      "name": "Extra credits",
      "type": "credit_pack",
      "creditAmount": 50,
      "priceCents": 500
    }
  ],
  "policy": { "onInsufficientCredits": "block" }
}

Use your Ledger API key in Authorization: Bearer <LEDGER_API_KEY> for every request below. Send JSON with Content-Type: application/json.

Step	Request body	What to do with the response
`POST /v1/customers`	`{ "customerId": "your-user-123" }`	Use your application’s stable customer ID. Repeating the request is safe.
`POST /v1/billing/attach`	`{ "customerId": "your-user-123", "planId": "starter" }`	Redirect the customer to `checkoutUrl`. Credits appear only after Stripe’s paid invoice webhook.
`POST /v1/check`	`{ "customerId": "your-user-123", "featureId": "api_call" }`	Run the feature only when `allowed` is true.
`POST /v1/track`	`{ "customerId": "your-user-123", "featureId": "api_call", "request_id": "unique-operation-id" }`	Record successful use with a unique request ID. Retrying the same ID does not charge again.
`POST /v1/billing/attach`	`{ "customerId": "your-user-123", "addOnId": "extra_credits" }`	Redirect to the credit pack’s `checkoutUrl` when more credits are needed.
`POST /v1/billing/upgrade`	`{ "customerId": "your-user-123", "planId": "pro" }`	Include a unique `Idempotency-Key` header. If `paymentUrl` is returned, send the customer to Stripe’s hosted invoice page. Ledger applies the upgrade after payment and Stripe confirmation.

/v1/check does not reserve credits. /v1/track makes its own fresh decision, so your app must handle 409 insufficient_credits even after an allowed check. Show the user a plan upgrade or credit pack when either endpoint reports insufficient credits. Never call track from an untrusted browser with the Ledger key. The complete request and response schemas are available at /openapi.json, and the generated TypeScript SDK is in packages/sdk.

Getting started

Concepts

About

Integrate Ledger