Skip to content
TikTok Shop Partner API

Create Promotion Activity

POST
/promotion/202309/activities

Create a fixed-price, percentage-off, flash sale, shipping-discount, Buy More Save More, Gift With Purchase, or Buy X Get Y promotion activity. Coupons cannot be created with this API; create them in Seller Center or the seller app. To update the products or SKUs included in the activity, use Update Activity Product.

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.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
title
required

Unique name across all your activities. Maximum length: 50 characters for FLASHSALE and SHIPPING_DISCOUNT; 100 characters for FIXED_PRICE, DIRECT_DISCOUNT, BUY_MORE_SAVE_MORE, BUY_X_GET_Y, and GIFT_WITH_PURCHASE.

string
activity_type
required

The type of promotion activity. 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
product_level
required

The product scope of the activity. Possible values:

  • PRODUCT: Apply the promotion at the product (SPU) level to all SKUs in each selected product.
  • VARIATION: Apply the promotion only to selected SKUs.
  • SHOP: Apply the promotion to all products in the shop.

Activity-specific constraints:

  • FIXED_PRICE, DIRECT_DISCOUNT, and FLASHSALE support PRODUCT or VARIATION.
  • SHIPPING_DISCOUNT does not support VARIATION.
  • BUY_MORE_SAVE_MORE and BUY_X_GET_Y support PRODUCT or SHOP.
  • GIFT_WITH_PURCHASE requires PRODUCT.

To set the products or SKUs covered by the activity, use Update Activity Product.

string
Allowed values: PRODUCT VARIATION SHOP
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
required

Activity start time. UNIX timestamp. The value must be greater than the value of the current time.

integer format: int64
end_time
required

Activity end time as a Unix timestamp in seconds. For NORMAL FIXED_PRICE, DIRECT_DISCOUNT, FLASHSALE, BUY_MORE_SAVE_MORE, BUY_X_GET_Y, and GIFT_WITH_PURCHASE activities, it must be at least 600 seconds after begin_time. For a NORMAL shipping-discount activity, provide a positive value.

integer format: int64
participation_limit

Buyer participation-limit settings. For BUY_MORE_SAVE_MORE, BUY_X_GET_Y, and GIFT_WITH_PURCHASE, provide exactly one entry.

Array<object>
object
type
required

Determines whether each buyer can receive the activity benefit more than once. Possible values:

  • BUYER_NO_LIMIT: A buyer can benefit from this activity across multiple orders.
  • BUYER_LIMIT_ONLY_ONE: A buyer can benefit from this activity for no more than one order.
string
Allowed values: BUYER_NO_LIMIT BUYER_LIMIT_ONLY_ONE
discount

Discount configuration. For SHIPPING_DISCOUNT, provide shipping_discount; for BUY_MORE_SAVE_MORE, provide bmsm_discount; for GIFT_WITH_PURCHASE, provide gift_discount; and for BUY_X_GET_Y, provide bxgy_discount. This field is not used for FIXED_PRICE, DIRECT_DISCOUNT, or FLASHSALE.

object
shipping_discount

Configurations for the shipping discount, including purchase criteria, discount value, shipping method, inventory type, and area scope.

object
threshold_type
required

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 of the discount, based on threshold_type, for example, 3. Determined by the user.

  • When threshold_type==NO_THRESHOLD, this value is not required.
  • 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
type
required

The shipping benefit type.

  • FREE_SHIPPING: Reduce the buyer’s shipping fee to zero.
  • DISCOUNT_SHIPPING_FEE: Reduce the buyer’s shipping fee by up to the amount specified in shipping_discount.value.
string
value

The shipping discount value determined by type.

  • When type==FREE_SHIPPING, omit this value.
  • When type==DISCOUNT_SHIPPING_FEE, enter the maximum amount deducted from the buyer’s shipping fee in local currency, with at most 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
required

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

object
type
required

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 Buy More Save More tiers. Provide one or two tiers. threshold_type and type must be the same across all tiers.

Array<object>
object
tier
required

tier uses 1-based indexing: the first and second tiers are 1 and 2, not 0 and 1. For each subsequent tier, both threshold_value and value must be greater than those of the previous tier. For example, if tier 1 has threshold_value 20 and value 15, tier 2 must have a threshold_value greater than 20 and a value greater than 15.

integer format: int64
threshold_type
required

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
required

The purchase threshold for this tier.

  • When threshold_type==MINIMAL_ITEM_QUANTITY, enter a positive integer.
  • When threshold_type==MINIMAL_ORDER_AMOUNT, enter a positive amount in local currency, with at most two decimal places.
string
type
required

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
required

The discount value.

  • When type==PERCENTAGE_OFF, enter a positive integer percentage.
  • When type==AMOUNT_OFF, enter a positive amount in local currency, with at most 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
required

The receiving type of gift. Currently only one type is supported:

  • ALL_RECEIVE: All gifts configured in the promotion can be collected.
string
gift_infos
required

Gift With Purchase tier configurations. Provide at least one tier. A maximum of two tiers is permitted in SEA and the UK, while only one tier is permitted in the US. threshold_type must be the same across all tiers.

Array<object>
object
tier
required

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
required

The 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
required

The purchase threshold for the gift, determined by threshold_type.

  • When threshold_type==MINIMAL_ITEM_QUANTITY, enter a positive integer number of eligible products.
  • When threshold_type==MINIMAL_ORDER_AMOUNT, enter a positive eligible-product subtotal in local currency, with at most two decimal places.
string
gift_details
required

The gift SKUs for this tier. Across all tiers, provide at least one gift SKU in total, and do not repeat the same sku_id anywhere in the activity. For a MINIMAL_ITEM_QUANTITY tier, this list must not be empty.

Array<object>
object
product_id
required

TikTok Shop product id of gift.

string
sku_id
required

TikTok Shop sku id of gift.

string
total_claim_limit
required

The total claim limit for the gift SKU in this activity. Enter an integer from 1 to 99999.

string
bxgy_discount

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

object
threshold_type
required

The purchase criterion. Possible values:

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

The purchase threshold determined by threshold_type.

  • When threshold_type==MINIMAL_ITEM_QUANTITY, enter a positive integer no greater than 10.
  • When threshold_type==MINIMAL_ORDER_AMOUNT, enter a positive eligible-product subtotal in local currency, with at most two decimal places.
string
discount_type
required

The type of benefit. Possible values:

  • PERCENTAGE_OFF: Apply the percentage specified by discount_value to eligible products.
  • FREE: Provide the configured quantity of eligible products for free.
  • AMOUNT_OFF_EACH: Deduct the local-currency amount specified by discount_value from each eligible product.
string
Allowed values: PERCENTAGE_OFF FREE AMOUNT_OFF_EACH
discount_value
required

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
required

The quantity of item Y awarded each time the Buy X Get Y benefit applies. Enter a positive integer no greater than 20.

string
benefit_max_applicable_times

Optional. The maximum number of times the Buy X Get Y benefit can be applied in one order. Enter a positive integer no greater than 50.

string
target_user_info

Target-audience configuration for BUY_MORE_SAVE_MORE, BUY_X_GET_Y, and GIFT_WITH_PURCHASE activities. If omitted, the activity targets ALL_USER.

object
user_type

Possible enumerations are: ALL_USER SHOP_NEW_CUSTOMER SHOP_EXISTING_CUSTOMER SHOP_REPEAT_CUSTOMER

string
Allowed values: ALL_USER SHOP_NEW_CUSTOMER SHOP_EXISTING_CUSTOMER SHOP_REPEAT_CUSTOMER
auction_support_type

For SHIPPING_DISCOUNT activities, determines whether auction products are supported. Possible values:

  • ALL: Support both regular and auction products.
  • EXCLUDE_AUCTION: Exclude auction products. Default: ALL.
string
Allowed values: ALL EXCLUDE_AUCTION
Example
{
  "title": "DiscountEvent0829",
  "activity_type": "FIXED_PRICE",
  "product_level": "PRODUCT",
  "duration_type": "NORMAL",
  "begin_time": 1661756811,
  "end_time": 1661856811,
  "participation_limit": [
    {
      "type": "BUYER_NO_LIMIT"
    }
  ],
  "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": "5",
      "benefit_max_applicable_quantity": "5",
      "benefit_max_applicable_times": "5"
    }
  },
  "target_user_info": {
    "user_type": "ALL_USER"
  },
  "auction_support_type": "ALL"
}

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

On success, the ID of the created activity. Use it as activity_id when adding products or SKUs with Update Activity Product.

string
create_time

The time when the activity was created.

integer format: int64
update_time

The time when the activity was last updated.

integer format: int64
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
Example
{
  "code": 0,
  "data": {
    "activity_id": "7136104329798256386",
    "create_time": 1661756811,
    "update_time": 1661756811,
    "status": "ONGOING"
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}
DocsSDKsAPI Reference

Start here

Getting StartedConceptsAuthorizationWebhooksErrors

SDKs

Choose an SDK

OpenAPI

The spec