class-wc-rest-order-refunds-controller.php
<?php
/**
* REST API Order Refunds controller
*
* Handles requests to the /orders/<order_id>/refunds endpoint.
*
* @package WooCommerce\RestApi
* @since 2.6.0
*/
defined( 'ABSPATH' ) || exit;
use Automattic\WooCommerce\Internal\RestApiParameterUtil;
use Automattic\WooCommerce\Internal\CostOfGoodsSold\CogsAwareTrait;
use Automattic\WooCommerce\Internal\RestApi\Routes\V4\Refunds\DataUtils;
use Automattic\WooCommerce\Internal\RestApi\Routes\V4\Refunds\Schema\RefundPreviewSchema;
use Automattic\WooCommerce\Utilities\MetaDataUtil;
/**
* REST API Order Refunds controller class.
*
* @package WooCommerce\RestApi
* @extends WC_REST_Order_Refunds_V2_Controller
*/
class WC_REST_Order_Refunds_Controller extends WC_REST_Order_Refunds_V2_Controller {
use CogsAwareTrait;
/**
* Endpoint namespace.
*
* @var string
*/
protected $namespace = 'wc/v3';
/**
* Register the routes for order refunds, including the refund preview route.
*
* The override is new in 11.1.0 even though the parent method is not, hence
* the tag per the convention for public methods.
*
* @return void
*
* @since 11.1.0
*/
public function register_routes() {
parent::register_routes();
register_rest_route(
$this->namespace,
'/' . $this->rest_base . '/preview',
array(
'args' => array(
'order_id' => array(
'description' => __( 'The order ID.', 'woocommerce' ),
'type' => 'integer',
),
),
// permission_callback below intentionally uses the create-refund capability:
// preview is read-only but logically part of the refund-creation flow, so it
// requires the same capability. This prevents read-only-API clients from
// probing refund state on orders they cannot act on.
array(
'methods' => WP_REST_Server::CREATABLE,
'callback' => array( $this, 'preview_refund' ),
'permission_callback' => array( $this, 'create_item_permissions_check' ),
'args' => array(
'line_items' => $this->get_preview_line_items_arg_schema(),
),
),
'schema' => array( $this, 'get_public_preview_schema' ),
)
);
}
/**
* Preview a refund without creating it.
*
* Returns server-computed refund totals and per-line breakdowns for the
* requested line items, using the same calculation engine as the wc/v4
* refunds endpoints, so clients do not have to replicate tax, rounding,
* and currency-precision logic.
*
* @param WP_REST_Request $request Full details about the request.
* @return WP_REST_Response|WP_Error
*
* @phpstan-param WP_REST_Request<array<string, mixed>> $request
*
* @since 11.1.0
*/
public function preview_refund( $request ) {
$order = wc_get_order( (int) $request['order_id'] );
// wc_get_order returns WC_Order|WC_Order_Refund|false; only a WC_Order
// (shop_order) is previewable here — refunds and missing IDs are rejected.
if ( ! $order instanceof WC_Order ) {
return new WP_Error( 'woocommerce_rest_invalid_order_id', __( 'Invalid order ID.', 'woocommerce' ), array( 'status' => 404 ) );
}
// The shared engine runs the whole pipeline: normalize, validate, build,
// and the aggregate guards. Its WP_Errors carry their HTTP status in the
// error data and use unprefixed codes (the engine is convention neutral);
// they are prefixed here at the v3 boundary so this endpoint follows the
// `woocommerce_rest_*` convention of the rest of the v3 surface.
$preview = $this->get_data_utils()->compute_refund_preview_or_error( $order, $request['line_items'], 'wc-rest-refunds' );
if ( is_wp_error( $preview ) ) {
return $this->prefix_error_code( $preview );
}
$preview = $this->add_preview_additional_fields( $preview, $request );
$response = rest_ensure_response( $preview );
/**
* Filters the refund preview response before it is returned, following the
* `woocommerce_rest_prepare_*` family contract. The preview is advisory:
* the create path re-validates independently, so filtered values cannot
* bypass the creation guards.
*
* @param WP_REST_Response $response The preview response. Its data carries
* breakdown, subtotal, tax, total, max_refundable.
* @param WC_Order $order The order the refund preview was computed for.
* @param WP_REST_Request $request The request.
*
* @since 11.1.0
*/
return apply_filters( 'woocommerce_rest_prepare_order_refund_preview', $response, $order, $request );
}
/**
* Populate fields registered for the preview object type into a response.
*
* The stock add_additional_fields_to_object() resolves the object type from
* this controller's item schema (`order_refund`), so it would populate the
* wrong field set; the preview publishes its schema as
* `order_refund_preview` and must populate the fields registered for that
* type. Mirrors core's `_fields` handling: callbacks for fields the request
* excludes are not executed, so extension callbacks do not run for
* responses that will not carry their field. Runs before the response
* filter so filters see the complete payload.
*
* @param array $preview Preview response data.
* @param WP_REST_Request $request The request.
*
* @return array
*
* @phpstan-param WP_REST_Request<array<string, mixed>> $request
*/
private function add_preview_additional_fields( array $preview, $request ): array {
$additional_fields = $this->get_additional_fields( 'order_refund_preview' );
if ( empty( $additional_fields ) ) {
return $preview;
}
$fields_for_response = $this->get_preview_fields_for_response( $request );
foreach ( $additional_fields as $field_name => $field_options ) {
if ( empty( $field_options['get_callback'] ) || ! is_callable( $field_options['get_callback'] ) ) {
continue;
}
if ( ! in_array( $field_name, $fields_for_response, true ) ) {
continue;
}
$preview[ $field_name ] = call_user_func( $field_options['get_callback'], $preview, $field_name, $request, 'order_refund_preview' );
}
return $preview;
}
/**
* Get the preview fields a request asks for, mirroring core's
* get_fields_for_response() against the preview schema instead of the
* controller's item schema.
*
* @param WP_REST_Request $request The request.
*
* @return string[]
*
* @phpstan-param WP_REST_Request<array<string, mixed>> $request
*/
private function get_preview_fields_for_response( $request ): array {
$schema = $this->get_public_preview_schema();
$properties = isset( $schema['properties'] ) && is_array( $schema['properties'] ) ? $schema['properties'] : array();
// For back-compat, include any registered field with an empty schema, as
// core's get_fields_for_response() does: without a schema the field never
// reaches the published properties, but its callback must still run.
foreach ( $this->get_additional_fields( 'order_refund_preview' ) as $field_name => $field_options ) {
if ( is_null( $field_options['schema'] ) ) {
$properties[ $field_name ] = $field_options;
}
}
$fields = array_map( 'strval', array_keys( $properties ) );
if ( ! isset( $request['_fields'] ) || empty( $request['_fields'] ) ) {
return $fields;
}
$requested_fields = array_map(
static function ( $field ): string {
return trim( (string) $field );
},
wp_parse_list( $request['_fields'] )
);
if ( 0 === count( $requested_fields ) ) {
return $fields;
}
return array_values(
array_filter(
$fields,
function ( string $field ) use ( $requested_fields ): bool {
return rest_is_field_included( $field, $requested_fields );
}
)
);
}
/**
* Get the public schema for the refund preview endpoint.
*
* @return array
*
* @since 11.1.0
*/
public function get_public_preview_schema() {
$schema = wc_get_container()->get( RefundPreviewSchema::class )->get_item_schema();
$schema['title'] = 'order_refund_preview';
// Like the sibling v3 schema getters: fields registered via
// register_rest_field() must appear in the published schema.
return $this->add_additional_fields_schema( $schema );
}
/**
* Get the argument schema for the preview route's line_items parameter.
*
* Shared with the wc/v4 preview endpoint (including the line_item_id key
* naming) so clients can send the same payload to both API versions and
* the accepted shape cannot drift between them.
*
* Note the two deliberate differences from this controller's create
* endpoint: the preview keys lines by `line_item_id` where the create
* uses `id`, and the preview's `refund_total` is tax-inclusive where the
* create's classic `refund_total` is net with taxes supplied separately
* via `refund_tax` (the compute_totals create shares the preview's
* tax-inclusive semantics).
*
* @return array
*/
private function get_preview_line_items_arg_schema() {
return $this->get_data_utils()->get_preview_line_items_arg_schema();
}
/**
* Normalize one compute_totals line item to the shared engine's shape.
*
* Maps the create endpoint's public `id` key to the engine's `line_item_id`
* and validates/normalizes the scalar types. The REST schema cannot validate
* the line_items subtree (the property is readonly for backward
* compatibility), so without this check malformed values such as an array
* refund_total would reach the calculation engine and fail with a TypeError
* instead of a 400 response. Uses the same error codes as the engine's own
* validation, and casts numeric strings to their proper types.
*
* @param array $line_item Line item in the public request shape (id keys).
* @return array|WP_Error The normalized line item, or WP_Error on an invalid type.
*
* @since 11.1.0
*/
private function normalize_line_item( array $line_item ) {
// The create endpoint documents `id`; the shared engine and the preview
// endpoint key lines by `line_item_id`, and either form is accepted here.
// A payload carrying both is rejected: silently preferring one could
// refund and restock a different line than the client intended.
if ( isset( $line_item['id'], $line_item['line_item_id'] ) ) {
return new WP_Error( 'woocommerce_rest_invalid_line_item', __( 'Specify the line item with either id or line_item_id, not both.', 'woocommerce' ), array( 'status' => 400 ) );
}
if ( isset( $line_item['id'] ) ) {
$line_item['line_item_id'] = $line_item['id'];
unset( $line_item['id'] );
}
// IDs must be whole numbers (rest_is_integer): silently truncating a
// fractional id such as 123.5 to 123 would target a different line or
// tax bucket than requested.
if ( isset( $line_item['line_item_id'] ) ) {
if ( ! rest_is_integer( $line_item['line_item_id'] ) ) {
return new WP_Error( 'woocommerce_rest_invalid_line_item', __( 'Line item id must be an integer.', 'woocommerce' ), array( 'status' => 400 ) );
}
$line_item['line_item_id'] = (int) $line_item['line_item_id'];
}
if ( isset( $line_item['quantity'] ) ) {
if ( ! rest_is_integer( $line_item['quantity'] ) ) {
return new WP_Error( 'woocommerce_rest_invalid_quantity', __( 'Quantity must be a whole number.', 'woocommerce' ), array( 'status' => 400 ) );
}
$line_item['quantity'] = (int) $line_item['quantity'];
}
if ( isset( $line_item['refund_total'] ) ) {
if ( ! is_numeric( $line_item['refund_total'] ) ) {
return new WP_Error( 'woocommerce_rest_invalid_refund_total', __( 'refund_total must be a number.', 'woocommerce' ), array( 'status' => 400 ) );
}
$line_item['refund_total'] = (float) $line_item['refund_total'];
}
if ( isset( $line_item['refund_tax'] ) ) {
if ( ! is_array( $line_item['refund_tax'] ) ) {
return new WP_Error( 'woocommerce_rest_invalid_line_item', __( 'refund_tax must be an array of objects with id and refund_total.', 'woocommerce' ), array( 'status' => 400 ) );
}
foreach ( $line_item['refund_tax'] as $index => $tax ) {
if ( ! is_array( $tax ) || ! isset( $tax['id'], $tax['refund_total'] ) || ! rest_is_integer( $tax['id'] ) || ! is_numeric( $tax['refund_total'] ) ) {
return new WP_Error( 'woocommerce_rest_invalid_line_item', __( 'refund_tax entries must be objects with an integer id and a numeric refund_total.', 'woocommerce' ), array( 'status' => 400 ) );
}
$line_item['refund_tax'][ $index ] = array(
'id' => (int) $tax['id'],
'refund_total' => (float) $tax['refund_total'],
);
}
}
return $line_item;
}
/**
* Get the shared refund calculation engine.
*
* DataUtils is the calculation/validation engine shared with the wc/v4
* refunds endpoints (the V4 segment in its namespace is historical); using
* it here keeps wc/v3 and wc/v4 refund math identical.
*
* @return DataUtils
*/
private function get_data_utils(): DataUtils {
return wc_get_container()->get( DataUtils::class );
}
/**
* Prefix a shared-engine error code with `woocommerce_rest_`.
*
* DataUtils emits unprefixed codes (the wc/v4 convention). The wc/v3 surface
* uses `woocommerce_rest_*`, so errors crossing into a v3 response are
* renamed at this boundary. Codes that already carry the prefix pass through
* unchanged, and the message and data (including the HTTP status) are kept.
* An unprefixed engine error whose data carries no HTTP status is backfilled
* with 400, the same default the wc/v4 envelope applies, so it is not served
* as a 500. An already-prefixed code returns untouched above and so misses
* that backfill, which leaves no gap: every prefixed error reaching this
* endpoint is built by normalize_line_item() with an explicit status.
*
* @param WP_Error $error The error whose code should be prefixed.
*
* @return WP_Error
*/
private function prefix_error_code( WP_Error $error ): WP_Error {
$code = (string) $error->get_error_code();
if ( str_starts_with( $code, 'woocommerce_rest_' ) ) {
return $error;
}
// Every DataUtils error site attaches array data; the guard below is here
// so a non-array payload cannot turn the $data['status'] write into a
// fatal. Replacing such a payload rather than nesting it mirrors the wc/v4
// envelope, which likewise reads a status only out of array data and drops
// the rest, so both versions answer an identical error identically.
$data = $error->get_error_data();
if ( ! is_array( $data ) ) {
$data = array();
}
if ( ! isset( $data['status'] ) ) {
$data['status'] = 400;
}
return new WP_Error( 'woocommerce_rest_' . $code, $error->get_error_message(), $data );
}
/**
* Prepares one object for create or update operation.
*
* @since 3.0.0
* @param WP_REST_Request $request Request object.
* @param bool $creating If is creating a new object.
* @return WP_Error|WC_Data The prepared item, or WP_Error object on failure.
*/
protected function prepare_object_for_database( $request, $creating = false ) {
// The opt-in compute_totals mode routes through the shared wc/v4 refund
// calculation pipeline. It is a separate path so that requests without the
// flag behave exactly as before, including degenerate forms such as
// quantity-only line items producing a 0.00 refund. The schema declares
// compute_totals as boolean with a false default, so the REST layer has
// already sanitized the value by the time this runs.
if ( $creating && true === $request['compute_totals'] ) {
return $this->create_refund_with_computed_totals( $request );
}
RestApiParameterUtil::adjust_create_refund_request_parameters( $request );
$order = wc_get_order( (int) $request['order_id'] );
if ( ! $order ) {
return new WP_Error( 'woocommerce_rest_invalid_order_id', __( 'Invalid order ID.', 'woocommerce' ), 404 );
}
if ( 0 > $request['amount'] ) {
return new WP_Error( 'woocommerce_rest_invalid_order_refund', __( 'Refund amount must be greater than zero.', 'woocommerce' ), 400 );
}
// Create the refund.
$refund = wc_create_refund(
array(
'order_id' => $order->get_id(),
'amount' => $request['amount'],
'reason' => $request['reason'],
'line_items' => $request['line_items'],
'refund_payment' => $request['api_refund'],
'restock_items' => $request['api_restock'],
)
);
if ( is_wp_error( $refund ) ) {
return new WP_Error( 'woocommerce_rest_cannot_create_order_refund', $refund->get_error_message(), 500 );
}
if ( ! $refund ) {
return new WP_Error( 'woocommerce_rest_cannot_create_order_refund', __( 'Cannot create order refund, please try again.', 'woocommerce' ), 500 );
}
if ( ! empty( $request['meta_data'] ) ) {
MetaDataUtil::update( $request['meta_data'], $refund );
$refund->save_meta_data();
}
/**
* Filters an object before it is inserted via the REST API.
*
* The dynamic portion of the hook name, `$this->post_type`,
* refers to the object type slug.
*
* @param WC_Data $coupon Object object.
* @param WP_REST_Request $request Request object.
* @param bool $creating If is creating a new object.
*/
return apply_filters( "woocommerce_rest_pre_insert_{$this->post_type}_object", $refund, $request, $creating );
}
/**
* Create a refund with server-computed per-line totals (compute_totals mode).
*
* Mirrors the wc/v4 refund creation pipeline: line items may omit refund_total
* (computed from quantity at the order's stored unit price, tax-inclusive,
* clamped to the remaining refundable amount), input is validated against the
* order's refund history, and the refund amount is derived from the line items
* unless an explicit amount override is supplied. Validation follows the same
* rules as the wc/v4 creation endpoint; error codes are prefixed with
* `woocommerce_rest_` at this v3 boundary like the rest of the v3 surface.
*
* @param WP_REST_Request $request Request object.
* @return WP_Error|WC_Data The created refund, or WP_Error object on failure.
*
* @phpstan-param WP_REST_Request<array<string, mixed>> $request
*
* @since 11.1.0
*/
private function create_refund_with_computed_totals( $request ) {
$order = wc_get_order( (int) $request['order_id'] );
// wc_get_order can return a WC_Order_Refund for refund IDs — reject those
// here since refunds are not refundable themselves.
if ( ! $order instanceof WC_Order ) {
return new WP_Error( 'woocommerce_rest_invalid_order_id', __( 'Invalid order ID.', 'woocommerce' ), array( 'status' => 404 ) );
}
// Normalize each line to the engine's schema shape and validate value
// types here: the REST layer cannot, because the line_items schema
// property is readonly for backward compatibility, so its args are not
// registered.
$line_items = array();
foreach ( (array) ( $request['line_items'] ?? array() ) as $line_item ) {
if ( ! is_array( $line_item ) ) {
return new WP_Error( 'woocommerce_rest_invalid_line_item', __( 'Each line item must be an object.', 'woocommerce' ), array( 'status' => 400 ) );
}
$line_item = $this->normalize_line_item( $line_item );
if ( is_wp_error( $line_item ) ) {
return $line_item;
}
$line_items[] = $line_item;
}
// The shared engine runs the whole creation preparation: fill missing
// refund totals, validate against the order's refund history, convert to
// the internal wc_create_refund() format, resolve the amount, and apply
// the aggregate guards. Its WP_Errors carry their HTTP status in the
// error data and use unprefixed codes; they are prefixed here at the v3
// boundary like every other error the endpoint returns.
$prepared = $this->get_data_utils()->prepare_refund_creation_or_error(
$order,
$line_items,
$request->has_param( 'amount' ),
$request['amount'],
'wc-rest-refunds'
);
if ( is_wp_error( $prepared ) ) {
return $this->prefix_error_code( $prepared );
}
$line_item_data = $prepared['line_items'];
$refund_amount = $prepared['amount'];
// Mirror the resolved values back onto the request so the pre_insert filter
// below and any other downstream readers see the same internal-format
// line_items and amount the legacy path exposes after
// RestApiParameterUtil::adjust_create_refund_request_parameters().
$request->set_param( 'line_items', $line_item_data );
$request->set_param( 'amount', strval( $refund_amount ) );
$refund = wc_create_refund(
array(
'order_id' => $order->get_id(),
'amount' => $refund_amount,
'reason' => empty( $request['reason'] ) ? null : $request['reason'],
'line_items' => $line_item_data,
'refund_payment' => is_bool( $request['api_refund'] ) ? $request['api_refund'] : true,
'restock_items' => is_bool( $request['api_restock'] ) ? $request['api_restock'] : true,
)
);
// Same code and status as the legacy path above so a wc_create_refund
// failure looks identical to clients regardless of the compute_totals flag.
if ( is_wp_error( $refund ) ) {
return new WP_Error( 'woocommerce_rest_cannot_create_order_refund', $refund->get_error_message(), array( 'status' => 500 ) );
}
if ( ! $refund ) {
return new WP_Error( 'woocommerce_rest_cannot_create_order_refund', __( 'Cannot create order refund, please try again.', 'woocommerce' ), array( 'status' => 500 ) );
}
if ( ! empty( $request['meta_data'] ) ) {
MetaDataUtil::update( $request['meta_data'], $refund );
$refund->save_meta_data();
}
/**
* Filters an object before it is inserted via the REST API.
*
* The dynamic portion of the hook name, `$this->post_type`,
* refers to the object type slug.
*
* @param WC_Data $refund Object object.
* @param WP_REST_Request $request Request object.
* @param bool $creating If is creating a new object.
*
* @since 3.0.0
*/
return apply_filters( "woocommerce_rest_pre_insert_{$this->post_type}_object", $refund, $request, true );
}
/**
* Get formatted item data.
* Invokes parents and then adds the proper Cost of Goods Sold information.
*
* @param WC_Data $data_object WC_Data instance.
* @return array
* @since 9.9.0
*/
protected function get_formatted_item_data( $data_object ) {
$data = parent::get_formatted_item_data( $data_object );
if ( ! $this->cogs_is_enabled() ) {
return $data;
}
if ( $data_object instanceof WC_Abstract_Order && $data_object->has_cogs() ) {
$data['cost_of_goods_sold'] = array(
'value' => $data_object->get_cogs_total_value(),
);
foreach ( $data['line_items'] as $key => $line_item ) {
$cogs_value = $line_item['cogs_value'] ?? null;
if ( ! is_null( $cogs_value ) ) {
$data['line_items'][ $key ]['cost_of_goods_sold'] = array(
'value' => $cogs_value,
);
unset( $data['line_items'][ $key ]['cogs_value'] );
}
}
}
return $data;
}
/**
* Get the refund schema, conforming to JSON Schema.
*
* @return array
*/
public function get_item_schema() {
$schema = parent::get_item_schema();
$schema['properties']['line_items']['items']['properties']['refund_total'] = array(
'description' => __( 'Amount that will be refunded for this line item (excluding taxes).', 'woocommerce' ),
'type' => 'number',
'context' => array( 'edit' ),
'readonly' => true,
);
$schema['properties']['line_items']['items']['properties']['taxes']['items']['properties']['refund_total'] = array(
'description' => __( 'Amount that will be refunded for this tax.', 'woocommerce' ),
'type' => 'number',
'context' => array( 'edit' ),
'readonly' => true,
);
$schema['properties']['api_restock'] = array(
'description' => __( 'When true, refunded items are restocked.', 'woocommerce' ),
'type' => 'boolean',
'context' => array( 'edit' ),
'default' => true,
);
$schema['properties']['compute_totals'] = array(
'description' => __( 'When true, the server computes per-line refund amounts from quantities using the order\'s stored prices and taxes, validating the request against the order\'s refund history. Defaults to false, which preserves the pre-existing behavior of this endpoint.', 'woocommerce' ),
'type' => 'boolean',
'context' => array( 'edit' ),
'default' => false,
);
if ( $this->cogs_is_enabled() ) {
$schema = $this->add_cogs_related_schema( $schema );
}
return $schema;
}
/**
* Add the Cost of Goods Sold related fields to the schema.
*
* @param array $schema The original schema.
* @return array The updated schema.
*/
private function add_cogs_related_schema( array $schema ): array {
$schema['properties']['cost_of_goods_sold'] = array(
'description' => __( 'Cost of Goods Sold data.', 'woocommerce' ),
'type' => 'object',
'context' => array( 'view', 'edit' ),
'properties' => array(
'total_value' => array(
'description' => __( 'Total value of the Cost of Goods Sold for the refund.', 'woocommerce' ),
'type' => 'number',
'readonly' => true,
'context' => array( 'view', 'edit' ),
),
),
);
$schema['properties']['line_items']['items']['properties']['cost_of_goods_sold'] = array(
'description' => __( 'Cost of Goods Sold data. Only present for product refund line items.', 'woocommerce' ),
'type' => 'object',
'context' => array( 'view', 'edit' ),
'properties' => array(
'total_value' => array(
'description' => __( 'Value of the Cost of Goods Sold for the refund item.', 'woocommerce' ),
'type' => 'number',
'readonly' => true,
'context' => array( 'view', 'edit' ),
),
),
);
return $schema;
}
}
