Introduction to CommerceClarity API

Overview of CommerceClarity APIs and their integration

CommerceClarity APIs provide a programmatic interface that allows you to interact with the platform, automate processes, and easily integrate CommerceClarity functionalities into your existing applications and workflows.

This documentation is designed to guide you through all available functionalities.

API Base URL
https://api.commerceclarity.io

Main Features

Secure Authentication

All API requests are protected via Bearer Token authentication, ensuring that only authorized clients can access your data.

RESTful API

Our APIs follow RESTful principles, using standard HTTP methods and JSON response formats for easy integration with any development environment.

Rate Limiting System

We implement reasonable frequency limits to ensure optimal performance for all users. Critical endpoints are optimized for high loads.

Standardized Formats

All responses are in JSON format with consistent structures. Errors follow predictable patterns to simplify exception handling.

Quick Usage Guide

PHP Example (Guzzle) 
<?php

require 'vendor/autoload.php';

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

// Initialize the API client
$client = new Client([
    'base_uri' => 'https://api.commerceclarity.io/',
    'timeout'  => 10.0,
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_TOKEN',
        'Accept' => 'application/json',
    ]
]);

// Make an API request
try {
    $response = $client->get('products/list');
    $data = json_decode($response->getBody()->getContents(), true);
    
    // Process the data
    
} catch (RequestException $e) {
    if ($e->hasResponse()) {
        $errorResponse = json_decode($e->getResponse()->getBody()->getContents(), true);
        // Handle the error...
    }
}
JavaScript Example (Fetch) 
const apiUrl = 'https://api.commerceclarity.io/products/list';
const token = 'YOUR_API_TOKEN';

// Make an API request
fetch(apiUrl, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Accept': 'application/json'
  }
})
.then(response => {
  if (!response.ok) {
    throw new Error(`Status: ${response.status}`);
  }
  return response.json();
})
.then(data => {
  console.log('Received data:', data);
  // Process the data
})
.catch(error => {
  console.error('Error during the API request:', error);
});
Python Example (Requests) 
import requests

api_url = 'https://api.commerceclarity.io/products/list'
token = 'YOUR_API_TOKEN'

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

# Make an API request
try:
    response = requests.get(api_url, headers=headers)
    response.raise_for_status()  # Raise an exception for HTTP 4XX/5XX responses
    
    data = response.json()
    
    # Process the data
    
except requests.exceptions.HTTPError as err:
    print(f'HTTP Error: {err}')
    if response.text:
        error_data = response.json()
        print(f'Error message: {error_data.get("message", "No message")}')
except requests.exceptions.RequestException as err:
    print(f'Request error: {err}')
cURL Example 
# Make an API request
curl -X GET "https://api.commerceclarity.io/products/list" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Accept: application/json"

Endpoint Categories

Category Description Use Cases
Products Product import and retrieval Analysis, details retrieval, state management

Common Workflows

  1. Product analysis: Use POST /products/analyze providing EAN, ASIN, or MINSAN codes to analyze and enrich product data.
  2. Check the status: Monitor the processing status with GET /products/details/{id}.
  3. Inventory management: Once the analysis is complete, you can update the publication state with PUT /inventories/set-publication-state.
The analysis will consume credits based on the requested services. Monitor your credit balance in the API response.

API Versioning

Currently, all CommerceClarity APIs are in the stable version without the need to explicitly specify the version in the URL.

Any future versions will be managed through specific HTTP headers or URL prefixes, maintaining backward compatibility for a reasonable period.

Supported Systems

CommerceClarity APIs are designed to be used with any programming language or framework capable of making HTTP requests. We provide code examples for the following languages and frameworks:

PHP (Guzzle)
JavaScript (Fetch/Axios)
Python (Requests)
cURL

Next Steps

Authentication

Learn how to authenticate your API requests with access tokens.

Go to Authentication
Product Analysis Endpoint

Add new products to your inventory to be able to retrieve their details.

Go to Product Analysis
Product Details

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

Go to Product Details

Assistance

Technical Support

If you have questions or encounter issues with the APIs, our support team is available to help. Fill out the support form available at this link including details about your request and any error messages received.