Skip to main content

Create Product

Create Product Mutation

This mutation creates a new product in the store with comprehensive product information including variants, options, pricing, and metadata.

⚠️ IMPORTANT: Required Workflow for Products with Variants​

Products with variants now require options and option values to be created FIRST before creating the product.

Required Steps for Products with Variants:​

  1. Create Product Options using CreateProductOption mutation

    • Create each option (e.g., "Size", "Color", "Material")
    • Note the returned option IDs

  2. Create Option Values using CreateProductOptionValue mutation

    • Create values for each option (e.g., "Small", "Medium", "Large" for Size)
    • Note the returned option value IDs

  3. Create Product using this CreateProduct mutation

    • Reference existing option IDs in the options array (only id and position required)
    • Reference existing option value IDs in variant selectedOptions

Example Workflow:​

# Step 1: Create Size option
mutation CreateSizeOption {
  createProductOption(input: {
    name: "Size"
    position: 1
    locale: "en"
    storeId: "your_store_id"
  }) {
    id  # Save this ID: "option_size_123"
  }
}

# Step 2: Create Size option values
mutation CreateSizeValues {
  createProductOptionValue(input: {
    name: "Small"
    optionId: "option_size_123"
    locale: "en" 
    storeId: "your_store_id"
  }) {
    id  # Save this ID: "value_small_456"
  }
}

# Step 3: Create product with existing option references
mutation CreateProduct {
  createProduct(input: {
    title: "T-Shirt"
    options: [
      { id: "option_size_123", position: 1 }
    ]
    variants: [
      {
        title: "Small T-Shirt"
        selectedOptions: [
          { optionId: "option_size_123", valueId: "value_small_456" }
        ]
      }
    ]
  })
}

Use Cases​

  • Product Catalog Management: Add new products to your store inventory
  • Bulk Product Import: Create products programmatically from external systems
  • Product Variants: Create products with multiple variants (size, color, etc.)
  • SEO Optimization: Set up products with proper SEO metadata
  • Inventory Management: Initialize products with stock quantities and tracking

Key Features​

Product Information​

  • Basic Details: Title, description, handle, and product type
  • Visibility Controls: Set product visibility and archive status
  • Status Management: Control product status (ACTIVE, DRAFT, etc.)
  • Source Tracking: Track how products were created (MANUAL, IMPORT)

Pricing and Tax​

  • Initial Pricing: Set base product price
  • Tax Configuration: Configure tax settings and rates
  • Cost Tracking: Track product costs for profit analysis

Product Variants​

  • Multiple Variants: Create products with different combinations of options
  • Individual Pricing: Set unique prices for each variant
  • Inventory Tracking: Manage stock levels per variant
  • Cart Limits: Set minimum and maximum cart quantities
  • Package Details: Define weight and dimensions for shipping

Product Options (Pre-created)​

  • Option References: Reference pre-created option IDs
  • Position Control: Set display order for options
  • Variant Mapping: Map variants to specific option value combinations

SEO and Marketing​

  • SEO Metadata: Set custom title and description for search engines
  • URL Handle: Create SEO-friendly product URLs
  • Product Images: Associate images with products

Input Parameters​

  • $input: ProductInput! - Complete product information including:
    • storeId: Store identifier where the product will be created
    • title: Product name/title
    • type: Product type (SIMPLE, VARIABLE, etc.)
    • status: Product status (ACTIVE, DRAFT, ARCHIVED) - Required
    • descriptionHtml: Full HTML product description
    • shortDescription: Brief product summary
    • handle: URL-friendly product slug
    • taxable: Whether product is subject to tax
    • productTax: Tax rate (as decimal, e.g., 0.08 for 8%)
    • seo: SEO metadata object
    • variants: Array of product variants with options array containing option value IDs
    • options: Array of option references with existing option id and position (starting from 0)
    • attributes: Array of product attributes (can be empty array)
    • collectionsToJoin: Array of collection IDs to add product to (can be empty array)
  • $media: [CreateMediaInput!] - Array of media/images to attach (can be empty array)
  • $locale: String! - Language locale for the product content

Option Structure​

NEW (Required approach):

"options": [
  {
    "id": "ProductOption_color_id",
    "position": 0
  }
]

Variant Options Structure​

Variants reference option values directly:

"variants": [
  {
    "options": [
      "ProductOptionValue_red_id",
      "ProductOptionValue_small_id"
    ],
    "sku": "TSHIRT-RED-SM",
    "price": {"amount": 29.99, "currencyCode": "USD"}
  }
]

Response Structure​

The mutation returns a CreateProductPayload containing:

  • product: Complete product object with all created data
  • Generated IDs for the product, variants, and options
  • Timestamps for creation
  • All associated metadata and relationships

Example Response​

{
  "data": {
    "createProduct": {
      "product": {
        "id": "Product_abc123",
        "title": "Premium Wireless Headphones",
        "handle": "premium-wireless-headphones",
        "type": "SIMPLE",
        "status": "ACTIVE",
        "source": "MANUAL",
        "isVisible": true,
        "isArchived": false,
        "locale": "en",
        "shortDescription": "Premium wireless headphones with noise cancellation",
        "descriptionHtml": "<p>High-quality wireless headphones...</p>",
        "taxable": true,
        "productTax": 0.1,
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z",
        "variants": {
          "nodes": [
            {
              "id": "Variant_xyz789",
              "title": "Black / Standard",
              "sku": "PWH-BLK-STD",
              "price": {
                "amount": 299.99,
                "currencyCode": "USD"
              },
              "quantity": 50,
              "trackQuantity": true
            }
          ]
        },
        "options": [
          {
            "id": "Option_color123",
            "name": "Color",
            "position": 1,
            "values": [
              {
                "id": "OptionValue_black456",
                "name": "Black"
              }
            ]
          }
        ]
      }
    }
  }
}

Implementation Notes​

Validation Requirements​

  • Product title is required and must be unique within the store
  • Handle must be URL-friendly and unique
  • At least one variant is typically required for SIMPLE products
  • Option values must correspond to variant selections

Best Practices​

  • Use descriptive, SEO-friendly handles
  • Set appropriate tax settings based on product category
  • Include comprehensive product descriptions
  • Configure proper inventory tracking
  • Set realistic cart limits to prevent overselling

Error Handling​

  • Handle duplicate handle errors by generating unique alternatives
  • Validate price formats and currency codes
  • Ensure option-variant consistency
  • Check store permissions and limits

Required Prerequisites (for products with variants):​

  • createProductOption - Create product options first
  • createProductOptionValue - Create option values first
  • createProductAttribute - Create product attributes first
  • createProductAttributeValue - Create attribute values first

Product Management:​

  • updateProduct - Update existing product information
  • createCollection - Create product collections
  • addProductsToCollection - Add products to collections
  • archiveProducts - Archive multiple products
  • ListStoreProducts - Query created products

Queries for Existing Options/Attributes:​

  • productOptions - List existing product options
  • productOptionValues - List existing option values
  • productAttributes - List existing product attributes
  • productAttributeValues - List existing attribute values

GraphQL Endpoint​

https://graphql.wuilt.com

Operation: CreateProduct​

Try It Out​

Query​

mutation CreateProduct(
$input: ProductInput!
$media: [CreateMediaInput!]
$locale: String!
) {
createProduct(input: $input, media: $media, locale: $locale) {
  product {
    id
    title
    handle
    type
    status
    source
    isVisible
    isArchived
    locale
    shortDescription
    descriptionHtml
    taxable
    productTax
    createdAt
    updatedAt
    images {
      id
      src
      altText
      width
      height
      __typename
    }
    seo {
      title
      description
      __typename
    }
    options {
      id
      name
      position
      values {
        id
        name
        __typename
      }
      __typename
    }
    attributes {
      id
      name
      type
      values {
        id
        name
        __typename
      }
      __typename
    }
    collections {
      nodes {
        id
        title
        __typename
      }
      totalCount
      __typename
    }
    variants(first: 10) {
      nodes {
        id
        title
        sku
        price {
          amount
          currencyCode
          __typename
        }
        compareAtPrice {
          amount
          currencyCode
          __typename
        }
        cost {
          amount
          currencyCode
          __typename
        }
        quantity
        trackQuantity
        selectedOptions {
          option {
            id
            name
            __typename
          }
          value {
            id
            name
            __typename
          }
          __typename
        }
        externalId
        cartLimitsEnabled
        minPerCart
        maxPerCart
        packageDetails {
          weight
          dimensions {
            length
            width
            height
            __typename
          }
          __typename
        }
        createdAt
        updatedAt
        __typename
      }
      __typename
    }
    __typename
  }
  __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
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

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.