stable本次发布有变化全部展示
来自 TikTok Shop 官方资料快照 ·
- 当前资料结构化阅读页
- 固定快照已留存，可追溯
- 官方原文可核对
资料正文
§1 Path: /promotion/202309/activities/{activity_id}/products
#§2 Method: [PUT]
#§3 Function Description
Use this API to add the products or SKUs to the list of a product discount activity or a flash deal activity. You can also change the discounts on existing products or SKUs. To remove the products or SKUs from the list, use Remove Activity Product.
§4 Common Parameters
For common parameters, refer to How to call TikTok Shop APIs - Common Parameters
| Properties | Location | Type | Require | Sample | Properties description |
|---|---|---|---|---|---|
| shop_cipher | query | string | Y | GCP_XF90igAAAABh00qsWgtvOiGFNqyubMt3 | Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response. |
| Get by API Get Authorization Shop | |||||
| content-type | header | string | Y | application/json | Allowed type: application/json |
§5 Request Path Parameters
| Properties | Type | Require | Sample | Properties description |
|---|---|---|---|---|
| activity_id | string | Y | 7402881377634567979 | The unique identifier of the promotion activity. |
§6 Request Query Parameters
| Properties | Type | Require | Sample | Properties description |
|---|---|---|---|---|
| app_key | string | Y | 38abcd | Every single app will have a unique key. Please use the specific key assigned to your app. |
| sign | string | Y | 5361235029d141222525e303d742f9e38aea052d10896d3197ab9d6233730b8c | Signature generated by gen algorithm. When you send API requests to TTS, you must sign them so that TTS can identify the senders. |
| timestamp | int | Y | 1623812664 | Unix timestamp GMT (UTC+00:00). This timestamp is used across all API requests. Developers can use this convert to local time. |
§7 Request Body Parameters
| Properties | Type | Require | Sample | Properties description |
|---|---|---|---|---|
| products | []object | N | 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. | |
| ^id | string | Y | 7135427619356477189 | TikTok Shop product ID |
| ^activity_price_amount | string | N | 4.5 | Deal price. |
You must specify the value when product_level==PRODUCT and activity_type==FIXED_PRICE / FLASHSALE. The currency is the same between activity price and product price. | ||||
| ^discount | string | N | 10 | 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. | ||||
| ^quantity_limit | int | Y | -1 | 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. | ||||
| ^quantity_per_user | int | Y | -1 | 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. | ||||
| ^skus | []object | N | 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. | |
You must specify the value to [] when product_level==PRODUCT. | ||||
| ^^id | string | Y | 7125688837187176194 | SKU ID |
| ^^activity_price_amount | string | N | 6.5 | Deal price. |
You must specify the value when product_level==VARIATION and activity_type==FIXED_PRICE / FLASHSALE. The currency of activity price is the same as that of SKU price. | ||||
| ^^discount | string | N | 10 | Discount value. If the SKU is 10% off, the value is 10. |
You must specify the value when product_level==VARIATION and activity_type==DIRECT_DISCOUNT. | ||||
| ^^quantity_limit | int | Y | -1 | 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. |
| ^^quantity_per_user | int | Y | 10 | 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. |
| activity_id | string | Y | 7136104288010372865 | A unique ID that identifies activities. |
You cannot update the products in DEACTIVATED or EXPIRED activities. | ||||
| benefit_product_ids | []string | N | ["7135427619356477189","7135427619356477190"] | TikTokShop product ID list. |
| exclude_product_ids | []string | N | ["7135427619356477189","7135427619356477190"] | IDs of the BXGY exclude products to remove. |
| Max count: 100. |
§8 Request Sample
Query
https://open-api.tiktokglobalshop.com/promotion/202309/activities/7402881377634567979/products?app_key=123abc&sign=5361235029d141222525e303d742f9e38aea052d10896d3197ab9d6233730b8c×tamp=1625484268&shop_cipher=ROW_RHkDDABBAAB8tKAVoAqsMTjsQZFLyNfY
Body
{"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"]}
§9 Response Parameters
| Properties | Type | Sample | Properties description |
|---|---|---|---|
| code | int | 0 | The success or failure status code returned in API response. |
| message | string | Success | The success or failure messages returned in API response. Reasons of failure will be described in the message. |
| request_id | string | 202203070749000101890810281E8C70B7 | Request log |
| data | object | Specific return information | |
| ^activity_id | string | 7136104329798256386 | A unique ID that identifies different activities. |
| ^title | string | DiscountPromotion | Activity name set by the merchant. |
| ^update_time | int | 1661756811 | Latest update time. UNIX timestamp. |
| ^status | string | DRAFT | 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. | ^total_count |int |1 |The number of items in this request. When
product_level==PRODUCT, it's the number of products; whenproduct_level==VARIATION, it's the number of SKUs across products. |
§10 Response Sample
{"code":0,"data":{"activity_id":"7136104329798256386","title":"DiscountPromotion","update_time":1661756811,"status":"DRAFT","total_count":1},"message":"Success","request_id":"202203070749000101890810281E8C70B7"}
§11 Error Code
For common error codes, refer to How to call TikTok Shop APIs - Common Error Code
| Code | Message |
|---|---|
| 17011102 | Promotion title cannot be a duplicate. |
| 17027107 | Internal system error, please try again later. |
| 17029001 | Invalid parameters |
| 17029009 | Activity does not exist |
| 17029010 | Activity is deactivated |
| 17029012 | Not allowed to update expired activities |
| 17029013 | sku must be [] for activities of which product_level==PRODUCT. |
| 17029014 | The value of quantity_per_user is out of range. |
| 17029015 | When product_level==VARIATION, the value of quantity_limit must be -1. |
| 17029016 | Invalid SKU ID. |
| 17029017 | You are specifying products not in your shop. |
| 17029018 | The provided SKU quantity is greater than the available stock. |
| 17029019 | The provided product quantity is greater than the available stock. |
| 17029020 | Product discount exceeds limit. The limit varies based on products and regions. |
| 17029021 | SKU discount exceeds limit. The limit varies based on products and regions. |
| 17029022 | The product or SKU cannot be in two ONGOING or NOT_START activities at the same time. |
| 17029025 | The quantity of the products or the SKUs included in the activity exceeds 10000. |
| 17029026 | Invalid SellerID |
| 17029028 | You are specifying activities not in your shop. |
| 17029029 | You are incorrectly specifying activity_price_amount instead of discount when activity_type==DIRECT_DISCOUNT and product_level==PRODUCT. |
| 17029030 | You are incorrectly specifying discount instead of activity_price_amount when activity_type==FIXED_PRICE / FLASHSALE and product_level==PRODUCT. |
| 17029031 | You are incorrectly specifying activity_price_amount instead of discount when activity_type==DIRECT_DISCOUNT and product_level==VARIATION. |
| 17029032 | You are incorrectly specifying discount instead of activity_price_amount when activity_type==FIXED_PRICE / FLASHSALE and product_level==VARIATION. |
| 17029033 | products is empty. |
| 17029034 | activity_price_amount is invalid. |
| 17029037 | skus is empty when product_level==VARIATION. |
| 17029038 | When product_level==VARIATION, you must not specify product.activity_price_amount and product.discount. |
| 17029039 | Duplicate product ID. |
| 17029040 | Duplicate SKU ID. |
| 17029041 | You must specify product.discount when activity_type==DIRECT_DISCOUNT and product_level==PRODUCT. |
| 17029042 | You must specify product.activity_price_amount when activity_type==FIXED_PRICE / FLASHSALE and product_level==PRODUCT. |
| 17029043 | You must specify sku.discount when activity_type==DIRECT_DISCOUNT and product_level==VARIATION. |
| 17029044 | You must specify sku.activity_price_amount when activity_type==FIXED_PRICE / FLASHSALE and product_level==VARIATION. |
| 17029045 | Duplicated RequestSerialNo. |
| 17029046 | Number of items per request exceeds the limit. |
| 17029047 | An ONGOING flash sale product cannot be updated. |
| 17029048 | An ONGOING flash sale SKU cannot be updated. |
| 17029049 | ActivityVersion is not supported. |
| 17029050 | The value of quantity_limit and quantity_per_user must be -1 or in the range of [1, 99]. |
| 17029051 | Product ID not found. |
| 17029053 | The SKU ID does not match the product ID. |
| 17029054 | Please limit the request frequency. |
| 17029055 | Request Timeout |
| 17029056 | Invalid product status. |
| 17029058 | Unable to decrease buyer/num PurchaseLimit. |
| 17029060 | The Categories of products is invalid |
| 17029062 | Discount is below the limit, please confirm. |
| 17029063 | SKU discount is below the limit, please confirm. |
| 17029064 | Product is non-sellable. |
| 17029065 | Target quota is less than the initial quota. |
| 17029066 | Limit info cannot be changed or modified. |
| 17029067 | Auction products are not eligible for promotions. |
| 17029069 | Access denied. This activity does not belong to this shop and therefore cannot be modified. |
| 17029074 | Eligible products and the gift products must not be the same product. |
| 17029079 | Product is already assigned in another conflicting promotion. |
| 17029103 | Partial of products have already been applied to another conflict promotion during the selected period. |
| 17029104 | The product(s) selected have already been applied to another buy more save more promotion during the selected period. To proceed, edit the product list or change the promotion period. |
| 17029113 | The number of products will exceed the maximum number of the promotion. |
| 36009003 | Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support. |