- Use Case 8: Schedule Tax Payments
- Tax Payment Batches
Use Case 8: Schedule Tax Payments
Tax Payment Batches
Submit up to 5,000 tax payments in one request, follow the batch, and read the result of each item.
Submit up to 5,000 tax payments for the taxpayers of one firm in a single request. Remitian validates the shape of the request synchronously, stores the batch and responds immediately. Each item is then scheduled asynchronously, as if it was sent to Schedule a Tax Payment. When every item has an outcome, Remitian sends the batch.Processed.v1 webhook event, and your system reads the result of each item to resubmit only what failed.
Integration Flow:
- Your system submits the batch with its own
externalId(Submit a Batch) - Remitian responds with
201 Createdand the batchid - Remitian schedules each item in the background
- When every item has succeeded or failed, the batch becomes
Processedand Remitian sendsbatch.Processed.v1 - Your system reads the batch counters (Get a Batch or Find a Batch by External ID) and the failed items (List Batch Items)
- Your system corrects the failed items and submits them in a new batch
Batch Statuses:
| Status | Meaning |
|---|---|
Requested | The batch was accepted and its items are being scheduled |
Processed | Every item of the batch has succeeded or failed |
Batch Item Statuses:
| Status | Meaning |
|---|---|
Pending | The item is waiting to be scheduled |
Processing | The item is being scheduled |
Succeeded | The tax payment was created. taxPaymentId identifies it |
Failed | The tax payment was not created. errorCode and errorMessage describe why |
Submit a Batch
Sequence of Events:
- Your system sends the batch with its own
externalIdand the list of tax payments to schedule - Remitian validates the batch shape and stores it with status
Requested - Remitian responds with
201 Created, the batchidand the number of items accepted
Batch Request Structure:
| Field | Type | Description |
|---|---|---|
externalId | string | Your system’s unique identifier for the batch. Required and unique per firm: a second batch with the same value is rejected with 409 Conflict, so it is safe to retry a submissionExample: my_batch_2026_12 |
items | array | The tax payments to schedule, between 1 and 5,000 items. See Batch Item Structure below |
Batch Item Structure:
Each item has the same fields as Schedule a Tax Payment, plus the taxpayer it belongs to.
| Field | Type | Description |
|---|---|---|
taxpayerId | guid | Taxpayer of the firm the tax payment belongs to Example: 029bc3f4-d65e-73f7-8133-f5800e825510 |
externalId | string | (Optional) Your system’s unique identifier for the tax payment Example: my_tax_payment_123 |
taxAccountId | guid | Associated tax account identifier Example: 059bc3f4-d65e-73f7-8133-f5800e825513 |
bankAccountId | guid | (Optional) Funding bank account for the payment Example: 049bc3f4-d65e-73f7-8133-f5800e825512 |
paymentTypeId | number | Type of the tax payment, see the Available Payment Types page Example: 10101 |
periodEndDate | date | End date of the tax period the payment covers Example: 2026-12-31 |
paymentDate | date | Scheduled payment date Example: 2026-12-31 |
amount | decimal | Payment amount Example: 100.00 |
externalId values (batch and item) must be 3 to 100 characters long and contain only letters, numbers, spaces, underscores, commas, periods or hyphens.
HTTP Request:
POST https://public-api.remitian.com/v1/firms/{firmId}/tax-payment-batches
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY
{
"externalId": "my_batch_2026_12",
"items": [
{
"taxpayerId": "029bc3f4-d65e-73f7-8133-f5800e825510",
"externalId": "my_tax_payment_123",
"taxAccountId": "059bc3f4-d65e-73f7-8133-f5800e825513",
"paymentTypeId": 10101,
"periodEndDate": "2026-12-31",
"paymentDate": "2026-12-31",
"amount": 100.00
},
{
"taxpayerId": "029bc3f4-d65e-73f7-8133-f5800e825510",
"externalId": "my_tax_payment_124",
"taxAccountId": "059bc3f4-d65e-73f7-8133-f5800e825513",
"paymentTypeId": 10101,
"periodEndDate": "2026-12-31",
"paymentDate": "2027-01-15",
"amount": 250.00
}
]
}
HTTP Response:
HTTP/1.1 201 Created
Content-Type: application/json
Location: /v1/firms/{firmId}/tax-payment-batches/{batchId}
{
"id": "079bc3f4-d65e-73f7-8133-f5800e825515",
"status": "Requested",
"totalItems": 2
}
Validation:
The submission validates the batch shape only. The content of each item (taxpayer, tax account, bank account, payment type, amount, dates) is validated when the item is scheduled, so an item with invalid data does not reject the batch: it fails on its own and the other items continue. Properties that are not part of the item structure are ignored and not stored.
Validation errors name the property in the response body:
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
"Items": [
"A batch carries at most 5000 items."
]
}
}
Get a Batch
Sequence of Events:
- Your system requests a batch by the
idreturned on submission - Remitian responds with the batch status and its counters
HTTP Request:
GET https://public-api.remitian.com/v1/firms/{firmId}/tax-payment-batches/{batchId}
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY
HTTP Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "079bc3f4-d65e-73f7-8133-f5800e825515",
"externalId": "my_batch_2026_12",
"status": "Processed",
"requestedAt": "2026-12-01T14:00:00Z",
"processedAt": "2026-12-01T14:20:00Z",
"totalItems": 2,
"succeededItems": 1,
"failedItems": 1
}
Batch Object Structure:
| Field | Type | Description |
|---|---|---|
id | guid | Unique identifier for the batch Example: 079bc3f4-d65e-73f7-8133-f5800e825515 |
externalId | string | Your system’s identifier for the batch Example: my_batch_2026_12 |
status | string | Batch status, see Batch Statuses above Example: Processed |
requestedAt | datetime | When the batch was submitted Example: 2026-12-01T14:00:00Z |
processedAt | datetime | (Optional) When the batch became Processed. Absent while it is RequestedExample: 2026-12-01T14:20:00Z |
totalItems | number | Number of items in the batch Example: 2 |
succeededItems | number | Number of items that created a tax payment Example: 1 |
failedItems | number | Number of items that failed Example: 1 |
Find a Batch by External ID
Sequence of Events:
- Your system lists the firm’s batches, filtered by the
externalIdit submitted - Remitian responds with a paginated list that holds the matching batch, or no batch
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
externalId | string | (Optional) Filter by your system’s batch ID. Single value: the external ID can contain commas, so it is never split Example: my_batch_2026_12 |
pageNumber | number | Page to retrieve Example: 1 |
pageSize | number | Items per page Example: 10 |
HTTP Request:
GET https://public-api.remitian.com/v1/firms/{firmId}/tax-payment-batches?externalId=my_batch_2026_12
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY
HTTP Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"items": [
{
"id": "079bc3f4-d65e-73f7-8133-f5800e825515",
"externalId": "my_batch_2026_12",
"status": "Processed",
"requestedAt": "2026-12-01T14:00:00Z",
"processedAt": "2026-12-01T14:20:00Z",
"totalItems": 2,
"succeededItems": 1,
"failedItems": 1
}
],
"currentPage": 1,
"pageSize": 10,
"totalCount": 1,
"totalPages": 1
}
An unknown externalId returns 200 OK with an empty items list. Without the filter, the firm’s batches are returned paginated.
List Batch Items
Sequence of Events:
- Your system requests the items of a batch, optionally filtered by
statusand/orexternalIds - Remitian responds with a paginated list of items, ordered as they were submitted
- Your system resubmits the failed items in a new batch after correcting them
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
status | string | (Optional) Filter by item status, see Batch Item Statuses above Example: Failed |
externalIds | string | (Optional) Filter by your system’s tax payment ID. Comma-separated for multiple values Example: my_tax_payment_123,my_tax_payment_124 |
pageNumber | number | Page to retrieve Example: 1 |
pageSize | number | Items per page Example: 10 |
HTTP Request:
GET https://public-api.remitian.com/v1/firms/{firmId}/tax-payment-batches/{batchId}/items?status=Failed
Authorization: Bearer YOUR_ACCESS_TOKEN
x-api-key: YOUR_API_KEY
HTTP Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"items": [
{
"id": "089bc3f4-d65e-73f7-8133-f5800e825516",
"sequence": 2,
"externalId": "my_tax_payment_124",
"status": "Failed",
"errorCode": "TaxAccount.NotFound",
"errorMessage": "The tax account 059bc3f4-d65e-73f7-8133-f5800e825513 was not found."
}
],
"currentPage": 1,
"pageSize": 10,
"totalCount": 1,
"totalPages": 1
}
Batch Item Object Structure:
| Field | Type | Description |
|---|---|---|
id | guid | Unique identifier for the batch item Example: 089bc3f4-d65e-73f7-8133-f5800e825516 |
sequence | number | Position of the item in the submitted items list, starting at 1Example: 2 |
externalId | string | (Optional) Your system’s identifier for the tax payment, when it was submitted Example: my_tax_payment_124 |
status | string | Item status, see Batch Item Statuses above Example: Failed |
taxPaymentId | guid | (Optional) Tax payment created by the item, when it SucceededExample: 069bc3f4-d65e-73f7-8133-f5800e825514 |
errorCode | string | (Optional) Error code, when the item Failed. Treat it as an opaque value: use it for logging and support, and do not parse itExample: TaxAccount.NotFound |
errorMessage | string | (Optional) Human-readable error description, when the item Failed. Its wording can changeExample: The tax account 059bc3f4-d65e-73f7-8133-f5800e825513 was not found. |
The submitted item payload is never returned.
Batch Processed Webhook
When a batch becomes Processed, Remitian delivers the batch.Processed.v1 event to the webhook configured for the firm, once per batch. Subscribe to it in the Webhooks section of the Developer Portal. A firm without an active webhook configuration receives nothing.
Webhook Delivery:
POST https://your-system.example.com/remitian/webhooks
Content-Type: application/json
payload-signature: BASE64_HMAC_SHA256_SIGNATURE
{
"id": "019b2a7f-2d45-7f01-9b3c-1a6e7d2f4b53",
"eventType": "batch.Processed.v1",
"createdAtUtc": "2026-12-01T14:20:00Z",
"data": {
"id": "079bc3f4-d65e-73f7-8133-f5800e825515",
"firm": {
"id": "019b1f0e-6a4c-7d21-9b3e-2c8f5a7d4e10",
"externalId": "FIRM-1042"
},
"externalId": "my_batch_2026_12",
"actionType": "ScheduleCreation",
"totalItems": 2,
"succeededItems": 1,
"failedItems": 1
}
}
| Field | Description |
|---|---|
id | Batch identifier |
firm.id | Firm the batch belongs to |
firm.externalId | Your external identifier for the firm; null when the firm has none |
externalId | Your system’s identifier for the batch |
actionType | What the batch does. ScheduleCreation for a tax payment batch |
totalItems | Number of items in the batch |
succeededItems | Number of items that created a tax payment |
failedItems | Number of items that failed. When it is greater than zero, use List Batch Items with status=Failed to find them |
Error Handling
| HTTP Status | When it happens |
|---|---|
400 Bad Request | Submit: externalId is missing or invalid, items is missing or empty, the batch has more than 5,000 items, an item is null, an item misses a required field, or an item externalId is invalid. Lists: a filter or page parameter is invalid |
401 Unauthorized | The Authorization header is missing or invalid |
403 Forbidden | The caller cannot manage the clients of the firm in the route |
404 Not Found | The firm does not exist, or (Get a Batch and List Batch Items) the batch does not exist or belongs to another firm |
409 Conflict | Submit: the firm already submitted a batch with the same externalId. The response names the existing batch |
Limitations
- At launch, batches are processed for US tax payments only.
- A batch holds at most 5,000 items.