This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

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:

Placeholder values

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

PlaceholderReplace withFrom
{projectKey}project_keyyour API Client
{clientID}client_idyour API Client
{clientSecret}secretyour API Client
{scope}scopeyour API Client
{region}your RegionHosts

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 nameValue
grant_typeclient_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:

NameValue
AuthorizationBearer ${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:

EndpointAccesses
/customersYour Customer data
/productsAll of your Products and Product Variants
/ordersYour 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.