Get Coupon

Use this API to get the full details of a coupon matching the {coupon_id}.

---

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

Query

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

Values:

• REGULAR: Regular coupons which are displayed to TikTok users across all display locations available in TTS, including PLPs, PDPs, TikTok Videos, LIVE Rooms, Creator Showcases, and may be shared via TTS Customer Support instant messages. Includes coupons which target select customer segments.
• LIVE: Coupons which are only displayed to TikTok users in LIVE Rooms.
• CREATOR_EXCLUSIVE: Coupons that can be claimed through the display channels of the specified creator, such as their LIVE Rooms, and their Creator Showcase.
• CHAT: Exclusive coupons that may be sent to customers via TTS customer support chat messages, but are not displayed in other display locations.
• PROMO_CODE: Promo codes do not have dedicated display locations on TikTok, but may be shared with customers in LIVEs, in TikTok videos, or other social media platforms. They can be claimed by customers entering a claim code at checkout or by customers that use a custom promo code landing page URL.

| ^^status |string |NOT_START |Coupon's promotion status. Values:

• NOT_START: Not available to TikTok users until the coupon's configured start time.
• ONGOING: Available to TikTok users.
• EXPIRED: Not available to TikTok users because it has expired.
• DEACTIVATED: Deactivated by the seller and is not available to TikTok users.

| ^^create_time |int |1661756811000 |The UNIX timestamp of when the coupon was created. | ^^update_time |int |1661756811000 |The UNIX timestamp of when the coupon was updated. | ^^claim_duration |object | |Claimable period of the coupon. | ^^^start_time |int |1709568000 |The UNIX timestamp from which a shopper can claim the coupon. | ^^^end_time |int |1709654340 |The UNIX timestamp after which a shopper can no longer claim the coupon. | ^^redemption_duration |object | |Period during which the coupon can be redeemed (i.e. applied to an order). | ^^^type |string |ABSOLUTE |Values:

• ABSOLUTE: the redemption period starts from start_time and ends at end_time.
• RELATIVE: the redemption period starts from the time the coupon is claimed and lasts for relative_time. | ^^^start_time |int |1709768000 |The UNIX timestamp at which the redemption period starts, if type == 'ABSOLUTE'. | ^^^end_time |int |1709754340 |The UNIX timestamp at which the redemption period ends, if type == 'ABSOLUTE'. | ^^^relative_time |int |4 |The number of days after coupon claim time for which a coupon is valid to be redeemed, type = 'RELATIVE'. | ^^display_channels |[]string |["SHOPPING_CENTER"]

|The channels in which the coupons can be displayed or distributed:

• ALL: All channels.
• SHOPPING_CENTER: Only in TikTok Shop shopping center.
• CHAT: Only in TT chat.
• LIVE: Only in TT live.
• PRIVATE: For promotion code. TikTok users won't know the codes until you show them.
• VIDEO: Only in short videos.
• SHOWCASE: Only in showcases. | ^^promo_code |string |TTS12345 |Promotion code. The string contains only Unicode letters or digits. The length of the string is in the range of [6, 12]. | ^^target_buyer_segment |string |NEW |The target buyer segment of the coupon. Possible enumerations are:
• ALL: May be discovered and claimed by all TTS buyers.
• NEW:Customers who have never purchased from your shop.
• REPEAT_CUSTOMERS: People who have previously placed orders in your shop and made another purchase within certain days(30 days for non-US and 90 days for US).
• RECENT_CUSTOMERS: People who have made their first purchase in your shop in the past certain days(30 days for non-US and 90 days for US).
• FREQUENT_CUSTOMERS: Customers with more than 1 purchase within the last 90 days.
• LAPSED_CUSTOMERS: Customers with at least 1 purchase in the past 365 days but no purchases within the last certain days(90 days for non-US and 30 days for US).
• NEW_FOLLOWERS: People who started following the TikTok account of your shop in the past 30 days.
• EXISTING_ACTIVE_FOLLOWERS: People who followed the TikTok account of your shop and engaged with your shop through LIVE, short videos or product cards in the past 30 days. | ^^usage_limits |object | |Limitations for the use of the coupons. | ^^^single_buyer_claim_limit |int |30 |The number of times a single buyer can claim the coupon. | ^^^total_claim_limit |int |1000 |The total number of claims allowed for the coupon across all buyers. | ^^^redemption_limit |int |1000 |The number of times that a claimed coupon can be redeemed across all buyers. (Only available in ID, MY, PH, TH, SG, VN regions.) | ^^usage_stats |object | |Usage statistics | ^^^claimed_count |int |5 |The number of times that the coupon has been claimed. | ^^^redeemed_count |int |0 |The number of times that a coupon has been redeemed (i.e. applied to an order). | ^^discount |object | |The coupon discount configuration, including type, reduction_amount, percentage, and max_discount. | ^^^type |string |AMOUNT_OFF |The type of discount offered by the coupon. Possible enumerations are:
• AMOUNT_OFF: Reduces the final price of the item by the specified reduction_amount
• PERCENT_OFF: Reduces the final price by the specified percentage. | ^^^reduction_amount |object | |Will appear when type == 'AMOUNT_OFF'. | ^^^^amount |string |30.5 |Monetary value of an AMOUNT_OFF discount. | ^^^^currency |string |USD |Currency of the discount amount. | ^^^percentage |string |30 |The discount offered by the coupon, in percentage points. Will appear when type == 'PERCENT_OFF'. | ^^^max_discount |object | |Optional monetary upper limit of the total discount amount when type == "PERCENT_OFF". | ^^^^amount |string |40 |Monetary value of the max_discount. | ^^^^currency |string |USD |Currency of the max_discount. | ^^threshold |object | |Optional minimum purchase criteria that must be met in order to receive the coupon's discount. | ^^^type |string |MIN_SPEND |The type of purchase criteria. Possible enumerations are:
• NONE: No minimum purchase criteria.
• MIN_SPEND: Buyer must meet or exceed the minimum spend criteria with eligible products. | ^^^min_spend |object |MIN_SPEND |When threshold.type == 'MIN_SPEND', a customer must purchase products from the range defined by product_scope with a monetary amount greater than or equal to this value, or the customer cannot use the coupon. | ^^^^amount |string |30 |Monetary value of the min_spend. | ^^^^currency |string |USD |Currency of the min_spend threshold. | ^^product_scope |string |FULL_SHOP |The range of the products which the coupon applies to. The possible enumerations are:
• FULL_SHOP: All products sold in the shop are eligible for the coupon.
• SPECIFIC_PRODUCTS: Only specified products are eligible for the coupon. The list of specified products are returned in the response of the get_coupon API. | ^^product_ids |[]string |["1729581162206365900"] |The IDs of the eligible products when product_scope == 'SPECIFIC_PRODUCTS'. | ^^seller_tnc |string |terms & conditions: xxx |Custom terms & conditions optionally uploaded by the seller when configuring the coupon. | ^^creation_source |string |SELLER_CENTER |The system where the coupon is created:
• SELLER_CENTER: Created via the Promotions section of TikTok Seller Center.
• SELLER_APP: Created via the TikTok Seller Mobile App.
• TTS_CRM: Created via the TikTok Shop CRM. | ^^live_tasks |[]object | |The tasks which the shopper must fulfill before claiming the coupon distributed in TikTok live. Only exists for LIVE coupons in the US and the UK. | ^^^type |string |FOLLOW_HOST |Possible enumerations:
• NONE: Any shopper in the LIVE room may claim the coupon.
• FOLLOW_HOST: Shoppers must follow the LIVE host before being able to claim the coupon.
• WATCH_FOR_MIN_TIME: Shoppers must watch the LIVE for the time specified by min_watch_time before being able to claim the coupon. | ^^^min_watch_time |string |60 |Number of seconds for which the shopper must watch the LIVE in order to claim the coupon. |

{"code":0,"data":{"coupon":{"id":"7342461823095965461","title":"Coupon202407","display_type":"CHAT\n\n\n","status":"NOT_START\n\n\n\n","create_time":1661756811000,"update_time":1661756811000,"claim_duration":{"start_time":1709568000,"end_time":1709654340},"redemption_duration":{"type":"ABSOLUTE","start_time":1709768000,"end_time":1709754340,"relative_time":4},"display_channels":["SHOPPING_CENTER"],"promo_code":"TTS12345","target_buyer_segment":"NEW\n","usage_limits":{"single_buyer_claim_limit":30,"total_claim_limit":1000,"redemption_limit":1000},"usage_stats":{"claimed_count":5,"redeemed_count":0},"discount":{"type":"AMOUNT_OFF","reduction_amount":{"amount":"30.5","currency":"USD"},"percentage":"30","max_discount":{"amount":"40","currency":"USD"}},"threshold":{"type":"MIN_SPEND","min_spend":{"amount":"30","currency":"USD"}},"product_scope":"FULL_SHOP","product_ids":["1729581162206365900"],"seller_tnc":"terms \u0026 conditions: xxx","creation_source":"SELLER_CENTER","live_tasks":[{"type":"FOLLOW_HOST","min_watch_time":"60"}]}},"message":"Success","request_id":"202203070749000101890810281E8C70B7"}

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