**Version: 202601**

# Get data analysis by SPU

**POST** `/openapi/2026-01/data-analysis/spu`

Provides merchants with detailed insights into sales data, enabling data-driven decision-making by analyzing products by SPU.

## Request

**application/json**

**Body | Example**

**Body (required)**

- `type` string (required)

  Type of resource to analyze. Supported values: `product`, `variant`, `collection`
- `begin_time` string (required)

  Start time for retrieving analysis data: a Unix timestamp in seconds, passed as a string (e.g. "1748736000"). Must be less than end\_time; typically the start of the day (00:00) in the relevant timezone
- `end_time` string (required)

  End time for retrieving analysis data: a Unix timestamp in seconds, passed as a string (e.g. "1781481600"). Must be greater than begin\_time; typically the start of the following day (00:00) in the relevant timezone
- `cursor` string

  Cursor for pagination
- `page_size` int32

  Page size

  **Default value:** `10`
- `page` int32

  Page number (1-based). Mutually exclusive with cursor
- `time_zone` int32

  Notice: Values outside the range -12 to 14 might lead to unexpected results in time-based calculations. Time zone offset (in hours) used for analysis. Recommended range: -12 to 14
- `sort_by` string

  Field to sort by. Supported values:

  *   `created_at`: Product creation time
  *   `first_published_at`: First publish time
  *   `published_at`: Latest publish time
  *   `product_op_updated_at`: Last product operation update time
  *   `order_count`: Number of orders
  *   `sales_count`: Number of items sold
  *   `sales_total`: Total sales amount
  *   `net_sales_total`: Net sales amount
  *   `discount`: Discount amount
  *   `tax`: Tax amount
  *   `views_count`: Page view count
  *   `add_to_cart_count`: Add-to-cart count
  *   `add_to_cart_rate`: Add-to-cart rate
  *   `view_client_count`: Unique viewer count
  *   `add_cart_client_count`: Unique add-to-cart user count
  *   `add_to_cart_conversion_rate`: Add-to-cart conversion rate
  *   `transform_rate`: Overall conversion rate
- `sort_direction` string

  Sorting direction: asc (ascending) or desc (descending)
- `collection_id` string

  Filter by collection ID. When the collection ID is passed, results are filtered by that collection
- `keyword` string

  When the keyword is not empty, products are filtered. Keywords will fuzzy match these product fields: title, ID, brief, SKU, SPU, tags, note
- `search_model` string

  Filtering mode: base (default) or advanced. When set to advanced, the `filter` field takes effect
- `filter` string

  Advanced filter conditions as a JSON string. Only takes effect when `search_model` is "advanced".

  Structure: a flat JSON object that maps each filter key to a leaf `{"operator": "...", "value": ...}`; multiple keys are combined with AND (this endpoint does not support OR groups).

  The `value` type to send depends on the operator (operators are case-insensitive):

  *   `in` / `not in` -> value is an ARRAY of strings, e.g. `["SPU001", "SPU002"]`
  *   `like` / `not like` -> value is a STRING, e.g. `"shirt"`
  *   `=` `>` `>=` `<` `<=` -> value is a SCALAR (string or number), e.g. `10`

  Key -> expected value:

  *   list keys `spu` `sku` `product_id` `title` `tag_list` -> array
  *   range keys `price_min`/`price_max`, `cost_price_min`/`cost_price_max`, `compare_at_price_min`/`compare_at_price_max`, `created_at_min`/`created_at_max`, `updated_at_min`/`updated_at_max` -> scalar
  *   boolean keys `published` `sub_category` -> `"true"` / `"false"`
  *   other keys `collection_id` `keyword` `vendor` `category` `product_note` `sales_platform` -> string

  Unknown keys are silently ignored (the request still returns 200), so a filter "not taking effect" usually means a mistyped key.

  e.g. `{"spu": {"operator": "in", "value": ["SPU001", "SPU002"]}}`
- `with_impression` boolean

  Whether to include impression data in the response
- `filter_crawler_type` string

  Crawler-filtering policy that controls whether bot/crawler traffic is excluded from the statistics. Values:

  *   `no_filter_crawler`: do not filter; count all traffic (default)
  *   `official_crawler`: exclude known crawlers/bots
- `sub_type` string

  Grouping granularity, only effective when `type` is "collection". Values:

  *   `collection` (default): group by collection; `product_id` is empty
  *   `collection_product`: group by collection x product
  *   `product`: group by product

```json
{
  "type": "string",
  "begin_time": "string",
  "end_time": "string",
  "cursor": "string",
  "page_size": 10,
  "page": 0,
  "time_zone": 0,
  "sort_by": "string",
  "sort_direction": "string",
  "collection_id": "string",
  "keyword": "string",
  "search_model": "string",
  "filter": "string",
  "with_impression": true,
  "filter_crawler_type": "string",
  "sub_type": "string"
}
```

## Responses

**200**

OK

**application/json**

**Schema | Example**

**Schema**

- `code` string

  error code
- `message` string

  error message
- `data` object

  - `data` object[]

    Data list

    *   Array \[

    - `utm_source` string

      UTM source
    - `utm_medium` string

      UTM medium
    - `utm_campaign` string

      UTM campaign
    - `utm_term` string

      UTM term
    - `utm_content` string

      UTM content
    - `image` string

      Image
    - `title` string

      Title
    - `order_count_original` int32

      Original order count
    - `sales_count_original` int32

      Original sales count
    - `sales_total_original` float

      Original total sales amount
    - `net_sales_total_original` float

      Original net sales total
    - `discount_original` float

      Original discount amount
    - `tax_original` float

      Original tax amount
    - `views_count_original` int32

      Original views count
    - `add_to_cart_count_original` int32

      Original add-to-cart count
    - `views_rate_original` float

      Original views rate
    - `add_to_cart_rate_original` float

      Original add-to-cart rate
    - `view_client_count_original` int32

      Original view client count
    - `add_cart_client_count_original` int32

      Original add-to-cart client count
    - `add_to_cart_conversion_rate_original` float

      Original add-to-cart conversion rate
    - `transform_rate_original` float

      Original transform rate
    - `product_id` string

      Product ID
    - `brief` string

      Brief description
    - `spu` string

      SPU (Standard Product Unit)
    - `collection` string

      Collection
    - `created_at` string

      Creation time, in ISO-8601 format
    - `first_published_at` string

      First publish time, in ISO-8601 format
    - `published_at` string

      Publish time, in ISO-8601 format
    - `product_op_updated_at` string

      Product last operation update time, in ISO-8601 format
    - `published` boolean

      Whether the product is published
    - `duty_total_original` int32

      Original duty total
    - `order_count` string

      Number of orders
    - `sales_count` string

      Sales count
    - `sales_total` string

      Total sales amount
    - `net_sales_total` string

      Net sales total
    - `discount` string

      Discount amount
    - `tax` string

      Tax
    - `views_count` string

      Views count
    - `add_to_cart_count` string

      Add-to-cart count
    - `views_rate` string

      Views rate
    - `add_to_cart_rate` string

      Add-to-cart rate
    - `view_client_count` string

      View client count
    - `add_cart_client_count` string

      Add-to-cart client count
    - `add_to_cart_conversion_rate` string

      Add-to-cart to order conversion rate
    - `transform_rate` string

      Transform rate
    - `duty_total` string

      Total duty cost
    - `seo_url` string

      SEO-friendly URL
    - `impression` string

      Impression count
    - `collection_id` string

      Collection ID
    - `collection_title` string

      Collection title
    - `impression_original` int64

      Impression count, numeric value
    *   \]
  - `count` int32

    Total number of matching records
  - `cursor` string

    Cursor for pagination
  - `has_more` boolean

    Whether there are more records

```json
{
  "code": "string",
  "message": "string",
  "data": {
    "data": [
      {
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "utm_term": "string",
        "utm_content": "string",
        "image": "string",
        "title": "string",
        "order_count_original": 0,
        "sales_count_original": 0,
        "sales_total_original": 0,
        "net_sales_total_original": 0,
        "discount_original": 0,
        "tax_original": 0,
        "views_count_original": 0,
        "add_to_cart_count_original": 0,
        "views_rate_original": 0,
        "add_to_cart_rate_original": 0,
        "view_client_count_original": 0,
        "add_cart_client_count_original": 0,
        "add_to_cart_conversion_rate_original": 0,
        "transform_rate_original": 0,
        "product_id": "string",
        "brief": "string",
        "spu": "string",
        "collection": "string",
        "created_at": "string",
        "first_published_at": "string",
        "published_at": "string",
        "product_op_updated_at": "string",
        "published": true,
        "duty_total_original": 0,
        "order_count": "string",
        "sales_count": "string",
        "sales_total": "string",
        "net_sales_total": "string",
        "discount": "string",
        "tax": "string",
        "views_count": "string",
        "add_to_cart_count": "string",
        "views_rate": "string",
        "add_to_cart_rate": "string",
        "view_client_count": "string",
        "add_cart_client_count": "string",
        "add_to_cart_conversion_rate": "string",
        "transform_rate": "string",
        "duty_total": "string",
        "seo_url": "string",
        "impression": "string",
        "collection_id": "string",
        "collection_title": "string",
        "impression_original": 0
      }
    ],
    "count": 0,
    "cursor": "string",
    "has_more": true
  }
}
```