Guides
Builder API
Processor API
Getting Started
Overview
Account Setup
Creating your first discount
API Intro
Overview
Coupon Codes
Loyalty Schemes
Discount Types
Discount Interaction
Publishing Model
Tiered Actions
Currencies
Properties
Example Loyalty Scheme
Management Tooling
Discounts
Discount Conditions
Discount Actions
Discount Priorities
Expressions
Coupon Codes
Loyalty Schemes
Files
Properties
Currencies
Audit
commercetools integration
Builder API
Discount Types
Coupon Code Generation
Loyalty Schemes
Loyalty Discount Types
File Uploads
Expressions
Dates and Times
Discount Priorities
Discount Examples
Processor API
Request
Response
Commits
Dates and Times
Loyalty APIs
Line Item Apportioning

Management Tooling - commercetools integration

The Integrations section allows you to integrate a commercetools project with the Dovetech management tooling. Once configured, the expression builder will allow searching values in commercetools. This makes it easier to find and enter property values. The example below is for the Product Key property:

expression builder showing search

Prerequisites

Before creating the integration you will need to create an API Client in the commercetools Merchant Center (under Settings - Developer settings). This API Client needs "View" access for any commercetools API endpoints you want to use for the property search. The default property configuration when you create the integration uses the following permissions:

  • View Products
  • View Shipping Methods
  • View Customer Groups

Below is a screenshot from the commercetools Merchant Center when creating an API Client.

commercetools API Client Settings

Note, you only need to create permissions for the endpoints you will use. I.e. if you're only going to use search for products, then only give access for viewing products.

Save the credentials in the "Environment Variables (.env)" format or just keep the page open in the Merchant Center while you create the integration.

Creating the Integration

On the Integrations page, click the "Add integration" button and choose commercetools. You will be presented with the create commercetools integration page:

create commercetools integration page

Complete the API Client Settings fields using the API Client you created above. For example, if you download the credentials in the "Environment Variables (.env)" format, you will have settings similar to those below:

CTP_PROJECT_KEY=project-key
CTP_CLIENT_SECRET=client-secret
CTP_CLIENT_ID=client-id
CTP_AUTH_URL=https://auth.europe-west1.gcp.commercetools.com
CTP_API_URL=https://api.europe-west1.gcp.commercetools.com
CTP_SCOPES=view_customer_groups:project-key view_products:project-key view_shipping_methods:project-key

Using these details you should complete the form as follows:

  • Project Key: project-key
  • Region: europe-west1.gcp (make sure this includes the entire region - in this case it includes .gcp because the project is on Google Cloud)
  • Client ID: client-id
  • Client Secret: client-secret
  • Scopes: view_customer_groups:project-key view_products:project-key view_shipping_methods:project-key

The API URL and Auth URL fields are optional and are only required if your values are different from the following commercetools defaults:

  • API URL: https://api.[region].commercetools.com
  • Auth URL: https://auth.[region].commercetools.com

Once you have created the integration, you are redirect to the edit page.

Edit Page

Integration Property Search Configuration

On the edit page you can see the property configuration that was created by default:

default property configuration

You can remove any you don't need or add new ones not created by default. Each property listed will be configured to provide a search using the commercetools API.

Details on each field are below:

  • "Property" allows you to choose a property for which to configure search
  • "Data Source" allows you to choose a commercetools API endpoint to use for the search (see more details below)
  • "Data Source Property" is the property in the search response JSON to use as the property value
  • "Data Source Display Property" is the property in the search response JSON to use as the display value in the search results

The object-mapper library is used to get the property for each search result. This is to provide a flexible and generic way to get values from the search result JSON.

For example, below is a sample product result from the /product-projections/search API endpoint:

example product returned from commercetools search
  • The key value of the product is a top level property within the product. So to use that as the property value, you need to configure the "Data Source Property" to just be "key".
  • The English name of the product has a path of name -> en-GB in the JSON. So to use that as the display text in the search results, you need to configure the "Data Source Display Property" to be "name.en-GB"

See the Object Mapper documentation for more details.

Note, for simplicity of working with variants, we merge the masterVariant and any additional values in the variants array into a single variants array.

Data Sources

The list below provides details on the mapping between the data source display name and the commercetools API endpoint:

Diagnosing Issues

If you receive an error when searching for a property value then check the permissions of the API Client. You can manually make a request to any of the commercetools API endpoints to check permissions. Note, we cache the integration config used by the search for up to 15 minutes so ensure you test the search after this period when making any API Client changes.

For the Product projections search, the commercetools documentation mentions enabling the search feature: Activation of the feature. We haven't had to do this for any of our projects, but it's worth checking if you have issues.

Client Secret

The Client Secret is stored separately to the other settings in AWS Secrets Manager.

Once the client secret has been saved successfully, its value is not displayed again.