Create a transaction batch

post

https://api.brinta.com/transaction-batches/

Submits up to 10,000 transactions for asynchronous ingestion.

Every element of transactions is the exact body you would send toPOST /sales/, POST /refunds/ , or POST /transfers/, depending ontransaction_type.

Three rules differ from the single-resource endpoints:

transaction_external_id is required and must be unique within the batch. It is both the correlation key for results and the deduplication key for retries.
The per-transaction type field may be omitted (it is inherited from transaction_type), but if present it must match.
Refunds may reference the original sale by your own identifier using original_transaction_external_id .

The response is always 202.

Use links.self to poll for progress, or listen to the webhook when the batch finishes.

Body Params

transaction_type

string

enum

required

The kind of transaction carried by every entry in the batch. Uses the same
vocabulary as the type field on the single-resource endpoints, and
determines which one each entry is routed to.

Value	Processed as
`sale`	`POST /sales/`
`refund`, `chargeback`, `adjustment`	`POST /refunds/`
`transfer`, `transfer reversal`, `to settle`, `settlement`, `payment from invoice`	`POST /transfers/`

calculation is deliberately absent: batches never run the tax engine.

options

object

transactions

array

required

length between 1 and 10000

Each element is the exact body of POST /sales/, POST /refunds/ or
POST /transfers/, selected by transaction_type.
transaction_external_id is required and must be unique within the
batch. The per-transaction type may be omitted (inherited from
transaction_type) but must match if present. Taxes must be supplied by
you; the tax engine does not run. Refunds must reference the original
sale through exactly one of original_transaction_id or
original_transaction_external_id.

transactions*

transaction_owner_company_id

string

Company ID in Brinta's system. Defaults to the authenticated client.

transaction_external_id

string

required

Your identifier for this transaction. Required in batches: it correlates
results back to your records and deduplicates retries.

type

string

enum

Optional. Inherited from transaction_type; must match if present.

Allowed:

status

string

enum

Allowed:

currency

string

required

exchange_rate

number

invoice_number

string

invoice_date

date

Required when status is invoiced.

additional_info

string

payment_method

object

payment_model

object

payment_methods

array of objects

payment_methods

buyer

required

Identify the counterparty in one of three ways: by Brinta company ID, by your
own external ID, or by supplying the full company object.

items

array of objects

required

length ≥ 1

items*

Headers

Idempotency-Key

uuid

required

A client-generated UUID identifying this logical load attempt.

Replaying the same key with the same body within 24 hours returns the
original batch_id without re-queuing anything. Replaying it with a
different body returns 409. Scoped per company.

Responses

Language

Credentials

Bearer

JWT

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

202Batch accepted and queued. Poll links.self or wait for the webhook.

400Malformed JSON.

401Missing or invalid token.

403No permission over the transaction_owner_company_id of one or more transactions.

409The Idempotency-Key was already used with a different payload.

413Request body exceeds 10 MB.

429Rate limit exceeded.

503The ingestion queue is saturated. Retry after the indicated delay.