This article walks through the first-time setup of the commercetools integration on iPaaS.com: obtaining API client credentials from commercetools, subscribing to the integration, entering the connection settings, and verifying that data actually moves.
For a field-by-field reference of every subscription setting after installation, see Connections and Settings. For the commercetools endpoints this integration calls, see API Endpoints.
Before You Begin
Confirm your commercetools project region
This is a hard prerequisite. Check it before you do anything else.
commercetools hosts projects in several cloud regions across Google Cloud and AWS, and it operates a separate authorization host for each one. Its documentation instructs clients to "use the authorization URL according to the Region your Project is located in", and publishes five such hosts — North America (Google Cloud, Iowa), North America (AWS, Ohio), Europe (Google Cloud, Belgium), Europe (AWS, Frankfurt) and Australia (Google Cloud, Sydney). See commercetools' Authorization documentation (retrieved 2026-07-20).
At the time this documentation was written, this integration authenticates against the North America Google Cloud us-central1 host only, and does not select the host that matches your project. This is a documented commercetools requirement the integration does not currently meet. If your commercetools project is hosted in any of the other four regions, the integration cannot obtain an access token, and no combination of API Url, Client_Id, Client_Secret, or Scope values will make it authenticate.
You can confirm your region from the API Url and Auth URL shown on your API client details page in commercetools. If they do not contain us-central1.gcp, stop here and contact iPaaS.com Support before subscribing. This constraint is also recorded in Known Limitations.
Obtain commercetools API client credentials
Creating an API client in commercetools produces a set of credentials that are displayed once. Copy them before leaving the page — commercetools does not display the client secret again, and a lost secret means creating a new API client. See commercetools' own documentation for the full procedure: Creating an API Client (retrieved 2026-07-20).
Log in to the commercetools Merchant Center.
Choose your project.
On the Developer settings page, choose the API clients tab.
Click Create new API client.
On the New API client page, enter a Name that identifies this client as the iPaaS.com integration.
Select the Scopes for the API client. The integration reads and writes products, product types, categories, channels, inventory, customers, orders, payments, and tax categories, so the API client needs manage-level access to those resources. The simplest supported choice is the Admin client template, which grants
manage_projectacross the project.
Click Create API client. commercetools displays the API Client Details page.
Copy and store the following values. You will need them when you configure the subscription:
client_id
client_secret
scope
api_url
auth_url
project_key
If you want a non-production environment, isolate it with a separate commercetools project (still in the us-central1.gcp region) rather than with a different host. Create the second project, create an API client within it, and install a second iPaaS.com subscription pointed at that project. The host stays the same for both; only the project key portion of the API Url differs.
Installation Instructions for Integration Setup
Go to Subscriptions and click Search Certified Integration Marketplace.
Click the commercetools integration tile.
Click the Subscribe button, then enter the Name of the subscription and select a Version. The name must be unique within the company where the subscription is created.
Format: [Product Name] - [Environment/Purpose]
Example: commercetools - Production
Example: commercetools - Staging Catalog
Select Create Default Mappings (recommended). This installs the shipped mapping collections so the subscription is functional out of the box. If you clear this checkbox, no mapping collections are created and you must build every collection, mapping, and filter yourself before any data can transfer.
Enter the connection settings retrieved from commercetools. Each is required. See Authentication Configuration below for exactly where each value comes from, and Connections and Settings for the field-by-field reference.
API Url
Client_Id
Client_Secret
Scope
Review the throttle and concurrency settings. These are platform settings that arrive pre-populated; see Operational Configuration below before changing them.
Click Apply to save your subscription settings.
If you accepted Create Default Mappings
The default mappings are a working starting point, not a finished configuration. Several of them ship with example values that you are expected to replace during implementation. These are intentional examples, not defects — but they must be replaced before you run production data.
The most important ones:
The customer password is a shipped example value. Because it is a static value, an unmodified default configuration would assign the same password to every customer created in commercetools. Replace this mapping before transferring real customers.
The product type mapping resolves commercetools product type identifiers that are specific to the commercetools project that produced the defaults. They will not match your project. Repoint that lookup translation at your own product types.
Several other mappings carry example or development values that need to be repointed at your own data.
The full list, with the collection and field for each, is in Known Limitations under Placeholder Values to Replace Before Go-Live. Work through that list before enabling any mapping collection for production use.
Authentication Configuration
The commercetools integration authenticates with OAuth 2.0 using the client credentials grant. The Client_Id and Client_Secret are exchanged for an access token, and that token is used to authorize every subsequent call to your commercetools project through the API Url. There is no interactive consent step and no redirect URL — you enter the four values below and the integration handles the token exchange.
All four values come from the same commercetools API Client Details page described in Before You Begin. Each is also documented as a subscription setting in Connections and Settings.
API Url
Credential Name: API Url
Location: commercetools Merchant Center > Settings > Developer settings > API clients > your API client > API URL
Description: The base address of your commercetools project's HTTP API. It includes your project key, which is how the integration knows which project to read from and write to. Enter it exactly as commercetools displays it, with no trailing slash.
The value has this shape:
https://api.us-central1.gcp.commercetools.com/<your-project-key>
Client_Id
Credential Name: Client_Id
Location: commercetools Merchant Center > Settings > Developer settings > API clients > your API client > client_id
Description: The public identifier of the API client. It identifies the integration to commercetools during the token exchange.
Client_Secret
Credential Name: Client_Secret
Location: commercetools Merchant Center > Settings > Developer settings > API clients > your API client > client_secret
Description: The secret paired with the Client_Id. It authenticates the token request. commercetools displays it only once, on the page shown immediately after the client is created.
Scope
Credential Name: Scope
Location: commercetools Merchant Center > Settings > Developer settings > API clients > your API client > scope
Description: The permission set requested when the access token is issued. It must include your project key. An Admin client produces a scope of this shape:
manage_project:<your-project-key>
Important Notes
The client secret is shown once. If you navigate away from the API Client Details page without copying it, you cannot recover it. Create a new API client and use its credentials instead.
The API Url must contain the project key. The integration issues resource paths relative to whatever you enter here and does not add a project key of its own. An API Url that stops at the host will produce authorization or not-found failures on every transfer.
The scope must match the API Url's project. A token scoped to a different project key authenticates successfully but is rejected on every resource call.
The scope must be broad enough for the collections you enable. The integration reads and writes products, product types, product attributes, categories, channels, inventory, customers, orders, payments, and tax categories. A narrowly scoped client will authenticate and then fail on the first call to a resource it was not granted.
There is no API key setting. Earlier versions of this article referred to an API Key field; no such setting exists. The four values above are the complete set.
A stored access token is not renewed on expiry. The integration acquires an access token and stores it, and it requests a new one only when no token is stored — it does not check whether a stored token has expired. If a stored token does expire, calls can begin failing with authorization errors even though the credentials on the subscription are correct and unchanged. Watch Dashboard / Integration Monitoring / Error Logs for authorization failures that appear without any credential change, and contact iPaaS.com Support at support@ipaas.com if they persist.
Rotating the secret in commercetools breaks the subscription immediately. If you delete or regenerate the API client, update Client_Id and Client_Secret on the subscription in the same maintenance window.
Saving the settings does not prove they are correct. The subscription reports a successful connection whether or not the credentials work. See Post-Installation Verification — an actual data transfer is the only reliable test.
Operational Configuration
These settings are managed by the iPaaS.com platform rather than by the commercetools integration itself, and they arrive pre-populated when the subscription is created. Most subscribers never need to change them. Each is also described in Connections and Settings.
API Throttle Limit and API Throttle Seconds
Purpose: Together these cap how many calls the subscription may issue to commercetools in a rolling time window, so a large catalog load does not saturate your commercetools project or trip its platform rate limits.
API Throttle Limit is the number of calls permitted per window.
API Throttle Seconds is the length of that window in seconds.
Example: a limit of 500 over 60 seconds allows up to 500 commercetools calls per minute; the 501st waits for the window to roll.
Recommended values for API Throttle Limit:
Initial Setup: 5 — deliberately slow, so mapping mistakes surface on a handful of records instead of thousands.
Ongoing Operations: 500
High Volume: 500
API Throttle Limit (To iPaaS) and API Throttle Seconds (To iPaaS) apply the same cap to the iPaaS.com side of the transfer. Both field names are reproduced exactly as they appear on the subscription settings page.
These fields arrive pre-populated, and the values supplied are not necessarily the figures shown above. The recommendations here are workable operating values for a new installation, not a statement of what your subscription ships with. Read the current values on your own subscription before changing anything.
commercetools applies its own rate limits independently of these settings, and this integration does not automatically reschedule or resume a transfer that commercetools throttles. If you see rate-limit failures, lower API Throttle Limit and re-run the affected transfer manually rather than expecting it to recover on its own. See commercetools' Limits documentation (retrieved 2026-07-20) for the platform's current behavior.
Concurrent Connections
Purpose: Caps how many transfers the subscription runs against commercetools at the same time. Lower values trade throughput for a gentler load on your commercetools project.
Pre-populated when the subscription is created; check the value on your own subscription.
Example: set to 2 during an initial catalog load and the subscription runs at most two transfers side by side, making failures far easier to attribute to a specific record.
Recommended values:
Initial Setup: 2
Ongoing Operations: 10
High Volume: 10
Concurrent Batch Executions
Purpose: On integrations that split work into batches, this caps how many batches run at once. At the time this documentation was written, changing this value has no observable effect on how the commercetools integration processes data. Leave it as supplied.
Pre-populated when the subscription is created. Because the setting does not affect transfer behavior, the value it arrives with does not matter; this field is also described in Connections and Settings.
Additional Configuration Options
The commercetools integration adds no optional subscription settings of its own beyond the four required credentials and the platform throttle and concurrency settings above. Configuration after installation happens in the mapping collections rather than in subscription settings — see Connections and Settings for the full settings reference, and Known Limitations for behavior you should account for before go-live.
Post-Installation Verification
Do not treat a successful connection test as proof that your credentials are correct. The subscription reports a successful connection regardless of the values you entered, so an incorrect API Url, Client_Id, Client_Secret, or Scope — each defined in Connections and Settings — will not surface at save time. It surfaces as an authorization failure on the first real transfer. The verification below is built around performing an actual transfer for that reason.
Connection Test
Confirm the subscription saved with all four settings populated and no typographical errors — in particular that API Url ends with your project key and Scope names the same project key.
Confirm the API client still exists in commercetools and has not been deleted or regenerated since you copied its credentials.
Proceed directly to the Data Sync Test. There is no connection check that meaningfully validates these credentials.
Data Sync Test
Choose one low-risk mapping collection to test first — a small customer or category set is a good choice.
Constrain it. Apply a mapping filter, or work in a commercetools project that contains only test data, so a mapping error cannot touch production records.
Run a Manual Sync on that collection.
Open Dashboard / Integration Monitoring / Error Logs and review the result of that run.
Authorization failures indicate a wrong credential, a scope that does not cover the resource, or a commercetools project outside the
us-central1.gcpregion.Validation failures generally indicate a mapping that is unmapped or still carries a shipped example value.
Confirm the records arrived on the receiving side with the values you expected — not merely that the run completed.
Repeat for one collection in the other direction so both inbound and outbound paths are exercised.
Data arriving into iPaaS.com from commercetools is retrieved by polling and by Manual Sync. The integration does not register commercetools webhooks, so do not expect a change in commercetools to appear in iPaaS.com the instant it is made.
Functionality Test
Run one end-to-end business process against test data — for example, create a record in the source system, transfer it, and confirm it appears correctly in the destination.
Update that same record at the source and re-run the transfer, then confirm the update applied as expected. Pay particular attention to fields you did not map: on some collections an unmapped field is written as empty rather than left alone, which is covered in Known Limitations.
Review the run in Dashboard / Integration Monitoring / Error Logs. Error Logs is the reliable surface for confirming success or failure. The Activity Tracker gives a useful overall activity trail, but some failed calls are currently recorded there with a completed status, so a clean-looking Activity Tracker is not on its own evidence that the transfer succeeded — confirm against the Error Logs and against the record actually arriving.
Once a collection behaves correctly on test data, widen its mapping filter to production scope.
Error Messages
Errors raised during installation and first transfer are most often an incorrect credential, an insufficient scope, or a commercetools project outside the supported region. For the full catalog of error text this integration produces, what each message means, and how to resolve it, see Error Messages.
Support and Troubleshooting
Click the Help button on any iPaaS.com page to contact Support or to search our documentation.
Support Portal: https://support.ipaas.com/en/
Contact Information: https://ipaas.com/contact-us/ or email support@ipaas.com
For questions about your commercetools project, API clients, scopes, region, or platform limits, use commercetools' own resources:
commercetools Documentation: https://docs.commercetools.com/
commercetools API Limits: https://docs.commercetools.com/api/limits
commercetools Support: https://support.commercetools.com/
Subscribers or their MiSP should have the subscription name, the affected mapping collection, and the relevant entries from Dashboard / Integration Monitoring / Error Logs on hand when contacting Support.