HTTP API Tutorial

Dive into the commercetools platform HTTP API.

The commercetools platform HTTP API provides business logic for e-commerce solutions as Web services which you can request by any HTTP client of your choice in any programming language you like.

A typical application would be a Web Shop providing a full customizable GUI via HTML and CSS. Those applications do HTTP calls to the commercetools platform to perform actions like searching for products, putting products in a cart or generating orders.

In this tutorial you will learn the most essential basics of the commercetools platform HTTP API

Supported clients

Commercetools supports clients in three different languages to help you connect with the HTTP APIs:

Additionally, we provide some samples in many other languages in our ↗ Hello API Github repository .

The HTTP client used in this tutorial is curl , but you can use one of your choice instead.

Prerequisites

We assume that you’ve completed the Getting Started Tutorial to get your API keys that allow you accessing the commercetools platform. We also assume that the commercetools platform project you’ll use for this tutorial contains some products. When creating new commercetools platform projects in the ↗ Admin Center EU (or ↗ Admin Center US ) you’ll be asked if you want to fill your project with some example product data.

Authentication

The commercetools platform provides authorization via OAuth2 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 possibility to change or delete products.

How to generate an OAuth2 token for your project with cURL is shown in the Admin Center in the section Developers in the tab API CLIENTS.
Use the copy symbol on the page to get the call and paste it into the console.
After pressing enter you will receive a Bearer token.

Screenshot API Settings

Example Request
#!/bin/sh
$curl https://clientID:clientSecret@auth.sphere.io/oauth/token \
      -X POST \
      -d "grant_type=client_credentials&scope=manage_project:demo-project-slug"
Example Response
{
  "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 with full access.

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 has to be part of the HTTP headers in every shop related request. In cURL this is done by -H 'Authorization: Bearer kLhYhqi-XDOsWC_qpOHCkUx07WCYcIyU' as command line argument.

Preparation

Please set the following environment variables, e.g. 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.sphere.io/${projectKey}
tokenHeader="Authorization: Bearer ${token}"

Retrieving Products

All Products

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

$curl -H "${tokenHeader}" "${baseUrl}/products"
#equals
$curl -H 'Authorization: Bearer kLhYhqi-XDOsWC_qpOHCkUx07WCYcIyU' https://api.sphere.io/demo-project-slug/products
 final ProductQuery productQuery = ProductQuery.of();
 return client.execute(productQuery);
<?php
 $request = ProductQueryRequest::of();
 $response = $request->executeWithClient($client);
 $products = $request->mapFromResponse($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"
        },
        "catalogs": [],
        "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://sphere.io/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://sphere.io/cli/data/252542005_1.jpg",
                            "dimensions": {
                                "w": 1400,
                                "h": 1400
                            }
                        }
                    ],
                    "attributes": []
                },
                "variants": []
            },
            "published": true,
            "hasStagedChanges": false
        },
        "catalogData": {},
        "taxCategory": {
            "typeId": "tax-category",
            "id": "6a9a275f-cc37-46ec-bf65-df86cff150c3"
        },
        "lastVariantId": 1
    },
    {
        "id": "54e625a3-fb88-4593-82eb-28d1e52a7200",
        "version": 2,
        "productType": {
            "typeId": "product-type",
            "id": "da5dd5e7-c5e4-4ccd-a753-d92013414cd9"
        },
        "catalogs": [],
        "masterData": {
            "current": {
                "name": {
                    "en": "GIRLS HARTBREAK CREW"
                },
                "description": {
                    "en": "Sample description"
                },
                "categories": [
                    {
                        "typeId": "category",
                        "id": "870b3e14-94c1-420e-b830-452a4b0f86a3"
                    }
                ],
                "slug": {
                    "en": "girls-hartbreak-crew1374314429744"
                },
                "masterVariant": {
                    "id": 1,
                    "sku": "sku_GIRLS_HARTBREAK_CREW_variant1_1374314429744",
                    "prices": [
                        {
                            "value": {
                                "currencyCode": "EUR",
                                "centAmount": 3400
                            }
                        }
                    ],
                    "images": [
                        {
                            "url": "https://sphere.io/cli/data/253234387_1.jpg",
                            "dimensions": {
                                "w": 1400,
                                "h": 1400
                            }
                        }
                    ],
                    "attributes": []
                },
                "variants": []
            },
            "staged": {
                "name": {
                    "en": "GIRLS HARTBREAK CREW"
                },
                "description": {
                    "en": "Sample description"
                },
                "categories": [
                    {
                        "typeId": "category",
                        "id": "870b3e14-94c1-420e-b830-452a4b0f86a3"
                    }
                ],
                "slug": {
                    "en": "girls-hartbreak-crew1374314429744"
                },
                "masterVariant": {
                    "id": 1,
                    "sku": "sku_GIRLS_HARTBREAK_CREW_variant1_1374314429744",
                    "prices": [
                        {
                            "value": {
                                "currencyCode": "EUR",
                                "centAmount": 3400
                            }
                        }
                    ],
                    "images": [
                        {
                            "url": "https://sphere.io/cli/data/253234387_1.jpg",
                            "dimensions": {
                                "w": 1400,
                                "h": 1400
                            }
                        }
                    ],
                    "attributes": []
                },
                "variants": []
            },
            "published": true,
            "hasStagedChanges": false
        },
        "catalogData": {},
        "taxCategory": {
            "typeId": "tax-category",
            "id": "6a9a275f-cc37-46ec-bf65-df86cff150c3"
        },
        "lastVariantId": 1
    },
    {
        "id": "11e9c8de-f851-4c3d-bd2b-091edcf3c6df",
        "version": 2,
        "productType": {
            "typeId": "product-type",
            "id": "da5dd5e7-c5e4-4ccd-a753-d92013414cd9"
        },
        "catalogs": [],
        "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://sphere.io/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://sphere.io/cli/data/253265444_1.jpg",
                            "dimensions": {
                                "w": 1400,
                                "h": 1400
                            }
                        }
                    ],
                    "attributes": []
                },
                "variants": []
            },
            "published": true,
            "hasStagedChanges": false
        },
        "catalogData": {},
        "taxCategory": {
            "typeId": "tax-category",
            "id": "6a9a275f-cc37-46ec-bf65-df86cff150c3"
        },
        "lastVariantId": 1
    },
    {
        "id": "5becc121-1bbe-45f3-9f67-04208b476b3e",
        "version": 2,
        "productType": {
            "typeId": "product-type",
            "id": "da5dd5e7-c5e4-4ccd-a753-d92013414cd9"
        },
        "catalogs": [],
        "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://sphere.io/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://sphere.io/cli/data/254391631_1.jpg",
                            "dimensions": {
                                "w": 1400,
                                "h": 1400
                            }
                        }
                    ],
                    "attributes": []
                },
                "variants": []
            },
            "published": true,
            "hasStagedChanges": false
        },
        "catalogData": {},
        "taxCategory": {
            "typeId": "tax-category",
            "id": "6a9a275f-cc37-46ec-bf65-df86cff150c3"
        },
        "lastVariantId": 1
    },
    {
        "id": "336c316d-7cf2-456d-a178-8e6bfeaede69",
        "version": 2,
        "productType": {
            "typeId": "product-type",
            "id": "da5dd5e7-c5e4-4ccd-a753-d92013414cd9"
        },
        "catalogs": [],
        "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://sphere.io/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://sphere.io/cli/data/253245821_1.jpg",
                            "dimensions": {
                                "w": 1400,
                                "h": 1400
                            }
                        }
                    ],
                    "attributes": []
                },
                "variants": []
            },
            "published": true,
            "hasStagedChanges": false
        },
        "catalogData": {},
        "taxCategory": {
            "typeId": "tax-category",
            "id": "6a9a275f-cc37-46ec-bf65-df86cff150c3"
        },
        "lastVariantId": 1
    }
]}

Products of a Category

Retrieving all products for an entire shop can be too much load for a shop visitor. It makes sense to organize products into categories like ‘long sleeves’ or ‘snowboard equipment’. Now we want to load just ‘long sleeves’. First we query for all categories with:

$curl -H "${tokenHeader}" "${baseUrl}/categories"
 final CategoryQuery categoryQuery = CategoryQuery.of();
 return client.execute(categoryQuery);
<?php
 $request = CategoryQueryRequest::of();
 $response = $request->executeWithClient($client);
 $categories = $request->mapFromResponse($response);
{
   "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.

The products are rich objects that can have multiple representations. You can find those on the product documentation page and think of it as a tree of structured objects and arrays. On the first level of the product objects are the ID, the name displayed in the Admin Center and the masterData which is of type ProductCatalogData. As the name implies that object holds the product information that can be in a catalog. The ProductCatalogData consists of the two objects current (released data) and staged (draft) of the type ProductData. This object finally contains the name of the product for the customer, the description, the variants, the categories array and much more.
The path to the category ID is masterData.current.categories[0].id.

Since we know the category ID and the path in the product representation, we can filter for it during product search by using the Predicates.

CURL helps to urlencode the query for the category 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.

$curl -H "${tokenHeader}" -G --data-urlencode  'where=masterData(current(categories(id="870b3e14-94c1-420e-b830-452a4b0f86a3")))' "${baseUrl}/products"

#is equivalent to the to human less readable form
$curl -H "${tokenHeader}" "${baseUrl}/products?where=masterData%28current%28categories%28id%3D%22870b3e14-94c1-420e-b830-452a4b0f86a3%22%29%29%29"
 final ProductQuery productQuery = ProductQuery.of()
         .plusPredicates(m -> m.masterData().current().categories().id().is(categoryId));
 return client.execute(productQuery);
<?php
 $request = ProductQueryRequest::of()->where('masterData(current(categories(id="'.$category->getId().'")))');
 $response = $request->executeWithClient($client);
 $products = $request->mapFromResponse($response);
{
   "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"
         },
         "catalogs":[

         ],
         "masterData":{
            "current":{
               "name":{
                  "en":"GIRLS HARTBREAK CREW"
               },
               "description":{
                  "en":"Sample description"
               },
               "categories":[
                  {
                     "typeId":"category",
                     "id":"870b3e14-94c1-420e-b830-452a4b0f86a3"
                  }
               ],
               "slug":{
                  "en":"girls-hartbreak-crew1374314429744"
               },
               "masterVariant":{
                  "id":1,
                  "sku":"sku_GIRLS_HARTBREAK_CREW_variant1_1374314429744",
                  "prices":[
                     {
                        "value":{
                           "currencyCode":"EUR",
                           "centAmount":3400
                        }
                     }
                  ],
                  "images":[
                     {
                        "url":"https://sphere.io/cli/data/253234387_1.jpg",
                        "dimensions":{
                           "w":1400,
                           "h":1400
                        }
                     }
                  ],
                  "attributes":[

                  ]
               },
               "variants":[

               ]
            },
            "staged":{
               "name":{
                  "en":"GIRLS HARTBREAK CREW"
               },
               "description":{
                  "en":"Sample description"
               },
               "categories":[
                  {
                     "typeId":"category",
                     "id":"870b3e14-94c1-420e-b830-452a4b0f86a3"
                  }
               ],
               "slug":{
                  "en":"girls-hartbreak-crew1374314429744"
               },
               "masterVariant":{
                  "id":1,
                  "sku":"sku_GIRLS_HARTBREAK_CREW_variant1_1374314429744",
                  "prices":[
                     {
                        "value":{
                           "currencyCode":"EUR",
                           "centAmount":3400
                        }
                     }
                  ],
                  "images":[
                     {
                        "url":"https://sphere.io/cli/data/253234387_1.jpg",
                        "dimensions":{
                           "w":1400,
                           "h":1400
                        }
                     }
                  ],
                  "attributes":[

                  ]
               },
               "variants":[

               ]
            },
            "published":true,
            "hasStagedChanges":false
         },
         "catalogData":{

         },
         "taxCategory":{
            "typeId":"tax-category",
            "id":"6a9a275f-cc37-46ec-bf65-df86cff150c3"
         },
         "lastVariantId":1
      },
      {
         "id":"336c316d-7cf2-456d-a178-8e6bfeaede69",
         "version":2,
         "productType":{
            "typeId":"product-type",
            "id":"da5dd5e7-c5e4-4ccd-a753-d92013414cd9"
         },
         "catalogs":[

         ],
         "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://sphere.io/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://sphere.io/cli/data/253245821_1.jpg",
                        "dimensions":{
                           "w":1400,
                           "h":1400
                        }
                     }
                  ],
                  "attributes":[

                  ]
               },
               "variants":[

               ]
            },
            "published":true,
            "hasStagedChanges":false
         },
         "catalogData":{

         },
         "taxCategory":{
            "typeId":"tax-category",
            "id":"6a9a275f-cc37-46ec-bf65-df86cff150c3"
         },
         "lastVariantId":1
      }
   ]
}

You did it! We will continue to make tutorials for more advanced topics.
For more information on how to develop with the commercetools platform consult the developer resources.