NetSuite Cash Refund From iPaaS.com Mapping Documentation
A NetSuite Cash Refund can be created and updated from an iPaaS.com transaction that represents a refund. The integration maps the customer, location, subsidiary, totals, shipping, and tax-handling fields, and through child collections the refund's line items and billing/shipping address. Transactions transfer on demand from the iPaaS.com Manual Sync page or automatically when outbound transaction triggers are enabled.
ID Format
Manual Sync ID Format
Enter the iPaaS.com record ID of the transaction on the Manual Sync page.
External ID Format
On a successful transfer, the NetSuite cash refund's internal ID is recorded as the external-ID link on the iPaaS.com transaction, so subsequent transfers update the existing cash refund. The originating transaction number is also stored on the refund's Other Reference Number (see System Caveats).
Deleted Record Support
Outbound delete is not provided for cash refunds — there is no Cash Refund delete collection, so a deletion in iPaaS.com does not remove the NetSuite cash refund. Reverse or void a cash refund in NetSuite using your normal accounting process.
Custom Field Support
The cash refund carries source tax onto NetSuite transaction custom fields (custbody_otg_ipaas_tax_code / custbody_otg_ipaas_tax_rate) for a post-create override applied by the Tax Override customization (see Setup Requirements). Any NetSuite custom field used by the integration must be created in NetSuite (Customization → Lists, Records & Fields) with a matching iPaaS.com custom field of the same Field ID.
Mapping Collection Status
Status: Enabled (a single Add/Update collection handles both create and update).
Trigger Events: Create and Update. Automatic transfers fire on the iPaaS.com transaction outbound triggers subscribed in Outbound Data Flows; the collection is also available on demand from the Manual Sync page.
Duplicate or Conflicting Mappings
Several collections process iPaaS.com transactions; which one acts is determined by each collection's filter. Review the filters and Add/Update settings before enabling, and confirm the intended source of truth for each transaction type:
Add NetSuite Sales Order FROM iPaaS.com — orders (see NetSuite Sales Order From iPaaS.com Mapping Documentation).
Add/Update NetSuite Cash Sale FROM iPaaS.com — fully paid sales (see NetSuite Cash Sale From iPaaS.com Mapping Documentation).
Add NetSuite RMA FROM iPaaS.com — returns.
Collision handling
The integration does not use iPaaS.com collision handling for this collection; it prevents duplicates through the external-ID link plus the Other Reference Number matching key. Because Other Reference Number is a matching key, changing or un-mapping it after cash refunds exist can cause incoming transactions to stop matching their NetSuite records and create duplicates. Keep that mapping stable once live and coordinate any change with your implementation partner.
Supported Child Collections
Add/Update NetSuite Cash Refund Line FROM iPaaS.com — the refund line items.
Add/Update NetSuite Cash Refund Address FROM iPaaS.com — the billing/shipping address.
System Caveats
NetSuite Caveats
Accounts Receivable must be enabled in NetSuite for cash refunds.
NetSuite calculates tax. NetSuite computes its own tax; tax amounts cannot be set directly through the API. The integration carries the source tax onto transaction custom fields for a post-create override applied by the Tax Override customization; the NetSuite SuiteTax feature is not required.
Location and subsidiary are required. The location resolves from a location name, and on OneWorld accounts the subsidiary resolves from a subsidiary name — both must match your account (the shipped values are placeholders; see Setup Requirements).
Posting period must be open. The transaction date must fall in an open NetSuite posting period.
iPaaS.com Caveats
Other Reference Number matching key. The originating transaction number is stored on Other Reference Number and is used to match an existing cash refund. Keep that mapping stable once live — see Collision handling.
Customer handling. You don't need to sync the customer first. The integration checks whether the transaction's customer is already linked in NetSuite, matches an existing one by email if possible, and otherwise attempts to create it as a prerequisite. If the customer cannot be created, the transfer is blocked with "Unable to create customer. This will prevent the transfer of the order." — resolve the underlying customer error and re-sync.
Integration-Specific Caveats
Totals are computed by NetSuite from the lines. The refund subtotal/total are carried from the source for reference; NetSuite recalculates totals from the refund lines.
Setup Requirements
Control Fields and Required Configuration
These mappings gate specific behavior and must be configured if you use the feature; replace every shipped placeholder before going live.
Mapping | Enables | Action | Required? |
CreateTransactionAs | Cash refund creation | Static value must be exactly | Control — required |
custbody_otg_ipaas_tax_code | Tax override | Set a valid NetSuite tax code. Placeholder — replace: ships as | Control — required for tax |
custbody_otg_ipaas_tax_rate | Tax-rate override | Computed as | Control — required for tax-rate override |
custbody_es_bt_auth_by_external_pnref | External payment authorization | Configure your payment-auth custom field (a Dynamic Formula returning a real boolean is preferable to the static | Control — required for external payment auth |
ShippingCostOverridden | Supplied shipping cost | Keep | Control |
Placeholders to replace: Location_Id (ships as the example name Califorina), Subsidiary_Id (ships as Parent Company), and the posting period / transaction date used by the date formula (ships with period 212).
Subscription settings: enable the iPaaS.com transaction create/update triggers in Outbound Data Flows for automatic transfers; until then, only Manual Sync transfers run.
Authentication
The integration authenticates to NetSuite using the connection configured for the integration. The Tax Override customization (the custbody_otg_ipaas_tax_code/_rate custom fields plus the supporting User Event script) is documented in NetSuite Connections and Settings.
Integration Flow
An iPaaS.com transaction transfers — on demand from the Manual Sync page (enter the transaction record ID), or automatically when the transaction outbound triggers are enabled in Outbound Data Flows.
The collection filter decides whether the transaction is a refund: its status must be Refunded or Partially Refunded, or its total negative, and its type must not be Invoice or Return. Sales, orders, and returns route to their own collections.
The integration checks for the customer in NetSuite — matching by email or otherwise attempting to create it as a prerequisite — resolves the location and subsidiary, creates the cash refund header, and transfers the children: refund line items and the address.
The NetSuite cash refund internal ID is stored back on the iPaaS.com transaction as its external ID; the source transaction number is written to Other Reference Number for matching.
A later transfer of the same transaction matches the existing cash refund (external ID, then Other Reference Number) and updates it.
Mappings
Each mapping collection below shows its live filter (where one applies), a short description, and its field mapping table. Fields marked Control gate a feature; fields with a Placeholder value ship with an example that must be replaced (see Setup Requirements).
Add/Update NetSuite Cash Refund FROM iPaaS.com
iPaaS.com data type: Transaction
Mapping Filter
(Status == "Refunded" || Status == "Partially Refunded" || Total < 0) && Type != "Invoice" && Type != "Return"
Filter Description. A transaction is processed as a cash refund only when it represents a refund and is not an invoice or return: it passes if its Status is Refunded or Partially Refunded, OR its Total is less than zero — AND its Type is neither Invoice nor Return. Transactions that are not in a refunded status and carry a non-negative total are skipped, as are any of type Invoice or Return. The filter does not raise an exception; non-matching transactions are silently skipped.
This collection creates or updates a NetSuite cash refund from a refunded iPaaS.com transaction.
Mapping Type | Source Field (iPaaS.com) | Destination Field (NetSuite) | Description |
Static |
| CreateTransactionAs | Control — required. Tells the integration to create the transaction as a cash refund (not a sales order, cash sale, or return). The value must be exactly |
Dynamic Formula |
| Entity_Id | Required. Identifies the customer the refund belongs to. The customer must exist in NetSuite or be matchable by email, or the transfer fails. |
Dynamic Formula |
| Location_Id | Required. Resolves the NetSuite location from a location name. Placeholder value — replace during implementation: ships as the example name |
Dynamic Formula |
| Subsidiary_Id | Required on OneWorld accounts. Resolves the NetSuite subsidiary from a subsidiary name. Placeholder value — replace during implementation: ships as |
Dynamic Formula |
| custbody_otg_ipaas_tax_code | Control — required for tax override. Writes the NetSuite tax code to a transaction custom field. Placeholder value — replace during implementation: |
Dynamic Formula |
| custbody_otg_ipaas_tax_rate | Control — required for the tax-rate override. Writes the tax percentage to a transaction custom field. Confirm/replace to match how your source supplies tax. |
Static |
| custbody_es_bt_auth_by_external_pnref | Control — required for external payment authorization. Flags the payment as authorized by an external reference. A Dynamic Formula returning a real boolean is preferable to the static text |
Dynamic Formula |
| Memo | Optional. Builds a short summary on the refund's Memo field. |
Field | TransactionNumber | OtherRefNum | Recommended (matching key). Stores the originating transaction number on Other Reference Number and is used to match an existing cash refund. Keep stable once live — changing it can create duplicates. |
Field | EmailAddress | Recommended. Sets the refund email from the customer's email. | |
Field | Subtotal | Subtotal | Optional. Carries the refund subtotal for reference (NetSuite recalculates from the lines). |
Field | Total | Total | Optional. Carries the refund total for reference (NetSuite recalculates from the lines). |
Field | ShippingAmount | ShippingCost | Optional. The shipping amount being refunded; pairs with |
Field | ShippingAmount | AltShippingCost | Optional. Alternate shipping-cost field from the same source amount. |
Static |
| ShippingCostOverridden | Control. Tells NetSuite to use the supplied shipping cost rather than calculating its own. Keep |
Dynamic Formula |
| ShipMethod_RefName | Optional. Sets the shipping method from the primary shipping address; must match a NetSuite shipping method. |
Lookup | Lookup Translation: OrderStatus_RefName | OrderStatus_RefName | Recommended. Sets the NetSuite status via a lookup translation you configure (map each source status to a NetSuite value). |
Dynamic Formula |
| TransactionDate | Recommended. Sets the transaction date and validates it against the selected NetSuite posting period. Placeholder value — replace during implementation: ships with posting period |
Add/Update NetSuite Cash Refund Line FROM iPaaS.com
iPaaS.com data type: Transaction Line
Mapping Filter
var netSuiteProductId = await GetNetSuiteProductIdBySku(Sku);
if(netSuiteProductId != null){
return true;
}
else{
throw new Exception("Sku "+Sku+" is not linked to a NetSuite item id");
}Filter Description. Each refund line passes only when its product Sku resolves to a linked NetSuite item. The filter looks up the NetSuite product id by SKU; a match passes the line. If the SKU cannot be matched, the filter throws "Sku [Sku] is not linked to a NetSuite item id" and the line (and refund) fails. (Unlike the sale-line collections, this filter has no gift-certificate branch — cash refunds handle product lines only.)
Adds one line per item being refunded on the cash refund.
Mapping Type | Source Field (iPaaS.com) | Destination Field (NetSuite) | Description |
Dynamic Formula |
| Item_Id | Required. Resolves the NetSuite item being refunded from the product SKU; an unmatched SKU fails the line. |
Field | Qty | Quantity | Required. The quantity being refunded on this line. |
Dynamic Formula |
| Amount | Recommended. The amount refunded on this line, calculated as quantity × unit price. As elsewhere, a discount is reflected only when folded into the unit price. |
Field | Description | Description | Optional. The line description carried to the refund line. |
Dynamic Formula |
| LineItemtype | Control — required for line creation. Sets the NetSuite line item type for the refund line, derived from the product type. |
Add/Update NetSuite Cash Refund Address FROM iPaaS.com
iPaaS.com data type: Transaction Address
This collection writes the billing/shipping address onto the cash refund.
Mapping Type | Source Field (iPaaS.com) | Destination Field (NetSuite) | Description |
Dynamic Formula |
| Addressee | Recommended. The name shown on the address. |
Field | Address1 | Addr1 | Recommended. The first address line. |
Field | Address2 | Addr2 | Optional. The second address line. |
Field | Address3 | Addr3 | Optional. The third address line. |
Field | City | City | Recommended. The address city. |
Field | Region | State | Recommended. The state or region. |
Field | PostalCode | Zip | Recommended. The postal/ZIP code. |
Field | IsPrimaryBilling | IsPrimaryBilling | Recommended. Whether this is the refund's primary billing address. |
Field | IsPrimaryShipping | IsPrimaryShipping | Recommended. Whether this is the refund's primary shipping address; the shipping method is read from it. |
Error Handling
"Sku [Sku] is not linked to a NetSuite item id" — a refund line's SKU did not resolve to a NetSuite item. Resolution: confirm the SKU and link the item/product in NetSuite, then re-sync.
Customer could not be resolved — when
Entity_Idcannot match a NetSuite customer by ID or email, the refund cannot be created. Resolution: confirm the transaction's customer record is present in iPaaS.com and review the customer's own transfer error — the integration attempts to create and link it in NetSuite for you, so the fix is usually on the customer record rather than a manual NetSuite entry.Location / subsidiary / posting-period rejections — NetSuite rejects the refund when the location or subsidiary name does not match, or the transaction date is outside an open posting period. Resolution: confirm the location and subsidiary names (replace the placeholders) and that the posting period is open.
Accounts Receivable not enabled — cash refunds require AR in NetSuite. Resolution: enable Accounts Receivable in your NetSuite account.
Testing & Validation
Test Scenarios
Create a cash refund. Manually sync a refunded transaction and confirm a NetSuite cash refund is created with the correct customer, lines, address, and that the internal ID is stored back on the iPaaS.com transaction.
Update a cash refund. Re-sync the same transaction after a change and confirm the existing refund is updated rather than a duplicate created.
Required-field validation. Sync a refund whose line SKU is not linked in NetSuite and confirm the error "Sku [Sku] is not linked to a NetSuite item id".
ID format. Manually sync using the iPaaS.com transaction record ID and confirm success.
Child collections. Create a refund with lines and an address; confirm each appears on the NetSuite cash refund.
Placeholders replaced. Confirm the location, subsidiary, tax code, and posting period are set to your account's values, not the shipped placeholders.
Validation Checklist
Accounts Receivable is enabled in NetSuite.
The customer resolves correctly (NetSuite ID or email).
Location and subsidiary names match your NetSuite account (not the placeholders
Califorina/Parent Company).Tax control fields carry a valid tax code (not the placeholder
5) and the Tax Override customization applies tax as expected.The transaction date falls in an open posting period.
Other Reference Number is populated and stable (the duplicate-matching key).
Additional Notes
Tax is applied by the Tax Override customization, documented in NetSuite Connections and Settings. The NetSuite SuiteTax feature is not required.
Fully paid sales are handled by Add/Update NetSuite Cash Sale FROM iPaaS.com, and returns by the Return Authorization feature; see the related mapping documentation.
Known limitations affecting transactions are collected in NetSuite Known Limitations.