TikTok Shop Search Suggestions API

Endpoint (API key)#

GET /api/v1/tiktok-shop/suggestions

Send Clé X-API (or Autorisation : au porteur) 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 (catégories, magasins, créateurs, produits, vidéos): short id + nom rows as the user types.

Request Parameters#

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#

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 Clé API and the same metering as other /api/v1/tiktok-shop/* routes.
• Poignée 401 / 403 from Authentification et 429 from Limites de débit / Générique like any other programmatic call.

See also#

• TikTok Shop · filters & query params — explore/count filters and MCP tools that pair with suggestions in workflows.
• API reference — full route list.