Documentation

Make your first API call

Learn the fundamentals of using the HTTP API

The HTTP API is the core of commercetools Composable Commerce. Everything in your Project can be retrieved and modified using the HTTP API.

Objectives of this guide

The objective of this guide is to help you make your first API call to your Project. This is to make sure you have everything set up correctly and understand the basics of how to interact with the API.

Upon completing this guide, you will have:

Placeholder values

Since some parameters used in this guide are specific to your Project, the examples use the following placeholders that you should replace with the actual values from your Project and API Client.:

PlaceholderReplace withFrom
{projectKey}project_keyyour API Client
{clientID}client_idyour API Client
{clientSecret}secretyour API Client
{region}your RegionHosts
${BEARER_TOKEN}access_tokenfrom your access token response

Get your access token

Before you can access resources in your Project, you must first get a token from the OAuth 2.0 service and then provide it with every API call.

This involves making an HTTP POST request to the Authorization URL with the client credentials of the API Client you created before.
No headers or payload are required for this request, but you must include the following parameters for the client credentials flow:
Parameter nameValue
grant_typeclient_credentials
scopeAt least one of the scopes you assigned to your API Client, for example: manage_project:{projectKey}
Example request for an access token through the client credentials flow
POST https://{clientID}:{clientSecret}@auth.{region}.commercetools.com/oauth/token
?grant_type=client_credentials
&scope={scope}
Access token returnedjson
{
  "access_token": "NIMrFiOkdGWJdEKTY5uUe16OyE5jIbE6",
  "token_type": "Bearer",
  "expires_in": 172800,
  "scope": "manage_project:{projectKey}"
}
With the value in access_token you can start making calls to the Composable Commerce API.

The token expires in 48 hours (172800 seconds).

Make your first API call

Now that you have your access token, you can make your first API call to your Project. You can retrieve the Project settings by making an HTTP GET request to your host's API URL followed by your {projectKey}.
You must provide the Authorization header with the access token you obtained in the previous step. Replace the placeholder ${BEARER_TOKEN} with your access_token value, for example: Bearer NIMrFiOkdGWJdEKTY5uUe16OyE5jIbE6. If you are using cURL, you can include the header using the -H parameter as follows:
If you can't see the cURL example below, switch the toggle in the top right corner to cURL instead of http.
Example request to retrieve the Project settings
GET https://api.{region}.commercetools.com/{projectKey}/
Authorization: Bearer ${BEARER_TOKEN}

Process response

The response contains information about your Project, including the name, countries, currencies, and languages that are configured for your Project:
Example response with Project settingsjson
{
  "key": "{projectKey}",
  "name": "{projectName}",
  "countries": ["GB", "DE", "US"],
  "currencies": ["EUR", "GBP", "USD"],
  "languages": ["en-GB", "de-DE", "en-US"],
  "createdAt": "2023-10-23T12:48:51.728Z",
  "trialUntil": "2023-12",
  "messages": {
    "enabled": false,
    "deleteDaysAfterCreation": 15
  },
  "carts": {
    "deleteDaysAfterLastModification": 90,
    "allowAddingUnpublishedProducts": false,
    "countryTaxRateFallbackEnabled": false,
    "cartDiscountCache": {
      "enabled": false
    },
    "loadParsedDiscountsEnabled": false
  },
  "shoppingLists": {
    "deleteDaysAfterLastModification": 360
  },
  "version": 9,
  "searchIndexing": {
    "products": {
      "status": "Activated",
      "lastModifiedAt": "2023-10-23T12:50:19.191Z",
      "lastModifiedBy": {
        "isPlatformClient": true
      }
    },
    "orders": {
      "status": "Activated",
      "lastModifiedAt": "2023-10-23T12:49:11.387Z",
      "lastModifiedBy": {
        "isPlatformClient": true
      }
    }
  }
}
If you find it difficult to read the response, use a JSON processor like jq to format the output. To filter out the information you are really interested in you can add the grep command to the cURL request. The example statement below will show you the Project name in the response only:
  | jq . | grep \"name\"

We chose the Project resource as example because it is available by default, even if your Project has no data. The objective is to provide a clear and simple way to get started with the API and understand the basic concepts. If you have succeeded in making this API call, you are now ready to manage other resources in your Project.

If you have received an error response instead, check that you have replaced all the placeholder values with the correct values from your Project and API Client. Also verify that your API Client has the correct scopes assigned to it.

Next steps

Now that you have your access token and have made a successful API call to your Project, you are now ready to create, update, and query resources, such as Customers, Products, and Orders.