Public Suppliers Bulk Upsert

Request

Bulk-upsert suppliers (async).

Accepts up to 100,000 suppliers 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

suppliersArray of objects, [ 1 .. 100000 ] items(Suppliers)required

Example:

[
  {
    "addresses": [ … ],
    "custom_fields": { … },
    "emails": [ … ],
    "name": "Lumaris Leuchten GmbH",
    "supplier_id": "L-2001"
  }
]

curl -i -X POST \
  https://docs.mercura.ai/_mock/openapi/suppliers \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: string' \
  -H 'authorization: string' \
  -d '{
    "suppliers": [
      {
        "addresses": [
          {
            "city": "Lüdenscheid",
            "country": "DE",
            "is_default": true,
            "kind": "hq",
            "postal_code": "58507",
            "region": "NRW",
            "street": "Lichtstraße",
            "street_number": "8"
          }
        ],
        "custom_fields": {
          "7c4e0a91-5b23-4d6f-8e10-3a9c1f2b6d05": "Leuchten"
        },
        "emails": [
          "vertrieb@lumaris.example"
        ],
        "name": "Lumaris Leuchten GmbH",
        "supplier_id": "L-2001"
      }
    ]
  }'

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"
}