### Schema: RequestStartDate

Source: https://docs.peachfinance.com/_spec/API%20Docs/@2023-11-29/api-public.json

The start date of the promise to pay plan. If `startDate` is not provided upon promise to pay plan creation,
the system will use the created date (i.e. "today") as the `startDate`. If `startDate` is provided, it must be a date in the future.
Notes:
- If you are providing a `schedule` object, you should not pass the `startDate`. In case both are provided in the 
  request, a `400 Bad Request error` will be returned.
- If Peach's system creates the schedule based on `frequency`,`specificDays` and `duration` passed, the system will 
  schedule Promise to Pay Periods starting after the `startDate`.


```markdown
## Schema: RequestStartDate

The start date of the promise to pay plan. If `startDate` is not provided upon promise to pay plan creation,
the system will use the created date (i.e. "today") as the `startDate`. If `startDate` is provided, it must be a date in the future.
Notes:
- If you are providing a `schedule` object, you should not pass the `startDate`. In case both are provided in the 
  request, a `400 Bad Request error` will be returned.
- If Peach's system creates the schedule based on `frequency`,`specificDays` and `duration` passed, the system will 
  schedule Promise to Pay Periods starting after the `startDate`.


**Type:** string


```

--------------------------------

### GET /people/{personId}/loans/{loanId}/advances/{advanceId}

Source: https://docs.peachfinance.com/_spec/API%20Docs/@2023-11-29/api-public.json

Returns an installment loan advance

```markdown
### Parameters

- **personId** (AnyId, path, required): A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

- **loanId** (AnyId, path, required): The unique identifier of the Loan we wish to retrieve. Can be
Peach or lender's external identifier.

- **advanceId** (AnyId, path, required): The advance identifier.

### Responses

#### 200 - Success

- **message** (string): Description of the server action or error.
- **status** (integer): HTTP status code.
- **data** (object)
  - **advanceDate** (string (date)): The date of the advance in the product timezone. The date cannot be in the past or greater than the last due date.
 - If the advance is created in `pending` or `settled` status, the advance will be recorded in the ledger with an effective timestamp of
   the Create advance call.
 - If the advance is created in `scheduled` status, the advance will be recorded in the ledger only when the status changes to `pending` or `settled`.

  - **advanceDetails** (object): The details of advance.
    - **categoryId** (string): The category identifier of the advance.
    - **description** (string): The description of the advance. Normally shown in Borrower Portal and on statements. At least one of the attributes, `description`
or `merchantName` must be passed.

    - **merchantId** (string): The merchant identifier that the advance was used for.
    - **merchantName** (string): The merchant name that the advance was used for. At least one of the attributes, `description` or `merchantName` must be passed.
    - **metadata** (object): Store any type of key/value pairs in the form of a JSON dictionary.
    - **pointOfSaleType** (string (online|physical|recurring)): - `online` - the advance was made online on a website or in a mobile application.
- `physical` - the advance was made in a store with a physical card or instrument.
- `recurring` - the advance was made as part of a subscription service.
 ("online"|"physical"|"recurring")
  - **advanceTimeOfDay** (object)
    - **hour** (integer) (required): The hour. Value range is 0-23. 0=Midnight...23=11 PM.
    - **minute** (integer) (required): The minute. Value range is 0-59.
    - **second** (integer): The second. Value range is 0-59.
  - **amount** (number (float)): The amount of advance. The amount must be positive.
  - **canceledBy** (string): Identifier of the `User` who canceled the advance.
  - **externalId** (string): A lender's identifier for a resource.

After the resource is successfully created, a lender can use the Peach assigned ID OR
the `externalId` identifiers to fetch the resource.

### Fetching with `externalId`:

To fetch a resource using an `externalId`, you MUST use the prefix `ext-` in the URL.

For example, a loan with an external identifier of `ABCDE` would be referenced like `/api/people/BO-FAKE-IDNT/loans/ext-ABCDE`.

### Creating with `externalId`:

To create a resource with an external identifer, you MUST NOT use the prefix `ext-`.

For example, if the external identifier should be `ABCDE`, then pass
`{ externalId: "ABCDE", ... }` in the request body.

  - **id** (string): The unique identifier of the purchase.
  - **metadata** (object): Store any type of key/value pairs in the form of a JSON dictionary.
  - **originalAmount** (number (float)): The original amount of the advance. The amount must be positive.
  - **status** (string (scheduled|settled|pending|canceled)): - `scheduled` - the advance was scheduled in the future. If the advance status doesn't change to `pending`, `settled` or `canceled` on the advance due
   date, the system will automatically cancel the advance on the following calendar day (aka change the status to `canceled`).

   For example: An advance was `scheduled` for May 27, 2021. On May 28, 2021, the advance status was still `scheduled`. The system will cancel the advance.

- `settled` - the advance was settled and/or funded. `settled` advances increase the loan balance.

- `pending` - the advance is pending. `pending` advances increases the loan balance similar to `settled`. `pending` status is used mainly for visuals
   and normally shown in Borrower Portal.

- `canceled` - the advance was canceled. `canceled` advances reduce the draw balance. A new advance cannot be created in `canceled` status.
 ("scheduled"|"settled"|"pending"|"canceled")
  - **timestamps** (object)
    - **canceledAt** (string (date-time))
    - **createdAt** (string (date-time))
    - **updatedAt** (string (date-time))

### Example Usage

```bash
curl -X GET "https://sandboxapi.peach.finance/api/people/{personId}/loans/{loanId}/advances/{advanceId}"
```

```

--------------------------------

### GET /people/{personId}/loans/{loanId}/advances

Source: https://docs.peachfinance.com/_spec/API%20Docs/@2023-11-29/api-public.json

Returns an installment loan's advances

```markdown
### Parameters

- **personId** (AnyId, path, required): A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

- **loanId** (AnyId, path, required): The unique identifier of the Loan we wish to retrieve. Can be
Peach or lender's external identifier.

- **status** (string (scheduled|pending|settled|canceled), query, optional): The status of the advances.

### Responses

#### 200 - Success

- **message** (string): Description of the server action or error.
- **status** (integer): HTTP status code.
- **data** (object)
  - **advances** (array (Advance))
    Array items:
      - **advanceDate** (string (date)): The date of the advance in the product timezone. The date cannot be in the past or greater than the last due date.
 - If the advance is created in `pending` or `settled` status, the advance will be recorded in the ledger with an effective timestamp of
   the Create advance call.
 - If the advance is created in `scheduled` status, the advance will be recorded in the ledger only when the status changes to `pending` or `settled`.

      - **advanceDetails** (object): The details of advance.
        - **categoryId** (string): The category identifier of the advance.
        - **description** (string): The description of the advance. Normally shown in Borrower Portal and on statements. At least one of the attributes, `description`
or `merchantName` must be passed.

        - **merchantId** (string): The merchant identifier that the advance was used for.
        - **merchantName** (string): The merchant name that the advance was used for. At least one of the attributes, `description` or `merchantName` must be passed.
        - **metadata** (object): Store any type of key/value pairs in the form of a JSON dictionary.
        - **pointOfSaleType** (string (online|physical|recurring)): - `online` - the advance was made online on a website or in a mobile application.
- `physical` - the advance was made in a store with a physical card or instrument.
- `recurring` - the advance was made as part of a subscription service.
 ("online"|"physical"|"recurring")
      - **advanceTimeOfDay** (object)
        - **hour** (integer) (required): The hour. Value range is 0-23. 0=Midnight...23=11 PM.
        - **minute** (integer) (required): The minute. Value range is 0-59.
        - **second** (integer): The second. Value range is 0-59.
      - **amount** (number (float)): The amount of advance. The amount must be positive.
      - **canceledBy** (string): Identifier of the `User` who canceled the advance.
      - **externalId** (string): A lender's identifier for a resource.

After the resource is successfully created, a lender can use the Peach assigned ID OR
the `externalId` identifiers to fetch the resource.

### Fetching with `externalId`:

To fetch a resource using an `externalId`, you MUST use the prefix `ext-` in the URL.

For example, a loan with an external identifier of `ABCDE` would be referenced like `/api/people/BO-FAKE-IDNT/loans/ext-ABCDE`.

### Creating with `externalId`:

To create a resource with an external identifer, you MUST NOT use the prefix `ext-`.

For example, if the external identifier should be `ABCDE`, then pass
`{ externalId: "ABCDE", ... }` in the request body.

      - **id** (string): The unique identifier of the purchase.
      - **metadata** (object): Store any type of key/value pairs in the form of a JSON dictionary.
      - **originalAmount** (number (float)): The original amount of the advance. The amount must be positive.
      - **status** (string (scheduled|settled|pending|canceled)): - `scheduled` - the advance was scheduled in the future. If the advance status doesn't change to `pending`, `settled` or `canceled` on the advance due
   date, the system will automatically cancel the advance on the following calendar day (aka change the status to `canceled`).

   For example: An advance was `scheduled` for May 27, 2021. On May 28, 2021, the advance status was still `scheduled`. The system will cancel the advance.

- `settled` - the advance was settled and/or funded. `settled` advances increase the loan balance.

- `pending` - the advance is pending. `pending` advances increases the loan balance similar to `settled`. `pending` status is used mainly for visuals
   and normally shown in Borrower Portal.

- `canceled` - the advance was canceled. `canceled` advances reduce the draw balance. A new advance cannot be created in `canceled` status.
 ("scheduled"|"settled"|"pending"|"canceled")
      - **timestamps** (object)
        - **canceledAt** (string (date-time))
        - **createdAt** (string (date-time))
        - **updatedAt** (string (date-time))
  - **totalAdvancedAmount** (number (float)): The total of advances amounts in `pending` or `settled` status. In other words, the total of advances that
were written to the ledger.

  - **totalScheduledAmount** (number (float)): The total of advances amounts in `scheduled` status.

### Example Usage

```bash
curl -X GET "https://sandboxapi.peach.finance/api/people/{personId}/loans/{loanId}/advances?status=scheduled"
```

```

--------------------------------

### Schema: PromoStartDate

Source: https://docs.peachfinance.com/_spec/API%20Docs/@2023-11-29/api-public.json

The `promoStartDate` date marks the start date from which a
promotional program is valid and will be evaluated to be exercised.
When a promo program is created with `promoDurationDays` specified,
the `promoStartDate` is also used to calculate the `promoEndDate`. 

For installment loans:

- The `promoStartDate` can be a date in the future but not after the
  loan's last due date.
  The promotion is valid and evaluated after it has been activated
  and the `promoStartDate` arrived.
- The `promoStartDate` can be a date in the past but not before the
  loan's activation date.
- The `promoStartDate` is optional.
  If the value is not passed, the system will set the promoStartDate
  to the loan activation date.
- For `Same as Cash` promo programs, the waiving of interest benefit
  will be added from the loan activation date for the entire life of
  the loan for installment loans, regardless of the
  `promoStartDate`.

For Line of Credit draws:

- The `promoStartDate` can be a date in the future.
  The promotion is valid and evaluated after it has been activated
  and the `promoStartDate` arrived.
- The `promoStartDate` cannot be a date in the past.

If a value is not passed, the system will set the `promoStartDate`
to be the date of the activation.

This date value should be in the product timezone.


```markdown
## Schema: PromoStartDate

The `promoStartDate` date marks the start date from which a
promotional program is valid and will be evaluated to be exercised.
When a promo program is created with `promoDurationDays` specified,
the `promoStartDate` is also used to calculate the `promoEndDate`. 

For installment loans:

- The `promoStartDate` can be a date in the future but not after the
  loan's last due date.
  The promotion is valid and evaluated after it has been activated
  and the `promoStartDate` arrived.
- The `promoStartDate` can be a date in the past but not before the
  loan's activation date.
- The `promoStartDate` is optional.
  If the value is not passed, the system will set the promoStartDate
  to the loan activation date.
- For `Same as Cash` promo programs, the waiving of interest benefit
  will be added from the loan activation date for the entire life of
  the loan for installment loans, regardless of the
  `promoStartDate`.

For Line of Credit draws:

- The `promoStartDate` can be a date in the future.
  The promotion is valid and evaluated after it has been activated
  and the `promoStartDate` arrived.
- The `promoStartDate` cannot be a date in the past.

If a value is not passed, the system will set the `promoStartDate`
to be the date of the activation.

This date value should be in the product timezone.


**Type:** string


```

--------------------------------

### PUT /people/{personId}/loans/{loanId}/payment-plan-scra

Source: https://docs.peachfinance.com/_spec/API%20Docs/@2023-11-29/api-public.json

This endpoint is used for modifying the start date or end date of a single SCRA interest rate (`interestType=AbsoluteScra`).
Only applicable to installment loans.

If the SCRA start date is in the past, this will replay the loan.

When an existing SCRA plan is updated or deleted, the system determines whether fees should be canceled or revived based on the `isCancelFees` value from the original SCRA plan.
For example, if we are updating the SCRA plan:

Expanding the SCRA period
- If `isCancelFees` = `true`, we will cancel fees within the extended SCRA plan period.
- If `isCancelFees` = `false`, we will not cancel any fees within the extended SCRA plan period.

Shrinking the SCRA period
- If `isCancelFees` = `true`, we will revive any previously canceled fees within the portion of the SCRA plan period that is being removed.
- If `isCancelFees` = `false`, we will not revive any fees since there were no fees canceled in the original SCRA plan.


```markdown
### Parameters

- **personId** (AnyId, path, required): A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

- **loanId** (AnyId, path, required): The unique identifier of the Loan we wish to retrieve. Can be
Peach or lender's external identifier.


### Request Body

**Content-Type:** application/json

- **caseId** (string): An identifier for an existing case.
- **endDate** (string (date)) (required): The new end date for the SCRA period. The end date is inclusive.
Must be within the loan's lifetime, after the start date, and must not overlap with other SCRA plans.

- **rateId** (string) (required): The public ID of the SCRA interest rate to modify.
- **sendNotice** (boolean): When set to `false`, the system will NOT send a `loanPaymentScheduleChanged` notice to the borrower.

- **startDate** (string (date)) (required): The new start date for the SCRA period. The start date is inclusive.
Must be within the loan's lifetime and must not overlap with other SCRA plans.


### Responses

#### 200 - response

- **count** (integer): Total number of items in this result.
- **status** (integer): HTTP status code.
- **data** (object)
  - **isLocked** (boolean): If true, the loan is in the middle of being updated or replayed. The returned data are not consistent. The caller should poll
on the `Get loan lock status` endpoint. Once `isLocked`` becomes `false`, the caller should call this endpoint again to get consistent data.

  - **paymentFrequency** (string (weekly|everyTwoWeeks|twiceMonthly|monthly)): The expected payments' frequency. ("weekly"|"everyTwoWeeks"|"twiceMonthly"|"monthly")
  - **schedule** (array (ExpectedPayment))
    Array items:
      - **amount** (number (float)): The amount of the expected payment.
      - **date** (string (date)): The due date of the expected payment.
      - **dynamicFeeDetails** (object): When `paymentType`=`dynamicFee` this will contain details of the dynamic fee.

        - **apiName** (string): The API name of the dynamic fee. For example: 'lateFee' or 'breatherFee'.

        - **displayName** (string): The display name of the dynamic fee as shown to the borrower in the UI. For example: `Late Fee` or `Breather Fee`.

        - **dynamicFeeTypeId** (string): The dynamic fee type identifier in the system.
        - **loanFeeId** (string): The loan fee identifier in the system.
      - **interestAmount** (number (float)): The portion of the `amount` allocated to net interest.
Available only for `paymentType=periodicPayment`.

      - **interestBeforeDiscountAmount** (number (float)): The interest amount that was accrued before promo rate(s) or any discount.
Available only for `paymentType=periodicPayment`.

      - **isDeferred** (boolean): `true` if the amount of this expected payment has been deferred before.

      - **isForcedAmount** (boolean): Only applicable to `paymentType=periodicPayment`.
If set to `true`, the system will honor the amount and will not update it on loan recalculations.
If set to `false` and the amount is less than the `periodicPaymentAmount`, the system can increase the amount when
the loan is being recalculated.
In most of the cases, the lender should set the value to `false` (aka the default value.) If you need more
explanation or advice on your use case, please contact the Peach team.

      - **originalAmount** (number (float)): The amount of the expected payment at creation. The `amount` will change as a result of refreshing
expected payments, but the `originalAmount` will stay the same.

      - **paymentType** (string (periodicPayment|originationFee|drawFee|dynamicFee|downPayment|discountCredit)): The payment type. ("periodicPayment"|"originationFee"|"drawFee"|"dynamicFee"|"downPayment"|"discountCredit")
      - **periodId** (string): The period identifier.
      - **principalAmount** (number (float)): The portion of the `amount` allocated to principal.
Available only for `paymentType=periodicPayment`.

      - **status** (string (booked|modified|canceled)): The status of the expected payment.

`scheduled`  - borrower is expected to make the payment. Only applicable to paymentType=dynamicFee.

`booked` - borrower is or was expected to make the payment.

`modified` - the amount was modified at some point and different from the original amount.

`canceled` - borrower is or was not expected to make the payment.
 ("booked"|"modified"|"canceled")
      - **unroundedInterestAmount** (string): The portion of the `amount` allocated to net interest. Available only for `paymentType=periodicPayment`.
This value is unrounded.

      - **unroundedInterestBeforeDiscountAmount** (string): The interest amount that was accrued before promo rate(s) or any discount. Available only for
`paymentType=periodicPayment`. This value is unrounded.

      - **unroundedPrincipalAmount** (string): The portion of the `amount` allocated to principal. Available only for `paymentType=periodicPayment`.
This value is unrounded.

  - **specificDays** (array (union)): Specific days designate the day(s) that due dates will fall on. The allowed values for specific
day(s) depends on the `paymentFrequency`.

`weekly` - provide one number in the valid range 1-7. 1=Monday...7=Sunday.

For example: [1].

`everyTwoWeeks` - provide two inputs. The first input (required) is an integer in the valid range 1-7. 1=Monday...7=Sunday.

The second input is a date that indicates when to start the cycle. If the second input is not passed, the system will default
to the first valid start date based on the first input (the day of week passed in). If this date is provided then it can override
the minimum due date gap specified on the loan type.

For example: [1, "2020-09-16"].

`twiceMonthly` - provide two numbers in the valid range 1-31. 1=first day of a month. Use 31 to
indicate the last day of a month.

For example: [1, 15] or [15, 31].

`monthly` - provide one or two numbers, depending on the loan type `periodCalculationType` configuration:
  - If `periodCalculationType=dueDate`, then provide one number in the valid range 1-31. This is the recurring due date. 1=first
  day of a month. Use 31 to indicate the last day of a month. For example: [1].
  - If `periodCalculationType=statementDate`, then provide one number in the valid range 1-31. This is the recurring statement date.
  1=first day of a month. Use 31 to indicate the last day of a month. For example: [1].
  - If `periodCalculationType=fixedStatementAndDueDates`, then provide two numbers. First number represents a recurring statement
  date and the valid range is 1-31. Use 31 to indicate the last day of a month. Second number represents a recurring due date and
  the valid range is 1-28. Two numbers must be different. For example: [1, 15] - statements are on 1st and due dates are on 15th.
  Notes:
    - If the due date precedes the statement day, it's pushed to the next month. For example: [20, 10] and today is Oct 1, 2024. The
    first statement date is Oct 20, 2024 and the first due date is Nov 10th.
    - For February in non-leap years, if the statement date is ≥ 29 and the due date is 28, the statement date becomes March 1st.

`singleTerm` - provide one number to indicate duration as a number of calendar days or provide a valid calendar date in the
future. This option is only valid for use on the installment type and at loan origination.
For example: [90] or ["2020-09-16"].

For `weekly`, `everyTwoWeeks`, `twiceMonthly`, `monthly`:
If specificDays is left null, then the system will calculate due dates according to the paymentFrequency relative
to the origination or activation date (or use existing specific days in the case of change due date).

For `singleTerm`:
The specificDays is mandatory.


### Example Usage

```bash
curl -X PUT "https://sandboxapi.peach.finance/api/people/{personId}/loans/{loanId}/payment-plan-scra" \
  -H "Content-Type: application/json" \
  -d '{
  "example": "data"
}'
```

```