# Allocate customer credit balance to an invoice

Allocates existing allocatable credit memos related to the invoice customer.
Specific credit memos cannot be provided in the request and are selected automatically.
Allocation can be capped with `amount`.
Credit memos are applied automatically in the specified allocation order.
If no order is specified, `oldest-first` is used.

Endpoint: POST /invoices/{id}/allocate-credit-balance
Version: latest
Security: SecretApiKey, JWT

## Security:

  - `SecretApiKey` (unknown)
    apiKey in header REB-APIKEY

  - `JWT` (unknown)
    http bearer JWT

## Path parameters:

  - `id` (string, required)
    ID of the resource.

## Request body:

  - `application/json` (unknown)
    Invoice credit memo automatic allocation settings.

## Request fields (application/json):

  - `amount` (number)
    Optional maximum amount to allocate from customer credit memos to the invoice.
If provided, allocation is capped at this value.
If omitted, the allocated amount is the lesser of:
- Invoice unpaid amount.
- Available allocatable credit memo balance.

  - `allocationOrder` (string)
    Credit memo application order.
    Enum: "oldest-first", "newest-first"

## Response 200:

  - `200` (unknown)
    Credit memos allocated to invoice.

## Response 200 fields (application/json):

  - `invoiceId` (string, required)
    ID of the invoice.
    Example: in_0YVF9605RKC62BP14NE2R7V2XT

  - `currency` (string, required)
    Currency code in ISO 4217 format.
    Example: USD

  - `appliedCreditMemos` (array, required)
    List of credit memos applied to the invoice and the amount allocated from each.

  - `appliedCreditMemos.creditMemoId` (string, required)
    ID of the credit memo.
    Example: crmm_0YVCNN22TWC3G8H82QNPNVZCHG

  - `appliedCreditMemos.amount` (number, required)
    Amount allocated from the credit memo to the invoice.

  - `remainingInvoiceAmount` (number, required)
    Remaining amount due on the invoice after credit memo allocation.

## Response 200 headers (application/json):

  - `Rate-Limit-Limit` (integer)
    Maximum number of requests available at one time for this rate limit.
For more information, see [Rate limits](#section/Rate-limits).
    Example: 500

  - `Rate-Limit-Remaining` (integer)
    Number of requests still available for this rate limit.
For more information, see [Rate limits](#section/Rate-limits).
    Example: 499

## Response 401:

  - `401` (unknown)
    Unauthorized access.
Invalid credentials used.

## Response 401 fields (application/json):

  - `status` (integer)
    HTTP status code.

  - `type` (string)
    Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference.
It should provide human-readable documentation for the problem type.
When this member is not present, its value is assumed to be "about:blank".

  - `title` (string)
    Short, human-readable summary of the problem type.
Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.

  - `detail` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem.
It may or may not yield further information if dereferenced.

## Response 403:

  - `403` (unknown)
    Access forbidden.
If the organization requires multi-factor authentication (MFA) and the session has not passed MFA, `error` is `mfa_required`.

## Response 403 fields (application/json):

  - `status` (integer)
    HTTP status code.

  - `error` (string)
    Message that describes why the request is forbidden.
Most responses use a descriptive message, such as `Not allowed to change security settings`.
If the organization requires multi-factor authentication (MFA) and MFA verification has not been completed for the session, this value is `mfa_required`.
If the request sets `requireMfa` to `true` and MFA verification has not been completed for the session, this value is `mfa_required_for_caller`.

  - `type` (string)
    Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference.
It should provide human-readable documentation for the problem type.
When this member is not present, its value is assumed to be "about:blank".

  - `title` (string)
    Short, human-readable summary of the problem type.
Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.

  - `detail` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem.
It may or may not yield further information if dereferenced.

## Response 404:

  - `404` (unknown)
    Resource not found.

## Response 404 fields (application/json):

  - `status` (integer)
    HTTP status code.

  - `type` (string)
    Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference.
It should provide human-readable documentation for the problem type.
When this member is not present, its value is assumed to be "about:blank".

  - `title` (string)
    Short, human-readable summary of the problem type.
Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.

  - `detail` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem.
It may or may not yield further information if dereferenced.

## Response 422:

  - `422` (unknown)
    Invalid data sent.

## Response 422 fields (application/json):

  - `status` (integer)
    HTTP status code.

  - `type` (string)
    Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference.
It should provide human-readable documentation for the problem type.
When this member is not present, its value is assumed to be "about:blank".

  - `title` (string)
    Short, human-readable summary of the problem type.
Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.

  - `detail` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem.
It may or may not yield further information if dereferenced.

  - `invalidFields` (array)
    Invalid field details.
    Example: [{"field":"field1","message":"field1 is invalid"},{"field":"subObject.field2","message":"field2 is invalid"},{"field":"subObject.field2","message":"another error in the field2"}]

  - `invalidFields.field` (string)
    Name of the field.
Dot notation is used for nested object field names.

  - `invalidFields.message` (string)
    Message field.

## Response 429:

  - `429` (unknown)
    Request rate limit exceeded.

## Response 429 fields (application/json):

  - `type` (string)
    Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference.
It should provide human-readable documentation for the problem type.
When this member is not present, its value is assumed to be "about:blank".
    Example: about:blank

  - `title` (string)
    Short, human-readable summary of the problem type.
Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.
    Example: Rate Limit Exceeded

  - `status` (integer)
    HTTP status code.

  - `detail` (string)
    Human-readable explanation that is specific to this occurrence of the problem.
    Example: A request cannot be executed because the user has sent too many requests within a certain period of time

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem.
It may or may not yield further information if dereferenced.

## Response 429 headers (application/json):

  - `Rate-Limit-Limit` (integer)
    Maximum number of requests available at one time for this rate limit.
For more information, see [Rate limits](#section/Rate-limits).
    Example: 500

  - `Rate-Limit-Remaining` (integer)
    Number of requests still available for this rate limit.
For more information, see [Rate limits](#section/Rate-limits).
    Example: 0

  - `Rate-Limit-Retry-After` (integer)
    Number of seconds to wait before retrying the request.
    Example: 1

  - `Retry-After` (integer)
    Number of seconds to wait before retrying the request.
    Example: 1