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 | DescriptionExample | Example |
|---|---|---|---|
code |
string |
The error code indicating the type of issue. | 200 |
message |
string |
A detailed message describing the error. | OK |
data |
object |
||
data. |
string |
Product ID | "e2da343c-182c-4908-b009-557cea226829" |
data. |
string |
Product spu | "123" |
data. |
string |
Product title | "TEST" |
data. |
string |
Product subtitle | "" |
data. |
string |
Product image | "free/5d4c48f9e65ffab9e73efbf1fd37a0f3.jpg" |
data. |
bool |
Current published status | true |
data. |
string |
Collection | "x_2022-06-2709" |
data. |
string |
Product created time | "2022-03-24 19:18:44" |
data. |
string |
First published time | "2022-03-24 19:18:44" |
data. |
string |
Last published time | "2022-03-24 19:18:44" |
data. |
string |
Product variant update time | "2023-08-21 15:43:34" |
data. |
string |
Utm source | "" |
data. |
string |
Utm medium | "" |
data. |
string |
Utm campaign | "" |
data. |
string |
Utm content | "" |
data. |
string |
Utm term | "" |
data. |
string |
Order count (string format) | "1" |
data. |
int |
Order count | 1 |
data. |
string |
Sales count (string format) | "1" |
data. |
float |
Sales count | 1 |
data. |
string |
Total sales amount (string format) | "20.00" |
data. |
float |
Total sales amount | 20.0 |
data. |
string |
Net sales total (string format) | "19.00" |
data. |
float |
Net sales total | 19.0 |
data. |
string |
Discount rate (string format) | "19.00" |
data. |
float |
Discount rate | 19.0 |
data. |
string |
Sales tax (string format) | "0" |
data. |
float |
Sales tax | 0 |
data. |
string |
Online product view count (string format) | "0" |
data. |
int |
Online product view count | 0 |
data. |
string |
Online product add-to-cart count (string format) | "25" |
data. |
int |
Online product add-to-cart count | 25 |
data. |
string |
Online product view rate (string format) | "50.00%" |
data. |
float |
Online product view rate | 50 |
data. |
string |
Online product add-to-cart rate (string format) | "25.00%" |
data. |
float |
Online product add-to-cart rate | 25 |
data. |
string |
Online product viewer count (string) | "1" |
data. |
float |
Online product viewer count | 1 |
data. |
string |
Online product add-to-cart user count (string format) | "1" |
data. |
float |
Online product add-to-cart user count | 1 |
data. |
string |
Online store add-to-cart conversion rate | "100.00%" |
data. |
float |
Online store add-to-cart conversion rate | 100 |
data. |
string |
Online store conversion rate (string format) | "100.00%" |
data. |
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 |