Skip to main content

Create Collection

Create Collection Mutation

This mutation creates a new product collection in the store, allowing you to group related products together for better organization and marketing.

Use Cases​

  • Product Organization: Group related products by category, brand, or theme
  • Marketing Campaigns: Create seasonal or promotional collections
  • Store Navigation: Organize products for easier customer browsing
  • SEO Strategy: Create targeted landing pages for product groups
  • Multilingual Stores: Support collections in multiple languages

Key Features​

Collection Information​

  • Basic Details: Title, description, and URL handle
  • Visibility Controls: Control collection visibility in storefront
  • Status Management: Archive or delete collections as needed
  • Rich Content: HTML descriptions with formatting support

Product Management​

  • Initial Products: Add products during collection creation
  • Product Relationships: Automatically establish product-collection links
  • Dynamic Updates: Collections update automatically when products change

SEO and Marketing​

  • SEO Metadata: Custom title and description for search engines
  • URL Handle: SEO-friendly collection URLs
  • Collection Images: Featured images for collection pages
  • Social Sharing: Optimized metadata for social media

Internationalization​

  • Multi-language Support: Create collections in multiple languages
  • Localized Content: Translate titles, descriptions, and SEO metadata
  • Regional Customization: Adapt collections for different markets

Input Parameters​

  • $input: CollectionInput! - Complete collection information including:
    • storeId: Store identifier where the collection will be created
    • title: Collection name/title
    • handle: URL-friendly collection slug
    • descriptionHtml: Full HTML collection description
    • shortDescription: Brief collection summary
    • isVisible: Whether collection appears in storefront
    • isArchived: Archive status for internal organization
    • isDeleted: Soft delete status
    • image: Featured collection image
    • seo: SEO metadata object
    • productsToAdd: Array of product IDs to include initially
    • translations: Array of translations for different locales
  • $locale: String - Primary language locale for the collection (optional)

Response Structure​

The mutation returns a CreateCollectionPayload containing:

  • collection: Complete collection object with all created data
  • Associated products with basic information
  • Generated IDs and timestamps
  • All translations and metadata

Collection Fields Detail​

Basic Information​

  • id - Unique collection identifier
  • title - Collection name
  • handle - URL-friendly slug
  • descriptionHtml - Full HTML description
  • shortDescription - Brief summary
  • isVisible/isArchived/isDeleted - Status flags
  • locale - Primary language
  • createdAt/updatedAt - Timestamps

Associated Data​

  • image - Featured collection image with dimensions
  • seo - SEO metadata for search engines
  • products - Paginated list of collection products
  • translations - Array of localized versions

Example Response​

{
  "data": {
    "createCollection": {
      "collection": {
        "id": "Collection_electronics_001",
        "title": "Electronics & Gadgets",
        "handle": "electronics-gadgets",
        "descriptionHtml": "<p>Discover our curated collection...</p>",
        "shortDescription": "Cutting-edge electronics and innovative gadgets",
        "isVisible": true,
        "isArchived": false,
        "isDeleted": false,
        "locale": "en",
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z",
        "image": {
          "id": "Image_collection_banner_001",
          "src": "https://example.com/collections/electronics-banner.jpg",
          "altText": "Electronics and Gadgets Collection Banner",
          "width": 1200,
          "height": 600
        },
        "seo": {
          "title": "Electronics & Gadgets - Latest Technology Products",
          "description": "Shop the latest electronics and gadgets..."
        },
        "products": {
          "totalCount": 3,
          "nodes": [
            {
              "id": "Product_smartphone_001",
              "title": "iPhone 15 Pro",
              "handle": "iphone-15-pro",
              "status": "ACTIVE"
            }
          ]
        },
        "translations": [
          {
            "title": "الإلكترونيات والأجهزة",
            "locale": "ar",
            "seo": {
              "title": "الإلكترونيات والأجهزة - أحدث منتجات التكنولوجيا"
            }
          }
        ]
      }
    }
  }
}

Implementation Notes​

Validation Requirements​

  • Collection title must be unique within the store
  • Handle must be URL-friendly and unique
  • At least one translation is recommended for multilingual stores
  • Product IDs in productsToAdd must exist and be accessible

Best Practices​

  • Use descriptive, keyword-rich titles for SEO
  • Create meaningful handles that reflect collection content
  • Include comprehensive descriptions with relevant keywords
  • Set up proper image alt text for accessibility
  • Plan collection hierarchy for logical site navigation

Error Handling​

  • Handle duplicate handle errors with unique alternatives
  • Validate product IDs before adding to collection
  • Check store permissions and collection limits
  • Ensure translation locales are supported

Performance Considerations​

  • Limit initial product additions to essential items
  • Use pagination when querying collection products
  • Consider collection size impact on page load times
  • Optimize collection images for web performance
  • addProductsToCollection - Add more products to existing collections
  • removeProductsFromCollection - Remove products from collections
  • updateCollection - Update collection information
  • archiveCollection - Archive collections
  • ListStoreProducts - Query products to add to collections

GraphQL Endpoint​

https://graphql.wuilt.com

Operation: CreateCollection​

Try It Out​

Query​

mutation CreateCollection($input: CollectionInput!, $locale: String) {
createCollection(input: $input, locale: $locale) {
  collection {
    id
    title
    descriptionHtml
    productsCount
    locale
    locales
    handle
    seo {
      title
      description
    }
  }
  __typename
}
}

Query Variables

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

Note: Make sure to change the storeId with your store ID. For guidance on how to get your store ID, reference the Store ID guide.

Authentication​

To use this query, you will need an API key. Click the "API Key" button in the navigation bar to enter your credentials.