Search Promotion Activities

POST

/promotion/202309/activities/search

Search product discount, flash sale, shipping discount, Buy More Save More, Gift With Purchase, and Buy X Get Y promotion activities. For coupon activities, use Search Coupons.

Authorizations

accessToken

Parameters

Query Parameters

shop_cipher

required

string

Identifies the shop. Obtain it from the Get Authorized Shops API.

Request Body

application/json

object

status

Filter activities by status. If omitted, activities with NOT_START, ONGOING, EXPIRED, or DEACTIVATED status are returned. Possible values:

NOT_START: The activity is not available to TikTok users until its start time.
ONGOING: The activity is available to TikTok users.
EXPIRED: The activity is no longer available because it has expired.
DEACTIVATED: The activity was deactivated by the seller and is not available to TikTok users.

string

Allowed values: NOT_START ONGOING EXPIRED DEACTIVATED

activity_title

Activity title key words. No fuzzy matching.

string

page_size

Number of activities to return per page. Range: 0 to 100. If omitted or set to 0, the effective page size is 10.

integer format: int64

page_token

Specify the value for the page. Use "" for the first page.

string

activity_type

The type of promotion activity to return. If activity_type is omitted, activities of all supported types are returned. Possible values:

FIXED_PRICE: Product discount activity with a fixed price.
DIRECT_DISCOUNT: Product discount activity with a percentage off.
FLASHSALE: Flash sale activity.
SHIPPING_DISCOUNT: Shipping fee discount activity.
BUY_MORE_SAVE_MORE: Buy More Save More activity.
GIFT_WITH_PURCHASE: Gift With Purchase activity.
BUY_X_GET_Y: Buy X Get Y activity.

string

Allowed values: FIXED_PRICE DIRECT_DISCOUNT FLASHSALE SHIPPING_DISCOUNT BUY_MORE_SAVE_MORE GIFT_WITH_PURCHASE BUY_X_GET_Y

Example

{
  "status": "ONGOING",
  "activity_title": "Discount",
  "page_size": 20,
  "page_token": "21",
  "activity_type": "FLASHSALE"
}

Responses

200

Success

application/json

object

code

Status code; 0 means success.

integer format: int64

message

Success or failure message.

string

request_id

Request log ID.

string

data

object

total_count

Total number of activities matching the supplied filters. This value can be greater than the number of entries in activities.

integer format: int64

next_page_token

Page cursor for the next request. Pass a non-empty returned token as page_token to retrieve the next page. Stop when next_page_token is omitted or empty.

string

activities

Activities list information.

Array<object>

object

A unique ID that identifies different activities.

string

title

Activity name (50 characters max).

string

activity_type

The type of promotion activity. Possible values:

FIXED_PRICE: Product discount activity with a fixed price.
DIRECT_DISCOUNT: Product discount activity with a percentage off.
FLASHSALE: Flash sale activity.
SHIPPING_DISCOUNT: Shipping fee discount activity.
BUY_MORE_SAVE_MORE: Buy More Save More activity.
GIFT_WITH_PURCHASE: Gift With Purchase activity.
BUY_X_GET_Y: Buy X Get Y activity.

string

Allowed values: FIXED_PRICE DIRECT_DISCOUNT FLASHSALE SHIPPING_DISCOUNT BUY_MORE_SAVE_MORE GIFT_WITH_PURCHASE BUY_X_GET_Y

duration_type

The effective time type of the current activity

NORMAL: begin_time and end_time must be filled
INDEFINITE: begin_time and end_time aren’t required, and the promotion will be a long-term activity which runs indefinitely.

INDEFINITE is only valid when activity_type is SHIPPING_DISCOUNT,
If duration_type is INDEFINITE, start_time and end_time should be 0 Default: NORMAL

string

begin_time

Activity start time, as a Unix timestamp in seconds.

integer format: int64

end_time

Activity end time, as a Unix timestamp in seconds.

integer format: int64

status

Activity status. Possible values:

DRAFT: Promotion activities with this status are not available to TikTok users.
NOT_START: Promotion activities with this status are not available to TikTok users until the set activity start time.
ONGOING: Promotion activities with this status are available to TikTok users.
EXPIRED: Promotion activities with this status are not available to TikTok users because it has expired.
DEACTIVATED: The activity has been deactivated by the seller and is not available to TikTok users.
NOT_EFFECTIVE: The activity is terminated by the platform and is not available to TikTok users.

string

Allowed values: DRAFT NOT_START ONGOING EXPIRED DEACTIVATED NOT_EFFECTIVE

create_time

The time when the activity was created, as a Unix timestamp in milliseconds.

integer format: int64

update_time

The time when the activity was last updated, as a Unix timestamp in milliseconds.

integer format: int64

product_level

Activity product dimension, values are: - PRODUCT: Promotion activity applies at the product (SPU) level. Any and all SKUs that are part of this product will be subject to the promotion. - VARIATION: Promotion activity only applies to specified SKUs. - SHOP: Promotion activity applies to all products in the shop.

string

activity_commands

Applicable commands to the activity:

IMMUTABLE: The activity cannot be edited or deactivated.

Array<string>

participation_limit

The number of times a buyer can participate in the promotion.

Array<object>

object

type

Determines whether the promotion activity limits the number of times each buyer can receive its benefit. e.g.:

BUYER_NO_LIMIT: No limit for buyers. Buyers can benefit from this promotion across multiple orders.
BUYER_LIMIT_ONLY_ONE: Buyers can benefit from this promotion activity for no more than one order. Default: BUYER_NO_LIMIT

string

discount

Discount information. This field is omitted for FIXED_PRICE, DIRECT_DISCOUNT, and FLASHSALE activities.

object

shipping_discount

Shipping discount

object

threshold_type

The type of purchase criteria. Possible enumerations are:

NO_THRESHOLD: No minimum purchase criteria.
MINIMAL_ITEM_QUANTITY: Buyer must meet or exceed the minimum spend criteria with eligible products.
MINIMAL_ORDER_AMOUNT: Buyer must meet or exceed the minimum spend criteria with eligible order. MINIMAL_ITEM_QUANTITY and MINIMAL_ORDER_AMOUNT can only be set when product_level==SHOP.

string

Allowed values: NO_THRESHOLD MINIMAL_ITEM_QUANTITY MINIMAL_ORDER_AMOUNT

threshold_value

The purchase threshold returned for the shipping discount, based on threshold_type.

When threshold_type==NO_THRESHOLD, this value is not required.
When threshold_type==MINIMAL_ITEM_QUANTITY, this is the number of eligible products the buyer must purchase and must be an integer.
When threshold_type==MINIMAL_ORDER_AMOUNT, this is the eligible-product subtotal the buyer must reach in local currency (for example, 3 units of local currency) and must have no more than two decimal places.

string

type

The type of shipping discount returned for the promotion activity.

FREE_SHIPPING: The buyer’s shipping charge is fully covered.
DISCOUNT_SHIPPING_FEE: The buyer’s shipping charge is reduced by up to the amount in value.

string

value

Value of the discount.

When type==FREE_SHIPPING, this value is not required.
type==DISCOUNT_SHIPPING_FEE, this value is the maximum amount deducted from the buyer’s price of shipping in local currency. The value should be limited to two decimal places.

string

shipping_method

The shipping methods to which this promotion applies.

When STANDARD_SHIPPING: Only applies to Standard Shipping methods, including Economy.
EXPRESS_SHIPPING: Only applies to Express Shipping methods.
ALL_SHIPPING_METHOD: Applies to all shipping methods that the shop offers. Default: STANDARD_SHIPPING

string

inventory_type

The inventory types to which the promotion activity applies:

SELF_FULFILLED: Only applies to Inventory fulfilled from seller warehouses
FULFILLED_BY_TIKTOK: Only applies to Inventory fulfilled by TikTok from FBT (Fulfilled by TikTok) warehouses.
ALL: Applies to all inventory of eligible products. Default: SELF_FULFILLED FULFILLED_BY_TIKTOK and ALL can only be set when product_level==SHOP and threshold_type=NO_THRESHOLD.

string

area_scope

The (buyer’s) geographical areas to which the promotion activity applies.

object

type

The (buyer’s) geographical area to which the promotion activity applies. - WHOLE: Promotion activity applies to all areas to which the seller offers fulfillment.

SPECIFIC_AREAS: Only applies to specific fulfillment areas, as defined in area_scope.specific_areas.

string

specific_areas

The list of areas for which the promotion activity applies. The valid values that may be included in this list are dependent on the region of the shop. The list of valid values for each shop region are available here: link

Array<string>

bmsm_discount

Configurations related to Buy More Save More (BMSM) promotions.

object

details

Configurations for BMSM promotions. A maximum of two tiers are permitted. details.threshold_type and details.type must be the same across all tiers.

Array<object>

object

tier

tier uses 1-based indexing, i.e. the first and second tiers are counted “1, 2”, not “0, 1”. threshold_value and value for a given tier must be greater than that of the previous tier. E.g. If tier==1 has threshold_value==20 and value== 15, tier==2 must have threshold_value > 20 and value>15.

integer format: int64

threshold_type

The type of purchase criteria. Possible enumerations are:

MINIMAL_ITEM_QUANTITY: Buyer must meet or exceed the minimum spend criteria with eligible products.
MINIMAL_ORDER_AMOUNT: Buyer must meet or exceed the minimum spend criteria with eligible order.

string

Allowed values: MINIMAL_ITEM_QUANTITY MINIMAL_ORDER_AMOUNT

threshold_value

The purchase threshold of the discount, based on the threshold_type, e.g., “3”. Determined by user.

When threshold_type==NO_THRESHOLD, this value is not required.
When threshold_type==MINIMAL_ITEM_QUANTITY, buyer must purchase at least the specified number of eligible products (e.g. must purchase 3 or more eligible products to receive the benefit). If it represents a quantity, it must be an integer.
When threshold_type==MINIMAL_ORDER_AMOUNT, the eligible product subtotal for the buyer’s order must meet or exceed the specified order value in local currency (e.g. buyer’s order subtotal must be at least $3 to receive the benefit). If it represents an order value, it must be limited to two decimal places.

string

type

The type of discount awarded as a benefit. The value of the discount is determined by value. Possible enumerations are:

PERCENTAGE_OFF: Buyer will receive X% off the price of the eligible products.
AMOUNT_OFF: Buyer will receive X units of local currency off the price of eligible products.

string

Allowed values: PERCENTAGE_OFF AMOUNT_OFF

value

Value of the discount.

When type==PERCENTAGE_OFF, the buyer will receive X% off the price of eligible products. If the value represents a percentage, it should be an integer.
type==AMOUNT_OFF, the buyer will receive X units of local currency off the price of eligible products. If the value represents a monetary amount, it should be limited to two decimal places.

string

gift_discount

Configurations related to Gift With Purchase (GWP) promotions. Only needs to be configured for GWP promotions.

object

gift_receiving_type

The receiving type of gift. Currently only supports one type: ALL_RECEIVE

string

gift_infos

Configurations regarding Gift With Purchase (GWP) promotions. A maximum of two tiers are permitted in SEA and UK. Only one tier is permitted in US. And threshold_type must be the same across all tiers.

Array<object>

object

tier

tier uses 1-based indexing, i.e. the first and second tiers are counted “1, 2”, not “0, 1”. threshold_value for a given tier must be greater than that of the previous tier. E.g. If tier==1 has threshold_value==2, tier==2 must have threshold_value > 2.

integer format: int64

threshold_type

Purchase threshold type of discount. Possible enumerations are:

MINIMAL_ITEM_QUANTITY: Buyer must meet or exceed the minimum spend criteria with eligible products.
MINIMAL_ORDER_AMOUNT: Buyer must meet or exceed the minimum spend criteria with eligible order.

string

Allowed values: MINIMAL_ITEM_QUANTITY MINIMAL_ORDER_AMOUNT

threshold_value

The purchase threshold value of the gift, based on threshold_type. Determined by the user.

When threshold_type==MINIMAL_ITEM_QUANTITY, the buyer must purchase at least the specified number of eligible products (for example, 3 eligible products). If it represents a quantity, it must be an integer.
When threshold_type==MINIMAL_ORDER_AMOUNT, the eligible-product subtotal must meet or exceed the specified value in local currency (for example, 3 units of local currency). If it represents an order value, it must be limited to two decimal places.

string

gift_details

Gift configurations related to Gift With Purchase (GWP) promotions.

Array<object>

object

product_id

TikTok Shop product id of gift.

string

sku_id

TikTok Shop sku ID of gift.

string

total_claim_limit

The quantity limit of the gift sku which is involved in the activity. The range is [1, 99999]. If you are updating the value of an existing sku, the value cannot be decreased.

string

bxgy_discount

Configurations related to Buy X Get Y (BXGY) promotions. Only needs to be configured for BXGY promotions.

object

threshold_type

The purchase criterion returned for the activity. Possible values:

MINIMAL_ITEM_QUANTITY: The buyer must purchase at least the specified quantity of eligible products.
MINIMAL_ORDER_AMOUNT: The eligible-product subtotal must reach the specified amount.

string

Allowed values: MINIMAL_ITEM_QUANTITY MINIMAL_ORDER_AMOUNT

threshold_value

The purchase threshold returned for the activity, based on threshold_type.

When threshold_type==MINIMAL_ITEM_QUANTITY, this is the number of eligible products the buyer must purchase and must be an integer.
When threshold_type==MINIMAL_ORDER_AMOUNT, this is the eligible-product subtotal the buyer must reach, in local currency.

string

discount_type

The type of discount awarded as a benefit. For PERCENTAGE_OFF and AMOUNT_OFF_EACH, the discount amount is determined by discount_value. Possible enumerations are:

PERCENTAGE_OFF: Buyer will receive X% off the price of the eligible products.
FREE: Buyer will receive X eligible products for free.
AMOUNT_OFF_EACH: Buyer will receive X units of local currency off the price of each eligible product.

string

Allowed values: PERCENTAGE_OFF FREE AMOUNT_OFF_EACH

discount_value

Value of the discount.

When type==PERCENTAGE_OFF, the buyer will receive X% off the price of eligible products. If the value represents a percentage, it should be an integer.
type==AMOUNT_OFF_EACH, the buyer will receive X units of local currency off the price of each eligible products. If the value represents a monetary amount, it should be limited to two decimal places.

string

benefit_max_applicable_quantity

The quantity of item Y in a BXGY promotion. This value must be a positive integer.

string

benefit_max_applicable_times

Optional. The maximum number of times the BXGY benefit can be applied within a single order. This value must be a positive integer.

string

auction_support_type

Whether a SHIPPING_DISCOUNT activity supports auction products. This field is omitted for other activity types and can be omitted when auction-support data is unavailable. Possible values:

ALL: The activity supports both normal products and auction products.
EXCLUDE_AUCTION: The activity does not support auction products.

string

Allowed values: ALL EXCLUDE_AUCTION

Example

{
  "code": 0,
  "data": {
    "total_count": 120,
    "next_page_token": "1661756811000",
    "activities": [
      {
        "id": "7136104329798256386",
        "title": "FlashSale 20230707",
        "activity_type": "FIXED_PRICE",
        "duration_type": "INDEFINITE",
        "begin_time": 1661756811,
        "end_time": 1661756811,
        "status": "ONGOING",
        "create_time": 1788301318971,
        "update_time": 1788301318971,
        "product_level": "PRODUCT",
        "activity_commands": [
          "IMMUTABLE"
        ],
        "participation_limit": [
          {
            "type": "BUYER_NO_LIMIT"
          }
        ],
        "discount": {
          "shipping_discount": {
            "threshold_type": "MINIMAL_ITEM_QUANTITY",
            "threshold_value": "3",
            "type": "DISCOUNT_SHIPPING_FEE",
            "value": "10.5",
            "shipping_method": "STANDARD_SHIPPING",
            "inventory_type": "SELF_FULFILLED",
            "area_scope": {
              "type": "WHOLE",
              "specific_areas": [
                "Washington",
                "New York"
              ]
            }
          },
          "bmsm_discount": {
            "details": [
              {
                "tier": 1,
                "threshold_type": "MINIMAL_ITEM_QUANTITY",
                "threshold_value": "5",
                "type": "PERCENTAGE_OFF",
                "value": "10"
              }
            ]
          },
          "gift_discount": {
            "gift_receiving_type": "ALL_RECEIVE",
            "gift_infos": [
              {
                "tier": 1,
                "threshold_type": "MINIMAL_ITEM_QUANTITY",
                "threshold_value": "3",
                "gift_details": [
                  {
                    "product_id": "1732239744891062847",
                    "sku_id": "1732239787859544639",
                    "total_claim_limit": "100"
                  }
                ]
              }
            ]
          },
          "bxgy_discount": {
            "threshold_type": "MINIMAL_ITEM_QUANTITY",
            "threshold_value": "5",
            "discount_type": "AMOUNT_OFF_EACH",
            "discount_value": "5",
            "benefit_max_applicable_quantity": "5",
            "benefit_max_applicable_times": "5"
          }
        },
        "auction_support_type": "ALL"
      }
    ]
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}

Search Promotion Activities

Authorizations

Parameters

Query Parameters

Request Body

Example

Responses

200

Example

Start here

SDKs

OpenAPI