Manage Customers with the 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:
| Placeholder | Replace with | From |
|---|---|---|
{projectKey} | project_key | your API Client |
{region} | your Region | Hosts |
${BEARER_TOKEN} | your access token | Make 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.
{"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:
POST https://api.{region}.commercetools.com/{projectKey}/customersAuthorization: Bearer ${BEARER_TOKEN}{"email": "getting-started@example.com","password": "examplePassword"}
{"customer": {"id": "{customerID}","version": 1,"createdAt": "2023-10-23T13:02:19.636Z","lastModifiedAt": "2023-10-23T13:02:19.636Z","lastModifiedBy": {"clientId": "{clientID}","isPlatformClient": false},"createdBy": {"clientId": "{clientID}","isPlatformClient": false},"email": "getting-started@example.com","password": "****gSs=","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.
GET https://api.{region}.commercetools.com/{projectKey}/customers/{customerID}Authorization: Bearer ${BEARER_TOKEN}
{"customer": {"id": "{customerID}","version": 1,"createdAt": "2023-10-23T13:02:19.636Z","lastModifiedAt": "2023-10-23T13:02:19.636Z","lastModifiedBy": {"clientId": "{clientID}","isPlatformClient": false},"createdBy": {"clientId": "{clientID}","isPlatformClient": false},"email": "getting-started@example.com","password": "****gSs=","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.
{"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:
POST https://api.{region}.commercetools.com/{projectKey}/customers/{customerID}Authorization: Bearer ${BEARER_TOKEN}{"version": 1,"actions": [{"action": "setFirstName","firstName": "John"},{"action": "setLastName","lastName": "Smith"}]}
{"id": "{customerID}","version": 3,"createdAt": "2023-10-23T13:02:19.636Z","lastModifiedAt": "2023-10-23T13:06:24.629Z","lastModifiedBy": {"clientId": "{clientID}","isPlatformClient": false},"createdBy": {"clientId": "{clientID}","isPlatformClient": false},"email": "getting-started@example.com","firstName": "John","lastName": "Smith","password": "****gSs=","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%22Authorization: Bearer ${BEARER_TOKEN}
{"limit": 20,"offset": 0,"count": 1,"total": 1,"results": [{"id": "{customerID}","version": 3,"createdAt": "2023-10-23T13:02:19.636Z","lastModifiedAt": "2023-10-23T13:06:24.629Z","lastModifiedBy": {"clientId": "{clientID}","isPlatformClient": false},"createdBy": {"clientId": "{clientID}","isPlatformClient": false},"email": "getting-started@example.com","firstName": "John","lastName": "Smith","password": "****gSs=","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:
{"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.