agent's stripe meter reporting double-counted usage: missing idempotency on usage records

TL;DR

Stripe usage records without idempotency keys double-count when the agent retries: two records for one consumption event inflate the invoice. Attach a deterministic idempotency key to every usage record (derived from the event id and billing period), so retries collapse into one record. Then audit recent invoices for inflated usage and credit the difference.

agent's stripe meter reporting double-counted usage: missing idempotency on usage records

Use this when

• Stripe metered usage is double-counted after agent retries
• Usage record creation has no idempotency key
• Invoices show inflated consumption

Not for this skill when

• Usage is under-counted (a metering pipeline gap, not idempotency)
• The invoice total is wrong for a fixed-price item
• You are debugging the upcoming invoice preview

Steps

1. Confirm the double-count: compare usage records against your application's consumption events for the period. Expected: The duplication is proven.

2. Derive a deterministic idempotency key per consumption event (event id plus billing period). Expected: Every event maps to exactly one key.

3. Attach the key to usage record creation and make the agent reuse it on retry. Expected: Retries are idempotent.

4. Re-run the failed reporting path and confirm a single record per event. Expected: No duplicates are created.

5. Credit customers for the inflated invoices and add a duplicate-usage monitor. Expected: Past harm is repaired and future harm is caught.

6. Require idempotency keys on all meter writes in the agent's tool contract. Expected: The class of bug is closed.

Tool compatibility

Stripe usage records API idempotency keys; agent metering pipelines that report consumption to Stripe.

Variant phrasings

stripe usage records duplicate idempotency

The mechanism phrased as a fix.

agent meter double counting stripe

The agent-operations angle.

stripe metered billing duplicate usage records

The billing-symptom phrasing.

Why it happens

Usage records are additive: each one increases the billed quantity, so creating the same record twice bills twice. Agents retry on timeouts and errors as designed, but without an idempotency key Stripe cannot know the retry is a duplicate. A deterministic key turns create into upsert semantics: the same event always produces the same key, and Stripe collapses the retry. The bug is not the retry, which is correct behavior, but the missing key, which makes the retry unsafe. Guardrail: no meter write without a key.

Edge cases / pitfalls

• Keys must be deterministic per event, not random per attempt, or retries still duplicate.
• Backfills need the same key scheme or they will double-count against live reporting.
• Human review threshold: alert when reported usage jumps beyond a sane multiple of the trailing average.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_bHDeh1UYNOeJkUBQbHlQCA