collectionAddProductsV2 - admin-graphql - MUTATION

Version: 2025-01

Description:

Asynchronously adds a set of products to a given collection. It can take a long time to run. Instead of returning a collection, it returns a job which should be polled.

Access Scopes

`write_products` access scope. Also: The user must have a permission to add products to a collection.

Arguments

• id: ID! - The ID of the collection that's being updated.
• productIds: ID! - The IDs of the products that are being added to the collection. If the collection's sort order is manual, the products will be added in the order in which they are provided.

Returns

• job: Job The asynchronous job adding the products.
• userErrors: CollectionAddProductsV2UserError! The list of errors that occurred from executing the mutation.

Examples

• Add a product to a non-existing collection

          Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2025-01/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) { collectionAddProductsV2(id: $id, productIds: $productIds) { job { done id } userErrors { field message } } }\",\n \"variables\": {\n    \"id\": \"gid://shopify/Collection/-1\",\n    \"productIds\": [\n      \"gid://shopify/Product/108828309\"\n    ]\n  }\n}'\n"
          Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n  data: {\n    \"query\": `mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) {\n      collectionAddProductsV2(id: $id, productIds: $productIds) {\n        job {\n          done\n          id\n        }\n        userErrors {\n          field\n          message\n        }\n      }\n    }`,\n    \"variables\": {\n      \"id\": \"gid://shopify/Collection/-1\",\n      \"productIds\": [\n        \"gid://shopify/Product/108828309\"\n      ]\n    },\n  },\n});\n"
          Ruby example: "session = ShopifyAPI::Auth::Session.new(\n  shop: \"your-development-store.myshopify.com\",\n  access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n  session: session\n)\n\nquery = <<~QUERY\n  mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) {\n    collectionAddProductsV2(id: $id, productIds: $productIds) {\n      job {\n        done\n        id\n      }\n      userErrors {\n        field\n        message\n      }\n    }\n  }\nQUERY\n\nvariables = {\n  \"id\": \"gid://shopify/Collection/-1\",\n  \"productIds\": [\"gid://shopify/Product/108828309\"]\n}\n\nresponse = client.query(query: query, variables: variables)\n"
          PHP example: "use Shopify\\Clients\\Graphql;\n\n$client = new Graphql(\"your-development-store.myshopify.com\", $accessToken);\n$query = <<<QUERY\n  mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) {\n    collectionAddProductsV2(id: $id, productIds: $productIds) {\n      job {\n        done\n        id\n      }\n      userErrors {\n        field\n        message\n      }\n    }\n  }\nQUERY;\n\n$variables = [\n  \"id\" => \"gid://shopify/Collection/-1\",\n  \"productIds\" => [\"gid://shopify/Product/108828309\"],\n];\n\n$response = $client->query([\"query\" => $query, \"variables\" => $variables]);\n"
          Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n  `#graphql\n  mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) {\n    collectionAddProductsV2(id: $id, productIds: $productIds) {\n      job {\n        done\n        id\n      }\n      userErrors {\n        field\n        message\n      }\n    }\n  }`,\n  {\n    variables: {\n      \"id\": \"gid://shopify/Collection/-1\",\n      \"productIds\": [\n        \"gid://shopify/Product/108828309\"\n      ]\n    },\n  },\n);\n\nconst data = await response.json();\n"
          Graphql query: "mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) {\n  collectionAddProductsV2(id: $id, productIds: $productIds) {\n    job {\n      done\n      id\n    }\n    userErrors {\n      field\n      message\n    }\n  }\n}"
        

  input: {
    "id": "gid://shopify/Collection/-1",
    "productIds": [
      "gid://shopify/Product/108828309"
    ]
  }

  response: {
    "data": {
      "collectionAddProductsV2": {
        "job": null,
        "userErrors": [
          {
            "field": [
              "id"
            ],
            "message": "Collection does not exist"
          }
        ]
      }
    }
  }

  Add a product to a smart collection

          Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2025-01/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) { collectionAddProductsV2(id: $id, productIds: $productIds) { job { done id } userErrors { field message } } }\",\n \"variables\": {\n    \"id\": \"gid://shopify/Collection/142458073\",\n    \"productIds\": [\n      \"gid://shopify/Product/910489600\"\n    ]\n  }\n}'\n"
          Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n  data: {\n    \"query\": `mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) {\n      collectionAddProductsV2(id: $id, productIds: $productIds) {\n        job {\n          done\n          id\n        }\n        userErrors {\n          field\n          message\n        }\n      }\n    }`,\n    \"variables\": {\n      \"id\": \"gid://shopify/Collection/142458073\",\n      \"productIds\": [\n        \"gid://shopify/Product/910489600\"\n      ]\n    },\n  },\n});\n"
          Ruby example: "session = ShopifyAPI::Auth::Session.new(\n  shop: \"your-development-store.myshopify.com\",\n  access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n  session: session\n)\n\nquery = <<~QUERY\n  mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) {\n    collectionAddProductsV2(id: $id, productIds: $productIds) {\n      job {\n        done\n        id\n      }\n      userErrors {\n        field\n        message\n      }\n    }\n  }\nQUERY\n\nvariables = {\n  \"id\": \"gid://shopify/Collection/142458073\",\n  \"productIds\": [\"gid://shopify/Product/910489600\"]\n}\n\nresponse = client.query(query: query, variables: variables)\n"
          PHP example: "use Shopify\\Clients\\Graphql;\n\n$client = new Graphql(\"your-development-store.myshopify.com\", $accessToken);\n$query = <<<QUERY\n  mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) {\n    collectionAddProductsV2(id: $id, productIds: $productIds) {\n      job {\n        done\n        id\n      }\n      userErrors {\n        field\n        message\n      }\n    }\n  }\nQUERY;\n\n$variables = [\n  \"id\" => \"gid://shopify/Collection/142458073\",\n  \"productIds\" => [\"gid://shopify/Product/910489600\"],\n];\n\n$response = $client->query([\"query\" => $query, \"variables\" => $variables]);\n"
          Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n  `#graphql\n  mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) {\n    collectionAddProductsV2(id: $id, productIds: $productIds) {\n      job {\n        done\n        id\n      }\n      userErrors {\n        field\n        message\n      }\n    }\n  }`,\n  {\n    variables: {\n      \"id\": \"gid://shopify/Collection/142458073\",\n      \"productIds\": [\n        \"gid://shopify/Product/910489600\"\n      ]\n    },\n  },\n);\n\nconst data = await response.json();\n"
          Graphql query: "mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) {\n  collectionAddProductsV2(id: $id, productIds: $productIds) {\n    job {\n      done\n      id\n    }\n    userErrors {\n      field\n      message\n    }\n  }\n}"
        

  input: {
    "id": "gid://shopify/Collection/142458073",
    "productIds": [
      "gid://shopify/Product/910489600"
    ]
  }

  response: {
    "data": {
      "collectionAddProductsV2": {
        "job": null,
        "userErrors": [
          {
            "field": [
              "id"
            ],
            "message": "Can't manually add products to a smart collection"
          }
        ]
      }
    }
  }

  Add products that already belong to the specified collection

          Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2025-01/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) { collectionAddProductsV2(id: $id, productIds: $productIds) { job { done id } userErrors { field message } } }\",\n \"variables\": {\n    \"id\": \"gid://shopify/Collection/1007901140\",\n    \"productIds\": [\n      \"gid://shopify/Product/108828309\",\n      \"gid://shopify/Product/632910392\",\n      \"gid://shopify/Product/20995642\"\n    ]\n  }\n}'\n"
          Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n  data: {\n    \"query\": `mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) {\n      collectionAddProductsV2(id: $id, productIds: $productIds) {\n        job {\n          done\n          id\n        }\n        userErrors {\n          field\n          message\n        }\n      }\n    }`,\n    \"variables\": {\n      \"id\": \"gid://shopify/Collection/1007901140\",\n      \"productIds\": [\n        \"gid://shopify/Product/108828309\",\n        \"gid://shopify/Product/632910392\",\n        \"gid://shopify/Product/20995642\"\n      ]\n    },\n  },\n});\n"
          Ruby example: "session = ShopifyAPI::Auth::Session.new(\n  shop: \"your-development-store.myshopify.com\",\n  access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n  session: session\n)\n\nquery = <<~QUERY\n  mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) {\n    collectionAddProductsV2(id: $id, productIds: $productIds) {\n      job {\n        done\n        id\n      }\n      userErrors {\n        field\n        message\n      }\n    }\n  }\nQUERY\n\nvariables = {\n  \"id\": \"gid://shopify/Collection/1007901140\",\n  \"productIds\": [\"gid://shopify/Product/108828309\", \"gid://shopify/Product/632910392\", \"gid://shopify/Product/20995642\"]\n}\n\nresponse = client.query(query: query, variables: variables)\n"
          PHP example: "use Shopify\\Clients\\Graphql;\n\n$client = new Graphql(\"your-development-store.myshopify.com\", $accessToken);\n$query = <<<QUERY\n  mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) {\n    collectionAddProductsV2(id: $id, productIds: $productIds) {\n      job {\n        done\n        id\n      }\n      userErrors {\n        field\n        message\n      }\n    }\n  }\nQUERY;\n\n$variables = [\n  \"id\" => \"gid://shopify/Collection/1007901140\",\n  \"productIds\" => [\"gid://shopify/Product/108828309\", \"gid://shopify/Product/632910392\", \"gid://shopify/Product/20995642\"],\n];\n\n$response = $client->query([\"query\" => $query, \"variables\" => $variables]);\n"
          Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n  `#graphql\n  mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) {\n    collectionAddProductsV2(id: $id, productIds: $productIds) {\n      job {\n        done\n        id\n      }\n      userErrors {\n        field\n        message\n      }\n    }\n  }`,\n  {\n    variables: {\n      \"id\": \"gid://shopify/Collection/1007901140\",\n      \"productIds\": [\n        \"gid://shopify/Product/108828309\",\n        \"gid://shopify/Product/632910392\",\n        \"gid://shopify/Product/20995642\"\n      ]\n    },\n  },\n);\n\nconst data = await response.json();\n"
          Graphql query: "mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) {\n  collectionAddProductsV2(id: $id, productIds: $productIds) {\n    job {\n      done\n      id\n    }\n    userErrors {\n      field\n      message\n    }\n  }\n}"
        

  input: {
    "id": "gid://shopify/Collection/1007901140",
    "productIds": [
      "gid://shopify/Product/108828309",
      "gid://shopify/Product/632910392",
      "gid://shopify/Product/20995642"
    ]
  }

  response: {
    "data": {
      "collectionAddProductsV2": {
        "job": {
          "done": false,
          "id": "gid://shopify/Job/f2d9094c-e3d7-45b0-9eaa-b58976f7af3e"
        },
        "userErrors": []
      }
    }
  }

  Add products that don't exist to an existing collection

          Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2025-01/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) { collectionAddProductsV2(id: $id, productIds: $productIds) { job { done id } userErrors { field message } } }\",\n \"variables\": {\n    \"id\": \"gid://shopify/Collection/636030761\",\n    \"productIds\": [\n      \"gid://shopify/Product/-1\",\n      \"gid://shopify/Product/108828309\",\n      \"gid://shopify/Product/-2\"\n    ]\n  }\n}'\n"
          Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n  data: {\n    \"query\": `mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) {\n      collectionAddProductsV2(id: $id, productIds: $productIds) {\n        job {\n          done\n          id\n        }\n        userErrors {\n          field\n          message\n        }\n      }\n    }`,\n    \"variables\": {\n      \"id\": \"gid://shopify/Collection/636030761\",\n      \"productIds\": [\n        \"gid://shopify/Product/-1\",\n        \"gid://shopify/Product/108828309\",\n        \"gid://shopify/Product/-2\"\n      ]\n    },\n  },\n});\n"
          Ruby example: "session = ShopifyAPI::Auth::Session.new(\n  shop: \"your-development-store.myshopify.com\",\n  access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n  session: session\n)\n\nquery = <<~QUERY\n  mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) {\n    collectionAddProductsV2(id: $id, productIds: $productIds) {\n      job {\n        done\n        id\n      }\n      userErrors {\n        field\n        message\n      }\n    }\n  }\nQUERY\n\nvariables = {\n  \"id\": \"gid://shopify/Collection/636030761\",\n  \"productIds\": [\"gid://shopify/Product/-1\", \"gid://shopify/Product/108828309\", \"gid://shopify/Product/-2\"]\n}\n\nresponse = client.query(query: query, variables: variables)\n"
          PHP example: "use Shopify\\Clients\\Graphql;\n\n$client = new Graphql(\"your-development-store.myshopify.com\", $accessToken);\n$query = <<<QUERY\n  mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) {\n    collectionAddProductsV2(id: $id, productIds: $productIds) {\n      job {\n        done\n        id\n      }\n      userErrors {\n        field\n        message\n      }\n    }\n  }\nQUERY;\n\n$variables = [\n  \"id\" => \"gid://shopify/Collection/636030761\",\n  \"productIds\" => [\"gid://shopify/Product/-1\", \"gid://shopify/Product/108828309\", \"gid://shopify/Product/-2\"],\n];\n\n$response = $client->query([\"query\" => $query, \"variables\" => $variables]);\n"
          Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n  `#graphql\n  mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) {\n    collectionAddProductsV2(id: $id, productIds: $productIds) {\n      job {\n        done\n        id\n      }\n      userErrors {\n        field\n        message\n      }\n    }\n  }`,\n  {\n    variables: {\n      \"id\": \"gid://shopify/Collection/636030761\",\n      \"productIds\": [\n        \"gid://shopify/Product/-1\",\n        \"gid://shopify/Product/108828309\",\n        \"gid://shopify/Product/-2\"\n      ]\n    },\n  },\n);\n\nconst data = await response.json();\n"
          Graphql query: "mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) {\n  collectionAddProductsV2(id: $id, productIds: $productIds) {\n    job {\n      done\n      id\n    }\n    userErrors {\n      field\n      message\n    }\n  }\n}"
        

  input: {
    "id": "gid://shopify/Collection/636030761",
    "productIds": [
      "gid://shopify/Product/-1",
      "gid://shopify/Product/108828309",
      "gid://shopify/Product/-2"
    ]
  }

  response: {
    "data": {
      "collectionAddProductsV2": {
        "job": {
          "done": false,
          "id": "gid://shopify/Job/fdabe76d-6ba6-4404-90c0-f7ad8dfef0c7"
        },
        "userErrors": []
      }
    }
  }

  Add products to an existing collection

          Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2025-01/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) { collectionAddProductsV2(id: $id, productIds: $productIds) { job { done id } userErrors { field message } } }\",\n \"variables\": {\n    \"id\": \"gid://shopify/Collection/636030761\",\n    \"productIds\": [\n      \"gid://shopify/Product/121709582\",\n      \"gid://shopify/Product/108828309\"\n    ]\n  }\n}'\n"
          Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n  data: {\n    \"query\": `mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) {\n      collectionAddProductsV2(id: $id, productIds: $productIds) {\n        job {\n          done\n          id\n        }\n        userErrors {\n          field\n          message\n        }\n      }\n    }`,\n    \"variables\": {\n      \"id\": \"gid://shopify/Collection/636030761\",\n      \"productIds\": [\n        \"gid://shopify/Product/121709582\",\n        \"gid://shopify/Product/108828309\"\n      ]\n    },\n  },\n});\n"
          Ruby example: "session = ShopifyAPI::Auth::Session.new(\n  shop: \"your-development-store.myshopify.com\",\n  access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n  session: session\n)\n\nquery = <<~QUERY\n  mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) {\n    collectionAddProductsV2(id: $id, productIds: $productIds) {\n      job {\n        done\n        id\n      }\n      userErrors {\n        field\n        message\n      }\n    }\n  }\nQUERY\n\nvariables = {\n  \"id\": \"gid://shopify/Collection/636030761\",\n  \"productIds\": [\"gid://shopify/Product/121709582\", \"gid://shopify/Product/108828309\"]\n}\n\nresponse = client.query(query: query, variables: variables)\n"
          PHP example: "use Shopify\\Clients\\Graphql;\n\n$client = new Graphql(\"your-development-store.myshopify.com\", $accessToken);\n$query = <<<QUERY\n  mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) {\n    collectionAddProductsV2(id: $id, productIds: $productIds) {\n      job {\n        done\n        id\n      }\n      userErrors {\n        field\n        message\n      }\n    }\n  }\nQUERY;\n\n$variables = [\n  \"id\" => \"gid://shopify/Collection/636030761\",\n  \"productIds\" => [\"gid://shopify/Product/121709582\", \"gid://shopify/Product/108828309\"],\n];\n\n$response = $client->query([\"query\" => $query, \"variables\" => $variables]);\n"
          Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n  `#graphql\n  mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) {\n    collectionAddProductsV2(id: $id, productIds: $productIds) {\n      job {\n        done\n        id\n      }\n      userErrors {\n        field\n        message\n      }\n    }\n  }`,\n  {\n    variables: {\n      \"id\": \"gid://shopify/Collection/636030761\",\n      \"productIds\": [\n        \"gid://shopify/Product/121709582\",\n        \"gid://shopify/Product/108828309\"\n      ]\n    },\n  },\n);\n\nconst data = await response.json();\n"
          Graphql query: "mutation collectionAddProductsV2($id: ID!, $productIds: [ID!]!) {\n  collectionAddProductsV2(id: $id, productIds: $productIds) {\n    job {\n      done\n      id\n    }\n    userErrors {\n      field\n      message\n    }\n  }\n}"
        

  input: {
    "id": "gid://shopify/Collection/636030761",
    "productIds": [
      "gid://shopify/Product/121709582",
      "gid://shopify/Product/108828309"
    ]
  }

  response: {
    "data": {
      "collectionAddProductsV2": {
        "job": {
          "done": false,
          "id": "gid://shopify/Job/623cf371-2e67-4d4f-9bd1-dbfdd7b8a58b"
        },
        "userErrors": []
      }
    }
  }