NetSuite Return Authorization From iPaaS.com Mapping Documentation
Summary
NetSuite Return Authorization (RMA) records can be created and updated from iPaaS.com return transactions. When a return is received in iPaaS.com, the integration creates a Return Authorization in NetSuite against the originating Sales Order, with the requested return lines and optional shipping-refund and tax-refund lines. This document covers the four mapping collections that manage the Return Authorization lifecycle:
Add NetSuite RMA FROM iPaaS.com (parent) and Add NetSuite RMA Line FROM iPaaS.com (child)
Update NetSuite RMA FROM iPaaS.com (parent) and Update NetSuite RMA Line FROM iPaaS.com (child)
Purpose & Function
The integration creates a Return Authorization in NetSuite from an iPaaS.com return transaction and keeps it linked to the originating Sales Order. The Add collections create the Return Authorization on the first return event for a Sales Order; the Update collections apply later return activity to the existing Return Authorization rather than creating a duplicate, replacing its lines with the return's current lines.
Scope of this integration. The integration is responsible only for sending the Return Authorization (and its return lines) into NetSuite and maintaining the transaction linkage to the originating Sales Order.
The following are intentionally out of scope and are handled natively inside NetSuite by the account's own configuration/customization:
Credit Memo generation
Customer refunds and refund logic
Transforming the Return Authorization into a Credit Memo
Item Receipt processing (physical inventory return)
This separates financial refund processing and physical inventory return — both owned by NetSuite — from the Return Authorization creation that this integration performs.
ID Format
Manual Sync ID: the iPaaS.com record ID of the return transaction, entered in the IPAAS.COM input field on the iPaaS.com Manual Sync page.
External ID Format: on a successful transfer, the integration stores the NetSuite Return Authorization's internal ID back on the iPaaS.com transaction as its external ID (for example,
74188). Subsequent transfers for the same return use that link to update the existing Return Authorization instead of creating a new one.
Deleted Record Support
Outbound delete is not part of this feature. Returns are created and updated only; there is no delete mapping for Return Authorizations.
Custom Field Support
Any NetSuite transaction body custom field — a field whose ID starts with custbody (for example custbody_return_reason or custbody8921) — can be set on the Return Authorization header, on both create and update. There is no fixed list; either mapping style works:
Map a value directly to a destination field named with the NetSuite custom field ID, or
Carry it in an iPaaS.com custom field whose name matches the NetSuite custom field ID.
If the same field is supplied both ways, the direct mapping wins. Other custom field types — line fields (custcol…), entity, item and record fields — are not sent on the header; they are skipped and logged.
The custom field must exist in NetSuite (Customization → Lists, Records & Fields → Transaction Body Fields) and be applied to Return Authorization transactions, or NetSuite rejects the return. Values are sent exactly as mapped, so they must use NetSuite's REST format for the field type: text/number/checkbox as plain values, dates as YYYY-MM-DD, list/record fields as { "id": "<internal id>" }, and multi-select fields as { "items": [ { "id": "<internal id>" } ] }.
Mapping Collection Status
Enabled. Trigger events: Create (Add collections) and Update (Update collections).
Duplicate or Conflicting Mappings
The following collections handle related transaction types from iPaaS.com. Which collection processes a given transaction is determined by each collection's filter, so a return routes only to the RMA collections. Review these filters and each collection's Add/Update settings before enabling, and confirm the intended source of truth for each transaction type:
NetSuite Cash Refund Add From iPaaS
NetSuite Cash Sale Add From iPaaS
NetSuite Sales Order Add From iPaaS
NetSuite Sales Order Cancel From iPaaS
NetSuite Sales Order Update From iPaaS
Supported Child Collections
Add NetSuite RMA FROM iPaaS.com → Add NetSuite RMA Line FROM iPaaS.com — supplies the individual return line items.
Update NetSuite RMA FROM iPaaS.com → Update NetSuite RMA Line FROM iPaaS.com — supplies the return's current lines when an existing Return Authorization is updated.
System Caveats
NetSuite Caveats
The Sales Order must be fulfilled before the Return Authorization is created. NetSuite only allows a returnable quantity from fulfilled items; an unfulfilled order has nothing to return and the create fails.
Transform behavior. The Return Authorization is created from the originating Sales Order using the NetSuite Transform API, in a single step holding only the lines being returned, so lines that are not being returned never appear on it. NetSuite scripts or workflows that run when a Return Authorization is created, such as one that creates a credit memo, see the final record.
Totals are computed by NetSuite from the return lines. The line amounts and taxes (amount, rate, taxability) directly determine the return's subtotal, tax, and total. The mapped header Total is carried for reference and reconciliation only — it is not honored in lieu of the line-based computation.
The return reuses the originating order's tax rate. The originating Sales Order's tax rate is recorded on a NetSuite custom field by a NetSuite customization and applied to each return line by the line's taxable flag; the NetSuite SuiteTax feature is not required. By default the return's tax is instead refunded as its own Tax Refund line and the return lines are sent non-taxable, so this tax rate applies only when the tax-refund mappings are removed (see Setup Requirements).
Multiple Return Authorizations per Sales Order are permitted. Each references the same originating Sales Order; the integration links subsequent returns to the existing Return Authorization where one already exists for the transaction.
Source (iPaaS.com) Caveats
The return transaction must reference a valid originating Sales Order, not be in a cancelled state, and include at least one return line item, a shipping refund, or a tax refund — shipping-only and tax-only returns (only the shipping charge and/or the tax refunded, no merchandise) are supported.
Returnable items must exist on the originating Sales Order; an item that is not on the order cannot be returned.
Integration-Specific Caveats
Originating Sales Order handling. You don't pre-create the originating order in NetSuite. If it isn't already linked, the integration attempts to create it from the source as a prerequisite ("Unable to create parent sales order. This prevents creating the return transaction." if that fails). The order must still be fulfilled for a returnable quantity to exist — fulfillment, not manual order creation, is the gate; auto-fulfillment is driven by the Sales Order Line CreateItemFullfilment control field.
Over-quantity returns are authorized at the Return Authorization stage. The integration does not block a return quantity that exceeds the originating Sales Order quantity — the Return Authorization is created or updated as sent. NetSuite enforces refund and return limits downstream at the Item Receipt stage, which is out of scope for this integration. Subscribers should not rely on the Return Authorization step to cap over-returns.
Discounts must be reflected in the line unit price. The return line Amount is calculated as quantity × the per-unit rate, so a discount is honored only when the source has already applied it to the unit price (so that unit price × quantity equals the discounted line total). If a connected platform keeps the full unit price and carries the discount separately — in a line discount amount and/or a discounted extended price — the return line posts at the full unit price × quantity and the discount is not reflected in the return total. Depending on how each source platform stores discounts on the iPaaS.com order, this mapping may require adjustment during onboarding; subscribers whose source stores discounts separately should validate return line amounts in a staging environment before relying on them.
Lifecycle ownership. This integration creates and updates the Return Authorization only. NetSuite owns the subsequent refund/credit-memo and Item Receipt steps.
Shipping refunds are represented as a dedicated return line — see Setup Requirements and the Add RMA mappings below. A shipping-only return (a shipping refund with no merchandise lines) is supported.
Returned items are linked to the first matching order line. Each returned line keeps a link to a Sales Order line. When the order carries the same item on more than one line, a return line does not identify the order line it came from, so the integration links a returned item to the first line on the order with that item that still has quantity to return, whatever quantity is returned. Orders that carry each item on one line are not affected.
Tax refunds are represented, by default, as a dedicated Tax Refund line, and the returned item lines are then sent non-taxable so the tax is refunded once — see Setup Requirements and the Add RMA mappings below.
Updates replace the Return Authorization's lines. Each update from iPaaS.com replaces the Return Authorization's lines with the return's current lines, so lines added to it in NetSuite (for example, a restocking fee) are removed. Change a return's lines on the iPaaS.com return; add NetSuite-only lines after the last update from iPaaS.com, or disable Update NetSuite RMA FROM iPaaS.com if your returns are only created from iPaaS.com.
The Return Authorization holds only the returned items. When only some of an order's items are returned, the order's remaining items are removed from the Return Authorization, both when it is created and when it is updated. Because no zero-quantity lines are sent, items NetSuite will not accept at a quantity of zero (for example certain non-inventory or service items) do not cause a failure, and the Exclude RMA lines by Internal Item IDs subscription setting is no longer used. Lines added to the Return Authorization manually in NetSuite are removed the next time the integration updates it.
Setup Requirements
NetSuite Configuration
Shipping-Refund item. A NetSuite item used to represent a shipping-refund line on the Return Authorization. It must be type Other Charge (OthCharge) with subtype For Sale (Sale). Create it under Lists → Items → Items → New, assign an income account, save, and note the Internal ID. Set ShippingRefundItemId to that Internal ID in the mapping. If the item is missing or of the wrong type when a shipping refund is included, the integration raises a validation error and the return is not created.
Tax-Refund item. A NetSuite item used to represent the tax-refund line, added by default when a return carries a tax amount. It must be type Other Charge (OthCharge) with subtype For Sale (Sale) and can be the same item as the shipping-refund item. Create it the same way, note the Internal ID, and set TaxRefundItemId to it on both RMA collections. If the item is missing or of the wrong type when a tax refund is included, the integration raises a validation error and the return is not created or updated. To have NetSuite calculate the return's tax on the return lines instead, remove the TaxRefundAmount and TaxRefundItemId mappings from both Add NetSuite RMA FROM iPaaS.com and Update NetSuite RMA FROM iPaaS.com, and remove || TaxAmount > 0 from both collection filters, so a return that carries only a tax amount is skipped rather than reported as an error.
Subsidiary (OneWorld accounts). The return's subsidiary is resolved by name; the subsidiary name configured in the mapping must match a subsidiary in your NetSuite account.
Posting period / transaction date. The transaction date must fall within an open NetSuite accounting (posting) period. Configure these so they resolve to an open period for each return — ideally sourced from a custom field per order rather than a fixed value.
Default Return Authorization Status. Confirm the NetSuite preference for the default status applied to newly created Return Authorizations matches your intended workflow.
Integration Flow
A return transaction is received in iPaaS.com (via Manual Sync or an enabled outbound trigger).
The collection filter validates the transaction: it must be a non-cancelled return that references a valid originating Sales Order and includes at least one return line, a shipping refund, or a tax refund (shipping-only and tax-only returns are supported).
The integration resolves the customer the same way as the Sales Order (the company's NetSuite ID for a company order, then the customer's NetSuite ID, then a match by email; otherwise created as a prerequisite) and the originating Sales Order (the CreatedFrom_Id mapping — created from the source if it is not yet linked), then the subsidiary and posting period.
Add: a Return Authorization is created from the originating Sales Order via the Transform API in a single step, holding only the requested return lines, plus a shipping-refund line when a shipping amount is present and a tax-refund line when a tax amount is present. Each returned line keeps its link to a Sales Order line: the first order line with that item that still has quantity to return. A return that carries a shipping or tax refund but no return lines (a shipping-only or tax-only return) is supported — the Return Authorization holds only the refund lines. A return with no return lines and no shipping or tax refund, or with a missing or invalid refund item, is rejected before anything is created in NetSuite. If NetSuite rejects a return line, the create fails and nothing is created in NetSuite. If reading the new Return Authorization back fails, the integration deletes it and reports the error; if it cannot be deleted, the reported error (NETS-EXTN-1021) names the Return Authorization to delete in NetSuite.
Update: when a Return Authorization already exists for the transaction, its lines are replaced with the return's current lines: lines already on it are updated in place (keeping their link to the Sales Order line), new return lines are added, and any other line is removed, including lines added to the Return Authorization in NetSuite. The shipping-refund and tax-refund lines are updated in place to the return's current amounts; if a later update carries no tax amount, the tax-refund line is removed and the return lines go back to the taxable setting from the line mappings.
The NetSuite Return Authorization internal ID is saved back to the iPaaS.com transaction as its external ID, linking subsequent transfers to the same Return Authorization.
NetSuite handles the downstream refund/credit-memo and any Item Receipt natively — these are out of scope for this integration.
Mappings
Add NetSuite RMA FROM iPaaS.com (parent)
iPaaS.com data type: Transaction
Mapping Filter:
if (
(Lines.Count > 0 || ShippingAmount > 0 || TaxAmount > 0) &&
Type != "Invoice" &&
Type == "Return" &&
Status != "Cancelled" &&
Total >= 0 &&
ParentId > 0
)
{
return true;
}return false;Only valid return transactions are processed: the transaction must be typed as a return, not be cancelled, have a non-negative total, reference a valid originating Sales Order, and include at least one return line item, a shipping refund, or a tax refund. Shipping-only and tax-only returns — only the shipping charge and/or the tax refunded, with no merchandise returned — are supported. The tax condition (TaxAmount > 0) belongs with the tax-refund mappings: remove it if you remove them (see Setup Requirements).
Mapping Type | Source / Formula | Destination Field | Description |
Dynamic Formula | builds an "RMA" memo: transaction number, summed line totals plus shipping, and tax | Memo | Optional. A human-readable return memo (for example, "RMA 1023 $149.50 Tax: $12.00"). |
Field | TransactionNumber | OtherRefNum | Recommended. Stores the originating transaction number on the return's Other Reference Number for traceability. |
Field | Total | Total | Optional. Carried for reference/reconciliation; NetSuite computes the actual return total from the lines. |
Dynamic Formula | Company NetSuite ID, else customer NetSuite ID, else match by email | Entity_Id | Required. The customer the return belongs to, identified the same way as the Sales Order's, so the Return Authorization stays on the order's customer; the create fails without it. |
Dynamic Formula | subsidiary resolved by name | Subsidiary_Id | Required on OneWorld accounts. Placeholder value — replace during implementation: the subsidiary name is set to an example value ( |
Field | ShippingAmount | ShippingCost | Recommended. The shipping amount being refunded; when greater than zero, a shipping-refund line is added automatically (see ShippingRefundItemId). |
Dynamic Formula | posting-period validation for the transaction date | TransactionDate | Required. Placeholder value — replace during implementation: the accounting period ( |
Dynamic Formula | originating Sales Order external ID (from ParentId) | CreatedFrom_Id | Required. The originating Sales Order the return is transformed from; it must already exist and be fulfilled in NetSuite. |
Static |
| CreateTransactionAs | Control field. Routes the transaction to create a Return Authorization; the value must be exactly order return. |
Static | Internal ID of the shipping-refund item | ShippingRefundItemId | Required when a shipping refund is included. Placeholder value — replace during implementation: set to the Internal ID of your own Other Charge / For Sale shipping-refund item (example ships as |
Field | TaxAmount | TaxRefundAmount | Optional, mapped by default. The tax amount being refunded; when greater than zero, a tax-refund line is added automatically (see TaxRefundItemId) and the returned item lines are sent non-taxable, so the tax is refunded once as its own line. Remove this mapping (with TaxRefundItemId and the filter's tax condition) to have NetSuite calculate the tax on the return lines instead. |
Static | Internal ID of the tax-refund item | TaxRefundItemId | Required when a tax refund is included. Placeholder value — replace during implementation: set to the Internal ID of your own Other Charge / For Sale tax-refund item (example ships as |
Add NetSuite RMA Line FROM iPaaS.com (child)
iPaaS.com data type: Transaction Line
Supplies the individual return line items for the Return Authorization. The line Amount, Rate, and IsTaxable values directly contribute to NetSuite's computed totals (subtotal, tax, and total); the mapped header Total is not honored in their place.
Mapping Type | Source / Formula | Destination Field | Description |
Dynamic Formula |
| Item_Id | Required. The NetSuite item being returned, resolved from the line SKU; must be a line on the originating Sales Order. |
Field | Qty | Quantity | Required. The quantity being returned on this line. |
Dynamic Formula |
| Amount | Required. The extended line amount; directly contributes to the NetSuite-computed return totals. |
Dynamic Formula |
| Rate | Required. The per-unit rate for the returned line. |
Field | (line taxability) | IsTaxable | Required. Whether the line is taxed; contributes to the computed return tax (the return reuses the originating order's tax rate; SuiteTax is not required). When the return refunds its tax as a separate line, every return line is sent non-taxable regardless of this value. |
Field | (line description) | Description | Optional. The line description carried to the Return Authorization line. |
Update NetSuite RMA FROM iPaaS.com (parent)
iPaaS.com data type: Transaction
Mapping Filter:
if (
(Lines.Count > 0 || ShippingAmount > 0 || TaxAmount > 0) &&
Type != "Invoice" &&
Type == "Return" &&
Status != "Cancelled" &&
Status != "Refunded" &&
Total >= 0 &&
ParentId > 0
)
{
return true;
}return false;Same as the Add filter, with the additional exclusion of Refunded transactions.
The field mappings match the Add parent (Memo, OtherRefNum, Total, Entity_Id, Subsidiary_Id, ShippingCost, TransactionDate, CreatedFrom_Id, CreateTransactionAs, ShippingRefundItemId, TaxRefundAmount, TaxRefundItemId), with the same classifications and placeholder callouts. On update, the Return Authorization's lines are replaced with the return's current lines: lines already on it are updated in place (keeping their link to the Sales Order line), new return lines are added, and any line that is not on the return is removed — including Sales Order lines that were never returned and lines a NetSuite user added to the Return Authorization, such as a restocking fee.
Update NetSuite RMA Line FROM iPaaS.com (child)
iPaaS.com data type: Transaction Line
The field mappings match the Add RMA Line child (Item_Id, Quantity, Amount, Rate, IsTaxable, Description). On update, these lines replace the Return Authorization's lines: lines already on it are updated in place, new return lines are added, and lines that are not on the return are removed, including lines added to the Return Authorization in NetSuite.
Error Handling
Missing or unresolved required data. Return Authorization creation fails when a required value cannot be resolved — for example, an unresolved customer (no company or customer NetSuite ID and no email match), a missing or unfulfilled originating Sales Order, or a subsidiary name that does not match a NetSuite subsidiary. Ensure the required header fields (Entity_Id, CreatedFrom_Id, TransactionDate, Memo, CreateTransactionAs) resolve before transfer.
Posting period closed or date out of range. If the transaction date is empty or falls outside the selected posting period, NetSuite rejects the return; supply a date within an open period.
Shipping-refund item invalid. When a shipping refund is included but ShippingRefundItemId is missing or references an item that is not Other Charge / For Sale, the integration raises a validation error and the return is not created.
Tax-refund item invalid. When a tax refund is included but TaxRefundItemId is missing or references an item that is not Other Charge / For Sale, the integration raises a validation error (NETS-VALD-1014 or NETS-VALD-1015) and the return is not created or updated.
Unfulfilled Sales Order. If the originating Sales Order is not fulfilled, there is no returnable quantity and the create fails. NetSuite returns an error similar to: "Unable to process transfer. Reason: Bad Request! Error while accessing a resource. You can not initialize returnauthorization: invalid reference 79518." — the reference number identifies the originating Sales Order and will vary. Fulfill the Sales Order before sending the return.
Return lines rejected. If NetSuite rejects a return line (for example, an item that does not exist in NetSuite), the create fails, nothing is created, and the error is reported in Dashboard / Integration Monitoring / Error Logs. Correct the return and send it again. If the error is NETS-EXTN-1021, reading the new Return Authorization back failed and the integration could not delete it: delete the Return Authorization it names in NetSuite first, so the retry does not create a second one.
Additional Notes
Known limitations affecting returns are collected in NetSuite Known Limitations.
Related Documents
Related Mapping Documentation