---
title: "Top customers report"
method: GET
path: "/shop/reports/top-customers"
tags: ["Reports"]
---

# Top customers report

`GET /shop/reports/top-customers`

Returns the top 100 customers by net total across the filter range, sorted by net total
descending. The customer name returned is the one most frequently used on the orders
matched — the source-of-truth customer record lives in the [Customers API](/endpoints/Customers).

For large date ranges or background CSV delivery, queue an export with
[`/shop/reports/top-customers/queue`](/endpoints/Reports#queueTopCustomersExport).

## Query parameters

- `site_id` string, uuid
- `revenue_date_from` string, date
- `revenue_date_to` string, date
- `submitted_at_from` string, date
- `submitted_at_to` string, date

## Response `200`

The report was successfully generated.

- TopCustomersResponse
  - `data` TopCustomer[], required — The top 100 customers by net total within the filter range, sorted by net total descending.
    - `id` string, object-id, required — The customer's ID.
    - `full_name` string, required — The most common name the customer has used on their orders.
    - `num_orders` integer, required — The number of submitted or settled orders by this customer in the filter range.
    - `total_value_gross` integer, required — The sum of gross order totals for this customer, in minor units.
    - `average_value_gross` integer, required — The average gross order total for this customer, in minor units.
    - `total_value_net` integer, required — The sum of net order totals for this customer, in minor units.
    - `average_value_net` integer, required — The average net order total for this customer, in minor units.

## Other responses

- `400` — The request failed.

---

[API](https://skmtc.dev/try/apis/trybe-api.md) · [All operations](https://skmtc.dev/try/apis/trybe-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/try/trybe-api/revisions/f37f92702da5/schema)