OroCommerce Order To iPaaS.com Mapping Documentation
This integration flow transfers order data from OroCommerce to iPaaS.com. When an order is created or updated in OroCommerce, the integration creates or updates a matching transaction in iPaaS.com, including the order header, order addresses (billing and shipping), and order line items. In this workflow OroCommerce is the source system and iPaaS.com is the destination. The flow is polling-based: new and changed orders are detected on the integration's polling schedule rather than through a real-time webhook.
Before You Begin
Ensure the following prerequisites are in place before configuring this integration flow.
iPaaS.com Requirements
Access to iPaaS.com with permissions to create and update transaction records.
Products referenced on order line items must exist in iPaaS.com before orders are synced. If a product referenced on an order line does not exist in iPaaS.com, the transfer fails.
OAuth 2.0 credentials for the OroCommerce account must be configured in iPaaS.com.
OroCommerce Requirements
A valid OroCommerce account with API access.
OAuth 2.0 credentials (Code, Client ID, Client Secret, and Redirect URL) configured for iPaaS.com API access.
Orders must contain valid data for all required mapping fields (Identifier, Internal Status, Customer User, and 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.
ID Format
When manually transferring an order, enter the OroCommerce order's internal identifier into the input field on the iPaaS.com manual sync page. The integration retrieves that order from OroCommerce and creates or updates the corresponding iPaaS.com transaction.
Example: 1042
External ID Format
The OroCommerce order identifier is mapped to the iPaaS.com transaction number through the TransactionNumber mapping (source Attributes_Identifier). This value uniquely identifies the order in iPaaS.com and is used to locate the existing transaction on subsequent updates so that changes are applied to the same record rather than creating a duplicate.
Custom Field Support
This flow supports the use of custom fields. To map data from an OroCommerce custom field into a custom field in iPaaS.com, create the field in both systems and then add a mapping. The supported entities for this workflow are Order, Order Address, and Order Line Item.
Creating Custom Fields in OroCommerce
In OroCommerce, click System > Entities > Entity Management.
Locate and select the module (entity) where you want to add the custom field (Order, Order Address, or Order Line Item).
Click Create Field and create a custom field.
Enter a unique Field Name and select a 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. |
We recommend selecting Serialized Field as the Storage Type to avoid manual schema updates.
Set the desired field type.
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).
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 (Transaction for order header, or the matching Order Address / Order Line module), and set the Data Type to the desired type.
The Description field is recommended but not required.
Click Save.
Mapping Custom Field Values
There are two supported ways to map custom fields:
One-to-one approach — used when no additional logic or manipulation is required for the value coming into iPaaS.com. Create the matching custom field on both the subscription and iPaaS.com levels, then add a new mapping that selects the custom field as the destination.
Dynamic Formula approach — used when a custom field needs to be resolved at run time, for example a field added after the initial setup. Select Dynamic Formula as the mapping type, select the destination custom field, and use the
GetValueFromCustomFieldconversion function in the source. The function accepts the additional-properties collection and the custom field name, and the name must be provided in the exact format used in OroCommerce.
Mapping Collection Status
Status: Enabled
Trigger Events: Create, Update
Detection: Polling. Orders are detected on the integration's polling schedule, which is controlled by the Order Poll Days setting in the subscription configuration. Adjust this setting to control how far back the integration looks for new and changed orders on each poll. There is no record-blocking filter on these collections, so all qualifying orders within the polling window are processed.
Duplicate or Conflicting Mappings
This is the only active workflow that transfers OroCommerce orders to iPaaS.com. The parent Order collection and its two child collections (Order Address and Order Line Item) together form the complete order transfer. There are no sibling Add-versus-Update collections for this entity; a single Add/Update collection handles both new orders and changes to existing orders, using the transaction number to determine whether to create or update.
Supported Child Collections
This flow has one parent collection and two child collections:
Parent: Add/Update OroCommerce Order TO iPaaS.com — maps the order header to the iPaaS.com transaction.
Child: Add/Update OroCommerce Order Address TO iPaaS.com — maps each order billing and shipping address to a transaction address.
Child: Add/Update OroCommerce Order Line Item TO iPaaS.com — maps each order line item to a transaction line item.
System Caveats
OroCommerce Caveats
In OroCommerce's B2B model, a Customer record represents a Company, and a CustomerUser record represents an individual Customer. The integration resolves the iPaaS.com company and customer identifiers from these OroCommerce relationships.
The OroCommerce Order record does not include an email address field. The integration resolves the order email from iPaaS.com using the customer or company relationship; see the
EmailAddressmapping for the fallback logic.OroCommerce exposes several discount fields whose API values can differ from what is shown in the OroCommerce UI. The integration reconciles these into a single discount amount; see the
DiscountAmountmapping.If a product SKU was modified to meet OroCommerce requirements during 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 your integration solution provider for more information.
iPaaS.com Caveats
To ensure orders sync correctly, confirm that all referenced products exist in iPaaS.com before the order is transferred.
The order line item Status is set to a static initial value of "Pending"; downstream processing in iPaaS.com may advance this status.
Setup Requirements
OroCommerce: Any custom fields to be mapped must exist on the relevant OroCommerce entity (Order, Order Address, or Order Line Item) before mapping. A schema update may be required for Table Column fields.
iPaaS.com: Matching custom fields must exist with names and modules that align with the OroCommerce fields.
Authentication: OroCommerce uses OAuth 2.0 (Authorization Code) to generate an access token, which authorizes all OroCommerce API requests during transfer operations. Store credentials securely within the iPaaS.com credential manager.
Authentication and Security
OroCommerce uses OAuth 2.0 (Authorization Code) to generate an access token that authorizes all OroCommerce API requests during transfer operations. The Code, Client ID, Client Secret, and Redirect URL are exchanged during the OAuth flow to obtain the token. These credentials are stored securely within iPaaS.com and are not exposed in mapping configuration. See the Connections and Settings documentation for credential entry.
Integration Flow
The integration processes OroCommerce orders as follows:
An order is created or updated in OroCommerce.
On its next scheduled poll, the integration detects the new or changed order within the window defined by the Order Poll Days setting.
iPaaS.com authenticates with OroCommerce using OAuth 2.0.
The OroCommerce company and customer associated with the order are resolved to their iPaaS.com identifiers.
Order header attributes are mapped to the iPaaS.com transaction (transaction number, type, status, totals, dates, and email).
Each order address (billing and shipping) is mapped to a transaction address through the Order Address child collection.
Each order line item is mapped to a transaction line item through the Order Line Item child collection.
The transaction is created or updated in iPaaS.com, using the transaction number to match an existing record.
Transfer status and any errors are logged in iPaaS.com.
Mappings
Parent: Add/Update OroCommerce Order TO iPaaS.com
This mapping collection maps the OroCommerce order header to an iPaaS.com transaction. It resolves the iPaaS.com company and customer from the order's OroCommerce relationships, maps order totals and timestamps, and sets the transaction number from the OroCommerce order identifier. Address and line item detail are handled by the two child collections.
Mapping Filter
This collection has no mapping filter. All orders detected within the polling window are processed.
Mapping Type | Source Field (OroCommerce) | Destination Field (iPaaS.com) | Description |
Dynamic Formula |
| CompanyId | (Required) Looks up and returns the internal iPaaS.com company id associated with the OroCommerce Customer (which represents a Company) linked to the order. If a match is found, the iPaaS.com company id is returned. |
Dynamic Formula |
| SystemId | (Required) Sets the iPaaS.com system id for the transaction from the integration's runtime system value, identifying the subscription the order originated from. This value is supplied by the integration at run time. |
Dynamic Formula |
| CustomerId | (Required) Looks up and returns the internal iPaaS.com customer id associated with the OroCommerce CustomerUser (which represents an individual Customer) linked to the order. If a match is found, the iPaaS.com customer id is returned. |
Field | Attributes_PoNumber | poNumber | (Recommended) Maps the purchase order number from the OroCommerce order to the iPaaS.com transaction. |
Static | Order | Type | (Required) Sets the iPaaS.com transaction type to "Order". |
Lookup Translation | Lookup Translation: Transaction (Order) Status | Status | (Required) Converts the OroCommerce internal order status into the iPaaS.com status format using the "Transaction (Order) Status To iPaaS.com" translation table. See the Lookup Translation Tables subsection below. |
Field | Attributes_TotalDiscountsAmount | DiscountAmount | (Recommended) Maps the order discount amount to the transaction. The integration sums the order's discount, shipping discount, and total-discounts amounts together with discounts found in the order subtotals, then takes the higher amount, to reconcile cases where OroCommerce returns different discount values via the API than are shown in the OroCommerce UI. |
Field | Attributes_SubtotalValue | Subtotal | (Recommended) Maps the order subtotal (line items before shipping and tax) from OroCommerce to the transaction. |
Field | OrderTaxAmount | TaxAmount | (Recommended) Maps the order tax amount to the transaction. This is a control field used only to populate the Tax Amount field at the transaction level. |
Field | Attributes_EstimatedShippingCostAmount | ShippingAmount | (Recommended) Maps the estimated shipping cost from the OroCommerce order to the transaction. |
Field | Attributes_TotalValue | Total | (Recommended) Maps the order grand total from OroCommerce to the transaction. |
Field | Attributes_CreatedAt | TransactionCreatedDateTime | (Recommended) Maps the OroCommerce order creation timestamp to the transaction's created date and time. |
Field | Attributes_UpdatedAt | TransactionUpdatedDateTime | (Recommended) Maps the OroCommerce order last-updated timestamp to the transaction's updated date and time. |
Dynamic Formula | See Email Resolution formula below | EmailAddress | (Recommended) Resolves the order email address. Because the OroCommerce Order record has no email field, the integration first tries the customer email via the CustomerUser relationship, then falls back to the company email, and finally to a placeholder email. See the formula and notes below. |
Dynamic Formula | See Total Quantity formula below | TotalQty | (Recommended) Calculates and returns the total quantity of items across the order's line items. If the order has no line items, the total is zero. See the formula below. |
Dynamic Formula |
| AlexTestCustomFieldOrderHeader | (Example) Demonstrates how to map an order header custom field from OroCommerce to iPaaS.com using the Dynamic Formula type and the value-from-custom-field conversion function. A one-to-one custom field mapping is preferred where possible. Placeholder value — replace during implementation: replace |
Field | Attributes_Identifier | TransactionNumber | (Required) Maps the OroCommerce order identifier to the iPaaS.com transaction number, which uniquely identifies the order in iPaaS.com. |
Email Resolution Formula (EmailAddress)
Because the OroCommerce Order record does not contain an email address, the integration resolves it in two steps and falls back to a placeholder if neither lookup succeeds. The OroCommerce B2B model treats Customers as Companies, and the email address is not part of the Customer (Company) object schema in OroCommerce, so the company email is retrieved from iPaaS.com rather than directly from OroCommerce.
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@email.com";Placeholder value — replace during implementation: the formula returns email@email.com only as a last-resort fallback when no customer or company email can be located. If your orders should always carry a real email, ensure the related customer or company in iPaaS.com has a valid email so this fallback is not used, or adjust the fallback value to one appropriate for your implementation.
Total Quantity Formula (TotalQty)
var sum = 0;
if (LineItems?.Count > 0) {
foreach (var item in LineItems){
sum = sum + item.Attributes_Quantity;
}
}
return sum;Lookup Translation Tables
The Status mapping uses the "Transaction (Order) Status To iPaaS.com" lookup translation table to convert each OroCommerce internal order status into the corresponding iPaaS.com status.
Source Value (OroCommerce) | Destination Value (iPaaS.com) | Notes |
— | — | Review the live "Transaction (Order) Status To iPaaS.com" translation collection in the subscription for the current source-to-destination value pairs. |
Child: Add/Update OroCommerce Order Address TO iPaaS.com
This child collection maps an OroCommerce order's billing and shipping addresses to iPaaS.com transaction addresses. It runs under the parent Order collection. The integration control fields IsPrimaryBilling and IsPrimaryShipping determine which address is treated as the primary billing or shipping address when the address is synced into iPaaS.com.
Mapping Filter
This collection has no mapping filter. All addresses on a processed order are transferred.
Mapping Type | Source Field (OroCommerce) | Destination Field (iPaaS.com) | Description |
Field | Attributes_Street | Address1 | (Required) Maps the first address line from the OroCommerce order address to the transaction address. |
Field | Attributes_Street2 | Address2 | (Recommended) Maps the second address line (suite, unit) from the OroCommerce order address to the transaction address. |
Field | Attributes_City | City | (Required) Maps the city from the OroCommerce order address to the transaction address. |
Field | Attributes_PostalCode | PostalCode | (Required) Maps the postal or ZIP code from the OroCommerce order address to the transaction address. |
Field | Relationships_Country_Id | Country | (Required) Maps the country from the OroCommerce order address to the transaction address. |
Field | Attributes_FirstName | FirstName | (Recommended) Maps the recipient first name from the OroCommerce order address to the transaction address. |
Field | Attributes_LastName | LastName | (Recommended) Maps the recipient last name from the OroCommerce order address to the transaction address. |
Field | IsPrimaryBilling | IsPrimaryBilling | (Recommended) IsPrimaryBilling is a special integration control field rather than a standard OroCommerce data field. It determines which billing address is used when the address is synced into iPaaS.com. |
Field | IsPrimaryShipping | IsPrimaryShipping | (Recommended) IsPrimaryShipping is a special integration control field rather than a standard OroCommerce data field. It determines which shipping address is used when the address is synced into iPaaS.com. |
Dynamic Formula |
| AlexTestCustomFieldOrderAddress | (Example) Demonstrates how to map an order address custom field from OroCommerce to iPaaS.com using the Dynamic Formula type and the value-from-custom-field conversion function. A one-to-one custom field mapping is preferred where possible. Placeholder value — replace during implementation: replace |
Field | Relationships_Region_Id | Region | (Recommended) Maps the state or region from the OroCommerce order address to the transaction address. |
Child: Add/Update OroCommerce Order Line Item TO iPaaS.com
This child collection maps each OroCommerce order line item to a line item on the iPaaS.com transaction. It runs under the parent Order collection.
Mapping Filter
This collection has no mapping filter. All line items on a processed order are transferred.
Mapping Type | Source Field (OroCommerce) | Destination Field (iPaaS.com) | Description |
Field | Attributes_ProductSku | Sku | (Required) Maps the product SKU from the OroCommerce order line item to the transaction line item, identifying the product ordered. |
Field | Attributes_ProductName | Description | (Recommended) Maps the product name from the OroCommerce order line item to the transaction line item description. |
Field | Attributes_Quantity | Qty | (Required) Maps the ordered quantity from the OroCommerce order line item to the transaction line item. |
Field | Attributes_RowTotalAfterDiscount | ExtendedPrice | (Recommended) Maps the line total after discounts from the OroCommerce order line item to the transaction line item extended price. |
Field | Attributes_Quantity | QtyShipped | (Recommended) Maps the shipped quantity from the OroCommerce order line item. It is mapped from the ordered quantity, so it reflects full fulfillment unless partial shipments are tracked separately. |
Static | Product | Type | (Required) Sets the transaction line item type to "Product". |
Static | Pending | Status | (Recommended) Sets the initial transaction line item status to "Pending". |
Field | Attributes_Value | UnitPrice | (Required) Maps the per-unit price from the OroCommerce order line item to the transaction line item. |
Error Handling
"Product not found by Sku" — A line item references a product SKU (for example,
Product not found by Sku: 7BS71 provided.) that does not exist in iPaaS.com. Resolution: Confirm that all products on the order exist in iPaaS.com before the order is transferred.Email could not be resolved — Neither the customer nor the company email could be located, and the transaction received the placeholder fallback email. Ensure the related customer or company in iPaaS.com has a valid email so the fallback is not used.
SKU mismatch on line items — A product SKU was modified to meet OroCommerce requirements during product or variant mapping and no longer matches the iPaaS.com SKU. Convert the OroCommerce SKU back to the iPaaS.com SKU within the transaction line SKU mapping. Consult your integration solution provider for guidance.
Testing & Validation
Test Scenarios
Create order: Create a new order in OroCommerce. After the next poll, confirm a transaction is created in iPaaS.com with the correct transaction number, totals, addresses, and line items.
Update order: Update an existing order in OroCommerce. After the next poll, confirm the existing iPaaS.com transaction is updated in place rather than duplicated.
Billing and shipping addresses: Create an order with distinct billing and shipping addresses. Confirm both addresses transfer and that the primary billing and shipping flags are set correctly.
Multiple line items: Create an order with several line items. Confirm each line item transfers with the correct SKU, quantity, unit price, and extended price, and that the order header total quantity matches the sum of the line item quantities.
Email fallback: Create an order for a customer or company without an email on file in iPaaS.com. Confirm the transaction email reflects the resolution logic, including the placeholder fallback when no email is found.
Order without addresses or line items: Sync an order that has no addresses and no line items. Confirm the parent transaction is created in iPaaS.com and the child collections are skipped.
Re-sync existing order: Sync an order that already exists in iPaaS.com. Confirm the record is updated rather than duplicated.
Missing product SKU (failure case): Sync an order containing a line item with a SKU that does not exist in iPaaS.com. Confirm the sync fails with a "Product not found by Sku" error and that no incomplete records are created.
Validation Checklist
The order's customer and company resolve to the correct iPaaS.com identifiers.
Transaction number is populated from the OroCommerce order identifier.
Order totals (subtotal, discount, tax, shipping, and grand total) match the OroCommerce order.
Created and updated timestamps reflect the OroCommerce order.
Each billing and shipping address transfers with the correct primary flags.
Each line item transfers with SKU, quantity, unit price, and extended price, and the header total quantity equals the sum of line item quantities.
Any mapped custom fields exist in both OroCommerce and iPaaS.com with matching names and modules.
Additional Notes
This workflow is polling-based; orders are picked up on the integration's schedule controlled by the Order Poll Days setting, not in real time.
The Order custom field example mappings (
AlexTestCustomFieldOrderHeaderandAlexTestCustomFieldOrderAddress) are demonstration mappings. Replace the custom field names with fields that exist in your OroCommerce instance, or remove the mappings if they are not needed.In OroCommerce's B2B model a Customer represents a Company and a CustomerUser represents an individual Customer; the integration resolves the iPaaS.com company and customer identifiers accordingly.
Dynamic formulas must return valid output; null or invalid returns may cause transfer failures.