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

API · TikTok Shop

TikTok Shop Search Suggestions API

Endpoint (API key)

GET /api/v1/tiktok-shop/suggestions

Send X-API-Key (or Authorization: Bearer) like every other metered programmatic route. Behavior matches the in-app autocomplete for the same path shape.

Dashboard (session): GET /api/tiktok-shop/suggestions — used when you are logged into the web app. For scripts and integrations, always use the /api/v1/... URL.

Description

Autocomplete for TikTok Shop entities (categories, shops, creators, products, videos): short id + name rows as the user types.

Request Parameters

Parameter Type Required Beschrijving Example
type string Ja Entity type to search categories, shops, creators, products, videos
q string Ja Search query (partial name match) fash, Nike, elect
limit integer Geen Maximum number of suggestions to return (default: 10, cap enforced server-side) 5, 10, 20

Response Format

Success Response

Status Code: 200 OK

Content-Type: application/json

{
  "success": true,
  "suggestions": [
    {
      "id": "category_12345",
      "name": "Fashion & Apparel"
    },
    {
      "id": "category_67890",
      "name": "Fitness Equipment"
    }
  ]
}

Error Response

Status Code: 400 Bad Request

{
  "success": false,
  "error": "Invalid entity type"
}

Status Code: 500 Internal Server Error

{
  "success": false,
  "error": "Internal server error"
}

Entity Types

Type Typical id Typical name Beschrijving
categories Category id or path Category label Product categories
shops Shop id Shop name TikTok shops
creators Creator id Username or display name Creators / affiliates
products Product id Product titel Producten
videos Video id Video title Video content

Request Examples

cURL

# Replace {origin} and $WH_API_KEY.
curl -sS -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/suggestions?type=categories&q=fash&limit=10"

curl -sS -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/suggestions?type=shops&q=nike&limit=5"

curl -sS -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/suggestions?type=creators&q=fitness&limit=10"

JavaScript Fetch

// Programmatic (API key)
const response = await fetch(`${ORIGIN}/api/v1/tiktok-shop/suggestions?type=categories&q=fash&limit=10`, {
  headers: {
    Accept: 'application/json',
    'X-API-Key': process.env.WH_API_KEY,
  },
});

const data = await response.json();
console.log(data.suggestions);
// [{ id: "category_123", name: "Fashion & Apparel" }, ...]

Behavior Notes

  • Matching: Case-insensitive partial match on the primary label field for each entity (for creators, both username and display name are considered).
  • Sorting: Results are ordered by a popularity-style signal per entity (e.g. revenue, followers, views) so common matches surface first.
  • Empty input: Very short queries may return an empty suggestions array; the web app often waits until at least 2 characters before calling.
  • Client UX: If you build a typeahead, debounce requests (~300ms) and cache recent type+q pairs briefly to avoid redundant calls (same idea as the in-app search bar).

Auth and errors

  • /api/v1/tiktok-shop/suggestions uses your API key and the same metering as other /api/v1/tiktok-shop/* routes.
  • Handgreep 401 / 403 from Authentication and 429 from Rate limits / Colofon like any other programmatic call.

See also