Commercetools

What this connector is

Commercetools is a headless, composable commerce platform. This connector wraps its GraphQL API — one endpoint (/{project-key}/graphql) that serves every resource: products, categories, carts, orders, customers, inventory, prices, discounts, quotes, and B2B business units.

It is generated from commercetools' published GraphQL schema — one action per Query or Mutation root field. commercetools' mcpServer* operations (its own MCP-server management, not commerce) and any @deprecated fields are left out.

Browse every action, grouped by resource, in the action reference. Each action page shows its default query, typed variables with an example, and the response fields.

Connecting

Every action uses a Commercetools connection. In commercetools' Merchant Center, go to Settings → Developer settings → API clients, create an API client, and copy its details before you close the dialog (the secret is shown only once). The connection asks for:

• Region — the host segment for your project, e.g. europe-west1.gcp, us-central1.gcp, australia-southeast1.gcp, eu-central-1.aws, us-east-2.aws. It's the part between api. / auth. and .commercetools.com in the URLs the Merchant Center shows you.
• Project key — your commercetools project key.
• Client ID and Client Secret — from the API client.
• Scopes — optional, space-separated. Defaults to manage_project:<project-key>; set granular scopes here instead if your API client is scoped down (e.g. manage_products:acme view_orders:acme).

The connector mints an OAuth2 client-credentials token from https://auth.<region>.commercetools.com/oauth/token, caches it, and refreshes it automatically shortly before it expires (commercetools tokens last ~2 days) — the same token lifecycle the Elastic Path connection uses. The token is sent as Authorization: Bearer <token>.

The GraphQL endpoint — https://api.<region>.commercetools.com/<project-key>/graphql — is filled in from the connection's region and project key automatically. Override the Endpoint field on an action only to point at a different project.

How the actions work

Each action wraps one GraphQL operation:

• GraphQL Query — the query/mutation document, pre-filled and fully editable. The generated selection set is nested up to 3 levels and omits fields that take their own arguments (localized text, expandable references, nested pagination) — edit it to add name(locale: "en-US"), expand a { typeId, id } reference, or select results { ... } on a list query.
• Variables — one multi-line field for the whole variables object, with the usual parameter picker to wire in values with {{<stepReference>.field.path}}. It is pre-filled with a skeleton of every declared argument. For update mutations the skeleton's actions array lists every possible update action in one object — replace it with an array where each element has exactly one update-action key (see "Update actions"). Once references resolve it must be valid JSON.
• Endpoint — your project's GraphQL URL (see above).
• Additional Headers, Forward All Headers — as on every connector.

If you edit the query to add or rename variables, keep Variables in sync — they are sent together as { query, variables }.

Reading the response

Every action's result is at {{<stepReference>.response...}} (see Step Reference): {{<stepReference>.response.status}}, {{<stepReference>.response.headers.<name>}}, and {{<stepReference>.response.data...}} for the body.

The body is the raw GraphQL HTTP response, so there are two levels of data:

• The operation result — {{<stepReference>.response.data.data.<fieldName>}}. A step named "Get Product" (reference getProduct) running the product query resolves the product at {{getProduct.response.data.data.product.id}}. A list query resolves as {{getProducts.response.data.data.products.results}} (an array) plus .total, .count, .offset.
• GraphQL errors — a top-level errors array (unknown field, missing scope, validation problem, stale version) fails the step. Details at {{<stepReference>.response.data.errors}} (each { message, path, locations, extensions }); extensions.code identifies the problem. Turn on Continue on Error to inspect the errors and branch instead of stopping.

commercetools does not use Shopify's userErrors pattern — a mutation either returns the resource under data.<mutationName> or reports the problem in errors.

Optimistic concurrency (version)

Every commercetools resource carries an integer version that increments on each change. Update and delete mutations require the current version:

mutation UpdateProduct($id: String!, $version: Long!, $actions: [ProductUpdateAction!]!) {
  updateProduct(id: $id, version: $version, actions: $actions) {
    id
    version
  }
}

Pass a stale version and the mutation fails with an error. Read the resource immediately before the mutation and pass {{getProduct.response.data.data.product.version}} so the two steps agree.

Update actions

commercetools has no PATCH-style partial update — every change is one or more update actions passed as an array. Each array element is an object with exactly one key, the action name, whose value is that action's parameters:

{
  "id": "a1b2c3d4-....",
  "version": 7,
  "actions": [
    { "changeName": { "name": { "en-US": "New name" }, "staged": false } },
    { "setDescription": { "description": { "en-US": "..." }, "staged": false } },
    { "publish": { "scope": "All" } }
  ]
}

The Variables skeleton collapses all the possible actions for a resource into one object so you can see what's available — delete the ones you don't need and split the rest into separate { ... } elements. commercetools' API reference lists every update action per resource (Products, Carts, Orders, Customers, …).

Identifiers, keys, and references

• id is a plain UUID (a1b2c3d4-e5f6-...), not a gid:// global id.
• Most resources also accept a user-defined key — many queries and mutations take either, e.g. product(id: "...") or product(key: "my-sku"), updateCategory(key: "...", version: ..., actions: [...]).
• References in responses come back as { "typeId": "product", "id": "..." }. To get the referenced object's own fields, expand the reference in the query — e.g. lineItems { productId name(locale:"en") variant { sku } } rather than just lineItems { productId }.

Localized text

LocalizedString fields (name, description, slug, metaTitle, …) either take a locale argument or return an array of { locale, value }. The generated selection set does not add locale: arguments, so edit the query: name(locale: "en-US") for a single string, or nameAllLocales { locale value } for every translation. On write, a localized value is a JSON object keyed by locale: { "en-US": "Hat", "de-DE": "Hut" }.

Pagination and filtering

List queries (products, orders, customers, categories, …) take:

• limit (default 20, max 500) and offset (max 10000) — or, for deep pagination, sort by id and use a where predicate on id instead of a large offset.
• sort — an array of strings, e.g. ["createdAt desc", "id asc"].
• where — a commercetools Query Predicate string, e.g. where: "masterData(current(masterVariant(sku = \"ABC-1\")))" or where: "orderState = \"Open\" and createdAt > \"2026-01-01T00:00:00.000Z\"".

Responses are { results, total, count, offset, exists } — not Relay-style edges/node. Add results { ... } to the query's selection set (the generator leaves it out because it's an argument-bearing connection).

Store and customer scope

• inStore(key: "uk") / inStores(keys: [...]) wrap store-scoped reads and writes — the fields you select inside them are the same, but limited to that store's carts, orders, customers, and product selections.
• me { ... } and the *My* mutations (createMyCart, updateMyCustomer, createMyOrderFromCart, …) are customer-scoped and need a customer's password-flow token, which a client-credentials connection cannot issue. Use the admin equivalents instead: customer / customers, cart / carts, createOrderFromCart, updateCustomer.

Common operations

• Publish a product — updateProduct with a { "publish": { "scope": "All" } } update action. Products have masterData { current { ... } staged { ... } }.
• Cart to order — createCart → updateCart (add line items, set addresses, apply discount codes) → createOrderFromCart.
• Sign up a customer — customerSignUp creates the customer and returns { customer, cartId }.
• Search — productProjectionSearch and productsSearch do full-text and faceted search.

Not sure which action?

Open the action reference and search or filter by resource (Product, Cart, Order, Customer, …). Action names are the GraphQL field names exactly. The most common actions:

• Products: product, products, createProduct, updateProduct, productProjectionSearch, createCategory
• Carts and orders: createCart, updateCart, createOrderFromCart, order, orders, updateOrder
• Customers and stock: customer, customers, customerSignUp, updateCustomer, inventoryEntries