Parent-Child Products

Organize product variants efficiently with parent-child relationships, enabling intelligent data aggregation and family-level management.

Overview

Parent-child product relationships allow you to structure your catalog hierarchically, where parent products represent a product family and child products represent specific variants. This structure is essential for managing products with multiple variations like colors, sizes, or configurations.

Benefits

• Logical Organization: Group product variants under a common parent
• Intelligent Aggregation: Automatically enrich parent products from child variant data
• Data Consistency: Validate parent attributes against child products
• Efficient Management: Filter, search, and manage by product type
• Better Analytics: Track performance at both variant and family levels

Concepts

Parent Products

Parent products are the main product entries that represent an entire product family. They typically:

• Have the isParent flag set to true
• Cannot have a parentId (parents can't be children)
• Contain aggregated attributes from all their variants
• Display type badge: Parent in the UI

Examples:

• "Classic T-Shirt" (with variants for different colors and sizes)
• "Wireless Mouse" (with variants for different colors)
• "Smartphone Model X" (with variants for storage capacity and colors)

Child Products (Variants)

Child products are specific variants that belong to a parent product. They:

• Have a parentId linking to their parent product
• Cannot be marked as isParent: true
• Contain specific variant attributes (e.g., "Red, Size M")
• Display type badge: Variant in the UI
• Show a link to their parent product in product tables

Examples:

• "Classic T-Shirt - Red, Medium"
• "Classic T-Shirt - Blue, Large"
• "Wireless Mouse - Black"

Relationship Rules

1. A product cannot be both a parent (isParent: true) and have a parentId
2. Parent products can have unlimited child products
3. Child products can only have one parent
4. Parent products should exist before linking children

Setting Up Parent-Child Relationships

Option 1: Via UI

Creating a Parent Product:

1. Go to Products → Add Product
2. Fill in product details
3. Check Mark as Parent Product checkbox
4. Click Create Product

Creating a Variant Product:

1. Go to Products → Add Product
2. Fill in product details for the specific variant
3. Click the Parent Product field and search by SKU or name to select the parent
4. Leave Mark as Parent Product unchecked
5. Click Create Product

Converting Existing Products:

1. Open the product detail page
2. To make it a parent:
   • Check Mark as Parent Product
   • Ensure the Parent Product field is cleared
3. To link to a parent:
   • Use the Parent Product searchable dropdown to select the parent
   • Ensure Mark as Parent Product is unchecked
4. Click Save Changes

Option 2: Via CSV Import

When importing products via CSV, include these columns:

• parent_id or parentId - The ID of the parent product
• is_parent or isParent - Set to true, yes, or 1 for parent products

Example CSV:

sku,name,brand,category,is_parent,parent_id
TSHIRT-CLASSIC,Classic T-Shirt,MyBrand,Apparel,true,
TSHIRT-RED-M,Classic T-Shirt - Red M,MyBrand,Apparel,false,TSHIRT-CLASSIC
TSHIRT-RED-L,Classic T-Shirt - Red L,MyBrand,Apparel,false,TSHIRT-CLASSIC
TSHIRT-BLUE-M,Classic T-Shirt - Blue M,MyBrand,Apparel,false,TSHIRT-CLASSIC

Important Notes:

• You can use either the parent product's ID or External ID in the parent_id field
• Parent products must be marked with is_parent: true
• The system will automatically resolve External IDs to product IDs during import
• Products cannot have both is_parent: true and a parent_id

Option 3: Update Existing Products via CSV

Use Update Products via CSV to modify parent-child relationships on products that already exist in your catalog. This is ideal for bulk re-linking variants or marking many products as parents at once.

How to access:

1. Go to Products
2. Click Bulk Actions → Update Products via CSV
3. Upload your CSV and click Update Products

How it works:

• Products are matched by internal id/product_id or current external_id
• Existing SKU-only files remain supported as a legacy fallback
• Only columns present in the CSV are updated — omitted columns are left unchanged
• Rows with missing products, invalid relationships, or conflicting identifiers are skipped and downloaded with a reason

Example CSV — mark as parent and link variants:

external_id,is_parent,parent_id
TSHIRT-CLASSIC-EXT-ID,true,
TSHIRT-RED-M-EXT-ID,false,TSHIRT-CLASSIC-EXT-ID
TSHIRT-RED-L-EXT-ID,false,TSHIRT-CLASSIC-EXT-ID
TSHIRT-BLUE-M-EXT-ID,false,TSHIRT-CLASSIC-EXT-ID

Example CSV — clear parent link (unlink a variant):

external_id,parent_id,is_parent
TSHIRT-RED-M-EXT-ID,,false

Supported columns for update CSV:

For general CSV update examples, identifier precedence, and skipped-row behavior, see Updating Existing Products from CSV.

Option 4: Via API

Create Parent Product:

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/products/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "TSHIRT-CLASSIC",
    "name": "Classic T-Shirt",
    "brand": "MyBrand",
    "isParent": true
  }'

Create Variant Product:

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/products/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "TSHIRT-RED-M",
    "name": "Classic T-Shirt - Red, Medium",
    "brand": "MyBrand",
    "parentId": "prod_parent123"
  }'

Viewing and Filtering

Product Type Filter

Use the Type filter dropdown on the Products page to view:

• All Products: Show all products (default)
• Parent Products Only: Show only parent products
• Non-Parent Products Only: Show only child/variant and standalone products

Product Type Badges

Products display type badges for easy identification:

• Purple "Parent" badge: Product is a parent (has variants)
• Blue "Variant" badge: Product is a child/variant (has a parent)
• No badge: Standalone product (neither parent nor child)

Parent Product Links

In product tables, child products show a clickable link to their parent product in the "Parent Product" column. Click the link to navigate to the parent product details.

Parent Product Enrichment

Parent products use a special enrichment process that aggregates data from all child variants instead of searching the web.

How It Works

1. Select a parent product for enrichment
2. The system identifies all child products linked to the parent
3. Analyzes child product attributes across all variants
4. Applies aggregation strategies based on attribute types
5. Generates parent-level attributes automatically

Aggregation Strategies

1. Common/Shared Values

When all children share the same value, the parent uses that value.

Applies to: Brand, Manufacturer, Category, Material

Example:

• All variants have Brand: "MyBrand"
• Parent gets: Brand: "MyBrand"

2. Range Values (Numeric)

When children have different numeric values, the parent shows a range.

Format: [minimum] - [maximum] [unit]

Applies to: Price, Weight, Dimensions, Capacity

Example:

• Variant 1: Price $19.99
• Variant 2: Price $22.99
• Variant 3: Price $24.99
• Parent gets: Price: "$19.99 - $24.99"

3. Combined Values (Categorical)

When children have different categorical values, the parent lists all unique values.

Applies to: Colors, Sizes, Compatible Models

Example:

• Variant 1: Color "Red"
• Variant 2: Color "Blue"
• Variant 3: Color "Green"
• Parent gets: Colors: "Red, Blue, Green"

4. Summarized Values (Descriptive)

For text descriptions, the parent gets a comprehensive summary covering common features and variations.

Applies to: Description, Features, Specifications

Requirements

• Parent product must have at least one child product
• Child products should have enriched attributes for best results
• System will error if parent has no children

Credit Usage

Parent product enrichment:

• Does not use web search
• Consumes fewer credits than standard enrichment
• Only performs AI aggregation of child data
• Typically uses ~50% fewer credits than web-based enrichment

Running Parent Enrichment

Follow the same process as standard enrichment, but:

1. Filter for Parent Products Only
2. Select parent products to enrich
3. Choose your AI model
4. The system automatically uses parent enrichment for applicable products

Note: websearch and extractImages options are ignored for parent products. Include existing attributes applies to the parent's own values; child variant attributes are always used as the aggregation source.

Parent Product Validation

Parent products use a special validation process that compares parent attributes against aggregated data from child products.

How It Works

1. Select a parent product for validation
2. The system retrieves all child products
3. Aggregates expected values from child data
4. Compares parent attributes to aggregated child data
5. Provides validation results with confidence scores

Validation Rules

Common Values

• Valid if parent matches the value shared by all/most children
• Invalid if children share a value but parent differs

Example:

• All variants have Manufacturer: "ACME Corp"
• Parent has Manufacturer: "ACME Corp" → Valid
• Parent has Manufacturer: "Other Corp" → Invalid

Range Values

• Valid if parent range encompasses all child numeric values
• Invalid if range is incorrect or missing boundary values

Example:

• Variants: Weight 200g, 220g, 240g
• Parent: "200g - 240g" → Valid
• Parent: "200g - 230g" → Invalid (missing 240g)

Aggregated Values

• Valid if parent list contains all unique child values
• Invalid if parent is missing child values or has extra values

Example:

• Variants have colors: Red, Blue, Green
• Parent: "Red, Blue, Green" → Valid
• Parent: "Red, Blue" → Invalid (missing Green)
• Parent: "Red, Blue, Green, Yellow" → Invalid (has extra Yellow)

Descriptive Values

• Valid if parent text accurately reflects common features and variations
• Invalid if parent contradicts child data or misses key information

Confidence Scores

• 90-100%: All children confirm parent value (perfect match)
• 75-89%: Most children (>80%) confirm parent value
• 60-74%: Majority (>60%) confirm, or parent shows valid aggregation
• 40-59%: Partial match, parent value is reasonable but not optimal
• 20-39%: Weak match, parent value is questionable
• 0-19%: Parent value contradicts child data

Requirements

• Parent product must have at least one child product
• Child products should have enriched attributes
• Parent product should have existing attributes to validate

Credit Usage

Parent product validation:

• Does not use web search
• Consumes fewer credits than standard validation
• Validates against child data only
• Typically uses ~50% fewer credits than web-based validation

Running Parent Validation

Follow the same process as standard validation, but:

1. Filter for Parent Products Only
2. Select parent products to validate
3. Choose your AI model
4. The system automatically uses parent validation for applicable products

Note: extractImages option is ignored for parent products.

Best Practices

Naming Conventions

Use consistent naming to easily identify relationships:

Parent Products:

• Keep names generic and family-level
• Examples: "Classic T-Shirt", "Wireless Mouse Pro"

Child Products:

• Include variant details in the name
• Examples: "Classic T-Shirt - Red, Size M", "Wireless Mouse Pro - Black"

SKU Structure

Use hierarchical SKUs for easy identification:

Parent Product:

• SKU: TSHIRT-CLASSIC

Child Products:

• SKU: TSHIRT-CLASSIC-RED-M
• SKU: TSHIRT-CLASSIC-RED-L
• SKU: TSHIRT-CLASSIC-BLUE-M

Enrichment Workflow

1. Enrich child products first with web search to get accurate variant data
2. Then enrich parent products to aggregate child data
3. Validate parent products to ensure aggregation accuracy
4. Re-enrich parents if child data changes significantly

Catalog Organization

• Create separate catalogs for parent and variant products if needed
• Use the Type filter to work on parent or variant products independently
• Consider organizing by product families using catalogs

Common Use Cases

E-commerce Variants

Scenario: Managing apparel with multiple sizes and colors

Setup:

• Parent: "Men's Classic Polo Shirt"
• Children: Combinations of 3 colors × 5 sizes = 15 variants

Benefits:

• Display parent on category pages
• Show all variants on product detail page
• Aggregate pricing and availability
• Enrich parent with all available options

Product Configurations

Scenario: Electronics with different specifications

Setup:

• Parent: "Laptop Model Pro"
• Children: Different RAM/storage combinations (8GB/256GB, 16GB/512GB, etc.)

Benefits:

• Present all configurations under one product family
• Aggregate technical specs into parent
• Compare variants side-by-side
• Validate parent specs match variant offerings

Product Bundles

Scenario: Products sold in different bundle sizes

Setup:

• Parent: "Premium Supplement Pack"
• Children: 30-day supply, 60-day supply, 90-day supply

Benefits:

• Manage pricing tiers
• Aggregate common ingredients and benefits
• Validate parent accurately represents all bundle options

Troubleshooting

Cannot Enrich Parent Product

Problem: "Parent product has no child products. Cannot enrich without children."

Solution:

• Ensure at least one child product is linked to the parent
• Verify child products have parentId set to the parent's ID
• Enrich child products first to have data to aggregate

Cannot Link Parent and Child

Problem: Error when setting both isParent: true and parentId

Solution:

• A product cannot be both a parent and a child
• Remove one of the two fields
• Create separate products if you need nested hierarchies

Parent Link Not Showing

Problem: Parent product link not visible in tables

Solution:

• Verify the child product has a valid parentId
• Check that the parent product exists in your organization
• Refresh the page or clear filters

Validation Scores Are Low

Problem: Parent validation showing low confidence

Solution:

• Enrich child products first to have complete data
• Review child product attributes for consistency
• Manually update parent attributes to match aggregated child data
• Re-validate after updating

API Examples

Check if Product is Parent

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/products/prod_123/get \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response includes isParent and parentId fields:

{
  "success": true,
  "data": {
    "id": "prod_123",
    "sku": "TSHIRT-RED-M",
    "name": "Classic T-Shirt - Red, Medium",
    "isParent": false,
    "parentId": "prod_parent_abc"
  }
}

List All Parent Products

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/products/get \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "limit": 50,
    "parentFilter": "parent"
  }'

Update Parent Relationship

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/products/prod_123/update \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "TSHIRT-RED-M",
    "name": "Classic T-Shirt - Red, Medium",
    "parentId": "prod_parent_abc"
  }'

Next Steps

• Product Enrichment - Learn about standard enrichment
• Product Validation - Understand validation workflows
• Catalog Management - Organize product families
• API Reference - Programmatic product management