Migration workflow

The migration is a Stripe-only state machine. Each step produces artifacts consumed by later steps.

1. Source inventory

Reads products, prices, Billing Meters, customers, subscription items, default payment indicators, tax flags, collection methods, discounts, and schedules.

Outputs:

• inventory-source/source-inventory.json
• inventory-source/source-inventory-summary.md

2. Plan and classify

Classifies subscriptions into automatic candidates, manual-review rows, and ignored historical rows.

The planner uses the configured minimum start buffer. The default is 48h, intentionally stricter than Stripe's toolkit minimum, because customer-copy timing and operator review often take real time.

Manual-review buckets include:

• near renewal
• past due
• cancel at period end
• trialing or unexpected status
• missing payment default
• discounts or coupons
• manual tax rates or unsupported collection settings
• existing schedules
• unexpected item shapes

3. Destination preflight

Checks destination account reachability for products, prices, meters, customers, payment methods, subscription schedules, subscriptions, and invoice previews.

4. Destination catalog

Plans or applies destination products, prices, and Billing Meters.

Destination writes store source IDs in metadata and use idempotency keys so reruns can reuse existing objects.

5. Customer copy and verification

Generates the customer-copy CSV for Stripe's customer copy flow. After Stripe copies customers/payment methods, verification checks:

• destination customer exists
• email presence/mismatch
• default payment method/default source
• attached card PaymentMethod/Source counts

Optional payment-default repair can set invoice_settings.default_payment_method when exactly one attached card PaymentMethod exists.

6. Tax preview

Uses Stripe's non-persistent invoice preview API with destination prices and target subscription settings.

A successful preview shows Stripe could calculate the invoice. It is not legal or tax advice.

7. Subscription migration

Two output paths are supported:

• Stripe Billing migration toolkit CSV
• Direct API-created destination subscription schedules

Direct schedules use source current_period_end as the destination schedule start and default to proration_behavior=none.

8. Schedule verification

Retrieves each destination schedule and checks customer, start date, metadata, prices, phase settings, collection method, proration behavior, and status.

Source cancellation is blocked if any verification issue remains.

9. Source cancel at period end

The final source write sets cancel_at_period_end=true on verified source subscriptions.

The runner re-checks source account identity, source customer, status, and current period end before planning or applying updates.