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.
Before you can use the API you have to request for an OAuth token as described below:
Get your access token
If not done yet, please open the ↗ Merchant Center EU
(or ↗ Merchant Center US
respectively), go to the
Developer Settings Section and create an API client with the scopes you would like to give the client as described in the Getting Started Guide.
After successful creation of the API client you’ll find a section on the page that shows the cURL command as you can use it on your command line interpreter. You can copy this command to your clipboard easily:
The request should look like below, the
project_key are replaced with your personal credentials:
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
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: