Skip to content
TikTok Shop Partner API

Update Promotion Activity

PUT
/promotion/202309/activities/{activity_id}

Update an existing promotion activity. The stored activity type determines which request fields are processed:

  • For fixed-price, direct-discount, and flash-sale activities, update title, begin_time, and end_time; the other type-specific fields are not processed by this update path.
  • For a shipping-discount activity, provide discount.shipping_discount; use duration_type to choose a scheduled or indefinite activity.
  • For a Buy More Save More (BMSM) or Buy X Get Y (BXGY) activity, set duration_type to NORMAL, set product_level to PRODUCT or SHOP, provide exactly one participation_limit entry, and provide the matching discount object.
  • For a Gift With Purchase (GWP) activity, set duration_type to NORMAL, set product_level to PRODUCT, provide exactly one participation_limit entry, and provide discount.gift_discount. Fixed-price, direct-discount, flash-sale, BMSM, BXGY, and GWP activities cannot be updated after they are deactivated or expired. For those activity types, an upcoming activity with a normal schedule requires a future begin_time, while an ongoing activity must keep its existing begin_time. An ongoing BMSM or BXGY activity must also keep its existing first-tier threshold value, threshold type, discount type, product scope, participation limit, and target-user setting.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
activity_id
required
string

The unique identifier of the promotion activity.

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

Activity name. The name must be unique. Maximum length: 50 Unicode characters for a flash-sale activity; 50 characters for a shipping-discount activity; 100 Unicode characters for a fixed-price, direct-discount, BMSM, BXGY, or GWP activity.

string
duration_type

The activity schedule mode.

  • For BMSM, BXGY, and GWP activities, set this field to NORMAL and provide the scheduled begin_time and end_time.
  • For a shipping-discount activity, use NORMAL for a scheduled activity or INDEFINITE for an activity without a scheduled end. When this field is omitted for a shipping-discount update, it defaults to NORMAL. For INDEFINITE, set both begin_time and end_time to 0.
  • This field is not processed when updating a fixed-price, direct-discount, or flash-sale activity.
string
begin_time
required

Activity start time as a Unix timestamp in seconds. For an INDEFINITE shipping-discount activity, set this field to 0. For a fixed-price, direct-discount, flash-sale, BMSM, BXGY, or GWP activity with a normal schedule, use a future time when the activity is upcoming; if it is ongoing, use its existing start time because that value cannot be changed.

integer format: int64
end_time
required

Activity end time as a Unix timestamp in seconds. For an INDEFINITE shipping-discount activity, set this field to 0. For a normal-schedule fixed-price, direct-discount, flash-sale, BMSM, BXGY, or GWP update, end_time must be at least 600 seconds after begin_time.

integer format: int64
product_level

The promotion’s product scope. You must provide this field when updating a BMSM, BXGY, GWP, or shipping-discount activity.

  • PRODUCT: Applies to a product and all of its SKUs. Use this value for GWP; BMSM, BXGY, and shipping-discount also support it.
  • VARIATION: Applies only to specified SKUs. It is not supported for BMSM, BXGY, GWP, or shipping-discount updates.
  • SHOP: Applies to all products in the shop. It is supported for BMSM, BXGY, and shipping-discount, but not GWP. This field is not processed for fixed-price, direct-discount, or flash-sale updates. For an ongoing BMSM or BXGY activity, keep its existing PRODUCT or SHOP scope.
string
participation_limit

The buyer participation limit. For BMSM, BXGY, and GWP updates, provide exactly one entry. If a BMSM or BXGY activity is ongoing, keep its existing participation limit unchanged.

Array<object>
object
type
required

Determines whether the promotion limits how many orders each buyer can receive the benefit from.

  • BUYER_NO_LIMIT: Buyers can receive the benefit across multiple orders.
  • BUYER_LIMIT_ONLY_ONE: Each buyer can receive the benefit for no more than one order.
string
discount

Discount information.

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

The promotion’s target-user configuration. For an ongoing BMSM or BXGY activity, keep the existing target-user setting unchanged and include that existing value in the request.

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

Determines whether a shipping-discount activity supports auction products. This field is not processed for other activity types. Possible values:

  • ALL: Supports both standard and auction products.
  • EXCLUDE_AUCTION: Excludes auction products. When omitted for a shipping-discount update, defaults to ALL.
string
Allowed values: ALL EXCLUDE_AUCTION
Example
{
  "title": "BlackFridayDiscount",
  "duration_type": "NORMAL",
  "begin_time": 1661756811,
  "end_time": 1661856811,
  "product_level": "PRODUCT",
  "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

A unique ID that identifies different activities.

string
title

Activity name set by the seller. Returned on successful fixed-price, direct-discount, flash-sale, BMSM, GWP, and BXGY updates. Not returned on successful shipping-discount updates.

string
update_time

Last update time as a Unix timestamp in seconds.

integer format: int64
Example
{
  "code": 0,
  "data": {
    "activity_id": "7136104329798256386",
    "title": "BlackFridayDiscount",
    "update_time": 1661756811
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}
DocsSDKsAPI Reference

Start here

Getting StartedConceptsAuthorizationWebhooksErrors

SDKs

Choose an SDK

OpenAPI

The spec