Documentation
¶
Overview ¶
Command backfill-events replays commerce's EXISTING subscriptions, invoices, and api-usage transactions into the analytics collector (commerce.events) as lifecycle events — so admin.hanzo.ai's warehouse-backed billing views show real HISTORY, not just events emitted from now on.
It is IDEMPOTENT: every event carries a deterministic id derived from the immutable source record (see billing.BackfillEventID), so a re-run recomputes the SAME id per (entity, lifecycle-transition) and never double-counts.
Usage:
backfill-events # DRY-RUN every org (default), emits nothing
backfill-events --org acme # DRY-RUN one org
backfill-events --since 2026-01-01T00:00:00Z # bound the window
# real emit (per-org first), after the collector is deployed:
COMMERCE_BACKFILL_ALLOW=true backfill-events --org acme \
--dry-run=false --endpoint http://analytics-collector.hanzo.svc:8091
Like cmd/grant, it bootstraps the same datastore commerce uses at runtime (commerce.App.Bootstrap) then calls billing.BackfillEvents directly. --dry-run defaults ON; a live emit additionally requires --endpoint (or ANALYTICS_ENDPOINT) and COMMERCE_BACKFILL_ALLOW=true so it can never fire against the wrong env by accident.
Source Files