How to access the commercetools platform with curl?
If you want to try our the commercetools platform API one simple way is doing this with curl in your terminal window. You need to have a valid account on our commercetools platform in order to access it. If you don’t have an account yet sign up for a free trial as explained in our Getting Started tutorial.
- Get your access token
- Use API commands
- Retrieve published products
- Query for product variants with specific color
- Full-text search on product projections
- Search for products of a certain price
- Search for products in a certain price range
- Search for custom attribute values
- What’s next?
Before you can use the API you have to request for an OAuth token as described below:
Get your access token
Please open the ↗ Admin Center EU
(or ↗ Admin Center US
respectively) and go to the Developers Section.
curl request as it is from the Admin Center, paste it in your
console/terminal and execute the command. The command should look like below, but with your personal
client_secret and your
In response to the above command you’ll retrieve your access_token.
Use API commands
To get you started quickly we’ve selected the following calls for you.
Please be aware that you have to replace to following parameters with your project-specific values:
ACCESS_TOKEN= replace with your
access_token, something like this:
PROJECT_KEY= replace with your
project_keywhich can be found in the Admin Center -> Developers -> API Clients.
Please note that some examples (like full-text search) require that your product data have matching values.
Retrieve published products
At first, you want to retrieve your published products via the Products endpoint. For this we’ll use following command:
In the second step, you want to limit your results for your query. Just append
Now you want the whole data set, but sorted. We choose to sort it ascending by name. The respective query would be
sort=masterData.current.name.en asc, but we need to URL-encode the query, so that the whitespace will be replaced by the code
Curl can also encode the query with the
--data-urlencode parameter. When using the
--data-urlencode parameter the default method is POST so the
-G parameter is needed to set the request method to GET.
Query for product variants with specific color
To query products with a variant that contains a specific attribute
color, the following query can be used:
You probably found out, it’s not quite easy reading here. 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 Stock Keeping Unit (SKU) of the products in the query response only. Pretty cool, isn’t it?
Full-text search on product projections
You can send search requests either via GET or via POST.
The POST request is the better choice for a long list of parameters that had to be appended to the URL in case of GET requests. Instead the parameters are given in the request body encoded in ` application/x-www-form-urlencoded`.
In the example below we’ll search for products whose name contains the string ‘MB’ that we add as query parameter. We’ll use a different query URL now, surrounded by quotes this time, like so:
You will get the message, that a parameter is missing for the full text search, so we’ll add the language identifier
Let’s send the same search request as before, but this time via POST:
Search for products of a certain price
The Product Projection Search endpoint has some more features to filter results. For instance, we can easily get the variants which have a price of exactly 100.00 USD. The original statement would be
variants.price.centAmount:10000, but we need to URL-encode it, like so:
Search for products in a certain price range
Usually, you’re not searching for a specific price but more for a price range. The filter expression
range (2000 to 4000) is your friend to show all product variants with a price between 20.00 and 40.00 USD. URL-encoded it looks like this:
Search for custom attribute values
This works also for the attributes you’ve defined via product types. Let’s say, you’ve created a string attribute called
size. To search for the value
XL of this attribute, just use
To get clustered information about product attributes, you can add facets regarding their attributes. If you’d like to know, for example, the number of each size that is in your products list, e.g., 23 *
S, 34 *
M and 43 *
L, you’ll add following parameter to your curl command: