Why Use Batch Payouts
Batch payouts simplify repetitive or large-scale payments by allowing you to group them into a single operation. Benefits include:- Reduced API calls and easier reconciliation.
- Consistent tracking and reporting for related payouts.
- A single webhook event to track batch completion.
- Monthly commission payouts to agents.
- Weekly vendor payments.
- Claims reimbursements to multiple members.
How Batch Payouts Work
When you create a batch, you provide:- A funding account (the account that funds all payouts).
- A list of payouts (each with amount, currency, and payee).
- Validates all payout details.
- Processes each payout in parallel.
- Sends webhook events for both individual payouts and the batch as a whole.
Batch Lifecycle
A typical batch flows through these stages:| Stage | Description |
|---|---|
| created | The batch was accepted and queued for processing. |
| processing | Payouts within the batch are being executed. |
| succeeded | All payouts finished successfully. |
| partial_failed | Some payouts failed, but others succeeded. |
| failed | All payouts failed (e.g., insufficient funds). |
Webhooks for Batches
Acclaim sends events for both the batch and its individual payouts. Common events include:payout_batch.createdpayout_batch.updatedpayout_batch.succeededpayout_batch.failedpayout_batch.canceled
payout.succeeded or payout.failed.
You can listen for batch-level webhooks to summarize or reconcile results, and payout-level events for detailed reporting.
Tips for Working with Batches
- Use consistent reference IDs to help match batches with internal reports.
- Handle partial failures gracefully by checking which payouts succeeded before retrying.
- Use sandbox testing to validate batch flows before moving to production.
Next Steps
- Learn how to handle webhook events to track batch and payout statuses in real time.
- Explore reconciliation and reporting to close the loop on large payout runs.