Metrics
TikTok Shop metrics via API
Your customer connects their TikTok Shop account and your product queries 34 metrics through the same endpoint as every other platform. Each metric has an id (reference_key) that goes in the request.
POST /api/metrics/get-data
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
{
"customer_integration": "<connection uuid>",
"start": "2026-10-01",
"end": "2026-10-31",
"comparison_start": "2026-09-01",
"comparison_end": "2026-09-30",
"metrics": [
{
"id": "m1",
"reference_key": "tiktok_shop:orders",
"component": "number_v1",
"metrics": [
"orders"
]
}
]
}More TikTok Shop request examples
The same endpoint for every kind of metric. The metrics and dimensions of each item come from the platform catalog (GET /api/metrics/{integration_slug}).
Chart
Orders over time
Orders placed on each day of the analyzed period.
POST /api/metrics/get-data
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
{
"customer_integration": "<connection uuid>",
"start": "2026-10-01",
"end": "2026-10-31",
"metrics": [
{
"id": "m1",
"reference_key": "tiktok_shop:orders_over_time",
"component": "chart_v1",
"metrics": [
"orders"
],
"dimensions": [
"date"
]
}
]
}Table
Sales summary
Sales of the orders placed on each day of the analyzed period, net of the refunds concluded on that day.
POST /api/metrics/get-data
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
{
"customer_integration": "<connection uuid>",
"start": "2026-10-01",
"end": "2026-10-31",
"metrics": [
{
"id": "m1",
"reference_key": "tiktok_shop:sales_summary",
"component": "datatable_v1",
"metrics": [
"orders",
"items_sold",
"gross_sales",
"seller_discount",
"platform_discount",
"net_sales",
"shipping",
"taxes",
"total_sales"
],
"dimensions": [
"date"
]
}
]
}Number
Delivered orders
Orders placed in the analyzed period that were delivered to the customer or completed.
POST /api/metrics/get-data
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
{
"customer_integration": "<connection uuid>",
"start": "2026-10-01",
"end": "2026-10-31",
"metrics": [
{
"id": "m1",
"reference_key": "tiktok_shop:delivered_orders",
"component": "number_v1",
"metrics": [
"delivered_orders"
]
}
]
}Numbers
22 metrics
Orders
Number of orders placed in the analyzed period, excluding unpaid orders, canceled orders and sample orders sent to creators.
tiktok_shop:ordersDelivered orders
Orders placed in the analyzed period that were delivered to the customer or completed.
tiktok_shop:delivered_ordersCanceled orders
Orders whose cancellation was concluded in the analyzed period, regardless of when they were placed.
tiktok_shop:cancelled_ordersItems sold
Units sold in the orders placed in the analyzed period.
tiktok_shop:items_soldCustomers
Number of distinct customers who placed orders in the analyzed period.
tiktok_shop:customersGross sales
Product prices before discounts in the orders placed in the analyzed period.
tiktok_shop:gross_salesSeller discount
Discounts funded by the shop in the orders placed in the analyzed period.
tiktok_shop:seller_discountPlatform discount
Discounts funded by TikTok Shop in the orders placed in the analyzed period. They are paid by the platform, so they are not deducted from the shop's sales.
tiktok_shop:platform_discountNet sales
Gross sales minus the discounts funded by the shop and the refunds concluded in the analyzed period.
tiktok_shop:net_salesShipping
Shipping fees paid by customers in the orders placed in the analyzed period.
tiktok_shop:shippingTaxes
Taxes charged in the orders placed in the analyzed period.
tiktok_shop:taxesTotal sales
Net sales plus the shipping and taxes charged in the orders placed in the analyzed period. Canceled orders never enter the sales, so cancellations are not deducted.
tiktok_shop:total_salesAverage order value
Product value of the orders placed in the analyzed period, before discounts and refunds, divided by the number of orders.
tiktok_shop:average_order_valueItems per order
Items sold divided by the number of orders placed in the analyzed period.
tiktok_shop:items_per_orderCancellations value
Amount refunded to customers by the cancellations concluded in the analyzed period.
tiktok_shop:cancelled_amountRefunds
Return and refund requests concluded with a refund in the analyzed period, regardless of when the order was placed.
tiktok_shop:refundsRefunded items
Units refunded by the returns concluded in the analyzed period.
tiktok_shop:refunded_itemsRefunds value
Amount refunded to customers by the returns concluded in the analyzed period.
tiktok_shop:refunded_amountCancellation rate
Orders whose cancellation was concluded in the analyzed period divided by the orders placed in it.
tiktok_shop:cancellation_rateRefund rate
Returns concluded with a refund in the analyzed period divided by the orders placed in it.
tiktok_shop:refund_rateAverage shipping
Shipping fees paid by customers divided by the number of orders placed in the analyzed period.
tiktok_shop:average_shippingAverage discount
Discounts funded by the shop divided by the number of orders placed in the analyzed period.
tiktok_shop:average_discount
Charts
5 metrics
Orders over time
Orders placed on each day of the analyzed period.
tiktok_shop:orders_over_timeSales over time
Total sales of the orders placed on each day of the analyzed period.
tiktok_shop:sales_over_timeOrders by status
Distribution of the orders placed in the analyzed period by their current status, including unpaid and canceled orders.
tiktok_shop:orders_by_statusCancellations by initiator
Distribution of the cancellations concluded in the analyzed period by who requested them: the customer, the shop, TikTok Shop operators or the system.
tiktok_shop:cancellations_by_initiatorReturns by type
Distribution of the returns concluded in the analyzed period by the solution given: refund only, return and refund, replacement or exchange.
tiktok_shop:returns_by_type
Tables
7 metrics
Sales summary
Sales of the orders placed on each day of the analyzed period, net of the refunds concluded on that day.
tiktok_shop:sales_summaryCancellations and refunds by day
Cancellations and refunds concluded on each day of the analyzed period.
tiktok_shop:cancellations_and_refunds_by_daySales by payment method
Orders placed in the analyzed period grouped by the payment method chosen by the customer.
tiktok_shop:sales_by_payment_methodBest selling products
Products sold in the analyzed period; net sales deduct the refunds of those items concluded in the period. Status, variations and stock reflect the catalog at the time of the report, not the period.
tiktok_shop:best_selling_productsSales by variant
Product variants sold in the analyzed period; net sales deduct the refunds of those items concluded in the period. Price and stock reflect the catalog at the time of the report, not the period.
tiktok_shop:sales_by_variantCancellations by reason
Cancellations concluded in the analyzed period grouped by the reason given.
tiktok_shop:cancellations_by_reasonReturns by reason
Returns concluded in the analyzed period grouped by the reason given by the customer.
tiktok_shop:returns_by_reason
See Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.
