Bill by usage with meters
v0.0.1
Usage-based billing charges a customer for what they used in a period: API calls, gigabytes, messages. With Stripe, a meter counts reports, a metered price bills the count, and Mishka Pay sends the reports and reads the totals. This guide makes a meter and a metered price, reports usage once, corrects a mistake and reads a summary. If your product runs on Mishka CMS, report usage under the tenant of the site that used it.
Before you begin
- Mishka Pay installed with a Stripe key. A sandbox is fine for everything here except the high-volume stream.
- A Stripe product to attach the price to. See Take a one-time payment for
create_product/1. - A customer with a
cus_id. Stripe takes nocustomer_accountyet for usage reports, summaries, entitlements and tax calculations, so a customer made on Accounts v2 (anacct_id) isErrors.Invalidon:customer_idhere. Make that customer withapi: :v1. See Save customers and cards, and open the billing portal. - The provider needs the
:usagecapability. Stripe has it. PayPal does not.
Make a meter
{:ok, meter} =
MishkaPay.create_meter(%{
provider: "stripe",
tenant: site.id,
name: "API calls",
event_name: "api_call",
aggregation: :sum
})aggregation is how a period's usage adds up: :sum of the values (the default), :count of the reports, or the :last value reported. The meter reads the customer from stripe_customer_id and the value from value in each report, which are Stripe's defaults.
A meter is never deleted. deactivate_meter/3 stops it taking usage or new prices, and reactivate_meter/3 turns it on again. update_meter/1 changes the display name only. List meters with list_meters("stripe", site.id, status: :active).
Make a metered price
A metered price is a recurring price with a meter_id. The amount is the price of one unit.
{:ok, price} =
MishkaPay.create_price(%{
provider: "stripe",
tenant: site.id,
product_id: product.id,
amount: %{amount: "0.01", currency: "USD"},
interval: :month,
meter_id: meter.id
})Each interval, the customer pays for the usage the meter counted. A customer subscribes to it like to any recurring price. See Sell and manage subscriptions.
Report usage
{:ok, usage} =
MishkaPay.report_usage(%{
provider: "stripe",
tenant: site.id,
event_name: "api_call",
customer_id: customer.id,
value: 3,
reference: "req-9f21"
})referencebecomes the report's identifier and its idempotency key, so a retry never counts twice. Stripe refuses a repeated identifier within at least 24 hours. Without a reference, Stripe makes one.atis when the usage happened. Stripe takes it within the last 35 days and up to 5 minutes ahead. Anything else isErrors.Invalidon:atbefore any request.valuemay have decimals. A value has at most 15 digits, at most 12 of them after the decimal point. A longer one isErrors.Invalidon:value. A negative value corrects usage reported by mistake.- Without
stream: true, a report goes to Stripe's meter events and is checked before Stripe answers.
Send high volume through the stream
Add stream: true to send a report through Stripe's meter event stream (API v2). It takes up to 10,000 reports a second.
MishkaPay.report_usage(%{
provider: "stripe",
tenant: site.id,
event_name: "api_call",
customer_id: customer.id,
value: 1,
stream: true
})The stream works in live mode only. Stripe answers a sandbox or test-mode key but counts nothing, so Mishka Pay refuses stream: true with such a key (Errors.Invalid on :stream) before any request. Report without it in a sandbox.
Stripe checks a streamed report after it answers. A wrong customer or event name is not an error in the answer. It arrives later as a v1.billing.meter.error_report_triggered or .no_meter_found thin event, which your own listener can take as a %MishkaPay.Event{} with object_type "billing.meter" and the meter as object_id. A site on snapshot events never gets it. See Receive and verify webhooks.
Take back a wrong report
{:ok, cancellation} =
MishkaPay.cancel_usage(%{
provider: "stripe",
tenant: site.id,
event_name: "api_call",
usage_id: usage.id
})
cancellation.status #=> :pending, then :completeA cancel works within 24 hours of the report and cancels once. Later than that, report the value again below zero.
Read a summary
{:ok, summary} =
MishkaPay.usage_summary(
"stripe",
meter.id,
customer.id,
from,
to,
site.id
)
summary.valueThe summary counts whole minutes: from rounds down and to rounds up. Stripe counts a report a little after it comes in, so a summary read at once may not show it yet.
Know the limits
Stripe's documentation now points new usage-based integrations to Metronome, its main usage billing platform, and says meters stay fully supported. Mishka Pay uses Stripe Billing Meters and has no Metronome calls.
Next steps
- Sell and manage subscriptions: put a customer on the metered price.
- Count tax, send invoices and issue credit notes: the bill a period of usage makes.
- Errors and telemetry: the codes a refused report returns.