Skip to main content
GET
List top products

Authorizations

Authorization
string
header
required

Send either an API token or an OAuth access token as Authorization: Bearer <token>. See the Authentication page for details.

Headers

Privy-Account-Id
string

Target a subaccount instead of the main connected account. Pass a subaccount id from get_account's subaccounts list. Only direct subaccounts of the connected account are reachable — omit this for the main account itself.

Query Parameters

metric
enum<string>
default:sales

Ranking metric. views availability depends on the store's platform and the requested window (see the operation description); sales works for any store that syncs orders to Privy.

Available options:
views,
sales
window_days
enum<integer>
default:30

Ranking window in days. 0 means all-time, which is supported for metric=views on BigCommerce stores only and is rejected for metric=sales.

Available options:
0,
30,
60,
90
page
integer
default:1

Page number (starts at 1).

Required range: x >= 1
per_page
integer
default:40

Number of results per page. Values outside 10–100 are clamped to the nearest bound.

Required range: 10 <= x <= 100

Response

The ranked product ids for the requested metric and window.

data
object[]
metric
enum<string>
Available options:
views,
sales
window_days
enum<integer>

The window this ranking covers. 0 means all-time.

Available options:
0,
30,
60,
90
refreshed_at
string<date-time> | null

When this ranking was last computed. null if it has never been computed. For the rolling windows the request enqueues the refresh that fills it. The all-time views ranking is computed only for BigCommerce stores that have configured a most-viewed dynamic product block, so null there means either the store's platform produces no all-time view counts or no such block exists yet.

note
string

Fixed caveat that entries are store product ids with live-resolved titles, and full details live at GET /v1/products/{id}.

pagination
object