> ## 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 items (bulk upsert)

> Upserts up to 200 items in a single call using external_item_id as the match key. Items are created or updated; items 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="items" type="object[]" required>
  Array of 1–200 item rows. Each row:

  <Expandable title="item row fields">
    <ParamField body="external_item_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 (1–256 chars).</ParamField>
    <ParamField body="type" type="string" required>`INGREDIENT`, `PACKAGING`, `SUPPLY`, `PREPARED_ITEM`, or `FINISHED_GOOD`.</ParamField>
    <ParamField body="procurement_type" type="string" required>`PURCHASED`, `PRODUCED`, or `PURCHASED_AND_PRODUCED`.</ParamField>
    <ParamField body="unit_group_code" type="string" required>Code of the unit group (resolved by BOH).</ParamField>
    <ParamField body="base_unit_code" type="string" required>Code of the base unit within the group.</ParamField>
    <ParamField body="code" type="string">Short alphanumeric code.</ParamField>
    <ParamField body="is_inventory_tracked" type="boolean">Defaults to `true`.</ParamField>
    <ParamField body="count_frequency" type="string | null">`DAILY`, `WEEKLY`, `MONTHLY`, or `null`.</ParamField>
    <ParamField body="tags" type="string[]">Array of item tag codes to assign.</ParamField>
    <ParamField body="archived" type="boolean">Set `true` to archive this item via sync.</ParamField>
    <ParamField body="metadata" type="object">Free-form extra data.</ParamField>
  </Expandable>
</ParamField>

<ParamField body="external_user_id" type="string">
  ID of the user performing this action in your system.
</ParamField>

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

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

<RequestExample>
  ```json theme={null}
  {
    "items": [
      {
        "external_item_id": "SKU-001",
        "name": "All-purpose flour",
        "type": "INGREDIENT",
        "procurement_type": "PURCHASED",
        "unit_group_code": "MASS",
        "base_unit_code": "G",
        "code": "FLOUR-KG",
        "is_inventory_tracked": true,
        "count_frequency": "WEEKLY"
      }
    ],
    "external_user_id": "user_setup_01"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "results": [
      {
        "external_item_id": "SKU-001",
        "id": "itm_01j5k...",
        "action": "created"
      }
    ],
    "summary": { "created": 1, "updated": 0, "unchanged": 0 }
  }
  ```
</ResponseExample>