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

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.

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.