Deduplicate accounting events

Keeps repeated usage events from creating duplicate charges while retaining a reconstructable accounting history.

deduplication-accounting-integrity

See how it helps

When is it useful?

Use when webhooks or worker retries feed a usage or billing ledger.

What does it help you do?

Derives stable operation keys for repeat-safe event ingestion.
Preserves ledger entries and represents corrections as additional entries.
Separates raw events from summaries and uses exact monetary arithmetic.

Try asking this

Process the same usage event three times and record one charge with an auditable correction path. Redeliver the event after a simulated worker restart. The ledger should show one original charge and any later correction as a separate traceable entry.

Detailed documentation

Read the skill’s original instructions, examples and checks in their authored language.

Details…Show less

Deduplication & Accounting Integrity

Usage and cost ledgers require financial-grade accounting integrity. Retries, webhook replays, queue redeliveries, and crash recoveries must never inflate usage or silently drop consumption.

Workflow

Deterministic idempotency keys:
- Construct idempotency keys from stable business coordinates rather than random UUIDs generated at logging time:
  - LLM / external API call: {provider}:{providerRequestId} or {runId}:{stepIndex}:{attemptNumber}.
  - Queue job execution: {queueName}:{jobId}:{executionAttempt}.
  - Periodic storage snapshot: {tenantId}:{bucketId}:{windowStartIso}.
- Enforce a unique constraint (UNIQUE (tenant_id, idempotency_key)) at the database or ingestion layer and handle conflicts with idempotent upserts (ON CONFLICT DO NOTHING or upgrading 'estimated' to 'provider_reported').
Append-only immutable ledger:
- Never UPDATE or DELETE committed usage or cost ledger rows to fix a bug, apply a credit, or change a price.
- Record corrections, refunds, provider credits, or late invoice adjustments as compensating/adjustment ledger entries (entryType: 'raw_usage' | 'adjustment' | 'credit' | 'reconciliation_delta') referencing originalEventId with a reason code and timestamp.
Separate raw events from rollups:
- Keep the raw event table append-only as the single source of truth.
- Materialize hourly/daily/monthly rollups (usage_rollups_hourly, usage_rollups_daily) as derived projections that can be deterministically rebuilt from the raw event log.
- Track a watermark on rollups so late-arriving events trigger incremental recalculation of affected time buckets.
Integer and fixed-point arithmetic:
- Never use IEEE 754 floating-point (number / FLOAT / DOUBLE) to accumulate monetary costs.
- Store and sum costs in integer sub-cent units (nanodollars 10^-9 USD or microdollars 10^-6 USD using BIGINT / BigInt or NUMERIC(20, 9)) because per-token LLM prices underflow 2- or 4-decimal cent columns.

Anti-Patterns to Avoid

Random UUID idempotency keys: Generating crypto.randomUUID() inside the logger wrapper makes every retry look like a new event.
Rounding each event to cents (0.01): Rounding a $0.0004 LLM call before summing causes massive cumulative drift.
In-place backfills: Overwriting historical ledger rows without an audit trail makes it impossible to explain why past reported cost changed.

Included files 1

SKILL.md