Top products

Applies to: API integrators with third-party API access.

Use Content-Type: application/json and optionally X-Locale: en. The third-api-token header is required. See common headers and error handling.

Brief Description

• Paginated list of best-selling products within a specified time range, ordered by sales volume (descending), then product name (ascending).
• Without pagination parameters, defaults to page 1 with size 10 (same result set size as the previous Top-10 behavior).
• Data scope follows the user identity and selected groupId in the token (visible device set).
• Optional filters: deviceCode, goodsId, sku.

Request URL

• https://{GATEWAY_HOST}/third-center-web/openapi/v1/phamboxDashboard/topBestSellers?current=1&size=10

Request Method

• POST

Request Headers

Header	Required	Description
Content-Type	Yes	application/json
third-api-token	Yes	OpenAPI access token
X-Locale	No	Recommended: en

Parameters

Send a JSON object as the request body. When using only defaults, send {}; optional fields do not make the body optional.

URL Query:

Parameter Name	Required	Type	Description
current	No	int	Current page number; default 1
size	No	int	Page size; default 10

Request Body:

Parameter Name	Required	Type	Description
startTimestamp	No	long	Statistics start time (millisecond timestamp). Default: first day of the current month at 00:00:00 in the statistics service's effective timezone. Supply explicit bounds; see time handling
endTimestamp	No	long	Statistics end time (millisecond timestamp). Default: current time
deviceCode	No	string	Device code. When omitted, query across all visible devices; when provided, query only that device (must be within the caller's visible scope)
goodsId	No	string	Product ID; exact match
sku	No	string	SKU; exact match

Response Example

{
  "code": 200,
  "msg": "success",
  "enMsg": null,
  "data": {
    "total": 35,
    "current": 1,
    "size": 10,
    "records": [
      {
        "goodsId": "goods-001",
        "productName": "Vitamin C 500mg",
        "sku": "SKU-EXAMPLE-001",
        "price": 10.99,
        "units": 512
      },
      {
        "goodsId": "goods-002",
        "productName": "Pain Relief",
        "sku": "SKU-EXAMPLE-002",
        "price": 8.49,
        "units": 389
      }
    ]
  }
}

Response Parameter Description

Response data: A pagination object on success. No matches return total: 0 and records: [], not a raw array.

Errors: data may be null, a string or an array of messages. Check the HTTP status and code before reading success data. See error handling.

Response data:

Parameter Name	Type	Description
total	long	Total number of matching sold products
current	long	Current page number
size	long	Page size
records	array	Page data list
records[].goodsId	string	Product ID
records[].productName	string	Product name
records[].sku	string / null	SKU; may be null when product metadata is unavailable
records[].price	double	Default / retail price (USD, major currency unit)
records[].units	long	Sales volume

Remarks

• Sort order: units descending, then productName ascending.
• Only products with sales in the time range are returned (not the full catalog).
• When both goodsId and sku are provided, they must resolve to the same product; otherwise an empty page is returned.
• If sku cannot be resolved to a product, an empty page is returned (total=0, records=[]).
• Empty visible device scope, or no matching sales, returns an empty page.
• If deviceCode is outside the caller's visible scope, the request fails with a business permission error.
• Breaking change vs previous Top-10 API: data is now a pagination object (total / current / size / records) instead of a raw array. Read items from data.records.