Contents
Summary
A BigCommerce refund is transferred to iPaaS.com as a Transaction recorded as a validated return. BigCommerce treats a refund as its own record, distinct from the original order, so the refund is routed here rather than through the standard order collection: the refund header — the link back to the original order, buyer email, totals, tax, shipping, discount, dates, and quantities — is mapped onto the Transaction, and the refund's related data is transferred through child collections for refund lines, billing and shipping addresses, and payments (one collection per payment gateway). Refund financial values are recorded as negatives so the return reduces the corresponding order totals in downstream systems. As delivered, the refund collection is Disabled by default as an install-time safeguard, so no refund transfers until the subscriber deliberately enables it (see Mapping Collection Status).
ID Format
Manual Sync ID Format
On the iPaaS.com Manual Sync page, enter the BigCommerce order ID of the refunded order — the numeric identifier BigCommerce assigns to the order. Example: 1234. Transferring the order in this way transfers its refund and the refund's child records together.
External ID Format
After a successful transfer, iPaaS.com records the refund's identifier as the external ID on a dedicated external-ID record. That external-ID record is the primary match that routes a later transfer of the same refund to an update rather than creating a duplicate. The collection also writes a composite value — the original order ID, followed by -R, followed by the refund ID (for example, 1234-R56) — into the Transaction's transaction-number field, which gives the return visibility on the Transaction and serves as a fallback match key when no external-ID record yet exists. The -R marker distinguishes the return from the original order.
Remapping the transaction-number field to a different source is supported, but it disables that fallback auto-link for any Transactions that existed before the change.
Deleted Record Support
Outbound delete of a refund is not supported. This family creates and updates return Transactions only; no refund-delete mapping collection ships in the default template, and removing a refund in BigCommerce does not delete the linked return Transaction in iPaaS.com. A refund is itself the reversal of an order — it is not a delete of the original order Transaction, which continues to exist alongside the return.
Custom Field Support
BigCommerce custom fields are supported on the Order and Order Product modules and can be mapped on the refund collections in the same way they are mapped on the order collections. To use a BigCommerce custom field in a mapping, first add it as a custom field in the BigCommerce subscription (Subscription Management → Subscriptions → BigCommerce → Custom Fields), then map it to the corresponding iPaaS.com field on the relevant collection. For Order Product custom fields, the custom-field module is BC Order Product, and the custom-field name must match the source field's display name in BigCommerce. See the BigCommerce Products article for how product-level fields are configured.
Two iPaaS.com custom fields on the Transaction Line are used by the refund line collection out of the box:
Module | Custom Field |
Transaction Line | Original SKU |
Transaction Line | SellingUnit |
Mapping Collection Status
Status: Disabled by default. As delivered, the refund parent collection's filter includes an always-false guard, so no record passes through and nothing transfers. This is an intentional install-time safeguard so refunds do not transfer until the subscriber deliberately enables them. To enable the collection, edit the mapping filter to remove the always-false guard, leaving the refund-selection condition (the IsRefund flag) in place, then review the filter against your business rules before enabling automatic transfers. The child collections are enabled and transfer with the parent once the parent is activated.
Trigger Events: Automatic transfers run when BigCommerce sends an order webhook to iPaaS.com. Enable the BigCommerce order events (order created and updated) under the Inbound Data Flows section of the subscription configuration. Until these are enabled — and until the parent filter's always-false guard is removed — no automatic refund transfers occur; Manual Sync is available at any time once the filter is activated.
Duplicate or Conflicting Mappings
Other collections operate on the same BigCommerce order data. Review their filters and Add/Update settings before enabling the refund collection, and decide which collection is the source of truth for each order state:
Add BigCommerce Order TO iPaaS.com and Update BigCommerce Order TO iPaaS.com: handle the original (non-refund) order. Their filters explicitly exclude refunds (
!IsRefund), so an order and its refund are handled by different collections.
The order collections and the refund collection move records in the same direction (BigCommerce → iPaaS.com) but select disjoint sets of records — the order collections reject refunds and the refund collection accepts only refunds once activated. This coordination is what keeps an order and its refund from colliding.
Important: Enabling overlapping collections without coordinated filters can create duplicate or conflicting Transactions. Confirm each collection's filter selects a distinct set of records.
Collision Handling
This Refund family does not use iPaaS.com collision handling — records are routed to a create or update by external-ID presence (with a fallback match on the existing Transaction's number), not by a collision-recovery step. See ID Format for how the external-ID link and transaction-number fallback prevent duplicates.
Supported Child Collections
Each child below is linked to the parent refund Transaction and transferred as part of the refund. The parent (Add/Update BigCommerce Refund TO iPaaS.com) drives the full set when a refund transfers:
Add/Update BigCommerce Refund Line TO iPaaS.com: the refunded line items.
Add BigCommerce Refund Billing Address TO iPaaS.com and Add BigCommerce Refund Shipping Address TO iPaaS.com — the refund billing and shipping addresses.
Add BigCommerce Refund Payment Credit Card TO iPaaS.com, Add BigCommerce Refund Payment PayPal TO iPaaS.com, Add BigCommerce Refund Payment Test Payment Gateway TO iPaaS.com, and Add BigCommerce Refund Payment Check TO iPaaS.com — the refund's payments, one collection per payment gateway.
System Caveats
BigCommerce Caveats
Refunds are separate records. BigCommerce treats a refund as its own record distinct from the order. This family exists specifically to capture that record; the standard order collections filter refunds out.
Addresses reflect the refund. BigCommerce provides the shipping and billing addresses used for the refund. If a refund's addresses should not change from the original order's, review the address child collections with your implementation team before enabling.
Different payment types need different mappings. The data BigCommerce returns differs by payment type, so refund payments are split across gateway-specific child collections. If a refund uses a payment type not covered by the supplied payment collections, an additional payment sub-collection may be needed — review with your implementation team before relying on it in production.
Rate limiting. When BigCommerce rate-limits requests, the transfer is automatically rescheduled to resume after the limit window resets — no subscriber action is required.
iPaaS.com Caveats
Original order link required. The refund is linked to the original order's Transaction through its parent link. If that Transaction cannot be resolved in iPaaS.com, the refund transfer does not complete. Ensure the original order has transferred before its refund.
Negative financials. Totals, tax, shipping, subtotal, and line quantities and prices are recorded as negatives so the return reduces the original order's figures in downstream systems. Confirm your downstream systems interpret negative return values as you expect.
Existing record required on update. When a refund that has already transferred is refreshed, the update targets the return Transaction that already exists in iPaaS.com. A refund that has never transferred through the parent collection has no Transaction to update.
Full-replace updates. Refund updates write the full record; fields left unmapped can be overwritten on each transfer. Map every field you want preserved, or use a destination-value approach for fields you do not source from BigCommerce. This behavior is accurate at the time this documentation was written.
Integration-Specific Caveats
Disabled-by-default safeguard. As delivered, the refund parent collection is disabled through an always-false guard in its filter so no refund transfers until the subscriber deliberately activates it. This is intentional. Activate refunds only after confirming the original orders they reverse are already transferring, so each refund has an order Transaction to link to (see Mapping Collection Status).
Refund payment split by gateway. Because BigCommerce returns different payment data per gateway, the refund's payment is captured by whichever payment child collection matches the order's payment method — Credit Card, PayPal, Test Payment Gateway, or Check. An order paid with a gateway not covered by these collections produces no refund payment record until an additional payment sub-collection is added.
Setup Requirements
Before automatic refund transfers will run, two things must be in place. First, configure the BigCommerce order webhooks and enable the corresponding order events (order created and updated) under Inbound Data Flows in the subscription configuration. Second, edit the refund parent collection's mapping filter to remove the always-false guard, leaving the IsRefund condition, so refunds are allowed through (see Mapping Collection Status). The store-level API account access token and store hash used for the connection are configured in the subscription settings. For the full webhook and credential walkthrough, see the BigCommerce Installation Instructions and the BigCommerce Connections and Settings article; this document does not duplicate those steps.
Integration Flow
When a refund is transferred, the integration retrieves the full BigCommerce refund and its related records, then dispatches the header and each child to iPaaS.com in order:
The refund header is read and evaluated against the collection filter. As delivered, the always-false guard rejects every record; once the guard is removed, only records flagged as refunds (
IsRefund) pass, and non-refund orders are handled by the order collections instead.The original order this refund reverses is resolved so the return can be linked to it. If the original order's Transaction cannot be found in iPaaS.com, the refund cannot be linked and the transfer does not complete.
The header fields are mapped to the iPaaS.com Transaction, with financial values recorded as negatives. The Transaction type is set to Validated Return, the status to Complete, and the transaction number to the composite
originalOrderId-R refundIdvalue.Child records are transferred and linked to the return Transaction — refund lines (each linked back to its original order line), billing and shipping addresses, and the refund payment for whichever gateway matches the order's payment method.
On a successful first transfer, iPaaS.com saves the refund's identifier as the external-ID link so later transfers of the same refund route to an update.
Mappings
Each mapping collection is documented below with its live Mapping Filter (where the collection has one), the iPaaS.com data type it targets, and its field-mapping table. In the tables, Dynamic Formula source values are shown inline in backticks; Static values are quoted. The Description column carries the required/recommended classification and behavior for each field. Refund financial values are mapped as negatives throughout.
Add / Update BigCommerce Refund
iPaaS.com data type: Transaction
This collection — Add/Update BigCommerce Refund TO iPaaS.com — maps the refund header onto the iPaaS.com Transaction as a validated return and drives the transfer of the refund's child collections. It handles both new refunds and later changes to an existing refund.
Mapping Filter
1 == 0 && IsRefund
Filter Description. As delivered, this filter combines an always-false guard with the refund condition, so no record passes through and nothing transfers — this is the intentional Disabled-by-default install-time safeguard. The always-false guard is the first term; the second term is the IsRefund flag, which selects only orders that BigCommerce has flagged as refunds (these are excluded from the standard order collections and routed here instead). To activate refund processing, remove the always-false guard from the front of the filter, leaving the IsRefund condition. After activation, only refund records pass and every non-refund order is skipped. No value in this filter is environment-specific, so no placeholder substitution is required.
Mapping Type | Source Field (BigCommerce) | Destination Field (iPaaS.com) | Description |
Dynamic Formula |
| SystemId | Required. Sets the source system for the Transaction to the BigCommerce system this subscription is connected to — the Transaction must record which system the refund came from. |
Dynamic Formula |
| TransactionNumber | Required. Builds the refund's transaction number by combining the original order ID, the literal -R, and the refund ID (for example, |
Dynamic Formula |
| ParentId | Required. Resolves the original order's iPaaS.com Transaction and links this refund to it as the parent — the return must point back to the order it reverses. If the original order's Transaction cannot be resolved, the refund cannot be linked and the transfer does not complete. |
Static |
| Type | Required. Fixed value — sets the Transaction type to Validated Return. Every record in this collection is a return. |
Static |
| Status | Required. Fixed value — sets the return status to Complete for every refund created by this collection. |
Dynamic Formula | Dynamic Formula (email resolution) | EmailAddress | Recommended. Sets the refund email from the original order — the company email for B2B orders, otherwise the original order's billing-address email, falling back to a guest email when the order had no customer. See the placeholder note below the table. |
Dynamic Formula |
| TaxAmount | Recommended. Records the refunded tax as a negative value so the return reduces the original order's tax in downstream systems. |
Dynamic Formula |
| ShippingAmount | Recommended. Records the refunded shipping cost (excluding tax) as a negative value so the return reduces the original order's shipping. |
Dynamic Formula |
| Subtotal | Recommended. Records the refunded subtotal (excluding tax) as a negative value so the return reduces the original order's subtotal. |
Dynamic Formula |
| Total | Recommended. Records the refunded grand total (including tax) as a negative value so the return reduces the original order's total. |
Field | order ItemsTotal | TotalQty | Recommended. Maps the total item quantity on the refund to the Transaction. |
Field | order DateCreated | TransactionCreatedDateTime | Recommended. Preserves the original creation date/time on the return Transaction. |
Field | order DateModified | TransactionUpdatedDateTime | Recommended. Preserves the last-modified date/time on the return Transaction. |
Placeholder value — replace during implementation: the guest fallback email Guest@theredrookqa.com used by the EmailAddress formula is an example test-domain address. Replace it with the email your business wants to record on guest refunds before enabling this collection.
The email-resolution formula is a configurable dynamic formula maintained on the mapping. Its behavior is summarized in the Description column above; the full expression body is recoverable from a live iPaaS.com subscription export.
Add / Update BigCommerce Refund Line TO iPaaS.com
iPaaS.com data type: Transaction Line
This collection is a child of Add/Update BigCommerce Refund TO iPaaS.com — it maps each refunded line item onto a Transaction Line, linked back to the original order line. It has no mapping filter, so every line on the refund is transferred. Quantity, unit price, extended price, and tax are recorded as negatives so the return reduces the original order line's figures. Because BigCommerce does not expose a per-line unit price or an after-discount extended price directly, both are calculated from the line total, applied discounts, and quantity.
Mapping Type | Source Field (BigCommerce) | Destination Field (iPaaS.com) | Description |
Dynamic Formula |
| SellingUnit | Optional. Derives the selling unit from the line's SKU by parsing the unit component out of the SKU string. When the SKU does not encode a unit, no selling unit is set. |
Dynamic Formula |
| Original SKU | Recommended. Records the original ordered SKU, parsed from the line's SKU string — it preserves the item identifier as it appeared on the order. |
Static |
| Type | Required. Fixed value — sets the Transaction Line type to Product for every refund line. |
Dynamic Formula |
| ParentId | Required. Resolves the original order line's iPaaS.com Transaction Line and links this refund line to it, using the original order ID and product ID as the key. If the original line cannot be resolved, the refund line cannot be linked. |
Static |
| Status | Required. Fixed value — sets the refund line status to Complete for every line. |
Dynamic Formula |
| Sku | Recommended. Records the returned item's SKU, parsed from the line's SKU string — it identifies the item being refunded. |
Field | refund line Name | Description | Recommended. Maps the item name to the refund line description. |
Dynamic Formula |
| Qty | Recommended. Records the refunded quantity as a negative value so the return reduces the original order line's quantity. |
Dynamic Formula |
| UnitPrice | Recommended. Derives the per-unit price net of the per-unit applied discount: the line's price excluding tax, less the total applied discount divided by the original ordered quantity. BigCommerce does not expose a per-line unit price directly, so this value is computed. |
Dynamic Formula |
| ExtendedPrice | Recommended. Derives the extended (line total) amount net of the proportional applied discount for the refunded quantity, recorded as a negative so the return reduces the original order line's total. |
Field | refund line BasePrice | OriginalUnitPrice | Recommended. Maps the item's base price to the refund line as the original unit price. |
Dynamic Formula |
| EstimatedTaxAmount | Recommended. Records the refunded line tax as a negative value so the return reduces the original order line's tax. |
Field | refund line Weight | Weight | Recommended. Maps the item weight to the refund line. |
Add BigCommerce Refund Billing Address TO iPaaS.com
iPaaS.com data type: Transaction Address
This collection is a child of Add/Update BigCommerce Refund TO iPaaS.com — it captures the billing address on the refund and flags it as the return's primary billing address. The address is drawn from the original order's billing address.
Mapping Filter
SourceTypeName == "ParentOnly"
Filter Description. The collection processes the address only when SourceTypeName is ParentOnly — that is, once per refund, from the refund header's billing address rather than from a per-line or per-shipment source. This ensures exactly one primary billing address is created for the return. No value in this filter is environment-specific.
Mapping Type | Source Field (BigCommerce) | Destination Field (iPaaS.com) | Description |
Static |
| IsPrimaryBilling | Required. Fixed value — flags this address as the return's primary billing address. |
Dynamic Formula |
| Address1 | Recommended. Maps the first billing street line from the original order's billing address. |
Dynamic Formula |
| Address2 | Optional. Maps the second billing street line; set only when a second line is present. |
Dynamic Formula |
| City | Recommended. Maps the billing city from the original order's billing address. |
Dynamic Formula |
| Region | Recommended. Maps the billing state or region from the original order's billing address. |
Dynamic Formula |
| Country | Recommended. Maps the billing country from the original order's billing address. |
Dynamic Formula |
| PostalCode | Recommended. Maps the billing postal code from the original order's billing address. |
Dynamic Formula |
| FirstName | Recommended. Maps the billing contact's first name from the original order's billing address. |
Dynamic Formula |
| LastName | Recommended. Maps the billing contact's last name from the original order's billing address. |
Dynamic Formula |
| Company | Recommended when the buyer is a company. Maps the billing company name from the original order's billing address. |
Add BigCommerce Refund Shipping Address TO iPaaS.com
iPaaS.com data type: Transaction Address
This collection is a child of Add/Update BigCommerce Refund TO iPaaS.com — it captures the shipping address on the refund and flags it as the return's primary shipping address. The shipping method is normalized through a lookup translation while the raw method label is preserved as the description.
Mapping Filter
SourceTypeName == "OrderShippingAddress"
Filter Description. The collection processes the address only when SourceTypeName is OrderShippingAddress — the refund's shipping-address source. This keeps the shipping address distinct from the billing address (which is created by the billing-address collection) so the return gets one primary shipping address. No value in this filter is environment-specific.
Mapping Type | Source Field (BigCommerce) | Destination Field (iPaaS.com) | Description |
Static |
| IsPrimaryShipping | Required. Fixed value — flags this address as the return's primary shipping address. |
Field | shipping address Street1 | Address1 | Recommended. Maps the first shipping street line. |
Field | shipping address Street2 | Address2 | Optional. Maps the second shipping street line; set only when a second line is present. |
Field | shipping address City | City | Recommended. Maps the shipping city. |
Field | shipping address State | Region | Recommended. Maps the shipping state or region. |
Field | shipping address Country | Country | Recommended. Maps the shipping country. |
Field | shipping address Zip | PostalCode | Recommended. Maps the shipping postal code. |
Lookup Translation | Lookup Translation: BigCommerce Shipping Method → iPaaS.com Shipping Method | ShippingMethod | Recommended. Translates the BigCommerce shipping method into the iPaaS.com shipping method. Review and customize the translation values so each BigCommerce shipping method maps to the value your workflow expects. |
Field | shipping address ShippingMethod | ShippingMethodDescription | Recommended. Records the original BigCommerce shipping-method label as the description, preserving the raw value alongside the translated |
Field | shipping address FirstName | FirstName | Recommended. Maps the recipient's first name. |
Field | shipping address LastName | LastName | Recommended. Maps the recipient's last name. |
Field | shipping address Company | Company | Recommended when the delivery is to a company. Maps the recipient company name. |
Lookup Translation Tables
The ShippingMethod mapping above translates the BigCommerce shipping method into the iPaaS.com shipping method through the BC Shipping Method To iPaaS lookup translation. These pairs are subscriber-configurable defaults — review and customize them so each BigCommerce shipping method maps to the value your workflow expects.
Placeholder value — replace during implementation: the pairs below are example UPS mappings from the development store. Replace them with your store's actual shipping-method names and the values your destination system expects before go-live.
Source Value (BigCommerce) | Destination Value (iPaaS.com) | Notes |
UPS (UPS Ground) | UPS GROUND | example |
None | UPS GROUND | example |
UPS (UPS 3 Day Select) | UPS GROUND | example |
UPS (UPS 2nd Day Air) | UPS BLUE | example |
UPS (UPS Next Day Air) | UPS RED | example |
Flat Rate | UPS GROUND | example |
Add BigCommerce Refund Payment - Credit Card TO iPaaS.com
iPaaS.com data type: Transaction Payment
This collection is a child of Add/Update BigCommerce Refund TO iPaaS.com — it captures the refund payment for orders paid by credit card. The payment amount is recorded as a negative.
Mapping Filter
Parent.PaymentMethod == "Credit Card"
Filter Description. The collection processes the refund payment only when the original order's PaymentMethod is Credit Card. Refunds on any other payment method are skipped here and handled by the PayPal, Test Payment Gateway, or Check collections. No value in this filter is environment-specific.
Mapping Type | Source Field (BigCommerce) | Destination Field (iPaaS.com) | Description |
Dynamic Formula |
| Method | Required. Resolves the payment method from the original order's gateway, using the order's payment method, the refund ID, and the order's payment transactions to select the correct method. Confirm the credit-card payment method your workflow expects exists in iPaaS.com so the intended method is matched. |
Dynamic Formula |
| Description | Recommended. Builds the refund payment description from the resolved method, appending OFFLINE when the refund was processed offline and DECLINED when the refund was declined — surfacing refund details that are not part of the standard payment method value. |
Dynamic Formula |
| Amount | Required. Records the refunded amount as a negative value so the return reduces the original order's payment total in downstream systems. |
Dynamic Formula |
| Status | Required. Sets the payment status to Refunded, or to Declined when the refund was declined. |
Add BigCommerce Refund Payment - PayPal TO iPaaS.com
iPaaS.com data type: Transaction Payment
This collection is a child of Add/Update BigCommerce Refund TO iPaaS.com — it captures the refund payment for orders paid through PayPal. The payment amount is recorded as a negative.
Mapping Filter
Parent.PaymentMethod.StartsWith("PayPal")Filter Description. The collection processes the refund payment only when the original order's PaymentMethod starts with PayPal. Refunds on any other payment method are skipped here and handled by the Credit Card, Test Payment Gateway, or Check collections. No value in this filter is environment-specific.
Mapping Type | Source Field (BigCommerce) | Destination Field (iPaaS.com) | Description |
Dynamic Formula |
| Method | Required. Records the payment method from the original order's payment method value, which for this collection is the PayPal gateway. |
Dynamic Formula |
| Description | Recommended. Builds the refund payment description from the method, appending OFFLINE when the refund was processed offline and DECLINED when the refund was declined. |
Dynamic Formula |
| Amount | Required. Records the refunded amount as a negative value so the return reduces the original order's payment total. |
Dynamic Formula |
| Status | Required. Sets the payment status to Refunded, or to Declined when the refund was declined. |
Add BigCommerce Refund Payment - Test Payment Gateway TO iPaaS.com
iPaaS.com data type: Transaction Payment
This collection is a child of Add/Update BigCommerce Refund TO iPaaS.com — it captures the refund payment for orders paid through the test gateway. The payment amount is recorded as a negative.
Mapping Filter
Parent.PaymentMethod == "Test Payment Gateway" || Parent.PaymentMethod == "Test Payment Provider"
Filter Description. The collection processes the refund payment only when the original order's PaymentMethod is either Test Payment Gateway or Test Payment Provider. Refunds on any other payment method are skipped here and handled by the Credit Card, PayPal, or Check collections. No value in this filter is environment-specific.
Mapping Type | Source Field (BigCommerce) | Destination Field (iPaaS.com) | Description |
Static |
| Method | Required. Fixed value — sets the payment method to Other for test-gateway refund payments. The test gateway does not correspond to a specific production payment method, so a generic label is used. See the placeholder note below the table. |
Dynamic Formula |
| Description | Recommended. Builds the refund payment description from the method, appending OFFLINE when the refund was processed offline and DECLINED when the refund was declined. |
Dynamic Formula |
| Amount | Required. Records the refunded amount as a negative value so the return reduces the original order's payment total. |
Dynamic Formula |
| Status | Required. Sets the payment status to Refunded, or to Declined when the refund was declined. |
Placeholder value — replace during implementation: "Other" is a generic method label for test-gateway transactions. If test-gateway refunds can reach a production environment, replace it with the payment method your workflow expects for accurate reporting. The transfer succeeds either way — this affects reporting precision, not success.
Add BigCommerce Refund Payment - Check TO iPaaS.com
iPaaS.com data type: Transaction Payment
This collection is a child of Add/Update BigCommerce Refund TO iPaaS.com — it captures the refund payment for orders paid by check. The payment amount is recorded as a negative.
Mapping Filter
Parent.PaymentMethod == "Check"
Filter Description. The collection processes the refund payment only when the original order's PaymentMethod is Check. Refunds on any other payment method are skipped here and handled by the Credit Card, PayPal, or Test Payment Gateway collections. No value in this filter is environment-specific.
Mapping Type | Source Field (BigCommerce) | Destination Field (iPaaS.com) | Description |
Dynamic Formula | Dynamic Formula (match existing Check payment method, else Check) | Method | Required. Looks up an existing iPaaS.com payment method matching Check and uses it if found; otherwise records the method as Check. Confirm the check payment method your workflow expects exists in iPaaS.com so the intended method is matched. |
Dynamic Formula |
| Description | Recommended. Builds the refund payment description from the resolved method, appending OFFLINE when the refund was processed offline and DECLINED when the refund was declined. |
Dynamic Formula |
| Amount | Required. Records the refunded amount as a negative value so the return reduces the original order's payment total. |
Dynamic Formula |
| Status | Required. Sets the payment status to Refunded, or to Declined when the refund was declined. |
Error Handling
The BigCommerce integration reports errors through the standard iPaaS.com error path. For the catalog of order- and refund-related error messages and how to resolve them, see the BigCommerce Integration - Error Messages article rather than duplicating it here. Two behaviors specific to this family are worth noting:
Rate limiting. When BigCommerce rate-limits requests, the transfer is automatically rescheduled to resume after the limit window resets — no subscriber action is required.
Original order prerequisite failure. If the original order this refund reverses cannot be resolved as a Transaction in iPaaS.com, the refund cannot be linked through its parent and the transfer does not complete. Confirm the original order has transferred before re-running the refund.
Testing & Validation
Test Scenarios
Enable the collection. Confirm the refund parent collection is disabled as delivered (its filter carries the always-false guard), then remove the guard, leaving the IsRefund condition, and confirm refunds begin to be selected.
Create a refund. Transfer an order (through the order collections), then issue a refund against it in BigCommerce and verify the refund transfers to iPaaS.com as a validated-return Transaction linked to the original order, with the transaction number
originalOrderId-R refundId, the correct buyer email, and negative totals, tax, shipping, and subtotal.Update a refund. Change a refund that has already transferred and verify the linked return Transaction is updated — not duplicated — and remains linked to the original order.
Original-order prerequisite. Attempt to transfer a refund whose original order has not transferred and confirm the refund does not complete because the parent order Transaction cannot be resolved.
ID format. From the Manual Sync page, transfer a refund by the numeric BigCommerce order ID of the refunded order and confirm the refund and its child records transfer together and the external-ID link is saved.
Payment-type coverage. Issue refunds on orders paid by credit card, PayPal, check, and the test gateway, and verify each is captured by the matching payment collection with a negative amount and a Refunded status (or Declined for a declined refund).
Negative financials. Verify the return Transaction's totals, line quantities, unit prices, extended prices, tax, and payment amounts are all recorded as negatives and reduce the original order's figures as your downstream systems expect.
Guest refund. Issue a refund on a guest order (no customer) and confirm the email falls back correctly — after replacing the placeholder guest email with your own value.
Validation Checklist
The refund parent collection was disabled as delivered and was activated by removing the always-false guard from its filter.
The return Transaction's type is Validated Return and its status is Complete.
The transaction number equals
originalOrderId-R refundId(for example,1234-R56).The return is linked to the original order's Transaction through its parent link.
Totals, tax, shipping, subtotal, line quantities and prices, and payment amounts are all recorded as negatives.
Refund lines are linked back to their original order lines and carry the correct SKU, description, quantity, unit price, extended price, tax, and weight.
Billing and shipping addresses are flagged as primary and carry the correct contact and address fields; the shipping method maps through the shipping-method lookup translation.
The refund payment is captured by the collection matching the order's payment gateway, with a negative amount and a Refunded (or Declined) status.
The placeholder guest email has been replaced before enabling the collection.
Additional Notes
Refunds versus orders. Standard orders are handled by the BigCommerce Order Mapping Documentation collections, not the refund collection. A refund is a distinct BigCommerce record that reverses an order; both the order Transaction and the return Transaction exist in iPaaS.com side by side.
Deposit tickets and gift-card tickets (the -D and -GC order clones) are handled by their own collections.
B2B quotes are handled by the B2B Quote collections.
Refund addresses. iPaaS.com pulls in the shipping and billing addresses used for a refund; if you need to ensure those do not change from the original order's, review the address child collections with your implementation team.
Full details of the read and write endpoints this integration uses are in the BigCommerce API Endpoints article.
For the full list of integration-wide constraints, see the BigCommerce Integration Known Limitations article.