Batch Payouts
Batch payouts let you send many payouts at once — perfect for commission runs, claims reimbursements, or any recurring disbursement that involves multiple recipients. This guide covers when to use batches, how they work, and what to expect as they process.
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.
Example use cases:
- 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 source wallet (the wallet that funds all payouts).
- A list of payouts (each with amount, currency, and payee).
Each payout in the batch runs independently, but Acclaim manages them as one coordinated process.
Once created, Acclaim:
- 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. |
| completed | All payouts finished successfully. |
| partial_failed | Some payouts failed, but others succeeded. |
| failed | All payouts failed (e.g., insufficient funds). |
You’ll see these states reflected in both the Acclaim Console and webhook events.
Webhooks for Batches
Acclaim sends events for both the batch and its individual payouts.
Common events include:
payout_batch.createdpayout_batch.processingpayout_batch.completedpayout_batch.partial_failedpayout_batch.failed
Each individual payout will also trigger its own events such as payout.completed 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.
Updated 27 days ago
Learn how to handle webhook events track batch and payout statuses in real time. Explore reconciliation and reporting to close the loop on large payout runs.