​
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

​
Tools

​
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.