Operation types
type | A line of the input | Scope |
|---|---|---|
inventory.set | The body of setting stock. | inventory:write |
products.upsert | The body of writing a product by external ID, plus external_id and, if you want the version checked, version. | catalog:write |
money_transactions.create | The body of recording manual income or expense. | finance:write |
money_transactions.update | The 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.export | No input: the operation exports the orders by the filters in params. | orders:read |
libro_iva.export | No 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.export | No 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:
{"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:
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
}'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.
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
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.
{"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.