# Creator TTS - Add showcase products

- API version: 1.11.0
- Last updated: 2026-11-16
- Server: `https://api.ailingtu.com`
- Web document: [Creator TTS - Add showcase products](/en/openapi/add-showcase-products)
- Full schema: [JSON Schema](/en/openapi/operations/addTikTokShowcaseProducts.json)
- Discovery: [Operation index](/en/openapi/operations/index.json)

## POST /v1/creator/tiktokshop/product/addToShowcase

Operation ID: `addTikTokShowcaseProducts`

Add TikTok Shop products to an authorized creator showcase by product IDs or a product link.

Authentication: Request header `x-api-key: <YOUR_API_KEY>`; keep the key on the server and never expose it in client code, logs or shared files.

Success criteria: HTTP 2xx with code=0; for asynchronous tasks, also query the final status.

### Request parameters

| Field | Location | Type | Required | Description |
|---|---|---|---|---|
| `id` | body | integer | Yes | Creator account id |
| `addType` | body | PRODUCT_ID \| PRODUCT_LINK | Yes | How products are identified |
| `productIds` | body | string[] | Conditional | Required for PRODUCT_ID; 1–20 product IDs |
| `productLink` | body | string(uri) | Conditional | Required for PRODUCT_LINK |

Request format: `application/json`

### Request example: Add by product ID

```json
{
  "id": 12345,
  "addType": "PRODUCT_ID",
  "productIds": [
    "1732280564607717841",
    "1732280564607717842"
  ]
}
```

### Request example: Add by product link

```json
{
  "id": 12345,
  "addType": "PRODUCT_LINK",
  "productLink": "https://shop.tiktok.com/view/product/1732280564607717841"
}
```

### Success response: All products added

```json
{
  "code": 0,
  "data": {},
  "message": "success",
  "timestamp": 1786406400000
}
```

### Success response: Some products failed

```json
{
  "code": 0,
  "data": {
    "errors": [
      {
        "code": 16001001,
        "message": "Product is unavailable for this creator",
        "detail": {
          "productId": "1732280564607717842"
        }
      }
    ]
  },
  "message": "success",
  "timestamp": 1786406400000
}
```

### Success response: Creator authorization expired

```json
{
  "code": 40101,
  "data": {},
  "message": "授权过期，请重新授权",
  "timestamp": 1786406400000
}
```

### Response fields

Main levels are listed below. The endpoint JSON Schema is authoritative for the full structure, unions and validation rules; Required refers to the containing object.

| Field | Type | Required | Description |
|---|---|---|---|
| `code` | integer | Yes | Business status code. 0 means the request was processed; still check the per-product results. |
| `data` | object | Yes | — |
| `data.errors` | object[] | No | Per-product failures; empty or omitted when every product was added. |
| `data.errors[].code` | integer | No | — |
| `data.errors[].message` | string | No | — |
| `data.errors[].detail` | object | No | — |
| `data.errors[].detail.productId` | string | No | Product ID that failed to be added. |
| `message` | string | Yes | — |
| `timestamp` | integer | Yes | Unix timestamp in milliseconds. |

### Integration notes and limits

- Required scopes: creator.showcase.write and creator.video.write.
- A request can contain at most 20 product IDs.
- Check data.errors even when code is 0; entries identify products that failed.
- An expired creator authorization returns the business error “授权过期，请重新授权” (authorization expired, reauthorize).

### Error handling

| HTTP | Description |
|---|---|
| 400 | The request parameters or body are invalid. Fix them and retry. |
| 401 | The API key is missing or invalid. Check x-api-key. |
| 403 | The API key has no permission to call this endpoint. |
| 429 | Too many requests. Retry with exponential backoff. |
| 500 | The server failed. Retry transient failures with exponential backoff. |

Treat any non-zero business code as a failure. Do not blindly retry parameter, permission or authorization errors. If creating a publishing or generation task times out, query the existing task first instead of creating another one.

### Related endpoints

- [List showcase products](/en/openapi/showcase-products) · [Markdown](/en/openapi/operations/listTikTokShowcaseProducts.md)
- [Creator TTS - Remove showcase products](/en/openapi/remove-showcase-products) · [Markdown](/en/openapi/operations/removeTikTokShowcaseProducts.md)
- [Creator TTS - Move showcase products to top](/en/openapi/move-showcase-products-to-top) · [Markdown](/en/openapi/operations/moveTikTokShowcaseProductsToTop.md)
