Skip to content
TikTok Shop Partner API

Get Activity

GET
/promotion/202309/activities/{activity_id}

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

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
activity_id
required
string

Activity ID

Query Parameters

Section titled “Query Parameters”
shop_cipher
required
string

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

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
activity_id

A unique ID that identifies different activities.

string
title

Activity name (50 characters max.) The name must be unique.

string
activity_type

The activity type. Possible values:

  • FIXED_PRICE: A product discount activity with a fixed price.
  • DIRECT_DISCOUNT: A product discount activity with a percentage discount.
  • FLASHSALE: A flash sale activity.
  • SHIPPING_DISCOUNT: A shipping fee discount activity.
  • BUY_MORE_SAVE_MORE: A Buy More Save More promotion.
  • GIFT_WITH_PURCHASE: A Gift With Purchase promotion.
  • BUY_X_GET_Y: A Buy X Get Y promotion.
string
Allowed values: FIXED_PRICE DIRECT_DISCOUNT FLASHSALE SHIPPING_DISCOUNT BUY_MORE_SAVE_MORE GIFT_WITH_PURCHASE BUY_X_GET_Y
duration_type

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.
  1. INDEFINITE is only valid when activity_type is SHIPPING_DISCOUNT,
  2. If duration_type is INDEFINITE, start_time and end_time should be 0 Default: NORMAL
string
begin_time

Activity start time as a UNIX timestamp in seconds.

integer format: int64
end_time

Activity end time as a UNIX timestamp in seconds.

integer format: int64
participation_limit

The number of times a buyer can participate in the promotion.

Array<object>
object
type

Determines whether the promotion activity limits the number of times each buyer can receive its benefit. e.g.:

  • BUYER_NO_LIMIT: No limit for buyer​s. 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
string
products

Product List. Note:If FIXED_PRICE, DIRECT_DISCOUNT and FLASHSALE activity that ended more than 180 days,this field is empty.

Array<object>
object
id

TikTok Shop Product ID.

string
activity_price

Activity price.

object
amount

Activity price amount.

string
currency

Currency unit of an activity price.

string
quantity_limit

The quantity limit of the products involved in the activity. The range is [1, 99], or -1 for unlimited.

integer format: int64
quantity_per_user

Limit of product purchase per buyer. The range is [1, 99], or -1 for unlimited.

integer format: int64
discount

Discount value. If the product is 10% off, the value is 10. Available only if activity_type==DIRECT_DISCOUNT and product_level==PRODUCT.

string
skus

Available only if product_level==VARIATION.

Array<object>
object
id

TikTok Shop SKU ID.

string
discount

Discount value. If the SKU is 10% off, the value is 10. Available only if activity_type==DIRECT_DISCOUNT.

string
quantity_limit

The quantity limit of the SKU involved in the activity. The range is [1, 99], or -1 for unlimited.

integer format: int64
quantity_per_user

Limit of SKU purchase per buyer. The range is [1, 99], or -1 for unlimited.

integer format: int64
activity_price

Activity price. Available only if activity_type==FIXED_PRICE/FLASHSALE.

object
amount

Activity price amount.

string
currency

Currency unit of an activity price.

string
used_quantity

The quantity of SKU that have already taken effect in the activity.

integer format: int64
used_quantity

The quantity of products that have already taken effect in the activity.

integer format: int64
status

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.
string
Allowed values: DRAFT NOT_START ONGOING EXPIRED DEACTIVATED NOT_EFFECTIVE
create_time

Activity creation time as a UNIX timestamp in milliseconds.

integer format: int64
update_time

Activity update time as a UNIX timestamp in milliseconds.

integer format: int64
product_level

Activity product dimension, values are:

  • PRODUCT: Product level promotion activity.
  • VARIATION: SKU level promotion activity.
  • SHOP: Shop level promotion activity.
string
Allowed values: PRODUCT VARIATION SHOP
activity_commands

Applicable commands to the activity:

  • IMMUTABLE: The activity cann’t be editable or deactivated
Array<string>
discount

Type-specific discount information. This field is omitted for FIXED_PRICE, DIRECT_DISCOUNT, and FLASHSALE activities. For other supported activity types, use the corresponding nested discount object when it is returned.

object
shipping_discount

Shipping discount

object
threshold_type

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.
string
Allowed values: NO_THRESHOLD MINIMAL_ITEM_QUANTITY MINIMAL_ORDER_AMOUNT
threshold_value

The purchase threshold returned for the shipping discount, based on threshold_type.

  • When threshold_type==NO_THRESHOLD, this value is not required.
  • When threshold_type==MINIMAL_ITEM_QUANTITY, this is the number of eligible products the buyer must purchase and must be an integer.
  • When threshold_type==MINIMAL_ORDER_AMOUNT, this is the eligible-product subtotal the buyer must reach in local currency (for example, 3 units of local currency) and must have no more than two decimal places.
string
type

The type of shipping discount returned for the promotion activity.

  • FREE_SHIPPING: The buyer’s shipping charge is fully covered.
  • DISCOUNT_SHIPPING_FEE: The buyer’s shipping charge is reduced by up to the amount in value.
string
value

Value of the discount.

  • When type==FREE_SHIPPING, this value is not required.
  • 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.
string
shipping_method

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
string
inventory_type

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.
string
area_scope

The (buyer’s) geographical areas to which the promotion activity applies.

object
type

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.
string
specific_areas

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

Array<string>
bmsm_discount

Configurations related to Buy More Save More (BMSM) promotions.

object
details

Configurations for BMSM promotions. A maximum of two tiers are permitted. details.threshold_type and details.type must be the same across all tiers.

Array<object>
object
tier

tier uses 1-based indexing, i.e. the first and second tiers are counted “1, 2”, not “0, 1”. threshold_value and value for a given tier must be greater than that of the previous tier. E.g. If tier==1 has threshold_value==20 and value== 15, tier==2 must have threshold_value > 20 and value>15.

integer format: int64
threshold_type

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.
string
Allowed values: MINIMAL_ITEM_QUANTITY MINIMAL_ORDER_AMOUNT
threshold_value

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.
string
type

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.
string
Allowed values: PERCENTAGE_OFF AMOUNT_OFF
value

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.
string
gift_discount

Configurations related to Gift With Purchase (GWP) promotions. Only needs to be configured for GWP promotions.

object
gift_receiving_type

The receiving type of gift. Currently only supports one type: ALL_RECEIVE

string
gift_infos

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.

Array<object>
object
tier

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==1 has threshold_value==2, tier==2 must have threshold_value > 2.

integer format: int64
threshold_type

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.
string
Allowed values: MINIMAL_ITEM_QUANTITY MINIMAL_ORDER_AMOUNT
threshold_value

The purchase threshold value of the gift, based on threshold_type. Determined by the user.

  • When threshold_type==MINIMAL_ITEM_QUANTITY, the buyer must purchase at least the specified number of eligible products (for example, 3 eligible products). If it represents a quantity, it must be an integer.
  • When threshold_type==MINIMAL_ORDER_AMOUNT, the eligible-product subtotal must meet or exceed the specified value in local currency (for example, 3 units of local currency). If it represents an order value, it must be limited to two decimal places.
string
gift_details

Gift configurations related to Gift With Purchase (GWP) promotions.

Array<object>
object
product_id

TikTok Shop product id of gift.

string
sku_id

TikTok Shop sku ID of gift.

string
total_claim_limit

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.

string
bxgy_discount

Configurations related to Buy X Get Y (BXGY) promotions. Only needs to be configured for BXGY promotions.

object
threshold_type

The purchase criterion returned for the activity. Possible values:

  • MINIMAL_ITEM_QUANTITY: The buyer must purchase at least the specified quantity of eligible products.
  • MINIMAL_ORDER_AMOUNT: The eligible-product subtotal must reach the specified amount.
string
Allowed values: MINIMAL_ITEM_QUANTITY MINIMAL_ORDER_AMOUNT
threshold_value

The purchase threshold returned for the activity, based on threshold_type.

  • When threshold_type==MINIMAL_ITEM_QUANTITY, this is the number of eligible products the buyer must purchase and must be an integer.
  • When threshold_type==MINIMAL_ORDER_AMOUNT, this is the eligible-product subtotal the buyer must reach, in local currency.
string
discount_type

The type of discount awarded as a benefit. For PERCENTAGE_OFF and AMOUNT_OFF_EACH, the discount amount is determined by discount_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 of each eligible product.
string
Allowed values: PERCENTAGE_OFF FREE AMOUNT_OFF_EACH
discount_value

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.
string
benefit_max_applicable_quantity

The quantity of item Y in a BXGY promotion. This value must be a positive integer.

string
benefit_max_applicable_times

Optional. The maximum number of times the BXGY benefit can be applied within a single order. This value must be a positive integer.

string
target_user_info

The targeted user type of the promotion.

object
user_type

The targeted user type. Possible values:

  • ALL_USER
  • SHOP_NEW_CUSTOMER
  • SHOP_EXISTING_CUSTOMER
  • SHOP_REPEAT_CUSTOMER
  • SHOP_ABANDONED_CHECKOUTS_CUSTOMER
string
Allowed values: ALL_USER SHOP_NEW_CUSTOMER SHOP_EXISTING_CUSTOMER SHOP_REPEAT_CUSTOMER SHOP_ABANDONED_CHECKOUTS_CUSTOMER
benefit_products

Benefit products in BXGY promotions

Array<object>
object
id

TikTokShop product ID

string
auction_support_type

Whether a SHIPPING_DISCOUNT activity supports auction products. This field is omitted for other activity types and can also be omitted for a shipping-discount activity when auction-support data is unavailable. Possible values:

  • ALL: The activity supports both normal products and auction products.
  • EXCLUDE_AUCTION: The activity does not support auction products.
string
Allowed values: ALL EXCLUDE_AUCTION
Example
{
  "code": 0,
  "data": {
    "activity_id": "7136104329798256386",
    "title": "FlashSale 20230707",
    "activity_type": "FIXED_PRICE",
    "duration_type": "NORMAL",
    "begin_time": 1661756811,
    "end_time": 1661856811,
    "participation_limit": [
      {
        "type": "BUYER_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": 1789355787347,
    "update_time": 1789355865063,
    "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": "10",
        "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"
}
DocsSDKsAPI Reference

Start here

Getting StartedConceptsAuthorizationWebhooksErrors

SDKs

Choose an SDK

OpenAPI

The spec