Overview
This integration transfers OroCommerce Order records to iPaaS.com as Transactions. When an Order is created or updated in OroCommerce, the corresponding Transaction record is created or updated in iPaaS.com, along with the associated Order Addresses and Order Line Items.
Before You Begin
Ensure the following prerequisites are in place before configuring this integration.
OroCommerce Requirements
A valid OroCommerce account with API access.
OAuth 2.0 credentials (Code, Client ID, Client Secret, Redirect URL) must be correctly configured for iPaaS.com API access.
Orders must contain valid data for all required mapping fields (Identifier, Internal Status, Customer User, Customer).
Taxes may not appear on order lines even when taxes are configured in the OroCommerce taxes module. This is a known issue at the time of writing.
OroCommerce has multiple discount fields that may return inconsistent values via API compared to what the OroCommerce UI displays. The integration addresses this by comparing calculated discount totals and using the higher amount. See the DiscountAmount mapping for details.
iPaaS.com Requirements
Access to iPaaS.com with permissions to create and update Transaction records.
Products must exist in iPaaS.com before syncing Orders. If a product referenced in an order line does not exist in iPaaS.com, the transfer will fail.
OAuth 2.0 credentials must be correctly configured in iPaaS.com for OroCommerce API access.
ID Format
When manually syncing, the Order ID from OroCommerce is used. This can be resolved via an external ID.
Custom Field Support
This integration supports custom fields for both OroCommerce Order Headers and Order Addresses.
Order Header Custom Fields
To map a custom field from OroCommerce to iPaaS.com on the Order Header, use the Dynamic Formula mapping type with the GetValueFromCustomField conversion function. The source formula format is:
return GetValueFromCustomField(AdditionalProperties, "AlexTestCustomFieldOrderHeader");
This retrieves the custom field AlexTestCustomFieldOrderHeader from the AdditionalProperties collection using the GetValueFromCustomField conversion function.
It is preferred to keep a 1:1 ratio between OroCommerce and iPaaS.com custom fields. This should result in a smoother integration process.
The custom field mapping would change depending on your implementation, and the current example is for demonstration purposes only.
Order Address Custom Fields
To map a custom field from OroCommerce to iPaaS.com on the Order Address, use the same Dynamic Formula approach:
return GetValueFromCustomField(AdditionalProperties, "AlexTestCustomFieldOrderAddress");
This retrieves the custom field AlexTestCustomFieldOrderAddress from the AdditionalProperties collection using the GetValueFromCustomField conversion function.
The custom field mapping would change depending on your implementation, and the current example is for demonstration purposes only.
Mapping Collection Status
Mapping Status: Enabled.
Trigger Events: Manual Sync, Polling.
Conflicting Mappings
This is the only active mapping collection for OroCommerce Add/Update
Order TO iPaaS.com sync. This mapping applies only to Orders. Ensure no other mappings target the same OroCommerce entity to prevent data from being overwritten.
Authentication and Security
OroCommerce uses OAuth 2.0 authentication to generate an access token. This token authorizes all OroCommerce API requests during transfer operations.
Code: A temporary authorization code issued by OroCommerce during the OAuth flow. It is exchanged for an access token to allow secure API access on behalf of an OroCommerce account.
Client ID: A unique identifier assigned to iPaaS by OroCommerce. It is used to identify the app when initiating the OAuth authorization process.
Client Secret: A confidential key provided by OroCommerce, used together with the Client ID to securely authenticate iPaaS during token exchange and API calls.
Redirect URL: The callback URL that OroCommerce uses to return authorization-specific values during the authentication process.
Integration Flow
The integration processes OroCommerce Orders as follows:
The integration runs a prerequisite check to avoid duplicate transfers.
No specific filters are applied. All Orders are processed.
iPaaS.com Order fields are populated using mapped OroCommerce data.
If Order Addresses and Order Line Items exist, they are processed as child entities.
If the Transaction (Order) does not exist in iPaaS.com, it is created. If it already exists, it is updated.
Sync results are logged for troubleshooting.
Polling event must be configured in Events Queue section to transfer orders to iPaaS automatically.
Supported Child Collections
This parent mapping collection supports the following child collections:
Mappings
Parent: Add/Update OroCommerce Order To iPaaS
Description
This mapping collection handles the creation and update of OroCommerce Orders as Transaction records in iPaaS.com. It maps order identification, status, email resolution, financial totals, company and customer associations, and timestamps.
Mapping Type | Source Field (OroCommerce) | Destination Field (iPaaS.com) | Description |
Field | Attributes_PoNumber | poNumber (custom field) | Maps the PO number to a custom field in iPaaS.com. |
Dynamic Formula |
| AlexTestCustomFieldOrderHeader (custom field) | Example custom field mapping. Maintain a 1:1 ratio between OroCommerce and iPaaS.com custom fields. This example is for demonstration purposes only. |
Field | Attributes_Identifier | TransactionNumber | Required. Maps the OroCommerce order identifier. |
Static | Order | Type | Required. Sets the transaction type to "Order." |
Relationships_InternalStatus_Id | Status | Required. Translates the OroCommerce internal status to the iPaaS.com format. | |
Dynamic Formula | See Email Resolution. | EmailAddress | Required. OroCommerce Orders do not include an email field. The system resolves the email using a multi-step fallback. See Email Resolution. |
Field | Attributes_TotalDiscountsAmount | DiscountAmount | The integration sums Attributes_Discount, Attributes_ShippingDiscount, and Attributes_TotalDiscountsAmount, then compares the result against discounts found in order subtotals. The higher amount is used. This addresses inconsistencies between OroCommerce API values and UI values. |
Field | OrderTaxAmount | TaxAmount | Control field. Populates the tax amount on the Transaction. |
Field | Attributes_EstimatedShippingCostAmount | ShippingAmount | Recommended. Maps the estimated shipping cost. |
Field | Attributes_SubtotalValue | Subtotal | Recommended. Maps the order subtotal. |
Field | Attributes_TotalValue | Total | Recommended. Maps the order total. |
Dynamic Formula |
| TotalQty | Calculates the total quantity across all line items. Returns zero if LineItems is null or empty. |
Field | Attributes_CreatedAt | TransactionCreatedDateTime | Recommended. Maps the order creation timestamp. |
Field | Attributes_UpdatedAt | TransactionUpdatedDateTime | Recommended. Maps the order last-updated timestamp. |
Field | SpaceportSystemId | SystemId | Required. Maps the SpaceportSystemId. |
Dynamic Formula |
| CompanyId | Recommended. Looks up the iPaaS company ID for the OroCommerce Customer linked to the order. In OroCommerce, the Customer record represents a Company. |
Dynamic Formula |
| CustomerId | Recommended. Looks up the iPaaS customer ID for the OroCommerce CustomerUser linked to the order. In OroCommerce, the CustomerUser record represents a Customer. |
Email Resolution
The OroCommerce Order record does not include an EmailAddress field. The integration resolves the email using the following fallback sequence:
long? iPaaSCustomerId = await GetSpaceportIdAsync(Relationships_CustomerUser_Id, "Customer", SpaceportSystemId);
if (iPaaSCustomerId.HasValue) {
return await GetCustomerUserEmailByCustomerUserIdAsync(Relationships_CustomerUser_Id);
}
long? iPaaSCompanyId = await GetSpaceportIdAsync(Relationships_Customer_Id, "Company", SpaceportSystemId);
if (iPaaSCompanyId.HasValue) {
return await GetCompanyEmailByiPaaSCompanyIdAsync(iPaaSCompanyId.Value);
}
// We return a dummy email if we could not locate one for a company or customer
return "email@example.com";
First, the system attempts to find the customer in iPaaS.com using the Relationships_CustomerUser_Id value from the CustomerUsers entity. If found, the email is retrieved using GetCustomerUserEmailByCustomerUserIdAsync.
If the customer does not exist in iPaaS.com, the system attempts to find the company using
Relationships_Customer_Id. If found, the company email is retrieved usingGetCompanyEmailByiPaaSCompanyIdAsync.If neither lookup succeeds, a placeholder email (
email@email.com) is returned.
NOTE: In OroCommerce (B2B model), Customers are treated as Companies. However, the EmailAddress field is not part of the Customer (Company) object schema in OroCommerce. That is why the integration attempts to retrieve the company email from iPaaS.com instead of directly from OroCommerce. |
Lookup Translation: Transaction (Order) Status To iPaaS
Source Value (OroCommerce) | Destination Value (iPaaS) |
open | Pending |
pending | Pending |
processing | Processing |
cancelled | Cancelled |
closed | Closed |
Child: OroCommerce Add/Update Order Address TO iPaaS
Description
This mapping collection handles the creation and update of OroCommerce Order Addresses as child records in iPaaS.com. It maps address fields, contact names, and primary address indicators.
Mapping Type | Source Field (OroCommerce) | Destination Field (iPaaS.com) | Description |
Dynamic Formula |
| AlexTestCustomFieldOrderAddress (custom field) | Example custom field mapping. Maintain a 1:1 ratio between OroCommerce and iPaaS.com custom fields. This example is for demonstration purposes only. |
Field | Attributes_Street | Address1 | Recommended. Maps the primary street address. |
Field | Attributes_Street2 | Address2 | Recommended. Maps the secondary address (apartment, suite, unit). |
Field | Attributes_City | City | Recommended. Maps the city. |
Field | Relationships_Region_Id | Region | Recommended. Maps the state or province. |
Field | Relationships_Country_Id | Country | Recommended. Maps the country. |
Field | Attributes_PostalCode | PostalCode | Recommended. Maps the ZIP or postal code. |
Field | Attributes_FirstName | FirstName | Recommended. Maps the contact's first name. |
Field | Attributes_LastName | LastName | Recommended. Maps the contact's last name. |
Field | IsPrimaryShipping | IsPrimaryShipping | Recommended. Indicates whether this is the primary shipping address. |
Field | IsPrimaryBilling | IsPrimaryBilling | Recommended. Indicates whether this is the primary billing address. |
Child: OroCommerce Add/Update Order Line Item TO iPaaS
Description
This mapping collection handles the creation and update of OroCommerce Order Line Items as child records in iPaaS.com.
Mapping Type | Source Field (OroCommerce) | Destination Field (iPaaS.com) | Description |
Static | Product | Type | Required. Sets the line item type to "Product." |
Static | Pending | Status | Required. Sets the line item status to "Pending." |
Field | Attributes_ProductSku | Sku | Required. Maps the product SKU. Must exist in iPaaS.com. |
Field | Attributes_ProductName | Description | Recommended. Maps the product name as the line item description. |
Field | Attributes_Quantity | Qty | Recommended. Maps the ordered quantity. |
Field | Attributes_Quantity | QtyShipped | Recommended. Maps the shipped quantity. Defaults to the ordered quantity. |
Field | Attributes_Value | UnitPrice | Recommended. Maps the unit price. |
Field | Attributes_RowTotalAfterDiscount | UnitPrice | Recommended. Maps the unit price after discounts. |
Field | Attributes_RowTotalAfterDiscount | ExtendedPrice | Recommended. Maps the line total after discounts. |
Error Handling
Missing SKU
Product not found by Sku.
Description: OroCommerce Product referenced in an Order Line Item does not exist in iPaaS.com. For example:
Product not found by Sku:7BS71 provided.Resolution: Ensure all OroCommerce Products exist in iPaaS.com prior to Order transfer.
Validation and Testing
Before deploying this integration, verify the following configuration items and run the test scenarios to confirm proper operation.
Validation Checklist
Order (Parent) Requirements
OroCommerce Products must exist in iPaaS.com prior to Order transfer.
Address is optional but must be valid if present.
TransactionNumber (Attributes_Identifier) is populated.
Status maps to a valid iPaaS status via the lookup translation.
Email can be resolved through CustomerUser, Company, or fallback.
SystemId (SpaceportSystemId) is populated.
Order Address (Child) Requirements
Address fields are valid when present.
IsPrimaryShipping and IsPrimaryBilling are set.
Order Line Item (Child) Requirements
Product SKU exists in iPaaS.com.
Type and Status are set.
Test Scenarios
Scenario 1: Create Order
Create an order in OroCommerce. Execute manual sync. Verify the Order is created as a Transaction in iPaaS.com with all mapped fields populated.
Scenario 2: Update Existing Order
Update an existing order in OroCommerce. Execute manual sync. Verify changes are reflected in iPaaS.com without creating a duplicate.
Scenario 3: Order Without Address or Line Items
Sync an order that has no addresses and no line items. The parent Transaction should be created in iPaaS.com; child collections should be skipped.
Scenario 4: Order With Address and Line Items
Sync an order that includes both addresses and line items. Verify the parent Transaction and all child records (addresses and line items) are created.
Scenario 5: Re-sync Existing Order
Sync an order that already exists in iPaaS.com. Verify the record is updated, not duplicated.
Scenario 6: Missing Product SKU (Failure Case)
Sync an order containing a line item with a SKU that does not exist in iPaaS.com. The sync should fail with a "Product not found by Sku" error and no incomplete records should be created.
Additional Notes
OroCommerce Customers are treated as Companies in the B2B model. The EmailAddress field is not part of the Customer (Company) object schema in OroCommerce, so the integration retrieves the email from iPaaS.com.
OroCommerce has multiple discount fields that may return inconsistent values via API. The integration compares calculated totals and uses the higher amount to capture the most accurate discount.
Taxes may not appear on order lines even when configured in OroCommerce. This is a known issue.
Custom fields use the
GetValueFromCustomFieldconversion function to retrieve values from theAdditionalPropertiescollection. Maintain a 1:1 ratio between OroCommerce and iPaaS.com custom fields.If a product SKU was modified to meet OroCommerce requirements in product or variant mappings, it may be necessary to convert the OroCommerce SKU back to an iPaaS.com SKU within the transaction line SKU mapping. Consult with your MISP for more information.