Docs
Ctrl+K Search Alt+[Alt+] Guides
Get API key

Guides

Time windows

Different parts of the API use different date filters. This guide is the cheat sheet — pick the right one for the endpoint you're calling, and don't mix them.

At a glance

Surface Parameter Typical values
TikTok Shop explore / count / detail period 7d, 30d, 90d, sometimes all
Merkenoverzicht (dashboard /api/brands/..., session) date_range + optional date_from, date_to live, 7d, 30d, 3m, 6m, custom
TikTok Shop visit-event endpoints period 7d, 30d, all (default 30d)
GET /api/v1/tiktok-shop/products date_from, date_to Y-m-d strings
Ad library (API key: /api/v1/adlibrary or alias /api/adlibrary) Same query string as the dashboard's /api/fb-ads (see Meta ad library). Per-parameter there.

The single most common mistake: sending start_date / end_date alongside period on TikTok Shop endpoints. Don't — those fields collide with the period-aware revenue mapping upstream and silently filter out most data. Pass only period unless the docs for a specific endpoint say otherwise.

TikTok Shop period

Used by explore, count, detail aggregates, history, and most metric-bearing endpoints under /api/v1/tiktok-shop/.

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/products/explore?country=US&period=30d&limit=20"
  • Treat period as an opaque string that mirrors the in-app filter UI (7d, 30d, 90d, …). The backend maps it to period-specific fields like revenue_30d, revenue_growth_rate_7d, etc.
  • Do not also send start_date / end_date. The TikTok Shop API does not map those to the explore flow — sending them can trigger narrow “first seen in last N days” behavior upstream and return a tiny slice of the catalog.
  • Sort keys (sort=) follow the same period — passing sort=revenue with period=7d becomes revenue_7d upstream.
  • For aggregate revenue numbers (e.g. shop totals), the period determines which revenue.{key} field you should read in the response.

Visit-event endpoints (product-other-visits, category-visit-events, detail-visit-events)

These accept a more limited set:

period= Window
(omitted) Defaults to 30d
7d, 30d Rolling N-day window
all / alltime Lifetime totals
<integer> (e.g. 90) Treated as Nd

The response includes period_label (e.g. "Last 30 days") so you can display it without parsing.

Merkenoverzicht date_range

Used by dashboard routes such as /api/brands/ads, /api/brands/ad-copies, /api/brands/ad-headlines, /api/brands/ad-hooks, /api/brands/personas, /api/brands/themes, and the other brand-detail tabs (session).

GET /api/brands/ads?id={page_id}&date_range=30d
GET /api/brands/ad-copies?id={page_id}&date_range=custom&date_from=2026-01-01&date_to=2026-03-31

Accepted values (same semantics as the Brand tracker date picker in the app):

date_range= Effect
(omitted) of all No date filter.
live Ads last seen in the last 3 days (uses the updated_at field).
7d, 30d, 3m, 6m Ads with start date on or after the rolling cutoff (started field).
custom Requires both date_from and date_to as Y-m-d.

A few tips:

  • The same three params (date_range, date_from, date_to) carry across every brand-detail tab. Once you have a date filter for the user, reuse it on every call you make for that brand session.
  • live is the only value keyed off "last seen", not "started". Don't confuse it with 7d.
  • custom without both date_from and date_to falls back to "no date filter".

The brand-detail surface is session-only (logged-in browser), so this section applies when you mirror the dashboard, not when you use GET /api/v1/brands alone. Full reference: Brands & Brand tracker.

GET /api/v1/tiktok-shop/products

This route is a flat listing endpoint that takes a small set of GET params, including explicit dates:

GET /api/v1/tiktok-shop/products
  ?country=US
  &date_from=2026-03-01
  &date_to=2026-03-31
  &search=mascara
  &min_price=10&max_price=50
  &min_sales=100
  &min_rating=4
  • Both date_from and date_to are Y-m-d strings.
  • Either may be omitted; the upstream applies a sane default if so.
  • This is the only TikTok Shop flat-listing path where date_from / date_to are first-class params. On every other path, prefer period.

Why mixing time params goes wrong

A common failure mode: copying a "products explore" request and adding start_date=2026-01-01 thinking it'll narrow the window. What actually happens:

  1. The explore handler keeps period=30d (default).
  2. It also forwards your start_date / end_date.
  3. Upstream interprets that as "first seen between those dates".
  4. You get back ~5% of the catalog — only items first crawled in that exact window.

Fix: choose one mechanism per request. If period covers your need, use it alone. If you genuinely need a custom range, use the routes that document date_from / date_to (the Brands tracker, the flat products listing, the ad library).

Quick decision tree

  • Calling /api/v1/tiktok-shop/... explore / count / detail / history? → period=7d|30d|90d.
  • Calling /api/v1/tiktok-shop/products (flat listing)? → date_from, date_to.
  • Calling /api/v1/tiktok-shop/...visit-events* of product-other-visits? → period=7d|30d|all.
  • Calling /api/brands/* (dashboard session)? → date_range, plus date_from + date_to if date_range=custom. (Tracked list with an API key: GET /api/v1/brands — no date_range on that route.)
  • Calling /api/v1/adlibrary of /api/adlibrary (Meta ads)? → see Meta ad library.