Search Promotion Activities

Get a list of product discount or flash deal promotion activities. For coupon activities, use Search Coupons.

---

For common parameters, refer to How to call TikTok Shop APIs - Common Parameters

• 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. | activity_title |string |N |Discount |Activity title key words. No fuzzy matching. | page_size |int |N |20 |Page size. The range is [0, 100]. 50 by default. | page_token |string |N |21 |Specify the value for the page. Use "" for the first page. | activity_type |string |N |FLASHSALE |The type of activities. If activity_type isn't passed, return activities of all types. Possible values:
• FIXED_PRICE: product discount activity with fixed price.
• DIRECT_DISCOUNT: product discount activities with percentage off.
• FLASHSALE: flash sale activity.
• SHIPPING_DISCOUNT: shipping fee discount.
• BUY_MORE_SAVE_MORE: Buy more save more discount. |

Query

https://open-api.tiktokglobalshop.com/promotion/202309/activities/search?app_key=123abc&sign=5361235029d141222525e303d742f9e38aea052d10896d3197ab9d6233730b8c&timestamp=1625484268&shop_cipher=ROW_RHkDDABBAAB8tKAVoAqsMTjsQZFLyNfY

Body

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

• FIXED_PRICE: product discount activity with fixed price.
• DIRECT_DISCOUNT: product discount activities with percentage off.
• FLASHSALE: flash sale activity.
• SHIPPING_DISCOUNT: shipping fee discount. | ^^duration_type |string |INDEFINITE |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 | ^^begin_time |int |1661756811 |Activity start time. UNIX timestamp. The value must be greater than the value of the current time. | ^^end_time |int |1661756811 |Activity end time. UNIX timestamp. | ^^status |string |ONGOING |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. | ^^create_time |int |1661756811 |The time when the activity was created. | ^^update_time |int |1661756811 |The time when the activity was last updated. | ^^product_level |string |PRODUCT |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. | ^^activity_commands |[]string |IMMUTABLE |Applicable commands to the activity:
• IMMUTABLE: The activity cannot be edited or deactivated. | ^^participation_limit |[]object | |The number of times a buyer can participate in the promotion. | ^^^type |string |NO_LIMIT |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 | ^^discount |object | |Discount information. | ^^^shipping_discount |object | |Configurations for the shipping discount, including purchase criteria, discount value, shipping method, inventory type, and area scope. | ^^^^threshold_type |string |MINIMAL_ITEM_QUANTITY |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, | ^^^^threshold_value |string |3 |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. | ^^^^type |string |DISCOUNT_SHIPPING_FEE |The type of benefit awarded by the promotion activity.
• FREE_SHIPPING, the buyer's cost of shipping is reduced to zero.
• DISCOUNT_SHIPPING_FEE, the discount is reduced by the value specified in shipping_discount.value. | ^^^^value |string |10.5 |Value of the discount.
• discount_type==FREE_SHIPPING, this value is not required.
• discount_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. | ^^^^shipping_method |string |STANDARD_SHIPPING |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 | ^^^^inventory_type |string |SELF_FULFILLED |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. | ^^^^area_scope |object | |The (buyer's) geographical areas to which the promotion activity applies | ^^^^^type |string |WHOLE |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 | ^^^^^specific_areas |[]string |[Washington, New York] |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 | ^^^bmsm_discount |object | |Configurations related to Buy More Save More (BMSM) promotions | ^^^^details |[]object | |Configurations regarding BMSM promotions. A maximum of two tiers are permitted. details.threshold_type and details.discount_type must be the same across all tiers. | ^^^^^tier |int |1 |tier uses 1-based indexing, i.e. the first and second tiers are counted "1, 2", not "0, 1". threshold_value and discount_value for a given tier must be greater than that of the previous tier. E.g. If tier<span style="background-color: #ff0">1 has </span><span style="background-color: #ff0"><code>threshold_value</code></span>20 and discount_value== 15, tier==2 must have threshold_value > 20 and discount_value>15. | ^^^^^threshold_type |string |MINIMAL_ITEM_QUANTITY |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. | ^^^^^threshold_value |string |5 |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. | ^^^^^type |string |PERCENTAGE_OFF |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. | ^^^^^value |string |10 |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. | ^^^gift_discount |object | |Configurations related to Gift With Purchase (GWP) promotions. Only needs to be configured for GWP promotions. | ^^^^gift_receiving_type |string |ALL_RECEIVE |The receiving type of gift. Currently only supports one type: ALL_RECEIVE -ALL_RECEIVE: All gifts configured in the promotion can be collected. | ^^^^gift_infos |[]object | |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. | ^^^^^tier |int |1 |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<span style="background-color: #ff0">1 has </span><span style="background-color: #ff0"><code>threshold_value</code></span>2, tier==2 must have threshold_value > 2. | ^^^^^threshold_type |string |MINIMAL_ITEM_QUANTITY |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. | ^^^^^threshold_value |string |3 |The purchase threshold value of the gift, based on the threshold_type. Determined by user.
• 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. | ^^^^^gift_details |[]object | |Gift configurations related to Gift With Purchase (GWP) promotions. | ^^^^^^product_id |string |1732239744891062847 |TikTok Shop product id of gift. | ^^^^^^sku_id |string |1732239787859544639 |TikTok Shop sku id of gift. | ^^^^^^total_claim_limit |string |100 |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. | ^^^bxgy_discount |object | |Configurations related to Buy X Get Y (BXGY) promotions. Only needs to be configured for BXGY promotions. | ^^^^threshold_type |string |MINIMAL_ITEM_QUANTITY |The type of purchase criteria. Possible enumerations are:
• MINIMAL_ITEM_QUANTITY: Buyer must meet or exceed the minimum spend criteria with eligible products. | ^^^^threshold_value |string |5 |The purchase threshold of the discount, based on the threshold_type, e.g., "3". Determined by user.
• 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. | ^^^^discount_type |string |AMOUNT_OFF_EACH |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.
• FREE: Buyer will receive X eligible products for free.
• AMOUNT_OFF_EACH: Buyer will receive X units of local currency off the price on each of eligible products. | ^^^^discount_value |string |5 |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. | ^^^^benefit_max_applicable_quantity |string |5 |The quantity of item Y in a BXGY promotion. This value must be a positive integer. | ^^^^benefit_max_applicable_times |string |5 |Optional. The maximum number of times the BXGY benefit can be applied within a single order. This value must be a positive integer. | ^^auction_support_type |string |ALL |Determine whether the activity support auction product or not. Possible enumerations:
• ALL: activity support both normal product and auction product
• EXCLUDE_AUCTION: activity doesn't support auction product. |

{"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":1661756811,"update_time":1661756811,"product_level":"PRODUCT","activity_commands":"IMMUTABLE","participation_limit":[{"type":"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"}

For common error codes, refer to How to call TikTok Shop APIs - Common Error Code