Create Promotion Activity

Use this API to create a product discount activity or a flash deal activity. You cannot create a coupon activity with this API. To do that, you'll need to go to the seller center or the seller app. To update the products or SKUs included in the activity, use Update Activity Product.

---

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

• 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.
• BUY_X_GET_Y: Buy X get Y. | product_level |string |Y |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. When activity_type is SHIPPING_DISCOUNT, the product_level can not be VARIATION. To set the products or SKUs covered by the activity, use Update Activity Product. | duration_type |string |N |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 |Y |1661756811 |Activity start time. UNIX timestamp. The value must be greater than the value of the current time. | end_time |int |Y |1661856811 |Activity end time. UNIX timestamp. | participation_limit |[]object |N | |The number of times a buyer can participate in the promotion. | ^type |string |Y |BUYER_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 |N | |Discount information. | ^shipping_discount |object |N | |Configurations for the shipping discount, including purchase criteria, discount value, shipping method, inventory type, and area scope. | ^^threshold_type |string |Y |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 |N |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 |Y |DISCOUNT_SHIPPING_FEE |The type of benefit awarded by the promotion activity. -When FREE_SHIPPING, the buyer's cost of shipping is reduced to zero. -When DISCOUNT_SHIPPING_FEE, the discount is reduced by the value specified in shipping_discount.value. | ^^value |string |N |10.5 |Value of the discount.
• When 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 |N |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 |N |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 |Y | |The (buyer's) geographical areas to which the promotion activity applies. | ^^^type |string |Y |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 |N |["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 |N | |Configurations related to Buy More Save More (BMSM) promotions | ^^details |[]object |N | |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 |Y |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 |Y |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 |Y |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 |Y |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 |Y |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 |N | |Configurations related to Gift With Purchase (GWP) promotions. Only needs to be configured for GWP promotions. | ^^gift_receiving_type |string |Y |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 |Y | |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 |Y |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 |Y |MINIMAL_ITEM_QUANTITY |The 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 |Y |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 |Y | |Gift configurations related to Gift With Purchase (GWP) promotions. | ^^^^product_id |string |Y |1732239744891062847 |TikTok Shop product id of gift. | ^^^^sku_id |string |Y |1732239787859544639 |TikTok Shop sku id of gift. | ^^^^total_claim_limit |string |Y |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 |N | |Configurations related to Buy X Get Y (BXGY) promotions. Only needs to be configured for BXGY promotions. | ^^threshold_type |string |Y |The type of purchase criteria. Possible enumerations are:
• MINIMAL_ITEM_QUANTITY: Buyer must meet or exceed the minimum spend criteria with eligible products. |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 |Y |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 |Y |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 |Y |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 |Y |5 |The quantity of item Y in a BXGY promotion. This value must be a positive integer. | ^^benefit_max_applicable_times |string |N |5 |Optional. The maximum number of times the BXGY benefit can be applied within a single order. This value must be a positive integer. | target_user_info |object |N | |The targeted user type of the promotion. | ^user_type |string |N |ALL_USER |Possible enumerations are: ALL_USER SHOP_NEW_CUSTOMER SHOP_EXISTING_CUSTOMER SHOP_REPEAT_CUSTOMER | auction_support_type |string |N |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. |

Query

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

Body

{"title":"DiscountEvent0829","activity_type":"FIXED_PRICE","product_level":"PRODUCT","duration_type":"INDEFINITE","begin_time":1661756811,"end_time":1661856811,"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":"The type of purchase criteria. Possible enumerations are:\n- `MINIMAL_ITEM_QUANTITY`: Buyer must meet or exceed the minimum spend criteria with eligible products.","threshold_value":"5","discount_type":"AMOUNT_OFF_EACH","discount_value":"5","benefit_max_applicable_quantity":"5","benefit_max_applicable_times":"5"}},"target_user_info":{"user_type":"ALL_USER"},"auction_support_type":"ALL"}

• 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. |

{"code":0,"data":{"activity_id":"7136104329798256386","create_time":1661756811,"update_time":1661756811,"status":"ONGOING"},"message":"Success","request_id":"202203070749000101890810281E8C70B7"}

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