Billing Service — Migration Plan

Status: populated Owner: Platform Engineering Last updated: 2026-04-18

1. Context

This service is new (greenfield). There is no predecessor service handling billing. The migration plan covers:

1. Schema creation and seed data.
2. NATS stream provisioning.
3. S3 bucket provisioning.
4. Cutover from "no billing" to live event ingestion.

2. Pre-Launch Checklist

• billing schema migrations applied to production PG (via CI migration pipeline).
• NATS stream BILLING_EVENTS created with durable consumer billing-consumer and AckWait=30s.
• S3 bucket ghasi-invoices created; SSE-KMS enabled; 7-year lifecycle policy set.
• Vault policy grants billing-service read on secret/billing/*.
• Initial pricing rules loaded for all active account tiers × active operators.
• Initial operator costs loaded for all active operators.

3. Phased Rollout

Phase	Duration	State
0. Deploy, observe	3 days	Deploy with NATS consumer disabled (feature flag BILLING_CONSUMER_ENABLED=false). REST API live but returns empty data.
1. Shadow ingest	1 week	Enable consumer; events ingested to billing_events; usage_summaries populated. Monitor pricing_not_found alerts. Fix any missing pricing rules.
2. First invoice run	End of month	Enable GenerateMonthlyInvoicesUseCase cron. Validate PDFs manually. Confirm S3 objects accessible.
3. Downstream consumers	After first invoice	Confirm billing.invoice.generated received by notification-service (invoice email) and customer-portal (invoice UI).
4. Full live	—	All paths operational; monitoring active.

4. Backfill Consideration

• Events from before launch cannot be backfilled (no historical billing.events in NATS; dlr-processor did not publish before this service existed).
• First invoice covers only the portion of the month during which the consumer was active.
• Finance team has been briefed on partial first month.

5. Rollback

• Feature flag BILLING_CONSUMER_ENABLED=false stops ingestion without removing the deployment.
• Schema rollback: destructive; only if pre-launch and no data in tables.
• No impact on sms-orchestrator or dlr-processor on rollback (they publish regardless of whether billing-service is consuming).

6. Risks

See SERVICE_RISK_REGISTER: R-BILL-05 (missing pricing rules at launch), R-BILL-06 (partial first invoice).