Skip to main content

iPaaS.com to Shopify Order Mapping Documentation

How iPaaS.com Transaction data creates and updates Shopify orders, including the order header and its child records.

Summary

Orders can be created and updated in Shopify from iPaaS.com Transaction data. The order tree is led by the Add/Update Shopify Order FROM iPaaS.com parent collection, which writes the order header (customer, totals, financial status, currency, notes, and the default shipping line), and five child collections that complete the order: line items, tax lines, and the shipping, billing, or combined address. A sixth child, Add Shopify Order Tracking-Only Fulfillment FROM iPaaS.com, adds tracking to an existing order when tracking-only updates are turned on. The tree supports the Add/Update sync type — on Add a new Shopify order is created and linked by saving the Shopify order id; on Update the linked order is edited. Before creating, the integration can match an existing Shopify order by a transaction-number metafield so the same order is updated instead of duplicated.

For systems that send shipment tracking to iPaaS.com as an order update, the tree can also run as a tracking-only update: it adds a Shopify fulfillment for each new tracking record on the transaction and leaves the order itself unchanged. This is turned off in the default template (see Tracking-Only Updates).

ID Format

Manual Sync ID.

On the iPaaS.com Manual Sync page, enter the iPaaS.com Transaction id to send that order to Shopify.

External ID.

After a successful sync, the Shopify order id is saved as the external id on the iPaaS.com Transaction. Subsequent updates use that link to edit the same Shopify order rather than creating a new one.

Deleted Record Support

Order deletion is not performed by this collection tree. Removing or cancelling an order in Shopify is handled outside this FROM-iPaaS flow; deletions in iPaaS.com do not propagate to Shopify through these collections.

Mapping Collection Status

  • Status: Enabled (parent and all six children; the tracking child only acts when TrackingOnly is true)

  • Trigger Events: the iPaaS.com Transaction (Order) Create and Update outbound triggers (enabled per Setup Requirements below). The child collections have no independent trigger — they run as part of the parent order transfer.

Duplicate or Conflicting Mappings

Opposite-direction collections.

This tree creates and updates orders in Shopify. The reverse direction — transferring the same Shopify orders into iPaaS.com — is handled by the inbound order collections, including Add Shopify Order Header TO iPaaS.com, Update Shopify Order Header TO iPaaS.com, and Add Shopify Plus Order Header TO iPaaS.com. Decide which system is the source of truth for orders before enabling automatic transfers in both directions so a record is not written back and forth.

Address collections are mutually exclusive.

The three address children — shipping-only, billing-only, and the combined billing-and-shipping fallback — are mutually exclusive by filter. Each iPaaS.com address flows through exactly one of them based on its primary billing/shipping flags.

Important: Review and customize the mapping collection filters and the Add/Update settings to match your business rules before enabling automatic order transfers. If you use the default (unmodified) template mappings, existing order data may be overwritten.

Supported Child Collections

Parent Collection: Add/Update Shopify Order FROM iPaaS.com (284677)

  • Add/Update Shopify Order Lines FROM iPaaS.com (284676) — order line items, linked to Shopify products/variants by SKU.

  • Add/Update Shopify Order Tax Lines FROM iPaaS.com (284675) — tax amount, rate, and authority.

  • Add/Update Shopify Order Shipping Address FROM iPaaS.com (284673) — shipping-only address.

  • Add/Update Shopify Order Billing Address FROM iPaaS.com (284674) — billing-only address.

  • Add/Update Shopify Order Billing and Shipping Address FROM iPaaS.com (284678) — combined-address fallback.

  • Add Shopify Order Tracking-Only Fulfillment FROM iPaaS.com: one Shopify fulfillment per new tracking record; runs only when TrackingOnly is true.

Tracking-Only Updates

Some systems send shipment tracking to iPaaS.com as an update of the order rather than as a separate tracking event. The parent collection's TrackingOnly mapping covers that case: when it is true, an update of the order adds tracking only. The integration creates one Shopify fulfillment for each new tracking record on the transaction, through Add Shopify Order Tracking-Only Fulfillment FROM iPaaS.com, and does not send the order itself to Shopify.

Turning it on.

The default template ships the TrackingOnly formula turned off: it returns nothing, so every order transfers exactly as before. To turn it on, remove the // from the two example lines in the formula and delete the return null; line. The example sets TrackingOnly to true only when the transaction is already linked to a Shopify order, so new orders are still created normally and their tracking is added on their next update.

How tracking is added.

  • One fulfillment per new tracking record. A tracking record whose tracking number is already on the Shopify order is skipped at the locations where it was fulfilled, whatever its quantities. A new shipment must arrive as a new tracking record with its own number.

  • Quantities are running totals. Each tracking record's iPaaSLineItemIdAndQty custom field lists {transactionId}|{lineId}-{quantity} entries, where the quantity is the total shipped so far for that order line. Only the amount not yet fulfilled in Shopify is fulfilled, up to what Shopify can still fulfill. For example, with a line ordered 5: tracking record T1 says 4 and fulfills 4; tracking record T2 says 5 and fulfills the remaining 1.

  • Lines are matched by their order-line link. The template's LineItems formula turns each iPaaSLineItemIdAndQty entry into the linked Shopify order line; an entry whose line is not linked to the Shopify order is skipped. A custom LineItems formula can supply a SKU instead: the line is then matched on SKU, trying the unit-suffixed SKU first when the formula also supplies TrackingLineItem_SellingUnit for products sold in alternate units of measure. A SKU that matches more than one line on the order is skipped.

  • One fulfillment per location. When a shipment covers lines assigned to different Shopify locations, one fulfillment is created per location, each with the same tracking number. If one of them fails, a re-sync creates the missing location's fulfillment.

  • Fulfillments from the separate tracking event count. Fulfillments added by Add Shopify Fulfillment FROM iPaaS.com are recognized: their tracking numbers are skipped and their quantities count toward the running totals.

  • Fully fulfilled orders. Once every item is fulfilled, a new tracking record has nothing left to fulfill; the transfer completes without an error.

  • No echo. The integration ignores the order-update notification Shopify sends for each fulfillment it creates, so adding tracking does not import the order back into iPaaS.com as a change. A transfer that creates nothing ignores nothing.

What changes while it is on.

  • Order edits are not sent. For a linked order, changes made in iPaaS.com (for example notes, addresses, or metafields) are not written to Shopify. Turn it on only when Shopify does not need order edits after the order is created.

  • An order is never created. If the linked order is not found in Shopify, the transfer fails and no order is created.

  • Tracking records without line items are skipped. A tracking record without iPaaSLineItemIdAndQty (for example one added by another system) is skipped by the collection filter: it creates nothing and records no error.

  • Create only. Existing fulfillments are never updated or cancelled; a changed tracking number or quantity on an existing tracking record is not sent to Shopify.

System Caveats

Shopify Caveats.

  • A line item is mandatory. Shopify will not create an order without at least one line item; the parent filter enforces this.

  • Shipping lines set the delivery method and are immutable. Shopify decides an order's delivery method solely from the presence of a shipping line at creation. Map ShippingLine_Title and ShippingLine_Price or Shopify marks the order "Shipping not required" even when a shipping address exists. Shipping lines cannot be changed after the order is created.

  • Financial status is a case-sensitive enum. Only authorized, paid, partially_paid, pending, partially_refunded, refunded, and voided are accepted; the template maps the iPaaS.com Status to these values with a formula.

  • Region / country values are not validated on order addresses. Invalid values are accepted silently and stored.

iPaaS.com Caveats.

  • External-id link required. The Shopify order id is saved as the external id so subsequent updates edit the same Shopify order rather than creating a duplicate.

  • Duplicate detection depends on the metafield preset. Without the transaction-number metafield created in Shopify and configured in the matching preset, an unlinked transaction cannot be matched to an existing Shopify order and a re-sync can create a duplicate.

  • Customer link is not auto-created. The order's customer is resolved from the existing iPaaS.com-to-Shopify customer link; if the customer is not yet linked, the order is created without that customer association.

Setup Requirements

iPaaS.com Configuration.

Automatic transfers are enabled in the subscription configuration's Outbound Data Flows section. Subscribe to the iPaaS.com Transaction (Order) Create and Update outbound triggers that should dispatch this collection to Shopify. No automatic transfers occur until those outbound subscriptions are enabled. Orders can also be sent on demand from the Manual Sync page using the iPaaS.com Transaction id.

Two subscription presets control prerequisite behavior:

  • SHOPIFY METAFIELD FOR TRANSACTION NUMBER MATCHING: set to the namespace.key of the Shopify order metafield used for duplicate-order detection.

  • Create Line Item Product as Prerequisite — when enabled, missing line-item products are created in Shopify automatically before the order is written.

Shopify Configuration.

To enable duplicate-order detection, create an Order metafield in advance and make it filterable:

  1. Go to Shopify Admin → Settings → Custom data → Orders.

  2. Click Add definition.

  3. Give it a clear name (for example, iPaaS-Transaction-Number) and set the type to Single line text.

  4. Under Options, enable Filter on the order list and in the Admin API.

  5. Save, then copy the generated Namespace and Key.

  6. Paste the value as namespace.key into the SHOPIFY METAFIELD FOR TRANSACTION NUMBER MATCHING preset in your iPaaS.com subscription.

The Shopify connection must be authorized with permission to read and write orders.

Integration Flow

  1. Resolve the Shopify order for the iPaaS.com Transaction from the saved external-id link.

  2. If no external id is saved and the transaction-number metafield preset is configured, search Shopify for an order whose metafield matches this transaction number; a match is linked so the order is updated rather than duplicated.

  3. If the Create Line Item Product as Prerequisite preset is enabled, create any missing line-item products/variants in Shopify automatically; a failed product transfer fails the order.

  4. On Add: create the Shopify order with the mapped header values plus the child line, tax, and address records, and save the Shopify order id as the external-id link.

  5. On Update: edit the linked Shopify order.

  6. When TrackingOnly is true: steps 4 and 5 are replaced. The integration loads the Shopify order, its existing fulfillments, and its fulfillment orders; skips tracking numbers already on the order at that location; creates one fulfillment per new tracking record (per location) for the quantities not yet fulfilled; and returns the order so the link is kept. The order itself is not created or edited.

Mappings

Add/Update Shopify Order FROM iPaaS.com (Parent)

Mapping filter: Type == "Order" && Lines?.Count > 0

Description: Writes the order header and routes child line, tax, and address records. Only transactions of type Order with at least one line item are processed.

Mapping Type

Source (iPaaS.com)

Destination (Shopify)

Description

Static

test desc from mappings

global.Order-Desc (custom field)

Placeholder value — replace during implementation: replace the sample value with a real source, or remove the mapping.

Field

TransactionNumber

iPaaS Transaction Number (custom field)

Powers duplicate-order detection via the matching metafield.

Field

SystemId

iPaaS Transaction System ID (custom field)

Source system id, stored for traceability.

Field

Status

iPaaS Transaction Status (custom field)

Raw source status, stored for reference.

Field

ShippingAmount

iPaaS Transaction Shipping Amount (custom field)

Reference.

Field

Total

iPaaS Transaction Total (custom field)

Reference.

Field

TaxAmount

iPaaS Transaction Tax Amount (custom field)

Reference.

Field

EmailAddress

Email

Recommended; associates the order with a customer.

Dynamic Formula

Notes collection

Note

Concatenates all non-empty notes, newline-separated.

Field

TotalQty

ItemsTotal

Total item quantity.

Field

Total

TotalPrice

Order total.

Field

Subtotal

SubtotalPrice

Order subtotal.

Field

TaxAmount

TotalTax

Header tax total.

Dynamic Formula

Status

FinancialStatus

Maps to Shopify's case-sensitive financial-status enum.

Dynamic Formula

Status

Confirmed

True when status is Complete or Shipped.

Field

DiscountAmount

TotalDiscounts

Order discount total.

Dynamic Formula

CustomerId

CustomerId

Resolves the linked Shopify customer id; not auto-created.

Field

ShippingAmount

ShippingPrice

Header shipping amount.

Static

USD

Currency

Placeholder value — replace during implementation: change if your store is not USD.

Dynamic Formula

"Default Shipping Line Title" custom field, else Default Shipping

ShippingLine_Title

Required to create a shipping line / delivery method.

Field

ShippingAmount

ShippingLine_Price

Required, with the title, to create the shipping line.

Dynamic Formula

Transaction link (example, turned off)

TrackingOnly

Optional. True makes an update add tracking only and leaves the order unchanged. Ships returning nothing; the commented example returns true when the transaction is already linked to a Shopify order. See Tracking-Only Updates.

Add Shopify Order Tracking-Only Fulfillment FROM iPaaS.com (Child)

Mapping filter: processes a tracking record only when its iPaaSLineItemIdAndQty custom field has a value; records without it are skipped without an error. Runs only when the parent sets TrackingOnly to true; every tracking record on the transaction is evaluated each time.

Mapping Type

Source (iPaaS.com)

Destination (Shopify)

Description

Field

TrackingNumber

TrackingNumber

Required. Identifies the shipment; a number already on the Shopify order at that location is skipped.

Dynamic Formula

iPaaSLineItemIdAndQty custom field

LineItems

Required. Shipped lines as {transactionId}|{lineId}-{quantity} entries, for example 159484|390776-2. The quantity is the running total shipped for the line.

Dynamic Formula

ShippingMethodDescription (carrier map)

TrackingCompany

Recommended. Returns FedEx when the description contains fedex, otherwise the description. Placeholder value — replace during implementation: extend with your carrier names.

Static

false

NotifyCustomer

Optional. Whether Shopify emails the customer for each new shipment.

Add/Update Shopify Order Lines FROM iPaaS.com (Child)

Mapping filter: resolves the line SKU — with its selling unit when the line carries a SellingUnit custom field — to a Shopify variant; processes the line only when a match is found (adjustable for free-form items).

Mapping Type

Source (iPaaS.com)

Destination (Shopify)

Description

Dynamic Formula

Sku (+ SellingUnit)

VariantId

Resolves the Shopify variant id from the SKU, unit-aware: a SellingUnit custom field is appended to the base SKU (for example PBVANILLA^BOX) so unit lines link to the correct variant; the base SKU is used unchanged otherwise.

Field

Description

Title

Line description.

Field

Qty

Quantity

Ordered quantity.

Dynamic Formula

Sku (+ SellingUnit)

Sku

Sets the SKU written to the order line so it matches the variant: a SellingUnit custom field is appended to the base SKU (for example PBVANILLA^BOX); the base SKU is used unchanged otherwise.

Dynamic Formula

Sku

ProductId

Resolves the Shopify product id from the SKU.

Dynamic Formula

Type

GiftCard

True when the line type is GiftCard.

Field

UnitPrice

Price

Unit price.

Field

DiscountAmount

TotalDiscount

Line discount.

Add/Update Shopify Order Tax Lines FROM iPaaS.com (Child)

Mapping filter: none.

Mapping Type

Source (iPaaS.com)

Destination (Shopify)

Description

Field

Amount

Price

Tax amount.

Field

TaxPercent

Rate

Tax rate.

Field

Authority

Title

Tax authority name.

Add/Update Shopify Order Shipping Address FROM iPaaS.com (Child)

Mapping filter: IsPrimaryShipping && !IsPrimaryBilling

Mapping Type

Source (iPaaS.com)

Destination (Shopify)

Description

Static

FALSE

IsBillingAddress

Not a billing address.

Static

TRUE

IsShippingAddress

The shipping address.

Field

FirstName

FirstName

Field

Address1

Address1

Field

City

City

Field

PostalCode

Zip

Field

Region

Province

Not validated by Shopify.

Field

Country

Country

Not validated by Shopify.

Field

LastName

LastName

Field

Address2

Address2

Field

Company

Company

Add/Update Shopify Order Billing Address FROM iPaaS.com (Child)

Mapping filter: IsPrimaryBilling && !IsPrimaryShipping

Mapping Type

Source (iPaaS.com)

Destination (Shopify)

Description

Static

TRUE

IsBillingAddress

The billing address.

Static

FALSE

IsShippingAddress

Not a shipping address.

Field

FirstName

FirstName

Field

Address1

Address1

Field

City

City

Field

PostalCode

Zip

Field

Region

Province

Not validated by Shopify.

Field

Country

Country

Not validated by Shopify.

Field

LastName

LastName

Field

Address2

Address2

Field

Company

Company

Add/Update Shopify Order Billing and Shipping Address FROM iPaaS.com (Child)

Mapping filter: IsPrimaryBilling && IsPrimaryShipping — fallback when a single combined address carries both flags; applied to both order slots.

Mapping Type

Source (iPaaS.com)

Destination (Shopify)

Description

Static

TRUE

IsBillingAddress

Combined address used for billing.

Static

TRUE

IsShippingAddress

Combined address used for shipping.

Field

FirstName

FirstName

Field

Address1

Address1

Field

City

City

Field

PostalCode

Zip

Field

Region

Province

Not validated by Shopify.

Field

Country

Country

Not validated by Shopify.

Field

LastName

LastName

Field

Address2

Address2

Field

Company

Company

Error Handling

  • No line items: transactions without lines are filtered out — an order cannot be created in Shopify.

  • Wrong type: transactions whose type is not Order are filtered out.

  • Failed prerequisite product: when line-item product creation is enabled and a product transfer fails, the whole order transfer fails.

  • Unresolvable SKU: by default an order line whose SKU — with its selling unit, when present — does not match a Shopify variant is skipped; relax the line filter to allow free-form items.

  • Invalid financial status: an unrecognized source status maps to null financial status.

  • Tracking-only order not found: the linked Shopify order no longer exists, so tracking cannot be added and no order is created (SHPY-EXTN-1051).

  • Tracking-only without an order id: a tracking-only transfer has no valid Shopify order id (SHPY-VALD-1028).

  • Tracking-only on a return: TrackingOnly cannot be combined with Type = return (SHPY-VALD-1027).

  • Fulfillment orders unavailable: the connection lacks the fulfillment order scopes (SHPY-EXTN-1052).

  • Some tracking failed: one or more fulfillments could not be created; the others were created and a re-sync creates only the missing ones (SHPY-EXTN-1053).

See Shopify Error Messages for each code's resolution.

Testing & Validation

Test Scenarios.

  • Create a new Transaction of type Order with at least one line and sync it; verify a new Shopify order is created and the Shopify order id is saved as the external id.

  • Re-sync a transaction that already exists in Shopify (matched by the transaction-number metafield) and confirm it updates the existing order instead of creating a duplicate.

  • Sync an order with a line whose SKU is not yet in Shopify, with Create Line Item Product as Prerequisite enabled, and confirm the product is created first and the order succeeds.

  • Sync an order with a shipping-only, a billing-only, and a combined address and confirm each routes to the correct slot(s).

  • Confirm the order carries a delivery method because the shipping line title and price are mapped.

  • With tracking-only updates turned on: add a tracking record covering part of a linked order and update the transaction; confirm one fulfillment with that tracking number and quantity, and that an order note changed in iPaaS.com did not reach Shopify.

  • Re-send the same tracking number with a higher quantity and confirm nothing is added; add a new tracking record with the full running total and confirm only the remainder is fulfilled.

  • Create a new order with tracking-only updates turned on and confirm it is still created normally.

Validation Checklist.

  • New orders appear in Shopify with correct totals, financial status, and currency.

  • The Shopify order id is saved as the external id after the first successful sync.

  • Duplicate-order matching links to the existing order via the metafield.

  • Line items link to the correct products/variants by SKU.

  • Tax lines and addresses appear correctly on the order.

  • A delivery method is present on the order.

Additional Notes

  • The default template includes two placeholder values that must be reviewed before production use: the static global.Order-Desc value (test desc from mappings) and the static USD currency.

  • Customers are not auto-created in this direction. Establish the iPaaS.com-to-Shopify customer link beforehand if the order should carry a customer.

Related Documents

Related Mapping Documentation

Did this answer your question?