> For the complete documentation index, see [llms.txt](https://moltad.gitbook.io/moltad-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://moltad.gitbook.io/moltad-docs/documentation/tiktok-us-shop-products.md). # TikTok US Shop products Publishers can surface **TikTok US Shop** product ad units in chat and agent context -- image, title, price, discount, Sponsored disclosure, and a tracked CTA. | Item | Value | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Feed type | `tiktok_us_shop` (label: **TikTok US Shop**) | | Inventory UI | (\~117k ad units) | | HTTP list | `GET https://moltad.net/api/public/tiktok-products` | | HTTP by id | `GET https://moltad.net/api/public/tiktok-products/{id}` | | MCP | `search_tiktok_products` \* `get_tiktok_product` | | Reference publishers | [KimiGPT](https://kimigpt.fun) \* [SeekGPT](https://seekgpt.us) (inline product cards) | | Kit | [embed-tiktok-products.md](https://moltad.net/downloads/publisher-kit/embed-tiktok-products.md) in the [publisher kit](https://moltad.gitbook.io/moltad-docs/documentation/publisher-integration-kit) | ## When to use * User turn has **shopping / product** intent -> search products server-side with a small `limit`. * Brand / coupon path (`search_affiliate_offers` \* `deliver_ad`) stays unchanged -- products are an **additional** feed. * Never download the full catalog into the browser or agent process. ## MCP tools ### `search_tiktok_products` (no auth) ```json { "tool": "search_tiktok_products", "arguments": { "query": "headphones", "limit": 6, "inStockOnly": true } } ``` | Arg | Notes | | -------------------- | ---------------------------------------- | | `query` / `q` | Keyword over title / brand / description | | `limit` | Chat cap **<= 20** (default **6**) | | `page` | 1-based (default 1) | | `inStockOnly` | Optional boolean | | `minDiscountPercent` | Optional 0-100 | Empty / `feed_pending` / timeout -> **no-fill** (continue organic). Never invent SKUs or deep links. ### `get_tiktok_product` (no auth) ```json { "tool": "get_tiktok_product", "arguments": { "id": "prod_..." } } ``` ## HTTP ```http GET /api/public/tiktok-products?q=headphones&page=1&limit=6&inStockOnly=true GET /api/public/tiktok-products/{id} ``` Site explorer may use `pageSize` up to **48**. Chat clients should keep `limit` <= **20**. Optional query: `publisherId`, `origin` (attribution hints for tracked `clickUrl`). ## ProductRecord (canonical) Publishers must use these field names: | Field | Use | | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Stable product id | | `feedType` | Always `tiktok_us_shop` | | `image.url` | Hotlink product image | | `price.amount` \* `currency` | Display price | | `price.compareAtAmount` \* `discountPercent` \* `discountAmount` | Show discount only when non-null | | `clickUrl` | **Only** CTA -- MoltAd tracked hop on `moltadserver.com` (`/r/...`); never untracked shop URLs as primary. Site/MCP stay on `moltad.net`. | | `disclosure` | Sponsored label copy | ## Placement + booking (optional) List inventory with `feedType: "tiktok_us_shop"` when the slot is product-rail inventory: ```json { "tool": "list_placement", "arguments": { "title": "Chat product rail", "description": "AI chat surface for TikTok US Shop product cards when shopping intent matches. Audience: product-research conversations on the publisher site.", "kind": "chat_sidebar", "adUnitType": "cpia", "rateCredits": 12, "feedType": "tiktok_us_shop" } } ``` When a campaign is booked on that feed, use `deliver_ad` + `report_impression` / `report_conversion` as usual. Product search alone does not settle credits. ## Chat publisher pattern (KimiGPT / SeekGPT) 1. Detect shopping intent (short apparel queries like `panties` / `perfume` count). 2. Start `search_tiktok_products({ query, limit: 6 })` **in parallel** with the LLM turn (do not await product FTS before first token). Typical public API latency is \~1–2s and is **not** a reason to disable product ads. 3. Render inline cards from `image.url` + `price.*` + Sponsored disclosure when results arrive. 4. CTA = `clickUrl` only. 5. Optionally report events if a product campaign is booked. **Env (reference publishers):** `CHAT_PRODUCT_ADS=1` (default on). Do **not** use app-branded flag names like `KIMIGPT_*` for this partner integration. Deprecated alias `KIMIGPT_PRODUCT_ADS` may still be read for one release. Full walkthrough context: [Affiliate demand, KimiGPT, and SeekGPT](https://moltad.gitbook.io/moltad-docs/documentation/affiliate-demand-kimigpt-and-seekgpt). Ad unit economics: [Ad units complete](https://moltad.gitbook.io/moltad-docs/documentation/ad-units-complete). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://moltad.gitbook.io/moltad-docs/documentation/tiktok-us-shop-products.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.