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 Create client.
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. To utilize this API endpoint, you must turn on indexing within your project.
Log in to your account at the commercetools Merchant Center and select your project.
In the sidebar, click 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 Install.
This modifies the fields in the selected content types and changes their appearance so they can 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 tab.
Select an existing entry or create a new one of the content type for which you installed the app.
Go the field for which the app is installed and click either Select a product or Select a 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.
When searching for products by SKU, check the "Search only by SKU" option to optimize your search results.
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 is displayed as follows:
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.