Bulk operations

A bulk operation runs thousands of records in one request: the input is an NDJSON file, and the result says what happened to every line.

Loading the search index…

Bulk operations

Operation types

typeA line of the inputScope
inventory.setThe body of setting stock.inventory:write
products.upsertThe body of writing a product by external ID, plus external_id and, if you want the version checked, version.catalog:write
money_transactions.createThe body of recording manual income or expense.finance:write
money_transactions.updateThe body of updating a money transaction, plus the transaction id and, if you want the version checked, version. This is how you categorize the journal in bulk.finance:write
orders.exportNo input: the operation exports the orders by the filters in params.orders:read
libro_iva.exportNo input: the operation builds the Libro IVA Digital books of a legal entity for a month — params carry legal_entity_id, period (YYYY-MM) and books (ventas, compras or both).fiscal:read
accountant_package.exportNo input: the operation builds the accountant package of a legal entity for a month — params carry legal_entity_id and period.fiscal:read

Starting an operation needs bulk:write besides the scope of its type. Each line goes through the same checks as the single endpoint and gets the same response, so a line that fails does not stop the others.

Prepare the input

NDJSON is one JSON object per line. A file of stock levels:

NDJSON
{"variant_id": 1042, "location_id": 3, "on_hand": "24", "expected_on_hand": "20"}
{"variant_id": 1043, "location_id": 3, "on_hand": "0", "expected_on_hand": "5"}
{"variant_id": 2210, "location_id": 3, "on_hand": "12.5", "expected_on_hand": "12.5"}

The file may be up to 256 MB, a line up to 1 MB; a file compressed with gzip is unpacked on the way in. Upload it in chunks, or give the operation the url of the file instead and the store downloads it itself.

Upload in chunks

Start an upload with the name and size of the file. The response tells the size of a chunk, chunk_bytes, up to 1 MB:

Request
curl -X POST "https://api.saleya.app/v1/uploads" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'Idempotency-Key: 3c2b1a09-8f7e-4d6c-b5a4-938271605f4e' \
  -H "Content-Type: application/json" \
  -d '{
  "file_name": "stock-2026-11-11.ndjson",
  "size": 3407872
}'
Response
HTTP/1.1 201 Created

{
  "id": 55,
  "file_name": "stock-2026-11-11.ndjson",
  "size": 3407872,
  "received": 0,
  "complete": false,
  "chunk_bytes": 1048576,
  "expires_at": "2026-11-12T14:30:00Z",
  "created_at": "2026-11-11T14:30:00Z"
}

Send the file in order, one chunk per request: the raw bytes as the body and the byte the chunk starts at in offset. When received reaches the size, the upload is complete.

Request
curl -X POST "https://api.saleya.app/v1/uploads/55/chunks?offset=1048576" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'Idempotency-Key: 7e6d5c4b-3a29-4180-9f8e-7d6c5b4a3928' \
  -H "Content-Type: application/octet-stream" \
  --data-binary '@stock.part-01'

After a broken connection, read the upload and continue from received. A chunk with another offset gets 409 upload_offset_mismatch, and the response tells the right one.

Start the operation

Request
curl -X POST "https://api.saleya.app/v1/bulk-operations" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'Idempotency-Key: 2b1a0f9e-8d7c-4b6a-9594-837261504f3e' \
  -H "Content-Type: application/json" \
  -d '{
  "type": "inventory.set",
  "input": {
    "upload_id": 55
  }
}'

The response is 202 with the operation and its address in Location. Operations of an app run one at a time, in the order they were created; up to 5 can wait or run at once, and one more gets 409 bulk_operation_queue_full.

Follow it with GET /bulk-operations/{operation} — status and the counters of lines — or wait for the bulk_operation.finished webhook. Cancelling stops the operation between two lines: what was written stays.

Read the result

The result is NDJSON too: a line per input line with its number, the status it would get as a separate request and the response — the record or the error.

NDJSON
{"line": 1, "status": 200, "body": {"status": "applied", "inventory_level": {"variant_id": 1042, "location_id": 3, "on_hand": "24", "reserved": "2", "available": "22", "updated_at": "2026-11-11T14:31:02Z"}}}
{"line": 2, "status": 409, "body": {"type": "stock_on_hand_changed", "title": "On-hand quantity changed", "status": 409, "detail": "The on-hand quantity is 4, not 5: stock moved after it was read. Read the level again and repeat the request with the new expected_on_hand.", "current": {"on_hand": "4"}}}
{"line": 3, "status": 200, "body": {"status": "unchanged", "inventory_level": {"variant_id": 2210, "location_id": 3, "on_hand": "12.5", "reserved": "0", "available": "12.5", "updated_at": "2026-11-10T09:12:44Z"}}}

The result can be read while the operation runs: it only grows. Continue a download with Range: bytes=<downloaded>-. A result of orders.export is the orders themselves, and the finished export gives a sync_cursor to continue the list of orders from.

For libro_iva.export and accountant_package.export the result is not NDJSON but a ZIP with the same files the store dashboard exports. It appears in full once the operation is completed; before that, and for a failed operation, the result answers 409. If the book cannot be built because of documents of the period, the operation ends failed, and error.documents names every document and the reason.

The operation and its files are kept for 7 days after it ends.

Next guideWebhooks