Editing Products

This guide covers updating existing products and variants through Trustana's API. Product editing supports partial updates, allowing you to modify only specific attributes without affecting unchanged data.

Overview

Product editing in Trustana follows a partial update pattern where you only need to specify the supplierSku to identify the product and the specific attributes you want to modify. All other attributes remain unchanged.

Integration Pre-requisites

Before editing products, ensure you understand the same requirements as product creation:

Attribute Key Mapping:

All attribute keys used in edit operations must exist in your account configuration
New attributes cannot be created via API - coordinate with Portal users to add new attributes
Use POST /v1/attributes/search to discover available attribute keys for your account
Only include attributes you want to modify in the update payload

Product Identification:

Products are identified by their supplierSku (your internal identifier)
The product must exist in your Trustana account before editing
Variants require separate edit operations from their parent products

Media Considerations:

Media updates follow the same upload-first pattern as creation
Use the Uploading Media guide to get image IDs before including in edit operations
Media edits replace the entire media array (not append)

See Creating Products for attribute setup and Configuration Flow for attribute configuration.

Partial Update Pattern

Trustana's edit API follows a PATCH-style partial update pattern, allowing efficient modifications without large payloads.

Edit Structure

{
  "product": {
    "supplierSku": "PRODUCT-IDENTIFIER",
    "attributes": [
      {
        "key": "attribute-to-change",
        "value": "new-value"
      }
    ]
  }
}

Key Principles:

Minimal Payload: Only include attributes you want to change
Unchanged Attributes: Attributes not included remain unchanged
Replace Behavior: Included attributes completely replace existing values
Array Attributes: Media and other arrays are completely replaced, not merged

Simple Product Editing

Scenario: Update Product Name and Price

Updating basic information for an existing iPhone product:

curl -X PATCH 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 - Updated Edition"
        },
        {
          "key": "price",
          "value": "1299.99"
        }
      ]
    }
  }'

Success Response Example

{
  "errorCode": 0,
  "data": {
    "updatedAt": 1759845899157,
    "attributeSummary": {
      "enrichableTotal": 48,
      "enrichableCompleted": 3,
      "enrichableCompletionRate": 6.25
    },
    "attributes": [
      {
        "key": "name",
        "value": "Apple iPhone 15 Pro Max - Updated Edition"
      },
      {
        "key": "brand",
        "value": "Apple"
      },
      {
        "key": "price",
        "value": "1299.99"
      },
      {
        "key": "productModel",
        "value": "A3108"
      },
      {
        "key": "media",
        "value": [
          "IM03779818",
          "IM03779819",
          "IM03779820"
        ]
      }
    ],
    "skuId": "TR08214816",
    "supplierSku": "INTERNAL-APPLE-15PM-001",
    "updatedAt": 1759845899157,
    "id": "68e51e0bf52b9762b67b7de9"
  }
}

Response Notes:

updatedAt: Timestamp shows when the edit was completed
attributes: Returns all current attributes (both changed and unchanged)
attributeSummary: May show updated enrichment completion rates
Only the specified attributes (name and price) were modified

Media Gallery Updates

Adding/Updating Product Images

To update a product's media gallery, first use the Uploading Media guide to upload new images, then update the product:

# 1. Prepare upload for new images (if needed)
curl -X POST https://api.trustana.com/v1/upload/prepare \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "new-product-image.jpg",
    "skuIds": ["TR08214816"]
  }'

# Response: {"fileId": "IM03779827", "uploadUrl": "https://..."}

# 2. Update product with new media array
curl -X PATCH 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": "media",
          "value": [
            "IM03779818",
            "IM03779819", 
            "IM03779820",
            "IM03779827"
          ]
        }
      ]
    }
  }'

Media Array Behavior

Media Replacement

The media attribute completely replaces the existing image array. To add an image, include all existing image IDs plus the new ones. To remove an image, exclude it from the array.

Adding Image: Include all existing + new image IDs
Removing Image: Include only the image IDs you want to keep
Reordering Images: Change the order of image IDs in the array

Advanced Product Editing

Scenario: Medical Device Specification Update

Updating technical specifications for a medical device while leaving other attributes unchanged:

curl -X PATCH https://api.trustana.com/v1/products/{{skuId}} \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product": {
      "supplierSku": "INTERNAL-MEDSCAN-001",
      "attributes": [
        {
          "key": "power_requirements",
          "value": "110-240V AC, 50/60Hz"
        },
        {
          "key": "dimensions",
          "value": "48 x 32 x 18 cm"
        },
        {
          "key": "certification",
          "value": "ISO 13485, FDA Class II"
        }
      ]
    }
  }'

This update modifies only the technical specifications while preserving:

Product name and brand
Category assignment
Product model and other enrichment-related fields
Media gallery
All other custom attributes

Variant Editing

Variants follow the same partial update pattern but operate independently from their parent products.

Updating Variant-Specific Attributes

curl -X PATCH https://api.trustana.com/v1/variants/{{skuId}} \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product": {
      "supplierSku": "DRESS-EVENING-001-BLUE-M",
      "attributes": [
        {
          "key": "price",
          "value": "179.99"
        },
        {
          "key": "inventory",
          "value": "25"
        }
      ]
    }
  }'

Variant Editing Notes:

Variants inherit SPU data from parents (cannot edit inherited attributes directly)
Only variant-specific attributes can be modified on variants
To change inherited data, edit the parent product
Media inheritance can be broken by adding variant-specific media

Multiple Product Updates

For updating multiple products, iterate through individual PATCH operations:

Application-Level Iteration

// Example: JavaScript iteration for multiple product updates
const productUpdates = [
  {
    skuId: "TR08214816",
    supplierSku: "INTERNAL-APPLE-15PM-001",
    updates: [
      { key: "price", value: "1199.99" }
    ]
  },
  {
    skuId: "TR08295360",
    supplierSku: "INTERNAL-MEDSCAN-001", 
    updates: [
      { key: "certification", value: "ISO 13485, FDA Class II, CE Mark" }
    ]
  }
];

for (const update of productUpdates) {
  const response = await fetch(`https://api.trustana.com/v1/products/${update.skuId}`, {
    method: 'PATCH',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      product: {
        supplierSku: update.supplierSku,
        attributes: update.updates
      }
    })
  });
  
  // Handle response and potential errors
  const result = await response.json();
  console.log(`Updated product: ${result.data.supplierSku}`);
}

Validation & Error Handling

Common Edit Errors

Product Not Found:

{
  "errorCode": 404,
  "error": {
    "code": "product_not_found",
    "message": "Product with supplierSku 'INTERNAL-PRODUCT-001' not found",
    "suggestion": "Verify the supplierSku exists in your account"
  }
}

Invalid Attribute Key:

{
  "errorCode": 400,
  "error": {
    "code": "invalid_attribute_key",
    "message": "Attribute 'new_custom_field' does not exist in account configuration",
    "attribute_key": "new_custom_field",
    "suggestion": "Contact Portal users to create new attributes before using in API"
  }
}

Read-Only Attribute:

{
  "errorCode": 400,
  "error": {
    "code": "read_only_attribute",
    "message": "Attribute 'skuId' is system-generated and cannot be modified",
    "attribute_key": "skuId",
    "suggestion": "Remove read-only attributes from update payload"
  }
}

Pre-Edit Validation

Verify Product 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": "INTERNAL-PRODUCT-001"}}'

Check Editable Attributes:

curl -X POST https://api.trustana.com/v1/attributes/search \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Enrichment Impact

How Edits Affect Enrichment

Enrichment Preservation:

Editing non-enriched attributes preserves existing enriched content
Editing enriched attributes may trigger enrichment refresh (Portal-controlled)
System tracks which attributes have been user-modified vs AI-generated

Best Practices:

Avoid editing AI-enriched attributes unless intentional override is needed
Check blame field in responses to understand content source
Coordinate with Portal users on enrichment refresh policies

Blame Tracking After Edits

{
  "attributes": [
    {
      "key": "name",
      "value": "Apple iPhone 15 Pro Max - Updated Edition",
    },
    {
      "key": "smartShortDesp",
      "value": "Experience the ultimate smartphone with advanced camera system...",
      "blame": "ENRICHMENT_APPROVED"
    }
  ]
}

Blame Values:

ENRICHMENT: AI-generated content awaiting review
ENRICHMENT_APPROVED: User-approved AI content
ENRICHMENT_REJECTED: User-rejected AI content
No Blame. Manually edited via API or Portal

Performance & Best Practices

Efficient Update Strategies

▶️ Minimal Payloads

Only include attributes that need to change
Avoid sending unchanged values
Use specific attribute updates rather than full product replacement

▶️ Batch Processing

Group related updates by product type or category
Process similar products together for consistency
Implement proper error handling for partial failures

▶️ Validation First

Verify products exist before attempting updates
Validate attribute keys against account configuration
Check for read-only or system-managed attributes

Integration Patterns

ERP Sync Pattern:

# 1. Fetch products that need updates from ERP
# 2. For each product needing updates:
#    a. Validate product exists in Trustana
#    b. Map ERP fields to Trustana attributes  
#    c. PATCH only changed attributes
#    d. Handle errors and retry logic
# 3. Update ERP with sync status

Inventory Update Pattern:

# Regular inventory sync
for sku in inventory_updates:
    PATCH /v1/products → Update inventory levels
    # Keep other attributes unchanged

Monitoring & Analytics

Key Metrics to Track

Update Success Rate: Percentage of successful PATCH operations
Attribute Change Frequency: Which attributes are updated most often
Error Patterns: Common validation failures and resolution times
Payload Efficiency: Average attributes per update call

Common Performance Bottlenecks

Sending unnecessary unchanged attributes in payloads
Missing pre-validation causing failed API calls
Large media arrays when only minor changes needed
Concurrent edits to same products causing conflicts

Next Steps

After mastering product editing, explore related workflows:

🔍 Product Management

Creating Products: Understand initial product creation
Creating Variants: Learn variant-specific editing patterns
Fetching Products: Retrieve current product data before editing

📚 Understanding Changes

Enrichment Service: How edits interact with AI enrichment
Configuration Flow: Understand which attributes can be edited

🚀 Optimize Operations

Implement efficient partial update patterns
Build robust error handling and retry logic
Monitor edit success rates and performance metrics

📖 Reference

API Reference: Interactive documentation for product update endpoints

Editing Variants

Product variants use a specialized endpoint and have limited editable attributes compared to parent products. Variants can only be edited for variant-specific attributes like inventory, pricing, and color.

Variant Editing Endpoint

Use the dedicated variants endpoint with the variant's skuId:

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

Variant-Specific Attributes

Only attributes with variant-specific settings can be edited on variants, or are eligible for enrichment. Some examples of variant-specific attributes:

inventory: Stock levels for this specific variant
price: Variant-specific pricing (if different from parent)
color: Color specification for this variant
size: Size specification for this variant

Users can create custom attributes applicable to variants with the variant-specific setting on attribute config.

Inherited Attributes

Variants inherit most data from their parent product, including any custom attributes without a variant-specific setting.

name: Inherited from parent SPU
brand: Inherited from parent SPU
productCategory: Inherited from parent SPU
description: Inherited from parent SPU
media: Inherited from parent SPU. However, inheritance can be broken if they need to have different media galleries
productModel: Inherited from parent SPU

Parent Product Changes

To modify inherited attributes, edit the parent product instead. Changes to the parent will automatically reflect in all variants unless variant-specific overrides exist.

Success Response Example

{
  "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"
  }
}

Ready to start editing products? Begin with simple attribute updates on test products before implementing larger-scale edit operations.

Overview​

Partial Update Pattern​

Edit Structure​

Simple Product Editing​

Scenario: Update Product Name and Price​

Success Response Example​

Media Gallery Updates​

Adding/Updating Product Images​

Media Array Behavior​

Advanced Product Editing​

Scenario: Medical Device Specification Update​

Variant Editing​

Updating Variant-Specific Attributes​

Multiple Product Updates​

Application-Level Iteration​

Validation & Error Handling​

Common Edit Errors​

Pre-Edit Validation​

Enrichment Impact​

How Edits Affect Enrichment​

Blame Tracking After Edits​

Performance & Best Practices​

Efficient Update Strategies​

Integration Patterns​

Monitoring & Analytics​

Key Metrics to Track​

Common Performance Bottlenecks​

Next Steps​

🔍 Product Management​

📚 Understanding Changes​

🚀 Optimize Operations​

📖 Reference​

Editing Variants​

Variant Editing Endpoint​

Variant-Specific Attributes​

Inherited Attributes​

Success Response Example​

Overview

Partial Update Pattern

Edit Structure

Simple Product Editing

Scenario: Update Product Name and Price

Success Response Example

Media Gallery Updates

Adding/Updating Product Images

Media Array Behavior

Advanced Product Editing

Scenario: Medical Device Specification Update

Variant Editing

Updating Variant-Specific Attributes

Multiple Product Updates

Application-Level Iteration

Validation & Error Handling

Common Edit Errors

Pre-Edit Validation

Enrichment Impact

How Edits Affect Enrichment

Blame Tracking After Edits

Performance & Best Practices

Efficient Update Strategies

Integration Patterns

Monitoring & Analytics

Key Metrics to Track

Common Performance Bottlenecks

Next Steps

🔍 Product Management

📚 Understanding Changes

🚀 Optimize Operations

📖 Reference

Editing Variants

Variant Editing Endpoint

Variant-Specific Attributes

Inherited Attributes

Success Response Example