API Playground

Test the product analysis endpoint with your data.

Authentication Required

You need to Login to test the API playground

Product Analysis Endpoint

Submit products for analysis and data enrichment

POST

The analysis endpoint allows you to submit product codes (EAN, ASIN, or MINSAN) for analysis and enrichment. This process will create or update product records in your inventory with detailed information from various sources.

Each analysis request will consume credits based on the requested services and the selected model.

Endpoint URL
POST https://api.commerceclarity.com/products/analyze

Request Parameters

Parameter Type Required Description
codes string Required* Product codes (EAN, ASIN, or MINSAN) separated by commas. Up to 100 codes can be specified in a single call if no other parameters (sku, product_handle, title, brand, images, description) are provided. If any of these parameters are included, only one code can be specified. *Not required if the visual parameter is provided
agent_model string Optional Agent model. Accepted values: "v2" (default) - better model, "v1". Affects the type of credits consumed. *For visual requests, the model cannot be set and is always v2
price numeric Conditional docs.price_param_desc
shipping_cost numeric Conditional docs.shipping_cost_param_desc
operation string Optional Product renewal operations. Values: "refresh" (only available for potentially incorrect products, recreates the product without consuming credits) or "renew" (updates the product with additional data up to 3 times for free)
additional_data string Optional Additional data for analysis. Only usable when specifying a single product code
services array|object Optional docs.services_param_desc
services.import boolean Optional docs.services_import_param_desc
services.competitors_prices boolean Optional docs.services_competitors_param_desc
countries array Optional Target countries for analysis (e.g., ["it", "uk", "de"]). Default: ["it"]. Available: ['it', 'uk', 'de', 'fr', 'es']. Import for different countries will only work if enabled on the account. Not available for competitor prices
visual object Optional Visual information for image-based analysis
visual.title string Required** Product title. **Required if visual is used
visual.brand string Required** Product brand. **Required if visual is used
visual.images_list array Required** List of product image URLs. Minimum 1, maximum 5. **Required if visual is used
visual.customer_product_id string Required** Internal product ID (SKU). **Required if visual is used
visual.product_specifications string Optional Product technical specifications in text format
visual.description string Optional Product description in text format

Request Examples

Basic Product Analysis
{
  "codes": "8004120057724", 
  "services": [
    "import",
    "competitors_prices"
  ],
  "price": 12.99,
  "shipping_cost": 4.99,
  "countries": ["it"]
}
Multiple Products Analysis
{
  "codes": "8004120057724,8004120061721,8004120057731",
  "services": [
    "import",
    "competitors_prices"
  ],
  "price": 15.99,
  "shipping_cost": 4.99,
  "countries": ["it"]
}
Advanced Analysis Options
{
  "codes": "8004120057724",
  "agent_model": "v2",
  "price": 12.99,
  "shipping_cost": 4.99,
  "services": {
    "import": true,
    "competitors_prices": true
  },
  "operation": "renew",
  "additional_data": "Premium product with eco-friendly packaging",
  "countries": ["it", "uk", "de"]
}
Visual Analysis
{
"visual": {
  "title": "Organic Moisturizer",
  "brand": "NaturaSkin",
  "images_list": [
    "https://example.com/images/product1.jpg",
    "https://example.com/images/product1-angle.jpg",
    "https://example.com/images/product1-ingredients.jpg"
  ],
  "customer_product_id": "NS-CRIO-001",
  "product_handle": "organic-moisturizer",
  "product_specifications": "Ingredients: Aqua, Aloe Barbadensis Leaf Juice, Glycerin, Cetearyl Alcohol. Content: 50ml",
  "description": "Organic moisturizer formulated with natural ingredients. Ideal for sensitive and dry skin."
},
"services": {
  "import": true,
  "competitors_prices": true
},
"price": 19.99,
"shipping_cost": 3.99,
"countries": ["it"]
}

Response

The analysis endpoint returns a status object with information about the success or failure of the request, along with the updated credit balance for your account.

Success Response
{
  "status": "success",
  "message": "The requested codes have been successfully added to the processing queue",
  "credits": {
    "content": {
      "max": 100,
      "used": 27
    },
    "analytics": {
      "max": 100,
      "used": 34
    }
  }
}
Error Response - Validation
{
  "status": "error",
  "errors": [
    "You don't have enough credits to process this product",
    "The 'price' field is required when requesting competitor prices analysis."
  ]
}

Credit Consumption

Each API call to the analysis endpoint will consume credits from your account based on the requested services and the selected agent model.

Service Model Credits Used Description
import v1 1 content credit Product import with the basic model
import v2 (default) 5 Content Credits Product import with the alternative model
competitors_prices Any 1 analytics credit Competitor prices analysis across various marketplaces

Processing Flow

Once a product is processed through the analysis endpoint, it will be added to your inventory. The analysis process follows these steps:

Processing Flow
  1. Your application sends a request to the <code>/products/analyze</code> endpoint with the product codes and desired services.
  2. The API validates the request and verifies the availability of sufficient credits.
  3. If valid, the product is added to the processing queue.
  4. CommerceClarity systems process the product asynchronously:
    • Collecting product data from multiple sources
    • If requested, analyzing competitor prices from various marketplaces
    • Creating or updating the product in your inventory
  5. You can monitor the product status through the dashboard or API.

Rate Limits

The analysis endpoint is subject to rate limits to ensure system stability. Current limits:

  • Maximum 5 requests per second
  • Maximum 50 codes per request
  • For visual analysis: one product per request

If you need higher limits, contact our support team.

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',
    ]
]);

$productData = [
    'codes' => '8004120057724',
    'services' => [
        'import' => true,
        'competitors_prices' => true
    ],
    'price' => 12.99,
    'shipping_cost' => 4.99,
    'countries' => ['it']
];

try {
    $response = $client->post('/products/analyze', [
        'json' => $productData
    ]);
    
    $result = json_decode($response->getBody()->getContents(), true);
    
    echo "Status: " . $result['status'] . "\n";
    echo "Message: " . $result['message'] . "\n";
    
    // Display remaining credits
    if (isset($result['credits'])) {
        echo "Content Credits: " . ($result['credits']['content']['max'] - $result['credits']['content']['used']) . "\n";
        echo "Analytics Credits: " . ($result['credits']['analytics']['max'] - $result['credits']['analytics']['used']) . "\n";
    }
    
} catch (RequestException $e) {
    echo "Error: " . $e->getMessage() . "\n";
    
    if ($e->hasResponse()) {
        $errorResponse = json_decode($e->getResponse()->getBody()->getContents(), true);
        
        if (isset($errorResponse['errors'])) {
            echo "Validation errors:\n";
            foreach ($errorResponse['errors'] as $error) {
                echo "- " . $error . "\n";
            }
        }
    }
}
JavaScript Example (Fetch API)
// Product data to analyze
const productData = {
  codes: '8004120057724',
  services: {
    import: true,
    competitors_prices: true
  },
  price: 12.99,
  shipping_cost: 4.99,
  countries: ['it']
};

// Request configuration
const apiUrl = 'https://api.commerceclarity.com/products/analyze';
const token = 'YOUR_API_TOKEN';

// Make an API request
fetch(apiUrl, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify(productData)
})
.then(response => {
  if (!response.ok) {
    return response.json().then(errorData => {
      throw new Error(errorData.errors ? errorData.errors.join(', ') : `Status: ${response.status}`);
    });
  }
  return response.json();
})
.then(data => {
  console.log('Response:', data);
  
  // Handle the response
  if (data.status === 'success') {
    console.log('Message:', data.message);
    
    // Display remaining credits
    if (data.credits) {
      console.log('Content Credits:', data.credits.content.max - data.credits.content.used);
      console.log('Analytics Credits:', data.credits.analytics.max - data.credits.analytics.used);
    }
  }
})
.catch(error => {
  console.error('Error during product analysis:', error.message);
});
Python Example (Requests)
import requests
import json

# API Configuration
api_url = 'https://api.commerceclarity.com/products/analyze'
token = 'YOUR_API_TOKEN'

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

# Product data to analyze
product_data = {
    'codes': '8004120057724',
    'services': {
        'import': True,
        'competitors_prices': True
    },
    'price': 12.99,
    'shipping_cost': 4.99,
    'countries': ['it']
}

try:
    # Make the POST request
    response = requests.post(
        api_url,
        headers=headers,
        json=product_data
    )
    
    # Raise an exception for HTTP 4XX/5XX responses
    response.raise_for_status()
    
    # Extract the response data
    result = response.json()
    
    print(f"Status: {result['status']}")
    print(f"Message: {result['message']}")
    
    # Display remaining credits
    if 'credits' in result:
        credits = result['credits']
        print(f"Content Credits: {credits['content']['max'] - credits['content']['used']}")
        print(f"Analytics Credits: {credits['analytics']['max'] - credits['analytics']['used']}")
        
except requests.exceptions.HTTPError as err:
    print(f"HTTP Error: {err}")
    if response.text:
        error_data = response.json()
        if 'errors' in error_data:
            print("Validation errors:")
            for error in error_data['errors']:
                print(f"- {error}")
        
except requests.exceptions.RequestException as err:
    print(f"Request error: {err}")
cURL Example
curl -X POST "https://api.commerceclarity.com/products/analyze" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{
       "codes": "8004120057724",
       "services": {
         "import": true,
         "competitors_prices": true
       },
       "price": 12.99,
       "shipping_cost": 4.99,
       "countries": ["it"]
     }'

Related Resources

Authentication

Learn how to authenticate your API requests with access tokens.

Go to Authentication
Product Details

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

Go to Product Details
Product State

Manage the publication state of your products.

Go to Product State