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
Clearing a Value: Set value to null to clear an attribute. Inherited attributes on variants cannot be cleared — skip these in your payload. Avoid clearing attributes values, always aim to replace the value instead.

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

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}`);
}

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

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.

Inherited Attributes Are Read-Only on Variants

When you retrieve a variant, attributes with "inherited": true are managed at the parent product level. Submitting updates to inherited attributes on a variant will have no effect. To change these values, PATCH the parent product — changes cascade to all variants automatically.

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.

System attributes — always variant-specific:

supplierSku: Your internal identifier for this variant — uniqueness is enforced by the API
productModel: Variant-level model identifier — uniqueness is not enforced but each variant is expected to have a distinct value

Custom attribute examples — variant-specific when configured as such in Portal:

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.

System attributes — always inherited from parent:

name: Product name
brand: Brand
productCategory: Category classification
media: Media gallery

Custom attributes are also inherited when they do not have the variant-specific setting configured in Portal.

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​

Multiple Product Updates​

Application-Level Iteration​

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​

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

Multiple Product Updates

Application-Level Iteration

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

Editing Variants

Variant Editing Endpoint

Variant-Specific Attributes

Inherited Attributes

Success Response Example