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

> Upserts units by code + unit_group_code. Units that match an existing record are updated; new ones are created. Global (system-defined) units are returned as skipped_global.

<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="units" type="object[]" required>
  Array of unit rows:

  <Expandable title="unit row fields">
    <ParamField body="code" type="string" required>Unique alphanumeric code within the unit group (1–64 chars).</ParamField>
    <ParamField body="name" type="string" required>Display name.</ParamField>
    <ParamField body="unit_group_code" type="string" required>Code of the parent unit group (e.g. `MASS`, `VOLUME`, `COUNT`).</ParamField>
    <ParamField body="conversion_factor_to_base" type="number" required>How many base units one unit of this type equals (e.g. `1000` for kg when base is g).</ParamField>
    <ParamField body="symbol" type="string">Display symbol (e.g. `kg`, `ml`).</ParamField>
    <ParamField body="system" type="string">`METRIC`, `IMPERIAL`, or `OTHER`.</ParamField>
    <ParamField body="archived" type="boolean">Set `true` to archive the unit.</ParamField>
  </Expandable>
</ParamField>

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

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

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

<RequestExample>
  ```json theme={null}
  {
    "units": [
      {
        "code": "KG",
        "name": "Kilogram",
        "unit_group_code": "MASS",
        "conversion_factor_to_base": 1000,
        "symbol": "kg",
        "system": "METRIC"
      },
      {
        "code": "LB",
        "name": "Pound",
        "unit_group_code": "MASS",
        "conversion_factor_to_base": 453.592,
        "symbol": "lb",
        "system": "IMPERIAL"
      }
    ],
    "external_user_id": "user_setup_01"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "results": [
      { "code": "KG", "unit_group_code": "MASS", "id": "unit_kg_01...", "action": "unchanged" },
      { "code": "LB", "unit_group_code": "MASS", "id": "unit_lb_01...", "action": "created" }
    ],
    "summary": { "created": 1, "updated": 0, "unchanged": 1, "skipped_global": 0 }
  }
  ```
</ResponseExample>