Upsert an image by your own key

Create-or-update by a customer-named merge key: merge_key names any defined text-family attribute (usually sku) and attributes[merge_key] supplies the value to match — trimmed, case-insensitive. No match → create (201); one match → update (200); more than one match → 409 listing the matching ids. Idempotent for ERP-style pushes: address entities by your key, no UUID mapping table needed.

Scope: write:images.

post/images/upsert

Request

Base URL
https://www.merchkit.com/api/v1
Auth
HTTP bearer

Request body

merge_keystring required

A defined text-family attribute key to match on (e.g. sku).

parent_idstring uuid nullable

attributesAttributeWriteMap required

Map of attribute key → new value (sparse — only keys being written). Scalars set the value; null OR "" clears it (the key then disappears from reads). A single-reference key accepts a bare UUID string or an {id} object; a list-reference key accepts an array of either — list writes REPLACE the current set. Read stubs re-sent verbatim are valid writes (extra stub fields like type/label are ignored). Unknown keys are a 400; select values must be one of the attribute's acceptable_values.

Response

An existing image matched and was updated (full resource).

Example response

{
  "data": {
    "id": "9b2f6c1e-8a04-4c6e-b0d3-5f2f6f7a9e21",
    "type": "product",
    "label": "Aria Oak Dining Table",
    "parent_id": null,
    "created_at": "2026-06-02T14:11:09Z",
    "updated_at": "2026-07-18T09:30:22Z",
    "attributes": {
      "sku": "ARIA-DT-72",
      "product_name": "Aria Oak Dining Table",
      "price": 1299,
      "material": "White Oak",
      "vendor": {
        "id": "77e1b2aa-6b3d-4f19-9d10-8c2a5e7f4b21",
        "type": "vendor",
        "label": "Nordic Timber Co."
      },
      "category": {
        "id": "c41d09f3-2e85-47a6-b93c-d5f8e1a20c67",
        "type": "category",
        "label": "Dining Tables"
      },
      "gallery_images": [
        {
          "id": "f0a1b2c3-d4e5-4f60-8a7b-9c0d1e2f3a4b",
          "type": "image",
          "label": "aria-hero.jpg"
        },
        {
          "id": "f0a2c3d4-e5f6-4a70-9b8c-0d1e2f3a4b5c",
          "type": "image",
          "label": "aria-detail.jpg"
        },
        {
          "id": "f0a3d4e5-f6a7-4b80-8c9d-1e2f3a4b5c6d",
          "type": "image",
          "label": "aria-side.jpg"
        },
        {
          "id": "f0a4e5f6-a7b8-4c90-9dae-2f3a4b5c6d7e",
          "type": "image",
          "label": "aria-lifestyle.jpg"
        },
        {
          "id": "f0a5f6a7-b8c9-4da0-8ebf-3a4b5c6d7e8f",
          "type": "image",
          "label": "aria-packshot.jpg"
        }
      ]
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.