Stripe push beta

Available in beta on Pro and Ultra, at no extra cost. Set it up on your account page (no code needed) or with the API below. On Free, read monthly totals with the rollups API or CSV, or upgrade.

What it does

Usage Lab pushes each customer's month-to-date usage to your own Stripe account as Billing Meter events. Your Stripe subscriptions then bill from it. We only send the delta since the last push, so late events top the total up and nothing is double-counted.

Setup on your account page

1. In Stripe, create a Billing Meter with sum aggregation, payload keys stripe_customer_id and value.
2. Create a restricted key with Billing Meters read and Meter Events write. Paste it on /account/ under Stripe push. We check the permissions (list meters, plus a probe that records no usage) and show the result.
3. Pick a Usage Lab meter and the matching Stripe meter, and map each subscription id to a Stripe customer.
4. Click Preview to see what would be sent and what is skipped. Then turn on push and click Push now. Automatic pushes run every 15 minutes while push is on.

Setup with the API

1. In Stripe, create a Billing Meter with sum aggregation, payload keys stripe_customer_id and value.
2. Create a restricted key with Billing Meters read and Meter Events write, then store it. It is encrypted at rest (AES-GCM) and never returned:

   curl -X PUT https://usage-lab.pages.dev/api/v1/integrations/stripe \
     -H "Authorization: Bearer $USAGE_LAB_KEY" -H "Content-Type: application/json" \
     -d '{"restricted_key":"rk_test_..."}'

3. Map a meter to your Stripe event name, and each subscription id to a Stripe customer:

   curl -X PUT https://usage-lab.pages.dev/api/v1/integrations/stripe/meters \
     -H "Authorization: Bearer $USAGE_LAB_KEY" -H "Content-Type: application/json" \
     -d '{"meter":"llm_tokens","event_name":"llm_tokens"}'
   curl -X PUT https://usage-lab.pages.dev/api/v1/integrations/stripe/customers \
     -H "Authorization: Bearer $USAGE_LAB_KEY" -H "Content-Type: application/json" \
     -d '{"subscription":"acme","stripe_customer_id":"cus_..."}'

4. Turn push on (it is off by default):

   curl -X PUT https://usage-lab.pages.dev/api/v1/integrations/stripe/settings \
     -H "Authorization: Bearer $USAGE_LAB_KEY" -H "Content-Type: application/json" \
     -d '{"push_enabled":true}'

5. Preview, then push (pushes also run automatically every 15 minutes):

   curl -X POST "https://usage-lab.pages.dev/api/v1/integrations/stripe/push?dry_run=1" -H "Authorization: Bearer $USAGE_LAB_KEY"
   curl -X POST "https://usage-lab.pages.dev/api/v1/integrations/stripe/push" -H "Authorization: Bearer $USAGE_LAB_KEY"
   curl "https://usage-lab.pages.dev/api/v1/integrations/stripe/log" -H "Authorization: Bearer $USAGE_LAB_KEY"

Retry safety and limits

• Each push window (account, meter, customer, month, from-to quantity) gets a deterministic identifier. If a push is retried, Stripe rejects the duplicate and we record it as already pushed.
• Stripe accepts meter events up to 35 days old. We push the current and previous month only while they are inside that window; older windows are skipped.
• Negative corrections (usage that went down) are not pushed yet; they show as skipped_negative_delta in the preview.
• Subscriptions without a customer mapping are skipped and shown in the preview.
• Your Stripe meters, for building a mapping: GET /api/v1/integrations/stripe/meters/remote. Disconnect with DELETE /api/v1/integrations/stripe; the stored key is deleted.
• Beta: tested end to end against Stripe test mode. Tell us about rough edges at canada.site.ops@gmail.com.

Related: Stripe Billing Meters vs a usage ledger · API docs