Skip to main content

Migration Plan

:::info Source Sourced from services/billing-service/MIGRATION_PLAN.md in the documentation repo. :::

1. Core Rules​

  • Billing ACL (F19) frozen M2 start; processor-specific code behind ACL; events vendor-agnostic.
  • Invoice schema (F21) frozen M2 start; additive.
  • Money unit: micro-units + ISO4217; never change.
  • Tax retention: 7 years minimum; cannot be shortened.

2. Database Evolution​

  • Additive columns nullable.
  • Money columns always BIGINT in micro-units.
  • New currencies: additive.
  • Partition invoices + payments by year for efficient archival.

3. API Evolution​

  • URL major on breaking.
  • Payment intent API stable.
  • Invoice format additive.

4. Event Evolution​

EventvPolicy
billing.payment.succeeded.v1v1Additive
billing.invoice.paid.v1v1Additive
billing.subscription.changed.v1v1State enum additive

5. Processor Migration​

  • Billing ACL abstracts processor. Currently Stripe.
  • Adding secondary processor (e.g., Adyen):
    • Implement ACL implementation.
    • Migration: per-tenant gradual rollout.
    • Old payments remain on old processor; new on new.
    • Reconciliation per-processor.

6. Tax Provider Migration​

  • Stripe Tax → TaxJar (or vice versa): ACL change.
  • Historical tax calculations remain on original provider.
  • New calculations use new provider.

7. Subscription Plan Evolution​

  • Plans identified by ID; renames are display-only.
  • Deprecated plans: no new subscriptions; existing continue.
  • Plan change within subscription: pro-rated; new plan at next period boundary.

8. Currency Addition​

  • Add to supported currencies list.
  • Existing invoices unchanged (original currency).
  • New invoices can use new currency if tenant supports.

9. Payout Migration​

  • Payout method change per provider: coordinated with tenant.
  • Provider account portability: KYC re-verification may be required.

10. Data Residency​

  • Customer records pinned to tenant homeRegion.
  • Migration follows residency saga.
  • Stripe customer IDs regional (Stripe has multi-region support).

11. GDPR​

  • Anonymize customer PII on erasure.
  • Retain invoice/payment records per tax law.
  • Audit log of erasure + retention rationale.

12. Changelog​

Per-release: new currencies, new plan kinds, processor version updates, tax rate changes.