How to access the commercetools Composable Commerce API with cURL?
If you want to try the Composable Commerce APIs, one simple way is doing this with cURL in your terminal window.
You need to have a valid account on commercetools Composable Commerce to access it. If you don't have one yet, sign up for a 60 day free trial.
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, open the Merchant Center, go to the
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:
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
client_id, client_secret and project_key are replaced with your personal credentials:$curl https://auth.{region}.commercetools.com/oauth/token --basic --user "{client_id}:{client_secret}" -X POST -d "grant_type=client_credentials&scope=manage_project:{projectKey}"
In response to this command you'll retrieve your access_token.
Use API commands
To get you started fast we've selected the following calls for you.
You have to replace to following parameters with your project-specific values:
You have to replace to following parameters with your project-specific values:
ACCESS_TOKEN= replace with youraccess_token, something like this:shbjExwvfigNZlvrkS-V0KZyOkTRCaTKPROJECT_KEY= replace with yourproject_key.
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:
$curl -sH "Authorization: Bearer ACCESS_TOKEN" https://api.{region}.commercetools.com/PROJECT_KEY/products
Limit results
In the second step, you want to limit your results for your query. Just append
?limit=1:$curl -sH "Authorization: Bearer ACCESS_TOKEN" https://api.{region}.commercetools.com/PROJECT_KEY/products?limit=1
Sort results
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 %20:$curl -sH "Authorization: Bearer ACCESS_TOKEN" https://api.{region}.commercetools.com/PROJECT_KEY/products?sort=masterData.current.name.en%20asc
URL-encoding
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.$curl -sH "Authorization: Bearer ACCESS_TOKEN" -G --data-urlencode "sort=masterData.current.name.en asc" https://api.{region}.commercetools.com/PROJECT_KEY/products
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: $curl -sH "Authorization: Bearer ACCESS_TOKEN" -G --data-urlencode "where:masterData(current(variants(attributes(name="color" and value="blue"))))" https://api.{region}.commercetools.com/PROJECT_KEY/products
Process response
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?
| jq . | grep \"sku
Full-text search on product projections
Now we want to use the Product Projection Search endpoint instead that delivers ProductProjections a lot quicker than the Products endpoint.
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
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:
$curl -sH "Authorization: Bearer ACCESS_TOKEN" "https://api.{region}.commercetools.com/PROJECT_KEY/product-projections/search?text=MB"
You will get the message, that a parameter is missing for the full text search, so we'll add the language identifier
en:$curl -sH "Authorization: Bearer ACCESS_TOKEN" https://api.{region}.commercetools.com/PROJECT_KEY/product-projections/search?text.en=MB
Let's send the same search request as before, but this time via POST:
$curl -X POST https://api.{region}.commercetools.com/PROJECT_KEY/product-projections/search -H "Authorization: Bearer ACCESS_TOKEN" -H "Content-Type: application/x-www-form-urlencoded" --data-urlencode "text="MB""
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: &filter=variants.price.centAmount%3A10000
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: &filter=variants.price.centAmount%3Arange%282 000%20to%204000%29
Search for 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 variants.attributes.size:"XL": &filter=variants.attributes.size%3A%22XL%22
Add facets
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, for example, 23 _
S, 34 _ M and 43 * L, you'll add following parameter to your cURL command: &facet=variants.attributes.size
What's next?
Do you want more information? Checkout the API tutorial.
Find the full API documentation on the developer website.
Find the full API documentation on the developer website.