Contents
Summary
ID Format
Deleted Record Support
Custom Field Support
Mapping Collection Status
Duplicate or Conflicting Mappings
Supported Child Collections
System Caveats
Setup Requirements
Integration Flow
Mappings
Error Handling
Testing and Validation
Additional Notes
Related Documents
Summary
This documentation covers WooCommerce refunds TO iPaaS.com. Each refund, partial or full, becomes an iPaaS.com Return transaction:
numbered
{order number}-R{refund id}and linked to the order's transaction as its parent;with the refunded lines (negative quantities and amounts), the refunded taxes and shipping, the order's billing address and one negative Refunded payment;
an amount-only refund (no lines) arrives with no lines and its amount.
A refund comes with its order's change: after the order is transferred, each of its refunds not yet in iPaaS.com is sent. A full refund also sets the order's status to Refunded.
ID Format
Manual Sync ID Format: Enter {order id}-R{refund id} (for example 1307-R1311).
External ID Format (saved after sync): {order id}-R{refund id}; children {order id}-R{refund id}|{part}.
Deleted Record Support
A refund deleted in WooCommerce after it reached iPaaS.com leaves its Return as it was; the order's WooCommerce Refund Ids no longer list it. Correct the Return in iPaaS.com and in any system that received it. A refund deleted while being sent is skipped (WOOC-BIZL-1009, a warning).
Custom Field Support
Yes, as for orders: a refund's public meta entries are offered as custom fields on the WooCommerce Order table.
Mapping Collection Status
The template is active and its filter takes refunds only (return IsRefund;). Leave the filter and the parent link as they are. Its line Sku formula holds the same two stand-in SKUs as the order collections: replace them the same way.
Duplicate or Conflicting Mappings
As for orders: change a mapping to a keep-formula rather than deleting it, and never let two Refund collections overlap.
This collection has no Collision Handling Method setting.
Supported Child Collections
Refund Line: the refunded lines, negative.
Refund Address: the order's billing address.
Refund Payment: one negative Refunded payment.
Refund Tax: the refunded taxes.
System Caveats
A refund of an order that never reached iPaaS.com is not sent (the order filter left it out, or it failed).
The refund's lines must be iPaaS.com products, as for orders.
Whether a Return reaches your accounting system as a credit depends on that system's own integration.
Setup Requirements
The order.updated webhook scope and the order/poll event (refunds come with their order), the stand-in SKUs and the payment method translation.
Integration Flow
A refund is made on an order in WooCommerce; WooCommerce sends the order's update webhook (or the next poll finds the order).
The order is transferred, then each refund not yet in iPaaS.com is queued as its own transfer.
This collection creates the Return, linked to the order's transaction.
Mappings
Add WooCommerce Refund TO iPaaS.com
iPaaS.com data type: Transaction. Sync type: Add. Mappings: 15.
Description: Each WooCommerce refund becomes an iPaaS.com Return transaction linked to its order, with the refunded lines (if any), the order's billing address, the tax refunded and a negative payment for the amount. Refunds arrive with the order's update webhook and the order poll, after their order. A refund of an order that never reached iPaaS.com is not sent; a refund deleted in WooCommerce leaves its Return as it is and drops off the order's WooCommerce Refund Ids.
Mapping Filter:
// Refunds only: each WooCommerce refund becomes a Return transaction linked to its order. // A refund of an order that never reached iPaaS.com is not sent. return IsRefund;
Mapping Type | Source Field (WooCommerce) | Destination Field (iPaaS.com) | Description |
Dynamic Formula | formula 1 (below) | SystemId | (Required. Do not change.) Links the transaction to this subscription; iPaaS.com refuses a new transaction without it. |
Field | Number | TransactionNumber | (Required.) The refund's number: the order number, -R and the WooCommerce refund id. |
Field | Type | Type | (Required.) Return: the refund is a return transaction. |
Lookup Translation | Status, through WooCommerce Order Status TO iPaaS.com | Status | (Required.) refunded, through the WooCommerce Order Status translation. |
Dynamic Formula | formula 2 (below) | CustomerId | (Recommended.) The iPaaS.com customer of the registered WooCommerce customer, once that customer is in iPaaS.com. A guest order has none and carries the billing email and address. |
Field | EmailAddress | (Recommended.) The billing email. | |
Field | Subtotal | Subtotal | (Recommended.) The product lines before discounts and tax. |
Field | DiscountTotal | DiscountAmount | (Optional.) Zero: refunds carry no discount. |
Field | TaxTotal | TaxAmount | (Recommended.) Total tax. |
Field | ShippingTotal | ShippingAmount | (Optional.) The shipping refunded. |
Field | Total | Total | (Required.) The amount refunded, as a negative total. |
Field | TotalQty | TotalQty | (Optional.) Total quantity of the product lines. |
Field | DateCreated | TransactionCreatedDateTime | (Recommended.) When the refund was made, in UTC. |
Field | DateModified | TransactionUpdatedDateTime | (Optional.) When the refund was made, in UTC. |
Dynamic Formula | formula 3 (below) | ParentId | (Required.) The refunded order's iPaaS.com transaction, so the Return is linked to its sale. |
Lookup Translation Tables
WooCommerce Order Status TO iPaaS.com:
Source Value (WooCommerce) | Destination Value (iPaaS.com) | Notes |
| Awaiting Payment | An unpaid order. The Add filter doesn't create it; an order already in iPaaS.com can move to it. |
| Awaiting Payment | A failed payment. The Add filter doesn't create it. |
| Processing | Paid, to be fulfilled. |
| On Hold | Awaiting confirmation of payment; WooCommerce has already reduced the stock. |
| Complete | Fulfilled. |
| Cancelled | Cancelled in WooCommerce; reaches an order already in iPaaS.com as a status change. |
| Refunded | Fully refunded. Refunds use it too. |
| Draft | A checkout not yet placed. The Add filter doesn't create it. |
A refund always sends refunded. The translation is shared with the order collections: add a row for every other status your store uses (for example one added by a plugin) before the first order with it arrives: iPaaS.com refuses an order whose status has no row (Known Limitations 33).
Dynamic Formulas (verbatim)
Formula 1, SystemId:
return SpaceportSystemId;
Formula 2, CustomerId:
// The iPaaS.com customer of a registered WooCommerce customer who is already in iPaaS.com; empty for a guest order. long id; return long.TryParse(IpaasCustomerId, out id) ? (long?)id : null;
Formula 3, ParentId:
// The refunded order's iPaaS.com transaction, so the Return is linked to its sale. long id; return long.TryParse(IpaasParentTransactionId, out id) ? (long?)id : null;
WooCommerce Refund Line TO iPaaS.com
iPaaS.com data type: Transaction Line. Child of: Add WooCommerce Refund TO iPaaS.com. Sync type: Add/Update. Mappings: 11.
Description: The refund's product lines and fee lines. Every line must be an iPaaS.com product: a product line carries the linked iPaaS.com product's SKU, else its WooCommerce SKU, else the stand-in SKU for products without one; a fee line carries the fee item SKU. Replace both placeholders before the first order arrives.
Mapping Type | Source Field (WooCommerce) | Destination Field (iPaaS.com) | Description |
Dynamic Formula | formula 4 (below) | Sku | (Required. Replace the two placeholders.) The line's iPaaS.com product SKU: the linked iPaaS.com product's SKU, else the WooCommerce SKU. Placeholder value — replace during implementation: replace "REPLACE with your SKU for products without one" with the SKU of an iPaaS.com product used for lines whose WooCommerce product has no SKU, and "REPLACE with your fee item SKU" with the SKU of the iPaaS.com product that stands for fees. Pre-install prerequisite — the transfer fails without it. Each stand-in MUST be the SKU of a product that exists in iPaaS.com: either (a) create iPaaS.com products with the SKUs you put here, or (b) put the SKUs of existing iPaaS.com products here; one of these must be done before the first order arrives. Until then, iPaaS.com refuses every order with such a line and nothing is written, with an error that names the stand-in, for example NFND-1003 - Product Id: REPLACE with your fee item SKU does not exist or can not be found. Make the same change in the other two order collections. Change only the quoted REPLACE texts and keep the quotation marks; if you replace the whole formula with a SKU, every line gets that SKU. |
Field | Name | Description | (Recommended.) The line's name as shown on the refund. |
Static |
| Type | (Required.) Product for every line. iPaaS.com accepts only Product and Gift Card lines, and a Product line must name an iPaaS.com product: fee lines travel as Product lines on the fee stand-in product the Sku mapping names. |
Dynamic Formula | formula 5 (below) | Status | (Required.) Returned on a refund, Cancelled on a cancelled order; otherwise a status another system gave the line (for example Shipped) is kept, and a line that is new or still Pending becomes Complete when the order is completed, else Pending. |
Field | Quantity | Qty | (Required.) The quantity refunded (negative). |
Field | UnitPrice | UnitPrice | (Required.) The price per unit after discounts, before tax. |
Field | OriginalUnitPrice | OriginalUnitPrice | (Optional.) The price per unit before discounts. |
Field | Total | ExtendedPrice | (Recommended.) The line amount after discounts, before tax. |
Field | DiscountAmount | DiscountAmount | (Optional.) The line's discount. |
Field | TotalTax | EstimatedTaxAmount | (Optional.) The line's tax. |
Field | TaxPercent | TaxPercent | (Optional.) The line's tax as a percent of the line amount. |
Dynamic Formulas (verbatim)
Formula 4, Sku:
// Fee lines: the iPaaS.com product that stands for fees. if (LineType == "Fee") return "REPLACE with your fee item SKU"; // Product lines: the SKU of the linked iPaaS.com product or variant (it survives a SKU edited in WooCommerce), else the WooCommerce SKU, // else the stand-in SKU for products without one. if (!string.IsNullOrWhiteSpace(IpaasSku)) return IpaasSku; if (!string.IsNullOrWhiteSpace(Sku)) return Sku; return "REPLACE with your SKU for products without one";
Formula 5, Status:
// A refund's lines are returned; a cancelled order cancels its lines. if (Parent.IsRefund) return "Returned"; if (Parent.Status == "cancelled") return "Cancelled"; // Keep a status another system gave the line (for example Shipped); a line still Pending follows the order: Complete once the order is completed. if (DestinationValue != null && !string.IsNullOrWhiteSpace(DestinationValue.Status) && DestinationValue.Status != "Pending") return DestinationValue.Status; return Parent.Status == "completed" ? "Complete" : "Pending";
WooCommerce Refund Address TO iPaaS.com
iPaaS.com data type: Transaction Address. Child of: Add WooCommerce Refund TO iPaaS.com. Sync type: Add/Update. Mappings: 14.
Description: The refund's billing address (the order's). A refund carries the billing address only: the shipping address and shipping method stay on the order.
Mapping Type | Source Field (WooCommerce) | Destination Field (iPaaS.com) | Description |
Field | IsPrimaryBilling | IsPrimaryBilling | (Recommended.) True for the billing address. |
Field | IsPrimaryShipping | IsPrimaryShipping | (Recommended.) True for a shipping address; a refund carries none, so it is false. |
Field | FirstName | FirstName | (Recommended.) First name. |
Field | LastName | LastName | (Recommended.) Last name. |
Field | Company | Company | (Optional.) Company. |
Field | Address1 | Address1 | (Recommended.) Street 1. |
Field | Address2 | Address2 | (Optional.) Street 2. |
Field | City | City | (Recommended.) City. |
Field | State | Region | (Recommended.) State or county code. |
Field | Postcode | PostalCode | (Recommended.) Postal code. |
Field | Country | Country | (Recommended.) Two-letter country code. |
Lookup Translation | ShippingMethod, through WooCommerce Shipping Method TO iPaaS.com | ShippingMethod | (Recommended.) Shipping address only, so empty on a refund (a refund carries the billing address only): the WooCommerce shipping method through the WooCommerce Shipping Method translation. Add a row for every shipping method your store offers. |
Field | ShippingMethodDescription | ShippingMethodDescription | (Optional.) Shipping address only, so empty on a refund (a refund carries the billing address only): the shipping method's name as the shopper saw it. |
Field | ShippingAmount | ShippingAmount | (Optional.) Shipping address only, so empty on a refund (a refund carries the billing address only): the shipping charge before tax. |
Lookup Translation Tables
WooCommerce Shipping Method TO iPaaS.com:
Source Value (WooCommerce) | Destination Value (iPaaS.com) | Notes |
| Your iPaaS.com shipping method for flat-rate delivery | WooCommerce's Flat rate method. |
| Your iPaaS.com shipping method for free delivery | WooCommerce's Free shipping method. |
| Your iPaaS.com shipping method for collection | WooCommerce's Local pickup method. |
Placeholder value — replace during implementation: each destination in the template starts with REPLACE with. Replace it with the matching shipping method of your iPaaS.com company, and add a row for every other shipping method your store offers. Pre-install prerequisite — the transfer fails without it. Every target MUST be the exact name of a Shipping Method in your iPaaS.com company: either (a) set the target to one of your iPaaS.com Shipping Methods, or (b) create a Shipping Method in iPaaS.com with the target's name; one of these must be done before the first order arrives. A target still reading REPLACE with, or naming a method your company doesn't have, refuses the whole order and nothing is written, with VALD-1036 - Value (…) provided for Address Shipping Method is not valid, naming the value.
WooCommerce Refund Payment TO iPaaS.com
iPaaS.com data type: Transaction Payment. Child of: Add WooCommerce Refund TO iPaaS.com. Sync type: Add/Update. Mappings: 4.
Description: The refund's negative payment for the amount refunded, with the order's payment method through the WooCommerce Payment Method translation.
Mapping Type | Source Field (WooCommerce) | Destination Field (iPaaS.com) | Description |
Lookup Translation | Method, through WooCommerce Payment Method TO iPaaS.com | Method | (Required.) The WooCommerce payment method through the WooCommerce Payment Method translation. iPaaS.com refuses a payment whose method is still a REPLACE text or isn't one of your Payment Methods (Payment Method is not valid). iPaaS.com refuses a refund whose payment method has no row and nothing is written; add a row for every payment method your store uses, then send the refund again. |
Field | Amount | Amount | (Required.) The amount refunded, negative. |
Field | Status | Status | (Required.) Refunded. |
Dynamic Formula | formula 6 (below) | Description | (Optional.) The payment method's name, the gateway's transaction id, whether the refund was recorded manually, and the refund reason. |
Lookup Translation Tables
WooCommerce Payment Method TO iPaaS.com:
Source Value (WooCommerce) | Destination Value (iPaaS.com) | Notes |
| Your iPaaS.com payment method for bank transfers | WooCommerce's Direct bank transfer method. |
| Your iPaaS.com payment method for check payments | WooCommerce's Check payments method. |
| Your iPaaS.com payment method for cash on delivery | WooCommerce's Cash on delivery method. |
| Your iPaaS.com payment method for card payments | WooCommerce's own card payments. |
Placeholder value — replace during implementation: each destination in the template starts with REPLACE with. Replace it with the matching payment method of your iPaaS.com company, and add a row for every other payment method your store offers, using the method's id from WooCommerce > Settings > Payments. Pre-install prerequisite — the transfer fails without it. Every target MUST be the exact name of a Payment Method in your iPaaS.com company: either (a) set the target to one of your iPaaS.com Payment Methods, or (b) create a Payment Method in iPaaS.com with the target's name; one of these must be done before the first order arrives. Nothing is written when a paid order is refused: an order whose method has no row is refused whole, and one whose target still reads REPLACE with or names a method your company doesn't have is refused with VALD-1036 - Value (…) provided for Payment Method is not valid, naming the value.
Dynamic Formulas (verbatim)
Formula 6, Description:
// The payment method's name and the payment gateway's transaction id. var text = !string.IsNullOrWhiteSpace(MethodTitle) ? MethodTitle : Method; if (!string.IsNullOrWhiteSpace(TransactionId)) text = text + " " + TransactionId; // A refund says whether the money went back through the gateway, and why. if (RefundedThroughGateway == false) text = text + " (refund recorded manually)"; if (!string.IsNullOrWhiteSpace(Parent.RefundReason)) text = text + ": " + Parent.RefundReason; return text;
WooCommerce Refund Tax TO iPaaS.com
iPaaS.com data type: Transaction Tax. Child of: Add WooCommerce Refund TO iPaaS.com. Sync type: Add/Update. Mappings: 3.
Description: One record per tax rate on the refund, with the tax on items and shipping together.
Mapping Type | Source Field (WooCommerce) | Destination Field (iPaaS.com) | Description |
Dynamic Formula | formula 7 (below) | Authority | (Recommended.) The tax rate's label, else its code. |
Field | Amount | Amount | (Required.) The tax for this rate, items plus shipping. |
Field | RatePercent | TaxPercent | (Optional.) The rate as a percentage. |
Dynamic Formulas (verbatim)
Formula 7, Authority:
return !string.IsNullOrWhiteSpace(Label) ? Label : Code;
Error Handling
Every error the integration raises carries a WOOC- code; WooCommerce Error Messages has the full text, cause and what to do for each. iPaaS.com's own refusals have no WOOC- prefix. Connection errors (Store URL, key, host) can stop any transfer and are listed there under "Connection and settings".
Code | When | What to do | Retried by iPaaS.com |
WOOC-VALD-1011 | The transfer named an id that is neither an order number nor an order-refund pair. | Transfer the order from WooCommerce again; refunds follow their order. | Yes, until fixed or dismissed; it fails the same way until the cause is fixed |
WOOC-BIZL-1009 | Someone deleted the refund in WooCommerce between the order's change and the refund's transfer. | No action is needed for this refund. A refund deleted after it reached iPaaS.com leaves its return there as it was: correct that return in iPaaS.com and in any system that received it. | No; it is a warning in the subscription's log, not a transfer error |
WOOC-VALD-1014 | The stored link is not in the form this record type uses. | Remove the record's link in iPaaS.com and transfer it again. | Yes, until fixed or dismissed; it fails the same way until the cause is fixed |
iPaaS.com: "Product Id: … does not exist" | A line SKU is not an iPaaS.com product, or a stand-in SKU still reads REPLACE; the whole order is refused | Add the product in iPaaS.com, or set the stand-in SKUs, then resend the order | Yes, until fixed or dismissed |
iPaaS.com: VALD-1024 "Required property 'method'" or "'status' not found" | The order's payment method or status has no translation row; the whole order is refused | Add the row, then resend the order | Yes, until fixed or dismissed |
iPaaS.com: VALD-1036 "… provided for Payment Method (or Address Shipping Method) is not valid" | A payment or shipping method translation still holds its REPLACE target, or names a method your company doesn't have | Replace the target with the exact name of one of your iPaaS.com methods, then resend | Yes, until fixed or dismissed |
iPaaS.com: NFND-1029 "Duplicate transaction found!" | Another system already sent a transaction with that number | Prefix the TransactionNumber mapping in Add Order, Update Order and Add Refund (Known Limitations 27) | Fails the same way until the number is unique |
Testing and Validation
Follow the WooCommerce Installation Instructions, "Before you test: test safely": test on a staging copy of the store with its own subscription, if your host offers one; on your live store, test before your back-office systems are connected, with a Private test product and your own name and email address.
Refund one line of a test order in WooCommerce, choosing Refund manually: a Return numbered like
1234-R56appears, linked to the order, with that line and a negative payment.Refund the rest: a second Return appears and the order's status becomes Refunded.
Additional Notes
A paid order refunded before it first reached iPaaS.com arrives as an order with status Refunded, followed by its Return.
Related Documents
iPaaS.com <> WooCommerce: Background
Related Mapping Documentation
WooCommerce Order TO iPaaS.com Mapping Documentation
