> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fire.rest/llms.txt
> Use this file to discover all available pages before exploring further.

# Sync suppliers (bulk upsert)

> Upserts suppliers by external_supplier_id. Suppliers not in the batch are left untouched.

<ParamField header="x-api-key" type="string" required>
  BOH API key with `catalog:write` scope.
</ParamField>

<ParamField path="vendorId" type="string" required>
  Vendor UUID.
</ParamField>

<ParamField body="suppliers" type="object[]" required>
  Array of supplier rows:

  <Expandable title="supplier row fields">
    <ParamField body="external_supplier_id" type="string" required>Unique key in your system (1–128 chars). Used as match key.</ParamField>
    <ParamField body="name" type="string" required>Display name.</ParamField>
    <ParamField body="code" type="string">Short alphanumeric code.</ParamField>
    <ParamField body="email" type="string">Contact email.</ParamField>
    <ParamField body="phone" type="string">Contact phone.</ParamField>
    <ParamField body="tax_id" type="string">Tax/fiscal identifier.</ParamField>
    <ParamField body="archived" type="boolean">Set `true` to archive the supplier.</ParamField>
    <ParamField body="metadata" type="object">Free-form extra data.</ParamField>
  </Expandable>
</ParamField>

<ParamField body="external_user_id" type="string">
  Actor for audit trail.
</ParamField>

<ResponseField name="results" type="object[]">
  One entry per row: `external_supplier_id`, `id`, `action` (`created`, `updated`, `unchanged`).
</ResponseField>

<ResponseField name="summary" type="object">
  `{ created, updated, unchanged }` counts.
</ResponseField>

<RequestExample>
  ```json theme={null}
  {
    "suppliers": [
      {
        "external_supplier_id": "SUP-001",
        "name": "Best Foods Co.",
        "code": "BEST-FOODS",
        "email": "orders@bestfoods.com",
        "tax_id": "12-3456789"
      },
      {
        "external_supplier_id": "SUP-002",
        "name": "Old Supplier",
        "archived": true
      }
    ],
    "external_user_id": "user_setup_01"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "results": [
      { "external_supplier_id": "SUP-001", "id": "sup_01...", "action": "created" },
      { "external_supplier_id": "SUP-002", "id": "sup_02...", "action": "updated" }
    ],
    "summary": { "created": 1, "updated": 1, "unchanged": 0 }
  }
  ```
</ResponseExample>