Accessing with cURL Cheatsheet

Get your access token

If not done yet, please open the Merchant Center, 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 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.
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: shbjExwvfigNZlvrkS-V0KZyOkTRCaTK
• PROJECT_KEY = replace with your project_key.

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.{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 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 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, 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.
Please find the full API documentation on the developer website.