WooCommerce API Reports

The WooCommerce Reports API allows you to retrieve detailed reports on sales and order totals. This guide covers how to access and use the Reports endpoints to gather insights into your store's performance.

What can you do with Reports in the WooCommerce API?

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

Action	HTTP Method	Endpoint
Retrieve Sales Report	`GET`	`/reports/sales`
Retrieve Order Totals Report	`GET`	`/reports/orders/totals`

Reports in WooCommerce provide valuable insights into sales and order totals, helping store owners track performance over various periods.

Reports are identified by the type of report (sales or order totals) and the period they cover.

Reports are generated automatically based on existing order and sales data. No manual creation is required.

You can filter sales reports by period, start date, and end date using query parameters such as period, date_min, and date_max.

Properties of a Report

The properties section highlights the most important fields available in the Reports API, helping developers understand the structure of report data. Show all properties Only show essential properties

Field Name	Type	Short Description
total_sales	string	Total sales amount for the report period.
net_sales	string	Net sales amount after discounts and refunds.
average_sales	string	Average sales amount per order.
total_orders	integer	Total number of orders in the report period.
total_items	integer	Total number of items sold.
total_tax	string	Total tax amount collected.
total_shipping	string	Total shipping fees collected.
total_refunds	number	Total amount refunded to customers.
total_discount	string	Total discount amount given.
total_customers	integer	Total number of unique customers.
totals_grouped_by	string	The criteria by which totals are grouped.
totals	object	Detailed breakdown of sales summary items.
sales	string	Sales amount for a specific item.
orders	integer	Number of orders for a specific item.
items	integer	Number of items sold for a specific item.
tax	string	Tax amount for a specific item.
shipping	string	Shipping fees for a specific item.
discount	string	Discount amount for a specific item.
customers	integer	Number of customers for a specific item.
slug	string	An alphanumeric identifier for the resource.
name	string	Orders status name.
total	integer	Amount of orders.

Show all properties

Filtering and Query Parameters

The Reports API supports filtering sales data by specific periods and date ranges.

Parameter	Type	Description	Example
`period`	string	Report period. Options include week, month, last_month, and year.	`period=month`
`date_min`	string	Return sales for a specific start date in YYYY-MM-DD format.	`date_min=2023-01-01`
`date_max`	string	Return sales for a specific end date in YYYY-MM-DD format.	`date_max=2023-01-31`

What to watch out for

When working with the WooCommerce Reports API, there are a few important considerations to keep in mind.

Date Format

Ensure that date_min and date_max are in the YYYY-MM-DD format to avoid errors.

Period Options

The period parameter only accepts specific values: week, month, last_month, and year.

Frequently Asked Questions

Here are some frequently asked questions about using the WooCommerce Reports API to access and analyze report data.

How do I find a report for a specific date range in WooCommerce Reports?

To find a report for a specific date range, use the date_min and date_max query parameters with the /reports/sales endpoint. Ensure the dates are in YYYY-MM-DD format.

What happens if I don't specify a period in the WooCommerce Reports API?

If you don't specify a period when querying the /reports/sales endpoint, the API defaults to today's date for the report.

Can I retrieve both sales and order totals in a single request in WooCommerce Reports?

No, sales and order totals are retrieved via separate endpoints: /reports/sales for sales and /reports/orders/totals for order totals.

How do I handle unauthorized errors when accessing WooCommerce Reports?

Ensure that your API credentials are correct and that you have the necessary permissions to access the reports. Unauthorized errors typically indicate an issue with authentication.

What are the limits for the period parameter in WooCommerce Reports?

The period parameter accepts week, month, last_month, and year as valid options. Any other value will result in a bad request error.