Get Activity

Get the details of a product discount or flash deal promotion activity. Product information for FIXED_PRICE, DIRECT_DISCOUNT and FLASHSALE activity that ended more than 180 days will not be returned.For coupon activities, use Get Coupon.

---

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

Query

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

• 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. | ^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 |1661856811 |Activity end time. UNIX timestamp. | ^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 | ^products |[]object | |Product List. Note:If FIXED_PRICE, DIRECT_DISCOUNT and FLASHSALE activity that ended more than 180 days,this field is empty. | ^^id |string |7136011254174631686 |TikTok Shop Product ID. | ^^activity_price |object | |Activity price. | ^^^amount |string |70500 |Activity price amount. | ^^^currency |string |IDR |Currency unit of an activity price. | ^^quantity_limit |int |-1 |The quantity limit of the products involved in the activity. The range is [1, 99], or -1 for unlimited. | ^^quantity_per_user |int |-1 |Limit of product purchase per buyer. The range is [1, 99], or -1 for unlimited. | ^^discount |string |10 |Discount value. If the product is 10% off, the value is 10. Available only if activity_type==DIRECT_DISCOUNT and product_level==PRODUCT. | ^^skus |[]object | |Available only if product_level==VARIATION. | ^^^id |string |7136382541418366725 |TikTok Shop SKU ID. | ^^^discount |string |10 |Discount value. If the SKU is 10% off, the value is 10. Available only if activity_type==DIRECT_DISCOUNT. | ^^^quantity_limit |int |-1 |The quantity limit of the SKU involved in the activity. The range is [1, 99], or -1 for unlimited. | ^^^quantity_per_user |int |-1 |Limit of SKU purchase per buyer. The range is [1, 99], or -1 for unlimited. | ^^^activity_price |object | |Activity price. Available only if activity_type==FIXED_PRICE/FLASHSALE. | ^^^^amount |string |70500 |Activity price amount. | ^^^^currency |string |IDR |Currency unit of an activity price. | ^^^used_quantity |int |3 |The quantity of SKU that have already taken effect in the activity. | ^^used_quantity |int |3 |The quantity of products that have already taken effect in the activity. | ^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 |1661750811 |Activity creation time. UNIX timestamp. | ^update_time |int |1661750811 |Activity update time. UNIX timestamp. | ^product_level |string |PRODUCT |Activity product dimension, values are:
• PRODUCT: Product level promotion activity.
• VARIATION: SKU level promotion activity.
• SHOP: Shop level promotion activity. | ^activity_commands |[]string |IMMUTABLE |Applicable commands to the activity:
• IMMUTABLE: The activity cann't be editable or deactivated | ^discount |object | |Discount information. | ^^shipping_discount |object | |Shipping discount | ^^^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.
• 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 |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 | ^^^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 |AMOUNT_OFF_EACH |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. | ^target_user_info |object | |The targeted user type of the promotion. | ^^user_type |string |ALL_USER |Possible enumerations are: ALL_USER SHOP_NEW_CUSTOMER SHOP_EXISTING_CUSTOMER SHOP_REPEAT_CUSTOMER | ^benefit_products |[]object | |Benefit products in BXGY promotions | ^^id |string |1732239744891062847 |TikTokShop product ID | ^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":{"activity_id":"7136104329798256386","title":"FlashSale 20230707","activity_type":"FIXED_PRICE","duration_type":"INDEFINITE","begin_time":1661756811,"end_time":1661856811,"participation_limit":[{"type":"NO_LIMIT"}],"products":[{"id":"7136011254174631686","activity_price":{"amount":"70500","currency":"IDR"},"quantity_limit":-1,"quantity_per_user":-1,"discount":"10","skus":[{"id":"7136382541418366725","discount":"10","quantity_limit":-1,"quantity_per_user":-1,"activity_price":{"amount":"70500","currency":"IDR"},"used_quantity":3}],"used_quantity":3}],"status":"ONGOING","create_time":1661750811,"update_time":1661750811,"product_level":"PRODUCT","activity_commands":"IMMUTABLE","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":"AMOUNT_OFF_EACH","benefit_max_applicable_quantity":"5","benefit_max_applicable_times":"5"}},"target_user_info":{"user_type":"ALL_USER"},"benefit_products":[{"id":"1732239744891062847"}],"auction_support_type":"ALL"},"message":"Success","request_id":"202203070749000101890810281E8C70B7"}

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