Order refunds

The order refunds API allows you to create, view, and delete individual refunds, based on an existing order.

Order refund properties

Attribute	Type	Description
id	integer	Unique identifier for the resource. READ-ONLY
date_created	date-time	The date the order refund was created, in the site's timezone. READ-ONLY
date_created_gmt	date-time	The date the order refund was created, as GMT. READ-ONLY
amount	string	Total refund amount. Optional. If this parameter is provided, it will take precedence over line item totals, even when total of line items does not matches with this amount.
reason	string	Reason for refund.
refunded_by	integer	User ID of user who created the refund.
refunded_payment	boolean	If the payment was refunded via the API. See api_refund. READ-ONLY
meta_data	array	Meta data. See Order refund - Meta data properties
line_items	array	Line items data. See Order refund - Line items properties
tax_lines	array	Tax lines data. See Order refund - Tax lines properties READ-ONLY
shipping_lines	array	Shipping lines data. See Order refund - Shipping lines properties
fee_lines	array	Fee lines data. See Order refund - Fee lines properties
api_refund	boolean	When true, the payment gateway API is used to generate the refund. Default is true. WRITE-ONLY
api_restock	boolean	When true, the selected line items are restocked Default is true. WRITE-ONLY
compute_totals	boolean	When true, the server computes per-line refund amounts from quantities and validates the request against the order's refund history. Available since WooCommerce 11.1. See Server-computed refunds. Default is false. WRITE-ONLY

Order refund - Meta data properties

Attribute	Type	Description
id	integer	Meta ID. READ-ONLY
key	string	Meta key.
value	string	Meta value.

Order refund - Line items properties

Attribute	Type	Description
id	integer	Item ID. READ-ONLY
name	string	Product name.
product_id	integer	Product ID.
variation_id	integer	Variation ID, if applicable.
quantity	integer	Quantity ordered.
tax_class	string	Tax class of product.
subtotal	string	Line subtotal (before discounts).
subtotal_tax	string	Line subtotal tax (before discounts). READ-ONLY
total	string	Line total (after discounts).
total_tax	string	Line total tax (after discounts). READ-ONLY
taxes	array	Line taxes. See Order refund line item - Taxes properties READ-ONLY
meta_data	array	Meta data. See Order refund - Meta data properties
sku	string	Product SKU. READ-ONLY
price	string	Product price. READ-ONLY

Order refund line item - Taxes properties

Attribute	Type	Description
id	integer	Tax rate ID. READ-ONLY
total	string	Tax total. READ-ONLY
subtotal	string	Tax subtotal. READ-ONLY

Order refund - Tax lines properties

Attribute	Type	Description
id	integer	Item ID. READ-ONLY
rate_code	string	Tax rate code. READ-ONLY
rate_id	integer	Tax rate ID. READ-ONLY
label	string	Tax rate label. READ-ONLY
compound	boolean	Whether or not this is a compound tax rate. READ-ONLY
tax_total	string	Tax total (not including shipping taxes). READ-ONLY
shipping_tax_total	string	Shipping tax total. READ-ONLY
meta_data	array	Meta data. See Order refund - Meta data properties

Order refund - Shipping lines properties

Attribute	Type	Description
id	integer	Item ID. READ-ONLY
method_title	string	Shipping method name.
method_id	string	Shipping method ID.
total	string	Line total (after discounts).
total_tax	string	Line total tax (after discounts). READ-ONLY
taxes	array	Line taxes. See Order refund - Tax lines properties READ-ONLY
meta_data	array	Meta data. See Order refund - Meta data properties

Order refund - Fee lines properties

Attribute	Type	Description
id	integer	Item ID. READ-ONLY
name	string	Fee name.
tax_class	string	Tax class of fee.
tax_status	string	Tax status of fee. Options: taxable and none.
total	string	Line total (after discounts).
total_tax	string	Line total tax (after discounts). READ-ONLY
taxes	array	Line taxes. See Order refund - Tax lines properties READ-ONLY
meta_data	array	Meta data. See Order refund - Meta data properties

Create a refund

This API helps you to create a new refund for an order.

POST /wp-json/wc/v3/orders/<id>/refunds

cURL

curl -X POST https://example.com/wp-json/wc/v3/orders/723/refunds \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "amount": "30",
  "line_items": [
    {
      "id": "111",
      "refund_total": 10,
      "refund_tax": [
        {
          "id": "222",
          "refund_total": 20
        }
      ]
    }
}'

JavaScript

const data = {
	amount: '30',
	line_items: [
		{
			id: '111',
			refund_total: 10,
			refund_tax: [
				{
					id: '222',
					refund_total: 20,
				},
			],
		},
	],
};

WooCommerce.post( 'orders/723/refunds', data )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );

PHP

<?php
$data = [
     'amount' => '30',
     'line_items' => [
       [
           'id' => '111',
           'refund_total' => 10,
           'refund_tax' => [
              [
                 'id' => '222',
                 'amount' => 20
              ]
           ]
       ]
     ]
];

print_r($woocommerce->post('orders/723/refunds', $data));
?>

Python

data = {
    "amount": "30",
    "line_items": [
      {
         "id": "111",
         "refund_total": 10,
         "refund_tax": [
           {
             "id": "222",
             "refund_total": 20
           }
         ]
      }
   ]
}

print(wcapi.post("orders/723/refunds", data).json())

Ruby

data = {
  amount: "30",
  line_items: [
    {
       id: "111",
       refund_total: 10,
       refund_tax: [
         {
           id: "222",
           refund_total: 20
         }
       ]
    }
 ]
}

woocommerce.post("orders/723/refunds", data).parsed_response

JSON Response

{
	"id": 726,
	"date_created": "2017-03-21T17:07:11",
	"date_created_gmt": "2017-03-21T20:07:11",
	"amount": "10.00",
	"reason": "",
	"refunded_by": 1,
	"refunded_payment": false,
	"meta_data": [],
	"line_items": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723/refunds/726"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723/refunds"
			}
		],
		"up": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723"
			}
		]
	}
}

Line item parameters

Parameter	Type	Description
id	integer	The ID of the line item in the order.
refund_total	number	The amount to refund for this line item, excluding taxes.
refund_tax	array	Refunds for tax rates. See Refund tax parameters

Refund tax parameters

Parameter	Type	Description
id	integer	The ID of the tax rate.
refund_total	number	The amount of tax to refund for this line item.

Server-computed refunds (compute_totals)

Available since WooCommerce 11.1.

Set compute_totals to true to have the server compute per-line refund amounts instead of supplying them. Line items may then send only id and quantity: the server derives each line's refund amount from the order's stored unit prices and taxes, caps it to the line's remaining refundable amount, and validates the whole request against the order's refund history. The refund amount is derived from the line items unless supplied explicitly.

cURL

curl -X POST https://example.com/wp-json/wc/v3/orders/723/refunds \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "compute_totals": true,
  "line_items": [
    {
      "id": 111,
      "quantity": 1
    }
  ]
}'

JSON Response

{
	"id": 726,
	"date_created": "2026-08-06T17:07:11",
	"date_created_gmt": "2026-08-06T20:07:11",
	"amount": "110.00",
	"reason": "",
	"refunded_by": 1,
	"refunded_payment": false,
	"meta_data": [],
	"line_items": [ ]
}

Line item parameters with compute_totals

Parameter	Type	Description
id	integer	The ID of the line item in the order. Each line item may appear only once per request.
quantity	integer	The number of units to refund. The server computes the amount for the quantity.
refund_total	number	Optional explicit amount for this line. Tax-inclusive when refund_tax is omitted (the server splits the tax portion out); tax-exclusive when refund_tax is supplied.
refund_tax	array	Optional explicit tax refunds. See Refund tax parameters

When amount is supplied together with compute_totals, it must be at least the computed line items total and no more than the order's remaining refundable amount. Requests that exceed what is still refundable are rejected with HTTP 400 or 422 and error codes such as woocommerce_rest_invalid_refund_amount, woocommerce_rest_refund_exceeds_remaining, woocommerce_rest_quantity_exceeds_refundable, and woocommerce_rest_duplicate_line_item.

Older stores silently ignore compute_totals

Stores running WooCommerce below 11.1 drop the unknown compute_totals parameter and process the request with the classic behavior. A quantity-only request then creates a refund of 0.00 instead of the intended amount. Before sending computed-form requests, verify that the store supports the flag:

• Send OPTIONS /wp-json/wc/v3/orders/<id>/refunds and check that compute_totals is listed in the endpoint arguments, or
• Probe POST /wp-json/wc/v3/orders/<id>/refunds/preview, which returns rest_no_route with HTTP 404 on stores without support.

Preview a refund

Available since WooCommerce 11.1.

This API computes the totals a refund would have, without creating it. The preview uses the same calculation engine as refund creation with compute_totals, so clients do not have to replicate tax, rounding, and currency-precision logic. It requires the same capability as creating a refund.

POST /wp-json/wc/v3/orders/<id>/refunds/preview

cURL

curl -X POST https://example.com/wp-json/wc/v3/orders/723/refunds/preview \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "line_items": [
    {
      "line_item_id": 111,
      "quantity": 1
    }
  ]
}'

JSON Response

{
	"breakdown": {
		"products": {
			"items": [
				{
					"id": 111,
					"name": "T-Shirt",
					"quantity": 1,
					"subtotal": "100.00",
					"tax": "10.00",
					"total": "110.00",
					"product_id": 93
				}
			],
			"subtotal": "100.00",
			"tax": "10.00",
			"total": "110.00"
		},
		"shipping": {
			"items": [],
			"subtotal": "0.00",
			"tax": "0.00",
			"total": "0.00"
		},
		"fees": {
			"items": [],
			"subtotal": "0.00",
			"tax": "0.00",
			"total": "0.00"
		}
	},
	"subtotal": "100.00",
	"tax": "10.00",
	"total": "110.00",
	"max_refundable": "110.00"
}

Preview line item parameters

Parameter	Type	Description
line_item_id	integer	The ID of the line item in the order. Note that the preview keys lines by line_item_id where the create endpoint uses id.
quantity	integer	The number of units to preview. Shipping and fee lines must use a quantity of 1.
refund_total	number	Optional explicit tax-inclusive amount for this line.

Preview response properties

Attribute	Type	Description
breakdown	object	Refund breakdown by item type: products, shipping, and fees, each with items, subtotal, tax, and total. READ-ONLY
subtotal	string	Grand subtotal of the refund preview, excluding tax. READ-ONLY
tax	string	Grand tax total of the refund preview. READ-ONLY
total	string	Grand total of the refund preview, tax-inclusive. READ-ONLY
max_refundable	string	Maximum refundable amount remaining on the order. READ-ONLY

Invalid requests return the same errors as creation with compute_totals, for example woocommerce_rest_invalid_refund_amount for a non-positive total and woocommerce_rest_preview_exceeds_max_refundable with HTTP 422 when the preview exceeds the remaining refundable amount.

Retrieve a refund

This API lets you retrieve and view a specific refund from an order.

GET /wp-json/wc/v3/orders/<id>/refunds/<refund_id>

cURL

curl https://example.com/wp-json/wc/v3/orders/723/refunds/726 \
	-u consumer_key:consumer_secret

JavaScript

WooCommerce.get( 'orders/723/refunds/726' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );

PHP

<?php print_r($woocommerce->get('orders/723/refunds/726')); ?>

Python

print(wcapi.get("orders/723/refunds/726").json())

Ruby

woocommerce.get("orders/723/refunds/726").parsed_response

JSON Response

{
	"id": 726,
	"date_created": "2017-03-21T17:07:11",
	"date_created_gmt": "2017-03-21T20:07:11",
	"amount": "10.00",
	"reason": "",
	"refunded_by": 1,
	"refunded_payment": false,
	"meta_data": [],
	"line_items": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723/refunds/726"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723/refunds"
			}
		],
		"up": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723"
			}
		]
	}
}

Available parameters

Parameter	Type	Description
dp	string	Number of decimal points to use in each resource.

List all refunds

This API helps you to view all the refunds from an order.

Note: To view a list of refunds from your store, regardless of order, check out the refunds endpoint.

GET /wp-json/wc/v3/orders/<id>/refunds

cURL

curl https://example.com/wp-json/wc/v3/orders/723/refunds \
	-u consumer_key:consumer_secret

JavaScript

WooCommerce.get( 'orders/723/refunds' )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );

PHP

<?php print_r($woocommerce->get('orders/723/refunds')); ?>

Python

print(wcapi.get("orders/723/refunds").json())

Ruby

woocommerce.get("orders/723/refunds").parsed_response

JSON Response

[
	{
		"id": 726,
		"date_created": "2017-03-21T17:07:11",
		"date_created_gmt": "2017-03-21T20:07:11",
		"amount": "10.00",
		"reason": "",
		"refunded_by": 1,
		"refunded_payment": false,
		"meta_data": [],
		"line_items": [],
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723/refunds/726"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723/refunds"
				}
			],
			"up": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723"
				}
			]
		}
	},
	{
		"id": 724,
		"date_created": "2017-03-21T16:55:37",
		"date_created_gmt": "2017-03-21T19:55:37",
		"amount": "9.00",
		"reason": "",
		"refunded_by": 1,
		"refunded_payment": false,
		"meta_data": [],
		"line_items": [
			{
				"id": 314,
				"name": "Woo Album #2",
				"product_id": 87,
				"variation_id": 0,
				"quantity": -1,
				"tax_class": "",
				"subtotal": "-9.00",
				"subtotal_tax": "0.00",
				"total": "-9.00",
				"total_tax": "0.00",
				"taxes": [],
				"meta_data": [
					{
						"id": 2076,
						"key": "_refunded_item_id",
						"value": "311"
					}
				],
				"sku": "",
				"price": -9
			}
		],
		"_links": {
			"self": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723/refunds/724"
				}
			],
			"collection": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723/refunds"
				}
			],
			"up": [
				{
					"href": "https://example.com/wp-json/wc/v3/orders/723"
				}
			]
		}
	}
]

Available parameters

Parameter	Type	Description
context	string	Scope under which the request is made; determines fields present in response. Options: view and edit. Default is view.
page	integer	Current page of the collection. Default is 1.
per_page	integer	Maximum number of items to be returned in result set. Default is 10.
search	string	Limit results to those matching a string.
after	string	Limit response to resources published after a given ISO8601 compliant date.
before	string	Limit response to resources published before a given ISO8601 compliant date.
dates_are_gmt	boolean	Interpret after and before as UTC dates when true.
exclude	array	Ensure result set excludes specific IDs.
include	array	Limit result set to specific ids.
offset	integer	Offset the result set by a specific number of items.
order	string	Order sort attribute ascending or descending. Options: asc and desc. Default is desc.
orderby	string	Sort collection by object attribute. Options: date, modified, id, include, title and slug. Default is date.
parent	array	Limit result set to those of particular parent IDs.
parent_exclude	array	Limit result set to all items except those of a particular parent ID.
dp	integer	Number of decimal points to use in each resource. Default is 2.

Delete a refund

This API helps you delete an order refund.

DELETE /wp-json/wc/v3/orders/<id>/refunds/<refund_id>

cURL

curl -X DELETE https://example.com/wp-json/wc/v3/orders/723/refunds/726?force=true \
	-u consumer_key:consumer_secret

JavaScript

WooCommerce.delete( 'orders/723/refunds/726', {
	force: true,
} )
	.then( ( response ) => {
		console.log( response.data );
	} )
	.catch( ( error ) => {
		console.log( error.response.data );
	} );

PHP

<?php print_r($woocommerce->delete('orders/723/refunds/726', ['force' => true])); ?>

Python

print(wcapi.delete("orders/723/refunds/726", params={"force": True}).json())

Ruby

woocommerce.delete("orders/723/refunds/726", force: true).parsed_response

JSON Response

{
	"id": 726,
	"date_created": "2017-03-21T17:07:11",
	"date_created_gmt": "2017-03-21T20:07:11",
	"amount": "10.00",
	"reason": "",
	"refunded_by": 1,
	"refunded_payment": false,
	"meta_data": [],
	"line_items": [],
	"_links": {
		"self": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723/refunds/726"
			}
		],
		"collection": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723/refunds"
			}
		],
		"up": [
			{
				"href": "https://example.com/wp-json/wc/v3/orders/723"
			}
		]
	}
}

Available parameters

Parameter	Type	Description
force	string	Required to be true, as resource does not support trashing.