Skip to main content

Creating Product Variants

This guide covers creating product variants - variations of a parent product such as different sizes, colors, or styles. Variants inherit SPU (Standard Product Unit) level data from their parent and contain only SKU-specific attributes. Before creating variants, you must have a parent product already created in the system.

Prerequisites & Dependencies​

Creating variants requires understanding the parent-child relationship and inheritance model that drives Trustana's variant system.

Parent Product Dependency

Variants cannot exist without a parent product. Attempting to create a variant for a non-existent parent will result in an API error. The parent product must be successfully created and available in your account before variant creation.

Integration Pre-requisites

Before creating variants, ensure you have completed the same setup steps as product creation:

Attribute Key Mapping:

  • Map variant-specific attribute keys from your account configuration
  • Only use attribute keys that exist and are marked as "variant-specific"
  • Use POST /v1/attributes/search with filter.linkedCategories=[categoryId] and filter.option.variantable=true to discover variant attributes

Parent Product Validation:

  • Verify parent product exists using the parent's supplierSku
  • Confirm parent has proper SPU-level data (name, brand, productCategory)
  • Understand which attributes will be inherited vs variant-specific

Media Considerations:

  • Images are inherited from parent by default
  • Media inheritance can be broken for variant-specific galleries (not recommended unless necessary)
  • If breaking media inheritance, use the Uploading Media guide to upload variant-specific images first

See Creating Products for parent product creation and Configuration Flow for attribute configuration.

SPU vs SKU Inheritance Model​

Understanding the inheritance model is crucial for successful variant implementation and proper data organization.

SPU Level Data (Inherited from Parent)​

Automatically Inherited Attributes:

  • name: Product title and base naming
  • brand: Brand identifier
  • productCategory: Category classification
  • productModel: Manufacturer identifier for enrichment
  • media: Image gallery (unless inheritance is broken)
  • All non-variant-specific attributes: Descriptions, features, specifications

Inheritance Benefits:

  • Consistent branding across all variants
  • Single source of truth for shared product data
  • Efficient enrichment at parent level flows to all variants
  • Simplified management of common attributes

SKU Level Data (Variant-Specific)​

Common Variant Attributes:

  • color: Color variations ("Blue", "Red", "Black")
  • size: Size variations ("Small", "Medium", "Large", "8", "9", "10")
  • style: Style differences ("Classic", "Modern", "Vintage")
  • price: Variant-specific pricing
  • weight: May vary by size or material
  • inventory: Stock levels per variant

Inheritance Management​

Default Behavior:

Media Inheritance Flexibility:

  • Default: All variants inherit parent's media gallery
  • Override: Individual variants can have unique media galleries
  • Portal Management: Inheritance can be restored from Parent Detail page or variant page
  • Recommendation: Only break media inheritance when variants require significantly different images
Inheritance Breaking Guidelines

While the system supports breaking inheritance for any attribute, it is strongly recommended to only break media inheritance when necessary. Breaking inheritance of core SPU attributes (name, brand, productCategory) can complicate management and enrichment workflows.

Safe to Break: Media galleries for variant-specific images Not Recommended: Core product attributes, descriptions, brand information Recovery: All inheritance breaking can be reverted through the Portal UI

Portal Integration & Management​

Variants are managed and displayed through the Trustana Portal interface, providing business users with comprehensive variant oversight.

Parent Detail Page - Variants Section​

The Parent Detail page includes a dedicated Variants Section that displays:

  • Variant List Table: All variants belonging to the parent
  • Variant-Specific Attributes: Columns showing attributes that vary between variants (color, size, price, etc.)
  • Status Indicators: Stock levels, enrichment status, media inheritance status
  • Management Actions: Edit, delete, bulk operations

Variant Limits & Scale​

Fashion Use Case Optimization:

  • Maximum Variants: Up to 200 variants per parent product
  • Typical Fashion Range: Covers extensive size and color combinations
  • Example: 10 colors × 20 sizes = 200 variants for comprehensive fashion catalog
  • Performance: Optimized for large variant families common in apparel

Single Variant Creation Workflow​

Scenario: Fashion retailer creating a blue color variant for an existing evening dress parent product.

Example API Call​

Creating a blue, medium-sized variant of an evening dress:

curl -X POST https://api.trustana.com/v1/variants \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parentSupplierSku": "DRESS-EVENING-001",
    "supplierSku": "DRESS-EVENING-001-BLUE-M",
    "attributes": [
      {
        "key": "color",
        "value": "Blue"
      },
      {
        "key": "size", 
        "value": "Medium"
      },
      {
        "key": "price",
        "value": "189.99"
      }
    ]
  }'

Success Response Example​

{
  "errorCode": 0,
  "data": {
    "createdAt": 1759845899057,
    "parentSupplierSku": "DRESS-EVENING-001",
    "attributeSummary": {
      "enrichableTotal": 12,
      "enrichableCompleted": 0,
      "enrichableCompletionRate": 0
    },
    "attributes": [
      {
        "key": "color",
        "value": "Blue"
      },
      {
        "key": "size",
        "value": "Medium" 
      },
      {
        "key": "price",
        "value": "189.99"
      }
    ],
    "inheritedAttributes": [
      {
        "key": "name",
        "value": "Evening Dress Collection"
      },
      {
        "key": "brand",
        "value": "Designer Co"
      },
      {
        "key": "productCategory",
        "value": "2156"
      },
      {
        "key": "productModel",
        "value": "ED-2024-CLASSIC"
      }
    ],
    "skuId": "TR08214817",
    "supplierSku": "DRESS-EVENING-001-BLUE-M",
    "updatedAt": 1759845899057,
    "id": "68e51e0bf52b9762b67b7dea"
  }
}

Response Fields Explained:

  • parentSupplierSku: Links variant to parent product
  • attributes: Only variant-specific attributes submitted
  • inheritedAttributes: SPU-level data automatically inherited from parent
  • attributeSummary: Shows variant-specific enrichable attributes (12 available for this variant)
  • skuId: Trustana-generated unique identifier for the variant

Alternative Response Format with Inherited Flag​

Some responses may show all attributes in a single array with an inherited flag to indicate data source:

{
  "errorCode": 0,
  "data": {
    "updatedAt": 1759845899157,
    "attributes": [
      {
        "key": "name",
        "value": "Evening Dress Collection",
        "inherited": true
      },
      {
        "key": "inventory",
        "value": "15"
      },
      {
        "key": "price",
        "value": "189.99"
      },
      {
        "key": "color",
        "value": "Royal Blue",
        "blame": "ENRICHMENT"
      }
    ],
    "skuId": "TR08295361",
    "supplierSku": "DRESS-EVENING-001-BLUE-M",
    "parentSkuId": "TR08295360"
  }
}

Inheritance Indicators:

  • inherited: true: Attribute inherited from parent product
  • No inherited field: Variant-specific attribute
  • blame: Shows content source for AI-enriched attributes

Creating Multiple Variants​

For fashion catalogs with multiple size and color combinations, developers need to iterate through individual variant creation calls:

Fashion Use Case: Multiple Color/Size Combinations​

# Create variants individually for each color/size combination
# Blue variants
curl -X POST https://api.trustana.com/v1/variants \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parentSupplierSku": "DRESS-EVENING-001",
    "supplierSku": "DRESS-EVENING-001-BLUE-S",
    "attributes": [
      { "key": "color", "value": "Blue" },
      { "key": "size", "value": "Small" },
      { "key": "price", "value": "189.99" }
    ]
  }'

curl -X POST https://api.trustana.com/v1/variants \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parentSupplierSku": "DRESS-EVENING-001",
    "supplierSku": "DRESS-EVENING-001-BLUE-M",
    "attributes": [
      { "key": "color", "value": "Blue" },
      { "key": "size", "value": "Medium" },
      { "key": "price", "value": "189.99" }
    ]
  }'

# Red variants  
curl -X POST https://api.trustana.com/v1/variants \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parentSupplierSku": "DRESS-EVENING-001",
    "supplierSku": "DRESS-EVENING-001-RED-S",
    "attributes": [
      { "key": "color", "value": "Red" },
      { "key": "size", "value": "Small" },
      { "key": "price", "value": "199.99" }
    ]
  }'

Multiple Variant Creation Integration​

Iteration Strategies​

Application-Level Iteration:

// Example: JavaScript iteration for variant creation
const variants = [
  { color: "Blue", size: "Small", price: "189.99" },
  { color: "Blue", size: "Medium", price: "189.99" },
  { color: "Red", size: "Small", price: "199.99" },
  { color: "Red", size: "Medium", price: "199.99" }
];

for (const variant of variants) {
  const response = await fetch('https://api.trustana.com/v1/variants', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      parentSupplierSku: "DRESS-EVENING-001",
      supplierSku: `DRESS-EVENING-001-${variant.color.toUpperCase()}-${variant.size.charAt(0)}`,
      attributes: [
        { key: "color", value: variant.color },
        { key: "size", value: variant.size },
        { key: "price", value: variant.price }
      ]
    })
  });
  
  // Handle response and potential errors
  const result = await response.json();
  console.log(`Created variant: ${result.data.supplierSku}`);
}

Performance Considerations​

  • Individual API Calls: Each variant requires a separate API call
  • Rate Limiting: Be mindful of API rate limits when creating many variants
  • Error Handling: Implement retry logic for failed variant creation attempts
  • Payload Size: Keep individual variant payloads manageable (avoid large attribute sets)
  • Parallel Processing: Consider concurrent requests for different parents but sequential for same parent

Media Inheritance & Variant-Specific Images​

Understanding media inheritance helps optimize image management across variant families.

Default Media Inheritance​

# Parent product with media
{
  "supplierSku": "DRESS-EVENING-001",
  "attributes": [
    {
      "key": "media",
      "value": ["IM03779820", "IM03779821", "IM03779822"]
    }
  ]
}

# Variant automatically inherits parent media
{
  "parentSupplierSku": "DRESS-EVENING-001",
  "attributes": [
    { "key": "color", "value": "Blue" }
  ]
  // No media attribute needed - inherits parent's images
}

Breaking Media Inheritance​

For variants requiring unique images (e.g., color-specific photography):

# Variant with specific media (breaks inheritance)
{
  "parentSupplierSku": "DRESS-EVENING-001", 
  "attributes": [
    {
      "key": "color",
      "value": "Blue"
    },
    {
      "key": "media",
      "value": ["IM03779825", "IM03779826"]
    }
  ]
}

When to Break Media Inheritance:

  • Color Variants: Different color requires color-accurate images
  • Style Variations: Significant style differences need unique photography
  • Size Specifics: Size-related fit or appearance changes

Portal Recovery:

  • Navigate to Parent Detail page → Variants Section
  • Select variant → Media Settings → "Restore Parent Inheritance"
  • Or from individual variant page → Media Gallery → "Inherit from Parent"

Validation & Error Handling​

Common Validation Errors​

Missing Parent Product:

{
  "errorCode": 404,
  "error": {
    "code": "parent_not_found",
    "message": "Parent product with supplierSku 'DRESS-EVENING-001' not found",
    "suggestion": "Ensure parent product exists before creating variants"
  }
}

Invalid Variant Attributes:

{
  "errorCode": 400,
  "error": {
    "code": "invalid_variant_attribute",
    "message": "Attribute 'brand' is not configured as variant-specific",
    "attribute_key": "brand",
    "suggestion": "Use only variant-specific attributes. Check configuration."
  }
}

Variant Limit Exceeded:

{
  "errorCode": 400,
  "error": {
    "code": "variant_limit_exceeded",
    "message": "Parent product already has 200 variants (maximum reached)",
    "current_count": 200,
    "suggestion": "Consider creating additional parent products for more variants"
  }
}

Pre-Creation Validation​

Verify Parent Exists:

curl -X POST https://api.trustana.com/v1/products/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filter": {"supplierSku": "DRESS-EVENING-001"}}'

Check Variant Attributes:

curl -X POST https://api.trustana.com/v1/attributes/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "linkedCategories": ["2156"],
      "categoryScopes": ["DIRECT", "INHERITED", "GLOBAL"],
      "option.variantable": true
    },
    "pagination": {
      "limit": 100,
      "offset": 0
    }
  }'

Best Practices & Performance​

Variant Design Strategy​

▶️ Optimal Variant Attributes

  • Choose attributes that meaningfully differentiate variants
  • Focus on customer-facing attributes (color, size, style)
  • Avoid technical attributes that don't affect purchasing decisions
  • Keep variant matrices manageable (aim for <100 variants typically)

▶️ Parent Product Planning

  • Design parents with rich SPU data for maximum inheritance benefit
  • Include comprehensive productModel for enrichment success
  • Set up proper category assignment for variant attribute availability
  • Plan media gallery for broad variant applicability

Monitoring & Success Metrics​

Key Performance Indicators:

  • Variant Creation Rate: Variants created per API call/minute
  • Inheritance Success: Percentage of variants properly inheriting SPU data
  • Error Rates: Failed variant creation attempts and common causes
  • Parent-Variant Ratios: Average variants per parent (fashion target: 10-50)

Next Steps​

After mastering variant creation, explore related workflows:

Product Management​

Understanding the Platform​

Scale Your Integration​

  • Implement efficient iteration patterns for large variant families
  • Design efficient parent-child data models
  • Monitor inheritance patterns and variant performance
  • Optimize rate limiting and error handling for fashion use cases

Reference​