Summary

When a Transaction is created or updated in iPaaS.com with Type = "Invoice", the corresponding invoice is created or updated in OroCommerce. This flow runs FROM iPaaS.com TO OroCommerce on the Create and Update triggers. The parent collection writes the invoice header, and its child collection writes the invoice's line items. The related company and customer user are transferred automatically as prerequisites, and after a successful transfer the OroCommerce invoice id is saved as the external id so re-processing updates the existing invoice instead of creating a duplicate.

ID Format

When manually transferring an invoice from iPaaS.com, enter the valid iPaaS.com Transaction internal ID into the input field on the iPaaS.com manual sync page.

Example: 162436

External ID Format

The OroCommerce-returned id is saved as the external id, with a suffix so it does not collide with other entity types that share the same numeric id space:

Invoice: the invoice id followed by _invoice.
Invoice line item: the line item id.

Custom Field Support

Custom fields are supported on the invoice. There is no special configuration required for this flow — values are carried through the standard custom-field mapping when custom fields are configured in the subscription.

Mapping Collection Status

Enabled. Trigger events: Create and Update. Direction: From iPaaS.com.

Duplicate or Conflicting Mappings

No other mapping collection triggers an invoice from the iPaaS.com transaction flow, so there is no conflicting collection for this entity at this time.

Collision Handling

OroCommerce rejects a second invoice that reuses an existing invoice number. Configure collision handling on the parent collection so re-processing a transaction updates the existing invoice rather than attempting to create a duplicate:

Remap and Link / Update and Link — the re-processed transaction is matched to the existing OroCommerce invoice (by invoice number) and updated; no duplicate is created.
Error — a re-processed transaction whose invoice already exists is rejected with a conflict (see Error Handling, "Duplicate Invoice Number").

Supported Child Collections

Add/Update OroCommerce Invoice Line Item From iPaaS.com — writes the invoice's line items, linking each line to its parent invoice and mapping position, line number, description, quantity, unit price, and line total. Only lines with a quantity greater than zero are written. New lines added to an existing invoice are created and linked; existing lines are updated in place.

OroCommerce Caveats

Invoice number must be unique. Reusing an existing number is rejected as a conflict — configure collision handling to update the existing invoice instead.
Internal status accepts only draft or posted. Any other value is rejected. The status mapping defaults unrecognized statuses to draft to guard against this.
Payment status is read-only. It is calculated by OroCommerce; any value sent for it is ignored, so it should not be mapped.
Posting an invoice can generate a PDF. When the internal status becomes posted, OroCommerce may auto-generate an invoice PDF. Reverting a posted invoice to draft is accepted, but the previously generated PDF remains attached — reverting does not remove it.
Referenced entities must already exist. The organization, owner (user), and website are resolved by lookup and are not created by this flow.

iPaaS.com Caveats

The customer must be resolvable. The transaction must carry a Company ID, Customer ID, or Email Address that maps to an existing OroCommerce customer or customer user, or the invoice will not be created.
Line items are written by the child collection. This flow writes the invoice header; line detail is mapped separately and requires a quantity greater than zero.

Setup Requirements

Before configuring this flow, ensure the following exist in OroCommerce, since they are resolved by lookup and are not created by the mapping:

Organization — looked up by name (placeholder: "iPaaS.com").
Owner / User — looked up by username (placeholder: "admin").
Website — looked up by name (placeholder: "Default").
Customer (Company) and/or Customer User — the customer the invoice is billed to, resolvable by Company ID, Customer ID, or Email Address.
API credentials with permission to create and update invoices and invoice line items.

The internal status options draft and posted are built into OroCommerce and require no setup.

Integration Flow

A Transaction is created or updated in iPaaS.com with Type = "Invoice".
The Mapping Filter confirms the transaction qualifies as an invoice.
The customer name is resolved by a prioritized lookup — Company ID, then Customer ID, then Email Address. If none resolve, the transfer stops and the invoice is not created.
The related company and customer user are transferred automatically as prerequisites, and the required relationships (Owner, Organization, Website, Customer, Customer User) are resolved.
Invoice attributes are mapped (invoice date, currency, total, invoice number, customer name, Bill To, Ship To, shipping method, memo).
The internal status is derived from the transaction status (draft or posted).
The invoice is created or updated in OroCommerce (created on first sync, updated on subsequent syncs using the stored external id).
The OroCommerce invoice id is saved as the external id in iPaaS.com.
Each qualifying transaction line (quantity greater than zero) is written by the child collection and linked to the invoice.
Transfer status and any errors are logged in iPaaS.com.

Mappings

Parent: Add/Update OroCommerce Invoice From iPaaS.com

Mapping Filter: only transactions where Type = "Invoice" are processed; all other types are silently skipped.

Destination Field	Type	Source	Description
Type	Static	"invoices"	(Required) Routes the transfer to the invoice logic; do not change.
Id	Dynamic Formula	existing external id lookup	Resolves the existing OroCommerce invoice id (if any) to determine create vs. update.
Invoice_InvoiceNumber	Field	TransactionNumber	Unique; the key used for duplicate detection.
Invoice_InvoiceDate	Field	TransactionCreatedDateTime	(Required) The date the invoice was issued.
Invoice_Currency	Static	"USD"	(Required) ISO-4217 currency code. Placeholder — replace for your environment.
Invoice_TotalAmount	Field	Total	(Required) The invoice total.
Invoice_CustomerName	Dynamic Formula	Company ID → Customer ID → Email	(Required) Prioritized customer-name lookup; blocks the invoice if none resolve.
Invoice_BillTo	Dynamic Formula	primary billing address	Concatenates the primary billing address fields, skipping blanks.
Invoice_ShipTo	Dynamic Formula	primary shipping address	Concatenates the primary shipping address fields, skipping blanks.
Invoice_ShippingMethod	Static	"UPS"	Shipping method text. Placeholder — replace for your environment.
Invoice_Memo	Static	"Invoice Memo1"	Printed memo text. Placeholder — replace for your environment.
Invoice_Relationships_Owner_Id / _Type	Dynamic Formula / Static	user by username / "users"	(Required) Owner user lookup. Placeholder username "admin" — replace.
Invoice_Relationships_Organization_Id / _Type	Dynamic Formula / Static	organization by name / "organizations"	(Required) Organization lookup. Placeholder name "iPaaS.com" — replace.
Invoice_Relationships_Website_Id / _Type	Dynamic Formula / Static	website by name / "websites"	(Required) Website lookup. Placeholder name "Default" — replace.
Invoice_Relationships_Customer_Id / _Type	Dynamic Formula / Static	company external id / "customers"	Resolves the OroCommerce customer (company) from the Company ID; empty if none.
Invoice_Relationships_CustomerUser_Id / _Type	Dynamic Formula / Static	Customer ID → Email / "customerusers"	Resolves the OroCommerce customer user from Customer ID, falling back to Email.
Invoice_Relationships_InternalStatus_Id / _Type	Dynamic Formula / Static	status translation / "invoiceinternalstatuses"	Complete/Shipped → posted; all others → draft.

Child: Add/Update OroCommerce Invoice Line Item From iPaaS.com

Mapping Filter: only lines with quantity greater than zero are processed.

Destination Field	Type	Source	Description
Type	Static	"invoicelineitems"	(Required) Routes the transfer to the line item logic; do not change.
InvoiceLineItem_Position	Field	SequenceNumber	(Required) Unique within the invoice; sets display order.
InvoiceLineItem_LineNumber	Dynamic Formula	transaction line id	(Required) A unique line number per line.
InvoiceLineItem_Description	Field	Description	(Required) Line description.
InvoiceLineItem_Note	Field	Description	Same source as the description by default; remap for a separate note.
InvoiceLineItem_Quantity	Field	Qty	(Required) Line quantity.
InvoiceLineItem_UnitOfQuantity	Static	"piece"	(Required) Unit of measure. Placeholder — replace for your environment.
InvoiceLineItem_UnitPrice	Field	UnitPrice	(Required) Unit price.
InvoiceLineItem_RowTotal	Field	ExtendedPrice	(Required) Line total (quantity × unit price).

Error Handling

Missing Customer Name. When Company ID, Customer ID, and Email Address all fail to resolve to a customer, the transfer fails with the message "Invoice can not be created because it does not have valid Customer Name." Ensure the transaction carries a valid Company ID, Customer ID, or Email Address that maps to an existing OroCommerce customer or customer user.
Duplicate Invoice Number. Creating an invoice with a number that already exists in OroCommerce is rejected as a conflict. Ensure transaction numbers are unique, or configure collision handling to update the existing invoice.
Invalid Internal Status. OroCommerce accepts only draft or posted for the internal status; any other value is rejected. Confirm the status mapping only ever returns draft or posted, defaulting unrecognized statuses to draft.

Validation Rules

A relationship id is only applied when its matching type is also mapped. For example, if the owner id is mapped, the owner type must also be mapped, or the relationship is omitted. This applies to Owner, Organization, Website, Customer, Customer User, and Internal Status.

Testing & Validation

Test Scenarios

Create Invoice. Sync a new Transaction with Type = "Invoice" and a valid Company/Customer/Email reference. The invoice is created in OroCommerce and its id is saved as the external id.
Update Existing Invoice. Update the transaction (for example, change Status from Pending to Complete). The change is reflected on the same invoice without a duplicate, and the internal status updates from draft to posted.
Create Invoice with Line Items. Sync a transaction with one or more lines where quantity is greater than zero. The invoice is created with the corresponding line items linked via the child collection.
Missing Customer Name (failure). Sync a transaction where Company ID, Customer ID, and Email Address all fail to resolve. The transfer fails with the missing-customer-name error.
Duplicate Invoice Number (failure). Attempt to create an invoice with a transaction number that already exists, without collision handling. The transfer fails with a conflict.
Zero-Quantity Line (exclusion). Sync a line with quantity zero. The line is not created, and no error is raised for it.

Validation Checklist

All mandatory fields are mapped (Type, invoice number, invoice date, currency, total, customer name).
All required relationship fields have both id and type mapped (Owner, Organization, Website).
The referenced organization, owner, website, and customer exist in OroCommerce.
The status mapping covers all expected source statuses and has a safe default (draft).
The child collection's quantity-greater-than-zero filter matches your expected line-item behavior.
Collision handling is configured if invoice number conflicts are possible.
The placeholder values (organization, owner, website, currency, shipping method, memo, unit of quantity) have been replaced for your environment.

Additional Notes

Payment status is read-only in OroCommerce and should not be mapped.
Moving the internal status to posted can auto-generate an invoice PDF; reverting to draft leaves that PDF attached.
Ensure the status mapping falls back to a safe default (draft) for any unrecognized source status.

OroCommerce Invoice From iPaaS.com Mapping Documentation