Summary

commercetools customers can be created and updated from iPaaS.com Customer records through the Add/Update commercetools Customer FROM iPaaS.com mapping collection, with the customer's addresses carried by its child collection Add/Update commercetools Customer Address FROM iPaaS.com. Transfers run automatically once the matching outbound subscriptions are enabled under Outbound Data Flows, and on demand from the iPaaS.com Manual Sync page. The purpose of this family is to keep storefront customer accounts in commercetools in step with the system of record that feeds iPaaS.com — a customer and all of its addresses always move together in a single write.

ID Format

Manual Sync ID Format

Enter the iPaaS.com Customer ID — the numeric identifier of the Customer record on the iPaaS.com side. Because this collection transfers data from iPaaS.com, the Manual Sync page expects the iPaaS.com record identifier, not a commercetools one.

Pattern: a numeric iPaaS.com Customer ID. The value is the identifier shown on the Customer record in iPaaS.com, and it is specific to your subscription — open the Customer record to read it.

The integration uses this ID to retrieve the full Customer record, including its child addresses, and write it to commercetools. The child address collection has no Manual Sync entry point of its own — addresses are transferred by running Manual Sync on the parent Customer.

External ID Format

After a successful write, iPaaS.com stores the commercetools identifier returned by commercetools as the external-ID link on the iPaaS.com record. commercetools issues record identifiers as 36-character GUIDs (UUIDs).

Pattern: a 36-character commercetools GUID
Example: fbd9c195-5028-46b3-b85d-016dc6e2f9b9

The value stored is therefore a commercetools identifier even though the transfer runs from iPaaS.com. Two links are recorded per transfer:

The commercetools customer identifier, stored against the iPaaS.com Customer record. This link is what routes every subsequent transfer to an update of the existing commercetools customer instead of creating a duplicate.
The commercetools address identifier, stored against each iPaaS.com child address record. This link is what causes a subsequent transfer to change the existing commercetools address rather than adding another copy of it.

Deleted Record Support

Outbound delete is not supported for either collection in this family. Deleting an iPaaS.com Customer or address does not delete the corresponding record in commercetools, delete mappings are not included in the default mapping templates shipped with this integration, and deletions do not propagate in any direction. An attempted delete fails with the message "The method or operation is not implemented." — the exact string to search for in the Error Logs. Records that must be removed have to be deleted directly in commercetools.

Custom Field Support

This integration has no custom-field implementation for the Customer family. Neither collection reads or writes commercetools custom types or custom fields, and there is no conversion function for retrieving a custom field value on either side. Customer and address data that must be carried in a commercetools custom field cannot be transferred through these collections as shipped.

Mapping Collection Status

Status: Enabled. Neither collection has a mapping filter applied, so every Customer transfer dispatched to this family is processed, and every address on that Customer is processed with it.

Trigger Events: Create and Update. Both collections ship with a sync type of Add/Update. Whether a given transfer creates a new commercetools record or updates an existing one is not decided by which event fired — it is decided by whether iPaaS.com already holds an external-ID link for the record.

Automatic Transfer

Records are dispatched to commercetools automatically when the subscriber enables the corresponding outbound subscriptions under Outbound Data Flows in the subscription configuration:

Mapping collection	Outbound subscriptions
Add/Update commercetools Customer FROM iPaaS.com	customer/created, customer/updated
Add/Update commercetools Customer Address FROM iPaaS.com	customer/address/created, customer/address/updated

Nothing transfers automatically until those subscriptions are enabled. Where they are not enabled, Manual Sync is the only transfer path. Because addresses are written inside the parent customer write, the parent collection's own subscriptions also carry addresses whenever a customer transfers.

Manual Sync

Customers are transferred on demand from the iPaaS.com Manual Sync page using the iPaaS.com Customer ID, as described under ID Format above. Manual Sync is available on the parent collection regardless of any other configuration, and it carries the customer's addresses with it.

Duplicate or Conflicting Mappings

The following mapping collections operate on the same records in the opposite direction:

Add/Update commercetools Customer TO iPaaS.com — brings commercetools customers into iPaaS.com.
Add/Update commercetools Customer Address TO iPaaS.com — brings commercetools customer addresses into iPaaS.com.

Before running this family alongside the inbound collections, review both directions and decide explicitly which system is the source of truth for customer data. This integration performs no collision handling of any kind — no duplicate detection, no match fields and no resolution methods — so with both directions active the later write always wins and changes can propagate back and forth between the two systems.

Whether a transfer creates or updates a commercetools customer is decided solely by the presence of an iPaaS.com external-ID link. If a matching customer already exists in commercetools but was never linked through iPaaS.com, this family creates a second record rather than detecting and reusing the existing one. commercetools does, however, treat the customer email address as unique within a project, so the duplicate write is normally rejected rather than silently accepted.

Unmapped Field Overwrite Risk

When the parent collection updates an existing commercetools customer, it always sends an instruction to set firstName, lastName, companyName and email, whether or not those fields are mapped in the collection. A field that is not mapped is sent with no value, and commercetools interprets that as an instruction to clear the field. Any existing value in these four fields on the commercetools customer is therefore erased on every sync unless the field is mapped.

This applies to updates only. Creating a new commercetools customer omits unmapped fields entirely and lets commercetools apply its own defaults, so the Add path carries no overwrite risk.

There are two ways to protect a field:

Map it from the iPaaS.com source. This is the correct approach whenever iPaaS.com genuinely holds the value.
Carry the existing commercetools value forward with DestinationValue. Where the value is maintained in commercetools and does not exist on the iPaaS.com side, add a Dynamic Formula mapping whose destination is the field to protect and whose source reads the current destination value. For example, a formula of DestinationValue.companyName mapped to the companyName field returns the value already on the commercetools customer and writes it back unchanged. Repeat this for each field you need to preserve.

All four fields are mapped in the default mappings shipped with this integration, so a subscriber who accepts the defaults is protected. The risk arises when a mapping is removed, or when the source field is empty on the iPaaS.com Customer record — an empty source value clears the destination value just as an absent mapping does.

Unmapped Address Fields Are Not Preserved Either

The address side carries an equivalent risk by a different mechanism. Address values are replaced, not merged: when an existing commercetools address is changed, the change instruction supplies a complete address record rather than individual field edits, and commercetools replaces the stored address with the one supplied. Any address field not mapped in the child collection is therefore absent from the replacement and is not carried over from the previous value.

If your commercetools addresses hold data that iPaaS.com does not — a phone number, a department, a building — add a Dynamic Formula mapping for that field whose source reads the current destination value, so the existing commercetools value is written back on each update.

Address Pairing Is by Street Name

After the write completes, the integration re-reads the saved customer and pairs each returned address back to the address that was sent by comparing street names. Two addresses on the same customer that share a street name can be linked to each other's iPaaS.com records. Where a customer may legitimately hold two addresses on the same street, verify the resulting links after the first transfer.

Supported Child Collections

Parent Collection: Add/Update commercetools Customer FROM iPaaS.com

Add/Update commercetools Customer Address FROM iPaaS.com — writes every address held on the parent Customer. Addresses with no stored commercetools address link are added; addresses that already carry a link are changed in place. This collection has no independent transfer entry point, no filter of its own, and cannot be dispatched or manually synced on its own; its records move only as part of a parent Customer transfer.

System Caveats

commercetools Caveats

Email is required. The commercetools customer draft requires an email address on every customer record — it is the only unconditionally required field on a new customer per the commercetools HTTP API documentation for customer records (retrieved 2026-07-20). A transfer with no email value is rejected.
Country is required on every address. The commercetools address record requires a country and expects a country code, not a spelled-out country name (commercetools HTTP API documentation for address records, retrieved 2026-07-20). This family supplies the code through the Country lookup translation.
Email uniqueness. commercetools treats the customer email address as unique within a project. Two iPaaS.com Customer records carrying the same email address cannot both be created as separate commercetools customers; the second write is rejected and the rejection appears in Dashboard / Integration Monitoring / Error Logs.
Password and authentication mode. A customer whose authentication mode is Password — the platform default — must carry a password. When the project uses ExternalAuth, the password is optional and is not stored on the customer. Subscribers using external authentication should confirm the authentication mode their project applies to newly created customers before relying on the shipped password mapping.
Record versioning. Every update is applied against the customer's current record version, which the integration reads immediately before writing. If the same commercetools customer is edited elsewhere between that read and the write, the write is rejected as out of date and the whole transfer — customer and addresses together — fails. Re-running the transfer resolves it.
Rate limiting. commercetools publishes its request limits and per-project quotas at https://docs.commercetools.com/api/limits (retrieved 2026-07-20); most are configurable per project, a few are hard limits. There is no claim that a request declined for a limit is retried or resumed on the subscriber's behalf. Treat a declined request as a failed transfer: monitor Dashboard / Integration Monitoring / Error Logs, re-run affected records with Manual Sync, and validate expected throughput in a staging environment before relying on it in production.

iPaaS.com Caveats

A Customer with no addresses at all fails to transfer. Both the create and the update path read the customer's address collection while assembling the write. A Customer carrying no addresses fails rather than transferring a customer without address data. Ensure every iPaaS.com Customer intended for transfer holds at least one address.
Field references in dynamic formulas use PascalCase on the iPaaS.com source side, matching the iPaaS.com field names shown in the mapping editor.
The connection test reports success without contacting commercetools. A configuration problem in the connection settings is not caught by the test — it appears at the first transfer instead, as an authorization failure in Dashboard / Integration Monitoring / Error Logs. Validate the connection settings by running a single Manual Sync rather than by relying on the test result. See commercetools Connections and Settings.
Errors on the child collection are reported against the parent. Because addresses have no independent entry point, a failure while writing an address surfaces against the parent Customer transfer in the Error Logs.

Integration-Specific Caveats

The password mapping ships as a placeholder that must be replaced. Placeholder value — replace during implementation: the password mapping ships as a Static mapping carrying the example value Commerce123, supplied so the collection is functional out of the box. Because it is a Static value, every customer written to commercetools through the unmodified default mappings receives that same password. Subscribers or their MiSP MUST replace it before go-live — either by supplying a per-customer value through a different mapping, or by configuring the commercetools project to use ExternalAuth so that customers are created without a password. See commercetools Integration Known Limitations.
Unmapped values are cleared on update for firstName, lastName, companyName and email, and unmapped address fields are not preserved when an address is changed. See Duplicate or Conflicting Mappings above.
The shipped Country translation covers the United States only. Address data for any other country requires additional translation rows before it can be transferred.
No initialization. Bulk initialization of existing commercetools customers is not supported.
No automatic dependency transfer. Related records are not transferred on a customer's behalf; only the Customer and its addresses move.

Setup Requirements

iPaaS.com Configuration

Complete and valid commercetools connection settings. Because the connection test always reports success, confirm them with a single Manual Sync. See commercetools Connections and Settings and commercetools Installation Instructions.
Enable the customer/created and customer/updated subscriptions under Outbound Data Flows for the parent collection, and customer/address/created and customer/address/updated for the child, if records are to transfer without manual intervention.
Replace the password Static mapping before go-live, as described under System Caveats.
Add a Country lookup translation row for every country, spelling and casing present in the iPaaS.com address data.
Ensure each iPaaS.com Customer intended for transfer carries an email address and at least one address.

commercetools Configuration

A commercetools project with API client credentials that permit reading and writing customers. The endpoints used by this family are listed in commercetools API Endpoints.
Confirm the authentication mode the project applies to newly created customers — Password (the platform default) or ExternalAuth — because it determines whether the password mapping is required at all.

Integration Flow

A Customer transfer is dispatched from iPaaS.com, either automatically from an enabled Outbound Data Flows subscription or on demand from Manual Sync using the iPaaS.com Customer ID.
The integration retrieves the full iPaaS.com Customer record, including its child addresses. A Customer with no addresses fails at this point.
The integration checks whether the iPaaS.com Customer already carries a commercetools external-ID link. The presence or absence of that link — not the triggering event — decides whether the transfer is an Add or an Update.
Add (no link stored): the customer record is created in a single write carrying the mapped customer fields and all of the customer's addresses inline. Fields left unmapped are simply omitted and commercetools applies its own default. commercetools assigns an identifier to the customer and to each address as they are created.
Update (link stored): the integration first reads the current commercetools customer to obtain its record version, then submits a set of change instructions against that version. The instructions always include firstName, lastName, companyName and email — whether or not they are mapped — followed by one instruction per address.
Per address on an update: an address carrying no stored commercetools address link produces an add address instruction; an address that carries a link produces a change address instruction targeting that address, which replaces the stored address in full.
After the write completes, the integration re-reads the saved customer record and pairs each returned address back to the address that was sent, matching on street name.
iPaaS.com records the returned commercetools customer identifier against the Customer record and the returned commercetools address identifier against each child address record. Those links route the next transfer to an update rather than a duplicate create.
Any failure is reported in Dashboard / Integration Monitoring / Error Logs against the parent Customer transfer, including failures raised while writing an address.

Mappings

Add/Update commercetools Customer FROM iPaaS.com

iPaaS.com data type: Customer

Description: Writes an iPaaS.com Customer record into commercetools as a customer record, creating it on the first transfer and updating it on every transfer thereafter. This collection has no mapping filter, so every dispatched Customer is processed.

Mapping Type	Source Field (iPaaS.com)	Destination Field (commercetools)	Description
Field	FirstName	firstName	Sets the customer's first name. commercetools does not require it, but this collection sends an instruction to set it on every update whether or not the mapping is present — so an unmapped or empty first name clears the existing commercetools value. Treat it as required in practice, or protect it with a `DestinationValue` formula.
Field	LastName	lastName	Sets the customer's last name. As with the first name, commercetools does not require it, but an instruction is sent on every update, so an unmapped or empty value clears what is already there. Treat it as required in practice, or protect it with a `DestinationValue` formula.
Field	EmailAddress	email	Required. commercetools requires an email address on every customer record and treats it as unique within the project. A transfer with no email is rejected, and a second customer carrying an email already in use is rejected. On update, an instruction to change the email is always sent, so an empty source value clears the email rather than leaving it in place.
Field	Company	companyName	Sets the company name on the customer record. commercetools does not require it, but an instruction is sent on every update, so removing the mapping clears the existing commercetools value rather than leaving it alone. When the iPaaS.com Customer has no company recorded, the commercetools company name is set to empty. Protect it with `DestinationValue.companyName` if the value is maintained in commercetools.
Static	`"Commerce123"`	password	Required whenever the commercetools project's authentication mode is Password, which is the platform default; optional under ExternalAuth. Placeholder value — replace during implementation: `Commerce123` is an example value shipped so the collection works out of the box, and because it is Static every customer written through the unmodified defaults receives this same password. Subscribers or their MiSP MUST replace it before go-live.

Note that this is the complete shipped mapping set for the customer record itself. commercetools customer groups, stores and locale are not written by this collection.

Add/Update commercetools Customer Address FROM iPaaS.com

iPaaS.com data type: Customer Address

Description: Shapes every address held on the parent iPaaS.com Customer and writes it into commercetools as a customer address, as part of the parent Customer write. This collection has no mapping filter, so every address on a dispatched Customer is processed.

Mapping Type	Source Field (iPaaS.com)	Destination Field (commercetools)	Description
Dynamic Formula	Stored commercetools address link (see formula below)	Id	Recommended — do not remove. Supplies the commercetools address identifier iPaaS.com stored on a previous transfer, and returns nothing when none has been stored. This is what decides whether the address is added as new or the existing commercetools address is changed in place. commercetools does not require an identifier on a new address. Without this mapping, every transfer adds a further copy of each address to the commercetools customer.
Lookup Translation	Lookup Translation: Country	Country	Required. commercetools requires a country on every address and expects a country code rather than a spelled-out name. The translation converts the value on the iPaaS.com address into the code commercetools expects. An address whose country value matches no row does not resolve to a code and is rejected. See the Lookup Translation Tables below.
Field	Address1	StreetName	Recommended. Sets the street name from the first iPaaS.com address line. Optional as far as commercetools is concerned, but the integration pairs addresses returned by commercetools back to the addresses it sent by comparing street names — an address with no street name cannot be paired, so its commercetools link may not be recorded and the next transfer adds it again. Only the first address line is carried; second and third lines are not mapped and are not written.
Field	City	City	Optional — commercetools does not require a city on an address record. Because changing an existing address replaces the stored address in full, an empty source value produces an address with no city rather than one that keeps its previous city.
Field	Region	State	Optional — commercetools does not require a state. The source is the iPaaS.com Region field; commercetools exposes both a state and a region on an address, and this mapping writes the iPaaS.com region value into the commercetools state, leaving the commercetools region unset. No translation is applied, so the value arrives exactly as held in iPaaS.com. If commercetools or a downstream process expects state codes, ensure the source data already holds codes.
Field	PostalCode	PostalCode	Optional — commercetools does not require a postal code and does not validate it against the address's country. Ensure the iPaaS.com source data holds postal codes in the form the commercetools project and any downstream carrier integrations expect.
Field	FirstName	FirstName	Optional — commercetools does not require a first name on an address record. This is the address-level first name, which commercetools stores separately from the first name on the customer record.
Field	LastName	LastName	Optional — commercetools does not require a last name on an address record. This is the address-level last name, stored separately from the last name on the customer record.
Field	Company	Company	Optional — commercetools does not require a company on an address record. This is the address-level company and is separate from the company name on the customer record itself, which is handled by the parent collection.

The Id formula referenced above, reproduced verbatim:

var external = await GetExternalIdAsync(Id, "Address", SpaceportSystemId);
return external;

It looks up the commercetools address identifier iPaaS.com holds for this address and returns it, or returns nothing when no identifier has been stored yet. It runs automatically and needs no subscriber configuration; the formula text is visible and editable in the iPaaS.com mapping editor.

Lookup Translation Tables

Lookup Translation: Country — reads the Country field on the iPaaS.com address and returns the country code written to the commercetools address. Seven rows ship by default, all resolving to the United States.

Source Value	Destination Value	Notes
United States	`US`	Full country name as commonly held in iPaaS.com address data.
USA	`US`	Upper-case three-letter abbreviation.
Usa	`US`	Mixed-case abbreviation.
usa	`US`	Lower-case abbreviation.
US	`US`	Upper-case two-letter code — passes the code through unchanged.
us	`US`	Lower-case two-letter code.
`Us	`US`	The source value begins with a literal backtick character followed by `Us`. It matches only iPaaS.com values that literally begin with that character.

These are designed constants, not environment-specific settings: the destination values are country codes defined by commercetools, and the several source rows exist so that the differently cased and abbreviated spellings iPaaS.com may hold all resolve to the same code.

As shipped, this translation covers the United States only. Subscribers or their MiSP must add a row for every other country their iPaaS.com address data contains, including each spelling and casing variant that can occur, before transferring addresses outside the United States.

Error Handling

Failures for both collections are reported against the parent Customer transfer in Dashboard / Integration Monitoring / Error Logs. A fuller catalog is maintained in commercetools Error Messages.

A customer transferred with no email address is rejected. commercetools requires an email on every customer record. Resolution: populate the email address on the iPaaS.com Customer, confirm the email mapping is present, and re-run the transfer with Manual Sync.
A customer whose email address is already in use in commercetools is rejected. commercetools treats the email address as unique within a project. Resolution: identify which commercetools customer already holds the address. If it is the same person, link the records or correct the iPaaS.com data; if it is not, correct the duplicate email in iPaaS.com.
An address whose country value does not resolve to a code is rejected. commercetools requires a country code on every address. Resolution: add the missing spelling or casing variant to the Country lookup translation and re-run the parent Customer transfer.
A Customer with no addresses fails to transfer. The transfer fails rather than writing a customer without address data. Resolution: add at least one address to the iPaaS.com Customer record and re-run.
An update rejected because the record version is out of date. The commercetools customer was edited elsewhere between the version read and the write. Resolution: re-run the transfer with Manual Sync; the integration reads the current version again.
An authorization failure on the first transfer after setup. The connection test reports success without contacting commercetools, so credential problems surface here rather than at test time. Resolution: correct the connection settings per commercetools Connections and Settings and re-run a single Manual Sync.
A delete attempt fails with the message "The method or operation is not implemented." Delete is not implemented for either collection. Resolution: none through the integration — remove the record directly in commercetools.
A request declined for a commercetools request limit or project quota. Treat it as a failed transfer, not a delayed one; there is no claim of automatic retry or resumption. Resolution: re-run affected records with Manual Sync and reduce concurrent load.

Validation Rules

Email present on every Customer. Enforced by commercetools; a transfer without it is rejected.
Email unique within the commercetools project. Enforced by commercetools on create.
Country resolvable to a code on every address. Enforced by the Country lookup translation followed by commercetools validation.
At least one address on every Customer. Enforced by the integration; a Customer with none fails to transfer.
Record version current at write time. Enforced by commercetools optimistic concurrency on every update.
Password present when the project authentication mode is Password. Enforced by commercetools; satisfied by the shipped Static mapping, which must be replaced before go-live.

Testing & Validation

Test Scenarios

New customer create. Create a Customer in iPaaS.com with an email address and one address, run Manual Sync with its numeric iPaaS.com Customer ID, and confirm a new commercetools customer appears with the mapped name, company, email and address. Expected outcome: the transfer succeeds and iPaaS.com records a commercetools GUID as the external ID on the Customer and on the address.
Existing customer update. Change the first name on that Customer and re-run Manual Sync. Expected outcome: the existing commercetools customer is updated in place — no second customer is created — and the address link is unchanged.
Unmapped-field overwrite. In a staging environment only, remove the companyName mapping, set a company name directly on the commercetools customer, and re-run the transfer. Expected outcome: the commercetools company name is cleared. Then add a Dynamic Formula mapping of DestinationValue.companyName to companyName and re-run. Expected outcome: the commercetools value is preserved. Restore the original mapping afterwards.
Required-field validation. Clear the email address on a test Customer and attempt a transfer. Expected outcome: the transfer fails with a rejection recorded in Dashboard / Integration Monitoring / Error Logs.
No-address validation. Attempt a transfer of a Customer holding no addresses. Expected outcome: the transfer fails rather than creating a customer without address data.
Country translation coverage. Transfer an address whose country value is a spelling not present in the Country translation. Expected outcome: the address is rejected. Add the row and re-run; the address is then accepted.
Address add versus change. Add a second address to the Customer and re-run. Expected outcome: the new address is added to the commercetools customer and the existing address is changed in place, not duplicated.
Address pairing. Give the customer two addresses on the same street name and re-run. Expected outcome: verify which iPaaS.com address each commercetools address identifier is recorded against, since pairing is by street name and can cross-link.
Password replacement. After replacing the shipped Static password mapping, create a new customer and confirm the intended password behavior in commercetools before go-live.
Automatic transfer. Enable the four Outbound Data Flows subscriptions, change a Customer in the upstream system of record, and confirm the transfer runs without a Manual Sync.

Validation Checklist

The numeric iPaaS.com Customer ID is accepted on the Manual Sync page and the transfer completes.
A commercetools GUID is recorded as the external ID on the iPaaS.com Customer and on each child address.
All four of firstName, lastName, companyName and email are mapped, or are protected by a DestinationValue formula.
The password Static mapping has been replaced, or the commercetools project uses ExternalAuth.
The Country lookup translation holds a row for every country, spelling and casing present in the source data.
The Id mapping on the address collection is present, so repeat transfers change addresses rather than duplicating them.
Every Customer intended for transfer carries an email address and at least one address.
The four outbound subscriptions are enabled under Outbound Data Flows if automatic transfer is expected.
A repeat transfer of the same Customer updates the existing commercetools customer rather than creating a second one.
Error Logs are clear after a full test pass.

Additional Notes

The following are not performed by this family of collections:

Customer and address delete in either direction.
Standalone address writes. There is no address-only outbound flow; addresses move only with their parent Customer.
Customer groups, stores and locale, and address custom fields — none of these commercetools properties are written.
Default shipping and billing address designation. The child collection does not set which commercetools address is the customer's default.
Collision handling and duplicate detection. Not implemented for any collection in this integration.
Initialization. Bulk initialization of existing commercetools customers is not supported.

Further constraints that apply across the whole integration are described in commercetools Integration Known Limitations, and the endpoints used by these collections are listed in commercetools API Endpoints. For assistance, contact iPaaS.com Support at support@ipaas.com.

iPaaS.com to commercetools Customer Mapping Documentation