WooCommerce Refund Orders

Version	Date	Created / Updated	Notes
v1.0		Hristiyan Georgiev	Initial version

When we talk about refunds on WooCommerce we are meaning seller initiated refunds, which can be pushed from us to WooCommerce.

Similair like partial shipments, the core WooCommerce REST API does not natively support creating return requests or managing return statuses directly. These features are usually part of plugins that may or may not expose their own APIs. There are plugins and we will have to build our own plugin for that. This is TBA at the moment

There is a possibility for partial refunds and full refunds.

All triggers, validations, etc are as per the abstraction Refunds send general logic

API Call : POST /wp-json/wc/v3/orders/{orderId}/refunds API Docs : https://woocommerce.github.io/woocommerce-rest-api-docs/?shell#create-a-refund

The refunds need to be done order by order so we need to be able to handle this.

The {orderId} we pick from Orders > Marketplace Order ID

Example Body :

{
    "amount": "110",
    "reason": "Testvam be",
    "line_items": [
    { 
       "id": "89",      
    "refund_total": "100"                
    }
    ]
}

Mapping :

WooCommerce Field		MCPro Field	Notes
`amount`			We need to have a logic here and if we are doing a full refund (including shipping cost) we need to submit this field for the total amount we are refunding (items+shipping). If we are refunding only items, we have to exclude this field.
We also need another logic and if we are refunding ONLY the shipment, we exclude the `line_items` object.
`reason`		`Order Payment` > `Reason`	This is a free text reason.
`line_items`
	`id`		We need to map the `Order Refund Row` > `SKU` with the ordered item SKU, and send `Product In Order` > `Item Order Line ID` in this field.
`refund_total`		`Order Refund Row` > `Amount`

Example Success Response :

{
    "id": 69,
    "date_created": "2025-05-21T13:03:04",
    "date_created_gmt": "2025-05-21T13:03:04",
    "amount": "111.00",
    "reason": "Testvam be",
    "refunded_by": 1,
    "refunded_payment": true,
    "meta_data": [
        {
            "id": 81,
            "key": "_wcpay_refund_id",
            "value": "re_3RRCHPC5BtSvngHM0mSSW8XW"
        },
        {
            "id": 82,
            "key": "_wcpay_refund_transaction_id",
            "value": "txn_3RRCHPC5BtSvngHM063IQjhX"
        }
    ],
    "line_items": [
        {
            "id": 10,
            "name": "Hoodie with stripes",
            "product_id": 62,
            "variation_id": 0,
            "quantity": 0,
            "tax_class": "",
            "subtotal": "-111.00",
            "subtotal_tax": "0.00",
            "total": "-111.00",
            "total_tax": "0.00",
            "taxes": [],
            "meta_data": [
                {
                    "id": 77,
                    "key": "_refunded_item_id",
                    "value": "7",
                    "display_key": "_refunded_item_id",
                    "display_value": "7"
                }
            ],
            "sku": "",
            "price": 0,
            "image": {
                "id": "63",
                "src": "https://sociable-sable-b1ae91.instawp.xyz/wp-content/uploads/2025/05/1715726245686.jpg"
            },
            "parent_name": null
        }
    ],
    "shipping_lines": [],
    "tax_lines": [],
    "fee_lines": [],
    "_links": {
        "self": [
            {
                "href": "https://sociable-sable-b1ae91.instawp.xyz/wp-json/wc/v3/orders/68/refunds/69",
                "targetHints": {
                    "allow": [
                        "GET",
                        "DELETE"
                    ]
                }
            }
        ],
        "collection": [
            {
                "href": "https://sociable-sable-b1ae91.instawp.xyz/wp-json/wc/v3/orders/68/refunds"
            }
        ],
        "up": [
            {
                "href": "https://sociable-sable-b1ae91.instawp.xyz/wp-json/wc/v3/orders/68"
            }
        ]
    }
}

Example Error Response :

{
    "code": "woocommerce_rest_cannot_create_order_refund",
    "message": "Invalid refund amount.",
    "data": 500
}

From the success response we only need to store the id into Order Payment > Transaction ID and treat the refund as completed as per abstraction.

If we get an error, we are to store the message from the error response in the Order Errors table with Type = Refund Send

Marketplaces / WooCommerce Technical Sccope / WooCommerce Order Management / WooCommerce Refund Orders

WooCommerce Refund Orders