Commit 20f9cbd795c for woocommerce
commit 20f9cbd795c45d7389db8ff855d06a0fd9a76c36
Author: Brandon Kraft <public@brandonkraft.com>
Date: Sat Mar 28 01:33:16 2026 -0500
Clarify tax semantics in Orders REST API and add refund total_tax (#63692)
* Clarify tax semantics in Orders REST API and add refund total_tax field
The Orders API schema descriptions did not communicate whether totals
include or exclude tax, causing confusion for integrators. Order-level
total is tax-inclusive while line item, shipping, and fee totals are
tax-exclusive by design, but the descriptions were ambiguous or
copy-pasted across contexts.
Also adds total_tax to inline refund data so API consumers can separate
net and tax amounts for refunds, which was previously impossible.
See #62846
diff --git a/plugins/woocommerce/changelog/63692-fix-order-api-tax-docs b/plugins/woocommerce/changelog/63692-fix-order-api-tax-docs
new file mode 100644
index 00000000000..4587e806f7a
--- /dev/null
+++ b/plugins/woocommerce/changelog/63692-fix-order-api-tax-docs
@@ -0,0 +1,4 @@
+Significance: patch
+Type: fix
+
+Clarify tax inclusion/exclusion in Orders REST API schema descriptions and add total_tax field to inline refund data.
\ No newline at end of file
diff --git a/plugins/woocommerce/includes/rest-api/Controllers/Version2/class-wc-rest-orders-v2-controller.php b/plugins/woocommerce/includes/rest-api/Controllers/Version2/class-wc-rest-orders-v2-controller.php
index 98f524765ec..0f156c654f6 100644
--- a/plugins/woocommerce/includes/rest-api/Controllers/Version2/class-wc-rest-orders-v2-controller.php
+++ b/plugins/woocommerce/includes/rest-api/Controllers/Version2/class-wc-rest-orders-v2-controller.php
@@ -426,9 +426,10 @@ class WC_REST_Orders_V2_Controller extends WC_REST_CRUD_Controller {
$data['refunds'] = array();
foreach ( $order->get_refunds() as $refund ) {
$data['refunds'][] = array(
- 'id' => $refund->get_id(),
- 'reason' => $refund->get_reason() ? $refund->get_reason() : '',
- 'total' => '-' . wc_format_decimal( $refund->get_amount(), $this->request['dp'] ),
+ 'id' => $refund->get_id(),
+ 'reason' => $refund->get_reason() ? $refund->get_reason() : '',
+ 'total' => '-' . wc_format_decimal( $refund->get_amount(), $this->request['dp'] ),
+ 'total_tax' => wc_format_decimal( (float) $refund->get_total_tax(), $this->request['dp'] ),
);
}
break;
@@ -1243,7 +1244,7 @@ class WC_REST_Orders_V2_Controller extends WC_REST_CRUD_Controller {
'readonly' => true,
),
'total' => array(
- 'description' => __( 'Grand total.', 'woocommerce' ),
+ 'description' => __( 'Grand total, including tax.', 'woocommerce' ),
'type' => 'string',
'context' => array( 'view', 'edit' ),
'readonly' => true,
@@ -1255,7 +1256,7 @@ class WC_REST_Orders_V2_Controller extends WC_REST_CRUD_Controller {
'readonly' => true,
),
'prices_include_tax' => array(
- 'description' => __( 'True the prices included tax during checkout.', 'woocommerce' ),
+ 'description' => __( 'Whether prices included tax during checkout.', 'woocommerce' ),
'type' => 'boolean',
'context' => array( 'view', 'edit' ),
'readonly' => true,
@@ -1516,7 +1517,7 @@ class WC_REST_Orders_V2_Controller extends WC_REST_CRUD_Controller {
'context' => array( 'view', 'edit' ),
),
'subtotal' => array(
- 'description' => __( 'Line subtotal (before discounts).', 'woocommerce' ),
+ 'description' => __( 'Line subtotal, excluding tax (before discounts).', 'woocommerce' ),
'type' => 'string',
'context' => array( 'view', 'edit' ),
),
@@ -1527,7 +1528,7 @@ class WC_REST_Orders_V2_Controller extends WC_REST_CRUD_Controller {
'readonly' => true,
),
'total' => array(
- 'description' => __( 'Line total (after discounts).', 'woocommerce' ),
+ 'description' => __( 'Line total, excluding tax (after discounts).', 'woocommerce' ),
'type' => 'string',
'context' => array( 'view', 'edit' ),
),
@@ -1747,12 +1748,12 @@ class WC_REST_Orders_V2_Controller extends WC_REST_CRUD_Controller {
'context' => array( 'view', 'edit' ),
),
'total' => array(
- 'description' => __( 'Line total (after discounts).', 'woocommerce' ),
+ 'description' => __( 'Shipping total, excluding tax.', 'woocommerce' ),
'type' => 'string',
'context' => array( 'view', 'edit' ),
),
'total_tax' => array(
- 'description' => __( 'Line total tax (after discounts).', 'woocommerce' ),
+ 'description' => __( 'Shipping total tax.', 'woocommerce' ),
'type' => 'string',
'context' => array( 'view', 'edit' ),
'readonly' => true,
@@ -1839,12 +1840,12 @@ class WC_REST_Orders_V2_Controller extends WC_REST_CRUD_Controller {
'enum' => array( 'taxable', 'none' ),
),
'total' => array(
- 'description' => __( 'Line total (after discounts).', 'woocommerce' ),
+ 'description' => __( 'Fee total, excluding tax.', 'woocommerce' ),
'type' => 'string',
'context' => array( 'view', 'edit' ),
),
'total_tax' => array(
- 'description' => __( 'Line total tax (after discounts).', 'woocommerce' ),
+ 'description' => __( 'Fee total tax.', 'woocommerce' ),
'type' => 'string',
'context' => array( 'view', 'edit' ),
'readonly' => true,
@@ -1991,20 +1992,26 @@ class WC_REST_Orders_V2_Controller extends WC_REST_CRUD_Controller {
'items' => array(
'type' => 'object',
'properties' => array(
- 'id' => array(
+ 'id' => array(
'description' => __( 'Refund ID.', 'woocommerce' ),
'type' => 'integer',
'context' => array( 'view', 'edit' ),
'readonly' => true,
),
- 'reason' => array(
+ 'reason' => array(
'description' => __( 'Refund reason.', 'woocommerce' ),
'type' => 'string',
'context' => array( 'view', 'edit' ),
'readonly' => true,
),
- 'total' => array(
- 'description' => __( 'Refund total.', 'woocommerce' ),
+ 'total' => array(
+ 'description' => __( 'Refund total, including tax.', 'woocommerce' ),
+ 'type' => 'string',
+ 'context' => array( 'view', 'edit' ),
+ 'readonly' => true,
+ ),
+ 'total_tax' => array(
+ 'description' => __( 'Refund total tax.', 'woocommerce' ),
'type' => 'string',
'context' => array( 'view', 'edit' ),
'readonly' => true,