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
encryptedPayload	string	Required	AES-256-GCM encrypted credentials. See Encryption Guide.
filingId	string	Required	Unique idempotency key for this batch. Prevents duplicate submissions.
month	number	Required	Numeric month being filed. Valid values: `1`–`12`.
year	number	Required	4-digit filing year (e.g. `2024`).
data	array	Required	Array of VAT line item objects. Each object follows the same schema as a single filing item (see below).

data[ ] — Line Item Schema

Field	Type	Required	Description
vatStatus	number	Required	`0` VATABLE · `1` ZERO RATED · `2` VAT EXEMPT
amount	number	Required	Invoice amount exclusive of VAT.
item	string	Required	Name or category of the product or service.
taxId	string	Required	Customer Tax ID. Use `"0"` for B2C or unregistered customers.
narration	string	Optional	Invoice reference line or detailed context for the item.
beneficiary	string	Optional	Customer name. Defaults to `"Retail Customer"` if omitted.

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 '{
   "encryptedPayload": "encrypted_string_a1b2c3...",
   "filingId": "batch-123-abuiod-90",
   "month": 1,
   "year": 2024,
   "data": [
      {
         "vatStatus": 1,
         "amount": 5000,
         "item": "Baby diapers",
         "narration": "Bought kisskid diaper",
         "taxId": "1234567890123123",
         "beneficiary": "Retail Customer"
      },
      {
         "vatStatus": 0,
         "amount": 12000,
         "item": "Enterprise Software",
         "narration": "Annual license",
         "taxId": "9876543210987654",
         "beneficiary": "Acme Corp"
      }
   ]
}'

Example Response

202 Accepted

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