Skip to content

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.

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 unknown and 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.
  1. Create a meter in Stripe (Billing → Meters) with aggregation Sum, customer mapping on stripe_customer_id and value key value. Price it per unit: one unit is one micro-USD of model cost.
  2. Create a restricted key with billing.meter_events: write and nothing else.
  3. Connect it to your organization as the stripe_meter_export integration 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.
  4. Map customers (admin key). Every customer you bill needs a mapping, even when your business_subject_ref already is a Stripe customer id:
Terminal window
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).

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_id only 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 as scope_mismatch and 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": true in the integration config, which bills a cus_… subject directly without a mapping.
Terminal window
# Counts and settled value by status: pending, in_flight, delivered, unknown,
# unmapped, scope_mismatch, failed, expired, skipped_zero
curl "$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 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:

Terminal window
# List them, with their identifiers
curl "$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 window
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": 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.

  • 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.