Get Coupon

GET

/promotion/202406/coupons/{coupon_id}

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

Authorizations

accessToken

Parameters

Path Parameters

coupon_id

required

string

The unique identifier of the coupon.

Query Parameters

shop_cipher

required

string

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

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

coupon

The coupon detail object, including identity, display settings, status, claim and redemption durations, discount, threshold, product scope, usage limits, usage stats, and live tasks.

object

A unique ID that identifies different coupons.

string

title

Seller-specified title of the coupon.

string

display_type

The display type of coupons. 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.

string

status

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.

string

create_time

The UNIX timestamp, in milliseconds, when the coupon was created.

integer format: int64

update_time

The UNIX timestamp, in milliseconds, when the coupon was last updated.

integer format: int64

claim_duration

Claimable period of the coupon.

object

start_time

The UNIX timestamp, in seconds, from which a shopper can claim the coupon.

integer format: int64

end_time

The UNIX timestamp, in seconds, after which a shopper can no longer claim the coupon.

integer format: int64

redemption_duration

Period during which the coupon can be redeemed (i.e. applied to an order).

object

type

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.

string

start_time

The UNIX timestamp, in seconds, at which the redemption period starts, if type == 'ABSOLUTE'.

integer format: int64

end_time

The UNIX timestamp, in seconds, at which the redemption period ends, if type == 'ABSOLUTE'.

integer format: int64

relative_time

The number of days after coupon claim time for which a coupon is valid to be redeemed, type = 'RELATIVE'.

integer format: int64

display_channels

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.
PRIVATE_WITH_ALLOW: A private display-channel value returned for a regular coupon.
VIDEO: Only in short videos.
SHOWCASE: Only in showcases.

Array<string>

promo_code

Promotion code. Returned only when display_type == 'PROMO_CODE'. The string contains only Unicode letters or digits. The length of the string is in the range of [6, 12].

string

target_buyer_segment

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.

string

Allowed values: ALL NEW REPEAT_CUSTOMERS RECENT_CUSTOMERS FREQUENT_CUSTOMERS LAPSED_CUSTOMERS NEW_FOLLOWERS EXISTING_ACTIVE_FOLLOWERS

usage_limits

Limitations for the use of the coupons.

object

single_buyer_claim_limit

The number of times a single buyer can claim the coupon.

integer format: int64

total_claim_limit

The total number of claims allowed for the coupon across all buyers.

integer format: int64

redemption_limit

The number of times that a claimed coupon can be redeemed across all buyers. (Only available in ID, MY, PH, TH, SG, VN regions.)

integer format: int64

usage_stats

Usage statistics

object

claimed_count

The number of times that the coupon has been claimed.

integer format: int64

redeemed_count

The number of times that a coupon has been redeemed (i.e. applied to an order).

integer format: int64

discount

The coupon discount configuration, including type, reduction_amount, percentage, and max_discount.

object

type

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.

string

Allowed values: AMOUNT_OFF PERCENT_OFF

reduction_amount

Will appear when type == 'AMOUNT_OFF'.

object

amount

Monetary value of an AMOUNT_OFF discount.

string

currency

Currency of the discount amount.

string

percentage

The discount offered by the coupon, in percentage points. Will appear when type == 'PERCENT_OFF'.

string

max_discount

Optional monetary upper limit of the total discount amount when type == "PERCENT_OFF".

object

amount

Monetary value of the max_discount.

string

currency

Currency of the max_discount.

string

threshold

Optional minimum purchase criteria that must be met in order to receive the coupon’s discount.

object

type

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.

string

Allowed values: NONE MIN_SPEND

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.

object

amount

Monetary value of the min_spend.

string

currency

Currency of the min_spend threshold.

string

product_scope

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.

string

Allowed values: FULL_SHOP SPECIFIC_PRODUCTS

product_ids

The IDs of the eligible products when product_scope == 'SPECIFIC_PRODUCTS'.

Array<string>

seller_tnc

Custom terms & conditions optionally uploaded by the seller when configuring the coupon.

string

creation_source

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.

string

live_tasks

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.

Array<object>

object

type

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.

string

Allowed values: NONE FOLLOW_HOST WATCH_FOR_MIN_TIME

min_watch_time

Number of seconds for which the shopper must watch the LIVE in order to claim the coupon.

string

Example

{
  "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": 1709754340,
        "end_time": 1709768000,
        "relative_time": 4
      },
      "display_channels": [
        "SHOPPING_CENTER"
      ],
      "promo_code": "TTS12345",
      "target_buyer_segment": "NEW",
      "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 & conditions: xxx",
      "creation_source": "SELLER_CENTER",
      "live_tasks": [
        {
          "type": "FOLLOW_HOST",
          "min_watch_time": "60"
        }
      ]
    }
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}

Get Coupon

Authorizations

Parameters

Path Parameters

Query Parameters

Responses

200

Example

Start here

SDKs

OpenAPI