This guide provides end-to-end instructions on how to migrate an existing line of credit (LOC) portfolio from your legacy system to Peach, i.e., preparing your data, creating borrowers and loans, populating historical records, executing the migration, and validating results.
LOC migration uses a statement-based approach. Historical data before the most recent statement date is stored as read-only snapshots. Data after that date is actively replayed by Peach's Loan Replay™ engine. This differs from installment loan migration, which recreates the full loan history from activation.
This page explains the concepts behind LOC migration. To run a migration, see the LOC migration procedure.
Before diving into the steps, it helps to understand how LOC migration compares to installment loan migration at a high level.
| Aspect | Installment loan | Line of credit |
|---|---|---|
| History handling | Full replay from activation date | Read-only history before cutoff; replay after |
| Object structure | Single loan object | Line (loan) + multiple draws + migration draw |
| Migration timing | Any time | Between statement date and due date |
| Balance calculation | Fully recalculated from scratch | Seeded from statement balances |
| Historical objects | Expected payments | Past periods, purchases, past transactions (optional — see note below) |
| Replay behavior | All events replayed chronologically | Only activities after cutoff date replayed |
Past periods, historical purchases, and past transactions are not required for migration to succeed. They are read-only objects that display the borrower's history for convenience and reference, but they do not affect balance calculations or loan behavior. It is possible to migrate a loan onto Peach with just the seed balances and overdue information, and the loan will start running as if it was just created with those balances. However, providing historical data is recommended for a complete borrower experience.
The key difference is the migration cutoff date. For LOCs, Peach does not recalculate balances from the beginning of the loan. Instead, you provide balance snapshots as of the most recent statement date, and Peach replays only the activity that occurred after that date. This makes LOC migration faster but requires accurate statement-date balances from your legacy system. You will also need very granular information about your draws — since Peach allows draws with different interest rates, fee structures, and configurations, you must provide balances broken down by draw so Peach knows which balance belongs to which draw.
These terms appear throughout the guide. Understanding them before you start will make each step clearer.
The loan period during which migration executes. It begins on the migration cutoff date (your most recent statement date) and ends on the last day of that billing cycle. This is the "live" period — Peach takes control of the loan starting from the migration period's start date.
Example: If your statement generates on the 1st of each month and payment is due on the 22nd:
- Previous period: Jul 1 – Jul 31 (statement date: Aug 1, due date: Aug 22)
- Migration period: Aug 1 – Aug 31 (statement date: Sep 1, due date: Sep 22)
Migration must complete before the previous period's due date that falls within the migration period. In this example, that means migration must finish before Aug 22. If it doesn't, the loan must be canceled and re-migrated. See Canceling and re-migrating loans for the recovery process.
What happens if you miss the migration deadline: If migration is not completed before the previous period's due date, there is currently no in-place recovery path. You must cancel the loan (clearing external IDs), then restart the migration process from the beginning. When you re-create the loan, the data from the original migration period moves into "past periods" (read-only history), and you set up a new migration period based on your next statement date. Note that there is no time limit on the prepMigration phase — you can remain in prepMigration for as long as needed while preparing your data. The deadline only applies to when you call the migrate endpoint.
The most recent statement date relative to the day you execute migration. This date divides all activity into two categories:
- Before the cutoff date → historical (read-only). Stored as past periods and past transactions.
- On or after the cutoff date → live. Replayed by Peach during migration.
All balances you provide to Peach must be accurate as of this date. The cutoff date is also the startDate of the migration period.
Balances should include interest accrued through the last day of the previous period (endDate) but should not include interest for the statement date itself. Peach's system will accrue interest for the statement date during the migration replay. If you include interest for the statement date in your seed balances, the consequence is double interest corresponding to that day.
When you create a line of credit with migrationStatus: "prepMigration", Peach automatically creates a special draw called the migration draw. This draw serves as a container for all historical activity that occurred before the migration cutoff date.
The migration draw has specific behaviors:
- All historical purchases are posted to this draw (with the
originalDrawIdfield referencing the actual legacy draw). - It does not accrue interest.
- It does not participate in the Loan Replay process.
- After migration completes, it transitions to
activestatus but is effectively disabled — no new activity can be posted to it. The API rejects requests targeting a static draw.
Static draw post-migration behavior: After migration completes, the migration draw receives active status but is functionally inert. It does not participate in fee caps or other calculations that aggregate across draws. All new activity (purchases, payments, fees) must be posted to the actual draws you create in Step 2.
Statement-cycle snapshots from your legacy system, covering the borrower's full history before the migration cutoff date. Each past period includes start/end dates, statement date, due date, and optionally a reference to the uploaded statement document.
Past periods are displayed in the borrower's history but are not replayed — they're read-only records.
Activity is categorized based on when it occurred relative to the migration cutoff date:
| Historical activity | Live activity | |
|---|---|---|
| When it occurred | Before migration cutoff date | On or after migration cutoff date |
| Where purchases go | Migration draw (with originalDrawId) | Actual draw |
| Transaction endpoint | POST .../migration/past-transaction | POST .../transactions (with isExternal: true) |
| Fee endpoint | POST .../fees (with migration.originalDrawId) | POST .../fees (normal) |
| Replayed by Peach? | No | Yes |
For LOC products with grace periods (common for credit cards), the isGracePeriodEligible field in the migration period data controls whether interest accrues during the migration period:
true→ No interest accrues during the migration period (borrower is in grace).false→ Interest begins accruing immediately from the cutoff date.
Grace eligibility is re-evaluated on the day after the due date within the migration period. This means the system checks whether the borrower paid the full statement balance by the due date, and updates grace status accordingly for the next period.
Edge case: If a draw is configured with numPeriodsToRestoreGrace greater than 1 (meaning the borrower must pay in full for multiple consecutive periods to regain grace), this rule is not enforced during the migration period. During migration, if the draw qualifies for grace based on the current period's payment, the system restores grace immediately — regardless of numPeriodsToRestoreGrace. This is by design: since Peach does not store per-draw grace history for past periods, it defaults to the behavior most favorable to the borrower. The numPeriodsToRestoreGrace rule takes full effect starting in the period after the migration period.
- LOC migration procedure — Run the migration these concepts support.
- How LOC billing cycles work — Period dates and balance-bucket movement.
- How grace periods work for lines of credit — Grace eligibility and the due-date-plus-one check.
- How LOC draws work — Draw types and the static migration draw.