Documenten
Ctrl+K Zoeken Alt+[Alt+] Handleidingen
API-sleutel ophalen

Handleidingen

Time windows

Different surfaces use different date filters. Pick one mechanism per request — don’t mix them.

At a glance

Surface Parameter Typical values
TikTok Shop explore / count / detail period 7d, 30d, 90d, sometimes alle
Merkenoverzicht (/api/v1/brands/* and session /api/brands/...) date_range + optional date_from, date_to live, 7d, 30d, 3m, 6m, custom
TikTok Shop visit-event endpoints period 7d, 30d, alle (standaard 30d)
GET /api/v1/tiktok-shop/products date_from, date_to Y-m-d
Ad library (/api/v1/adlibrary) Dashboard-compatible query params See Meta ad library
Google Ads date_from / date_to, first_seen_* See Google Ads

Most common mistake: sending start_date / end_date with period on TikTok Shop. Pass only period unless a specific endpoint documents otherwise.

TikTok Shop period

Used by explore, count, detail aggregates, history, and most metric 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 mirroring the in-app UI.
  • Sort keys follow the same period (sort=revenue + period=7d → revenue_7d upstream).

Visit-event endpoints

product-other-visits, category-visit-events, detail-visit-events:

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

Responses include period_label for display.

Merkenoverzicht date_range

Works on /api/v1/brands/* insight/ads tabs and session /api/brands/....

date_range= Effect
(omitted) of alle No date filter
live Last seen in the last 4 days (updated_at)
7d, 30d, 3m, 6m Start date on or after rolling cutoff
custom Requires both date_from en date_to as Y-m-d

Flat products listing

GET /api/v1/tiktok-shop/products accepts date_from / date_to (Y-m-d). Prefer period on every other TikTok Shop path.

Decision tree

  1. Explore / count / detail / history under /api/v1/tiktok-shop/ → period
  2. Flat GET .../products → date_from / date_to
  3. Visit-event routes → period=7d|30d|all
  4. Session or v1 /api/brands/* insight tabs → date_range (+ custom dates if needed)
  5. Meta ads → Meta ad library
  6. Google Ads → Google Ads

Related

TikTok Shop FiltersExplore / count params including period. BrandsAPI key routes for list, ads, and insight tabs. TroubleshootingEmpty results from mixed date params.