Test the product analysis endpoint with your data.
Submit products for analysis and data enrichment
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.
POST https://api.commerceclarity.com/products/analyze
| 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 |
{
"codes": "8004120057724",
"services": [
"import",
"competitors_prices"
],
"price": 12.99,
"shipping_cost": 4.99,
"countries": ["it"]
}
{
"codes": "8004120057724,8004120061721,8004120057731",
"services": [
"import",
"competitors_prices"
],
"price": 15.99,
"shipping_cost": 4.99,
"countries": ["it"]
}
{
"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": {
"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"]
}
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.
{
"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
}
}
}
{
"status": "error",
"errors": [
"You don't have enough credits to process this product",
"The 'price' field is required when requesting competitor prices analysis."
]
}
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 |
Once a product is processed through the analysis endpoint, it will be added to your inventory. The analysis process follows these steps:
The analysis endpoint is subject to rate limits to ensure system stability. Current limits:
If you need higher limits, contact our support team.
<?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";
}
}
}
}
// 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);
});
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 -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"]
}'
Check the current status of a specific product in your inventory.
Go to Product Details