Billing lifecycle

Ledger runs billing through your Stripe account and treats Stripe’s signed webhooks as the only proof of payment. Your backend asks for a plan or pack with attach; Ledger grants credits when Stripe says the money arrived.

​

From attach to credits

The redirect back to your success URL happens at about the same time as the webhook, but it proves nothing: anyone can open that URL. Read the customer from your backend, or refresh your billing page, once the webhook has landed.

​

What attach does

A saved card is the default payment method on the customer’s Stripe customer. When Ledger charges it, the response arrives after Stripe has confirmed the invoice, so the credits are already there. A declined card creates no subscription, and the customer can attach again. A card that needs 3-D Secure isn’t charged off-session: attach returns a checkoutUrl for the same subscription, and the customer authenticates on Checkout. Attaching the same plan or pack again while its Checkout is open returns the same checkoutUrl, so retries are safe. Once Stripe expires an unpaid Checkout (after 24 hours), the next attach opens a new one.

​

Subscription statuses

List customer subscriptions returns each subscription’s status:

​

Renewals

Stripe renews paid plans every month. Ledger grants the new period’s credits when Stripe creates the renewal invoice, about an hour before it charges the card, so a customer isn’t stuck at zero while the payment goes through. If Stripe voids that invoice, the credits it granted end. Free plans renew in Ledger, at the same time of day each month from when they started. The previous period’s allowance expires at the period’s end, whether or not it was spent.

​

Plan changes

An upgrade charges the full new price now and starts a new period; the old plan’s unspent credits stay until the old period would have ended, and are spent first. A downgrade starts the cheaper plan at the next renewal by default, or now with prorated credits. Cancelling at period end keeps the plan and its credits until the paid period ends. Ledger doesn’t refund a cancellation; cancelling immediately is done in Stripe, and Ledger follows Stripe’s customer.subscription.deleted event.

​

Refunds and disputes

Refund and dispute payments in Stripe. Ledger follows Stripe’s signed events, and changes credits only for a credit pack refunded in full or lost to a dispute. The dashboard’s customer page lists the customer’s refunds and disputes, with what each did to credits. Canceling a subscription in Stripe ends the plan as cancellation does.

​

Credit packs

A pack’s credits are granted when Stripe’s signed checkout.session.completed event confirms the payment. Stripe also sends the customer an invoice for the pack, with a line such as “Top-up – 500 credits”. The invoice never grants the credits a second time.

​

When something goes wrong

Errors lists every code.

​

Next steps