# Update advance

Endpoint: PUT /people/{personId}/loans/{loanId}/advances/{advanceId}
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.

  - `advanceId` (string, required)
    The advance identifier.

## Query parameters:

  - `sync` (boolean)
    Make the process synchronous.

## Request fields (application/json):

  - `advanceDate` (string)
    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.

  - `advanceDetails.categoryId` (string)
    The category identifier of the advance.

  - `advanceDetails.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.

  - `advanceDetails.merchantId` (string)
    The merchant identifier that the advance was used for.

  - `advanceDetails.merchantName` (string)
    The merchant name that the advance was used for. At least one of the attributes, `description` or `merchantName` must be passed.

  - `advanceDetails.metadata` (object)
    Store any type of key/value pairs in the form of a JSON dictionary.

  - `advanceDetails.pointOfSaleType` (string)
    - `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.
    Enum: "online", "physical", "recurring"

  - `advanceTimeOfDay` (object)

  - `advanceTimeOfDay.hour` (integer, required)
    The hour. Value range is 0-23. 0=Midnight...23=11 PM.

  - `advanceTimeOfDay.minute` (integer, required)
    The minute. Value range is 0-59.

  - `advanceTimeOfDay.second` (integer)
    The second. Value range is 0-59.

  - `amount` (number)
    The amount of advance. The amount must be positive.

  - `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.

  - `metadata` (object)
    Store any type of key/value pairs in the form of a JSON dictionary.

  - `status` (string)
    - `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.
    Enum: "scheduled", "settled", "pending", "canceled"

## Response 200 fields (application/json):

  - `message` (string)
    Description of the server action or error.

  - `status` (integer)
    HTTP status code.

  - `data` (object)

  - `data.advanceDate` (string)
    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`.

  - `data.advanceDetails` (object)
    The details of advance.

  - `data.advanceDetails.categoryId` (string)
    The category identifier of the advance.

  - `data.advanceDetails.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.

  - `data.advanceDetails.merchantId` (string)
    The merchant identifier that the advance was used for.

  - `data.advanceDetails.merchantName` (string)
    The merchant name that the advance was used for. At least one of the attributes, `description` or `merchantName` must be passed.

  - `data.advanceDetails.metadata` (object)
    Store any type of key/value pairs in the form of a JSON dictionary.

  - `data.advanceDetails.pointOfSaleType` (string)
    - `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.
    Enum: "online", "physical", "recurring"

  - `data.advanceTimeOfDay` (object)

  - `data.advanceTimeOfDay.hour` (integer, required)
    The hour. Value range is 0-23. 0=Midnight...23=11 PM.

  - `data.advanceTimeOfDay.minute` (integer, required)
    The minute. Value range is 0-59.

  - `data.advanceTimeOfDay.second` (integer)
    The second. Value range is 0-59.

  - `data.amount` (number)
    The amount of advance. The amount must be positive.

  - `data.canceledBy` (string)
    Identifier of the `User` who canceled the advance.

  - `data.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.

  - `data.id` (string)
    The unique identifier of the purchase.

  - `data.metadata` (object)
    Store any type of key/value pairs in the form of a JSON dictionary.

  - `data.originalAmount` (number)
    The original amount of the advance. The amount must be positive.

  - `data.status` (string)
    - `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.
    Enum: "scheduled", "settled", "pending", "canceled"

  - `data.timestamps` (object)

  - `data.timestamps.canceledAt` (string)

  - `data.timestamps.createdAt` (string)

  - `data.timestamps.updatedAt` (string)