Curl cheatsheet

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.

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.
Copy the 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_id, client_secret and your project_key:

$curl https://{client_id}:{client_secret}@auth.sphere.io/oauth/token -X POST -d "grant_type=client_credentials&scope=manage_project:{project_key}"

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:

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:

$curl -sH "Authorization: Bearer ACCESS_TOKEN" https://api.sphere.io/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.sphere.io/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.sphere.io/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.sphere.io/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.sphere.io/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 ` 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.sphere.io/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.sphere.io/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.sphere.io/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%282000%20to%204000%29

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 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, e.g., 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 our API tutorial.
Please find the full API documentation on our developer website.

comments powered by Disqus