Updating WooCommerce Order Status via the REST API

The direct solution

To update an existing WooCommerce order status programmatically, send a POST request to /wp-json/wc/v3/orders/{order_id} with a status field containing a valid WooCommerce core status. Common valid values include processing, completed, or cancelled. The request requires an API key with write permissions. If you omit the {order_id} from the URL and POST to the general orders endpoint, the API will create a new order instead of updating the existing one.

How status updates are processed

WooCommerce treats orders as a custom post type called shop_order. When the REST API receives a status update, it validates the provided status against a list of registered constants. Once validated, it updates the post status and associated post meta—which is custom metadata attached to the order record in the database used to store payment dates and transaction IDs.

This process triggers internal action hooks. Depending on your store configuration, these hooks may automatically trigger customer email notifications or adjust inventory levels.

Implementation example: PHP cURL

Run this script from a server capable of reaching your WordPress installation. Replace the placeholders with your actual store credentials and order details.

<?php
$consumerKey    = 'ck_your_consumer_key';
$consumerSecret = 'cs_your_consumer_secret';
$orderId        = 12345;
$newStatus      = 'completed';
$storeUrl       = 'https://example.com';

$url = rtrim($storeUrl, '/') . '/wp-json/wc/v3/orders/' . $orderId;

$data = [
    'status' => $newStatus,
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Basic ' . base64_encode($consumerKey . ':' . $consumerSecret),
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    echo 'Order updated successfully.';
} else {
    echo 'Request failed with HTTP ' . $httpCode . ': ' . $response;
}
?>

• Where to run: Execute this via a CLI environment or a background job. Running this directly in a browser is not recommended for production automation.
• Permissions: The API key must have Read/Write access. Read-only keys will return a 401 or 403 error.
• Expected checks: A successful request returns HTTP 200. An HTTP 400 indicates the status value is not recognized by the system.
• Risks: This operation changes state immediately. Because it triggers hooks, it may send automated emails to customers.

Practical limits and common mistakes

Unsupported status values

The API only accepts statuses defined in WooCommerce core or those registered by active plugins. If you attempt to use a custom status (e.g., shipped) that has not been registered via a plugin or theme, the API will return an HTTP 400 error.

Inventory synchronization

Changing a status to completed does not always decrement stock. If your store is configured to reduce stock only upon payment completion, a manual status change via the API may not trigger the inventory reduction unless the payment state is also updated.

Endpoint confusion

A common error is POSTing to /wp-json/wc/v3/orders. Without the specific ID in the URI, the API interprets the request as a command to create a new order, which can lead to duplicate records in your database.

Verifying the result

1. API Response: Confirm the HTTP response code is 200 and the returned JSON body shows the updated status value.
2. Admin Interface: Navigate to WooCommerce > Orders in the WordPress dashboard and verify the status badge for the specific order.
3. Database Check: For absolute verification, query the wp_posts table where post_type = 'shop_order' and ID = {order_id}. The post_status column should reflect the new value.

Rollback procedure

To reverse a status change, repeat the API request using the previous status value. Note that while the status will revert, side effects—such as emails already sent to the customer—cannot be undone. Inventory adjustments may require manual correction in the product stock management screen if the rollback does not trigger a corresponding stock increase.