HTTP API Tutorial

Dive into the commercetools Composable Commerce HTTP API.

The Composable Commerce HTTP API provides business logic for commerce solutions as web services which you can request using any HTTP client of your choice in any programming language.

A typical application would be a web shop that provides a customizable user interface via HTML and CSS. Those applications perform API calls to carry out actions like searching for Products, putting Products in a Cart, or generating Orders.

In this tutorial you will learn the essential basics of the Composable Commerce HTTP API:

authenticate with OAuth 2.0 to get an access_token
retrieve Products

Supported clients

The HTTP client used in this tutorial is cURL, but you can use the tool or programming language of your choice to make calls to the Composable Commerce HTTP API.

commercetools also has four SDKs to simplify making API calls. Learn more about commercetools SDKs and follow get started guides for each SDK at:

Prerequisites

We assume that you've completed the getting started guide and have created a Project that contains one or more Products.

If you are using a commercetools SDK, you can skip Authentication and Preparation as these are automatically performed by the SDK.

Authentication

commercetools Composable Commerce provides authorization via OAuth 2.0 with scopes. The scope enables you to expose the API with limited rights, such as giving smartphone apps the right to view and search for Products but not the ability to change or delete Products.

An OAuth 2.0 token can be generated for your Project with cURL as shown in the cURL cheatsheet.

Example Requestshell

#!/bin/sh
$curl https://clientID:clientSecret@auth.{region}.commercetools.com/oauth/token \
  -X POST \
  -d "grant_type=client_credentials&scope=manage_project:demo-project-slug"

Example Responsejson

{
  "access_token": "kLhYhqi-XDOsWC_qpOHCkUx07WCYcIyU",
  "token_type": "Bearer",
  "expires_in": 172800,
  "scope": "manage_project:demo-project-slug"
}

The example response means that the token kLhYhqi-XDOsWC_qpOHCkUx07WCYcIyU can be used for the next 172800 seconds (2 days) for the Project identified by the Project key demo-project-slug. This token provides full access to the Project.

To limit the rights to the API, substitute manage_project with one of the listed scopes, such as view_products to only allow read access to the Products.

The token must be included in the HTTP header in every API call. In cURL you can include it using -H 'Authorization: Bearer kLhYhqi-XDOsWC_qpOHCkUx07WCYcIyU'.

Preparation

Set the following environment variables, for example in the current terminal:

projectKey=demo-project-slug # please use your project key instead
token=kLhYhqi-XDOsWC_qpOHCkUx07WCYcIyU # please use your token instead
baseUrl=https://api.{region}.commercetools.com/${projectKey}
tokenHeader="Authorization: Bearer ${token}"

Retrieve Products

All Products

To retrieve all Products as described in Query Products, make a GET request to the endpoint ${baseUrl}/products with the token in the HTTP header:

Select programming language

ProductPagedQueryResponse productQueryResult = apiRoot
  .products()
  .get()
  .executeBlocking()
  .getBody();

API response:json

{
  "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"
          },
          "categories": [
            {
              "typeId": "category",
              "id": "b6c9c274-3637-41d4-b40e-e4e10a62ef67"
            }
          ],
          "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
                }
              }
            ],
            "attributes": []
          },
          "variants": []
        },
        "staged": {
          "name": {
            "en": "SAPPHIRE"
          },
          "description": {
            "en": "Sample description"
          },
          "categories": [
            {
              "typeId": "category",
              "id": "b6c9c274-3637-41d4-b40e-e4e10a62ef67"
            }
          ],
          "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
                }
              }
            ],
            "attributes": []
          },
          "variants": []
        },
        "published": true,
        "hasStagedChanges": false
      },
      "taxCategory": {
        "typeId": "tax-category",
        "id": "6a9a275f-cc37-46ec-bf65-df86cff150c3"
      }
    },
    {
      "id": "54e625a3-fb88-4593-82eb-28d1e52a7200",
      "version": 2,
      "productType": {
        "typeId": "product-type",
        "id": "da5dd5e7-c5e4-4ccd-a753-d92013414cd9"
      },
      "masterData": {
        "current": {
          "name": {
            "en": "GIRLS CREW"
          },
          "description": {
            "en": "Sample description"
          },
          "categories": [
            {
              "typeId": "category",
              "id": "870b3e14-94c1-420e-b830-452a4b0f86a3"
            }
          ],
          "slug": {
            "en": "girls-crew1374314429744"
          },
          "masterVariant": {
            "id": 1,
            "sku": "sku_GIRLS_CREW_variant1_1374314429744",
            "prices": [
              {
                "value": {
                  "currencyCode": "EUR",
                  "centAmount": 3400
                }
              }
            ],
            "images": [
              {
                "url": "https://example.com/cli/data/253234387_1.jpg",
                "dimensions": {
                  "w": 1400,
                  "h": 1400
                }
              }
            ],
            "attributes": []
          },
          "variants": []
        },
        "staged": {
          "name": {
            "en": "GIRLS CREW"
          },
          "description": {
            "en": "Sample description"
          },
          "categories": [
            {
              "typeId": "category",
              "id": "870b3e14-94c1-420e-b830-452a4b0f86a3"
            }
          ],
          "slug": {
            "en": "girls-crew1374314429744"
          },
          "masterVariant": {
            "id": 1,
            "sku": "sku_GIRLS_CREW_variant1_1374314429744",
            "prices": [
              {
                "value": {
                  "currencyCode": "EUR",
                  "centAmount": 3400
                }
              }
            ],
            "images": [
              {
                "url": "https://example.com/cli/data/253234387_1.jpg",
                "dimensions": {
                  "w": 1400,
                  "h": 1400
                }
              }
            ],
            "attributes": []
          },
          "variants": []
        },
        "published": true,
        "hasStagedChanges": false
      },
      "taxCategory": {
        "typeId": "tax-category",
        "id": "6a9a275f-cc37-46ec-bf65-df86cff150c3"
      }
    },
    {
      "id": "11e9c8de-f851-4c3d-bd2b-091edcf3c6df",
      "version": 2,
      "productType": {
        "typeId": "product-type",
        "id": "da5dd5e7-c5e4-4ccd-a753-d92013414cd9"
      },
      "masterData": {
        "current": {
          "name": {
            "en": "WB ATHLETIC TANK"
          },
          "description": {
            "en": "Sample description"
          },
          "categories": [
            {
              "typeId": "category",
              "id": "d312c586-7edf-4d85-a07e-3b3d18c998b1"
            }
          ],
          "slug": {
            "en": "wb-athletic-tank1374314429773"
          },
          "masterVariant": {
            "id": 1,
            "sku": "sku_WB_ATHLETIC_TANK_variant1_1374314429773",
            "prices": [
              {
                "value": {
                  "currencyCode": "EUR",
                  "centAmount": 8400
                }
              }
            ],
            "images": [
              {
                "url": "https://example.com/cli/data/253265444_1.jpg",
                "dimensions": {
                  "w": 1400,
                  "h": 1400
                }
              }
            ],
            "attributes": []
          },
          "variants": []
        },
        "staged": {
          "name": {
            "en": "WB ATHLETIC TANK"
          },
          "description": {
            "en": "Sample description"
          },
          "categories": [
            {
              "typeId": "category",
              "id": "d312c586-7edf-4d85-a07e-3b3d18c998b1"
            }
          ],
          "slug": {
            "en": "wb-athletic-tank1374314429773"
          },
          "masterVariant": {
            "id": 1,
            "sku": "sku_WB_ATHLETIC_TANK_variant1_1374314429773",
            "prices": [
              {
                "value": {
                  "currencyCode": "EUR",
                  "centAmount": 8400
                }
              }
            ],
            "images": [
              {
                "url": "https://example.com/cli/data/253265444_1.jpg",
                "dimensions": {
                  "w": 1400,
                  "h": 1400
                }
              }
            ],
            "attributes": []
          },
          "variants": []
        },
        "published": true,
        "hasStagedChanges": false
      },
      "taxCategory": {
        "typeId": "tax-category",
        "id": "6a9a275f-cc37-46ec-bf65-df86cff150c3"
      }
    },
    {
      "id": "5becc121-1bbe-45f3-9f67-04208b476b3e",
      "version": 2,
      "productType": {
        "typeId": "product-type",
        "id": "da5dd5e7-c5e4-4ccd-a753-d92013414cd9"
      },
      "masterData": {
        "current": {
          "name": {
            "en": "MB SOFTSHELL LINER"
          },
          "description": {
            "en": "Sample description"
          },
          "categories": [
            {
              "typeId": "category",
              "id": "b6c9c274-3637-41d4-b40e-e4e10a62ef67"
            }
          ],
          "slug": {
            "en": "mb-softshell-liner1374314429797"
          },
          "masterVariant": {
            "id": 1,
            "sku": "sku_MB_SOFTSHELL_LINER_variant1_1374314429797",
            "prices": [
              {
                "value": {
                  "currencyCode": "EUR",
                  "centAmount": 10000
                }
              }
            ],
            "images": [
              {
                "url": "https://example.com/cli/data/254391631_1.jpg",
                "dimensions": {
                  "w": 1400,
                  "h": 1400
                }
              }
            ],
            "attributes": []
          },
          "variants": []
        },
        "staged": {
          "name": {
            "en": "MB SOFTSHELL LINER"
          },
          "description": {
            "en": "Sample description"
          },
          "categories": [
            {
              "typeId": "category",
              "id": "b6c9c274-3637-41d4-b40e-e4e10a62ef67"
            }
          ],
          "slug": {
            "en": "mb-softshell-liner1374314429797"
          },
          "masterVariant": {
            "id": 1,
            "sku": "sku_MB_SOFTSHELL_LINER_variant1_1374314429797",
            "prices": [
              {
                "value": {
                  "currencyCode": "EUR",
                  "centAmount": 10000
                }
              }
            ],
            "images": [
              {
                "url": "https://example.com/cli/data/254391631_1.jpg",
                "dimensions": {
                  "w": 1400,
                  "h": 1400
                }
              }
            ],
            "attributes": []
          },
          "variants": []
        },
        "published": true,
        "hasStagedChanges": false
      },
      "taxCategory": {
        "typeId": "tax-category",
        "id": "6a9a275f-cc37-46ec-bf65-df86cff150c3"
      }
    },
    {
      "id": "336c316d-7cf2-456d-a178-8e6bfeaede69",
      "version": 2,
      "productType": {
        "typeId": "product-type",
        "id": "da5dd5e7-c5e4-4ccd-a753-d92013414cd9"
      },
      "masterData": {
        "current": {
          "name": {
            "en": "MB PREMIUM TECH T"
          },
          "description": {
            "en": "Sample description"
          },
          "categories": [
            {
              "typeId": "category",
              "id": "870b3e14-94c1-420e-b830-452a4b0f86a3"
            }
          ],
          "slug": {
            "en": "mb-premium-tech-t1374314429824"
          },
          "masterVariant": {
            "id": 1,
            "sku": "sku_MB_PREMIUM_TECH_T_variant1_1374314429824",
            "prices": [
              {
                "value": {
                  "currencyCode": "EUR",
                  "centAmount": 10000
                }
              }
            ],
            "images": [
              {
                "url": "https://example.com/cli/data/253245821_1.jpg",
                "dimensions": {
                  "w": 1400,
                  "h": 1400
                }
              }
            ],
            "attributes": []
          },
          "variants": []
        },
        "staged": {
          "name": {
            "en": "MB PREMIUM TECH T"
          },
          "description": {
            "en": "Sample description"
          },
          "categories": [
            {
              "typeId": "category",
              "id": "870b3e14-94c1-420e-b830-452a4b0f86a3"
            }
          ],
          "slug": {
            "en": "mb-premium-tech-t1374314429824"
          },
          "masterVariant": {
            "id": 1,
            "sku": "sku_MB_PREMIUM_TECH_T_variant1_1374314429824",
            "prices": [
              {
                "value": {
                  "currencyCode": "EUR",
                  "centAmount": 10000
                }
              }
            ],
            "images": [
              {
                "url": "https://example.com/cli/data/253245821_1.jpg",
                "dimensions": {
                  "w": 1400,
                  "h": 1400
                }
              }
            ],
            "attributes": []
          },
          "variants": []
        },
        "published": true,
        "hasStagedChanges": false
      },
      "taxCategory": {
        "typeId": "tax-category",
        "id": "6a9a275f-cc37-46ec-bf65-df86cff150c3"
      }
    }
  ]
}

Products of a Category

Depending on the number of Products in your Project, querying for all Products may not be optimal. Projects often utilize hierarchical structures, known as Categories, to organize Products for purposes such as easier navigation or enhanced search functionality.

In the following example, we will load Products from a specific Category named "Long sleeves".

First, we query all Categories with:

Select programming language

CategoryPagedQueryResponse categoryQueryResult = apiRoot
  .categories()
  .get()
  .executeBlocking()
  .getBody();

API response:json

{
  "offset": 0,
  "count": 4,
  "total": 4,
  "results": [
    {
      "id": "b6c9c274-3637-41d4-b40e-e4e10a62ef67",
      "version": 1,
      "name": {
        "en": "Snowboard equipment"
      },
      "slug": {
        "en": "snowboard-equipment-b6c9c274-3637-41d4-b40e-e4e10a62ef67"
      },
      "ancestors": []
    },
    {
      "id": "d312c586-7edf-4d85-a07e-3b3d18c998b1",
      "version": 1,
      "name": {
        "en": "Tank tops"
      },
      "slug": {
        "en": "tank-tops-d312c586-7edf-4d85-a07e-3b3d18c998b1"
      },
      "ancestors": []
    },
    {
      "id": "870b3e14-94c1-420e-b830-452a4b0f86a3",
      "version": 1,
      "name": {
        "en": "Long sleeves"
      },
      "slug": {
        "en": "long-sleeves-870b3e14-94c1-420e-b830-452a4b0f86a3"
      },
      "ancestors": []
    },
    {
      "id": "7a4494b0-674e-4374-b4ab-38396bba6359",
      "version": 1,
      "name": {
        "en": "Hats"
      },
      "slug": {
        "en": "hats-7a4494b0-674e-4374-b4ab-38396bba6359"
      },
      "ancestors": []
    }
  ]
}

The response shows us that the "Long sleeves" Category has the ID 870b3e14-94c1-420e-b830-452a4b0f86a3.

Products are rich objects that can have multiple representations, structured like a tree of objects and arrays.

The first level of the Product object contains the id, key, and the masterData which is of type ProductCatalogData. This object holds the Product information of a category. ProductCatalogData consists of the two objects current (released data) and staged (draft) of the type ProductData. This object contains the name, categories, and description of the Product and also the Variants.

The path to the Category ID is masterData.current.categories[2].id. Since we know the Category ID and the path in the Product representation, we can filter for it during Product search by using Query Predicates.

cURL helps to urlencode the query predicate from where=masterData(current(categories(id="870b3e14-94c1-420e-b830-452a4b0f86a3"))) to where=masterData%28current%28categories%28id%3D%22870b3e14-94c1-420e-b830-452a4b0f86a3%22%29%29%29.

Select programming language

final ProductPagedQueryResponse productQuery = apiRoot
  .products()
  .get()
  .withWhere(
    "masterData(current(categories(id=\"870b3e14-94c1-420e-b830-452a4b0f86a3\")))"
  )
  .executeBlocking()
  .getBody();

API response:json

{
  "offset": 0,
  "count": 2,
  "total": 2,
  "results": [
    {
      "id": "54e625a3-fb88-4593-82eb-28d1e52a7200",
      "version": 2,
      "productType": {
        "typeId": "product-type",
        "id": "da5dd5e7-c5e4-4ccd-a753-d92013414cd9"
      },
      "masterData": {
        "current": {
          "name": {
            "en": "GIRLS CREW"
          },
          "description": {
            "en": "Sample description"
          },
          "categories": [
            {
              "typeId": "category",
              "id": "870b3e14-94c1-420e-b830-452a4b0f86a3"
            }
          ],
          "slug": {
            "en": "girls-crew1374314429744"
          },
          "masterVariant": {
            "id": 1,
            "sku": "sku_GIRLS_CREW_variant1_1374314429744",
            "prices": [
              {
                "value": {
                  "currencyCode": "EUR",
                  "centAmount": 3400
                }
              }
            ],
            "images": [
              {
                "url": "https://example.com/cli/data/253234387_1.jpg",
                "dimensions": {
                  "w": 1400,
                  "h": 1400
                }
              }
            ],
            "attributes": []
          },
          "variants": []
        },
        "staged": {
          "name": {
            "en": "GIRLS CREW"
          },
          "description": {
            "en": "Sample description"
          },
          "categories": [
            {
              "typeId": "category",
              "id": "870b3e14-94c1-420e-b830-452a4b0f86a3"
            }
          ],
          "slug": {
            "en": "girls-crew1374314429744"
          },
          "masterVariant": {
            "id": 1,
            "sku": "sku_GIRLS_CREW_variant1_1374314429744",
            "prices": [
              {
                "value": {
                  "currencyCode": "EUR",
                  "centAmount": 3400
                }
              }
            ],
            "images": [
              {
                "url": "https://example.com/cli/data/253234387_1.jpg",
                "dimensions": {
                  "w": 1400,
                  "h": 1400
                }
              }
            ],
            "attributes": []
          },
          "variants": []
        },
        "published": true,
        "hasStagedChanges": false
      },
      "taxCategory": {
        "typeId": "tax-category",
        "id": "6a9a275f-cc37-46ec-bf65-df86cff150c3"
      }
    },
    {
      "id": "336c316d-7cf2-456d-a178-8e6bfeaede69",
      "version": 2,
      "productType": {
        "typeId": "product-type",
        "id": "da5dd5e7-c5e4-4ccd-a753-d92013414cd9"
      },
      "masterData": {
        "current": {
          "name": {
            "en": "MB PREMIUM TECH T"
          },
          "description": {
            "en": "Sample description"
          },
          "categories": [
            {
              "typeId": "category",
              "id": "870b3e14-94c1-420e-b830-452a4b0f86a3"
            }
          ],
          "slug": {
            "en": "mb-premium-tech-t1374314429824"
          },
          "masterVariant": {
            "id": 1,
            "sku": "sku_MB_PREMIUM_TECH_T_variant1_1374314429824",
            "prices": [
              {
                "value": {
                  "currencyCode": "EUR",
                  "centAmount": 10000
                }
              }
            ],
            "images": [
              {
                "url": "https://example.com/cli/data/253245821_1.jpg",
                "dimensions": {
                  "w": 1400,
                  "h": 1400
                }
              }
            ],
            "attributes": []
          },
          "variants": []
        },
        "staged": {
          "name": {
            "en": "MB PREMIUM TECH T"
          },
          "description": {
            "en": "Sample description"
          },
          "categories": [
            {
              "typeId": "category",
              "id": "870b3e14-94c1-420e-b830-452a4b0f86a3"
            }
          ],
          "slug": {
            "en": "mb-premium-tech-t1374314429824"
          },
          "masterVariant": {
            "id": 1,
            "sku": "sku_MB_PREMIUM_TECH_T_variant1_1374314429824",
            "prices": [
              {
                "value": {
                  "currencyCode": "EUR",
                  "centAmount": 10000
                }
              }
            ],
            "images": [
              {
                "url": "https://example.com/cli/data/253245821_1.jpg",
                "dimensions": {
                  "w": 1400,
                  "h": 1400
                }
              }
            ],
            "attributes": []
          },
          "variants": []
        },
        "published": true,
        "hasStagedChanges": false
      },
      "taxCategory": {
        "typeId": "tax-category",
        "id": "6a9a275f-cc37-46ec-bf65-df86cff150c3"
      }
    }
  ]
}

You did it! For more tutorials that cover advanced topics, refer to our tutorials section.

For more information on how to use the HTTP API, consult the Composable Commerce API reference.

HTTP API Tutorial

Supported clients.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Prerequisites.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Authentication.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Preparation.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Retrieve Products.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

All Products.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Products of a Category.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Supported clients

Prerequisites

Authentication

Preparation

Retrieve Products

All Products

Products of a Category