1. Use Case 8: Schedule Tax Payments
  2. Tax Payment Batches

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:

  1. Your system submits the batch with its own externalId (Submit a Batch)
  2. Remitian responds with 201 Created and the batch id
  3. Remitian schedules each item in the background
  4. When every item has succeeded or failed, the batch becomes Processed and Remitian sends batch.Processed.v1
  5. Your system reads the batch counters (Get a Batch or Find a Batch by External ID) and the failed items (List Batch Items)
  6. Your system corrects the failed items and submits them in a new batch

Batch Statuses:

StatusMeaning
RequestedThe batch was accepted and its items are being scheduled
ProcessedEvery item of the batch has succeeded or failed

Batch Item Statuses:

StatusMeaning
PendingThe item is waiting to be scheduled
ProcessingThe item is being scheduled
SucceededThe tax payment was created. taxPaymentId identifies it
FailedThe tax payment was not created. errorCode and errorMessage describe why

​
Submit a Batch

Sequence of Events:

  1. Your system sends the batch with its own externalId and the list of tax payments to schedule
  2. Remitian validates the batch shape and stores it with status Requested
  3. Remitian responds with 201 Created, the batch id and the number of items accepted

Batch Request Structure:

FieldTypeDescription
externalIdstringYour 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 submission
Example: my_batch_2026_12
itemsarrayThe 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.

FieldTypeDescription
taxpayerIdguidTaxpayer of the firm the tax payment belongs to
Example: 029bc3f4-d65e-73f7-8133-f5800e825510
externalIdstring(Optional) Your system’s unique identifier for the tax payment
Example: my_tax_payment_123
taxAccountIdguidAssociated tax account identifier
Example: 059bc3f4-d65e-73f7-8133-f5800e825513
bankAccountIdguid(Optional) Funding bank account for the payment
Example: 049bc3f4-d65e-73f7-8133-f5800e825512
paymentTypeIdnumberType of the tax payment, see the Available Payment Types page
Example: 10101
periodEndDatedateEnd date of the tax period the payment covers
Example: 2026-12-31
paymentDatedateScheduled payment date
Example: 2026-12-31
amountdecimalPayment 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:

  1. Your system requests a batch by the id returned on submission
  2. 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:

FieldTypeDescription
idguidUnique identifier for the batch
Example: 079bc3f4-d65e-73f7-8133-f5800e825515
externalIdstringYour system’s identifier for the batch
Example: my_batch_2026_12
statusstringBatch status, see Batch Statuses above
Example: Processed
requestedAtdatetimeWhen the batch was submitted
Example: 2026-12-01T14:00:00Z
processedAtdatetime(Optional) When the batch became Processed. Absent while it is Requested
Example: 2026-12-01T14:20:00Z
totalItemsnumberNumber of items in the batch
Example: 2
succeededItemsnumberNumber of items that created a tax payment
Example: 1
failedItemsnumberNumber of items that failed
Example: 1

​
Find a Batch by External ID

Sequence of Events:

  1. Your system lists the firm’s batches, filtered by the externalId it submitted
  2. Remitian responds with a paginated list that holds the matching batch, or no batch

Query Parameters:

ParameterTypeDescription
externalIdstring(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
pageNumbernumberPage to retrieve
Example: 1
pageSizenumberItems 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:

  1. Your system requests the items of a batch, optionally filtered by status and/or externalIds
  2. Remitian responds with a paginated list of items, ordered as they were submitted
  3. Your system resubmits the failed items in a new batch after correcting them

Query Parameters:

ParameterTypeDescription
statusstring(Optional) Filter by item status, see Batch Item Statuses above
Example: Failed
externalIdsstring(Optional) Filter by your system’s tax payment ID. Comma-separated for multiple values
Example: my_tax_payment_123,my_tax_payment_124
pageNumbernumberPage to retrieve
Example: 1
pageSizenumberItems 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:

FieldTypeDescription
idguidUnique identifier for the batch item
Example: 089bc3f4-d65e-73f7-8133-f5800e825516
sequencenumberPosition of the item in the submitted items list, starting at 1
Example: 2
externalIdstring(Optional) Your system’s identifier for the tax payment, when it was submitted
Example: my_tax_payment_124
statusstringItem status, see Batch Item Statuses above
Example: Failed
taxPaymentIdguid(Optional) Tax payment created by the item, when it Succeeded
Example: 069bc3f4-d65e-73f7-8133-f5800e825514
errorCodestring(Optional) Error code, when the item Failed. Treat it as an opaque value: use it for logging and support, and do not parse it
Example: TaxAccount.NotFound
errorMessagestring(Optional) Human-readable error description, when the item Failed. Its wording can change
Example: 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
  }
}
FieldDescription
idBatch identifier
firm.idFirm the batch belongs to
firm.externalIdYour external identifier for the firm; null when the firm has none
externalIdYour system’s identifier for the batch
actionTypeWhat the batch does. ScheduleCreation for a tax payment batch
totalItemsNumber of items in the batch
succeededItemsNumber of items that created a tax payment
failedItemsNumber of items that failed. When it is greater than zero, use List Batch Items with status=Failed to find them

​
Error Handling

HTTP StatusWhen it happens
400 Bad RequestSubmit: 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 UnauthorizedThe Authorization header is missing or invalid
403 ForbiddenThe caller cannot manage the clients of the firm in the route
404 Not FoundThe firm does not exist, or (Get a Batch and List Batch Items) the batch does not exist or belongs to another firm
409 ConflictSubmit: 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.