How does CMD+K forward usage meter events?
Every billable widget interaction enqueues a meter event to a Postgres queue (pgmq), a worker drains the queue with exponential backoff, and successful events POST to your billing destination. Failed events are retried up to 5 times before landing in a dead-letter queue you can inspect and replay. The pipeline is at-least-once and Stripe deduplicates by identifier — so duplicates are harmless.
Pipeline
- Widget finishes a turn; the chat server records cost and enqueues a meter event.
- A worker drains the
meter_eventsqueue every 5 seconds. - Each event POSTs to the configured destination (Stripe Meter Events today).
- Success → event marked delivered. Failure → re-queued with exponential backoff (10s, 30s, 2m, 10m, 30m).
- After 5 retries the event moves to the DLQ with the last error message.
Idempotency & deduplication
Each event carries a deterministic identifier derived from the chat turn ID. Stripe ignores duplicate identifiers, so the at-least-once pipeline can safely replay events without double-billing your end-users.
What counts as a billable event?
- Per turn — one event per assistant reply, regardless of tool calls.
- Per token — value = input + output tokens; ideal for token-based markup.
- Per character — value = output character count; simpler for non-technical buyers.
Pick the metering unit on each assistant's Monetize settings tab.
Next steps
FAQ
- How fast does usage appear in Stripe?
- Median latency is under 30 seconds. Worst case during retry is ~10 minutes (5 retries with exponential backoff).
- What if my Stripe key is invalid?
- Events fail-fast and route to the DLQ with the Stripe error message. Fix the key and click Replay on each DLQ batch.
- Can I throttle forwarding to stay under Stripe's rate limits?
- The worker respects Stripe's 100 rps limit per account automatically. No configuration needed.