DOCS/flux/vat-filing

Batch VAT Filing

Authentication Required

This endpoint requires a valid API key in the x-api-key header of every request.

The Batch VAT Filing API processes multiple Value Added Tax transactions in a single request. Ideal for end-of-day reconciliation flows, bulk invoice uploads, or ERP integrations where many line items accumulate before submission.

Integration Flow

1Encrypt Credentials: Generate your encryptedPayload once per request — it covers all items in the batch.
2Assemble the Batch: Collect all VAT line items into the data array.
3Handle Result: Listen for vat.filing.success webhooks — one event is emitted per batch.

HTTP Request

POSThttps://api.taxstreem.com/v1/vat/filing/batch

Request Body

Top-level parameters for the batch request.

Parameter	Type	Required	Description
batchId	string	Required	Unique idempotency key for this batch request. Prevents duplicate batch submissions.
payload	array	Required	Array of filing item objects to be processed in batch (see schema below).

payload[ ] — Batch Filing Item Schema

Field	Type	Required	Description
encryptedPayload	string	Required	AES-256-GCM encrypted TaxPromax credentials. See Encryption Guide.
filingId	string	Required	Unique filing identifier / idempotency key for this item.
month	number	Required	Numeric month being filed (`1`–`12`).
year	number	Required	4-digit filing year (e.g. `2026`).
vatAmount	number	Required	Total VAT amount to file.
taxId	string	Required	Tax Identification Number (TIN) for the business entity.
interestAmount	number	Required	Accrued interest amount if filing past statutory deadline.
penaltyAmount	number	Required	Late filing penalty amount if applicable.
scheduleUrl	string	Required	URL to the uploaded filing schedule document (CSV, Excel, or PDF).

Encrypted Payload

FLUX requires sensitive credentials to be encrypted at the application layer. One encryptedPayload covers the entire batch.

The encryptedPayload must be a Base64-encoded AES-256-GCM encrypted JSON object containing your TaxPromax email and password.

Response

Returns 202 Accepted on success. Filing is processed asynchronously — listen for the vat.filing.success webhook for the final outcome.

HTTP Status	Error Key	Cause & Resolution
400	Bad Request	Missing or invalid fields. Check the `errors` array for field-level detail.
401	Unauthorized	Missing or invalid `x-api-key` header.
429	Too Many Requests	Rate limit exceeded. Backoff using the `Retry-After` header.

Example Request

curl -X POST https://api.taxstreem.com/v1/vat/filing/batch \
  -H "x-api-key: txsm_test_SK489c..." \
  -H "Content-Type: application/json" \
  -d '{
   "batchId": "batch_2343dfw",
   "payload": [
      {
         "encryptedPayload": "aXZJVkpTT05...YWx1ZQ==",
         "filingId": "filing_2343dfw",
         "month": 1,
         "year": 2026,
         "vatAmount": 0,
         "taxId": "",
         "interestAmount": 0,
         "penaltyAmount": 0,
         "scheduleUrl": ""
      }
   ]
}'

Example Response

202 Accepted

{
  "status":  "accepted",
  "message":  "schedule accepted successfully",
  "data":  {
    "id":  "xaee2ddf-batch-90",
    "created_at":  "2026-02-20T10:00:00Z"
  }
}