OroCommerce Customer Category From iPaaS.com Mapping Documentation

When a Customer Category is created or updated in iPaaS.com, the record is synchronized to OroCommerce as a Customer Group. This integration runs FROM iPaaS.com and is triggered on Create and Update events. It maps the customer segment's name and resolves the organizational structure and financial terms (organization, owner, payment term, and tax code) so that consistent pricing and taxation logic is associated with the customer segment in OroCommerce.

ID Format

When manually transferring a Customer Category from iPaaS.com, enter the valid iPaaS.com Customer Category internal ID into the input field on the iPaaS.com manual sync page.

Example: 145146

External ID Format

The OroCommerce Customer Group ID is saved as the external ID in iPaaS.com after a successful transfer. The presence of this external ID indicates that the record was transferred successfully and is used to align subsequent updates with the existing OroCommerce record.

Example: 25

Custom Field Support

This integration supports custom fields. Data from an iPaaS.com Customer Category can be mapped into a custom field on the OroCommerce Customer Group. Custom-field mappings read a value from the iPaaS.com record (using the custom-field value helper) and write it to the matching OroCommerce custom field. To map a custom field, create the field in OroCommerce first, then create a matching custom field in iPaaS.com, then add the mapping.

Note: For this collection, the custom field module in OroCommerce must be Customer Group.

Creating Custom Fields in OroCommerce

Navigate to Entity Management: go to System > Entities > Entity Management.
Select the target module (entity) where you want to add the custom field — Customer Group for this integration.
Click Create Field and configure the field as required (Field Name, Type, Storage Type).
Enter a unique Field Name and select a Storage Type. See the Storage Type Notes below.
Set the field Type as "string". Other simple data types such as "Number" or "Boolean" are supported when using compatible mappings.
Click Continue.
Edit the field information on the next page if necessary, then click Save and Close.
After creating the field, click Update Schema (if required by the Storage Type).

Storage Type Notes

Storage Type	Schema Update Required	Notes
Table Column	Yes (mandatory)	The custom field is not available until the schema update completes. Contact your OroCommerce administrator before changing an entity schema to prevent unexpected service downtime. After creating a Table Column field, a red Update Schema button appears on the page; click Update Schema to apply the changes.
Serialized Field	No (automatic)	The custom field is added to the schema automatically. Recommended.

Important: Selecting Serialized Field as the Storage Type is recommended to avoid manual schema updates.

Creating Custom Fields in iPaaS.com

In iPaaS.com, click Data Management > Custom Fields > Add Custom Field.
Enter a unique Field Name. This name must exactly match the OroCommerce custom field name created above. Select the Module (Customer Category) and set the Data Type to String.
The Description field is recommended but not required.
Click Save.

Setting Custom Field Values in iPaaS.com

In iPaaS.com, navigate to Customer Categories.
Open the Customer Category, click Edit, then click Add under the Custom Fields section.
Select an existing custom field in iPaaS.com, or create a new one if needed, and enter the value in the Value field.
Click Apply.

Mapping the Custom Field in iPaaS.com

In the iPaaS.com mapping collection, add a mapping by selecting the Custom Field type. A list of your created custom fields appears; choose the appropriate custom field from the Destination (OroCommerce) dropdown.
Map the source using a dynamic formula, a static value, or any other mapping method available in iPaaS.com.
Ensure the destination custom field name exactly matches the corresponding OroCommerce custom field name.

Mapping Collection Status

Status: Enabled
Trigger Events: Create, Update

This collection has no mapping filter, so all qualifying Customer Category records are processed on a Create or Update event.

Duplicate or Conflicting Mappings

This mapping applies only to the Customer Category (OroCommerce Customer Group). To prevent data from being overwritten, ensure no other mapping collection targets the same OroCommerce Customer Group entity.

Supported Child Collections

This flow has no child collections. All attributes and relationships are handled within this single mapping collection, transforming the flat iPaaS.com Customer Category record into OroCommerce's nested Customer Group structure.

System Caveats

OroCommerce Caveats

Name: Required for identifying the group in OroCommerce.
Organization: Required to link the group to the correct organization. The organization is resolved dynamically from the organization name.
Relationship type values: Type, Relationships_Organization_Type, Relationships_Owner_Type, Relationships_PaymentTerm_Type, and Relationships_TaxCode_Type must each be provided. A relationship ID is only used in the request when its corresponding type field is also mapped.
Type value is case-sensitive: The Type value "customergroups" must be entered exactly as shown.
Relationship resolution: Organization, Owner, Payment Term, and Tax Code are resolved dynamically through lookups that find the internal OroCommerce ID from the supplied name or code. The referenced organization, user, payment term, and tax code should exist in OroCommerce before the transfer runs.

iPaaS.com Caveats

The Name field is required. Without it, the Customer Category will not be created.

Setup Requirements

OroCommerce Configuration

Supply all required fields through mappings (see the Mappings section).
Ensure the referenced organization, user (owner), payment term, and tax code exist in OroCommerce so the dynamic lookups can resolve them.

iPaaS.com Configuration

Name: A unique identifier for the Customer Category in iPaaS.com.

Authentication

OroCommerce uses OAuth 2.0 (Authorization Code) authentication to generate an access token, which is then used to authorize all OroCommerce API requests during transfer operations. Ensure credentials are stored securely within the iPaaS.com credential manager.

Integration Flow

The integration processes iPaaS.com Customer Category records as follows:

A Customer Category is created or updated in iPaaS.com.
iPaaS.com authenticates with OroCommerce using OAuth 2.0.
Required relationship entities (Organization, Owner, Payment Term, Tax Code) are resolved via dynamic lookups against OroCommerce.
The Customer Group is created or updated in OroCommerce with the mapped name, relationship values, and any mapped custom fields.
The OroCommerce Customer Group ID is saved as the external ID in iPaaS.com.
Transfer status and any errors are logged in iPaaS.com.

Mappings

Add/Update OroCommerce Customer Category FROM iPaaS.com

This mapping collection synchronizes the iPaaS.com Customer Category to an OroCommerce Customer Group. It maps the category name and resolves the organization, owner, payment term, and tax code relationships so the customer segment carries consistent pricing and taxation logic in OroCommerce. There is no mapping filter on this collection, so all Customer Category records are processed.

Mapping Type	Source Field (iPaaS.com)	Destination Field (OroCommerce)	Description
Static	customergroups	Type	(Required) Specifies the customer category record type. This value is case-sensitive and must be entered exactly as "customergroups".
Field	Name	Attributes_Name	(Required) Maps the customer category name.
Dynamic Formula	`var id = await GetOrganizationIdByNameAsync("iPaaS.com"); return id;`	Relationships_Organization_Id	(Required) Resolves the organization ID from the organization name. Placeholder value — replace during implementation: substitute "iPaaS.com" with the name of the organization in your OroCommerce instance.
Static	organizations	Relationships_Organization_Type	(Required) Specifies the organization relationship type for the customer category.
Dynamic Formula	`var id = await GetUserIdByUsernameAsync("admin"); return id;`	Relationships_Owner_Id	Resolves the user (owner) ID from the user name. Placeholder value — replace during implementation: substitute "admin" with the username of the owning user in your OroCommerce instance.
Static	users	Relationships_Owner_Type	(Required when Owner_Id is mapped) Specifies the owner (user) relationship type for the customer category.
Dynamic Formula	See the Payment Term formula below the table.	Relationships_PaymentTerm_Id	Resolves the payment term ID from the payment term name. The formula raises an error if the payment term is not found in OroCommerce. Placeholder value — replace during implementation: substitute "net 90" with a payment term that exists in your OroCommerce instance.
Static	paymentterms	Relationships_PaymentTerm_Type	(Required when PaymentTerm_Id is mapped) Specifies the payment term relationship type for the customer category.
Dynamic Formula	`var id = await GetCustomerTaxCodeIdByTaxCodeAsync("STATE_GOVERNMENTS"); return id;`	Relationships_TaxCode_Id	Resolves the tax code ID from the tax code. Placeholder value — replace during implementation: substitute "STATE_GOVERNMENTS" with a customer tax code that exists in your OroCommerce instance.
Static	customertaxcodes	Relationships_TaxCode_Type	(Required when TaxCode_Id is mapped) Specifies the tax code relationship type for the customer category.
Dynamic Formula	See the CustomField11 formula below the table.	CustomField11	Reads the value of the "CustomField11" custom field from the iPaaS.com record and writes it to the matching custom field on the OroCommerce Customer Group; returns no value when the source is empty. Placeholder value — replace during implementation: "CustomField11" is an example custom field. Replace it with a custom field that exists on both the iPaaS.com Customer Category and the OroCommerce Customer Group, or remove this mapping if not used.

Payment Term formula (Relationships_PaymentTerm_Id):

var id = await GetPaymentTermIdByPaymentTermAsync("net 90");
if (id == null)
{
    throw new Exception("Payment term was not found in OroCommerce.");
}
return id;

CustomField11 formula (CustomField11):

var value = GetCustomFieldValue(CustomFields, "CustomField11");
if (string.IsNullOrEmpty(value)){return null;}
else {return value;}

Error Handling

Unable to create/update Customer Group in OroCommerce from iPaaS.com — This may occur when OroCommerce rejects the creation or update of a Customer Group. Resolution: ensure all required fields are populated.
Cannot update Customer Group: Id is missing — This may occur when OroCommerce rejects an update because no ID is present. Resolution: ensure the OroCommerce Customer Group ID is saved as the external ID in iPaaS.com, handle this through prerequisites, or synchronize the record using the create operation rather than update.
Payment term was not found in OroCommerce. — The payment term dynamic formula raises this error when the specified payment term name does not resolve to an OroCommerce payment term. Resolution: confirm the payment term exists in OroCommerce and that the name in the formula matches it exactly.

Validation Rules

Relationship type validation: When a relationship ID field is mapped (for example Relationships_Owner_Id), its corresponding type field (Relationships_Owner_Type) must also be mapped for the relationship to be included in the request. If the type field is not provided, the ID field is not used. This pattern applies to all relationship fields in this collection.
Custom field name matching: A custom field name in iPaaS.com must exactly match its OroCommerce field name for the value to map.

Testing and Validation

Test Scenarios

Create Customer Group: Sync a new Customer Category from iPaaS.com. Verify that the Customer Group is created in OroCommerce and that the OroCommerce Customer Group ID is saved as the external ID in iPaaS.com.
Update Existing Customer Group: Update an existing Customer Category in iPaaS.com and confirm that the changes are reflected in OroCommerce without creating duplicates.

Validation Checklist

Customer Group Name is present and not empty.
Organization ID is successfully resolved via the dynamic formula.
Owner (user) ID is successfully resolved.
Payment Term ID is resolved correctly when provided.
Tax Code ID is resolved correctly when provided.
Each mapped relationship ID has its corresponding relationship Type mapped.
The OroCommerce Customer Group ID is stored as the external ID in iPaaS.com after successful creation.

Additional Notes

Ensure dynamic formulas return valid references for all dependent entities; null or invalid returns may cause transfer failures.
The organization, owner, payment term, and tax code referenced by the dynamic lookups should exist in OroCommerce before the transfer runs.
Custom field names in iPaaS.com must exactly match the OroCommerce field names.
Contact your OroCommerce administrator before updating entity schemas to prevent service downtime.