Skip to main content
POST
cURL
Pass customerId with exactly one of planId or addOnId. Use your application’s stable customer ID, and create the customer first with Create or get a customer. Your API key selects Sandbox or Live. Paid live Checkout requires live activation and Ledger’s live-charge gate; see Sandbox and live environments. Paid Checkout requires a stored Stripe connection with both a webhook signing secret and endpoint ID. If the webhook setup is incomplete, Ledger returns 502 stripe_not_configured before creating a chargeable link. Free plans do not require Stripe.

Response and credit timing

A free plan returns subscriptionId and status: "active" immediately, without Stripe or a Checkout URL. The first monthly allowance is available at once. Repeating the same attach returns the same subscription without granting twice. A paid plan returns subscriptionId and checkoutUrl. Ledger activates the plan and grants its allowance only after a verified paid Stripe invoice webhook. A credit pack returns addOnPurchaseId and checkoutUrl; Ledger grants its credits after a signed, paid Checkout completion webhook. A browser redirect alone does not grant credits. An active free plan can start a paid plan Checkout. Its remaining allowance stays available while Checkout is open. After the verified paid invoice arrives, the remaining free plan allowance expires and the paid allowance begins. Previously purchased credit packs stay available. A failed or abandoned Checkout leaves the free plan active.

Retrying Checkout

Retrying the same pending paid plan or credit pack returns its existing open Checkout URL. If that Stripe session has expired, Ledger closes the pending attempt and creates a new Checkout on the next attach. Returning to your cancelUrl does not itself expire the Stripe session; the open link remains resumable until Stripe expires it. 409 subscription_exists means this customer already has an incompatible active or pending plan. 409 purchase_pending means a different credit pack Checkout is pending. See the billing guide for the complete lifecycle.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
customerId
string
required
Required string length: 1 - 255
planId
string
required
Required string length: 1 - 255

Response

Pending Stripe Checkout for a paid item, or an active free plan

checkoutUrl
string<uri>
required
subscriptionId
integer
required