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 batch

On https://api-test.brinta.com a 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 calculate

Every 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, use POST /sales/ one transaction at a time.

How it works

  1. POST /batches/transactions/{transaction_type} with an NDJSON body. Brinta answers 202 with a batch_id.
  2. GET /batches/transactions/{batch_id} until status is final. The response carries the summary counters.
  3. GET /batches/transactions/{batch_id}/results?status=failed to 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.ndjson

Use --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:

Pathtransaction_type in responsesEach line is the body of
/batches/transactions/salesalePOST /sales/
/batches/transactions/refundrefundPOST /refunds/
/batches/transactions/chargebackchargebackPOST /refunds/
/batches/transactions/adjustmentadjustmentPOST /refunds/
/batches/transactions/transfertransferPOST /transfers/
/batches/transactions/transfer-reversaltransfer reversalPOST /transfers/
/batches/transactions/to-settleto settlePOST /transfers/
/batches/transactions/settlementsettlementPOST /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_id is 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 with type fails with error_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 first

A 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
}
⚠️

A 202 does not mean your transactions were stored

It means the batch was accepted. Lines can still fail. Always read summary.failed before 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:

statusMeaning
receivingBrinta is still reading the request body.
processingLines are being processed.
completedFinished, no line failed.
completed_with_errorsFinished, at least one line failed and at least one succeeded or was skipped.
failedFinished, 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 }
}
  • index is the zero-based position of the line in your body. Blank lines are not counted.
  • error_field points at the value to fix, relative to the line. It is absent when the error is not tied to one field.
  • http_status appears 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 id Brinta assigned. Read the stored transaction with GET /sales/{id}, GET /refunds/{id} or GET /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

StatusMeaningStored in Brinta?
pendingWaiting to be processedNot yet
processingBeing createdNot yet
succeededCreated by this batchYes, new
skippedIdentical to a transaction already sent, nothing doneYes, from the earlier send
failedRejected by validation, or failed to be createdNo

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

LimitValue
Lines per batch10,000 in Production, 50 in Test
Batches in progress per company1
Results page size50 by default, 100 max
🚧

Lines over the limit are not read

Lines 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.total matches 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 guaranteed

Lines 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:

StatusWhen
400Content-Type is not application/x-ndjson, Idempotency-Key is missing, or the type in the path is not accepted.
401Missing or invalid token.
409Another 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.


Did this page help you?