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 Description Example
type string Yes Entity type to search categories, shops, creators, products, videos
q string Yes Search query (partial name match) fash, Nike, elect
limit integer No 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 Description
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 title Products
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.
  • Handle 401 / 403 from Authentication and 429 from Rate limits / Credits like any other programmatic call.

See also