post https://{shopdomain}.myshoplaza.com/openapi/2024-07/data-analysis/spu
Requires
write_dataaccess scope.More access scope
The Data Analysis By SPU API provides merchants with detailed insights into sales data, enabling data-driven decision-making by analyzing products by SPU, SKU, or collections. This API allows for flexible querying of sales data within a specified time range and with advanced filtering options.
This API is especially useful for:
- Analyzing sales performance by SPU, SKU, or product collections.
- Generating customized reports for time-specific sales trends.
- Applying advanced filters for more targeted sales data analysis.
Request Parameters
Public Request Parameters
Body Parameters
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
type |
string |
Yes | Analysis mode - product: View sales performance aggregated by SPU (Standard Product Unit), providing insights at the product level.- variant: Analyze sales performance by SKU (Stock Keeping Unit), offering detailed insights at the variant level.
- collection: Generate album page reports for specific collections |
product |
begin_time |
int64 |
Yes | The starting timestamp (in seconds) for retrieving analysis data. Must be a valid Unix timestamp and less than. Typically set to the start of the day (00:00) in the relevant timezoneend_time. Logic |
1666512000 |
end_time |
int64 |
Yes | The ending timestamp (in seconds) for retrieving analysis data. Must be a valid Unix timestamp and greater tha. . Typically set to the start of the following day (00:00) in the relevant timezone. begin_time. |
1682323199 |
tz |
float |
Yes | Time zone adjustment for analysis, in hours. Notice: Values outside the range -12 to 14 might lead to unexpected results in time-based calculations. |
8 |
page |
int32 |
No | Page number for pagination. Defaults to 1. Value must be greater than 0. |
1 |
limit |
int32 |
No | Maximum number of records per page. Defaults to 50 and cannot exceed 500. | 50 |
sort_by |
string |
No | Sort by field is used for sorting the data,chosen from: created_at, first_published_at, published_at, product_op_updated_at, order_count, sales_count, sales_total, net_sales_total, discount, tax, views_count, add_to_cart_count, add_to_cart_rate, view_client_count, add_cart_client_count, add_to_cart_conversion_rate, transform_rate. |
created_at |
sort_direction |
string |
No | Sorting direction: asc (ascending) or desc (descending). |
desc |
collection_id |
string |
No | The Collection ID uniquely identifies a group of products within a collection. When the collection id is passed, it is filtered based on the collection ID. | e79e6138-ae9a-4046-8d6c-50883c20535e |
keyword |
string |
No | When the keyword is not empty, the product is filtered. Keywords will vaguely match these fields of the product: title, id, brief, sku, spu, tags, note. |
test |
search_model |
string |
No | The filtering mode can be base or advanced. The default value is base. If you select advanced, the filters filter takes effect. |
base |
filters |
json |
No | Conditions for advanced filtering mode. The data structure of the condition is: {"spu": {"operator": "in", "value": ["spu1"]}}. - spu: The field for which filtering conditions take effect is spu- operator: The conditional operation symbol for filtering. in is supported, indicating that the filtering field is in the specified list- value: Filter value list. |
{"spu": {"operator": "in", "value": ["spu1"]}} |
Sort Fields Explanation Table
| Field | Description |
|---|---|
created_at |
Sort by the product's creation date. Useful for tracking newly added products. |
first_published_at |
Sort by the product's first published date. Useful for identifying the earliest published products. |
published_at |
Sort by the most recent published date. Helps track recently updated or republished products. |
product_op_updated_at |
Sort by the update time of product variants. Useful for monitoring recently modified product details. |
published |
Sort by the current publication status, such as products available for sale or not. |
order_count |
Sort by the number of orders. Helps analyze top-selling products. |
sales_count |
Sort by the sales volume (units sold). Useful for evaluating product popularity. |
sales_total |
Sort by the total sales price. Helps analyze the contribution of each product to overall sales. |
net_sales_total |
Sort by net sales (excluding refunds, discounts, etc.). Reflects the real contribution of the product to sales. |
discount |
Sort by the discount amount. Useful for analyzing products with the largest discounts. |
tax |
Sort by sales tax amount. Useful for analyzing tax-related data. |
views_count |
Sort by the number of views in the online store. Helps evaluate product exposure. |
add_to_cart_count |
Sort by the number of times the product was added to the cart in the online store. Reflects purchase interest. |
views_rate |
Sort by the proportion of views in the online store. Useful for comparing relative product visibility. |
add_to_cart_rate |
Sort by the proportion of add-to-cart actions. Useful for comparing purchase intention rates. |
view_client_count |
Sort by the number of unique users who viewed the product. Useful for analyzing user reach. |
add_cart_client_count |
Sort by the number of unique users who added the product to their cart. Useful for assessing purchase intentions. |
add_to_cart_conversion_rate |
Sort by the add-to-cart rate. Reflects the effectiveness of converting views into cart actions. |
transform_rate |
Sort by the conversion rate from views to purchases. Useful for evaluating the effectiveness of the sales funnel. |
Response Explanation
Public Response Parameters
Success Response
| Field | Type | Description | Example |
|---|---|---|---|
code | string | The error code indicating the type of issue. | 200 |
message | string | A detailed message describing the error. | OK |
data | object | ||
data.product_id | string | Product ID | "e2da343c-182c-4908-b009-557cea226829" |
data.spu | string | Product spu | "123" |
data.title | string | Product title | "TEST" |
data.brief | string | Product subtitle | "" |
data.image | string | Product image | "free/5d4c48f9e65ffab9e73efbf1fd37a0f3.jpg" |
data.published | bool | Current published status | true |
data.collection | string | Collection | "x_2022-06-2709" |
data.created_at | string | Product created time | "2022-03-24 19:18:44" |
data.first_published_at | string | First published time | "2022-03-24 19:18:44" |
data.published_at | string | Last published time | "2022-03-24 19:18:44" |
data.product_op_updated_at | string | Product variant update time | "2023-08-21 15:43:34" |
data.utm_source | string | Utm source | "" |
data.utm_medium | string | Utm medium | "" |
data.utm_campaign | string | Utm campaign | "" |
data.utm_content | string | Utm content | "" |
data.utm_term | string | Utm term | "" |
data.order_count | string | Order count (string format) | "1" |
data.order_count_original | int | Order count | 1 |
data.sales_count | string | Sales count (string format) | "1" |
data.sales_count_original | float | Sales count | 1 |
data.sales_total | string | Total sales amount (string format) | "20.00" |
data.sales_total_original | float | Total sales amount | 20.0 |
data.net_sales_total | string | Net sales total (string format) | "19.00" |
data.net_sales_total_original | float | Net sales total | 19.0 |
data.discount | string | Discount rate (string format) | "19.00" |
data.discount_original | float | Discount rate | 19.0 |
data.tax | string | Sales tax (string format) | "0" |
data.tax_original | float | Sales tax | 0 |
data.views_count | string | Online product view count (string format) | "0" |
data.views_count_original | int | Online product view count | 0 |
data.add_to_cart_count | string | Online product add-to-cart count (string format) | "25" |
data.add_to_cart_count_original | int | Online product add-to-cart count | 25 |
data.views_rate | string | Online product view rate (string format) | "50.00%" |
data.views_rate_original | float | Online product view rate | 50 |
data.add_to_cart_rate | string | Online product add-to-cart rate (string format) | "25.00%" |
data.add_to_cart_rate_original | float | Online product add-to-cart rate | 25 |
data.view_client_count | string | Online product viewer count (string) | "1" |
data.view_client_count_original | float | Online product viewer count | 1 |
data.add_cart_client_count | string | Online product add-to-cart user count (string format) | "1" |
data.add_cart_client_count_original | float | Online product add-to-cart user count | 1 |
data.add_to_cart_conversion_rate | string | Online store add-to-cart conversion rate | "100.00%" |
data.add_to_cart_conversion_rate_original | float | Online store add-to-cart conversion rate | 100 |
data.transform_rate | string | Online store conversion rate (string format) | "100.00%" |
data.transform_rate_original | float | Online store conversion rate | 100 |
Error Response
Error responses in the API can be represented using two different fields: errors and error. Both fields provide details about issues encountered during request processing. Below is an explanation of the fields with their respective examples and descriptions.
| Field | Type | Description | Example |
|---|---|---|---|
code | string | The error code indicating the type of issue. | InvalidParameter |
message | string | A detailed message describing the error. | wrong cursor |
| Field | Type | Example | Description |
|---|---|---|---|
error | String | "store is not active" | Indicates an error encountered during the process |
Error Detail
| Status Code | Message | Possible Reason | Example Response |
|---|---|---|---|
| 400 | Bad Request | Invalid input format or request structure, such as missing required fields or exceeding limits. | Bad Request |
| Unauthorized | Missing or invalid authentication credentials. | Unauthorized |