TikTok Shop · Details & Aggregates

Detail endpoints return deep data for a single entity (shop, product, creator, video) by id, rather than the lists returned by explore. Every response is { "success": true, "data": { ... } }. Use an explore route first to find an id if you only have a name.

Shop details

POST/api/v1/tiktok-shop/shop-detail

Core profile for a single shop.

Send X-API-Key on every request.

Body parameters

idstringrequired
Shop id.
landstringoptional
Market the shop sells in.

Verzoek

curl -sS \
  -X POST \
  -H "X-API-Key: $WH_API_KEY" \
  -H "Content-Type: application/json" \
  "{origin}/api/v1/tiktok-shop/shop-detail" \
  -d '{"id":"7493920192384910","country":"US"}'

const res = await fetch(`${ORIGIN}/api/v1/tiktok-shop/shop-detail`, {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "id": "7493920192384910",
      "country": "US"
  }),
});
const data = await res.json();

import os, requests

res = requests.post(
    f"{ORIGIN}/api/v1/tiktok-shop/shop-detail",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
    json={
        "id": "7493920192384910",
        "country": "US"
    },
)
data = res.json()

Response

{
    "success": true,
    "data": {
        "id": "7493920192384910",
        "name": "Glow Beauty Co.",
        "country": "US",
        "logo": "https://cdn.example.com/shops/glow.png",
        "products_count": 84,
        "creators_count": 312,
        "rating": 4.8
    }
}

{
    "success": false,
    "error": "Unauthorized"
}

{
    "success": false,
    "error": "Monthly credit limit reached (20000). Resets next month."
}

POST/api/v1/tiktok-shop/shop-detail/total

Aggregate performance (revenue, sales, conversion) over a period.

Send X-API-Key on every request.

Body parameters

idstringrequired
periodintegeroptional
Days: 1, 7, 30, or 90.

Verzoek

curl -sS \
  -X POST \
  -H "X-API-Key: $WH_API_KEY" \
  -H "Content-Type: application/json" \
  "{origin}/api/v1/tiktok-shop/shop-detail/total" \
  -d '{"id":"7493920192384910","period":30}'

const res = await fetch(`${ORIGIN}/api/v1/tiktok-shop/shop-detail/total`, {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "id": "7493920192384910",
      "period": 30
  }),
});
const data = await res.json();

import os, requests

res = requests.post(
    f"{ORIGIN}/api/v1/tiktok-shop/shop-detail/total",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
    json={
        "id": "7493920192384910",
        "period": 30
    },
)
data = res.json()

Response

{
    "success": true,
    "data": {
        "revenue": 1284500,
        "sales": 51380,
        "avg_price": 24.99,
        "conversion_rate": 0.037,
        "period": 30
    }
}

POST/api/v1/tiktok-shop/shop-detail/product/queryList

Products sold by a shop, with performance sorting.

Send X-API-Key on every request.

Body parameters

idstringrequired
paginaintegeroptional
limitintegeroptional
periodintegeroptional
sorterenstringoptional
Values omzet verkoop prijs
orderstringoptional
Values beschrijving asc

Verzoek

curl -sS \
  -X POST \
  -H "X-API-Key: $WH_API_KEY" \
  -H "Content-Type: application/json" \
  "{origin}/api/v1/tiktok-shop/shop-detail/product/queryList" \
  -d '{"id":"7493920192384910","page":1,"limit":20,"period":30,"sort":"revenue","order":"desc"}'

const res = await fetch(`${ORIGIN}/api/v1/tiktok-shop/shop-detail/product/queryList`, {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "id": "7493920192384910",
      "page": 1,
      "limit": 20,
      "period": 30,
      "sort": "revenue",
      "order": "desc"
  }),
});
const data = await res.json();

import os, requests

res = requests.post(
    f"{ORIGIN}/api/v1/tiktok-shop/shop-detail/product/queryList",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
    json={
        "id": "7493920192384910",
        "page": 1,
        "limit": 20,
        "period": 30,
        "sort": "revenue",
        "order": "desc"
    },
)
data = res.json()

Response

{
    "success": true,
    "data": [
        {
            "id": "1729384756102394",
            "title": "Vitamin C Serum",
            "price": 24.9,
            "revenue": 312540,
            "sales": 12550
        }
    ],
    "page": 1,
    "total": 84
}

Product details

GET/api/v1/tiktok-shop/product-detail/{id}

Full profile of a single product.

Send X-API-Key on every request.

Path parameters

idstringrequired

Verzoek

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/product-detail/1729384756102394"

const res = await fetch(`${ORIGIN}/api/v1/tiktok-shop/product-detail/1729384756102394`, {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
  },
});
const data = await res.json();

import os, requests

res = requests.get(
    f"{ORIGIN}/api/v1/tiktok-shop/product-detail/1729384756102394",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
)
data = res.json()

Response

{
    "success": true,
    "data": {
        "id": "1729384756102394",
        "title": "Vitamin C Brightening Serum",
        "shop_id": "7493920192384910",
        "price": 24.9,
        "revenue": 312540,
        "sales": 12550,
        "rating": 4.7,
        "image": "https://cdn.example.com/products/serum.jpg"
    }
}

{
    "success": false,
    "error": "Unauthorized"
}

POST/api/v1/tiktok-shop/product-detail/total

Aggregate totals for a product.

Send X-API-Key on every request.

Body parameters

idstringrequired
periodintegeroptional

Verzoek

curl -sS \
  -X POST \
  -H "X-API-Key: $WH_API_KEY" \
  -H "Content-Type: application/json" \
  "{origin}/api/v1/tiktok-shop/product-detail/total" \
  -d '{"id":"1729384756102394","period":30}'

const res = await fetch(`${ORIGIN}/api/v1/tiktok-shop/product-detail/total`, {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "id": "1729384756102394",
      "period": 30
  }),
});
const data = await res.json();

import os, requests

res = requests.post(
    f"{ORIGIN}/api/v1/tiktok-shop/product-detail/total",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
    json={
        "id": "1729384756102394",
        "period": 30
    },
)
data = res.json()

Response

{
    "success": true,
    "data": {
        "revenue": 312540,
        "sales": 12550,
        "avg_price": 24.9,
        "period": 30
    }
}

POST/api/v1/tiktok-shop/product-detail/history

Daily sales / revenue time series for a product.

Send X-API-Key on every request.

Body parameters

idstringrequired
periodintegeroptional

Verzoek

curl -sS \
  -X POST \
  -H "X-API-Key: $WH_API_KEY" \
  -H "Content-Type: application/json" \
  "{origin}/api/v1/tiktok-shop/product-detail/history" \
  -d '{"id":"1729384756102394","period":30}'

const res = await fetch(`${ORIGIN}/api/v1/tiktok-shop/product-detail/history`, {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "id": "1729384756102394",
      "period": 30
  }),
});
const data = await res.json();

import os, requests

res = requests.post(
    f"{ORIGIN}/api/v1/tiktok-shop/product-detail/history",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
    json={
        "id": "1729384756102394",
        "period": 30
    },
)
data = res.json()

Response

{
    "success": true,
    "data": [
        {
            "date": "2024-06-01",
            "revenue": 10840,
            "sales": 435
        },
        {
            "date": "2024-06-02",
            "revenue": 11290,
            "sales": 452
        }
    ]
}

Creator details

POST/api/v1/tiktok-shop/creator-detail/total

Aggregate metrics for a creator.

Send X-API-Key on every request.

Body parameters

idstringrequired
periodintegeroptional

Verzoek

curl -sS \
  -X POST \
  -H "X-API-Key: $WH_API_KEY" \
  -H "Content-Type: application/json" \
  "{origin}/api/v1/tiktok-shop/creator-detail/total" \
  -d '{"id":"6892301928374615","period":30}'

const res = await fetch(`${ORIGIN}/api/v1/tiktok-shop/creator-detail/total`, {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "id": "6892301928374615",
      "period": 30
  }),
});
const data = await res.json();

import os, requests

res = requests.post(
    f"{ORIGIN}/api/v1/tiktok-shop/creator-detail/total",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
    json={
        "id": "6892301928374615",
        "period": 30
    },
)
data = res.json()

Response

{
    "success": true,
    "data": {
        "revenue": 84200,
        "sales": 3380,
        "videos": 47,
        "followers": 512000,
        "period": 30
    }
}

POST/api/v1/tiktok-shop/creator-detail/searchProducts

Products promoted by a creator.

Send X-API-Key on every request.

Body parameters

idstringrequired
paginaintegeroptional
limitintegeroptional
periodintegeroptional

Verzoek

curl -sS \
  -X POST \
  -H "X-API-Key: $WH_API_KEY" \
  -H "Content-Type: application/json" \
  "{origin}/api/v1/tiktok-shop/creator-detail/searchProducts" \
  -d '{"id":"6892301928374615","page":1,"limit":20,"period":30}'

const res = await fetch(`${ORIGIN}/api/v1/tiktok-shop/creator-detail/searchProducts`, {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
      "id": "6892301928374615",
      "page": 1,
      "limit": 20,
      "period": 30
  }),
});
const data = await res.json();

import os, requests

res = requests.post(
    f"{ORIGIN}/api/v1/tiktok-shop/creator-detail/searchProducts",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
    json={
        "id": "6892301928374615",
        "page": 1,
        "limit": 20,
        "period": 30
    },
)
data = res.json()

Response

{
    "success": true,
    "data": [
        {
            "id": "1729384756102394",
            "title": "Vitamin C Serum",
            "revenue": 42100,
            "sales": 1680
        }
    ],
    "page": 1,
    "total": 23
}

Video details

GET/api/v2/videos/{id}

Core metadata for a TikTok video.

Send X-API-Key on every request.

Path parameters

idstringrequired

Verzoek

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v2/videos/7361029384756102"

const res = await fetch(`${ORIGIN}/api/v2/videos/7361029384756102`, {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
  },
});
const data = await res.json();

import os, requests

res = requests.get(
    f"{ORIGIN}/api/v2/videos/7361029384756102",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
)
data = res.json()

Response

{
    "success": true,
    "data": {
        "id": "7361029384756102",
        "caption": "This serum changed my skin",
        "creator_id": "6892301928374615",
        "product_id": "1729384756102394",
        "posted_at": "2024-05-28"
    }
}

GET/api/v2/videos/{id}/metrics

Performance metrics for a video.

Send X-API-Key on every request.

Path parameters

idstringrequired

Query parameters

periodintegeroptional
1 (yesterday), 7, or 30 (default).

Verzoek

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v2/videos/7361029384756102/metrics?period=30"

const res = await fetch(`${ORIGIN}/api/v2/videos/7361029384756102/metrics?period=30`, {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
  },
});
const data = await res.json();

import os, requests

res = requests.get(
    f"{ORIGIN}/api/v2/videos/7361029384756102/metrics?period=30",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
)
data = res.json()

Response

{
    "success": true,
    "data": {
        "views": 1840000,
        "likes": 92400,
        "comments": 3120,
        "shares": 8800,
        "period": 30
    }
}

Notes

Gebruik id, not names. Detail routes require the internal id; resolve it with explore of suggestions first.
Standard periods: most aggregates accept period values 1, 7, 30, en 90.
Errors: 401, 403, 429, en 500 follow the shared shapes in Errors.

TikTok Shop · Details & Aggregates

Shop details#

Body parameters

Body parameters

Body parameters

Product details#

Path parameters

Body parameters

Body parameters

Creator details#

Body parameters

Body parameters

Video details#

Path parameters

Path parameters

Query parameters

Notes#

Shop details

Product details

Creator details

Video details

Notes