Migration Guide
Use this guide when moving existing customers, subscriptions, invoices, or usage workflows into Floatless.
Migration should be treated as an operational project, not just a data import.
Migration phases
| Phase | Goal |
|---|---|
| Inventory | Identify existing products, prices, customers, subscriptions, invoices, credits, and payment methods. |
| Mapping | Decide how old system objects map to Floatless objects. |
| Test import | Import a small sample into test mode and validate invoices. |
| Parallel run | Compare old system output with Floatless bill run preview. |
| Cutover | Stop writes in the old system and start production billing in Floatless. |
| Reconciliation | Compare invoices, payments, credits, and reports after first live cycle. |
Data to prepare
- Product catalog.
- Price list and billing periods.
- Customer records and billing contacts.
- Active subscriptions and line items.
- Next billing dates and current service periods.
- Open invoices and balances.
- Credits, refunds, and customer credit balances.
- Saved payment method references where available.
- Metered usage history required for the next bill run.
Mapping checklist
| Source data | Floatless destination |
|---|---|
| Plan or SKU | Product |
| Price or rate card | Product price / pricing model |
| Account or company | Customer |
| Recurring contract | Subscription |
| Usage ledger | Usage records |
| Open bill | Invoice |
| Credit balance | Customer credit or credit memo |
Cutover checklist
- Freeze billing changes in the old system.
- Export final source data.
- Import or configure products and customers.
- Import active subscriptions with correct next billing dates.
- Recreate open invoice balances where needed.
- Run bill run preview.
- Compare preview totals to old system expectations.
- Enable production payment collection and webhooks.
- Execute first production bill run.
Migration risks
| Risk | Mitigation |
|---|---|
| Duplicate invoices | Track already-billed periods and validate next billing dates. |
| Missing credits | Import credit balances and open credit memos before first bill run. |
| Incorrect tax | Test representative customer locations before cutover. |
| Usage gaps | Freeze usage ingestion and import final usage before billing. |
| Payment method mismatch | Confirm gateway customer/payment method references. |