Bulk writes

Open in the interactive reference

Some resources have bulk endpoints, which create or delete many records in one call. Most are POST <resource>/bulk and POST <resource>/bulk-delete; a few other endpoints restore or update several records at once. Check a resource's endpoints before you plan a batch.

A bulk call is one transaction. Either every entry is written or none is, and one invalid entry fails the whole call. To write entries independently, call the single-record endpoint once per entry. A bulk call accepts an Idempotency-Key like any other write.

On most bulk endpoints, an error about one entry names it by its index, its position in the input array, in the diagnostic's details. The rest of details varies by endpoint; its error list shows the shape.

Do not send an empty batch. Some bulk endpoints refuse one, for example with NOTHING_TO_CREATE; others accept it and write nothing.

A successful call usually returns one result per entry, in input order, including each new id for a bulk create. What exactly comes back varies by endpoint, and its response shows it.

Examples

A bulk create

POST /inventory/items/bulk
{ "items": [ … ] }

HTTP/1.1 200 OK

{ "data": { "created": [
    { "id": "9f2c…", "itemCode": "WIDGET-01" },
    { "id": "3b7d…", "itemCode": "WIDGET-02" }
] } }

One bad entry

{
  "error": {
    "code": "DUPLICATE_CODE",
    "message": "…",
    "diagnostics": [
      {
        "code": "DUPLICATE_CODE",
        "severity": "error",
        "message": "…",
        "details": {
          "itemCode": "WIDGET-01",
          "index": 3
        }
      }
    ]
  }
}