Batch operations

Upsert up to 100 products or customers in one request, and read the result of each one.

Version v1.1, updated 5 October 2026

On this page

The request
Validation first
One result per item
Partial failure
Idempotency of a batch
Related

A batch sends many upserts of one resource in one request. Products and customers have one, for syncs that move many records at once.

The request

A batch is an object with items, from 1 to 100. Each item has a match, which finds the record, and data, the same body as the upsert of that resource.

Operation	Match by
`POST /v1/products/batch`	`{ "external_id", "source" }`, `{ "sku", "kind" }` with `kind` optional, or `{ "id" }`.
`POST /v1/customers/batch`	`{ "external_id", "source", "match_by" }` with `match_by` optional, or `{ "id" }`.

An item matched by external id or SKU is created when nothing matches. An item matched by id must exist.

Validation first

BIRP checks the whole request before it writes anything. One invalid item, such as a JSON number in a price, answers 422 validation_failed for the whole batch, with paths such as items[3].data.price. Nothing is written.

One result per item

A valid batch answers 200, with one result per item, in the order of the request, and a summary.

200 OKJSON

{
  "data": {
    "results": [
      {
        "id": "00000000-0000-4000-8000-000000000011",
        "index": 0,
        "status": "updated"
      },
      {
        "id": "00000000-0000-4000-8000-000000000012",
        "index": 1,
        "status": "updated"
      },
      {
        "errors": [
          {
            "code": "reference_not_found",
            "field": "match",
            "message": "matches no record of the company"
          }
        ],
        "index": 2,
        "status": "failed"
      }
    ],
    "summary": {
      "created": 0,
      "failed": 1,
      "updated": 2
    }
  }
}

Member	Meaning
`index`	The position of the item in `items`, from 0.
`status`	`created`, `updated` or `failed`.
`id`	The record created or updated.
`errors`	For a failed item: each `code`, `field` and `message`.

Partial failure

Each item is written on its own. An item that fails, for example a SKU taken by another product, leaves the others written. Fix the failed items, then send them in a new batch.

Idempotency of a batch

A batch takes one Idempotency-Key for the whole request. Sending it again with the same key returns the same results, failed items included. A new batch of the failed items needs a new key.

POST /v1/customers/batch

curl -X POST "https://api.birp.io/v1/customers/batch" \
  -H "Authorization: Bearer $BIRP_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"data":{"country_code":"FR","customer_type":"b2b","email":"achats@example.com","name":"Epicerie Exemple SARL"},"match":{"external_id":"cust-77","match_by":["email"],"source":"woocommerce"}},{"data":{"country_code":"US","customer_type":"b2c","email":"jordan.example@example.org","name":"Jordan Example"},"match":{"external_id":"cust-78","source":"woocommerce"}}]}'

const response = await fetch("https://api.birp.io/v1/customers/batch", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BIRP_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "items": [
      {
        "data": {
          "country_code": "FR",
          "customer_type": "b2b",
          "email": "achats@example.com",
          "name": "Epicerie Exemple SARL"
        },
        "match": {
          "external_id": "cust-77",
          "match_by": [
            "email"
          ],
          "source": "woocommerce"
        }
      },
      {
        "data": {
          "country_code": "US",
          "customer_type": "b2c",
          "email": "jordan.example@example.org",
          "name": "Jordan Example"
        },
        "match": {
          "external_id": "cust-78",
          "source": "woocommerce"
        }
      }
    ]
  }),
});
if (!response.ok) throw new Error(`BIRP API error ${response.status}`);
const result = await response.json();

<?php
$ch = curl_init("https://api.birp.io/v1/customers/batch");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BIRP_API_KEY"),
        "Idempotency-Key: " . bin2hex(random_bytes(16)),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
{
  "items": [
    {
      "data": {
        "country_code": "FR",
        "customer_type": "b2b",
        "email": "achats@example.com",
        "name": "Epicerie Exemple SARL"
      },
      "match": {
        "external_id": "cust-77",
        "match_by": [
          "email"
        ],
        "source": "woocommerce"
      }
    },
    {
      "data": {
        "country_code": "US",
        "customer_type": "b2c",
        "email": "jordan.example@example.org",
        "name": "Jordan Example"
      },
      "match": {
        "external_id": "cust-78",
        "source": "woocommerce"
      }
    }
  ]
}
JSON,
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

import os
import uuid
import requests

response = requests.request(
    "POST",
    "https://api.birp.io/v1/customers/batch",
    json={
      "items": [
        {
          "data": {
            "country_code": "FR",
            "customer_type": "b2b",
            "email": "achats@example.com",
            "name": "Epicerie Exemple SARL"
          },
          "match": {
            "external_id": "cust-77",
            "match_by": [
              "email"
            ],
            "source": "woocommerce"
          }
        },
        {
          "data": {
            "country_code": "US",
            "customer_type": "b2c",
            "email": "jordan.example@example.org",
            "name": "Jordan Example"
          },
          "match": {
            "external_id": "cust-78",
            "source": "woocommerce"
          }
        }
      ]
    },
    headers={
        "Authorization": f"Bearer {os.environ['BIRP_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    timeout=10,
)
response.raise_for_status()
result = response.json()

idempotency
sync-products
customers

The request

Validation first

One result per item

Partial failure

Idempotency of a batch

Related