Customers

Use your application’s stable user ID as Ledger’s customerId. Your API key selects Sandbox or Live, and the records are separate. POST /v1/customers is create-or-get: calling it again returns created: false and does not grant credits. The dashboard Customers page shows the selected environment’s current balance, subscriptions, add-on purchases, and recent usage.

Start a plan

Create a paid plan and connect the selected environment’s Stripe account before calling POST /v1/billing/attach with planId. Live paid Checkout also requires live activation and Ledger’s live-charge gate. Redirect the customer to the returned checkoutUrl. The plan is pending until Ledger processes the paid Stripe invoice webhook, which creates the monthly credit allocation.

curl --request POST https://api.integrateledger.com/v1/customers \
  -H "Authorization: Bearer $LEDGER_API_KEY" -H "Content-Type: application/json" \
  --data '{"customerId":"user_123"}'

curl --request POST https://api.integrateledger.com/v1/billing/attach \
  -H "Authorization: Bearer $LEDGER_API_KEY" -H "Content-Type: application/json" \
  --data '{"customerId":"user_123","planId":"starter"}'

Sell a credit pack

Send addOnId instead of planId to the same endpoint. Ledger grants pack credits after the paid Checkout webhook. A customer may buy multiple packs over time.

curl --request POST https://api.integrateledger.com/v1/billing/attach \
  -H "Authorization: Bearer $LEDGER_API_KEY" -H "Content-Type: application/json" \
  --data '{"customerId":"user_123","addOnId":"extra_credits"}'

attach is safe to retry while the same Checkout is pending; a different pending purchase or an existing subscription can return a conflict. Check the returned status and use the same customer and item ID for retries.

Upgrade a paid plan

POST /v1/billing/upgrade requires an Idempotency-Key header. If paymentUrl is returned, send the customer there. Ledger changes the plan after Stripe confirms payment.

curl --request POST https://api.integrateledger.com/v1/billing/upgrade \
  -H "Authorization: Bearer $LEDGER_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: upgrade_user_123_pro" \
  --data '{"customerId":"user_123","planId":"pro"}'

See Billing and Checkout for Stripe setup and webhook timing.

Getting started

Concepts

About

Start a plan

Sell a credit pack

Upgrade a paid plan

​Start a plan

​Sell a credit pack

​Upgrade a paid plan

Start a plan

Sell a credit pack

Upgrade a paid plan