Commercetools

Overview

The commercetools app allows editors to select a product or a product category from their commercetools account and reference it inside of Contentful entries.

Requirements

To use this app, you will need:

An account with commercetools.
A content type with a field of type Short text

Usage

Step 1: Configure your commercetools project

Before installing the app, you will need to configure your commercetools project. Create a new commercetools API client to acquire credentials that you can use with the app by following these steps on the commercetools website:

Log in to your account at the commercetools Merchant Center and select your project.
On the sidebar click on Settings > Developer settings > Create new API client.
Select Read only client from the scope presets dropdown and click the "Create client" button.
Store the generated client ID, client secret, API and Auth endpoints as you will need them for the app installation.

The commercetools app uses the Product Projection Search API endpoint to search for products. In order to utilize this API endpoint, you will need to turn on indexing within your project.

Log in to your account at the commercetools Merchant Center and select your project.
On the sidebar click on Settings > Project settings > Storefront search.
Enable the index status toggle under Indexing.

Step 2: Install commercetools app in Contentful

To install this app:

Fill in the credentials and endpoints in the commercetools installation screen.

Select all fields for which you would like to install the commercetools app from the list of available fields. For each field, select the picker widget you would like to enable, depending on whether you would like to select a product or a product category.
Click on Install.

This will modify the fields in the selected content types and change their appearance to use the commercetools app.

Step 3: Use the picker to select a product or a product category from commercetools

To reference commercetools a product or product category from your Contentful entries:

Navigate to the Content page.
Select or create a new entry of the content type for which you installed the app.
Find the field and click on "Select product" or "Select Category".
Scroll through the available product or category pages or search for a specific item by name or SKU for products and name or slug for categories and save your selection.
1. When searching for products by SKU, check the "Search only by SKU" option to optimize your search results.
2. When searching for categories, you can search by name, slug, or key, but it has to be an exact match (full text search is not supported).
Your selection should now appear like this:

Step 4: Enable Custom external references

To deliver commercetools data using the Contentful GraphQL API you must first enable the Custom external references feature by selecting the Resolve content on delivery check box in the field editor of your desired content type.

To enable the Resolve content on delivery check box:

Log in to the Contentful web app.
Navigate to the “Content model” tab and select the content type with the commercetools app field setup.
On the field used with the commercetools app, click Edit. The field editor is displayed.
In the “Appearance” section, under “Choose how this field should be displayed”, select commercetools.
Select the Resolve content on delivery check box.
Click Confirm.
Save your changes.

The commercetools content will be available through the Contentful GraphQL API via the name of the field configured with the commercetools app appended with _data:

External references with commercetools

query { topicProduct(id: "ENTRY_ID") { sys { id spaceId } thirdPartyReference thirdPartyReference_data { masterData { current { name(locale: "en-US") } } } } }

FAQ

What is the difference between the product picker and the category picker in the configuration screen?

Depending on which picker you choose, you will be presented with a different widget in the entry editor. The product picker allows you to select a product from commercetools and persist its SKU. The category picker allows you to select a product category and persist its ID.

What is the difference between installing the app for a field of type Short text vs Short text, list?

When the app is installed for fields of type "Short text" the SKU picker widget will allow you select a single SKU. For fields of type "Short text, list" the widget will allow you to select multiple SKUs.

How can I query the commercetools API for the SKUs I saved in my Contentful entries?

To fetch the data for the products corresponding to the SKUs you have selected and saved in your Contentful entries, you will need to query the Product Projection Search API endpoint, passing your SKUs in the payload.