API Playground

docs.products_playground_desc

Authentication Required

You need to Login to test the API playground

Product List Endpoint

Get a paginated list of products in your inventory

The product list endpoint allows you to retrieve a paginated list of products in your inventory. The response includes basic information about each product such as code, name, brand, category, and publication state.

The response is paginated with 50 products per page and includes pagination metadata to facilitate navigation through pages.

Note: This operation does not consume credits
Endpoint URL
GET https://api.commerceclarity.com/api/v1/products

Query Parameters

Parameter Type Required Description
page integer Optional Page number to retrieve. Default: 1
search string Optional Search term to filter products by code, SKU, or name
country string Optional Country code for which to get product details. If not specified, the user's default country is used (products_default_country)
publication_state string Optional The new publication state to assign to the products. Accepted values: <code>pending_review</code>, <code>ready</code>, <code>online</code>
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
brand string Optional Filter products by brand name
category string Optional Filter by category using full path separated by " > " (e.g., Electronics > Smartphones)
tags string Optional Filter by tags (comma-separated list)
from string Optional Filter products created from this date (format: YYYY-MM-DD or ISO 8601)
to string Optional Filter products created up to this date (format: YYYY-MM-DD or ISO 8601)
updated_from string Optional Filter products updated from this date (format: YYYY-MM-DD or ISO 8601)
updated_to string Optional Filter products updated up to this date (format: YYYY-MM-DD or ISO 8601)

Request Examples

Basic Request 
curl -X GET "https://api.commerceclarity.com/api/v1/products?page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"
PHP Example (Guzzle HTTP Client) 
$client = new \GuzzleHttp\Client();

$response = $client->get('https://api.commerceclarity.com/api/v1/products', [
    'headers' => [
        'Authorization' => 'Bearer ' . $apiToken,
        'Accept' => 'application/json',
    ],
    'query' => [
        'page' => 1
    ]
]);

$data = json_decode($response->getBody(), true);
JavaScript Example (Fetch API) 
const response = await fetch('https://api.commerceclarity.com/api/v1/products?page=1', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${apiToken}`,
    'Accept': 'application/json'
  }
});

const data = await response.json();

Response Example

Success Response 
{
  "status": "success",
  "data": {
    "current_page": 1,
    "data": [
      {
        "_id": "507f1f77bcf86cd799439011",
        "product_code": "8001234567890",
        "countries": {
          "it": {
            "name": "Product Name",
            "brand": "Brand Name",
            "category": "Category Name"
          }
        },
        "status": "completed",
        "publication_state": "online",
        "thumb": "https://example.com/images/product_thumb.jpg",
        "agent_model": "v2",
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      }
    ],
    "first_page_url": "https://api.commerceclarity.com/api/v1/products?page=1",
    "from": 1,
    "last_page": 10,
    "last_page_url": "https://api.commerceclarity.com/api/v1/products?page=10",
    "next_page_url": "https://api.commerceclarity.com/api/v1/products?page=2",
    "path": "https://api.commerceclarity.com/api/v1/products",
    "per_page": 50,
    "prev_page_url": null,
    "to": 50,
    "total": 500
  }
}

Response Structure

The response is paginated with the following structure:

Field Type Description
current_page integer Current page number
data array Array of products in the current page
data[].code string Product code (EAN, ASIN, etc.)
data[].sku string|null Customer SKU or custom code
data[].countries object Product data organized by country code
data[].countries.{country}.name string Product name for the specific country
data[].countries.{country}.brand string Product brand name
data[].countries.{country}.category string Full category path separated by " > "
data[].tags array Array of product tags
data[].thumb string|null URL to product thumbnail image
data[].status string Product status (completed, processing, error)
data[].publication_state string Publication state (pending_review, ready, online)
data[].agent_model string AI agent model version used (v1, v2)
data[].validation_messages array|null Validation messages if any issues detected
first_page_url string URL to the first page
from integer Index of the first item in the current page
last_page integer Total number of pages
last_page_url string URL to the last page
next_page_url string|null URL to the next page (null if on last page)
path string Base API path
per_page integer Number of items per page (default: 50)
prev_page_url string|null URL to the previous page (null if on first page)
to integer Index of the last item in the current page
total integer Total number of products