Public Customers Bulk Upsert

Request

Bulk-upsert customers (async).

Accepts up to 100,000 customers per call. The body is validated synchronously; the actual upsert runs out-of-band on a worker.

Response.

202 Accepted with JobAck { job_id, status_url } on the first call.
200 OK with the same JobAck on an idempotent replay (same Idempotency-Key + same body). No second job runs.

What to do next. Poll GET /jobs/{job_id} (the status_url is the canonical path) until status is COMPLETED or FAILED. A COMPLETED job with error_count > 0 means some rows failed — see errors[] for the per-row detail. The Jobs chapter has the full polling guide.

Idempotency. Pass an Idempotency-Key header (≤ 255 chars). Same key with a different body returns 422 IDEMPOTENCY_KEY_MISMATCH.

authorizationstring or null(Authorization)

Bearer <mrc_live_…> API key

Idempotency-Keystring or null(Idempotency-Key)

Optional client-supplied key for safe retries; <= 255 chars

Bodyapplication/jsonrequired

customersArray of objects, [ 1 .. 100000 ] items(Customers)required

Example:

[
  {
    "addresses": [ … ],
    "custom_fields": { … },
    "customer_id": "K-10042",
    "emails": [ … ],
    "name": "Elektro Mustermann GmbH",
    "vat_id": "DE123456789"
  }
]

curl -i -X POST \
  https://docs.mercura.ai/_mock/openapi/customers \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: string' \
  -H 'authorization: string' \
  -d '{
    "customers": [
      {
        "addresses": [
          {
            "city": "Düsseldorf",
            "country": "DE",
            "is_default": true,
            "kind": "billing",
            "postal_code": "40210",
            "region": "NRW",
            "street": "Industriestraße",
            "street_number": "12"
          }
        ],
        "custom_fields": {
          "9b1f3c7a-2d84-4e11-9f0a-6c2e5b7d1a34": "Elektrogroßhandel"
        },
        "customer_id": "K-10042",
        "emails": [
          "einkauf@mustermann-elektro.example"
        ],
        "name": "Elektro Mustermann GmbH",
        "vat_id": "DE123456789"
      }
    ]
  }'

Responses

Idempotent replay — same job returned

Bodyapplication/json

job_idstring(Job Id)required

Example:"4242"

status_urlstring(Status Url)required

Relative URL to poll for this job's status

Example:"/api/public/v1/jobs/4242"

Response

{
  "job_id": "4242",
  "status_url": "/api/public/v1/jobs/4242"
}