Skip to content
TikTok Shop Partner API

Search Coupon List

POST
/promotion/202406/coupons/search

Use this API to search coupons. Supported coupon creation sources include TikTok Shop Seller Center, the TikTok Seller App, and TikTok Shop CRM. Different supplied filters are combined with AND. Within status or display_type, multiple values are combined with OR. title_keyword performs phrase-prefix matching against the coupon title. For full details about a specific coupon, use the Get Coupon API.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
shop_cipher
required
string

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

page_token
string

Page cursor. Omitting this parameter will return the first page of results.

page_size
integer format: int64

The number of coupons returned in one page of results. The range is [1, 100], with a default value of 50.

Request Body

Section titled “Request Body”
Media typeapplication/json
object
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.
Array<string>
title_keyword

Keywords in coupon titles to search for. The UTF-8 byte length must be from 1 to 100. Fuzzy matching is not supported.

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.
Array<string>
Example
{
  "status": [
    "ONGOING"
  ],
  "title_keyword": "Coupon123",
  "display_type": [
    "CHAT"
  ]
}

Responses

Section titled “Responses”

200

Section titled “200”

Success

Media typeapplication/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
total_count

Total number of coupon records matching the supplied filters. This value can be greater than the number of entries in coupons.

integer format: int64
next_page_token

Cursor for the next page. If this field is present and non-empty, pass its value as page_token in the next request. Stop pagination when this field is absent or empty.

string
coupons

The list of coupons matching the search criteria.

Array<object>
object
id

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
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
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
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
Example
{
  "code": 0,
  "data": {
    "total_count": 20,
    "next_page_token": "1661756811000",
    "coupons": [
      {
        "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": 1709654340,
          "end_time": 1709754340,
          "relative_time": 4
        },
        "promo_code": "TTS12345",
        "target_buyer_segment": "NEW",
        "usage_limits": {
          "single_buyer_claim_limit": 30,
          "total_claim_limit": 1000,
          "redemption_limit": 1000
        },
        "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",
        "creation_source": "SELLER_CENTER"
      }
    ]
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}
DocsSDKsAPI Reference

Start here

Getting StartedConceptsAuthorizationWebhooksErrors

SDKs

Choose an SDK

OpenAPI

The spec