TikTok Shop User Showcase API examples for SocQ

Collect products displayed in one public TikTok user's Shop showcase by username and region, returning seller, price, media, rating, review, and sold-count fields.

Try TikTok Shop User Showcase API · Get an API key · Documentation · All SocQ examples

Use cases

• Review a user's showcase assortment: Use product IDs, titles, links, seller context, images, and categories to inspect the public products displayed for one username.
• Compare price and visible demand signals: Compare available prices, currencies, discounts, ratings, review counts, and sold counts across returned showcase products.
• Create regional showcase snapshots: Store input_username, region, product identity, public commerce fields, and collected_at for repeatable point-in-time review.
• Enrich a product research dataset: Add canonical product URLs, seller identity, media, categories, SKU context, and visible metrics to an existing username-led research set.

API behavior

• Submit one public TikTok username with or without a leading @; one task accepts one username.
• results_limit defaults to 100 and accepts integers from 20 through 2,000.
• The selected region controls market availability, so showcase products can differ across supported markets.
• Deduplicate repeated snapshots by product ID and treat empty tasks or missing commerce fields as valid public-data outcomes.

All requests use the shared asynchronous flow:

submit -> task_id -> poll task -> read every cursor page -> save results

Quick start

cp .env.example .env
export SOCQ_API_KEY="your-api-key"

Run the complete Node.js workflow:

cd node
npm start

Run the complete Python workflow:

python3 -m pip install -r python/requirements.txt
python3 python/main.py

Both examples load payload.example.json, retry transient API responses, wait for task completion, read every cursor page, and save a paginated public showcase-product dataset with seller, price, media, category, and visible commerce signals to output/results.json.

Never expose SOCQ_API_KEY in browser code, mobile apps, public repositories, screenshots, fixtures, or logs.

Request

POST https://api.socq.ai/v1/tiktok-shop/user-showcase
Authorization: Bearer <SOCQ_API_KEY>
Content-Type: application/json

{
  "username": "example_creator",
  "results_limit": 100,
  "region": "US"
}

The submit response contains data.task_id. Poll the task endpoint until data.status becomes succeeded or failed, then continue with data.results.next_cursor while data.results.has_more is true.

Complete workflow example

The Node.js and Python programs implement the production-shaped happy path:

1. Load and validate configuration.
2. Submit the endpoint-specific payload.
3. Retry rate-pressure and transient server responses with bounded backoff.
4. Poll the asynchronous task with a ten-minute application timeout.
5. Stop cleanly on a failed task and surface the public error message.
6. Read all cursor pages instead of silently returning only the first page.
7. Write a stable JSON artifact containing task metadata and normalized records.

Use the synthetic files in fixtures/ for tests and documentation. They do not contain customer, account, or production data.

Production notes

See docs/production-notes.md for validation, retry, timeout, pagination, deduplication, logging, and endpoint-specific guidance.

Responsible use and platform scope

• Use only publicly accessible TikTok Shop products, stores, reviews, showcases, and fields supported by the selected endpoint.
• Do not use the examples to access restricted content, login-only surfaces, authentication controls, private orders, or non-public customer information.
• SocQ is not an official API of the represented social platform and is not affiliated with or endorsed by that platform.
• Before production use, assess the laws, platform terms, privacy obligations, and retention requirements that apply to your organization and use case.
• Collect only the fields needed for a defined purpose, restrict access, set retention periods, and support correction or deletion workflows where required.
• Platform names and trademarks belong to their respective owners.

This section describes the public-data boundary; it is not legal advice or a guarantee that every use case is permitted in every jurisdiction.

Repository contents

Path	Purpose
curl/request.md	Copy-paste submit, poll, and pagination requests
node/index.mjs	Complete Node.js workflow
python/main.py	Complete Python workflow
payload.example.json	Safe endpoint-specific request body
fixtures/	Synthetic submit and task response shapes
docs/production-notes.md	Production integration guidance