v0.6.1

A small release that corrects the live credit figure and adds a way to read it from your backend. No database migration, and nothing to do when upgrading.

What was wrong

The public cost page shows a customer how much prepaid credit they have left (estimated_remaining_cents). In 0.5.0 and 0.6.0 that figure was wrong in five situations:

• After a billing-threshold invoice: usage the invoice had already taken from credit was subtracted a second time. The figure read too low, often zero.
• Around a trial: usage that is never billed was subtracted in some setups.
• Several subscriptions on different billing dates: one subscription's dates were applied to all of them.
• After a plan change in the middle of a period: usage from before the change was dropped.
• Credit past its expiry date: still counted for up to an hour.

For a customer with one ordinary subscription the figure was right. No invoice and no real balance was affected, only this estimate.

The figure now comes from the same calculation that builds the invoice, so what it subtracts is what the invoice will take.

What is new

• GET /v1/credits/balance/{customer_id}/live returns the live figure with a secret key: the credit a customer can spend, the usage not yet invoiced, and what is left.
• A guide: Stop usage when credit runs out. Poll the read on an interval, cache it, and check your cache before serving a request. Velox records usage and never refuses it, so the stop happens in your code.
• The cost page's credits object gains unbilled_usage_cents, so its three numbers add up.

Worth knowing

• The live read adds up the customer's usage for the period, so it takes longer as usage grows: about 0.2 seconds at 100,000 events and about 2 seconds at 1,000,000, measured on one laptop. Poll it; do not call it on every request.
• It is an estimate. It leaves out tax, a base fee billed at the end of the period, and unpaid invoices. The guide lists what it includes and what it does not.
• The credit.balance_low, credit.balance_depleted and credit.balance_recovered webhooks follow the settled balance, which moves when an invoice is issued. They do not follow usage. Webhooks on the live figure are tracked in #1019.

Every change, with its reasoning: CHANGELOG.