Connect your commercetools project to Clione

Plans: Starter ✓ · Growth ✓ · Pro ✓ · Agency ✓

You need: permission to create an API client in the commercetools Merchant Center, and the key of the distribution channel, store or brand attribute that identifies this store's products.

commercetools is different from the other platforms in one way that changes everything below: it has no storefront. Shopify, BigCommerce and WooCommerce all render pages, so Clione can publish straight into them. With commercetools, your own front end renders your pages, and Clione writes its signals onto your products as attributes for that front end to read.

So connecting has two sides. Yours is this page. Your developers' side is the render contract — and until they ship it, Clione's work does not appear on your site.

What Clione does and does not do with a commercetools project today

Reads your catalog	✅ Published product projections and categories, in every locale your project has
Enriches with AI	✅ The same pipeline as every other platform
Writes signals back to your project	❌ Not yet — in development
Your front end renders them	❌ Not until your developers add the contract

Nothing Clione generates reaches your site yet. We say it plainly rather than let you find out: connect, sync and enrich work now, and you can see everything Clione produces, but it stays in Clione until the write side and your front end are both in place.

Step 1 — Create an API client

In the Merchant Center: Settings → Developer settings → Create new API client.

Give it only the two scopes Clione needs:

• view_products — read your catalog
• manage_products — write the Clione attributes back (needed later; grant it now so you do not repeat this step)

Copy the project key, client ID and client secret. The secret is shown once.

Which region?

Your project lives in one region, and a client from another region cannot reach it. The Merchant Center URL tells you: the region appears in the API URL on the same screen as the credentials. Pick the matching one in Clione — there is no default, because each region is a different continent's data.

Step 2 — Know which products are this store's

This is the step that matters most, and it has no safe default.

One commercetools project often holds several brands. Clione treats each brand as its own store, so it has to be told which products belong to the one you are adding. Give one of these:

What you give	When to use it
Distribution channel key	Your brands are separated by channel
Store key	Your project uses commercetools Stores
Brand attribute name and value	Your products carry a brand attribute, e.g. brand = Champion

If you give more than one, Clione uses the first in that order and tells you which it used.

A brand attribute needs its value

The attribute name on its own is not a selector: every product that has the field would match, which is the whole project. Clione refuses the pair when the value is missing.

Clione will not connect without one. A project read with no selector returns every brand, and the result would not be an error — it would be another brand's products in this store's dashboard, enriched with this store's credits. So the connection is refused instead.

Step 3 — Add the store in Clione

+ Add website → commercetools, then fill in the project key, the region, the client ID and secret, and the selector from Step 2. Clione checks all of it with one API call, which is the only way to tell a wrong region from a wrong secret.

Access is limited while this is new

commercetools is in its first run, so connecting is enabled per organisation. If the form refuses with "Connecting a commercetools project is limited", ask Clione support to enable it for yours.

Step 4 — Sync, then give your developers the contract

Sync reads your catalog; enrichment writes nothing to your project. When your products are enriched, send your developers to the render contract. It names the four attributes and ships a Next.js reference they can copy.

Until that page is implemented on your side, your pages carry no Clione signals, however much you enrich.

Requirements and limits

• The API client's scopes must include view_products.
• Clione reads published products only (staged=false): a draft nobody has published is not something a search engine can see either.
• Catalogs are read up to 10,000 products per sync pass today.
• One selector per store, and several Clione stores may share one project.

Troubleshooting

"Connecting a commercetools project is limited" — the per-organisation gate above. Ask support.

The store connects, and the catalog is empty. Almost always the selector: it is valid but matches nothing. Clione logs how many products it read and how many it kept, so support can tell you "0 kept out of 12,480" rather than guessing. Check the channel key, store key or attribute value against the project.

A wrong region looks like a wrong secret. Both fail the same way at the API. Check the region first — it is the easier of the two to get wrong.