Choose a version:

collectionRemoveProducts

mutation

Requires write_products access scope. Also: The user must have a permission to remove products from a collection.

Removes multiple products from a collection in a single operation. This mutation can process large product sets (up to 250 products) and may take significant time to complete for collections with many products.

For example, when ending a seasonal promotion, merchants can remove all sale items from a "Summer Clearance" collection at once rather than editing each product individually.

Use CollectionRemoveProducts to:

Bulk-remove products from collections efficiently
Clean up collection membership during catalog updates
Implement automated collection management workflows

The operation processes asynchronously to avoid timeouts and performance issues, especially for large product sets.

Learn more about collection management.

Anchor to Arguments

Arguments

Anchor to idid •ID! required: The ID of the collection to remove products from. The ID must reference an existing manual collection.
Anchor to productIdsproductIds •[ID!]! required: The IDs of products to remove from the collection. The mutation doesn't validate that the products belong to the collection or whether the products exist.

Was this section helpful?

Anchor to CollectionRemoveProductsPayload returnsCollectionRemoveProductsPayload returns

Anchor to jobjob •Job: The asynchronous job removing the products.
Anchor to userErrorsuserErrors •[UserError!]! non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Examples

Remove a product from a manual collection

Description

Removing a product from a manual collection returns a job ID.

Query

mutation collectionRemoveProducts($id: ID!, $productIds: [ID!]!) {
  collectionRemoveProducts(id: $id, productIds: $productIds) {
    job {
      done
      id
    }
    userErrors {
      field
      message
    }
  }
}

Variables

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

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/unstable/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation collectionRemoveProducts($id: ID!, $productIds: [ID!]!) { collectionRemoveProducts(id: $id, productIds: $productIds) { job { done id } userErrors { field message } } }",
 "variables": {
    "id": "gid://shopify/Collection/1007901140",
    "productIds": [
      "gid://shopify/Product/20995642"
    ]
  }
}'

Remix

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(
  `#graphql
  mutation collectionRemoveProducts($id: ID!, $productIds: [ID!]!) {
    collectionRemoveProducts(id: $id, productIds: $productIds) {
      job {
        done
        id
      }
      userErrors {
        field
        message
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/Collection/1007901140",
        "productIds": [
            "gid://shopify/Product/20995642"
        ]
    },
  },
);

const data = await response.json();

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  mutation collectionRemoveProducts($id: ID!, $productIds: [ID!]!) {
    collectionRemoveProducts(id: $id, productIds: $productIds) {
      job {
        done
        id
      }
      userErrors {
        field
        message
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/Collection/1007901140",
  "productIds": [
    "gid://shopify/Product/20995642"
  ]
}

response = client.query(query: query, variables: variables)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation collectionRemoveProducts($id: ID!, $productIds: [ID!]!) {
      collectionRemoveProducts(id: $id, productIds: $productIds) {
        job {
          done
          id
        }
        userErrors {
          field
          message
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/Collection/1007901140",
        "productIds": [
            "gid://shopify/Product/20995642"
        ]
    },
  },
});

Response

{
  "collectionRemoveProducts": {
    "job": {
      "done": false,
      "id": "gid://shopify/Job/0d9c63ab-d903-4f1e-b9b1-6ddf55948dfb"
    },
    "userErrors": []
  }
}

Remove a product from a non-existent collection

Description

Trying to remove a product from a non-existent collection returns a user error.

Query

mutation collectionRemoveProducts($id: ID!, $productIds: [ID!]!) {
  collectionRemoveProducts(id: $id, productIds: $productIds) {
    job {
      done
      id
    }
    userErrors {
      field
      message
    }
  }
}

Variables

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

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/unstable/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation collectionRemoveProducts($id: ID!, $productIds: [ID!]!) { collectionRemoveProducts(id: $id, productIds: $productIds) { job { done id } userErrors { field message } } }",
 "variables": {
    "id": "gid://shopify/Collection/-1",
    "productIds": [
      "gid://shopify/Product/20995642"
    ]
  }
}'

Remix

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(
  `#graphql
  mutation collectionRemoveProducts($id: ID!, $productIds: [ID!]!) {
    collectionRemoveProducts(id: $id, productIds: $productIds) {
      job {
        done
        id
      }
      userErrors {
        field
        message
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/Collection/-1",
        "productIds": [
            "gid://shopify/Product/20995642"
        ]
    },
  },
);

const data = await response.json();

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  mutation collectionRemoveProducts($id: ID!, $productIds: [ID!]!) {
    collectionRemoveProducts(id: $id, productIds: $productIds) {
      job {
        done
        id
      }
      userErrors {
        field
        message
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/Collection/-1",
  "productIds": [
    "gid://shopify/Product/20995642"
  ]
}

response = client.query(query: query, variables: variables)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation collectionRemoveProducts($id: ID!, $productIds: [ID!]!) {
      collectionRemoveProducts(id: $id, productIds: $productIds) {
        job {
          done
          id
        }
        userErrors {
          field
          message
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/Collection/-1",
        "productIds": [
            "gid://shopify/Product/20995642"
        ]
    },
  },
});

Response

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

Remove a product from a smart collection

Description

Trying to manually remove a product from a smart collection returns a user error.

Query

mutation collectionRemoveProducts($id: ID!, $productIds: [ID!]!) {
  collectionRemoveProducts(id: $id, productIds: $productIds) {
    job {
      done
      id
    }
    userErrors {
      field
      message
    }
  }
}

Variables

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

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/unstable/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation collectionRemoveProducts($id: ID!, $productIds: [ID!]!) { collectionRemoveProducts(id: $id, productIds: $productIds) { job { done id } userErrors { field message } } }",
 "variables": {
    "id": "gid://shopify/Collection/142458073",
    "productIds": [
      "gid://shopify/Product/108828309"
    ]
  }
}'

Remix

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(
  `#graphql
  mutation collectionRemoveProducts($id: ID!, $productIds: [ID!]!) {
    collectionRemoveProducts(id: $id, productIds: $productIds) {
      job {
        done
        id
      }
      userErrors {
        field
        message
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/Collection/142458073",
        "productIds": [
            "gid://shopify/Product/108828309"
        ]
    },
  },
);

const data = await response.json();

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  mutation collectionRemoveProducts($id: ID!, $productIds: [ID!]!) {
    collectionRemoveProducts(id: $id, productIds: $productIds) {
      job {
        done
        id
      }
      userErrors {
        field
        message
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/Collection/142458073",
  "productIds": [
    "gid://shopify/Product/108828309"
  ]
}

response = client.query(query: query, variables: variables)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation collectionRemoveProducts($id: ID!, $productIds: [ID!]!) {
      collectionRemoveProducts(id: $id, productIds: $productIds) {
        job {
          done
          id
        }
        userErrors {
          field
          message
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/Collection/142458073",
        "productIds": [
            "gid://shopify/Product/108828309"
        ]
    },
  },
});

Response

{
  "collectionRemoveProducts": {
    "job": null,
    "userErrors": [
      {
        "field": [
          "id"
        ],
        "message": "Can't manually remove products from a smart collection"
      }
    ]
  }
}

Removes a product from a collection

Query

mutation RemoveFromCollection($id: ID!, $productIds: [ID!]!) {
  collectionRemoveProducts(id: $id, productIds: $productIds) {
    job {
      done
      id
    }
    userErrors {
      field
      message
    }
  }
}

Variables

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

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/unstable/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation RemoveFromCollection($id: ID!, $productIds: [ID!]!) { collectionRemoveProducts(id: $id, productIds: $productIds) { job { done id } userErrors { field message } } }",
 "variables": {
    "id": "gid://shopify/Collection/1007901140",
    "productIds": [
      "gid://shopify/Product/20995642"
    ]
  }
}'

Remix

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(
  `#graphql
  mutation RemoveFromCollection($id: ID!, $productIds: [ID!]!) {
    collectionRemoveProducts(id: $id, productIds: $productIds) {
      job {
        done
        id
      }
      userErrors {
        field
        message
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/Collection/1007901140",
        "productIds": [
            "gid://shopify/Product/20995642"
        ]
    },
  },
);

const data = await response.json();

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  mutation RemoveFromCollection($id: ID!, $productIds: [ID!]!) {
    collectionRemoveProducts(id: $id, productIds: $productIds) {
      job {
        done
        id
      }
      userErrors {
        field
        message
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/Collection/1007901140",
  "productIds": [
    "gid://shopify/Product/20995642"
  ]
}

response = client.query(query: query, variables: variables)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation RemoveFromCollection($id: ID!, $productIds: [ID!]!) {
      collectionRemoveProducts(id: $id, productIds: $productIds) {
        job {
          done
          id
        }
        userErrors {
          field
          message
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/Collection/1007901140",
        "productIds": [
            "gid://shopify/Product/20995642"
        ]
    },
  },
});

Response

{
  "collectionRemoveProducts": {
    "job": {
      "done": false,
      "id": "gid://shopify/Job/8b553d69-6076-4dee-bc21-8c2d52457a36"
    },
    "userErrors": []
  }
}

collectionRemoveProducts reference

Examples

Open in GraphiQL

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(

`#graphql

mutation collectionRemoveProducts($id: ID!, $productIds: [ID!]!) {

collectionRemoveProducts(id: $id, productIds: $productIds) {

job {

done

}

userErrors {

field

message

}

}`,

{

variables: {

"id": "gid://shopify/Collection/1007901140",

"productIds": [

"gid://shopify/Product/20995642"

]

);

const data = await response.json();

mutation collectionRemoveProducts($id: ID!, $productIds: [ID!]!) {
  collectionRemoveProducts(id: $id, productIds: $productIds) {
    job {
      done
      id
    }
    userErrors {
      field
      message
    }
  }
}

curl -X POST \
https://your-development-store.myshopify.com/admin/api/unstable/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation collectionRemoveProducts($id: ID!, $productIds: [ID!]!) { collectionRemoveProducts(id: $id, productIds: $productIds) { job { done id } userErrors { field message } } }",
 "variables": {
    "id": "gid://shopify/Collection/1007901140",
    "productIds": [
      "gid://shopify/Product/20995642"
    ]
  }
}'

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(
  `#graphql
  mutation collectionRemoveProducts($id: ID!, $productIds: [ID!]!) {
    collectionRemoveProducts(id: $id, productIds: $productIds) {
      job {
        done
        id
      }
      userErrors {
        field
        message
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/Collection/1007901140",
        "productIds": [
            "gid://shopify/Product/20995642"
        ]
    },
  },
);

const data = await response.json();

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation collectionRemoveProducts($id: ID!, $productIds: [ID!]!) {
      collectionRemoveProducts(id: $id, productIds: $productIds) {
        job {
          done
          id
        }
        userErrors {
          field
          message
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/Collection/1007901140",
        "productIds": [
            "gid://shopify/Product/20995642"
        ]
    },
  },
});

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  mutation collectionRemoveProducts($id: ID!, $productIds: [ID!]!) {
    collectionRemoveProducts(id: $id, productIds: $productIds) {
      job {
        done
        id
      }
      userErrors {
        field
        message
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/Collection/1007901140",
  "productIds": [
    "gid://shopify/Product/20995642"
  ]
}

response = client.query(query: query, variables: variables)

Input variables

JSON

{

"id": "gid://shopify/Collection/1007901140",

"productIds": [

"gid://shopify/Product/20995642"

]

}

Response

JSON

{

"collectionRemoveProducts": {

"job": {

"done": false,

"id": "gid://shopify/Job/0d9c63ab-d903-4f1e-b9b1-6ddf55948dfb"

"userErrors": []

}