Creating Products

This guide covers creating simple products and parent products through Trustana's API. If you need to create product variants (size, color, style variations of a parent product), see the Creating Variants guide instead.

Product Type Overview

Simple Products: Standalone products without variations (can contain both SPU and SKU level data)
Parent Products: Products that will have variants - ideally SPU level data only (some system exceptions allow SKU data where one variant serves as the 'group holder')
Variant Products: Child products where SPU data is inherited from parent, only SKU-specific data applicable for enrichment

Data Level Classifications

SPU (Standard Product Unit) Level Data:

• Shared across all variations: brand, productModel, category, descriptions, features
• Enriched at parent level and automatically inherited by variants
• Examples: "Nike Air Max 90" specifications apply to all sizes and colors

SKU (Stock Keeping Unit) Level Data:

• Specific to individual products/variants: size, color, price, inventory
• Enriched individually for each SKU or variant
• Examples: "Size 10, Red" pricing and availability

Variants Require Different Approach

Product variants have different creation workflows, API endpoints, and data structures. Use the Creating Variants guide for all variant-related operations.

Integration Pre-requisites

Before creating products, developers must complete essential setup steps to ensure successful API calls.

Attribute Key Mapping:

• Map existing attribute keys from your Trustana account to your application
• All attribute keys used in API calls must exist in your account configuration
• Adding a non-existent attribute key will result in an API error
• Use POST /v1/attributes/search to discover all available attribute keys
• Coordinate with Portal users to understand custom attribute definitions

Media Upload Workflow:

• Images must be uploaded first using the Uploading Media guide to obtain image IDs
• Use the returned image ID (format: "IM03779818") in the product creation body
• Image IDs are associated with the product's media gallery via the media attribute
• Up to 4 images can be included for AI vision processing

Trustana offers two distinct approaches to product creation, each designed for different integration scenarios and enrichment requirements. Understanding when to use each approach—and the critical role of SKU vs productModel—ensures successful enrichment and seamless system integration.

Basic Product Creation

Use Case: Quick catalog onboarding requiring AI-powered Image and Data Enrichment
Best For: Fashion, consumer goods, products needing web-sourced content enhancement
Complexity: Minimal attributes, maximum AI assistance

Advanced Product Creation

Use Case: Structured catalog with custom attributes and specific business requirements
Best For: Electronics, regulated products, complex specifications
Complexity: Configuration-driven attributes, selective enrichment targeting

Critical Fields for Enrichment Success

SKU: Internal Tracking Identifier

• Purpose: Internal system tracking and integration
• Scope: Your warehouse, inventory, ERP systems
• Example: "INTERNAL-ECO-TEE-001", "WH-SECTOR-A-12345"
• Usage: Required for all products, ensures uniqueness in your catalog

productModel: External Enrichment Key

• Purpose: AI-powered enrichment from web sources and manufacturer data
• Scope: Industry-standard, globally recognizable identifiers
• Critical: Essential for both Image and Data enrichment success
• Sources: Manufacturer catalogs, brand websites, product databases

Enrichment Success Depends on productModel

The quality and success rate of AI enrichment directly correlates with using proper manufacturer-provided identifiers in the productModel field. Internal SKUs typically yield poor enrichment results.

productModel Examples by Industry

Product Type	Good productModel	Poor productModel	Enrichment Impact
Electronics	"WH-1000XM5"	"HEADPHONES-001"	High vs No match
Fashion	"Air Max 90"	"NIKE-SHOE-42"	Rich content vs Basic
Appliances	"KitchenAid 5K45SS"	"MIXER-SILVER"	Specs found vs Manual entry
Auto Parts	"NGK BKR6E"	"SPARK-PLUG-6"	Cross-reference vs Unknown

Identifier Priority for productModel

1. Manufacturer Model Numbers - Official brand identifiers
2. GTIN/UPC Codes - Universal product identifiers
3. Manufacturer Part Numbers (MPN) - Technical part identifiers
4. Industry-Standard Codes - Sector-specific identifiers

Basic Product Creation Workflow

Scenario: Electronics retailer onboarding a new iPhone model that needs AI-powered image enhancement and data enrichment from web sources.

Key Success Factors

▶️ Required Fields

• name: "Apple iPhone 15 Pro Max"
• brand: "Apple"
• supplierSku: "INTERNAL-APPLE-15PM-001" (your internal identifier)

▶️ Enrichment Ready Fields

• productModel: "A3108" (manufacturer identifier for AI enrichment - optional but recommended)
• media: Up to 4 images for AI vision (array format: ["IM03779818", "IM03779819", "IM03779820"])
• productCategory: Category ID if known beforehand (ensures right attributes get enriched)

▶️ Manual Enrichment Capabilities

• AI can find additional product images using "A3108" when triggered
• Generates SEO-optimized descriptions from web sources via Portal
• Extracts specifications and features through manual enrichment tasks
• Creates channel-specific content variations when requested

Example API Call

curl -X POST https://api.trustana.com/v1/products \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product": {
      "supplierSku": "INTERNAL-APPLE-15PM-001",
      "attributes": [
        {
          "key": "name",
          "value": "Apple iPhone 15 Pro Max"
        },
        {
          "key": "brand", 
          "value": "Apple"
        },
        {
          "key": "productModel",
          "value": "A3108"
        },
        {
          "key": "media",
          "value": [
            "IM03779818",
            "IM03779819", 
            "IM03779820"
          ]
        }
      ]
    }
  }'

Advanced Product Creation Workflow

Scenario: Electronics manufacturer adding a medical device with regulatory tracking identifier, certifications, and technical specifications that must be mapped to pre-configured custom attributes.

Configuration-First Approach

Prerequisite: Account Configuration

This workflow assumes your Trustana account has been configured with:

• Category tree including "Medical Devices" category
• Custom attributes like fda_tracking_id, certification, compliance_level
• Attribute mappings linking these attributes to the medical devices category
• Enrichment rules defining which attributes should be AI-enhanced

Key Integration Points

▶️ Category Discovery

GET /v1/taxonomies
# Returns complete category tree - search locally for "medical" in the response

▶️ Attribute Mapping

POST /v1/attributes/search
Content-Type: application/json

{
  "filter": {
    "linkedCategories": ["5192"],
    "categoryScopes": ["DIRECT", "INHERITED", "GLOBAL"]
  }
}
# Returns: fda_tracking_id, certification, productModel, etc.

▶️ Payload Construction

• productModel: "MedScan Pro X1" (manufacturer part number)
• Custom Tracking: "TRK-2024-MD-001" (regulatory identifier)
• Certifications: Pre-configured dropdown values
• Technical Specs: Structured attributes for enrichment

Example Advanced Product Payload

curl -X POST https://api.trustana.com/v1/products \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product": {
      "supplierSku": "INTERNAL-MEDSCAN-001",
      "attributes": [
        {
          "key": "name",
          "value": "MedScan Pro X1"
        },
        {
          "key": "brand",
          "value": "MedTech Solutions"
        },
        {
          "key": "productCategory",
          "value": "5192"
        },
        {
          "key": "productModel",
          "value": "MedScan Pro X1"
        },
        {
          "key": "media",
          "value": [
            "IM03779825",
            "IM03779826"
          ]
        },
        {
          "key": "fda_tracking_id",
          "value": "TRK-2024-MD-001"
        },
        {
          "key": "certification",
          "value": "ISO 13485"
        },
        {
          "key": "compliance_level",
          "value": "Class II"
        },
        {
          "key": "power_requirements",
          "value": "110-240V AC"
        },
        {
          "key": "dimensions",
          "value": "45 x 30 x 15 cm"
        }
      ]
    }
  }'

Success Response Example

{
  "errorCode": 0,
  "data": {
    "createdAt": 1759845899057,
    "attributeSummary": {
      "enrichableTotal": 48,
      "enrichableCompleted": 1,
      "enrichableCompletionRate": 2.083333333333333
    },
    "attributes": [
      {
        "key": "name",
        "value": "MedScan Pro X1"
      },
      {
        "key": "brand",
        "value": "MedTech Solutions"
      },
      {
        "key": "productCategory",
        "value": "5192"
      },
      {
        "key": "productModel",
        "value": "MedScan Pro X1"
      },
      {
        "key": "media",
        "value": [
          "IM03779825",
          "IM03779826"
        ]
      },
      {
        "key": "fda_tracking_id",
        "value": "TRK-2024-MD-001"
      },
      {
        "key": "certification",
        "value": "ISO 13485"
      },
      {
        "key": "compliance_level",
        "value": "Class II"
      },
      {
        "key": "power_requirements",
        "value": "110-240V AC"
      },
      {
        "key": "dimensions",
        "value": "45 x 30 x 15 cm"
      }
    ],
    "skuId": "TR08214816",
    "supplierSku": "INTERNAL-MEDSCAN-001",
    "updatedAt": 1759845899057,
    "id": "68e51e0bf52b9762b67b7de9"
  }
}

Response Fields Explained:

• errorCode: 0 indicates successful creation
• skuId: Trustana-generated unique identifier ("TR08214816")
• supplierSku: Your original internal identifier
• id: MongoDB document ID for the product record
• attributeSummary: Shows enrichment readiness (48 total enrichable attributes, 1 completed)
• attributes: All provided attributes returned with their key-value pairs
• createdAt/updatedAt: Unix timestamps for audit tracking

Developer Integration Strategy

Middleware Design Considerations

▶️ SKU Management

• Maintain internal SKU uniqueness across all systems
• Use SKU for inventory tracking, order management, fulfillment
• Never expose internal SKUs to customers or external systems

▶️ productModel Transformation

• Map internal part numbers to manufacturer identifiers
• Prioritize GTIN/UPC codes when available
• Use manufacturer catalogs as source of truth for productModel
• Implement validation to prevent internal codes in productModel field

▶️ Repeatable Sync Operations

• Design idempotent product creation (handle duplicates gracefully)
• Implement proper error handling for attribute validation failures
• Use batch operations for large catalog uploads
• Maintain audit trails for product creation and updates

Enrichment Success Strategies

📈 Maximize Match Rates

# Good: Uses manufacturer identifier
"productModel": "iPhone 15 Pro Max"

# Better: Uses specific model variant
"productModel": "iPhone 15 Pro Max 256GB"  

# Best: Uses technical identifier when available
"productModel": "A3108"  # Apple internal model number

📈 Industry-Specific Approaches

• Fashion: Use brand style names, not season codes
• Electronics: Prioritize MPN over marketing names
• Auto Parts: Use OEM part numbers, not aftermarket SKUs
• Books: Use ISBN, not internal catalog numbers

Common Implementation Patterns

ERP Integration Pattern

# Step 1: Transform ERP data to Trustana format
internal_sku = "ERP-12345"
manufacturer_code = get_manufacturer_part_number(internal_sku)
category_id = map_erp_category_to_trustana(erp_category)

# Step 2: Create product with proper identifiers
{
  "sku": internal_sku,
  "productModel": manufacturer_code,
  "category_id": category_id
}

PIM Integration Pattern

# Leverage existing PIM structure
pim_attributes = get_pim_attributes(product_id)
trustana_attributes = map_to_trustana_schema(pim_attributes)

# Ensure productModel is manufacturer-sourced
trustana_attributes["productModel"] = pim_attributes["manufacturer_mpn"] 

Validation and Error Prevention

Critical Validation Points

• SKU Uniqueness: Ensure no duplicate SKUs in your system
• productModel Format: Validate against manufacturer catalogs when possible
• Category Existence: Verify category IDs before product creation
• Attribute Schema: Match custom attributes to configured schema

Common Error Scenarios

{
  "error": {
    "code": "enrichment_failed",
    "message": "productModel not found in external sources",
    "details": {
      "productModel": "INTERNAL-SKU-12345",
      "suggestion": "Use manufacturer identifier instead of internal SKU"
    }
  }
}

Success Response Format

{
  "id": "prod_12345",
  "name": "Apple iPhone 15 Pro Max",
  "brand": "Apple", 
  "sku": "INTERNAL-APPLE-15PM-001",
  "status": "active",
  "enrichment_status": "ready",
  "attributes": {
    "productModel": "A3108"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "links": {
    "self": "/api/v1/products/prod_12345",
    "enrichment": "/api/v1/products/prod_12345/enrichment"
  }
}

Key Takeaways

Critical Success Factors

1. SKU: Use for internal tracking and system integration
2. productModel: Use manufacturer identifiers for enrichment success
3. Configuration: Set up categories and attributes before integration
4. Validation: Implement proper error handling for failed enrichment
5. Monitoring: Track enrichment success rates and optimize productModel values

Enrichment Impact Measurement

• Monitor match rates by productModel type
• Track enrichment quality scores
• Measure time-to-market improvements
• Analyze content performance across channels

Next Steps

For Product Variants:

• Create product variants using the Creating Variants guide

For Basic Implementation:

1. Start with Product Retrieval to understand existing data
2. Monitor Product Details for enrichment results

For Advanced Implementation:

1. Review Configuration Flow for attribute setup
2. Explore Editing Products for ongoing management

---

Ready to optimize your product creation workflow? Contact our technical team for middleware integration guidance and enrichment strategy consultation.