WooCommerce API Orders

The WooCommerce Orders API allows you to create, retrieve, update, and delete orders in your WooCommerce store. This guide covers the essential operations and properties for managing orders effectively.

What can you do with Orders in the WooCommerce API?

The most common operations people perform on orders using the WooCommerce API.

Action	HTTP Method	Endpoint
Create an Order	`POST`	`/orders`
List All Orders	`GET`	`/orders`
Retrieve an Order	`GET`	`/orders/{orderId}`
Update an Order	`PUT`	`/orders/{orderId}`
Delete an Order	`DELETE`	`/orders/{orderId}`

Orders in WooCommerce represent the purchase transactions made by customers. They contain details about the products purchased, billing and shipping information, and payment details.

Orders are identified by a unique integer ID. This ID is used to perform operations such as retrieval, update, and deletion.

To create an order, you need to provide details such as customer information, line items, billing, and shipping details. Some fields like 'customer_id' can be optional if the order is for a guest.

Orders can be searched using various query parameters such as 'customer', 'status', 'product', and date filters like 'after' and 'before'. For example, to find orders created after a specific date, use the 'after' parameter with an ISO8601 date.

Properties of a Order

The properties section provides detailed information about the fields available in the Orders API. These properties are crucial for understanding the structure and data contained within an order. Show all properties Only show essential properties

Field Name	Type	Short Description
id	integer	Unique identifier for the resource.
number	string	Order number.
status	string	Order status. Options - pending, processing, on-hold, completed, cancelled, refunded, failed, trash and checkout-draft. Default is pending.
currency	string	Currency the order was created with, in ISO format.
date_created	datetime	The date the order was created, in the site's timezone.
total	string	Grand total.
customer_id	integer	User ID who owns the order. 0 for guests.
payment_method	string	Payment method ID.
line_items	array	Line items data.
billing	object	Billing address details.
parent_id	integer	Parent order ID.
order_key	string	Order key.
created_via	string	Shows where the order was created.
version	string	Version of WooCommerce which last updated the order.
date_created_gmt	datetime	The date the order was created, as GMT.
date_modified	datetime	The date the order was last modified, in the site's timezone.
date_modified_gmt	datetime	The date the order was last modified, as GMT.
discount_total	string	Total discount amount for the order.
discount_tax	string	Total discount tax amount for the order.
shipping_total	string	Total shipping amount for the order.
shipping_tax	string	Total shipping tax amount for the order.
cart_tax	string	Sum of line item taxes only.
total_tax	string	Sum of all taxes.
prices_include_tax	boolean	True the prices included tax during checkout.
customer_ip_address	string	Customer's IP address.
customer_user_agent	string	User agent of the customer.
customer_note	string	Note left by customer during checkout.
shipping	object	Shipping address details.
payment_method_title	string	Payment method title.
transaction_id	string	Unique transaction ID.
date_paid	datetime	The date the order was paid, in the site's timezone.
date_paid_gmt	datetime	The date the order was paid, as GMT.
date_completed	datetime	The date the order was completed, in the site's timezone.
date_completed_gmt	datetime	The date the order was completed, as GMT.
cart_hash	string	MD5 hash of cart items to ensure orders are not modified.
meta_data	array	Meta data properties.
tax_lines	array	Tax lines data.
shipping_lines	array	Shipping lines data.
fee_lines	array	Fee lines data.
coupon_lines	array	Fee lines data.
refunds	array	List of refunds.
set_paid	boolean	Define if the order is paid. It will set the status to processing and reduce stock items.

Show all properties

Filtering and Query Parameters

The Orders API supports a variety of filtering options to narrow down the results based on specific criteria.

Parameter	Type	Description	Example
`context`	string	Scope under which the request is made; determines fields present in response.	`context=view`
`page`	integer	Current page of the collection.	`page=2`
`per_page`	integer	Maximum number of items to be returned in result set.	`per_page=20`
`search`	string	Limit results to those matching a string.	`search=example`
`after`	string	Limit response to resources published after a given ISO8601 compliant date.	`after=2023-01-01T00:00:00`
`before`	string	Limit response to resources published before a given ISO8601 compliant date.	`before=2023-12-31T23:59:59`
`modified_after`	string	Limit response to resources modified after a given ISO8601 compliant date.	`modified_after=2023-01-01T00:00:00`
`modified_before`	string	Limit response to resources modified before a given ISO8601 compliant date.	`modified_before=2023-12-31T23:59:59`
`status`	array	Limit result set to orders assigned a specific status.	`status=completed`
`customer`	integer	Limit result set to orders assigned a specific customer.	`customer=123`
`product`	integer	Limit result set to orders assigned a specific product.	`product=456`

What to watch out for

When working with the Orders API, there are some common pitfalls and important considerations to keep in mind.

Immutable Fields

Certain fields such as id and order_key are immutable and cannot be changed once the order is created.

Date Handling

Ensure that date fields like date_created and date_modified are properly formatted in ISO8601 when making requests.

Payment Status

Setting set_paid to true will automatically change the order status to processing and reduce stock levels.

Frequently Asked Questions

Here are some frequently asked questions about the WooCommerce Orders API and how to effectively manage orders.

How do I find an order by customer ID in WooCommerce?

To find orders by customer ID, use the customer query parameter in the GET /orders endpoint. For example, GET /orders?customer=123 will return all orders associated with customer ID 123.

What happens when I update an order in WooCommerce?

When you update an order using the PUT /orders/{orderId} endpoint, ensure that you provide all necessary fields. Only the fields you include in the request will be updated. Fields not included will remain unchanged.

Can I delete an order that has been completed in WooCommerce?

Yes, you can delete any order using the DELETE /orders/{orderId} endpoint. Ensure that the force parameter is set to true, as orders do not support trashing.

How do I handle refunds for an order in WooCommerce?

Refunds are managed separately from the order itself. You can create a refund using the appropriate refund endpoint, which will adjust the order's financial totals accordingly.

Why is my order creation failing in WooCommerce?

Order creation can fail due to several reasons such as missing required fields, invalid data formats, or insufficient permissions. Check the response for specific error messages and ensure all mandatory fields are included.