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.

There are two types of collections:

Custom (manual) collections: You specify the products to include in a collection.
Smart (automated) collections: You define rules, and products matching those rules are automatically included in the collection.

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 rules (for example, by tag, type, or price)

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 smart collections.

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?

Create a collection with an image
Create a custom collection
Create a new metafield on a new collection
Create a smart collection
Create a smart collection with metafield definition conditions
collectionCreate reference

Examples

Open in GraphiQL

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/e36e8f91-08a6-46f0-8db7-dd37a55ccd57/test_file",

"altText": "A beautiful collection image"

}

);

const data = await response.json();

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

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2024-07/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/e36e8f91-08a6-46f0-8db7-dd37a55ccd57/test_file",
        "altText": "A beautiful collection image"
      }
    }
  }
}'

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/e36e8f91-08a6-46f0-8db7-dd37a55ccd57/test_file",
          "altText": "A beautiful collection image"
        }
      }
    },
  },
);

const data = await response.json();

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/e36e8f91-08a6-46f0-8db7-dd37a55ccd57/test_file",
          "altText": "A beautiful collection image"
        }
      }
    },
  },
});

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/e36e8f91-08a6-46f0-8db7-dd37a55ccd57/test_file",
      "altText": "A beautiful collection image"
    }
  }
}

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

Input variables

JSON

{

"input": {

"title": "Collection with Image",

"image": {

"src": "tmp/26371970/collections/e36e8f91-08a6-46f0-8db7-dd37a55ccd57/test_file",

"altText": "A beautiful collection image"

}

Response

JSON

{

"collectionCreate": {

"userErrors": [],

"collection": {

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

"title": "Collection with Image",

"image": {

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

"altText": "A beautiful collection image"

}