快工助手跨境电商知识与商机助手
快工云仓服务介绍

v2.principal.get_principal_livestream_performance

Shopee 官方资料 · Shopee Open Platform 接口参考 · 适合开发者

stable本次发布有变化全部展示

来自 Shopee 官方资料快照 ·

打开官方原文 ↗
  1. 当前资料结构化阅读页
  2. 固定快照已留存，可追溯
  3. 官方原文可核对
查看技术与溯源信息
平台 / profile
Shopee / profile.shopee.api_reference
语言
en-US
发布版本
cn-20260909-2
标签
zhuge/sourceplatform/shopeeaudience/developercategory/api_doctopic/apitopic/developer

资料正文

§1 v2.principal.get_principal_livestream_performance

Queries livestream performance data for the specified principal within the selected time range. Supports request granularity by day, week, month, quarter, year, or customize, and returns both overall summary metrics and region-level detailed metrics.

#

§2 Overview

Overview

FieldValue
ModuleBrandPortal
API typePrincipal
HTTP methodPOST
Path/api/v2/principal/get_principal_livestream_performance
Production URLhttps://partner.shopeemobile.com/api/v2/principal/get_principal_livestream_performance
Sandbox URLhttps://partner.test-stable.shopeemobile.com/api/v2/principal/get_principal_livestream_performance
PermissionBrand Portal Service
#

§3 Request parameters

Request parameters

NameTypeRequiredSampleDescription
start_datestringYes2026-01-01Start date of the requested period in YYYY-MM-DD format. Limitations: - Must use the YYYY-MM-DD format.; - Must be a valid calendar date.; - Must not be later than end_date.; - Validation is based on the requested timezone.; - The earliest selectable date is calculated as: current day in timezone - 1 day - 2 years.; - The exact boundary rules depend on granularity: -- For customize, start_date must not be earlier than the earliest selectable date.; -- For day, start_date must equal end_date.; -- For week, start_date must be a Sunday.; -- For month, start_date must be the first day of the month.; -- For quarter, start_date must be the first day of the quarter.; -- For year, start_date must be the first day of the year.
end_datestringYes2026-01-31End date of the requested period in YYYY-MM-DD format. Limitations: - Must use the YYYY-MM-DD format. - Must be a valid calendar date. - Must not be earlier than start_date. - Validation is based on the requested timezone. - For customize, end_date must not be later than the day before the current day in the requested timezone. The inclusive date range from start_date to end_date must not exceed 366 days. - For day, end_date must equal start_date. - For week, end_date must be within the selected week range: from start_date (Sunday) to the end of that Sunday-to-Saturday week, or to the latest selectable day if the week extends beyond today. Formally: startDate ≤ endDate ≤ min(startDate + 6 days, today - 1 day). - For month, end_date must be within the selected month: from the 1st day of the month to the last calendar day of that month, or to the latest selectable day for the current month. Formally: startDate ≤ endDate ≤ min(month end, today - 1 day). - For quarter, end_date must be within the selected quarter: from the 1st day of the quarter to the last calendar day of that quarter, or to the latest selectable day for the current quarter. Formally: startDate ≤ endDate ≤ min(quarter end, today - 1 day). - For year, end_date must be within the selected year: from January 1st to December 31st of that year, or to the latest selectable day for the current year. Formally: startDate ≤ endDate ≤ min(Dec 31, today - 1 day).
timezonestringYesGMT+8Timezone used for date boundary calculation, selectable date validation, and timestamp conversion. Limitations: - Enum values: ["GMT+7", "GMT+8", "GMT-3"]; - The API internally normalizes the open API timezone value for livestream metric queries.; - All date validation rules are evaluated in the requested timezone.
granularitystringYesmonthAggregation granularity that determines the validation rules for the requested date range and the reporting period.; Limitations: - Supported values are customize, day, week, month, quarter, and year.; - customize is validated as a free date range and is internally queried with the affiliate-compatible livestream granularity.; - day represents a single calendar day.; - week requires a Sunday-based calendar week.; - month requires a calendar month range.; - quarter requires a calendar quarter range.; - year requires a calendar year range.; - Any other value is rejected as invalid_parameter.
region_listobject[]NoOptional list of principal regions to be queried.; Limitations: - When omitted or empty, the API queries all regions belonging to the specified principal_id except the aggregate regional bucket.; - Must contain at most 100 region objects.; - Every region must belong to the specified principal_id.; - Duplicate region values are merged for filtering purposes.; - Currency defaults to USD when omitted.; - When the same region appears multiple times, the first provided currency is used.
region_list.regionstringYesMYRegion code to be queried. Limitations: - Required for every region object in region_list.; - Must be a valid region code supported by the API.; - Must belong to the specified principal_id.
region_list.currencystringNoUSDCurrency used for amount-based metrics for the region. Limitations: - Optional for every region object in region_list.; - Supported values are LOCAL and USD.; - Invalid currency values are rejected as invalid_parameter.; - Defaults to USD when omitted.
#

§4 Response parameters

Response parameters

NameTypeRequiredSampleDescription
request_idstringad13785b-402c-4896-84df-6dc6c008f90dThe identifier for an API request, used for troubleshooting and log tracing.
errorstringIndicate error type if any error happened. Empty string if no error.
messagestringIndicate error details if any error happened. Empty string if no error.
responseobjectBusiness response payload. See Business Response Parameters below.
response.summaryobject[]Aggregated summary metrics for the requested date range, representing the overall livestream performance of the selected principal. Summary values are returned in USD when data exists.
response.summary.currencystringUSDCurrency code used for all amount-based metrics in the summary. Summary values are returned in USD.
response.summary.ordersint6424544Number of placed orders (paid and unpaid) during your Livestream, including cancelled orders.
response.summary.buyersint6420011Number of unique buyers who placed order from your Livestream.
response.summary.likesint64822271Total number of likes in your Livestream.
response.summary.commentsint64122356Total number of comments acquired during your Livestream.
response.summary.sales_grossfloat4939417.062404577Value of placed orders (paid and unpaid) during your Livestream, reflecting the sales amount received by sellers after deducting seller rebates. Note: This value includes sales from cancelled orders.
response.summary.units_soldint6425027Number of items sold from placed orders during your Livestream.
response.summary.total_viewsint646041612Total views from your Livestream.
response.summary.total_live_durationint648061951Total duration of your Livestream.
response.summary.unique_viewersint643850270Total unique viewers from your Livestream.
response.summary.atc_unitsint64220831Number of Add To Cart button clicks for all products in the orange bag during your Livestream.
response.summary.total_livestreamsint64472Total count of Livestream sessions in the selected period.
response.summary.average_live_durationfloat17080.40466101695Average duration of your Livestream.
response.summary.average_views_durationfloat47.91673441083353Average time viewers watch your Livestreams.
response.summary.new_followersint6430726Total followers gained from your Livestream.
response.summary.new_buyersint6419188Number of buyers who have not had placed orders (including paid and unpaid) via your Livestream in the past 365 days.
response.summary.existing_buyersint64823Number of buyers who have already had placed orders (including paid and unpaid) via your Livestream in the past 365 days.
response.summary.sales_netfloat3478017.9173450004Value of placed orders (paid and unpaid) during your Livestream, reflecting the sales amount received by sellers after deducting seller rebates. Note: This value excludes the refund amount for all non-cancelled and invalid items.
response.summary.conversion_ratefloat0.004062491930961472Livestream orders / Livestream views.
response.detailsobject[]List of region-level detail records that returns livestream performance metrics for each selected region within the requested date range.; Details are produced by aggregating shop-level livestream data into region-level results in the service layer.
response.details.regionstringMYRegion code of this detail item.
response.details.currencystringUSDCurrency code used for all amount-based metrics of this region item.
response.details.ordersint6423767Number of placed orders (paid and unpaid) during your Livestream, including cancelled orders.
response.details.buyersint6419345Number of unique buyers who placed order from your Livestream.
response.details.likesint64800789Total number of likes in your Livestream.
response.details.commentsint64119351Total number of comments acquired during your Livestream.
response.details.sales_grossfloat4747505.5402737735Value of placed orders (paid and unpaid) during your Livestream, reflecting the sales amount received by sellers after deducting seller rebates. Note: This value includes sales from cancelled orders.
response.details.units_soldint6424226Number of items sold from placed orders during your Livestream.
response.details.total_viewsint645702168Total views from your Livestream.
response.details.total_live_durationint646565127Total duration of your Livestream.
response.details.unique_viewersint643616306Total unique viewers from your Livestream.
response.details.atc_unitsint64214603Number of Add To Cart button clicks for all products in the orange bag during your Livestream.
response.details.total_livestreamsint64313Total count of Livestream sessions in the selected period.
response.details.average_live_durationfloat20974.846645367412Average duration of your Livestream.
response.details.average_views_durationfloat47.33443242911413Average time viewers watch your Livestreams.
response.details.new_followersint6430022Total followers gained from your Livestream.
response.details.new_buyersint6418535Number of buyers who have not had placed orders (including paid and unpaid) via your Livestream in the past 365 days.
response.details.existing_buyersint64810Number of buyers who have already had placed orders (including paid and unpaid) via your Livestream in the past 365 days.
response.details.sales_netfloat3332254.597736Value of placed orders (paid and unpaid) during your Livestream, reflecting the sales amount received by sellers after deducting seller rebates. Note: This value excludes the refund amount for all non-cancelled and invalid items.
response.details.conversion_ratefloat0.00416806379608598Livestream orders / Livestream views.
#

§5 Common parameters

Common parameters

NameTypeRequiredSampleDescription
partner_idint1Partner ID is assigned upon registration is successful. Required for all requests.
timestamptimestamp1610000000This is to indicate the timestamp of the request. Required for all requests. Expires in 5 minutes.
access_tokenstringc09222e3fc40ffb25fc947f738b1abf1The token for API access, using to identify your permission to the api. Valid for multiple use and expires in 4 hours.
principal_idint1Shopee's unique identifier for a principal.
signstringe318d3e932719916a9f9ebb57e2011961bd47abfa54a36e040d050d8931596e2Signature generated by(depends on different APIs) partner_id, api path, timestamp, access_token, principal_id and partner_key via HMAC-SHA256 hashing algorithm.
#

§6 Request samples

Request samples

#

§7 Payload

Payload

{
	"start_date": "2026-01-01",
	"end_date": "2026-01-31",
	"timezone": "GMT+8",
	"granularity": "month",
	"region_list": [
		{
			"region": "MY",
			"currency": "USD"
		},
                {
			"region": "SG",
			"currency": "USD"
		}
	]
}
#

§8 Java

Java

Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post("https://partner.shopeemobile.com/api/v2/principal/get_principal_livestream_performance?access_token=access_token&partner_id=partner_id&principal_id=principal_id&sign=sign&timestamp=timestamp")
.header("Content-Type","application/json")
.body("{
   \"end_date\": \"2026-01-31\",
   \"granularity\": \"month\",
   \"region_list\": [
      {
         \"currency\": \"USD\",
         \"region\": \"MY\"
      }
   ],
   \"start_date\": \"2026-01-01\",
   \"timezone\": \"GMT+8\"
}")
.asString();
#

§9 PHP

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://partner.shopeemobile.com/api/v2/principal/get_principal_livestream_performance?access_token=access_token&partner_id=partner_id&principal_id=principal_id&sign=sign&timestamp=timestamp',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => '{
    "end_date": "2026-01-31",
    "granularity": "month",
    "region_list": [
        {
            "currency": "USD",
            "region": "MY"
        }
    ],
    "start_date": "2026-01-01",
    "timezone": "GMT+8"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
#

§10 cURL

cURL

curl --location --request POST 'https://partner.shopeemobile.com/api/v2/principal/get_principal_livestream_performance?access_token=access_token&partner_id=partner_id&principal_id=principal_id&sign=sign&timestamp=timestamp' \
--header 'Content-Type: application/json' \
--data-raw '{
   "end_date": "2026-01-31",
   "granularity": "month",
   "region_list": [
      {
         "currency": "USD",
         "region": "MY"
      }
   ],
   "start_date": "2026-01-01",
   "timezone": "GMT+8"
}'
#

§11 Python

Python

import requests
import json

url = "https://partner.shopeemobile.com/api/v2/principal/get_principal_livestream_performance?access_token=access_token&partner_id=partner_id&principal_id=principal_id&sign=sign&timestamp=timestamp"

payload=json.dumps({
  "end_date": "2026-01-31",
  "granularity": "month",
  "region_list": [
    {
      "currency": "USD",
      "region": "MY"
    }
  ],
  "start_date": "2026-01-01",
  "timezone": "GMT+8"
})
headers = {
  'Content-Type': 'application/json'
}
response = requests.RPCRequest("POST",url,headers=headers, data=payload, allow_redirects=False)

print(response.text)
#

§12 Response sample

Response sample

#

§13 JSON

JSON

{
    "error": "",
    "message": "",
    "response": {
        "summary": [
            {
                "currency": "USD",
                "orders": 24544,
                "buyers": 20011,
                "likes": 822271,
                "comments": 122356,
                "sales_gross": 4939417.062404577,
                "units_sold": 25027,
                "total_views": 6041612,
                "total_live_duration": 8061951,
                "unique_viewers": 3850270,
                "atc_units": 220831,
                "total_livestreams": 472,
                "average_live_duration": 17080.40466101695,
                "average_views_duration": 47.91673441083353,
                "new_followers": 30726,
                "new_buyers": 19188,
                "existing_buyers": 823,
                "sales_net": 3478017.9173450004,
                "conversion_rate": 0.004062491930961472
            }
        ],
        "details": [
            {
                "region": "MY",
                "currency": "USD",
                "orders": 23767,
                "buyers": 19345,
                "likes": 800789,
                "comments": 119351,
                "sales_gross": 4747505.5402737735,
                "units_sold": 24226,
                "total_views": 5702168,
                "total_live_duration": 6565127,
                "unique_viewers": 3616306,
                "atc_units": 214603,
                "total_livestreams": 313,
                "average_live_duration": 20974.846645367412,
                "average_views_duration": 47.33443242911413,
                "new_followers": 30022,
                "new_buyers": 18535,
                "existing_buyers": 810,
                "sales_net": 3332254.597736,
                "conversion_rate": 0.00416806379608598
            },
            {
                "region": "SG",
                "currency": "LOCAL",
                "orders": 777,
                "buyers": 666,
                "likes": 21482,
                "comments": 3005,
                "sales_gross": 245043.32999999996,
                "units_sold": 801,
                "total_views": 339444,
                "total_live_duration": 1496824,
                "unique_viewers": 233964,
                "atc_units": 6228,
                "total_livestreams": 159,
                "average_live_duration": 9413.987421383648,
                "average_views_duration": 56.91718811441076,
                "new_followers": 704,
                "new_buyers": 653,
                "existing_buyers": 13,
                "sales_net": 186087.52,
                "conversion_rate": 0.0022890373669883692
            }
        ]
    },
    "request_id": "ad13785b-402c-4896-84df-6dc6c008f90d"
}
#

§14 Error example

Error example

#

§15 JSON

JSON

{
    "request_id": "a1bb6a69-b5b4-408a-9e9a-4b1c36229c95",
    "error": "error_param",
    "message": "for month granularity, start_date must be the first day of month.",
    "response": null
}
#

§16 Errors

Errors

ErrorDescriptionSolution
error_paramtimezone is required
error_paramgranularity is required
error_paramrequest body is invalid
error_paramcurrency is invalid
error_paramregion_list contains invalid region.
error_paramregion is required
error_paramend_date is not ready, please retry later
error_paramfor day granularity, start_date must equal end_date.
error_paramday range is outside the allowed selectable range.
error_paramfor week granularity, end_date must be within the selected week range
error_paramfor week granularity, start_date must be a Sunday.
error_paramweek start_date is earlier than the earliest allowed week.
error_paramstart_date cannot be later than end_date.
error_parammonth range is outside the allowed selectable range.
error_paramfor month granularity, start_date must be the first day of month.
error_paramfor month granularity, end_date must be within the selected month range.
error_paramfor quarter granularity, end_date must be within the selected quarter range.
error_paramyear range is outside the allowed selectable range.
error_paramfor quarter granularity, start_date must be the first day of quarter.
error_paramfor quarter granularity, end_date must be within the selected quarter range.
error_paramstart_date is earlier than the earliest allowed date
error_paramfor year granularity, end_date must be within the selected year range.
error_paramend_date must not be later than the latest selectable day.
error_permissionauth failed
error_paramstart_date is required
error_paramstart_date is required; start_date must use YYYY-MM-DD
error_paramend_date is required
error_paramend_date must use YYYY-MM-DD
#

§17 Common errors

Common errors

ErrorDescriptionSolution
error_authpartner_id is invalid
error_authThe App is deleted, and you'll be unable to make any API call.
error_authApp developer’s permissions for authorizations have been restricted. If you’re a seller, contact the developer for more information. If you’re the developer, refer to the Open Platform Console for details.
error_paramThere is no partner_id in query.
error_paramInvalid partner_id.
error_paramno timestamp
error_paramInvalid timestamp
error_paramThere is no sign in query.
error_signWrong sign.
invalid_partner_idInvalid partner_id, please have a check.
error_authNo permission to current api.
error_api_call_restrictedThe App permission for api call have been restricted. If you’re a seller, contact the developer for more information. If you’re the developer, refer to the Open Platform Console for details.
api_suspendedThe API is offline. Please call v2 API instead.
error_limitThe total API call number made by your APP has reached the daily API call limit, please try again after 00: 00 (UTC+08:00)
error_rate_limitToo many requests. You have reached the rate limit. Please try again later.
source_ip_undeclaredRequest Source IP ({ip}) is undeclared. Please declare all your IP addresses in the Shopee Open Platform Console > App list > IP Address Whitelist
error_paramPermission denied. This API is currently offline or the request path is incorrect.
error_paramPartner_id is invalid, should be an integer between 0 and 4294967295.
error_paramno timestamp.
error_paramTimestamp is invalid, should be an integer between 0 and 4294967295.
error_paramTimestamp is expired.
error_partner_key_expiredYour API partner key has expired, please reset the Live API Partner Key in Console to get a new valid partner key to call open api.
error_api_permissionThis app type has no permission to this API.
#

§18 Update log

Update log

DateChange
2026-07-09New API
#