What can you do with it?
The Commercetools API allows you to manage your headless commerce platform. You can create and manage products, search through your catalog, query products with complex predicates, and handle product variants, categories, and pricing across multiple locales and currencies.
How to use it?
Basic Command Structure
/your-commercetools-connection [action] [required-parameters] [optional-parameters]
Parameters
Required:
action
- The action to perform (list, create, search, query)
entity
- The entity type (products, product-projections)
Optional:
query
- Search query text
locale
- Language locale (e.g., “en”, “de”)
sku
- Product SKU for searching
category_id
- Category ID for filtering
predicate
- Query predicate for complex filtering
List Products
Retrieve a list of all products in your Commercetools project.
Parameters:
limit
(optional) - Number of products to return
offset
(optional) - Number of products to skip
Example:
/your-commercetools-connection
action: list
entity: products
limit: 10
offset: 0
Response:
{
"offset": 0,
"count": 5,
"total": 5,
"results": [
{
"id": "f3b17f52-9ab1-478f-899c-e3d2d5c74579",
"version": 2,
"productType": {
"typeId": "product-type",
"id": "da5dd5e7-c5e4-4ccd-a753-d92013414cd9"
},
"masterData": {
"current": {
"name": {
"en": "SAPPHIRE"
},
"description": {
"en": "Sample description"
},
"slug": {
"en": "sapphire1374314429721"
},
"masterVariant": {
"id": 1,
"sku": "sku_SAPPHIRE_variant1_1374314429721",
"prices": [
{
"value": {
"currencyCode": "EUR",
"centAmount": 2800
}
}
],
"images": [
{
"url": "https://example.com/cli/data/252542005_1.jpg",
"dimensions": {
"w": 1400,
"h": 1400
}
}
]
}
},
"published": true,
"hasStagedChanges": false
}
}
]
}
Create Product
Create a new product in your Commercetools project.
Parameters:
product_type_id
(required) - Product type ID
name
(required) - Product name with locale
slug
(required) - Product slug with locale
description
(optional) - Product description with locale
sku
(required) - SKU for the master variant
price
(required) - Price information with currency
category_id
(optional) - Category ID to assign the product
Example:
/your-commercetools-connection
action: create
entity: product
product_type_id: 24f510c3-f334-4099-94d8-2c4a10f78472
name: {"en": "MB PREMIUM TECH T"}
slug: {"en": "mb-premium-tech-t1369226795424"}
description: {"en": "Sample description"}
sku: sku_MB_PREMIUM_TECH_T_variant1_1369226795424
price: {"currencyCode": "EUR", "centAmount": 10000}
category_id: cf6d790a-f027-4f46-9a2b-4bc9a31066fb
Response:
{
"id": "e7ba4c75-b1bb-483d-94d8-2c4a10f78472",
"version": 1,
"productType": {
"typeId": "product-type",
"id": "24f510c3-f334-4099-94d8-2c4a10f78472"
},
"masterData": {
"current": {
"name": {
"en": "MB PREMIUM TECH T"
},
"slug": {
"en": "mb-premium-tech-t1369226795424"
},
"masterVariant": {
"sku": "sku_MB_PREMIUM_TECH_T_variant1_1369226795424",
"prices": [
{
"value": {
"currencyCode": "EUR",
"centAmount": 10000
}
}
]
},
"categories": [
{
"typeId": "category",
"id": "cf6d790a-f027-4f46-9a2b-4bc9a31066fb"
}
]
},
"published": false,
"hasStagedChanges": true
}
}
Search Products
Search for products using text search across product names and descriptions.
Parameters:
query
(required) - Search query text
locale
(optional) - Language locale for search (default: “en”)
limit
(optional) - Number of results to return
Example:
/your-commercetools-connection
action: search
entity: product-projections
query: shirt
locale: en
limit: 10
Response:
{
"offset": 0,
"count": 2,
"total": 2,
"results": [
{
"id": "f68c111c-53d5-4f9c-8a6d-c2b015f3a030",
"version": 4,
"productType": {
"typeId": "product-type",
"id": "a3b57818-6c9c-45d4-befa-2dbe3cf18756"
},
"masterData": {
"current": {
"name": {
"en": "Basic T-Shirt"
},
"slug": {
"en": "basic-t-shirt"
},
"categories": [
{
"typeId": "category",
"id": "b6c9c274-3637-41d4-b40e-e4e10a62ef67"
}
],
"masterVariant": {
"sku": "sku_basic_tshirt_1",
"prices": [
{
"value": {
"currencyCode": "EUR",
"centAmount": 1999
}
}
]
}
}
}
}
]
}
Query Products with Predicates
Query products using complex predicates for advanced filtering.
Parameters:
predicate
(required) - Query predicate for filtering
limit
(optional) - Number of results to return
offset
(optional) - Number of results to skip
Example:
/your-commercetools-connection
action: query
entity: products
predicate: masterData(current(slug(en="super-product") and name(en="Super Product")))
limit: 20
Response:
{
"limit": 20,
"offset": 0,
"count": 1,
"total": 1,
"results": [
{
"id": "f3b17f52-9ab1-478f-899c-e3d2d5c74579",
"version": 2,
"productType": {
"typeId": "product-type",
"id": "da5dd5e7-c5e4-4ccd-a753-d92013414cd9"
},
"masterData": {
"current": {
"name": {
"en": "Super Product"
},
"slug": {
"en": "super-product"
},
"masterVariant": {
"sku": "sku_super_product_1",
"prices": [
{
"value": {
"currencyCode": "EUR",
"centAmount": 2800
}
}
]
}
}
}
}
]
}
Notes
Prices are specified in cent amounts (e.g., 2800 = €28.00). Products support multiple locales for names, descriptions, and slugs. The masterData object contains both current (published) and staged (draft) versions. Query predicates must be URL-encoded for API requests. Product types define the structure and attributes available for products. Categories organize products hierarchically. Supports both PinkConnect and Paragon proxy connections.