Idempotency

Send an Idempotency-Key header on usage tracking and supported billing mutations.

Choose a key that identifies one business operation, not one HTTP attempt:

invoice:inv_123:refund:attempt_1
job:job_456:feature:api_requests
subscription:sub_789:change:pro

When a request times out, retry with the same key and identical payload. Usagey replays the stored response. If the payload changes, Usagey rejects the request with HTTP 409.

Keys are scoped to a billing workspace and route, so Sandbox and Production cannot replay one another's writes.

Authenticated operator and customer-portal subscription creation, cancellation, reactivation, and plan changes bind the idempotency lock, local subscription mutation, and developer-event record to one workspace transaction. A failed local mutation therefore cannot leave behind a successful idempotency response. Provider calls may complete before a local transaction fails, so provider webhooks and reconciliation remain the source of recovery for that external boundary.

Operator and customer-portal checkout creation use the same transaction-bound key. Checkout confirmation also scopes the provider reference to the authenticated portal customer before contacting the provider. Replaying a successful credit-pack confirmation returns the stored response and cannot add credits twice.

Refund creation and failed-refund retry use the same rule. Refund eligibility, duplicate-pending checks, balance reversal, parent and child transaction updates, retry linkage, developer events, and the stored response share one transaction. Reusing the same key cannot dispatch a second local refund workflow.