Manage Customers with the API

Learn how to create and manage Customers using the HTTP API

Objectives of this guide

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
{region}your RegionHosts
${BEARER_TOKEN}your access tokenMake your first API call

Query for Customers

The Query Customers endpoint is reached at:
https://api.{region}.commercetools.com/{projectKey}/customers/

When you make a GET call to the Customers endpoint it returns up to 20 Customers by default. Up to 500 Customers can be returned by using a limit query parameter.

In a new Project, there are no Customers.

Create a Customer

Creating new resources with the commercetools Composable Commerce API requires posting a resource draft to a relevant endpoint. The new resource is then returned in the API response.

Customers are created by posting a CustomerDraft to the Customers endpoint.

Create a CustomerDraft

The CustomerDraft has two required fields: email and password.

CustomerDraft to create a Customer with an email address and passwordjson
{
"email": "getting-started@example.com",
"password": "examplePassword"
}

Post the CustomerDraft

Post the CustomerDraft to the Customers endpoint and a new Customer is created with the specified email and password.

Below is an example API call with the returned new Customer resource:

Example request to create a Customer
POST https://api.{region}.commercetools.com/{projectKey}/customers
Authorization: Bearer ${BEARER_TOKEN}
{
"email": "getting-started@example.com",
"password": "examplePassword"
}
Returned Customer resourcejson
{
"customer": {
"id": "{customerID}",
"version": 1,
"createdAt": "2022-01-09T15:32:56.130Z",
"lastModifiedAt": "2022-01-09T15:32:56.130Z",
"lastModifiedBy": {
"clientId": "{clientID}",
"isPlatformClient": false
},
"createdBy": {
"clientId": "{clientID}",
"isPlatformClient": false
},
"email": "getting-started@example.com",
"password": "l9vOLbrU19W4BBCrfDI8sknoTUe+Kegse2n5Zux1SIA=$U+egoGgBOTTYsD5MgL5wEdKvvui6bgNlt8H9+Wctx3A=",
"addresses": [],
"shippingAddressIds": [],
"billingAddressIds": [],
"isEmailVerified": false,
"stores": [],
"authenticationMode": "Password"
}
}

Take note of the highlighted {customerID} in your response as it is used as a placeholder in following examples.

Get your new Customer

Your new Customer can be retrieved by using the {customerID} as a path parameter.

When you make a GET call to this endpoint, you retrieve all the data of this Customer.

Example request to get a Customer
GET https://api.{region}.commercetools.com/{projectKey}/customers/{customerID}
Authorization: Bearer ${BEARER_TOKEN}
Returned Customer resourcejson
{
"customer": {
"id": "{customerID}",
"version": 1,
"createdAt": "2022-01-09T15:32:56.130Z",
"lastModifiedAt": "2022-01-09T15:32:56.130Z",
"lastModifiedBy": {
"clientId": "{clientID}",
"isPlatformClient": false
},
"createdBy": {
"clientId": "{clientID}",
"isPlatformClient": false
},
"email": "getting-started@example.com",
"password": "l9vOLbrU19W4BBCrfDI8sknoTUe+Kegse2n5Zux1SIA=$U+egoGgBOTTYsD5MgL5wEdKvvui6bgNlt8H9+Wctx3A=",
"addresses": [],
"shippingAddressIds": [],
"billingAddressIds": [],
"isEmailVerified": false,
"stores": [],
"authenticationMode": "Password"
}
}

Update your Customer

The Composable Commerce API uses update actions to modify existing resources.

When an array of update actions is posted to the {customerID} endpoint, the Customer is updated based on the specified update actions and values.

The current version of the Customer to be modified is also required.

The version of a new Customer is 1. This value is incremented every time an update action is applied to the Customer.

If the specified version does not match the current version, the request returns an error.

Create an update action array to change the Customer name

As we created a Customer with just an email and password, we should give our Customer a name.

The required update actions are Set First Name and Set Last Name. These update actions should be added to an array.

Customer version and update actions array to change the Customer's namejson
{
"version": 1,
"actions": [
{
"action": "setFirstName",
"firstName": "John"
},
{
"action": "setLastName",
"lastName": "Smith"
}
]
}

Post the update action array

Post this update actions array with the current Customer version to the {customerID} endpoint and the Customer is updated with the specified firstName and lastName.

Below is an example API call with the updated new Customer resource:

Example request to add a Customer name
POST https://api.{region}.commercetools.com/{projectKey}/customers/{customerID}
Authorization: Bearer ${BEARER_TOKEN}
{
"version": 1,
"actions": [
{
"action": "setFirstName",
"firstName": "John"
},
{
"action": "setLastName",
"lastName": "Smith"
}
]
}
Returned updated Customer resourcejson
{
"id": "{customerID}",
"version": 3,
"createdAt": "2022-01-09T15:32:56.130Z",
"lastModifiedAt": "2022-01-09T16:16:47.603Z",
"lastModifiedBy": {
"clientId": "{clientID}",
"isPlatformClient": false
},
"createdBy": {
"clientId": "{clientID}",
"isPlatformClient": false
},
"email": "getting-started@example.com",
"firstName": "John",
"lastName": "Smith",
"password": "l9vOLbrU19W4BBCrfDI8sknoTUe+Kegse2n5Zux1SIA=$U+egoGgBOTTYsD5MgL5wEdKvvui6bgNlt8H9+Wctx3A=",
"addresses": [],
"shippingAddressIds": [],
"billingAddressIds": [],
"isEmailVerified": false,
"stores": [],
"authenticationMode": "Password"
}

Find your Customer

If you don't know the {customerID}, you can search for Customers by querying the Customers endpoint with a where parameter.

In the Composable Commerce API, where uses a Query Predicate to specify filter criteria.

Finding a Customer by their email address

As the email of a Customer is unique, it is a dependable way to find a Customer.

The following example finds a Customer by their email address and returns the Customer resource:

In this example we use HTML URL encoding references. %3D is the encoding reference for = and %22 is the encoding reference for ".

Based on your method of making API calls, you may need to revert them.

GET https://api.{region}.commercetools.com/{projectKey}/customers/
?where=email%3D%22getting-started@example.com%22
Authorization: Bearer ${BEARER_TOKEN}
The result of searching for a Customer based on their email addressjson
{
"limit": 20,
"offset": 0,
"count": 1,
"total": 1,
"results": [
{
"id": "{customerID}",
"version": 3,
"createdAt": "2022-01-09T15:32:56.130Z",
"lastModifiedAt": "2022-01-09T16:16:47.603Z",
"lastModifiedBy": {
"clientId": "{clientID}",
"isPlatformClient": false
},
"createdBy": {
"clientId": "{clientID}",
"isPlatformClient": false
},
"email": "getting-started@example.com",
"firstName": "John",
"lastName": "Smith",
"password": "l9vOLbrU19W4BBCrfDI8sknoTUe+Kegse2n5Zux1SIA=$U+egoGgBOTTYsD5MgL5wEdKvvui6bgNlt8H9+Wctx3A=",
"addresses": [],
"shippingAddressIds": [],
"billingAddressIds": [],
"isEmailVerified": false,
"stores": [],
"authenticationMode": "Password"
}
]
}

If there is no Customer with the specified email address, then an empty query result is returned:

The result of searching for an email address that does not existjson
{
"limit": 20,
"offset": 0,
"count": 0,
"total": 0,
"results": []
}

Next steps

You should now feel confident creating, updating, and querying Customers.

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

For further practice in managing Customers, you could also try further update actions such as adding a date of birth, or an address.

The next step will be how to create, update, and query Products.