Make your first calls to the Composable Commerce API

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

Use your development environment with this sample data as safe playground for testing and experimentation. Explore various features like faceting, promotions, and order creation without the risk of affecting your current production environment.

By the end of this guide you will have:

Obtained your access token
Learned how to structure an API call
Made your first API call

Placeholder values

Example code in this getting started guide uses placeholders that should be replaced with these values:

Placeholder	Replace with	From
`{projectKey}`	project_key	your API Client
`{clientID}`	client_id	your API Client
`{clientSecret}`	secret	your API Client
`{scope}`	scope	your API Client
`{region}`	your Region	Hosts

Get your access token

Before you can make API calls, you need an access token.

This involves making a POST call to the auth URL with two parameters.

No headers or payload are required for this call.

Auth URL and parameters

The following is the URL to post to, with the parameters to use.

https://{clientID}:{clientSecret}@auth.{region}.commercetools.com/oauth/token

Parameter name	Value
grant_type	client_credentials
scope	`{scope}` For example: `manage_project:getting-started-project`

Example request and response

This example request returns an access token, its eligibility period, and the scopes available:

Example request that returns an access token

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

In following examples, replace the placeholder ${BEARER_TOKEN} with the access_token value.

How to make an API call

All requests to the Composable Commerce API require a minimum of:

A header containing authorization information (the access token).
A valid URL to an API endpoint.

For all API calls this header must be included:

Name	Value
Authorization	Bearer `${BEARER_TOKEN}` For example: `Bearer NIMrFiOkdGWJdEKTY5uUe16OyE5jIbE6`

URL and endpoints

Use the API URL from your API Client followed by your {projectKey}.

For example: https://api.{region}.commercetools.com/{projectKey}/

Example endpoints

Endpoints can be added to this URL to change what resource is targeted. Some examples are below:

Endpoint	Accesses
/customers	Your Customer data
/products	All of your Products and Product Variants
/orders	Your Order data

An example URL for the Query Customers endpoint is:
https://api.{region}.commercetools.com/{projectKey}/customers

A GET call to this URL with the Authorization header returns all your Customer data.

Parameters

If your API call response begins with limit, offset, count, total, and results, then you can include parameters to modify the results.

Common parameters include where, sort, limit, and offset.

When querying single resources (such as a specified Customer or Product), parameters will be ignored as a single JSON object is returned.

Make your first API call to the Project endpoint

If you make a GET call to your API URL with the Authorization header and no endpoint, you receive your Project data:

Example request to the API URL with no endpoint

GET https://api.{region}.commercetools.com/{projectKey}/
Authorization: Bearer ${BEARER_TOKEN}

Example response from the API requestjson

{
  "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
      }
    }
  }
}

Next steps

To learn more about authorization you can consult the HTTP API reference.

Now that you have your access token and have made initial calls to the API, you are now ready to create, update, and query Customers.