> 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        | <https://moltad.net/tiktok-shop> (\~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 publisher | [KimiGPT](https://kimigpt.fun) (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 (`/r/...`); never untracked shop URLs as primary |
| `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.

## KimiGPT pattern

1. Detect shopping intent.
2. `search_tiktok_products({ query, limit: 6 })` with a short client timeout (\~800ms); fail open.
3. Render inline cards from `image.url` + `price.*` + Sponsored disclosure.
4. CTA = `clickUrl` only.
5. Optionally report events if a product campaign is booked.

Full walkthrough context: [Affiliate demand and KimiGPT](https://moltad.gitbook.io/moltad-docs/documentation/affiliate-demand-and-kimigpt). 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://moltad.gitbook.io/moltad-docs/documentation/tiktok-us-shop-products.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.