Skip to main content

Creating Variants for Custom Products via CSV Import (New)

Create variants for Custom products in bulk using CSV import. Covers the variant fields (productVariantKey, options, values), file structure, consistency requirements, and how to resolve common upload errors.

Requirements

Before proceeding, ensure the following:

  • You have access to a Commerce Automation Manager (CAM) account with permissions to import products.

  • You are signed in at my.catalogkiosk.com using the Google Chrome browser.

  • You are familiar with the general CSV import process. See How to Import Products for the complete import procedure, including required fields for product creation.

  • The products you intend to link as variants are Custom products. CSV-based variant management is not supported for Managed (feed-based) products.

Core Concepts

Variants in Wonder

In Wonder, every variant is an individual product with its own SKU. A Variant Group is a set of products linked together by a shared identifier, allowing customers to browse them as a single product family with selectable options (for example, size or color).

Creating variants via CSV therefore means importing or updating a set of products that share the variant identifier fields described below.

Import scenarios

The CSV import supports two scenarios. The required fields differ between them:

Scenario

Description

Required fields

Scenario A: Create products and variants simultaneously

The products do not yet exist in your account. A single CSV creates the products and links them as variants in one operation.

All required fields for Custom product creation (brand, sku, name, price.cost) plus the variant fields described below. See How to Import Products for the complete field requirements, including Shopify Connector requirements.

Scenario B: Add variants to existing products

The products already exist in your account. The CSV contains only the data needed to identify each product and link it into a Variant Group.

brand and sku (used to identify and match each existing product) plus the variant fields described below.

Note: In both scenarios, brand and sku are mandatory on every row. In Scenario A, they are part of product creation; in Scenario B, they are the matching keys that identify which existing products to update.

Variant field reference

The following fields define variant relationships in the CSV file:

Field

Description

productVariantKey

Required

The unique identifier that links all variants in a group. Every row belonging to the same Variant Group must contain the identical key. The key must be unique within your Wonder account.

productVariantTitle

Required

The Variant Group title displayed to customers on product listing and search views.

productVariantDescription

Required

The shared description for the Variant Group. This field is displayed only through a Wonder Connector (Shopify, BigCommerce, or WooCommerce), where it serves as the product description for all variants in the group, regardless of which variant the customer selects.

variants.0.option

Required

The name of the first option type (for example: color, size, material, configuration). Custom option names are supported.

variants.0.values.0

Required

The value of the first option for the specific variant on that row (for example: Black, Queen).

variants.1.option / variants.1.values.0

Optional

The second option type and its value. Use when variants differ across more than one dimension.

variants.2.option / variants.2.values.0

Optional

The third option type and its value.

A Variant Group supports a maximum of 5 option types (variants.0 through variants.4).

Field consistency requirements

For all rows sharing the same productVariantKey, the following fields must be identical, character for character:

  • productVariantTitle

  • productVariantDescription

  • variants.0.option (and any additional variants.#.option fields in use)

Only the value fields (variants.0.values.0, variants.1.values.0, etc.) may differ between rows. These values are what distinguish one variant from another.

The import validates this consistency. Any discrepancy, including capitalization differences, punctuation differences, or a single trailing space, will block the upload. See the Troubleshooting section for the associated error message and resolution steps.

Key assignment guidelines

The productVariantKey accepts any string value. The following constraints and recommendations apply:

Constraints:

  • The key must be unique within your Wonder account. A key already assigned to an existing Variant Group cannot be reused.

  • The key must be identical on every row of the same Variant Group.

Recommended format: Use a short, sequential alphanumeric scheme that your team controls. Examples:

VG-001, VG-002, VG-003 (sequential)

VG-2026-001, VG-2026-002 (sequential with year)

MATTRESS-001, SECTIONAL-001 (grouped by product type)

Key register: Maintain an internal log (spreadsheet or document) recording each key, its Variant Group title, and the SKUs it contains. This prevents duplicate key assignment and simplifies later additions to existing Variant Groups.

Step-by-Step Guide

Step 1 — Structure the CSV file

Each row in the file represents one product and, therefore, one variant.

The following example shows a complete Variant Group: a foundation product from Ashley Furniture available in six sizes, all in one color.

Structural rules demonstrated in this example:

  • brand — identical on every row. All variants in a group must belong to the same manufacturer.

  • sku — unique on every row. Each variant is a distinct product.

  • productVariantKey — identical on every row. This is the linking identifier.

  • productVariantTitle and productVariantDescription — identical on every row, per the consistency requirements.

  • variants.0.option (color) — identical on every row. Its value (Black) is also identical here because all variants in this group share one color.

  • variants.1.option (size) — identical on every row. Its value varies per row — this is the dimension that differentiates the variants.

For products that vary across additional dimensions (for example, a sectional sofa available in multiple configurations, fabrics, and colors), add additional option pairs (variants.2.option / variants.2.values.0, up to variants.4). Each row then carries the unique combination of values defining that variant.

Recommendation: To satisfy the consistency requirements, enter the shared field values (productVariantTitle, productVariantDescription, option names) once in the first row, then copy and paste them to all remaining rows in the group. Manual retyping frequently introduces undetectable differences such as trailing spaces.

Save the completed file in CSV format.

Step 2 — Open the Import Products tool

  1. In CAM, click Content in the top navigation.

  2. Click Products from the drop-down.

  3. Click the green Import Products button.

The import process consists of four stages: Introduction, Import Settings, File Upload, and Column Mapping. This guide covers the variant-relevant configuration; for the complete walkthrough, see How to Import Products.

Step 3 — Configure Import Settings

In the Import Settings stage, select the options corresponding to your scenario:

Scenario

Required setting

A — Creating products and variants simultaneously

Check Create new products that don't exist in the database.

B — Adding variants to existing products

Check Update existing products in the database only. Leave "Create new products" unchecked.

Mixed file (new and existing products)

Check both options.

Recommendation for Scenario B: Also check Skip empty fields. This prevents the import from deleting existing product data when the corresponding CSV column is empty.

Step 4 — Upload the file

  1. In the File Upload stage, click Choose File and select your CSV.

  2. If your file includes a header row (recommended), leave CSV Has Header Row checked.

  3. Click Next after the confirmation message File Captured appears.

Step 5 — Verify Column Mapping

In the Column Mapping stage, the system automatically maps columns whose header names exactly match the field names (productVariantKey, productVariantTitle, variants.0.option, etc.). Successfully mapped columns display a green header.

If a column header does not match a field name, the column remains unmapped and must be assigned manually:

  1. Click the drop-down at the top of the unmapped column.

  2. Scroll to the bottom of the field list. The variant fields are grouped:

    • productVariantKey

    • productVariantTitle

    • productVariantDescription

    • variants.#.option

    • variants.#.values.#

  3. Select the correct field for the column.

Mapping behavior to note:

  • productVariantKey, productVariantTitle, and productVariantDescription can each be assigned to one column only. After assignment, they are removed from the drop-down list.

  • variants.#.option and variants.#.values.# remain available in the drop-down after assignment, because they can be mapped multiple times (once per option pair, up to 5).

Step 6 — Run the import and monitor progress

  1. Click Finish to start the import. The file processes in the background; CAM remains fully usable during this time.

  2. To monitor progress, click the Background Tasks icon (checkmark) in the top navigation, then click See Details.

  3. The task list displays the status, timestamps, and outcome of each import. If errors occurred, click Download log file to obtain a row-by-row error report.

Step 7 — Verify the variants in CAM

  1. Navigate to any product included in the import.

  2. Open the Variants tab.

  3. Confirm the following:

    • All variants in the group are listed.

    • The Variant Group title and description are correct.

    • Each variant displays the correct option values.

Adjustments can be made directly in CAM after import. See Getting Started with Variant Management for editing variants, options, and values.

Troubleshooting

Error: Inconsistent variant fields

Message: For products with the same productVariantKey, please ensure that the productVariantTitle, productVariantDescription, and variants.X.option are also consistent...

Cause: At least two rows share a productVariantKey but contain a difference in one or more of the shared fields (productVariantTitle, productVariantDescription, or any variants.#.option). The upload is blocked until the inconsistency is resolved.

Common sources of inconsistency:

  • Trailing or leading spaces in any shared field

  • Capitalization differences (color vs. Color)

  • Punctuation differences, including curly versus straight quotation marks

  • Line-break differences within the description field

Resolution:

  1. Open the CSV file in your spreadsheet application.

  2. Sort or filter the rows by productVariantKey.

  3. Compare the shared columns across all rows in each group and correct any differences.

  4. To eliminate hidden character differences, re-copy the value from one reference row and paste it into all other rows of the group.

  5. Save and re-upload the file.

Error: Brand mismatch within a Variant Group

Cause: Rows sharing a productVariantKey contain different brand values. All variants in a group must belong to the same manufacturer.

Resolution: Correct the brand values so that all rows in the group are identical, or assign products from different manufacturers to separate Variant Groups.

Variants do not appear after import

Resolution steps:

  1. Check the Background Tasks log for errors and download the log file if available.

  2. Verify that the productVariantKey is identical across all intended rows.

  3. Verify that the consistency requirements were met (see above).

  4. Confirm that the affected products are Custom products. Variant data in CSV imports does not apply to Managed products.

Related Articles
How to Import and Manage Local Inventory
How to Create a Catalog
How to Import Products
1st Gen Elo 22" - Unsupported Features
Getting Started with Variant Management (New)
Did this answer your question?