Choose a version:

collectionCreate

mutation

Requires write_products access scope. Also: The app must have access to the input fields used to create the collection. Further, the store must not be on the Starter or Retail plans and user must have a permission to create collection.

Creates a collection to group products together in the online store and other sales channels. For example, an athletics store might create different collections for running attire, shoes, and accessories.

Use the collectionCreate mutation when you need to:

Create a new collection for a product launch or campaign
Organize products by category, season, or promotion
Automate product grouping using conditions (for example, by tag, type, or price)

Collections can include products manually and can also include products automatically based on rules, sources, or conditions.

Defining a collection's membership

Define membership with sources on the collection argument (CollectionCreateInput). Each source adds products through conditions (such as product tag, title, or metafield—see CollectionSourceInclusionConditionInput for the full list) and through manual selections.

Note

The input argument and its ruleSet field are deprecated. Existing integrations should migrate to collection and sources — a ruleSet rule maps to an equivalent source condition (for example, a tag rule becomes a productTag condition). If both collection and input are provided, collection is used.

Note

The created collection is unpublished by default. To make it available to customers, use the publishablePublish mutation after creation.

Learn more about using metafields with collection conditions.

Anchor to Arguments

Arguments

Anchor to inputinput

•CollectionInput!

required

The properties to use when creating the collection.

Was this section helpful?

Anchor to CollectionCreatePayload returnsCollectionCreatePayload returns

Anchor to collectioncollection •Collection: The collection that has been created.
Anchor to userErrorsuserErrors •[UserError!]! non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Examples

Create a collection with an image

Description

Create a collection that includes an image. This example shows how to attach image details, such as the source URL and alt text during the process of creating the collection. The response returns the collection's ID, title, and other specified image details.

Query

mutation CollectionCreate($input: CollectionInput!) {
  collectionCreate(input: $input) {
    userErrors {
      field
      message
    }
    collection {
      id
      title
      image {
        url
        altText
      }
    }
  }
}

Variables

{
  "input": {
    "title": "Collection with Image",
    "image": {
      "src": "tmp/26371970/collections/2fb4c50b-b04b-4ee8-a857-52b7ad9e5d2d/test_file.txt",
      "altText": "A beautiful collection image"
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation CollectionCreate($input: CollectionInput!) { collectionCreate(input: $input) { userErrors { field message } collection { id title image { url altText } } } }",
 "variables": {
    "input": {
      "title": "Collection with Image",
      "image": {
        "src": "tmp/26371970/collections/2fb4c50b-b04b-4ee8-a857-52b7ad9e5d2d/test_file.txt",
        "altText": "A beautiful collection image"
      }
    }
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation CollectionCreate($input: CollectionInput!) {
    collectionCreate(input: $input) {
      userErrors {
        field
        message
      }
      collection {
        id
        title
        image {
          url
          altText
        }
      }
    }
  }`,
  {
    variables: {
        "input": {
            "title": "Collection with Image",
            "image": {
                "src": "tmp/26371970/collections/2fb4c50b-b04b-4ee8-a857-52b7ad9e5d2d/test_file.txt",
                "altText": "A beautiful collection image"
            }
        }
    },
  },
  );
  const json = await response.json();
  return json.data;
}

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 CollectionCreate($input: CollectionInput!) {
    collectionCreate(input: $input) {
      userErrors {
        field
        message
      }
      collection {
        id
        title
        image {
          url
          altText
        }
      }
    }
  }
QUERY

variables = {
  "input": {
    "title": "Collection with Image",
    "image": {
      "src": "tmp/26371970/collections/2fb4c50b-b04b-4ee8-a857-52b7ad9e5d2d/test_file.txt",
      "altText": "A beautiful collection image"
    }
  }
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation CollectionCreate($input: CollectionInput!) {
      collectionCreate(input: $input) {
        userErrors {
          field
          message
        }
        collection {
          id
          title
          image {
            url
            altText
          }
        }
      }
    }`,
    "variables": {
        "input": {
            "title": "Collection with Image",
            "image": {
                "src": "tmp/26371970/collections/2fb4c50b-b04b-4ee8-a857-52b7ad9e5d2d/test_file.txt",
                "altText": "A beautiful collection image"
            }
        }
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation CollectionCreate($input: CollectionInput!) {
  collectionCreate(input: $input) {
    userErrors {
      field
      message
    }
    collection {
      id
      title
      image {
        url
        altText
      }
    }
  }
}' \
--variables \
'{
  "input": {
    "title": "Collection with Image",
    "image": {
      "src": "tmp/26371970/collections/2fb4c50b-b04b-4ee8-a857-52b7ad9e5d2d/test_file.txt",
      "altText": "A beautiful collection image"
    }
  }
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation CollectionCreate($input: CollectionInput!) {
        collectionCreate(input: $input) {
          userErrors {
            field
            message
          }
          collection {
            id
            title
            image {
              url
              altText
            }
          }
        }
      }
    `,
    variables: {
        "input": {
            "title": "Collection with Image",
            "image": {
                "src": "tmp/26371970/collections/2fb4c50b-b04b-4ee8-a857-52b7ad9e5d2d/test_file.txt",
                "altText": "A beautiful collection image"
            }
        }
    },
  }),
});

const { data } = await response.json();
console.log(data);

Response

{
  "collectionCreate": {
    "userErrors": [],
    "collection": {
      "id": "gid://shopify/Collection/1063001426",
      "title": "Collection with Image",
      "image": {
        "url": "https://cdn.shopify.com/s/files/1/2637/1970/collections/test_file.jpg?v=1781273014",
        "altText": "A beautiful collection image"
      }
    }
  }
}

Create a custom collection

Description

Create a [custom collection](https://help.shopify.com/manual/products/collections/manual-shopify-collection) by defining the collection's title, description, handle, and associated products. The response returns detailed information about the newly created collection, including its ID, title, description, update timestamp, handle, an image, and a list of associated products.

Query

mutation CollectionCreate($input: CollectionInput!) {
  collectionCreate(input: $input) {
    collection {
      id
      title
      descriptionHtml
      updatedAt
      handle
      image {
        id
        height
        width
        url
      }
      products(first: 10) {
        nodes {
          id
          featuredMedia {
            id
          }
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

Variables

{
  "input": {
    "title": "New Custom Collection",
    "descriptionHtml": "This is a custom collection.",
    "handle": "custom-collection",
    "products": [
      "gid://shopify/Product/20995642"
    ]
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation CollectionCreate($input: CollectionInput!) { collectionCreate(input: $input) { collection { id title descriptionHtml updatedAt handle image { id height width url } products(first: 10) { nodes { id featuredMedia { id } } } } userErrors { field message } } }",
 "variables": {
    "input": {
      "title": "New Custom Collection",
      "descriptionHtml": "This is a custom collection.",
      "handle": "custom-collection",
      "products": [
        "gid://shopify/Product/20995642"
      ]
    }
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation CollectionCreate($input: CollectionInput!) {
    collectionCreate(input: $input) {
      collection {
        id
        title
        descriptionHtml
        updatedAt
        handle
        image {
          id
          height
          width
          url
        }
        products(first: 10) {
          nodes {
            id
            featuredMedia {
              id
            }
          }
        }
      }
      userErrors {
        field
        message
      }
    }
  }`,
  {
    variables: {
        "input": {
            "title": "New Custom Collection",
            "descriptionHtml": "This is a custom collection.",
            "handle": "custom-collection",
            "products": [
                "gid://shopify/Product/20995642"
            ]
        }
    },
  },
  );
  const json = await response.json();
  return json.data;
}

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 CollectionCreate($input: CollectionInput!) {
    collectionCreate(input: $input) {
      collection {
        id
        title
        descriptionHtml
        updatedAt
        handle
        image {
          id
          height
          width
          url
        }
        products(first: 10) {
          nodes {
            id
            featuredMedia {
              id
            }
          }
        }
      }
      userErrors {
        field
        message
      }
    }
  }
QUERY

variables = {
  "input": {
    "title": "New Custom Collection",
    "descriptionHtml": "This is a custom collection.",
    "handle": "custom-collection",
    "products": [
      "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 CollectionCreate($input: CollectionInput!) {
      collectionCreate(input: $input) {
        collection {
          id
          title
          descriptionHtml
          updatedAt
          handle
          image {
            id
            height
            width
            url
          }
          products(first: 10) {
            nodes {
              id
              featuredMedia {
                id
              }
            }
          }
        }
        userErrors {
          field
          message
        }
      }
    }`,
    "variables": {
        "input": {
            "title": "New Custom Collection",
            "descriptionHtml": "This is a custom collection.",
            "handle": "custom-collection",
            "products": [
                "gid://shopify/Product/20995642"
            ]
        }
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation CollectionCreate($input: CollectionInput!) {
  collectionCreate(input: $input) {
    collection {
      id
      title
      descriptionHtml
      updatedAt
      handle
      image {
        id
        height
        width
        url
      }
      products(first: 10) {
        nodes {
          id
          featuredMedia {
            id
          }
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}' \
--variables \
'{
  "input": {
    "title": "New Custom Collection",
    "descriptionHtml": "This is a custom collection.",
    "handle": "custom-collection",
    "products": [
      "gid://shopify/Product/20995642"
    ]
  }
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation CollectionCreate($input: CollectionInput!) {
        collectionCreate(input: $input) {
          collection {
            id
            title
            descriptionHtml
            updatedAt
            handle
            image {
              id
              height
              width
              url
            }
            products(first: 10) {
              nodes {
                id
                featuredMedia {
                  id
                }
              }
            }
          }
          userErrors {
            field
            message
          }
        }
      }
    `,
    variables: {
        "input": {
            "title": "New Custom Collection",
            "descriptionHtml": "This is a custom collection.",
            "handle": "custom-collection",
            "products": [
                "gid://shopify/Product/20995642"
            ]
        }
    },
  }),
});

const { data } = await response.json();
console.log(data);

Response

{
  "collectionCreate": {
    "collection": {
      "id": "gid://shopify/Collection/1063001436",
      "title": "New Custom Collection",
      "descriptionHtml": "This is a custom collection.",
      "updatedAt": "2026-06-12T14:03:36Z",
      "handle": "custom-collection",
      "image": null,
      "products": {
        "nodes": [
          {
            "id": "gid://shopify/Product/20995642",
            "featuredMedia": {
              "id": "gid://shopify/MediaImage/730211239"
            }
          }
        ]
      }
    },
    "userErrors": []
  }
}

Create a new metafield on a new collection

Description

Create a new metafield `my_field.subtitle` on a new collection. Alternatively, refer to the [`metafieldsSet`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metafieldsset) mutation to create and update metafields on collection resources.

Query

mutation createCollectionMetafields($input: CollectionInput!) {
  collectionCreate(input: $input) {
    collection {
      id
      metafields(first: 3) {
        edges {
          node {
            id
            namespace
            key
            value
          }
        }
      }
    }
    userErrors {
      message
      field
    }
  }
}

Variables

{
  "input": {
    "metafields": [
      {
        "namespace": "my_field",
        "key": "subtitle",
        "type": "single_line_text_field",
        "value": "Bold Colors"
      }
    ],
    "title": "Spring Styles"
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation createCollectionMetafields($input: CollectionInput!) { collectionCreate(input: $input) { collection { id metafields(first: 3) { edges { node { id namespace key value } } } } userErrors { message field } } }",
 "variables": {
    "input": {
      "metafields": [
        {
          "namespace": "my_field",
          "key": "subtitle",
          "type": "single_line_text_field",
          "value": "Bold Colors"
        }
      ],
      "title": "Spring Styles"
    }
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation createCollectionMetafields($input: CollectionInput!) {
    collectionCreate(input: $input) {
      collection {
        id
        metafields(first: 3) {
          edges {
            node {
              id
              namespace
              key
              value
            }
          }
        }
      }
      userErrors {
        message
        field
      }
    }
  }`,
  {
    variables: {
        "input": {
            "metafields": [
                {
                    "namespace": "my_field",
                    "key": "subtitle",
                    "type": "single_line_text_field",
                    "value": "Bold Colors"
                }
            ],
            "title": "Spring Styles"
        }
    },
  },
  );
  const json = await response.json();
  return json.data;
}

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 createCollectionMetafields($input: CollectionInput!) {
    collectionCreate(input: $input) {
      collection {
        id
        metafields(first: 3) {
          edges {
            node {
              id
              namespace
              key
              value
            }
          }
        }
      }
      userErrors {
        message
        field
      }
    }
  }
QUERY

variables = {
  "input": {
    "metafields": [
      {
        "namespace": "my_field",
        "key": "subtitle",
        "type": "single_line_text_field",
        "value": "Bold Colors"
      }
    ],
    "title": "Spring Styles"
  }
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation createCollectionMetafields($input: CollectionInput!) {
      collectionCreate(input: $input) {
        collection {
          id
          metafields(first: 3) {
            edges {
              node {
                id
                namespace
                key
                value
              }
            }
          }
        }
        userErrors {
          message
          field
        }
      }
    }`,
    "variables": {
        "input": {
            "metafields": [
                {
                    "namespace": "my_field",
                    "key": "subtitle",
                    "type": "single_line_text_field",
                    "value": "Bold Colors"
                }
            ],
            "title": "Spring Styles"
        }
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation createCollectionMetafields($input: CollectionInput!) {
  collectionCreate(input: $input) {
    collection {
      id
      metafields(first: 3) {
        edges {
          node {
            id
            namespace
            key
            value
          }
        }
      }
    }
    userErrors {
      message
      field
    }
  }
}' \
--variables \
'{
  "input": {
    "metafields": [
      {
        "namespace": "my_field",
        "key": "subtitle",
        "type": "single_line_text_field",
        "value": "Bold Colors"
      }
    ],
    "title": "Spring Styles"
  }
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation createCollectionMetafields($input: CollectionInput!) {
        collectionCreate(input: $input) {
          collection {
            id
            metafields(first: 3) {
              edges {
                node {
                  id
                  namespace
                  key
                  value
                }
              }
            }
          }
          userErrors {
            message
            field
          }
        }
      }
    `,
    variables: {
        "input": {
            "metafields": [
                {
                    "namespace": "my_field",
                    "key": "subtitle",
                    "type": "single_line_text_field",
                    "value": "Bold Colors"
                }
            ],
            "title": "Spring Styles"
        }
    },
  }),
});

const { data } = await response.json();
console.log(data);

Response

{
  "collectionCreate": {
    "collection": {
      "id": "gid://shopify/Collection/1063001315",
      "metafields": {
        "edges": [
          {
            "node": {
              "id": "gid://shopify/Metafield/1069228935",
              "namespace": "my_field",
              "key": "subtitle",
              "value": "Bold Colors"
            }
          }
        ]
      }
    },
    "userErrors": []
  }
}

Create a smart collection

Description

Create a [smart collection](https://help.shopify.com/manual/products/collections/smart-collections), specifically tailored for a store's shoe collection. The response returns the details of the newly created collection, including its ID, title, description, handle, sort order, and the defined rule set in the [collection's conditions](https://help.shopify.com/manual/products/collections/smart-collections/conditions).

Query

mutation CollectionCreate($input: CollectionInput!) {
  collectionCreate(input: $input) {
    userErrors {
      field
      message
    }
    collection {
      id
      title
      descriptionHtml
      handle
      sortOrder
      ruleSet {
        appliedDisjunctively
        rules {
          column
          relation
          condition
        }
      }
    }
  }
}

Variables

{
  "input": {
    "title": "Our entire shoe collection",
    "descriptionHtml": "View <b>every</b> shoe available in our store.",
    "ruleSet": {
      "appliedDisjunctively": false,
      "rules": {
        "column": "TITLE",
        "relation": "CONTAINS",
        "condition": "shoe"
      }
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation CollectionCreate($input: CollectionInput!) { collectionCreate(input: $input) { userErrors { field message } collection { id title descriptionHtml handle sortOrder ruleSet { appliedDisjunctively rules { column relation condition } } } } }",
 "variables": {
    "input": {
      "title": "Our entire shoe collection",
      "descriptionHtml": "View <b>every</b> shoe available in our store.",
      "ruleSet": {
        "appliedDisjunctively": false,
        "rules": {
          "column": "TITLE",
          "relation": "CONTAINS",
          "condition": "shoe"
        }
      }
    }
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation CollectionCreate($input: CollectionInput!) {
    collectionCreate(input: $input) {
      userErrors {
        field
        message
      }
      collection {
        id
        title
        descriptionHtml
        handle
        sortOrder
        ruleSet {
          appliedDisjunctively
          rules {
            column
            relation
            condition
          }
        }
      }
    }
  }`,
  {
    variables: {
        "input": {
            "title": "Our entire shoe collection",
            "descriptionHtml": "View <b>every</b> shoe available in our store.",
            "ruleSet": {
                "appliedDisjunctively": false,
                "rules": {
                    "column": "TITLE",
                    "relation": "CONTAINS",
                    "condition": "shoe"
                }
            }
        }
    },
  },
  );
  const json = await response.json();
  return json.data;
}

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 CollectionCreate($input: CollectionInput!) {
    collectionCreate(input: $input) {
      userErrors {
        field
        message
      }
      collection {
        id
        title
        descriptionHtml
        handle
        sortOrder
        ruleSet {
          appliedDisjunctively
          rules {
            column
            relation
            condition
          }
        }
      }
    }
  }
QUERY

variables = {
  "input": {
    "title": "Our entire shoe collection",
    "descriptionHtml": "View <b>every</b> shoe available in our store.",
    "ruleSet": {
      "appliedDisjunctively": false,
      "rules": {
        "column": "TITLE",
        "relation": "CONTAINS",
        "condition": "shoe"
      }
    }
  }
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation CollectionCreate($input: CollectionInput!) {
      collectionCreate(input: $input) {
        userErrors {
          field
          message
        }
        collection {
          id
          title
          descriptionHtml
          handle
          sortOrder
          ruleSet {
            appliedDisjunctively
            rules {
              column
              relation
              condition
            }
          }
        }
      }
    }`,
    "variables": {
        "input": {
            "title": "Our entire shoe collection",
            "descriptionHtml": "View <b>every</b> shoe available in our store.",
            "ruleSet": {
                "appliedDisjunctively": false,
                "rules": {
                    "column": "TITLE",
                    "relation": "CONTAINS",
                    "condition": "shoe"
                }
            }
        }
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation CollectionCreate($input: CollectionInput!) {
  collectionCreate(input: $input) {
    userErrors {
      field
      message
    }
    collection {
      id
      title
      descriptionHtml
      handle
      sortOrder
      ruleSet {
        appliedDisjunctively
        rules {
          column
          relation
          condition
        }
      }
    }
  }
}' \
--variables \
'{
  "input": {
    "title": "Our entire shoe collection",
    "descriptionHtml": "View <b>every</b> shoe available in our store.",
    "ruleSet": {
      "appliedDisjunctively": false,
      "rules": {
        "column": "TITLE",
        "relation": "CONTAINS",
        "condition": "shoe"
      }
    }
  }
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation CollectionCreate($input: CollectionInput!) {
        collectionCreate(input: $input) {
          userErrors {
            field
            message
          }
          collection {
            id
            title
            descriptionHtml
            handle
            sortOrder
            ruleSet {
              appliedDisjunctively
              rules {
                column
                relation
                condition
              }
            }
          }
        }
      }
    `,
    variables: {
        "input": {
            "title": "Our entire shoe collection",
            "descriptionHtml": "View <b>every</b> shoe available in our store.",
            "ruleSet": {
                "appliedDisjunctively": false,
                "rules": {
                    "column": "TITLE",
                    "relation": "CONTAINS",
                    "condition": "shoe"
                }
            }
        }
    },
  }),
});

const { data } = await response.json();
console.log(data);

Response

{
  "collectionCreate": {
    "userErrors": [],
    "collection": {
      "id": "gid://shopify/Collection/1063001438",
      "title": "Our entire shoe collection",
      "descriptionHtml": "View <b>every</b> shoe available in our store.",
      "handle": "our-entire-shoe-collection",
      "sortOrder": "MOST_RELEVANT",
      "ruleSet": {
        "appliedDisjunctively": false,
        "rules": [
          {
            "column": "TITLE",
            "relation": "CONTAINS",
            "condition": "shoe"
          }
        ]
      }
    }
  }
}

Create a smart collection with metafield definition conditions

Description

Create a [smart collection](https://help.shopify.com/manual/products/collections/smart-collections) that contains all products with the specific product and variant [metafield definition conditions](https://shopify.dev/docs/apps/build/custom-data/metafields/definitions). The collection includes all products that have the product metafield value `leather` and the variant metafield value `true`.

Query

mutation CollectionCreate($input: CollectionInput!) {
  collectionCreate(input: $input) {
    userErrors {
      field
      message
    }
    collection {
      id
      title
      descriptionHtml
      handle
      sortOrder
      ruleSet {
        appliedDisjunctively
        rules {
          column
          relation
          condition
          conditionObject {
            ... on CollectionRuleMetafieldCondition {
              metafieldDefinition {
                id
                name
                type {
                  name
                }
                ownerType
              }
            }
          }
        }
      }
    }
  }
}

Variables

{
  "input": {
    "title": "Our entire leather collection",
    "descriptionHtml": "Check out our leather products.",
    "ruleSet": {
      "appliedDisjunctively": false,
      "rules": [
        {
          "column": "PRODUCT_METAFIELD_DEFINITION",
          "relation": "EQUALS",
          "condition": "leather",
          "conditionObjectId": "gid://shopify/MetafieldDefinition/1071456136"
        },
        {
          "column": "VARIANT_METAFIELD_DEFINITION",
          "relation": "EQUALS",
          "condition": "true",
          "conditionObjectId": "gid://shopify/MetafieldDefinition/1071456137"
        }
      ]
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation CollectionCreate($input: CollectionInput!) { collectionCreate(input: $input) { userErrors { field message } collection { id title descriptionHtml handle sortOrder ruleSet { appliedDisjunctively rules { column relation condition conditionObject { ... on CollectionRuleMetafieldCondition { metafieldDefinition { id name type { name } ownerType } } } } } } } }",
 "variables": {
    "input": {
      "title": "Our entire leather collection",
      "descriptionHtml": "Check out our leather products.",
      "ruleSet": {
        "appliedDisjunctively": false,
        "rules": [
          {
            "column": "PRODUCT_METAFIELD_DEFINITION",
            "relation": "EQUALS",
            "condition": "leather",
            "conditionObjectId": "gid://shopify/MetafieldDefinition/1071456136"
          },
          {
            "column": "VARIANT_METAFIELD_DEFINITION",
            "relation": "EQUALS",
            "condition": "true",
            "conditionObjectId": "gid://shopify/MetafieldDefinition/1071456137"
          }
        ]
      }
    }
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation CollectionCreate($input: CollectionInput!) {
    collectionCreate(input: $input) {
      userErrors {
        field
        message
      }
      collection {
        id
        title
        descriptionHtml
        handle
        sortOrder
        ruleSet {
          appliedDisjunctively
          rules {
            column
            relation
            condition
            conditionObject {
              ... on CollectionRuleMetafieldCondition {
                metafieldDefinition {
                  id
                  name
                  type {
                    name
                  }
                  ownerType
                }
              }
            }
          }
        }
      }
    }
  }`,
  {
    variables: {
        "input": {
            "title": "Our entire leather collection",
            "descriptionHtml": "Check out our leather products.",
            "ruleSet": {
                "appliedDisjunctively": false,
                "rules": [
                    {
                        "column": "PRODUCT_METAFIELD_DEFINITION",
                        "relation": "EQUALS",
                        "condition": "leather",
                        "conditionObjectId": "gid://shopify/MetafieldDefinition/1071456136"
                    },
                    {
                        "column": "VARIANT_METAFIELD_DEFINITION",
                        "relation": "EQUALS",
                        "condition": "true",
                        "conditionObjectId": "gid://shopify/MetafieldDefinition/1071456137"
                    }
                ]
            }
        }
    },
  },
  );
  const json = await response.json();
  return json.data;
}

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 CollectionCreate($input: CollectionInput!) {
    collectionCreate(input: $input) {
      userErrors {
        field
        message
      }
      collection {
        id
        title
        descriptionHtml
        handle
        sortOrder
        ruleSet {
          appliedDisjunctively
          rules {
            column
            relation
            condition
            conditionObject {
              ... on CollectionRuleMetafieldCondition {
                metafieldDefinition {
                  id
                  name
                  type {
                    name
                  }
                  ownerType
                }
              }
            }
          }
        }
      }
    }
  }
QUERY

variables = {
  "input": {
    "title": "Our entire leather collection",
    "descriptionHtml": "Check out our leather products.",
    "ruleSet": {
      "appliedDisjunctively": false,
      "rules": [
        {
          "column": "PRODUCT_METAFIELD_DEFINITION",
          "relation": "EQUALS",
          "condition": "leather",
          "conditionObjectId": "gid://shopify/MetafieldDefinition/1071456136"
        },
        {
          "column": "VARIANT_METAFIELD_DEFINITION",
          "relation": "EQUALS",
          "condition": "true",
          "conditionObjectId": "gid://shopify/MetafieldDefinition/1071456137"
        }
      ]
    }
  }
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation CollectionCreate($input: CollectionInput!) {
      collectionCreate(input: $input) {
        userErrors {
          field
          message
        }
        collection {
          id
          title
          descriptionHtml
          handle
          sortOrder
          ruleSet {
            appliedDisjunctively
            rules {
              column
              relation
              condition
              conditionObject {
                ... on CollectionRuleMetafieldCondition {
                  metafieldDefinition {
                    id
                    name
                    type {
                      name
                    }
                    ownerType
                  }
                }
              }
            }
          }
        }
      }
    }`,
    "variables": {
        "input": {
            "title": "Our entire leather collection",
            "descriptionHtml": "Check out our leather products.",
            "ruleSet": {
                "appliedDisjunctively": false,
                "rules": [
                    {
                        "column": "PRODUCT_METAFIELD_DEFINITION",
                        "relation": "EQUALS",
                        "condition": "leather",
                        "conditionObjectId": "gid://shopify/MetafieldDefinition/1071456136"
                    },
                    {
                        "column": "VARIANT_METAFIELD_DEFINITION",
                        "relation": "EQUALS",
                        "condition": "true",
                        "conditionObjectId": "gid://shopify/MetafieldDefinition/1071456137"
                    }
                ]
            }
        }
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation CollectionCreate($input: CollectionInput!) {
  collectionCreate(input: $input) {
    userErrors {
      field
      message
    }
    collection {
      id
      title
      descriptionHtml
      handle
      sortOrder
      ruleSet {
        appliedDisjunctively
        rules {
          column
          relation
          condition
          conditionObject {
            ... on CollectionRuleMetafieldCondition {
              metafieldDefinition {
                id
                name
                type {
                  name
                }
                ownerType
              }
            }
          }
        }
      }
    }
  }
}' \
--variables \
'{
  "input": {
    "title": "Our entire leather collection",
    "descriptionHtml": "Check out our leather products.",
    "ruleSet": {
      "appliedDisjunctively": false,
      "rules": [
        {
          "column": "PRODUCT_METAFIELD_DEFINITION",
          "relation": "EQUALS",
          "condition": "leather",
          "conditionObjectId": "gid://shopify/MetafieldDefinition/1071456136"
        },
        {
          "column": "VARIANT_METAFIELD_DEFINITION",
          "relation": "EQUALS",
          "condition": "true",
          "conditionObjectId": "gid://shopify/MetafieldDefinition/1071456137"
        }
      ]
    }
  }
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation CollectionCreate($input: CollectionInput!) {
        collectionCreate(input: $input) {
          userErrors {
            field
            message
          }
          collection {
            id
            title
            descriptionHtml
            handle
            sortOrder
            ruleSet {
              appliedDisjunctively
              rules {
                column
                relation
                condition
                conditionObject {
                  ... on CollectionRuleMetafieldCondition {
                    metafieldDefinition {
                      id
                      name
                      type {
                        name
                      }
                      ownerType
                    }
                  }
                }
              }
            }
          }
        }
      }
    `,
    variables: {
        "input": {
            "title": "Our entire leather collection",
            "descriptionHtml": "Check out our leather products.",
            "ruleSet": {
                "appliedDisjunctively": false,
                "rules": [
                    {
                        "column": "PRODUCT_METAFIELD_DEFINITION",
                        "relation": "EQUALS",
                        "condition": "leather",
                        "conditionObjectId": "gid://shopify/MetafieldDefinition/1071456136"
                    },
                    {
                        "column": "VARIANT_METAFIELD_DEFINITION",
                        "relation": "EQUALS",
                        "condition": "true",
                        "conditionObjectId": "gid://shopify/MetafieldDefinition/1071456137"
                    }
                ]
            }
        }
    },
  }),
});

const { data } = await response.json();
console.log(data);

Response

{
  "collectionCreate": {
    "userErrors": [],
    "collection": {
      "id": "gid://shopify/Collection/1063001433",
      "title": "Our entire leather collection",
      "descriptionHtml": "Check out our leather products.",
      "handle": "our-entire-leather-collection",
      "sortOrder": "MOST_RELEVANT",
      "ruleSet": {
        "appliedDisjunctively": false,
        "rules": [
          {
            "column": "PRODUCT_METAFIELD_DEFINITION",
            "relation": "EQUALS",
            "condition": "leather",
            "conditionObject": {
              "metafieldDefinition": {
                "id": "gid://shopify/MetafieldDefinition/1071456136",
                "name": "Material",
                "type": {
                  "name": "single_line_text_field"
                },
                "ownerType": "PRODUCT"
              }
            }
          },
          {
            "column": "VARIANT_METAFIELD_DEFINITION",
            "relation": "EQUALS",
            "condition": "true",
            "conditionObject": {
              "metafieldDefinition": {
                "id": "gid://shopify/MetafieldDefinition/1071456137",
                "name": "Imported",
                "type": {
                  "name": "boolean"
                },
                "ownerType": "PRODUCTVARIANT"
              }
            }
          }
        ]
      }
    }
  }
}

collectionCreate reference

Examples

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {

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

const response = await admin.graphql(

`#graphql

mutation CollectionCreate($input: CollectionInput!) {

collectionCreate(input: $input) {

userErrors {

field

message

}

collection {

title

image {

url

altText

}

}`,

{

variables: {

"input": {

"title": "Collection with Image",

"image": {

"src": "tmp/26371970/collections/2fb4c50b-b04b-4ee8-a857-52b7ad9e5d2d/test_file.txt",

"altText": "A beautiful collection image"

}

);

const json = await response.json();

return json.data;

}

GQL

mutation CollectionCreate($input: CollectionInput!) {
  collectionCreate(input: $input) {
    userErrors {
      field
      message
    }
    collection {
      id
      title
      image {
        url
        altText
      }
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation CollectionCreate($input: CollectionInput!) { collectionCreate(input: $input) { userErrors { field message } collection { id title image { url altText } } } }",
 "variables": {
    "input": {
      "title": "Collection with Image",
      "image": {
        "src": "tmp/26371970/collections/2fb4c50b-b04b-4ee8-a857-52b7ad9e5d2d/test_file.txt",
        "altText": "A beautiful collection image"
      }
    }
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation CollectionCreate($input: CollectionInput!) {
    collectionCreate(input: $input) {
      userErrors {
        field
        message
      }
      collection {
        id
        title
        image {
          url
          altText
        }
      }
    }
  }`,
  {
    variables: {
        "input": {
            "title": "Collection with Image",
            "image": {
                "src": "tmp/26371970/collections/2fb4c50b-b04b-4ee8-a857-52b7ad9e5d2d/test_file.txt",
                "altText": "A beautiful collection image"
            }
        }
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation CollectionCreate($input: CollectionInput!) {
      collectionCreate(input: $input) {
        userErrors {
          field
          message
        }
        collection {
          id
          title
          image {
            url
            altText
          }
        }
      }
    }`,
    "variables": {
        "input": {
            "title": "Collection with Image",
            "image": {
                "src": "tmp/26371970/collections/2fb4c50b-b04b-4ee8-a857-52b7ad9e5d2d/test_file.txt",
                "altText": "A beautiful collection image"
            }
        }
    },
  },
});

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 CollectionCreate($input: CollectionInput!) {
    collectionCreate(input: $input) {
      userErrors {
        field
        message
      }
      collection {
        id
        title
        image {
          url
          altText
        }
      }
    }
  }
QUERY

variables = {
  "input": {
    "title": "Collection with Image",
    "image": {
      "src": "tmp/26371970/collections/2fb4c50b-b04b-4ee8-a857-52b7ad9e5d2d/test_file.txt",
      "altText": "A beautiful collection image"
    }
  }
}

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

Shopify CLI

shopify app execute \
--query \
'mutation CollectionCreate($input: CollectionInput!) {
  collectionCreate(input: $input) {
    userErrors {
      field
      message
    }
    collection {
      id
      title
      image {
        url
        altText
      }
    }
  }
}' \
--variables \
'{
  "input": {
    "title": "Collection with Image",
    "image": {
      "src": "tmp/26371970/collections/2fb4c50b-b04b-4ee8-a857-52b7ad9e5d2d/test_file.txt",
      "altText": "A beautiful collection image"
    }
  }
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation CollectionCreate($input: CollectionInput!) {
        collectionCreate(input: $input) {
          userErrors {
            field
            message
          }
          collection {
            id
            title
            image {
              url
              altText
            }
          }
        }
      }
    `,
    variables: {
        "input": {
            "title": "Collection with Image",
            "image": {
                "src": "tmp/26371970/collections/2fb4c50b-b04b-4ee8-a857-52b7ad9e5d2d/test_file.txt",
                "altText": "A beautiful collection image"
            }
        }
    },
  }),
});

const { data } = await response.json();
console.log(data);

Input variables

JSON

{

"input": {

"title": "Collection with Image",

"image": {

"src": "tmp/26371970/collections/2fb4c50b-b04b-4ee8-a857-52b7ad9e5d2d/test_file.txt",

"altText": "A beautiful collection image"

}

Response

JSON

{

"collectionCreate": {

"userErrors": [],

"collection": {

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

"title": "Collection with Image",

"image": {

"url": "https://cdn.shopify.com/s/files/1/2637/1970/collections/test_file.jpg?v=1781273014",

"altText": "A beautiful collection image"

}