Summary

Square orders can be transferred to iPaaS.com so that each Square order is recorded as an iPaaS.com transaction, carrying the order totals, tax, discount, tip, currency, location, and the Square created and updated timestamps. Each transfer also records the order's line items, payments, and discounts through the child collections. Orders transfer automatically when subscribers or their MiSP subscribe to the Square order events, and on demand from the Manual Sync page.

Note on amounts: Square records money in the smallest unit of the currency (for example, cents). Mappings that carry an amount divide the Square value by 100 to store a decimal amount in iPaaS.com.

ID Format

Manual Sync ID: the Square order identifier — the id Square assigns to the order — entered on the iPaaS.com Manual Sync page.
External ID saved after sync: on the first successful transfer, iPaaS.com saves the Square order identifier as the external ID on a dedicated external-ID record. That external-ID record is the primary match used to route later updates to the same iPaaS.com transaction. The Square order identifier is also written into the iPaaS.com TransactionNumber field, which provides visibility on the record and serves as a fallback match key when no external-ID record exists yet. Remapping TransactionNumber to a different value disables the fallback match and can cause duplicate transactions.

Deleted Record Support

Outbound order deletion is not supported. The Square Order model's Delete operation is not implemented, delete mappings are not included in the default templates, and deleting or canceling an order in Square does not remove the corresponding iPaaS.com transaction.

Mapping Collection Status

Status: Enabled, with a mapping filter on the parent Order collection that holds the order back until every line-item product exists in iPaaS.com (see Mappings). The child collections carry no filter.
Trigger Events: Square Order Created (order.created) and Order Updated (order.updated), enabled by subscribers or their MiSP in the subscription's Inbound Data Flows configuration. Orders can also be recorded on demand from the Manual Sync page.

Duplicate or Conflicting Mappings

Duplicate Matching

To prevent duplicate transactions, iPaaS.com links each Square order to its transaction by the external-ID record described under ID Format, and — when an order has not yet been linked — by matching an existing iPaaS.com transaction whose TransactionNumber equals the Square order identifier. After the first successful transfer, the external-ID record takes over as the primary match.

Unmapped Field Overwrite Risk

iPaaS.com applies a full-record update when it revises an existing transaction. ShippingAmount is not mapped in this collection and will be cleared on each transfer; if subscribers or their MiSP populate it by other means, add a Dynamic Formula mapping using the DestinationValue function to carry the existing value forward (for example, map DestinationValue.ShippingAmount to the ShippingAmount field). The transaction's CompanyId link is not set from Square and is not affected by this collection.

Supported Child Collections

Parent Collection: Add/Update Square Order TO iPaaS.com.

Add/Update Square Order Line Items TO iPaaS.com: records each line item on the order. It has its own child, Add/Update Square Order Line Item Applied Discount TO iPaaS.com, which records discounts applied to an individual line.
Add/Update Square Order Tenders TO iPaaS.com: records each payment (tender) on the order.
Add/Update Square Order Discount TO iPaaS.com: records order-level discounts.

System Caveats

Square Caveats

Money amounts are in the smallest unit of the currency. Square reports amounts in the smallest unit (for example, cents); the integration converts them to decimal amounts in iPaaS.com.
Order state is recorded as a fixed value. Every order is recorded with status Complete and type Order, regardless of the order's actual state in Square.
Allowed locations must be configured. The Square location is validated against a list kept inside the Square Location Id mapping formula; an order from a location that is not on the list fails until the list is updated (see Mappings and the placeholder callout).
Rate limiting: if Square temporarily limits requests, the transfer is automatically rescheduled to resume after the limit resets. No subscriber action is required.

iPaaS.com Caveats

Products are a source-of-truth prerequisite. The order is held back until every line-item product exists in iPaaS.com, so keep product data current before relying on automatic order transfers.
Updates overwrite mapped fields from the current Square values on every transfer, so Square is the source of truth for the mapped fields.

Setup Requirements

iPaaS.com Configuration

Subscribe to the Square Order Created (order.created) and Order Updated (order.updated) events in the subscription configuration's Inbound Data Flows section. No orders transfer automatically until those events are enabled. Orders can also be recorded on demand from the Manual Sync page using the Square order identifier. Before enabling this collection, replace the placeholder values called out under Mappings (the fallback customer email address and the allowed-location list).

Square Configuration

The Square connection must be authorized for the integration. The Square-side webhook registration for the order events is covered in the Square Installation Instructions.

Integration Flow

A Square order is received via the Order Created or Order Updated event, or retrieved on Manual Sync using the Square order identifier.
The collection filter checks that every line-item product exists in iPaaS.com: for each line, the integration resolves the SKU (the Square catalog SKU, or the line item's name when the catalog item has no SKU) and looks for a matching iPaaS.com product or product variant. If any SKU is missing, the order is held back and an error listing the missing SKUs is recorded.
The integration matches the existing iPaaS.com transaction by the saved external ID (or by TransactionNumber on first sync), or prepares to create a new one.
When the order references a Square customer that is not yet linked to iPaaS.com, the integration transfers that customer first so the order can be attributed to it. If the customer cannot be recorded, the order transfer stops.
The order is recorded as an iPaaS.com transaction, and the Square order identifier is saved as the external-ID link.
The child collections record the order's line items (and any line-level discounts), payments, and order-level discounts.

Mappings

Add/Update Square Order TO iPaaS.com (Parent)

iPaaS.com data type: Transaction

Mapping Filter

return await CheckSquareProductExistIniPaaSAsync(LineItems);

Filter Description. The order is processed only when every product on its line items already exists in iPaaS.com. For each line item the integration resolves the SKU (the Square catalog SKU, or the line item's name when the catalog item has no SKU) and checks for a matching iPaaS.com product or product variant. If one or more SKUs are missing, the order is rejected with the error The following SKUs do not exist in iPaaS: [list]. Please ensure all SKUs are created in iPaaS before processing Square transactions. Create the missing products — including static SKUs for non-catalog charges such as fees or surcharges — and the order transfers on the next attempt.

Mapping Type	Source (Square)	Destination (iPaaS.com)	Description
Field	`Id`	TransactionNumber	Required. The Square order identifier; anchors the record and enables the fallback match (see ID Format).
Static	`"Order"`	Type	Required. Every order is recorded as type Order (fixed for this collection).
Static	`"Complete"`	Status	Required. Every order is recorded with status Complete, regardless of its actual Square state.
Dynamic Formula	`SpaceportSystemId`	SystemId	Required. Identifies the iPaaS.com system; supplied automatically.
Dynamic Formula	Dynamic Formula	CustomerId	Links the order to its iPaaS.com customer by the Square customer identifier; when the order has no customer it is attributed to a fallback customer. Placeholder value — replace during implementation: the fallback email generic-email@gmail.com is example data — replace it with your guest or walk-in customer email address, and ensure a customer with that email exists in iPaaS.com.
Dynamic Formula	Dynamic Formula	EmailAddress	Returns the fallback email when the order has no customer; returns nothing when the order has a customer so the linked customer is used. Placeholder value — replace during implementation: the same fallback email generic-email@gmail.com must be replaced to match the CustomerId mapping.
Dynamic Formula	Dynamic Formula	Subtotal	Recommended. The order total minus the tax amount (the pre-tax value).
Dynamic Formula	`TotalTaxMoney_Amount/100`	TaxAmount	Recommended. The order's total tax; recorded as zero when Square reports no tax.
Dynamic Formula	`TotalDiscountMoney_Amount/100`	DiscountAmount	Recommended. The order's total discount; recorded as zero when Square reports no discount.
Dynamic Formula	`TotalMoney_Amount/100`	Total	Recommended. The order total, including tax and after discounts.
Dynamic Formula	Dynamic Formula	TotalQty	Recommended. The sum of all line-item quantities on the order.
Field	`TotalMoney_Currency`	Currency	Optional. The currency of the order total, stored in the iPaaS.com Currency custom field.
Dynamic Formula	Dynamic Formula	Square Location Id	Stores the Square location, validated against an allowed-location list kept inside the formula. Placeholder value — replace during implementation: the list ships with the example entries iPaaS.com and Location A — subscribers or their MiSP MUST replace them with their real Square location names before enabling this collection, or every order from an unlisted location fails.
Dynamic Formula	`TotalTipMoney_Amount/100`	Total Tip	Optional. The total tip amount, stored in the iPaaS.com Total Tip custom field; zero when Square reports no tip.
Dynamic Formula	Dynamic Formula	TransactionCreatedDateTime	Recommended. When the order was created in Square, stored as UTC.
Dynamic Formula	Dynamic Formula	TransactionUpdatedDateTime	Recommended. When the order was last changed in Square, stored as UTC.

Add/Update Square Order Line Items TO iPaaS.com (Child)

iPaaS.com data type: Transaction Line

Mapping Type	Source (Square)	Destination (iPaaS.com)	Description
Static	`"Product"`	Type	Required. Every line is recorded as line type Product (fixed for this collection).
Static	`"Complete"`	Status	Required. Every line is recorded with status Complete (fixed for this collection).
Dynamic Formula	Dynamic Formula	Sku	Recommended. The SKU of the Square catalog item on the line, or the line item's name when the catalog item has no SKU. Every SKU that can appear on an order must exist as an iPaaS.com product or product variant (see the parent filter).
Field	`Name`	Description	Recommended. The Square line item's name.
Field	`Quantity`	Qty	Recommended. The quantity of the line item.
Dynamic Formula	`BasePriceMoney_Amount/100`	UnitPrice	Recommended. The line item's base unit price from Square.
Dynamic Formula	`GrossSalesMoney_Amount/100`	ExtendedPrice	Recommended. The Square gross sales amount for the line (the line price before discounts).

Add/Update Square Order Line Item Applied Discount TO iPaaS.com (Child of Line Items)

iPaaS.com data type: Transaction Line Discount

Mapping Type	Source (Square)	Destination (iPaaS.com)	Description
Dynamic Formula	`AppliedMoney_Amount/100`	DiscountAmount	Recommended. The amount of the discount applied to the line; zero when none applies.
Field	`Percentage`	DiscountPercent	Recommended. The percentage of the discount, when Square reports the discount as a percentage.
Field	`DiscountUid`	DiscountMethod	Optional. The Square identifier of the applied discount, so it can be traced back to the order's discount.
Field	`DiscountUid`	DiscountTypeId	Optional. The Square identifier of the applied discount, associating the line-item discount with the order's discount.

Add/Update Square Order Tenders TO iPaaS.com (Child)

iPaaS.com data type: Transaction Payment

Mapping Type	Source (Square)	Destination (iPaaS.com)	Description
Field	`Type`	Method	Required. How the order was paid — the Square tender type (for example, card or cash) — recorded as the payment method.
Dynamic Formula	`AmountMoney_Amount/100`	Amount	Recommended. The amount collected by this payment.

Add/Update Square Order Discount TO iPaaS.com (Child)

iPaaS.com data type: Transaction Discount

Mapping Type	Source (Square)	Destination (iPaaS.com)	Description
Dynamic Formula	`AppliedMoney_Amount/100`	DiscountAmount	Recommended. The amount of the order-level discount; zero when none applies.
Field	`Type`	DiscountMethod	Recommended. How the order-level discount was expressed in Square (for example, a fixed amount or a percentage).
Field	`Percentage`	DiscountPercent	Recommended. The percentage of the order-level discount, when Square reports it as a percentage.

Error Handling

Missing products: The following SKUs do not exist in iPaaS: [list]. Please ensure all SKUs are created in iPaaS before processing Square transactions. The order is held back until each listed SKU exists as an iPaaS.com product or product variant. Create the missing products — including static SKUs for non-catalog charges such as fees or surcharges — and the order transfers on the next attempt.
Location not allowed: the Square Location Id mapping records an error when the order's Square location is not on the allowed-location list inside the formula. Add the location's name to the list (or exclude that location with a mapping collection filter). See the placeholder callout under Mappings.
Customer could not be recorded: when the order references a customer that cannot be transferred as a prerequisite, the order transfer stops. Confirm the referenced Square customer has the data iPaaS.com requires (an email address).
Duplicate-link warning: when the integration cannot complete the external-ID link for an order that matches an existing iPaaS.com transaction, it records a warning that duplicate transaction records may result.

See the Square Error Messages article for the full message text and resolution steps.

Testing & Validation

Record a Square order placed at an allowed location, for a customer that exists in iPaaS.com, whose line-item products already exist in iPaaS.com; confirm the transaction is created with the correct totals, tax, and the Square order identifier saved as the external ID.
Confirm the line items, payments, and any order-level or line-level discounts are recorded on the transaction.
Record an order whose line item references a SKU that does not exist in iPaaS.com and confirm the order is held back with the missing-SKU error; create the product and confirm the order then transfers.
Record an order placed at a location not on the allowed-location list and confirm the location error; add the location and confirm success.
Record an order that has no Square customer and confirm it is attributed to the fallback customer email address you configured.
Re-sync the same order and confirm it updates the existing transaction rather than creating a duplicate.

Additional Notes

Order state is not reflected. All orders are recorded as status Complete and type Order regardless of their Square state.
Deletion is out of scope. Deleting or canceling an order in Square does not remove the corresponding iPaaS.com transaction.

Square to iPaaS.com Order Mapping Documentation