Sales Report
Added in Thelia 3.4. The sales report shows what a period sold, by category, by product and by customer, compared with the previous period of the same length. Its figures add up to the revenue of the dashboard.
Open the report
In the back office, open Reports then Sales (/admin/reports/sales/category). The screen has three tabs:
| Tab | Address | Needs |
|---|---|---|
| By category | /admin/reports/sales/category | admin.order |
| By product | /admin/reports/sales/product | admin.order |
| By customer | /admin/reports/sales/customer | admin.customer |
A tab the administrator cannot read is not shown, and its address answers 403. An administrator who has admin.customer without admin.order finds the report in the Reports menu and lands on the customer tab. The export button needs admin.export.
The period is one of the presets of the dashboard (today, 7 days, 30 days by default, 90 days, this month, this year) or two free dates, up to three years apart and not after today. The previous period ends the day before the period starts and has as many days.
Orders counted
By default the report counts every order created in the period, whatever its status, as the dashboard revenue does.
A switch counts the paid orders only: those whose status is paid, processing or sent. A custom status counts when it is given one of these codes as its equivalent code. The screen says which orders it counts next to the switch, and the export button exports the same orders.
An administrator attached to some sale units sees the orders of those units only, on the screen and in the export.
By category
Each line is a category with its revenue including taxes, the revenue of the previous period, the change, the quantity sold, the number of orders and its share of the revenue. A category adds up its subcategories, which are folded under it.
- A product is counted in its default category only, so a product filed in several categories is not counted twice.
- The category is the one of the product today, not the one it had on the day of the sale.
- A deleted product, a product without a category, and the products of a category deleted since, are listed under Uncategorized. Their sales stay in the revenue.
- Service lines, such as a gift wrapping, are listed under Services.
- The components of a bundle are not counted as sold: the bundle is.
- The quantities keep their decimals for the goods sold by weight or volume: 0.4 kg sold reads 0.4.
- If the category tree holds a loop (a category whose parent is one of its own subcategories), each category of the loop counts a line once.
Under the tree, a table goes from the lines to the revenue: the total of the lines, minus the discounts, plus the shipping costs, gives the revenue of the dashboard for the same period. A discount larger than the goods of its order is counted up to the goods only.
By product
Every product sold in the period, best seller first, 25 per page, with its reference, the quantity, the revenue including taxes, the previous period, the change and the share of the revenue. The amounts are the lines of the orders, before discount and shipping costs. A deleted product keeps the title its order lines stored.
By customer
Every customer who ordered in the period, with the number of orders, the total including taxes, the average basket, the last order, the previous period and the change. The table is sorted on the total by default, and each column can be sorted. It shows 25 customers per page.
How the amounts are computed
Each order line is totalled with its taxes by the rounding rule of its order, as its invoice was. The amounts are added up as the orders store them, without converting their currency, as the dashboard does.
Three years of orders take a few seconds to add up. The screen keeps its figures fifteen minutes and says when they were computed, with a link to compute them again. The figures are computed again as soon as an order is placed, updated or deleted. A change that is not an order, such as a product moved to another category, shows once the figures are computed again or have expired.
Export
The export button writes the tab on screen as CSV, over the exact days and the orders on screen. The same exports are in the Reports category of the export screen, and can be sent by e-mail as scheduled reports:
| Export | Paid orders only | One line per | Ends with |
|---|---|---|---|
thelia.export.sales_by_category | thelia.export.sales_by_category_paid | Category, with its path ("Parent > Child") | The discounts, the shipping costs and the total |
thelia.export.sales_by_product | thelia.export.sales_by_product_paid | Product sold, best seller first | |
thelia.export.sales_by_customer | thelia.export.sales_by_customer_paid | Customer who ordered, biggest total first |
The first three count every order created in the period, the _paid ones the paid orders only. Each line gives the previous period, the change in percent and, for categories and products, the share of the revenue. What a customer or an administrator typed is written as text, so that a spreadsheet does not run it as a formula.
Without a start date, an export runs from the first order of the shop; without an end date, up to today. A period without any sale has no data, and the export reports that no data was found. Sent by e-mail, the report opens on the revenue, its change and the top category, product or customer of the period.
From the command line:
php Thelia export thelia.export.sales_by_category thelia.csv --start=2026-01-01 --end=2026-01-31 --locale=en_US
An export run by an administrator attached to some sale units covers those units only. An export run from the command line, or sent as a scheduled report, covers the whole shop.
For developers
Thelia\Domain\Report\Sales\SalesReportCalculator is the one computation the screen and the exports read. It takes a SalesReportCriteria (start, end, StatusScope::All by default or StatusScope::Paid, and the allowed sale unit ids, null for all):
| Method | Returns |
|---|---|
byCategory($criteria, $locale) | A list of CategorySalesRow, a parent before its children |
byProduct($criteria, $locale, $page, $perPage) | A SalesPage of ProductSalesRow |
byCustomer($criteria, $sort, $descending, $page, $perPage) | A SalesPage of CustomerSalesRow, sorted on a CustomerSort |
reconciliation($criteria) | A SalesReconciliation: total of the lines, discounts, shipping costs, revenue and number of orders |
SalesReportCriteria::previous() gives the previous period. The SQL of an order line total, of an order total and of a unit price, with their rounding rules, is in Thelia\Domain\Order\Sql\OrderAmountSql: a statement built on it binds the order ids the rules turn on with OrderAmountSql::bindRoundingPivots($statement, $sql).
An export restricted to the sale units of the administrator who runs it implements Thelia\Domain\DataTransfer\Export\SaleUnitScopedExportInterface. ExportHandler::export() hands it the allowed sale unit ids: null restricts nothing, and an empty list reaches no order.
Limits
- The category is the one of the product today.
- Amounts in several currencies are added up without conversion.
order.created_athas no index. On 30,000 orders over three years, the first computation of a tab takes a few seconds, then the figures are kept fifteen minutes.