# Create migration period draw data This endpoint allows you to pass additional details about draws in preparation for migration. The "migration period" is the period in which you execute the migration. This is the period from which the Peach system takes control over the line. This period is considered to be "open" at the time of the migration. The migration needs to be completed before the upcoming due date. To clarify, the upcoming due date corresponds to the previous period's statement date. The "Migration cutoff date" is the most recent statement date relative to the day on which you execute the migration process. This date is also the `startDate` of the migration period. The "Migration at date" is the actual date on which you execute the migration. For example: - Migration period: - startDate: Aug 1, 2024 - endDate: Aug 31, 2024 - statementDate: Sep 1, 2024 - dueDate: Sep 22, 2024 - Previous period (also called 'past period'): - startDate: Jul 1, 2024 - endDate: Jul 31, 2024 - statementDate: Aug 1, 2024 - dueDate: Aug 22, 2024 - Notes: - 'Migration cutoff date' is Aug 1, 2024. - If you execute the migration on Aug 10, 2024, the 'migration at date' is Aug 10. - Previous period's `dueDate`, Aug 22, 2024, falls in the 'migration period' that starts on Aug 1, 2024 and ends on Aug 31, 2024. - The upcoming due date is Aug 22, 2024. - If you didn't complete the migration before Aug 22, 2024, you need to cancel the loan and start the process again. Endpoint: POST /people/{personId}/loans/{loanId}/draws/{drawId}/migration/period Version: 2025-03-26 Security: oauth2, bearerAuth, apiKeyHeader ## Path parameters: - `personId` (string, required) A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier. - `loanId` (string, required) The unique identifier of the Loan we wish to retrieve. Can be Peach or lender's external identifier. - `drawId` (string, required) The draw identifier. ## Request fields (application/json): - `balances` (object, required) The draw level balances passed here should be as of the "migration cutoff date" after the most recent statement was generated in your legal system. We expect `balances` to include interest FOR the last date of the previous period (aka endDate) but not for the most recent statement date (which is also the first day of the migration period). For example: - Migration period: - startDate: Aug 1, 2024 - endDate: Aug 31, 2024 - statementDate: Sep 1, 2024 - dueDate: Sep 22, 2024 - Previous period (also called "past period"): - startDate: Jul 1, 2024 - endDate: Jul 31, 2024 - statementDate: Aug 1, 2024 - dueDate: Aug 22, 2024 - Notes: - The balances should be as of Aug 1, 2024 after the statement was generated on Aug 1, 2024. - End of day principal balance on Jul 31, 2024: $100.00. - The line/draw accrues daily simple interest of 18% annually (with 360 method). - The balances passed to Peach should include the daily interest that was accrued at the end of the day Jul 31, 2024: - $100.00 * (0.18 / 360) = $0.05 - Peach system will accrue daily interest for the end of the day Aug 1, 2024 day balance and onward. Do not double-count fees: a fee you charge on the regular (non-static) draw that it belongs to with a charge date on or after the "migration cutoff date" writes itself to the ledger. For any such fee, either include its amount in these balances OR charge it through the fees endpoint; never both, or the borrower will be billed twice. - `balances.creditLimitAmount` (number) The draw credit limit amount as of the "migration cutoff date". - `balances.dueBalances` (object, required) Due balances represent balances that are currently due. - `balances.dueBalances.dueDrawFeesAmount` (number, required) The draw fees portion of `dueFeesAmount`. - `balances.dueBalances.dueInterestAmount` (number, required) The interest portion of the `dueTotalAmount`. - `balances.dueBalances.dueLateFeesAmount` (number, required) The late fees portion of `dueFeesAmount`. - `balances.dueBalances.dueModificationFeesAmount` (number, required) The modification fees portion of `dueFeesAmount`. - `balances.dueBalances.duePrincipalAmount` (number, required) The principal portion of the `dueTotalAmount`. - `balances.nonDueBalances` (object, required) Non-due balances represent balances that are not yet due. - `balances.nonDueBalances.nonDueDrawFeesAmount` (number, required) The draw fees portion of `nonDueFeesAmount`. - `balances.nonDueBalances.nonDueInterestAmount` (number, required) The interest portion of the `nonDueTotalAmount`. - `balances.nonDueBalances.nonDueLateFeesAmount` (number, required) The late fees portion of `nonDueFeesAmount`. - `balances.nonDueBalances.nonDueModificationFeesAmount` (number, required) The modification fees portion of `nonDueFeesAmount`. - `balances.nonDueBalances.nonDuePrincipalAmount` (number, required) The principal portion of the `nonDueTotalAmount`. - `balances.overdueBalances` (object, required) Overdue balances represent balances that are overdue. - `balances.overdueBalances.overdueDrawFeesAmount` (number, required) The draw fees portion of `overdueFeesAmount`. - `balances.overdueBalances.overdueInterestAmount` (number, required) The overdue interest portion of the `overdueTotalAmount`. - `balances.overdueBalances.overdueLateFeesAmount` (number, required) The late fees portion of `overdueFeesAmount`. - `balances.overdueBalances.overdueModificationFeesAmount` (number, required) The modification fees portion of `overdueFeesAmount`. - `balances.overdueBalances.overduePrincipalAmount` (number, required) The overdue principal portion of the `overdueTotalAmount`. - `gracePeriod` (object, required) If you are not migrating past periods and the migration period is the first period of the LOC: Don't pass the `gracePeriod` object. If you are migrating past periods: This is the draw level grace period details. The draw level grace period data passed here corresponds to the previous period and not to the migration period. By the time you call this endpoint, you should have already created one or more past periods. The additional data that you pass here is only required for the previous period and not for all past periods. That's why the draw level grace period data is part of the "Create migration period draw data" vs "Create past periods data" endpoint. The migration period is a "live" period in which you execute migration. - Because the Peach system needs to know if the LOC is eligible for the grace period benefit when the migration period starts, the system will use the `isGracePeriodEligible` passed here. If you pass `isGracePeriodEligible=true`, the system will start migration without accruing interest in the "migration period". If you pass `isGracePeriodEligible=false`, the system will start migration with accruing interest in the "migration period". - On the "due date + 1" within the "migration period", the system evaluates the grace eligibility based on `fullBalanceAmount`, `fullBalanceMinusOverdueAmount` and payments made. - If you migrate the LOC/draw before the upcoming "due date", the system will evaluate the grace period eligibility in "live" and might revoke the benefit. - If you migrate the LOC/draw after the "due date", the system will evaluate the grace period eligibility as part of the "replay/migration" process. Because of existing limitations with "replay", grace period eligibility cannot be revoked as part of the replay process. However, the replay process can reinstate the grace period benefit (in other words, waive accrued interest from the start of the "migration period"). - Peach is responsible for generating the statement corresponding to the migration period on `migrationPeriod.statementDate` in the future. The grace period details of the migration period will be calculated by the Peach system on `migrationPeriod.statementDate` in the future. For example: - Migration period: - startDate: Aug 1, 2024 - endDate: Aug 31, 2024 - statementDate: Sep 1, 2024 - dueDate: Sep 22, 2024 - Previous period (also called "past period"): - startDate: Jul 1, 2024 - endDate: Jul 31, 2024 - statementDate: Aug 1, 2024 - dueDate: Aug 22, 2024 - Notes: - The draw level grace period details that you need to pass correspond to the previous period that started on Jul 1, 2024 and ended on Jul 31, 2024. - The amounts and values should be as of the "migration cutoff date", Aug 1, 2024, after the statement was finalized in your legacy system. - `gracePeriod.fullBalanceAmount` (number, required) The full balance amount of the line that is eligible for grace period. - `gracePeriod.fullBalanceMinusOverdueAmount` (number, required) The full balance amount minus the overdue amount. - `gracePeriod.isGracePeriodEligible` (boolean) Was the loan eligible for grace in this period? - `obligation` (object, required) If you are not migrating past periods and the migration period is the first period of the LOC: Don't pass the `obligation` object. If you are migrating past periods: This is the draw level obligation details. The draw level data passed here corresponds to the previous period and not to the migration period. By the time you call this endpoint, you should have already created one or more past periods. The additional data that you pass here is only required for the previous period and not for all past periods. That's why the draw level obligation data is part of the "Create migration period draw data" vs "Create past periods" endpoint. To remind, the migration period is a "live" period in which you execute migration. The draw level obligation details of the migration period will be calculated by the Peach system. Peach is also responsible for generating the statement corresponding to the migration period on `migrationPeriod.statementDate` in the future. For example: - Migration period: - startDate: Aug 1, 2024 - endDate: Aug 31, 2024 - statementDate: Sep 1, 2024 - dueDate: Sep 22, 2024 - Previous period (also called "past period"): - startDate: Jul 1, 2024 - endDate: Jul 31, 2024 - statementDate: Aug 1, 2024 - dueDate: Aug 22, 2024 - Notes: - The draw level obligation details that you need to pass correspond to the previous period that started on Jul 1, 2024 and ended on Jul 31, 2024. - The amounts and other values should be as of the "migration cutoff date", Aug 1, 2024, after the statement was finalized in your legacy system. - `obligation.migratedDaysOverdue` (integer, required) This represents the number of days overdue prior to the "migration cutoff" date as it appears in the other system (not Peach). This value is normally calculated as the number of calendar days overdue starting from the earliest overdue obligation's due date to the "migration cutoff date". This value, once set, won't change after the migration. This value will be prorated and added to `daysOverdue` of future obligations (if any become overdue). The system will prorate the `migratedDaysOverdue` dynamically as the borrower makes payments and add it to the days overdue post "migration cutoff date". Calculation details: - The `migratedDaysOverdue` value will be used to prorate days overdue prior to the "migration cutoff date" based on the paid balance of `migratedOverdueAmount` (which is set based on the `balances.overdueBalances`). - round_down [migratedDaysOverdue x (1 - min(fulfilledAmount / migratedOverdueAmount, 1))] - For example: - migratedDaysOverdue = 60 - migratedOverdueAmount = $1000 - Scenario 1: - Borrower didn't make any payment within the first 30 days after the "migration cutoff date". - Total days overdue: - 60 x (1 - min(0 / 1000, 1)) + 30 = 90 - Scenario 2: - Borrower made payments in a total amount of $700 within the first 30 days after the "migration cutoff date". The line is still overdue. - Total days overdue: - 60 x (1 - min(700 / 1000, 1)) + 30 = 48 - `obligation.obligationAmount` (number, required) The remaining amount of the previous period's obligation that a borrower needs to pay on the due date that comes after "migration cutoff date". The remaining amount should be as of "migration cutoff date" vs. "migration at date". This is the draw level remaining obligation amount. If your LOC (or credit card) product doesn't count payments that were made before the statement date towards the statement minimum amount, then `obligationAmount` must be always equal to the draw portion of the whole statement minimum amount. Example: - Migration period: - startDate: Aug 1, 2024 - endDate: Aug 31, 2024 - statementDate: Sep 1, 2024 - dueDate: Sep 22, 2024 - Previous period (also called "past period"): - startDate: Jul 1, 2024 - endDate: Jul 31, 2024 - statementDate: Aug 1, 2024 - dueDate: Aug 22, 2024 Scenario 1: - The draw minimum payment was calculated as $100 on the statement date on Aug 1, 2024. - A borrower made some payments in the previous period, and based on your waterfall configuration in the legacy system, $30 was counted towards the $100 minimum amount. - The remaining minimum amount of $70 is due on Aug 22, 2024. - You should pass `obligationAmount=70`. Scenario 2: - The draw minimum payment was calculated as $100 on the statement date on Aug 1, 2024. - A borrower made some payments in the previous period, and based on your waterfall configuration in the legacy system, none of the payments were counted toward the $100 minimum amount. - The minimum amount of $100 is due on Aug 22, 2024. - You should pass `obligationAmount=100`. Scenario 3: - The draw minimum payment was calculated as $100 on the statement date on Aug 1, 2024. - A borrower made early payments in the previous period, and based on your waterfall configuration in the legacy system, the payments were counted toward the $100 minimum amount. - The remaining minimum amount of $0 is due on Aug 22, 2024 (in other words, the borrower doesn't need to pay anything on Aug 22, 2024.) - You should pass `obligationAmount=0`. ## Response 201 fields (application/json): - `message` (string) Description of the server action or error. - `status` (integer) HTTP status code. - `data` (object) - `data.balances` (object) The draw level balances passed here should be as of the "migration cutoff date" after the most recent statement was generated in your legal system. We expect `balances` to include interest FOR the last date of the previous period (aka endDate) but not for the most recent statement date (which is also the first day of the migration period). For example: - Migration period: - startDate: Aug 1, 2024 - endDate: Aug 31, 2024 - statementDate: Sep 1, 2024 - dueDate: Sep 22, 2024 - Previous period (also called "past period"): - startDate: Jul 1, 2024 - endDate: Jul 31, 2024 - statementDate: Aug 1, 2024 - dueDate: Aug 22, 2024 - Notes: - The balances should be as of Aug 1, 2024 after the statement was generated on Aug 1, 2024. - End of day principal balance on Jul 31, 2024: $100.00. - The line/draw accrues daily simple interest of 18% annually (with 360 method). - The balances passed to Peach should include the daily interest that was accrued at the end of the day Jul 31, 2024: - $100.00 * (0.18 / 360) = $0.05 - Peach system will accrue daily interest for the end of the day Aug 1, 2024 day balance and onward. Do not double-count fees: a fee you charge on the regular (non-static) draw that it belongs to with a charge date on or after the "migration cutoff date" writes itself to the ledger. For any such fee, either include its amount in these balances OR charge it through the fees endpoint; never both, or the borrower will be billed twice. - `data.balances.creditLimitAmount` (number) The draw credit limit amount as of the "migration cutoff date". - `data.balances.dueBalances` (object, required) Due balances represent balances that are currently due. - `data.balances.dueBalances.dueDrawFeesAmount` (number, required) The draw fees portion of `dueFeesAmount`. - `data.balances.dueBalances.dueInterestAmount` (number, required) The interest portion of the `dueTotalAmount`. - `data.balances.dueBalances.dueLateFeesAmount` (number, required) The late fees portion of `dueFeesAmount`. - `data.balances.dueBalances.dueModificationFeesAmount` (number, required) The modification fees portion of `dueFeesAmount`. - `data.balances.dueBalances.duePrincipalAmount` (number, required) The principal portion of the `dueTotalAmount`. - `data.balances.nonDueBalances` (object, required) Non-due balances represent balances that are not yet due. - `data.balances.nonDueBalances.nonDueDrawFeesAmount` (number, required) The draw fees portion of `nonDueFeesAmount`. - `data.balances.nonDueBalances.nonDueInterestAmount` (number, required) The interest portion of the `nonDueTotalAmount`. - `data.balances.nonDueBalances.nonDueLateFeesAmount` (number, required) The late fees portion of `nonDueFeesAmount`. - `data.balances.nonDueBalances.nonDueModificationFeesAmount` (number, required) The modification fees portion of `nonDueFeesAmount`. - `data.balances.nonDueBalances.nonDuePrincipalAmount` (number, required) The principal portion of the `nonDueTotalAmount`. - `data.balances.overdueBalances` (object, required) Overdue balances represent balances that are overdue. - `data.balances.overdueBalances.overdueDrawFeesAmount` (number, required) The draw fees portion of `overdueFeesAmount`. - `data.balances.overdueBalances.overdueInterestAmount` (number, required) The overdue interest portion of the `overdueTotalAmount`. - `data.balances.overdueBalances.overdueLateFeesAmount` (number, required) The late fees portion of `overdueFeesAmount`. - `data.balances.overdueBalances.overdueModificationFeesAmount` (number, required) The modification fees portion of `overdueFeesAmount`. - `data.balances.overdueBalances.overduePrincipalAmount` (number, required) The overdue principal portion of the `overdueTotalAmount`. - `data.gracePeriod` (object) If you are not migrating past periods and the migration period is the first period of the LOC: Don't pass the `gracePeriod` object. If you are migrating past periods: This is the draw level grace period details. The draw level grace period data passed here corresponds to the previous period and not to the migration period. By the time you call this endpoint, you should have already created one or more past periods. The additional data that you pass here is only required for the previous period and not for all past periods. That's why the draw level grace period data is part of the "Create migration period draw data" vs "Create past periods data" endpoint. The migration period is a "live" period in which you execute migration. - Because the Peach system needs to know if the LOC is eligible for the grace period benefit when the migration period starts, the system will use the `isGracePeriodEligible` passed here. If you pass `isGracePeriodEligible=true`, the system will start migration without accruing interest in the "migration period". If you pass `isGracePeriodEligible=false`, the system will start migration with accruing interest in the "migration period". - On the "due date + 1" within the "migration period", the system evaluates the grace eligibility based on `fullBalanceAmount`, `fullBalanceMinusOverdueAmount` and payments made. - If you migrate the LOC/draw before the upcoming "due date", the system will evaluate the grace period eligibility in "live" and might revoke the benefit. - If you migrate the LOC/draw after the "due date", the system will evaluate the grace period eligibility as part of the "replay/migration" process. Because of existing limitations with "replay", grace period eligibility cannot be revoked as part of the replay process. However, the replay process can reinstate the grace period benefit (in other words, waive accrued interest from the start of the "migration period"). - Peach is responsible for generating the statement corresponding to the migration period on `migrationPeriod.statementDate` in the future. The grace period details of the migration period will be calculated by the Peach system on `migrationPeriod.statementDate` in the future. For example: - Migration period: - startDate: Aug 1, 2024 - endDate: Aug 31, 2024 - statementDate: Sep 1, 2024 - dueDate: Sep 22, 2024 - Previous period (also called "past period"): - startDate: Jul 1, 2024 - endDate: Jul 31, 2024 - statementDate: Aug 1, 2024 - dueDate: Aug 22, 2024 - Notes: - The draw level grace period details that you need to pass correspond to the previous period that started on Jul 1, 2024 and ended on Jul 31, 2024. - The amounts and values should be as of the "migration cutoff date", Aug 1, 2024, after the statement was finalized in your legacy system. - `data.gracePeriod.fullBalanceAmount` (number, required) The full balance amount of the line that is eligible for grace period. - `data.gracePeriod.fullBalanceMinusOverdueAmount` (number, required) The full balance amount minus the overdue amount. - `data.gracePeriod.isGracePeriodEligible` (boolean) Was the loan eligible for grace in this period? - `data.obligation` (object) If you are not migrating past periods and the migration period is the first period of the LOC: Don't pass the `obligation` object. If you are migrating past periods: This is the draw level obligation details. The draw level data passed here corresponds to the previous period and not to the migration period. By the time you call this endpoint, you should have already created one or more past periods. The additional data that you pass here is only required for the previous period and not for all past periods. That's why the draw level obligation data is part of the "Create migration period draw data" vs "Create past periods" endpoint. To remind, the migration period is a "live" period in which you execute migration. The draw level obligation details of the migration period will be calculated by the Peach system. Peach is also responsible for generating the statement corresponding to the migration period on `migrationPeriod.statementDate` in the future. For example: - Migration period: - startDate: Aug 1, 2024 - endDate: Aug 31, 2024 - statementDate: Sep 1, 2024 - dueDate: Sep 22, 2024 - Previous period (also called "past period"): - startDate: Jul 1, 2024 - endDate: Jul 31, 2024 - statementDate: Aug 1, 2024 - dueDate: Aug 22, 2024 - Notes: - The draw level obligation details that you need to pass correspond to the previous period that started on Jul 1, 2024 and ended on Jul 31, 2024. - The amounts and other values should be as of the "migration cutoff date", Aug 1, 2024, after the statement was finalized in your legacy system. - `data.obligation.migratedDaysOverdue` (integer, required) This represents the number of days overdue prior to the "migration cutoff" date as it appears in the other system (not Peach). This value is normally calculated as the number of calendar days overdue starting from the earliest overdue obligation's due date to the "migration cutoff date". This value, once set, won't change after the migration. This value will be prorated and added to `daysOverdue` of future obligations (if any become overdue). The system will prorate the `migratedDaysOverdue` dynamically as the borrower makes payments and add it to the days overdue post "migration cutoff date". Calculation details: - The `migratedDaysOverdue` value will be used to prorate days overdue prior to the "migration cutoff date" based on the paid balance of `migratedOverdueAmount` (which is set based on the `balances.overdueBalances`). - round_down [migratedDaysOverdue x (1 - min(fulfilledAmount / migratedOverdueAmount, 1))] - For example: - migratedDaysOverdue = 60 - migratedOverdueAmount = $1000 - Scenario 1: - Borrower didn't make any payment within the first 30 days after the "migration cutoff date". - Total days overdue: - 60 x (1 - min(0 / 1000, 1)) + 30 = 90 - Scenario 2: - Borrower made payments in a total amount of $700 within the first 30 days after the "migration cutoff date". The line is still overdue. - Total days overdue: - 60 x (1 - min(700 / 1000, 1)) + 30 = 48 - `data.obligation.obligationAmount` (number, required) The remaining amount of the previous period's obligation that a borrower needs to pay on the due date that comes after "migration cutoff date". The remaining amount should be as of "migration cutoff date" vs. "migration at date". This is the draw level remaining obligation amount. If your LOC (or credit card) product doesn't count payments that were made before the statement date towards the statement minimum amount, then `obligationAmount` must be always equal to the draw portion of the whole statement minimum amount. Example: - Migration period: - startDate: Aug 1, 2024 - endDate: Aug 31, 2024 - statementDate: Sep 1, 2024 - dueDate: Sep 22, 2024 - Previous period (also called "past period"): - startDate: Jul 1, 2024 - endDate: Jul 31, 2024 - statementDate: Aug 1, 2024 - dueDate: Aug 22, 2024 Scenario 1: - The draw minimum payment was calculated as $100 on the statement date on Aug 1, 2024. - A borrower made some payments in the previous period, and based on your waterfall configuration in the legacy system, $30 was counted towards the $100 minimum amount. - The remaining minimum amount of $70 is due on Aug 22, 2024. - You should pass `obligationAmount=70`. Scenario 2: - The draw minimum payment was calculated as $100 on the statement date on Aug 1, 2024. - A borrower made some payments in the previous period, and based on your waterfall configuration in the legacy system, none of the payments were counted toward the $100 minimum amount. - The minimum amount of $100 is due on Aug 22, 2024. - You should pass `obligationAmount=100`. Scenario 3: - The draw minimum payment was calculated as $100 on the statement date on Aug 1, 2024. - A borrower made early payments in the previous period, and based on your waterfall configuration in the legacy system, the payments were counted toward the $100 minimum amount. - The remaining minimum amount of $0 is due on Aug 22, 2024 (in other words, the borrower doesn't need to pay anything on Aug 22, 2024.) - You should pass `obligationAmount=0`. - `data.migratedOverdueAmount` (number)