Update Promotion Activity Products

PUT

/promotion/202309/activities/{activity_id}/products

Use this API as follows:

• For a FIXED_PRICE, DIRECT_DISCOUNT, or FLASHSALE activity with PRODUCT or VARIATION scope, provide a non-empty products array. For VARIATION scope, add or update SKUs in each product’s skus array.
• For a PRODUCT-scoped SHIPPING_DISCOUNT or GIFT_WITH_PURCHASE activity, provide a non-empty products array. A SHOP-scoped shipping-discount activity is not supported by this operation, and this operation does not document nested-SKU updates for shipping-discount or Gift With Purchase.
• For a PRODUCT-scoped BUY_MORE_SAVE_MORE or BUY_X_GET_Y activity, products can be omitted or empty when the request updates only benefit-product relations.
• For a SHOP-scoped BUY_MORE_SAVE_MORE or BUY_X_GET_Y activity, omit products or pass an empty array; use benefit_product_ids or exclude_product_ids for the applicable relation update. For an ongoing flash deal, you can add products or SKUs, but you cannot change the price or purchase limits of products or SKUs already in the activity. To remove products or SKUs, use Remove Activity Product.

Authorizations

• accessToken

Parameters

Path Parameters

activity_id

required

string

The unique identifier of the promotion activity.

Query Parameters

shop_cipher

required

string

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

Request Body^required

Media typeapplication/json

object

products

The items to add to the list or the existing items in the list of promotion activity to edit. The length must not exceed 300.

Array<object>

object

id

required

TikTok Shop product ID

string

activity_price_amount

Deal price in the product’s currency. Specify this field when product_level==PRODUCT and activity_type is FIXED_PRICE or FLASHSALE. Do not specify it when activity_type==DIRECT_DISCOUNT or when product_level==VARIATION.

string

discount

Discount value. If the product is 10% off, the value is 10. You must specify the value when product_level==PRODUCT and activity_type==DIRECT_DISCOUNT; and you must not specify it when it’s not.

string

quantity_limit

required

The quantity limit of the products involved in the activity. The range is [1, 99], or you can use -1 for unlimited. If you are updating the value of an existing product, the value cannot be less than the current value. When product_level==VARIATION, you must specify -1.

integer format: int64

quantity_per_user

required

Limit of product purchase per buyer. The range is [1, 99], or you can use -1 for unlimited. If you are updating the value of an existing product, the value cannot be less than the current value. When product_level==VARIATION, you must specify -1.

integer format: int64

skus

The SKUs to add to the list or to edit. The number of the SKUs across all products must not exceed 300 in an API call. For a product-discount or flash-deal activity with product_level==VARIATION, every product must contain at least one SKU. For those activity types with product_level==PRODUCT, specify [].

Array<object>

object

id

required

SKU ID

string

activity_price_amount

Deal price in the SKU’s currency. Specify this field when product_level==VARIATION and activity_type is FIXED_PRICE or FLASHSALE. Do not specify it when activity_type==DIRECT_DISCOUNT.

string

discount

Discount value. If the SKU is 10% off, the value is 10. You must specify this value when product_level==VARIATION and activity_type==DIRECT_DISCOUNT. Do not specify it when activity_type is FIXED_PRICE or FLASHSALE.

string

quantity_limit

required

The quantity limit of the SKU involved in the activity. The range is [1, 99], or you can use -1 for unlimited. If you are updating the value of an existing SKU, the value cannot be decreased.

integer format: int64

quantity_per_user

required

Limit of SKU purchase per buyer. The range is [1, 99], or you can use -1 for unlimited. If you are updating the value of an existing SKU, the value cannot be decreased.

integer format: int64

activity_id

required

A unique ID that identifies activities. You cannot update the products in DEACTIVATED or EXPIRED activities.

string

benefit_product_ids

IDs of benefit products to add to or update in a Buy More Save More (BMSM) or Buy X Get Y (BXGY) activity. Omitting this field or passing an empty array leaves the activity’s existing benefit products unchanged; it does not remove them. After the update, the activity can contain at most 100 benefit products.

Array<string>

exclude_product_ids

For a SHOP-level Buy More Save More (BMSM) or Buy X Get Y (BXGY) activity, these are the IDs of products to add to or update in the exclusion list. Omitting this field or passing an empty array leaves existing excluded products unchanged; it does not remove them. Maximum: 100 IDs per request.

Array<string>

Example

{
  "products": [
    {
      "id": "7135427619356477189",
      "activity_price_amount": "4.5",
      "discount": "10",
      "quantity_limit": -1,
      "quantity_per_user": -1,
      "skus": [
        {
          "id": "7125688837187176194",
          "activity_price_amount": "6.5",
          "discount": "10",
          "quantity_limit": -1,
          "quantity_per_user": 10
        }
      ]
    }
  ],
  "activity_id": "7136104288010372865",
  "benefit_product_ids": [
    "7135427619356477189",
    "7135427619356477190"
  ],
  "exclude_product_ids": [
    "7135427619356477189",
    "7135427619356477190"
  ]
}

Responses

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 merchant.

string

update_time

The time when the response was generated, as a Unix timestamp in seconds (UTC).

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

total_count

The number of items in this request. When product_level==PRODUCT, this is the number of products. When product_level==VARIATION, this is the total number of SKUs across all products. When product_level==SHOP, this value is 0. IDs in benefit_product_ids and exclude_product_ids are not included.

integer format: int64

Example

{
  "code": 0,
  "data": {
    "activity_id": "7136104329798256386",
    "title": "DiscountPromotion",
    "update_time": 1661756811,
    "status": "DRAFT",
    "total_count": 1
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}