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"
      ]
    }
  ]
}
Example: "Orders" in October, compared to September.

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:orders
  • Delivered orders

    Orders placed in the analyzed period that were delivered to the customer or completed.

    tiktok_shop:delivered_orders
  • Canceled orders

    Orders whose cancellation was concluded in the analyzed period, regardless of when they were placed.

    tiktok_shop:cancelled_orders
  • Items sold

    Units sold in the orders placed in the analyzed period.

    tiktok_shop:items_sold
  • Customers

    Number of distinct customers who placed orders in the analyzed period.

    tiktok_shop:customers
  • Gross sales

    Product prices before discounts in the orders placed in the analyzed period.

    tiktok_shop:gross_sales
  • Seller discount

    Discounts funded by the shop in the orders placed in the analyzed period.

    tiktok_shop:seller_discount
  • Platform 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_discount
  • Net sales

    Gross sales minus the discounts funded by the shop and the refunds concluded in the analyzed period.

    tiktok_shop:net_sales
  • Shipping

    Shipping fees paid by customers in the orders placed in the analyzed period.

    tiktok_shop:shipping
  • Taxes

    Taxes charged in the orders placed in the analyzed period.

    tiktok_shop:taxes
  • Total 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_sales
  • Average 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_value
  • Items per order

    Items sold divided by the number of orders placed in the analyzed period.

    tiktok_shop:items_per_order
  • Cancellations value

    Amount refunded to customers by the cancellations concluded in the analyzed period.

    tiktok_shop:cancelled_amount
  • Refunds

    Return and refund requests concluded with a refund in the analyzed period, regardless of when the order was placed.

    tiktok_shop:refunds
  • Refunded items

    Units refunded by the returns concluded in the analyzed period.

    tiktok_shop:refunded_items
  • Refunds value

    Amount refunded to customers by the returns concluded in the analyzed period.

    tiktok_shop:refunded_amount
  • Cancellation rate

    Orders whose cancellation was concluded in the analyzed period divided by the orders placed in it.

    tiktok_shop:cancellation_rate
  • Refund rate

    Returns concluded with a refund in the analyzed period divided by the orders placed in it.

    tiktok_shop:refund_rate
  • Average shipping

    Shipping fees paid by customers divided by the number of orders placed in the analyzed period.

    tiktok_shop:average_shipping
  • Average 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_time
  • Sales over time

    Total sales of the orders placed on each day of the analyzed period.

    tiktok_shop:sales_over_time
  • Orders by status

    Distribution of the orders placed in the analyzed period by their current status, including unpaid and canceled orders.

    tiktok_shop:orders_by_status
  • Cancellations 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_initiator
  • Returns 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_summary
  • Cancellations and refunds by day

    Cancellations and refunds concluded on each day of the analyzed period.

    tiktok_shop:cancellations_and_refunds_by_day
  • Sales by payment method

    Orders placed in the analyzed period grouped by the payment method chosen by the customer.

    tiktok_shop:sales_by_payment_method
  • Best 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_products
  • Sales 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_variant
  • Cancellations by reason

    Cancellations concluded in the analyzed period grouped by the reason given.

    tiktok_shop:cancellations_by_reason
  • Returns 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.