API Playground

Test the product update endpoint with your own data.

Authentication Required

You need to Login to test the API playground

Product Update Endpoint

Update product information in your inventory

POST

The update endpoint allows you to modify product information for a specific product in your inventory. You can identify the product using an EAN, ASIN, GTIN, MINSAN code or SKU.

You can update various product fields including name, descriptions, key features, SEO metadata, and category assignments.

Endpoint URL
POST https://api.commerceclarity.com/api/v1/products/update

Request Body

Parameter Type Required Description
code string Required Product identifier. Can be an EAN, ASIN, GTIN, MINSAN code or SKU
country string Required ISO country code (2 characters) for the specific market version
name string Optional Product name (max 255 characters)
short_description string Optional Brief product description (max 500 characters)
description string Optional Detailed product description (20-10,000 characters)
key_features array Optional Array of product key features (each max 255 characters)
category_id string Optional The category ID. This can be your custom category ID (if provided during the custom category import process) or the internal CommerceClarity ID. You can retrieve your custom category tree via API, see the 'Category tree' section for more details.
title_tag string Optional SEO title tag (max 255 characters)
meta_description string Optional SEO meta description (max 320 characters)
meta_keywords string Optional SEO meta keywords as comma-separated string (max 1,000 characters)
pictures array Optional Array of image URLs (each max 500 characters)
customer_code string Optional Custom customer code for the product
product_handle string Optional Product handle for URL generation and identification
grouped_specifications array Optional Product specifications organized by groups and categories
global_attr object Optional Global product attributes with custom values. Object where keys are attribute identifiers within the product, each containing attribute_id and value.
family_attr object Optional Product family attributes with specific values. Object where keys are attribute identifiers within the product, each containing attribute_id and value.

Attributes Structure

Both global_attr and family_attr follow the same structure. Each attribute is identified by a unique key (the attribute identifier within the product) and contains the following fields:

Important: Important: The object key (attribute identifier) is what the system uses to match and update attributes. Make sure to use the exact identifier present in your product data.
Field Type Required Description
Attribute Key string Required The attribute identifier within the product (used as object key). This is the normalized identifier that uniquely identifies this attribute in your product data.
attribute_id string|null Optional Optional custom identifier for the attribute. Can be null if not provided during attribute creation.
value mixed|null Optional The attribute value, formatted according to its type. Can be null if the attribute exists but has no value.
Structure Example

Here's how the structure works with actual attribute keys:

{
  "global_attr": {
    "color": {              // ← "color" is the attribute identifier (key)
      "attribute_id": "attr_color_global",
      "value": "Red"
    },
    "weight": {             // ← "weight" is the attribute identifier (key)
      "attribute_id": null,
      "value": {
        "value": 250,
        "unit": "g"
      }
    },
    "material": {           // ← "material" is the attribute identifier (key)
      "attribute_id": "attr_material",
      "value": null         // ← Value can be null
    }
  }
}

Attribute Types & Value Formats

Type Description Example
text Direct string value Example: "Red" or "Cotton fabric"
number Object with value and optional unit Example: {"value": 250, "unit": "ml"}
boolean Direct boolean value Example: true or false
single-select Object with one normalized value name containing value and value_id Example: {"red": {"value": "Red", "value_id": "color_red"}}
multi-select Object with multiple normalized value names, each containing value and value_id Example: {"cotton": {"value": "Cotton", "value_id": "mat_cotton"}, "polyester": {"value": "Polyester", "value_id": "mat_poly"}}

Complete Attributes Example

In the example below, keys like "color", "weight", "waterproof", "material", and "screen_size" are the attribute identifiers within the product. These are the unique identifiers used to match and update specific attributes.

JSON Example
{
  "global_attr": {
    "color": {
      "attribute_id": "attr_color_global",
      "value": "Red"
    },
    "weight": {
      "attribute_id": null,
      "value": {
        "value": 250,
        "unit": "g"
      }
    },
    "waterproof": {
      "attribute_id": "attr_waterproof",
      "value": true
    },
    "eco_friendly": {
      "attribute_id": "attr_eco",
      "value": null
    }
  },
  "family_attr": {
    "material": {
      "attribute_id": "attr_material_electronics",
      "value": {
        "plastic": {
          "value": "Plastic",
          "value_id": "mat_plastic"
        },
        "aluminum": {
          "value": "Aluminum",
          "value_id": "mat_aluminum"
        }
      }
    },
    "screen_size": {
      "attribute_id": null,
      "value": {
        "value": 6.5,
        "unit": "inches"
      }
    }
  }
}
Note: Note: Only include attributes you want to update. You must use the exact attribute identifier from your product data. The attribute_id field is optional and can be null. The value field can also be null if the attribute exists but has no value.
To get your attribute definitions, use the Attributes API endpoints documented in the Attributes section.

Response Statuses

Code Status Description
200 success Product updated successfully
404 error Product not found with the provided identifier
422 error Request validation failed
500 error Internal server error occurred during update

Response Examples

Success Response
{
  "message": "Product updated successfully"
}
Validation Error Response
{
  "status": "error",
  "errors": [
    "The product code is required.",
    "The country code is required."
  ]
}
Error Response - Validation
{
  "message": "Product not found in the database"
}
Server Error Response
{
  "message": "Failed to update product",
  "error": "Internal server error details"
}

Code Examples

PHP Example (Guzzle HTTP Client)
<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

$client = new Client([
    'base_uri' => 'https://api.commerceclarity.com',
    'timeout'  => 10.0,
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_TOKEN',
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ]
]);

$productCode = '8004120057724'; // Product code to delete
$country = 'it'; // Country code

$updateData = [
    'product_code' => $productCode,
    'country' => $country,
    'name' => 'Premium Organic Face Moisturizer',
    'short_description' => 'Nourishing organic moisturizer for all skin types',
    'description' => 'This premium organic face moisturizer is formulated with natural ingredients to provide deep hydration and nourishment for all skin types. Enriched with aloe vera, vitamin E, and essential oils.',
    'key_features' => [
        '100% organic ingredients',
        'Suitable for all skin types',
        'Dermatologically tested'
    ],
    'title_tag' => 'Premium Organic Face Moisturizer | Natural Skincare',
    'meta_description' => 'Discover our premium organic face moisturizer with natural ingredients. Perfect for all skin types, providing deep hydration and nourishment.',
    'meta_keywords' => 'organic moisturizer, natural skincare, face cream, hydration, vitamin E',
    'global_attr' => [
        'color' => [
            'attribute_id' => 'attr_color_global',
            'value' => 'Red'
        ],
        'weight' => [
            'attribute_id' => null,
            'value' => [
                'value' => 250,
                'unit' => 'g'
            ]
        ],
        'eco_friendly' => [
            'attribute_id' => 'attr_eco',
            'value' => null
        ]
    ],
    'family_attr' => [
        'screen_size' => [
            'attribute_id' => 'attr_screen_size',
            'value' => [
                'value' => 6.5,
                'unit' => 'inches'
            ]
        ]
    ]
];

try {
    $response = $client->post('/api/v1/products/update', [
        'json' => $updateData
    ]);
    
    $result = json_decode($response->getBody()->getContents(), true);
    
    if (isset($result['message'])) {
        echo "Update successful: " . $result['message'] . "\n";
    } else {
        echo "Product update completed successfully\n";
    }
    
} catch (RequestException $e) {
    echo "Error: " . $e->getMessage() . "\n";
    
    if ($e->hasResponse()) {
        $errorResponse = json_decode($e->getResponse()->getBody()->getContents(), true);
        echo "Error code: " . $e->getResponse()->getStatusCode() . "\n";
        
        if (isset($errorResponse['errors'])) {
            echo "Validation errors:\n";
            foreach ($errorResponse['errors'] as $error) {
                echo "- " . $error . "\n";
            }
        } else {
            echo "Message: " . ($errorResponse['message'] ?? 'no message') . "\n";
        }
    }
}
?>
JavaScript Example (Fetch API)
const productCode = '8004120057724'; // Product code to delete
const country = 'it'; // Country code
const apiUrl = 'https://api.commerceclarity.com/api/v1/products/update';
const token = 'YOUR_API_TOKEN';

const updateData = {
  product_code: productCode,
  country: country,
  name: 'Premium Organic Face Moisturizer',
  short_description: 'Nourishing organic moisturizer for all skin types',
  description: 'This premium organic face moisturizer is formulated with natural ingredients to provide deep hydration and nourishment for all skin types. Enriched with aloe vera, vitamin E, and essential oils.',
  key_features: [
    '100% organic ingredients',
    'Suitable for all skin types',
    'Dermatologically tested'
  ],
  title_tag: 'Premium Organic Face Moisturizer | Natural Skincare',
  meta_description: 'Discover our premium organic face moisturizer with natural ingredients. Perfect for all skin types, providing deep hydration and nourishment.',
  meta_keywords: 'organic moisturizer, natural skincare, face cream, hydration, vitamin E',
  global_attr: {
    color: {
      attribute_id: 'attr_color_global',
      value: 'Red'
    },
    weight: {
      attribute_id: null,
      value: {
        value: 250,
        unit: 'g'
      }
    },
    eco_friendly: {
      attribute_id: 'attr_eco',
      value: null
    }
  },
  family_attr: {
    screen_size: {
      attribute_id: 'attr_screen_size',
      value: {
        value: 6.5,
        unit: 'inches'
      }
    }
  }
};

// Make the update API request
fetch(apiUrl, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(updateData)
})
.then(response => {
  if (!response.ok) {
    return response.json().then(errorData => {
      throw new Error(errorData.message || `Status: ${response.status}`);
    });
  }
  return response.json();
})
.then(data => {
  if (data.message) {
    console.log(`Update successful: ${data.message}`);
  } else {
    console.log('Product update completed successfully');
  }
})
.catch(error => {
  console.error('Error updating product:', error.message);
});
Python Example (Requests)
import requests
import json

# API Configuration
product_code = '8004120057724'  # Product code to delete
country = 'it'  # Country code
api_url = 'https://api.commerceclarity.com/api/v1/products/update'
token = 'YOUR_API_TOKEN'

headers = {
    'Authorization': f'Bearer {token}',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
}

update_data = {
    'product_code': product_code,
    'country': country,
    'name': 'Premium Organic Face Moisturizer',
    'short_description': 'Nourishing organic moisturizer for all skin types',
    'description': 'This premium organic face moisturizer is formulated with natural ingredients to provide deep hydration and nourishment for all skin types. Enriched with aloe vera, vitamin E, and essential oils.',
    'key_features': [
        '100% organic ingredients',
        'Suitable for all skin types',
        'Dermatologically tested'
    ],
    'title_tag': 'Premium Organic Face Moisturizer | Natural Skincare',
    'meta_description': 'Discover our premium organic face moisturizer with natural ingredients. Perfect for all skin types, providing deep hydration and nourishment.',
    'meta_keywords': 'organic moisturizer, natural skincare, face cream, hydration, vitamin E',
    'global_attr': {
        'color': {
            'attribute_id': 'attr_color_global',
            'value': 'Red'
        },
        'weight': {
            'attribute_id': None,
            'value': {
                'value': 250,
                'unit': 'g'
            }
        },
        'eco_friendly': {
            'attribute_id': 'attr_eco',
            'value': None
        }
    },
    'family_attr': {
        'screen_size': {
            'attribute_id': 'attr_screen_size',
            'value': {
                'value': 6.5,
                'unit': 'inches'
            }
        }
    }
}

try:
    # Make the update request
    response = requests.post(api_url, headers=headers, json=update_data)
    
    # Raise exception for HTTP errors
    response.raise_for_status()
    
    # Extract data from the response
    result = response.json()
    
    if 'message' in result:
        print(f"Publication state successfully updated for: {result['message']}")
    else:
        print('Product update completed successfully')
        
except requests.exceptions.HTTPError as err:
    print(f"HTTP Error: {err}")
    if response.text:
        try:
            error_data = response.json()
            if 'errors' in error_data:
                print("Validation errors:")
                for error in error_data['errors']:
                    print(f"- {error}")
            else:
                print(f"Error message: {error_data.get('message', 'no message')}")
        except json.JSONDecodeError:
            print(f"Response text: {response.text}")
        
except requests.exceptions.RequestException as err:
    print(f"Request error: {err}")
cURL Example
curl -X POST "https://api.commerceclarity.com/api/v1/products/update" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "product_code": "8004120057724",
    "country": "it",
    "name": "Premium Organic Face Moisturizer",
    "short_description": "Nourishing organic moisturizer for all skin types",
    "description": "This premium organic face moisturizer is formulated with natural ingredients.",
    "key_features": [
      "100% organic ingredients",
      "Suitable for all skin types",
      "Dermatologically tested"
    ],
    "title_tag": "Premium Organic Face Moisturizer | Natural Skincare",
    "meta_description": "Discover our premium organic face moisturizer with natural ingredients.",
    "meta_keywords": "organic moisturizer, natural skincare, face cream",
    "global_attr": {
      "color": {
        "attribute_id": "attr_color_global",
        "value": "Red"
      },
      "weight": {
        "attribute_id": null,
        "value": {
          "value": 250,
          "unit": "g"
        }
      },
      "eco_friendly": {
        "attribute_id": "attr_eco",
        "value": null
      }
    },
    "family_attr": {
      "screen_size": {
        "attribute_id": "attr_screen_size",
        "value": {
          "value": 6.5,
          "unit": "inches"
        }
      }
    }
  }'

Related Resources

Product Details

Check the current status of a specific product in your inventory.

Go to Product Details
Product Deletion

Learn how to permanently remove products from your inventory.

Go to Product Deletion