---
title: Upsert a collection.
slug: api-documentation/upsert-a-collection
docTags: 
createdAt: 2026-08-27T17:01:40.499Z
---

{
  "id": "jYiUjFHQ2jI_x_pxdfzZy",
  "type": "api-oas-v2",
  "data": {
    "method": "PUT",
    "url": "https://api.upstartcommerce.com/pim/product-lines/collections/{id}",
    "servers": [
      {
        "url": "https://api.upstartcommerce.com/pim/product-lines/collections/{id}"
      }
    ],
    "name": "Upsert a collection.",
    "description": "<p>If the collection exists, updates displayName, description, and productIds only. If not found, creates the collection with all provided fields. State and status are not accepted.</p>",
    "contentType": "application/json",
    "request": {
      "pathParameters": [],
      "headerParameters": [
        {
          "name": "accept",
          "type": "string",
          "kind": "optional",
          "description": "Generated from available response content types",
          "enum": [
            "application/json"
          ],
          "default": "application/json"
        }
      ],
      "queryParameters": [],
      "bodyDataParameters": [
        {
          "kind": "required",
          "name": "body",
          "type": "object",
          "description": "",
          "customType": "PimCollection.json",
          "schema": [],
          "modelRef": "schemas/Collection/PimCollection.json",
          "isExpanded": true
        }
      ],
      "formDataParameters": [],
      "oAuthParameters": [
        {
          "id": "NoChannelPortalAccess",
          "name": "NoChannelPortalAccess",
          "kind": "optional",
          "type": "http",
          "description": "<p>(DEPRECATED) This authentication is required for clients to interact with any of the management APIs. Similar to 'LoggedIn', it indicates that the user has actually logged into the system, but in this case with a management role.</p>",
          "scheme": "bearer"
        },
        {
          "id": "ApiKeyAccess",
          "name": "X-Upstart-Api-Key",
          "kind": "optional",
          "type": "apiKey",
          "description": "Api key based authorization.",
          "in": "header"
        },
        {
          "id": "SessionIdAccess",
          "name": "X-Upstart-Session-Id",
          "kind": "optional",
          "type": "apiKey",
          "description": "<p>Session based authorization. This authentication is required for clients to interact with any of the management APIs. Similar to 'LoggedIn', it indicates that the user has actually logged into the system, but in this case with a management role.</p>",
          "in": "header"
        }
      ],
      "cookieParameters": []
    },
    "responses": [
      {
        "statusCode": "200",
        "description": "Collection updated successfully.",
        "jsonExample": "",
        "isExpanded": true,
        "schema": [
          {
            "kind": "optional",
            "type": "object",
            "description": "",
            "schema": [],
            "isExpanded": true
          }
        ]
      },
      {
        "statusCode": "201",
        "description": "<p>Collection created (upsert — did not previously exist).</p>",
        "jsonExample": "",
        "isExpanded": true,
        "schema": [
          {
            "kind": "optional",
            "type": "object",
            "description": "",
            "customType": "PimCollection.json",
            "schema": [],
            "modelRef": "schemas/Collection/PimCollection.json",
            "isExpanded": true
          }
        ]
      }
    ],
    "hasXCodeSamples": false,
    "examples": {
      "languages": [
        {
          "id": "5fk22Q2go8msA6GEyDF92",
          "language": "curl",
          "label": "cURL",
          "code": "curl --request PUT \\\n     --url https://api.upstartcommerce.com/pim/product-lines/collections/{id} \\\n     --header 'accept: application/json'"
        },
        {
          "id": "LwwWiWBZdOoJVFZSyMCT5",
          "language": "javascript",
          "label": "javascript",
          "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\n\nvar requestOptions = {\n   method: 'PUT',\n   headers: myHeaders,\n   redirect: 'follow'\n};\n\nfetch(\"https://api.upstartcommerce.com/pim/product-lines/collections/{id}\", requestOptions)\n   .then(response => response.text())\n   .then(result => console.log(result))\n   .catch(error => console.log('error', error));"
        },
        {
          "id": "5cOpCouC-LswZy2LRgbBP",
          "language": "ruby",
          "label": "Ruby",
          "code": "require \"uri\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.upstartcommerce.com/pim/product-lines/collections/{id}\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Put.new(url)\nrequest[\"accept\"] = \"application/json\"\n\nresponse = https.request(request)\nputs response.read_body\n"
        },
        {
          "id": "3h5ago4lEjztt8P9Vh0Qh",
          "language": "python",
          "label": "Python",
          "code": "import requests\n\nurl = \"https://api.upstartcommerce.com/pim/product-lines/collections/{id}\"\n\npayload = {}\nheaders = {\n   'accept': 'application/json'\n}\n\nresponse = requests.request(\"PUT\", url, headers=headers, data=payload)\n\nprint(response.text)\n"
        }
      ],
      "selectedLanguageId": "5fk22Q2go8msA6GEyDF92"
    },
    "results": {
      "languages": [
        {
          "id": "fwvnAJzsaT4qxFXTXIONs",
          "language": "200",
          "code": "// Collection updated successfully.\n{}"
        },
        {
          "id": "WyQWcXD-wjU0B9ZVix-3D",
          "language": "201",
          "code": "// Collection created (upsert — did not previously exist).\n{}"
        }
      ],
      "selectedLanguageId": "fwvnAJzsaT4qxFXTXIONs"
    }
  },
  "children": [
    {
      "text": ""
    }
  ]
}