Sending transactions in batches
Submit up to 10,000 pre-calculated sales, refunds or transfers in a single request, with per-transaction results and safe retries.
If you send Brinta a high volume of transactions, calling POST /sales/ once per record gets expensive: every transaction costs a TLS handshake, a token validation and a full round trip.
The Batch API lets you send up to 10,000 transactions in one request, as a stream of one JSON object per line, and track the whole load as a single batch.
Test environment: 50 transactions per batchOn
https://api-test.brinta.coma batch accepts only 50 lines. Lines after the 50th are not processed and do not appear in the summary or the results. Production accepts up to 10,000. Size your test loads accordingly.
Batches store, they do not calculateEvery transaction in a batch is stored with
use_tax_engine: false. You send the taxes on each item and Brinta validates and stores them. If you need Brinta to calculate taxes, usePOST /sales/one transaction at a time.
How it works
POST /batches/transactions/{transaction_type}with an NDJSON body. Brinta answers202with abatch_id.GET /batches/transactions/{batch_id}untilstatusis final. The response carries thesummarycounters.GET /batches/transactions/{batch_id}/results?status=failedto see which lines failed and why.
Sending a batch
The body is NDJSON: one transaction per line, each a complete JSON object, separated by a newline. Send it with Content-Type: application/x-ndjson and an Idempotency-Key header.
cat > sales.ndjson <<'EOF'
{"transaction_external_id":"SALE-0001","status":"invoiced","invoice_date":"2026-10-01","currency":"ARS","buyer":{"company":{"type":"business","name":"Example Corp","external_id":"CUST-0001","address":{"country":"AR","state":"AR-C"},"tax_registrations":[{"number":"30000000007","type":"CUIT","location":"AR","level":"country"}]}},"items":[{"name":"Item 1","amount":100,"taxes":[]}]}
{"transaction_external_id":"SALE-0002","status":"invoiced","invoice_date":"2026-10-01","currency":"ARS","buyer":{"company":{"type":"business","name":"Example Corp","external_id":"CUST-0001","address":{"country":"AR","state":"AR-C"},"tax_registrations":[{"number":"30000000007","type":"CUIT","location":"AR","level":"country"}]}},"items":[{"name":"Item 2","amount":100,"taxes":[]}]}
EOF
curl -X POST https://api.brinta.com/batches/transactions/sale \
-H "Authorization: Bearer $BRINTA_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/x-ndjson" \
--data-binary @sales.ndjsonUse --data-binary, not -d: -d strips the newlines that separate the lines.
The transaction type goes in the path
Every batch carries one type of transaction, set in the path. Each line is validated as the body of the matching single-resource endpoint:
| Path | transaction_type in responses | Each line is the body of |
|---|---|---|
/batches/transactions/sale | sale | POST /sales/ |
/batches/transactions/refund | refund | POST /refunds/ |
/batches/transactions/chargeback | chargeback | POST /refunds/ |
/batches/transactions/adjustment | adjustment | POST /refunds/ |
/batches/transactions/transfer | transfer | POST /transfers/ |
/batches/transactions/transfer-reversal | transfer reversal | POST /transfers/ |
/batches/transactions/to-settle | to settle | POST /transfers/ |
/batches/transactions/settlement | settlement | POST /transfers/ |
Types with a space use a hyphen in the path. Any other value returns 400.
What each line looks like
Each line is the body you would send to the single-resource endpoint, with these rules:
transaction_external_idis required. It is how results are matched to your records and how retries are deduplicated.- Do not send
type. The type comes from the path. A line withtypefails witherror_field: "type". - No extra fields. A field the single-resource endpoint does not accept fails the line with
Unknown field: '<name>'. - Blank lines are ignored.
A line that fails these rules is recorded as failed with its reason. The rest of the batch carries on.
Refunds, chargebacks and adjustments
POST /refunds/ identifies the original sale with original_transaction_id, Brinta's id. In a batch you can reference it by your own id with original_transaction_external_id, so you don't have to look up Brinta ids first:
{"transaction_external_id":"REF-0001","original_transaction_external_id":"SALE-0001","status":"refunded","invoice_date":"2026-10-02","items":[{"amount":40}]}Send one of original_transaction_external_id or original_transaction_id. The same body works for /batches/transactions/chargeback and /batches/transactions/adjustment.
The sale has to exist firstA batch holds one type, so a refund batch cannot include the sale it refers to. Send the sales, wait for that batch to finish, then send the refunds.
Transfers
Transfer, transfer reversal, to settle and settlement batches take the POST /transfers/ body on each line:
{"transaction_external_id":"TRF-0001","status":"pending","currency":"ARS","transaction_date":"2026-10-03","counterpart":{"company":{"type":"business","name":"Example Corp","external_id":"CUST-0001","address":{"country":"AR","state":"AR-C"},"tax_registrations":[{"number":"30000000007","type":"CUIT","location":"AR","level":"country"}]}},"items":[{"name":"Transfer 1","amount":100,"taxes":[]}]}Getting the result
Brinta reads and validates the lines as they arrive, queues the valid ones, and then answers 202 Accepted:
{
"batch_id": "3f6c2a1e-8b4d-4f7a-9c2e-1d5b7a9e0c42",
"kind": "transactions",
"transaction_type": "sale",
"status": "processing",
"created_at": "2026-10-13T14:31:00.000Z",
"completed_at": null
}
A202does not mean your transactions were storedIt means the batch was accepted. Lines can still fail. Always read
summary.failedbefore you consider a load complete.
Read the batch to follow its progress. The summary is only in this response, not in the 202:
curl https://api.brinta.com/batches/transactions/3f6c2a1e-8b4d-4f7a-9c2e-1d5b7a9e0c42 \
-H "Authorization: Bearer $BRINTA_TOKEN"{
"batch_id": "3f6c2a1e-8b4d-4f7a-9c2e-1d5b7a9e0c42",
"kind": "transactions",
"transaction_type": "sale",
"status": "completed_with_errors",
"created_at": "2026-10-13T14:31:00.000Z",
"completed_at": "2026-10-13T14:31:03.000Z",
"summary": { "total": 3, "succeeded": 1, "skipped": 0, "failed": 2, "pending": 0 }
}Poll every few seconds until status is one of the final values:
status | Meaning |
|---|---|
receiving | Brinta is still reading the request body. |
processing | Lines are being processed. |
completed | Finished, no line failed. |
completed_with_errors | Finished, at least one line failed and at least one succeeded or was skipped. |
failed | Finished, every line failed. |
Reading per-transaction results
curl "https://api.brinta.com/batches/transactions/3f6c2a1e-8b4d-4f7a-9c2e-1d5b7a9e0c42/results?status=failed" \
-H "Authorization: Bearer $BRINTA_TOKEN"{
"data": [
{
"index": 1,
"external_id": "SALE-0002",
"status": "failed",
"id": null,
"errors": [
{ "error_field": "type", "error_detail": "must not be sent in the record, the transaction type is taken from the path" }
]
},
{
"index": 2,
"external_id": "SALE-0003",
"status": "failed",
"id": null,
"errors": [
{ "error_field": "buyer", "error_detail": "must have required property 'buyer'" }
]
}
],
"page": { "next_cursor": null, "has_more": false }
}indexis the zero-based position of the line in your body. Blank lines are not counted.error_fieldpoints at the value to fix, relative to the line. It is absent when the error is not tied to one field.http_statusappears when the line passed validation but creating the transaction failed. It is the status the single-resource endpoint would have returned.- A successful line carries the
idBrinta assigned. Read the stored transaction withGET /sales/{id},GET /refunds/{id}orGET /transfers/{id}.
Filter with status set to succeeded, skipped or failed, or omit it to get every line.
Pagination
Results come in pages of 50 by default. Set limit up to 100 (larger values are treated as 100). When page.has_more is true, send page.next_cursor as cursor to get the next page, with the same status filter:
curl "https://api.brinta.com/batches/transactions/3f6c2a1e-8b4d-4f7a-9c2e-1d5b7a9e0c42/results?limit=2&cursor=$NEXT_CURSOR" \
-H "Authorization: Bearer $BRINTA_TOKEN"The cursor is opaque. A malformed one returns 400.
Line outcomes
| Status | Meaning | Stored in Brinta? |
|---|---|---|
pending | Waiting to be processed | Not yet |
processing | Being created | Not yet |
succeeded | Created by this batch | Yes, new |
skipped | Identical to a transaction already sent, nothing done | Yes, from the earlier send |
failed | Rejected by validation, or failed to be created | No |
Retrying safely
Two independent protections cover two kinds of retry.
Idempotency-Key protects the immediate retry. It is required on every batch: any string of 1 to 250 characters, a UUID is a good choice. If you send a key your company already used, you get the original batch back with 202 and nothing is read or queued again, even if the body is different. A timeout on your side no longer means a duplicated load. Use a new key for every new load.
transaction_external_id protects the later retry, with a new key. A line is skipped when it has the same transaction_external_id and exactly the same content as a line you already sent that succeeded, or that is still being processed. Its result carries the id of the existing transaction. So if your process dies halfway, resend the whole file with a new Idempotency-Key: the lines that already landed come back as skipped and the rest are created. The same applies to a line repeated within one batch.
Failed lines are never counted as sent. Fix them and send them again in a new batch.
Limits
| Limit | Value |
|---|---|
| Lines per batch | 10,000 in Production, 50 in Test |
| Batches in progress per company | 1 |
| Results page size | 50 by default, 100 max |
Lines over the limit are not readLines after the limit (10,000 in Production, 50 in Test), and anything past the request size limit, are not processed and do not appear in the summary or the results. Split larger loads into several batches and check that
summary.totalmatches the number of lines you sent.
Only one batch per company can be in progress at a time. Sending another while one is running returns 409. Wait for the running batch to reach a final status, then send the next one.
Order is not guaranteedLines are processed in parallel and can finish in any order. If you depend on sequential ordering, such as correlative invoice numbering, use the single-resource endpoints.
Errors on the request
These are returned before the batch is created:
| Status | When |
|---|---|
400 | Content-Type is not application/x-ndjson, Idempotency-Key is missing, or the type in the path is not accepted. |
401 | Missing or invalid token. |
409 | Another batch is in progress for your company. |
Problems with a single line (invalid JSON, a missing field, a wrong value) never reject the request. They show up as failed lines in the results.
Updated about 1 month ago
