> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withacclaim.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch payouts

> Send and manage a high volume of payouts at once. Use batches to process payouts at scale with visibility into execution, FX, and outcomes.

Batch payouts let you send multiple payouts in a single operation.
They are designed for workflows where you need to **process many payouts together**, such as claims runs, vendor payments, or scheduled disbursements.

Using batches provides **visibility, control, and efficiency** when operating at scale.

***

## When to use batch payouts

Use batch payouts when you need to:

* **Send large volumes of payouts** at once
* **Group related payouts** into a single execution
* **Track outcomes collectively** (e.g. by run, file, or event)
* **Reduce operational overhead** compared to individual payouts

***

## How batch payouts work

A batch groups multiple payouts into a single unit of execution.

1. **Create a batch**
   Define a batch and include one or more payouts.

2. **Validate payouts**
   Each payout is validated for required details, payout method compatibility, and readiness.

3. **Lock FX (if applicable)**
   For cross-border payouts, Acclaim generates a **single FX quote per currency pair within the batch**.
   This ensures consistent conversion rates across all payouts sharing the same source and destination currencies.

4. **Process the batch**
   Payouts are submitted for processing. Each payout progresses through its own **lifecycle and status**.

5. **Track results**
   Monitor outcomes at both the **batch level** and **individual payout level**.

***

## Batch vs individual payouts

* A **batch** is a container for multiple payouts
* Each **payout** inside the batch is processed independently

This means:

* Some payouts may **succeed** while others **fail**
* Failures do not block the entire batch
* Each payout maintains its own **status and lifecycle**

For cross-border payouts:

* FX is **grouped at the batch level**
* Execution and delivery remain **independent per payout**

***

## Creating batch payouts

You can create batch payouts using:

* **API** — programmatically create and submit batches
* **File uploads** — upload a structured file containing payouts
* **Console** — create and review batches manually

File uploads are commonly used for **high-volume batch workflows**.

***

## Validation and readiness

Before processing, each payout in a batch must be in a valid state.

Common requirements:

* Payee details are complete
* A valid payout method is available
* Required approvals are completed (if applicable)

Payouts that are not ready will remain in:

* **RequiresPayeeInfo**
* **RequiresPayoutMethod**
* **NeedsApproval**

Only payouts in **ReadyToProcess** will move into execution.

***

## FX and currency conversion

When a batch includes payouts across currencies:

* A **single FX quote is generated per currency pair** (e.g. USD → EUR)
* All payouts using that pair share the **same rate**
* This ensures **consistency and predictability** across the batch

Benefits:

* Simplified reconciliation
* Consistent recipient outcomes
* Reduced rate fragmentation across payouts

***

## Processing behavior

When a batch is processed:

* Eligible payouts move to **Processing**
* Payouts are sent through their selected payout methods
* Status updates occur asynchronously

Batch execution does not guarantee simultaneous delivery. Timing may vary based on:

* Payout method
* Country and currency
* External payment networks

***

## Tracking batch results

Track batch performance at two levels:

### Batch level

* Total number of payouts
* Number of payouts by status
* FX quotes applied per currency pair
* Overall progress and completion

### Payout level

* Individual payout status
* Failure reasons
* Delivery confirmations

This allows you to quickly identify:

* Which payouts succeeded
* Which require action

***

## Handling failures in batches

Failures are handled at the payout level.

If a payout fails:

* Review the failure reason
* Correct any issues (e.g. payee details, payout method)
* Retry the payout independently

You do not need to reprocess the entire batch.

***

## Best practices

* **Validate data upfront** to minimize failures
* **Group logically related payouts** (e.g. by run or event)
* **Use batches to consolidate FX exposure** across payouts
* **Monitor batch results** during and after processing
* **Use webhooks** to track status changes programmatically

***

## Summary

* Batch payouts enable **scalable payout execution**
* FX is **grouped per currency pair**, ensuring consistent rates
* Each payout maintains its own **lifecycle and status**
* Failures are **isolated and recoverable**
* Batches provide **visibility and operational efficiency** for high-volume workflows