---
title: "Every activity on the shop, live from TikTok"
method: GET
path: "/promotions/activities/search"
tags: ["Promotions"]
---

# Every activity on the shop, live from TikTok

`GET /promotions/activities/search`

## Request

- Base URL: `https://api.reacherapp.com/public/v1`
- URL: `https://api.reacherapp.com/public/v1/promotions/activities/search`
- Auth: API key in header `x-api-key` and API key in header `x-shop-id`

All product discount, flash sale, shipping and buy-more-save-more activities on the shop as TikTok lists them, including ones made in Seller Center. Nothing is stored. Search returns no products; read one with `GET /promotions/activities/{activity_id}` for products, prices and `used_quantity`. Coupons are listed under `/promotions/coupons`. Paged by walking TikTok's cursor, so page N costs N upstream calls; pages beyond 20 are refused. TikTok returns no GMV, orders, discount totals or ROI per promotion.

## Query parameters

- `page` integer
- `page_size` integer
- `status` 'DRAFT' | 'NOT_START' | 'ONGOING' | 'EXPIRED' | 'DEACTIVATED' | 'NOT_EFFECTIVE'
- `activity_type` 'FIXED_PRICE' | 'DIRECT_DISCOUNT' | 'FLASHSALE' | 'SHIPPING_DISCOUNT' | 'BUY_MORE_SAVE_MORE' | 'BUY_X_GET_Y' | 'GIFT_WITH_PURCHASE': ``activity_type`` values search returns (spec plus GIFT_WITH_PURCHASE seen live); wider than ``ActivityType``.
- `title` string, nullable: TikTok's title keyword match.

## Response `200`

Successful Response

- PromotionActivitySearchResponse: Every activity on the shop as TikTok lists it, including Seller Center ones; search omits products.
  - `shop_id` integer, required
  - `data` PromotionActivityLiveOut[], required
    - `activity_id` string, required
    - `title` string, required
    - `activity_type` string, required
    - `product_level` string, nullable
    - `status` string, required
    - `begin_time` integer, nullable: Unix seconds.
    - `end_time` integer, nullable: Unix seconds.
    - `immutable` boolean, required: TikTok will refuse edits and deactivation (activity_commands has IMMUTABLE).
    - `products` PromotionProductOut[]
      - `activity_price_amount` number, nullable
      - `currency` string, nullable
      - `discount` integer, nullable
      - `quantity_limit` integer, nullable
      - `quantity_per_user` integer, nullable
      - `used_quantity` integer, nullable: Units sold at the activity price so far (TikTok's used_quantity); detail only.
      - `product_id` string, required
      - `skus` PromotionSkuOut[]
        - `activity_price_amount` number, nullable
        - `currency` string, nullable
        - `discount` integer, nullable
        - `quantity_limit` integer, nullable
        - `quantity_per_user` integer, nullable
        - `used_quantity` integer, nullable: Units sold at the activity price so far (TikTok's used_quantity); detail only.
        - `sku_id` string, required
    - `duration_type` string, nullable: NORMAL (begin/end set) or INDEFINITE.
    - `participation_limit` string[]: TikTok's participation_limit[].type, e.g. BUYER_NO_LIMIT, BUYER_LIMIT_ONLY_ONE.
    - `discount` object: TikTok's discount object as sent: shipping_discount, bmsm_discount, gift_discount, bxgy_discount. Empty for flash sale, fixed price and percent-off, whose discount is on each product.
    - `target_user_info` object: TikTok's target_user_info as sent (user_type); detail only.
    - `benefit_product_ids` string[]: TikTok's benefit_products[].id; detail only.
    - `auction_support_type` string, nullable
    - `create_time` integer, nullable: Milliseconds since the epoch, as TikTok returns it.
    - `update_time` integer, nullable: Milliseconds since the epoch, as TikTok returns it.
  - `pagination` PublicApiCorePaginationPaginationMeta, required: Pagination metadata returned in responses.
    - `total_count` integer, required
    - `page` integer, required
    - `page_size` integer, required
    - `total_pages` integer, required

## Other responses

- `400`: Multi-shop key or invalid id.
- `403`: The shop's TikTok grant lacks `seller.promotion.info` (`SCOPE_NOT_GRANTED`).
- `404`: No such activity or coupon.
- `409`: The shop's TikTok connection needs re-authorizing (`SHOP_NOT_CONNECTED`).
- `422`: Validation Error
- `429`: TikTok is rate limiting this shop (`UPSTREAM_RATE_LIMITED`).
- `502`: TikTok did not complete the request (`UPSTREAM_ERROR`). For a UK shop, with `details.reason` and `Retry-After`, its customer-service token could not be renewed in time.

## Changes

> 76 revisions in range; 1 not diffed.

- **2026-10-28** `b703ac3d3141`: 2 info
  - added the non-success response with the status `409`
  - added the non-success response with the status `502`
- **2026-10-25** `84094c04c9fd`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/reacherapp/apis/reacher-data-api/changes/promotions/activities/search/get.md)

---

[API](https://skmtc.dev/reacherapp/apis/reacher-data-api.md) - [All operations](https://skmtc.dev/reacherapp/apis/reacher-data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/reacherapp/apis/reacher-data-api/revisions/63ce74b30b5a?raw)