n8n-nodes-commercetools

A custom n8n community node for integrating with commercetools. Provides full API coverage for Products, Customers, Carts, and Orders — plus a webhook trigger node with optional AWS SQS + Lambda or GCP Pub/Sub + Cloud Functions buffering for reliable event delivery.

Operations are auto-generated from the official commercetools Postman collection and kept in sync automatically via a daily GitHub Actions workflow.

Table of Contents

• Highlights
• Quick Start
• Nodes
  • commercetools (Action Node)
  • commercetools Trigger
• Credentials
• Development & Scripts
• Auto-Update Pipeline
• Error Handling & Troubleshooting
• Changelog
• License

Highlights

• Full CRUD coverage for Products, Customers, Carts, and Orders
• Auto-generated operations from the official Postman collection — always in sync
• Product image upload: downloads from a URL, posts raw binary to commercetools
• Product and Order search with structured query, sort, limit, and offset fields
• Update action UI builder — per-action typed field editors, no raw JSON required
• Native commercetools webhook subscriptions
• Optional AWS SQS + Lambda event buffering — fully auto-provisioned
• Optional GCP Pub/Sub + Cloud Functions event buffering — fully auto-provisioned
• All cloud infrastructure is automatically torn down on workflow deactivation

Quick Start

npm install
npm run dev

Nodes

commercetools (Action Node)

Select a Resource and Operation to interact with the commercetools API. All operations and their input fields are generated at build time from the official Postman collection.

Resources

How field generation works

Each operation type generates a different set of UI fields:

Update actions

The update action builder exposes every action type as a labelled group with its own typed fields. For example, adding a setName action shows a localised JSON field for name; adding addVariant shows typed fields for sku, prices, and so on.

Alternatively, paste a raw JSON array directly into Actions (JSON) to bypass the UI builder. When Actions (JSON) is non-empty it takes precedence.

Search operations (Products & Orders)

The commercetools Search API accepts a SearchRequest body. The node exposes these fields:

Note: Sending query: { and: [] } is rejected by commercetools with "exhausted input". Leaving Query › And empty omits the field entirely, which returns all results.

Upload Product image

commercetools requires raw binary image bytes in the request body with Content-Type: image/jpeg, image/png, or image/gif. It does not accept a JSON body — sending one returns "Unsupported Content-Type: application/json".

The node handles this transparently:

1. Downloads the image from the URL you provide using helpers.request()
2. Derives the Content-Type from the file extension (.jpg/.jpeg → image/jpeg, .png → image/png, .gif → image/gif, unknown → image/jpeg)
3. POSTs the raw buffer to commercetools with the correct Content-Type

commercetools Trigger

Listens for real-time commercetools events via webhook subscription. On activation, the node registers a commercetools subscription pointing to the n8n webhook URL. On deactivation, the subscription and any provisioned cloud infrastructure are automatically deleted.

Setup

1. Add the commercetools Trigger node to your workflow
2. Select one or more event types from the Events dropdown
3. Configure commercetools credentials (and optionally AWS or GCP sub-fields)
4. Activate the workflow

Supported event types

Product — created, published, unpublished, deleted, variant added/deleted, price added/changed/removed, image added, added/removed from category, state transition, slug and custom field updates

Customer — created, deleted, email verified/changed, password updated, address updates, custom fields and types

Category — created, slug changed

Order — created, deleted, imported, state transitions, customer updates, shipping and billing updates, line item changes, payments and deliveries, discount code updates, custom fields

Cart — cart created (change notification)

Subscription routing

Events are routed to the correct commercetools subscription arrays automatically using the generated event registry (produced by generateCtpRegistry.ts from the @commercetools/platform-sdk type declarations):

• message events → messages[] grouped by resourceTypeId with types[]
• change events → changes[] grouped by resourceTypeId

Empty arrays are never sent — commercetools rejects subscriptions that contain them.

Config change detection

A hash of { events, hasAWS, hasGCP } is stored in workflow static data. When checkExists runs and detects a hash mismatch (events changed, credentials changed), it automatically tears down the old subscription and infrastructure before create rebuilds everything.

AWS SQS + Lambda (optional)

When awsAccessKeyId and awsSecretAccessKey are present in the credential, the node automatically provisions:

• SQS queue (14-day retention, long polling)
• Lambda function (Node.js) with WEBHOOK_URL env var
• IAM role with SQS receive/delete and CloudWatch Logs policies
• Event source mapping (SQS → Lambda, batch size 10)

The Lambda forwards each SQS message to the n8n webhook URL as a POST request. All resources are deleted when the trigger is deactivated or its configuration changes.

Requirements:

• Publicly reachable n8n webhook URL
• AWS credentials with permissions for: SQS, Lambda, IAM, CloudWatch Logs

⚠️ AWS costs may apply.

GCP Pub/Sub + Cloud Functions (optional)

When serviceAccountJson is present in the credential, the node automatically provisions:

• Pub/Sub topic with roles/pubsub.publisher granted to the commercetools service account
• Cloud Storage bucket for function source
• Cloud Function Gen2 (Node.js 20, Eventarc trigger, RETRY_POLICY_RETRY)
• All required GCP APIs are enabled automatically (cloudfunctions, cloudbuild, artifactregistry, run, eventarc)

Event flow:

commercetools → Pub/Sub topic → Cloud Function (Gen2) → n8n webhook

All resources are deleted when the trigger is deactivated or reconfigured.

Requirements:

• Billing-enabled GCP project
• Publicly reachable n8n webhook URL
• Service account with: Pub/Sub Admin, Cloud Functions Admin, Storage Admin, IAM Policy Editor, Service Usage Admin

⚠️ GCP costs may apply.

Credentials

commercetools OAuth2 (required for both nodes)

The OAuth2 token URL is built automatically from the selected region — no manual URL entry needed.

Selecting an Event Provider reveals the relevant sub-fields:

AWS sub-fields

GCP sub-fields

Important: Use the Service Account JSON field — paste the complete downloaded key file. Do not split it into separate clientEmail / privateKey fields. n8n's encrypted credential storage mangles PEM line breaks in individual fields; the JSON field is treated as opaque text and preserves the key exactly.

Development & Scripts

# Install dependencies
npm install

# Start n8n in dev mode with this node loaded
npm run dev

# Regenerate operations from the latest Postman collection + rebuild event registry
npm run generate

# Build
npm run build

# Build and watch
npm run build:watch

# Lint
npm run lint
npm run lint:fix

Code generation pipeline

scripts/generate.ts                       (entry point: npm run generate)
│
├── parseCollection.ts
│     Downloads Postman collection.json → ParsedOperation[]
│     Detects per operation:
│       isSearch        POST .../search
│       isImageUpload   POST .../images
│       requiresId      URL contains {{...ID...}}
│       requiresKey     URL contains key={{...}}
│       keyPlaceholder  exact variable name from URL (e.g. product-key)
│       queryParams     all query params including disabled ones
│       bodyFields      extracted from Postman body.raw JSON
│       actionBodyFields fields from inside actions[0]
│
├── generateProperties.ts
│     ParsedOperation[] → INodeProperties[]
│     Emits in order:
│       1.  Resource dropdown
│       2.  Operation dropdowns (one per resource folder)
│       3.  Resource ID / Key / custom path param fields
│       4.  Version field  (Update + Delete ops)
│       5.  Actions (JSON) field
│       6.  Actions (UI) fixedCollection  (one option group per action type)
│       7.  Create body fields
│       8.  Misc POST body fields  (excludes isSearch + isImageUpload)
│       9.  Search body fields     (query.and, sort, limit, offset)
│       10. Image upload fields    (imageUrl + variant/sku/staged/filename
│                                   sourced from op.queryParams)
│       11. Query param Filters collection  (GET / HEAD ops only)
│
├── → nodes/Commercetools/generated/properties.ts
├── → nodes/Commercetools/generated/operations.json
│
├── generateCtpRegistry.ts
│     Parses @commercetools/platform-sdk .d.ts via TypeScript compiler API
│     Extracts: *MessagePayload type literals,
│               MessageSubscriptionResourceTypeId values,
│               ChangeSubscriptionResourceTypeId values
│     Filters to allowedResources: [product, customer, cart, order]
│     → nodes/Commercetools/generated/ctp-event-registry.json
│
└── generateSubscriptionProperties.ts
      Reads ctp-event-registry.json
      → nodes/Commercetools/generated/subscription.properties.ts
          exports subscriptionEvents[]  (name, value, resourceTypeId,
                                         subscriptionType, description)
          exports triggerProperties[]   (the Events multiOptions field)

Generated files are committed to the repository. The built node works without running generate unless the Postman collection or SDK has changed.

Auto-Update Pipeline

.github/workflows/auto-update.yml runs on three triggers:

• Daily at 06:00 UTC — checks if the Postman collection has changed
• Push to main — always regenerates and rebuilds
• Manual dispatch — via GitHub Actions UI

Steps: download latest collection → diff against committed version → if changed (or push/manual): npm run generate → npm run build → commit updated collection.json, generated files, and dist/.

New API endpoints and fields appear in the node automatically without manual development.

Error Handling & Troubleshooting

Changelog

License

MIT