For large portfolio migrations, follow these operational best practices.
If migrating a large portfolio, segment it into batches. Start small and increase batch size as you gain confidence:
- Start with 50 loans — validate thoroughly
- Increase to 100, then 250, then 500 — monitor for patterns
- Scale to your target batch size once the process is stable
Group loans with similar attributes in each batch:
- Current loans together
- Delinquent loans together
- Loans with promo programs together
- Loans with specific fee configurations together
This makes it easier to identify reconciliation patterns. For example, if all loans in a "delinquent" batch show a consistent DPD offset, you can diagnose the root cause once and apply the fix to the entire batch.
There is no hard limit on batch size in production, but we recommend monitoring migration completion times and adjusting batch sizes based on your throughput requirements.
Set muteLoanNotices: true on loan creation to prevent notifications during migration. This avoids confusing borrowers with messages like payment reminders or balance alerts while data is still being set up.
Re-enable communications only after:
- Migration has succeeded
- Balances have been validated
- Autopay has been configured (if applicable)
- You're ready to sunset the legacy system's communications for that borrower
During migration, both your legacy system and Peach can operate simultaneously. This allows for thorough testing and validation without disrupting your business.
If a loan was migrated incorrectly and cannot be fixed with adjustments, you can cancel it and re-migrate. This is also the recovery path if you miss the migration period due date — the loan must be canceled and re-created with a new migration period aligned to your next statement date.
Option A — Clear all external IDs automatically (up to 1,000 objects):
POST /api/people/{personId}/loans/{loanId}/cancel?clearAllExternalIds=trueThis clears external IDs on the loan, all its draws (including the migration draw, which is auto-canceled), transactions, purchases, and fees — up to 1,000 objects total. If your loan has more than 1,000 associated objects, use Option B.
Option B — Manual cleanup for large loans (> 1,000 objects):
- Cancel each draw individually, clearing its external IDs.
- Cancel the loan with
clearAllExternalIds=truefor the remaining objects.
After cancellation:
- Create a new loan with the original external ID and repeat the migration process.
- If you need to adjust data on the canceled loan before re-migrating (e.g., convert migration period data to a past period, reclassify live activities as past activities), you can update the canceled loan's data first.
Canceled loans do not appear on loan tapes. The clearAllExternalIds parameter frees up external IDs for re-use on the corrected loan without requiring manual changes.
- LOC migration procedure — The migration process to repeat after re-migration.
- LOC migration validation and troubleshooting — Diagnose issues before deciding to re-migrate.