Billing Catalog Operations

Source of truth

Catalog runtime data is normalized across billing catalog tables with version snapshots.

Core tables:

• billing_catalogs
• billing_catalog_versions
• billing_catalog_plans
• billing_catalog_variants
• billing_catalog_discounts

Checkout safety rules

createCheckout validates:

1. planKey exists
2. variantId belongs to the plan and matches mode (if provided)
3. ambiguous multi-variant selection is rejected when no variantId is provided
4. custom: true variants are not purchasable

Admin API

• GET /admin/billing/catalog
• GET /admin/billing/catalog/versions
• PUT /admin/billing/catalog

Operational guidance

• apply catalog updates in small auditable steps
• preserve variant IDs to avoid provider/webhook correlation drift
• validate staging checkout and webhook paths after catalog edits

Legacy source reference: docs/guides/billing-catalog-operations.md