# Create a payout request batch

Creates a batch of payout requests for batch processing.

The batch links multiple payout requests together so they can be auto-allocated and processed together.
Each payout request can be assigned to only one batch.
If any of the specified payout requests are already included in another batch, a 409 Conflict error is returned.

Both approaches are limited to a maximum of 1000 payout requests per batch.

Two mutually exclusive approaches are supported:
- Explicit IDs: Provide an array of payout request IDs in the payoutRequestIds field.
- Filter-based: Provide a filter string to select payout requests that match the specified criteria at execution time.
  Payout requests that are already included in a batch are automatically excluded from the filter results.
  If more than 1000 payout requests match the filter, only the oldest 1000 are included in the batch, sorted by creation time.
  To view the number of matching items before creating the batch, use the Preview payout request batch filter results operation.

Endpoint: POST /payout-request-batches
Version: latest
Security: SecretApiKey, JWT

## Response 201 fields (application/json):

  - `id` (string)
    ID of the batch.
    Example: "preq_batch_0YVDMDE2BMC6KBB5MX76RF6T80"

  - `userId` (string)
    ID of the user who created the batch.
    Example: "usr_0YVCEENYJ3D7Q9EN6BN16HA0G4"

  - `status` (string)
    Status of the batch.
    Enum: "pending", "processing", "completed", "failed"

  - `totalCount` (integer)
    Total number of payout requests in the batch.
    Example: 10

  - `successCount` (integer)
    Number of payout requests successfully processed.
    Example: 8

  - `failureCount` (integer)
    Number of payout requests that failed to process.
    Example: 2

  - `customerCount` (integer)
    Number of unique customers in the batch.
    Example: 3

  - `totalAmountByCurrency` (array)
    Total payout amount grouped by currency in the batch.

  - `totalAmountByCurrency.currency` (string, required)
    Currency code in ISO 4217 format.

  - `totalAmountByCurrency.amount` (number, required)

  - `description` (string,null)
    Optional description of the batch.
    Example: "Batch processed on 2024-01-15"

  - `allocationOrder` (array,null)
    Order for auto-allocation of payout requests in this batch.
When set, this field overrides the organization-level allocation order during batch auto-allocation.
Must contain selected-payment-instrument exactly once.
Valid values: payment-card (payment cards), alternative-payment-methods (catch-all for alternative payment methods), selected-payment-instrument (customer-requested instrument), or any payment method API name (for example, paypal, Interac-eTransfer).
    Example: ["paypal","Interac-eTransfer","payment-card","alternative-payment-methods","selected-payment-instrument"]

  - `createdTime` (string)
    Date and time when the batch was created.

  - `updatedTime` (string)
    Date and time when the batch was last updated.

  - `_links` (array)
    Related links.

  - `_links.href` (string)
    Link URL.

  - `_links.rel` (string)
    Type of link.
    Enum: "self", "payoutRequests"

## Response 400 fields (application/json):

  - `type` (string)
    URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] that identifies the problem type.
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: "https://www.rebilly.com/docs/"

  - `status` (integer)
    HTTP status code.

  - `title` (string)
    Short, human-readable summary of the problem type.
It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

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

## 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 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 409 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 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.

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

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

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