Stripe meter export
Hosted Agent FinOps can send the settled cost of every attributed model call to your own Stripe account as a billing meter event. Use the meter to bill AI usage (cost plus your markup), to set upgrade points, or only to see margin per customer next to revenue.
The export is part of the hosted product. The open-source SDK does not call Stripe.
What is sent
Section titled “What is sent”One meter event per settled call that carries a customer (business_subject_ref):
| Field | Value |
|---|---|
event_name |
The meter you configure |
payload[stripe_customer_id] |
Your Stripe customer for that business_subject_ref |
payload[value] |
Settled cost in micro-USD (integer; 1000000 = $1.00) |
identifier |
kz_<reservation_id> |
timestamp |
When the call settled |
- Calls without a
business_subject_ref, and calls that settled at $0 (for example a provider refusal), are not sent. - Calls still pending reconciliation are sent once they settle.
- Each settled call has one delivery, held by one worker at a time. Every attempt
is recorded before Stripe is called, and a resend reuses the same Stripe
idempotency key and
identifier, so a retry within Stripe’s 24-hour window cannot create a second event. - If an earlier attempt may have reached Stripe and a resend would fall outside
that window, the delivery is marked
unknownand is not sent again automatically. You check Stripe and reconcile it (below). - Stripe accepts events up to 35 days old, so a call that could not be delivered
within that window is marked
expired. - Admission and settlement never wait for Stripe. A Stripe outage only delays meter events.
Set it up
Section titled “Set it up”- Create a meter in Stripe (Billing → Meters) with aggregation Sum,
customer mapping on
stripe_customer_idand value keyvalue. Price it per unit: one unit is one micro-USD of model cost. - Create a restricted key with
billing.meter_events: writeand nothing else. - Connect it to your organization as the
stripe_meter_exportintegration with{"api_key": "rk_…", "event_name": "<your meter>"}. During onboarding we do this with you; the key is stored encrypted per organization and never returned by any API. - Map customers (admin key). Every customer you bill needs a mapping, even
when your
business_subject_refalready is a Stripe customer id:
curl -X PUT "$FINOPS/v1/org/$ORG/billing-export/customers/acct-42" \ -H "X-API-Key: $ADMIN_KEY" -H "Content-Type: application/json" \ -d '{"stripe_customer_id": "cus_Q1a2b3c4d5", "workspace_id": "prod-api"}'Calls for a customer with no mapping wait as unmapped and are sent as soon as
you add the mapping. workspace_id is optional (see below).
Who can be billed
Section titled “Who can be billed”The business_subject_ref on a call comes from your application through the SDK,
so on its own it never decides who is billed. Only the mapping an organization
admin creates does.
- A call naming a subject with no mapping is never sent, even if the subject looks like a Stripe customer id.
- A mapping with
workspace_idonly bills calls reserved in that workspace. The workspace is the one the calling API key is bound to, not a value in the call. Calls from another workspace are held asscope_mismatchand never sent; the retry endpoint does not release them, changing the mapping does. - A workspace is the billing trust boundary: any key in a workspace can name any subject mapped for that workspace. Give each customer-facing service its own workspace when one service must not be able to bill another’s customers.
- Single-tenant deployments where every key is trusted can set
"trust_client_customer_ids": truein the integration config, which bills acus_…subject directly without a mapping.
Check and retry
Section titled “Check and retry”# Counts and settled value by status: pending, in_flight, delivered, unknown,# unmapped, scope_mismatch, failed, expired, skipped_zerocurl "$FINOPS/v1/org/$ORG/billing-export/status" -H "X-API-Key: $KEY"
# Re-queue failed and unmapped deliveries still inside Stripe's 35-day window (admin).# Never re-queues unknown deliveries.curl -X POST "$FINOPS/v1/org/$ORG/billing-export/retry" -H "X-API-Key: $ADMIN_KEY"Unknown deliveries
Section titled “Unknown deliveries”unknown means Stripe may already have the event: an attempt’s result was never
recorded (for example the worker stopped mid-call), or retries ran out on server
or network errors. Resolve each one after searching your meter’s events in Stripe
for its identifier:
# List them, with their identifierscurl "$FINOPS/v1/org/$ORG/billing-export/deliveries?status=unknown" -H "X-API-Key: $KEY"
# Found in Stripe: record it as delivered (it is never resent)curl -X POST "$FINOPS/v1/org/$ORG/billing-export/deliveries/$ID/reconcile" \ -H "X-API-Key: $ADMIN_KEY" -H "Content-Type: application/json" \ -d '{"stripe_event_present": true, "note": "kz_rsv_123 found in meter events"}'
# Not in Stripe: send it again with a fresh idempotency windowcurl -X POST "$FINOPS/v1/org/$ORG/billing-export/deliveries/$ID/reconcile" \ -H "X-API-Key: $ADMIN_KEY" -H "Content-Type: application/json" \ -d '{"stripe_event_present": false, "note": "searched meter events for kz_rsv_123"}'Who reconciled each delivery, when, and their note are kept with it.
Rate limits (HTTP 429) and Stripe server errors are retried with backoff; if
they keep failing the delivery becomes unknown. Errors where Stripe refuses
the event, such as an unknown customer or meter or a revoked key, mark it
failed with Stripe’s message until you fix the cause and retry.
Limits
Section titled “Limits”- Cost is Agent FinOps’ settled amount from the provider-reported usage and the price table. It is not your provider invoice.
- Agent FinOps does not create Stripe customers, prices or invoices, and does not charge your users. Your billing setup stays the source of truth.
