Submitting tax payments in batches
Schedule up to 5,000 tax payments for one firm in a single request, then read each result and resubmit only what failed.
What it is
A tax payment batch lets you submit up to 5,000 tax payments for the taxpayers of one firm in a single request with POST /v1/firms/{firmId}/tax-payment-batches. Remitian stores the batch, responds immediately and schedules each item in the background, as if each was sent individually.
When you need it
- You schedule many payments at once, for example at a filing deadline.
- You want one result per item instead of handling thousands of individual requests.
How it works
- Submit the batch with your own batch
externalIdand anitemslist. Each item has the same fields as a single tax payment, plustaxpayerId. - Remitian responds with
201 Created, the batchidand the number of items accepted. - Remitian schedules each item in the background. When every item has an outcome, the batch becomes
Processedand Remitian sends thebatch.Processed.v1webhook event. - Read the counters with
GET .../tax-payment-batches/{batchId}, or find the batch by yourexternalId. - List failed items with
GET .../tax-payment-batches/{batchId}/items?status=Failed. - Correct the failed items and submit them in a new batch.
| Level | Statuses |
|---|---|
| Batch | Requested (items being scheduled), Processed (every item succeeded or failed) |
| Item | Pending, Processing, Succeeded (returns taxPaymentId), Failed (returns errorCode and errorMessage) |
Common questions
Does one bad item reject the whole batch?
No. Submission only checks the batch shape. Item content (taxpayer, tax account, bank account, payment type, amount, dates) is validated when each item is scheduled, so an invalid item fails on its own and the rest continue.
Is it safe to retry a submission?
Yes. The batch externalId is unique per firm, so a second batch with the same value returns 409 Conflict naming the existing batch instead of creating a duplicate.
What errors should I expect?
400 for a missing or invalid externalId, an empty list, more than 5,000 items or an item missing a required field. 403 when the caller cannot manage that firm's clients, 404 when the firm or batch is not found. Treat errorCode as opaque: log it, do not parse it.
Can I batch payments outside the US?
At launch, batches are processed for US tax payments only.
What if I do not receive the webhook?
The event goes to the webhook configured for the firm, once per batch. A firm without an active webhook configuration receives nothing, so poll the batch instead.
Full documentation