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 no customer_account yet for usage reports, summaries, entitlements and tax calculations, so a customer made on Accounts v2 (an acct_ id) is Errors.Invalid on :customer_id here. Make that customer with api: :v1. See Save customers and cards, and open the billing portal.
  • The provider needs the :usage capability. Stripe has it. PayPal does not.

Make a meter

elixir
{: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.

elixir
{: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

elixir
{:ok, usage} =
  MishkaPay.report_usage(%{
    provider: "stripe",
    tenant: site.id,
    event_name: "api_call",
    customer_id: customer.id,
    value: 3,
    reference: "req-9f21"
  })
  • reference becomes 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.
  • at is when the usage happened. Stripe takes it within the last 35 days and up to 5 minutes ahead. Anything else is Errors.Invalid on :at before any request.
  • value may have decimals. A value has at most 15 digits, at most 12 of them after the decimal point. A longer one is Errors.Invalid on :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.

elixir
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

elixir
{:ok, cancellation} =
  MishkaPay.cancel_usage(%{
    provider: "stripe",
    tenant: site.id,
    event_name: "api_call",
    usage_id: usage.id
  })

cancellation.status   #=> :pending, then :complete

A cancel works within 24 hours of the report and cancels once. Later than that, report the value again below zero.

Read a summary

elixir
{:ok, summary} =
  MishkaPay.usage_summary(
    "stripe",
    meter.id,
    customer.id,
    from,
    to,
    site.id
  )

summary.value

The 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