Skip to main content

WooCommerce Refund TO iPaaS.com Mapping Documentation

How the WooCommerce integration brings each WooCommerce refund TO iPaaS.com as a Return transaction linked to its order, with the refunded lines, taxes and a negative payment.

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

  1. A refund is made on an order in WooCommerce; WooCommerce sends the order's update webhook (or the next poll finds the order).

  2. The order is transferred, then each refund not yet in iPaaS.com is queued as its own transfer.

  3. 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

Email

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

pending

Awaiting Payment

An unpaid order. The Add filter doesn't create it; an order already in iPaaS.com can move to it.

failed

Awaiting Payment

A failed payment. The Add filter doesn't create it.

processing

Processing

Paid, to be fulfilled.

on-hold

On Hold

Awaiting confirmation of payment; WooCommerce has already reduced the stock.

completed

Complete

Fulfilled.

cancelled

Cancelled

Cancelled in WooCommerce; reaches an order already in iPaaS.com as a status change.

refunded

Refunded

Fully refunded. Refunds use it too.

checkout-draft

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

Product

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

flat_rate

Your iPaaS.com shipping method for flat-rate delivery

WooCommerce's Flat rate method.

free_shipping

Your iPaaS.com shipping method for free delivery

WooCommerce's Free shipping method.

local_pickup

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

bacs

Your iPaaS.com payment method for bank transfers

WooCommerce's Direct bank transfer method.

cheque

Your iPaaS.com payment method for check payments

WooCommerce's Check payments method.

cod

Your iPaaS.com payment method for cash on delivery

WooCommerce's Cash on delivery method.

woocommerce_payments

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.

  1. Refund one line of a test order in WooCommerce, choosing Refund manually: a Return numbered like 1234-R56 appears, linked to the order, with that line and a negative payment.

  2. 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

Related Mapping Documentation

  • WooCommerce Order TO iPaaS.com Mapping Documentation

Did this answer your question?