Add Products To Collection

Add Products to Collection Mutation

This mutation adds multiple products to an existing collection, allowing you to organize and group related products for better store navigation and marketing.

Use Cases

Collection Expansion: Add new products to existing collections
Product Organization: Group related products by category, brand, or theme
Marketing Campaigns: Add products to promotional or seasonal collections
Bulk Operations: Efficiently add multiple products at once
Inventory Management: Organize products for easier management
Store Navigation: Improve customer browsing experience

Key Features

Bulk Product Addition

Multiple Products: Add several products to a collection in one operation
Efficient Processing: Single API call for multiple product relationships
Atomic Operation: All products are added together or none at all
Relationship Management: Automatically establishes product-collection links

Collection Management

Existing Collections: Add products to any existing collection
Product Validation: Ensures all products exist and are accessible
Duplicate Prevention: Handles cases where products are already in the collection
Status Preservation: Maintains existing collection and product statuses

Response Data

Updated Collection: Returns the collection with updated product list
Product Details: Includes basic information about added products
Relationship Confirmation: Confirms successful product additions
Pagination Support: Handles large product lists with pagination

Input Parameters

$storeId: ID! - The unique identifier of the store
$id: ID! - The unique identifier of the collection to add products to
$productIds: [ID!]! - Array of product IDs to add to the collection

Response Structure

The mutation returns a CollectionAddProductsPayload containing:

collection: Updated collection object with new products included
Product list with pagination information
Collection metadata and settings
Confirmation of successful additions

Collection Fields Detail

Basic Information

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

Associated Products

products - Paginated list of collection products including newly added ones
totalCount - Total number of products in the collection
Product details including images, pricing, and availability
Pagination information for large product lists

Collection Metadata

image - Featured collection image
seo - SEO metadata for collection pages
Collection translations and localized content

Example Response

{
  "data": {
    "addProductsToCollection": {
      "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,
        "locale": "en",
        "updatedAt": "2024-01-15T14:30:00Z",
        "products": {
          "totalCount": 8,
          "nodes": [
            {
              "id": "Product_smartphone_galaxy_001",
              "title": "Samsung Galaxy S24 Ultra",
              "handle": "samsung-galaxy-s24-ultra",
              "status": "ACTIVE",
              "isVisible": true,
              "variants": {
                "nodes": [
                  {
                    "id": "Variant_galaxy_256gb_001",
                    "price": {
                      "amount": 1199.99,
                      "currencyCode": "USD"
                    },
                    "quantity": 25,
                    "isAvailable": true
                  }
                ]
              },
              "collections": {
                "totalCount": 2
              }
            },
            {
              "id": "Product_laptop_macbook_002",
              "title": "MacBook Pro 16-inch",
              "handle": "macbook-pro-16-inch",
              "status": "ACTIVE",
              "isVisible": true,
              "variants": {
                "nodes": [
                  {
                    "id": "Variant_macbook_512gb_001",
                    "price": {
                      "amount": 2499.99,
                      "currencyCode": "USD"
                    },
                    "quantity": 15,
                    "isAvailable": true
                  }
                ]
              }
            }
          ],
          "pageInfo": {
            "hasNextPage": true,
            "hasPreviousPage": false,
            "startCursor": "cursor_start",
            "endCursor": "cursor_end"
          }
        }
      }
    }
  }
}

Implementation Notes

Validation Requirements

Store ID must be valid and accessible
Collection ID must exist within the specified store
All product IDs must exist and be accessible
Products must belong to the same store as the collection
User must have permissions to modify the collection

Best Practices

Verify product availability before adding to collections
Consider collection theme and product relevance
Monitor collection size for performance implications
Use meaningful product groupings for better customer experience
Update collection metadata when adding significant products

Error Handling

Handle invalid store or collection IDs gracefully
Skip invalid product IDs and report which ones failed
Handle permission errors for restricted collections
Manage duplicate product additions (typically ignored)
Provide clear error messages for failed operations

Performance Considerations

Limit the number of products added in a single operation
Consider collection size impact on page load times
Use pagination when displaying large collections
Monitor database performance with large product lists
Cache collection data for frequently accessed collections

Duplicate Handling

When adding products that are already in the collection:

Typical Behavior: Duplicate additions are ignored (no error)
Idempotent Operation: Safe to retry without side effects
Response: Collection shows current state regardless of duplicates
No Errors: Existing relationships don't cause failures

removeProductsFromCollection - Remove products from collections
createCollection - Create new collections with initial products
updateCollection - Update collection information
ListStoreProducts - Query products to add to collections
collections - Query existing collections and their products

Use Case Examples

Seasonal Collection Update

{
  "storeId": "Store_example_001",
  "id": "Collection_summer_2024",
  "productIds": [
    "Product_sunglasses_001",
    "Product_swimwear_002",
    "Product_beach_accessories_003"
  ]
}

New Product Launch

{
  "storeId": "Store_example_001",
  "id": "Collection_new_arrivals",
  "productIds": [
    "Product_latest_smartphone_001",
    "Product_new_headphones_002"
  ]
}

Category Organization

{
  "storeId": "Store_example_001",
  "id": "Collection_home_office",
  "productIds": [
    "Product_desk_chair_001",
    "Product_monitor_002",
    "Product_keyboard_003",
    "Product_mouse_004"
  ]
}

GraphQL Endpoint

https://graphql.wuilt.com

Operation: AddProductsToCollection

Try It Out

Query

mutation AddProductsToCollection($storeId: ID!, $id: ID!, $productIds: [ID!]!) {
addProductsToCollection(storeId: $storeId, id: $id, productIds: $productIds) {
  collection {
    id
    title
    handle
    descriptionHtml
    shortDescription
    isVisible
    isArchived
    locale
    createdAt
    updatedAt
    image {
      id
      src
      altText
      width
      height
      __typename
    }
    seo {
      title
      description
      __typename
    }
    products(connection: { first: 20 }) {
      totalCount
      nodes {
        id
        title
        handle
        status
        isVisible
        createdAt
        images {
          id
          src
          altText
          __typename
        }
        variants(first: 1) {
          nodes {
            id
            price {
              amount
              currencyCode
              __typename
            }
            compareAtPrice {
              amount
              currencyCode
              __typename
            }
            quantity
            __typename
          }
          __typename
        }
        collections {
          nodes {
            id
            title
            __typename
          }
          totalCount
          __typename
        }
        __typename
      }
      pageInfo {
        hasNextPage
        hasPreviousPage
        startCursor
        endCursor
        __typename
      }
      __typename
    }
    __typename
  }
  __typename
}
}

Query Variables

Session ID header (optional)

{
"storeId": "Store_cm84j35iy02m001i89iiu2cts",
"id": "Collection_electronics_001",
"productIds": [
  "Product_smartphone_galaxy_001",
  "Product_laptop_macbook_002",
  "Product_tablet_ipad_003",
  "Product_smartwatch_apple_004",
  "Product_earbuds_airpods_005"
]
}

{
"storeId": "Store_cm84j35iy02m001i89iiu2cts",
"id": "Collection_electronics_001",
"productIds": [
  "Product_smartphone_galaxy_001",
  "Product_laptop_macbook_002",
  "Product_tablet_ipad_003",
  "Product_smartwatch_apple_004",
  "Product_earbuds_airpods_005"
]
}

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.

Add Products to Collection Mutation

Use Cases​

Key Features​

Bulk Product Addition​

Collection Management​

Response Data​

Input Parameters​

Response Structure​

Collection Fields Detail​

Basic Information​

Associated Products​

Collection Metadata​

Example Response​

Implementation Notes​

Validation Requirements​

Best Practices​

Error Handling​

Performance Considerations​

Duplicate Handling​

Related Operations​

Use Case Examples​

Seasonal Collection Update​

New Product Launch​

Category Organization​

GraphQL Endpoint​

Operation: AddProductsToCollection​

Try It Out​

Query​