This is an example product description.
" } ], "next_page_token": "cGFnZV9udW1iZXI9Mg==", "total_count": 1570 }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 6, "x-tts-scopes": [ "Read Affiliate Partner Campaigns" ], "x-tts-error-codes": [ { "code": "16032001", "message": "nvalid parameter Creator and Seller, please ensure Region mismatch." }, { "code": "16032005", "message": "Campaign not found" }, { "code": "16032007", "message": "Permission denied" }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-affiliate-partner-campaign-product-list-202405" } }, "/affiliate_partner/202405/campaigns/{campaign_id}/products/{product_id}/promotion_link/generate": { "post": { "operationId": "generateAffiliatePartnerCampaignProductLink", "summary": "Generate Affiliate Partner Campaign Product Link", "description": "Generates a promotion link for a product in an existing online campaign. The product must be associated with the campaign and appear in the response from Get Affiliate Partner Campaign Product List with `review_status` set to `APPROVED` or `PENDING_CLOSED`.", "tags": [ "Affiliate partner" ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "The ID of the campaign.", "schema": { "type": "string" } }, { "name": "product_id", "in": "path", "required": true, "description": "The ID of the product.", "schema": { "type": "string" } }, { "name": "category_asset_cipher", "in": "query", "required": true, "description": "The partner identifier used in API requests. Retrieve this value by using the [Get Authorized Category Assets API](https://partner.tiktokshop.com/docv2/page/666012dd609d4402cc3be995).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateAffiliatePartnerCampaignProductLinkRequest" }, "example": { "creator_commission_rate": 1000 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateAffiliatePartnerCampaignProductLinkResponse" }, "example": { "code": 0, "data": { "product_promotion_link": "https://affiliate.tiktok.com/api/v1/share/AIxvOHlaJoKO" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 6, "x-tts-scopes": [ "Manage Product Promote Links" ], "x-tts-error-codes": [ { "code": "16032001", "message": "nvalid parameter Creator and Seller, please ensure Region mismatch." }, { "code": "16032005", "message": "Campaign not found" }, { "code": "16032007", "message": "Permission denied" }, { "code": "16032008", "message": "Operation denied" }, { "code": "16032009", "message": "Product operation denied, please ensure campaign is under online status." }, { "code": "16032010", "message": "Campaign product not found" }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/generate-affiliate-partner-campaign-product-link-202405" } }, "/affiliate_partner/202405/campaigns/{campaign_id}/products/{product_id}/review": { "post": { "operationId": "reviewAffiliatePartnerCampaignProduct", "summary": "Review Affiliate Partner Campaign Product", "description": "Use this API as a TikTok Affiliate Partner to approve or reject a product submitted by a seller to a campaign. The product must be in a pending state.", "tags": [ "Affiliate partner" ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "The campaign identifier.", "schema": { "type": "string" } }, { "name": "product_id", "in": "path", "required": true, "description": "The product identifier.", "schema": { "type": "string" } }, { "name": "category_asset_cipher", "in": "query", "required": true, "description": "The partner identifier used in API requests. Retrieve this value by using the [Get Authorized Category Assets API](https://partner.tiktokshop.com/docv2/page/666012dd609d4402cc3be995).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewAffiliatePartnerCampaignProductRequest" }, "example": { "review_result": "APPROVE", "reject_reasons": [ "COMMISSION_TOO_LOW" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewAffiliatePartnerCampaignProductResponse" }, "example": { "code": 0, "data": {}, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 6, "x-tts-scopes": [ "Manage Affiliate Partner Campaign Products" ], "x-tts-error-codes": [ { "code": "16032001", "message": "nvalid parameter Creator and Seller, please ensure Region mismatch." }, { "code": "16032005", "message": "Campaign not found" }, { "code": "16032007", "message": "Permission denied" }, { "code": "16032009", "message": "Product operation denied, please ensure campaign is under online status." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/review-affiliate-partner-campaign-product-202405" } }, "/affiliate_partner/202405/campaigns/{campaign_id}/publish": { "post": { "operationId": "publishAffiliatePartnerCampaign", "summary": "Publish Affiliate Partner Campaign", "description": "This API offers the ability to publish an Affiliate Partner campaign. The campaign will be displayed to sellers after publishing.", "tags": [ "Affiliate partner" ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "The campaign identifier.", "schema": { "type": "string" } }, { "name": "category_asset_cipher", "in": "query", "required": true, "description": "The partner identifier used in API requests. Retrieve this value by using the [Get Authorized Category Assets API](https://partner.tiktokshop.com/docv2/page/666012dd609d4402cc3be995).", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishAffiliatePartnerCampaignRequest" }, "example": {} } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishAffiliatePartnerCampaignResponse" }, "example": { "code": 0, "data": {}, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 6, "x-tts-scopes": [ "Manage Affiliate Partner Campaigns" ], "x-tts-error-codes": [ { "code": "16032001", "message": "nvalid parameter Creator and Seller, please ensure Region mismatch." }, { "code": "16032005", "message": "Campaign not found" }, { "code": "16032007", "message": "Permission denied" }, { "code": "16032008", "message": "Operation denied" }, { "code": "16032011", "message": "Max campaign online count reached" } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/publish-affiliate-partner-campaign-202405" } }, "/affiliate_partner/202501/campaigns/{campaign_id}/products/performance": { "get": { "operationId": "getCampaignProductPerformanceList", "summary": "Get Campaign Product Performance List", "description": "Retrieves a paginated list of product-level performance statistics for the specified partner campaign.", "tags": [ "Affiliate partner" ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "the unique id of a campaign", "schema": { "type": "string" } }, { "name": "page_size", "in": "query", "required": false, "description": "The number of results to be returned per page. Valid range: 1-50.", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 50 } }, { "name": "page_token", "in": "query", "required": false, "description": "An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the `next_page_token` from a previous response. It is not needed for the first page.", "schema": { "type": "string" } }, { "name": "category_asset_cipher", "in": "query", "required": true, "description": "The partner identifier used in API requests. Retrieve this value by using the [Get Authorized Category Assets API](https://partner.tiktokshop.com/docv2/page/666012dd609d4402cc3be995).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCampaignProductPerformanceListResponse" }, "example": { "code": 0, "data": { "total_count": 10, "campaign_product_statistics": [ { "data_update_time": "1736204400000", "creator_sales_num": 1, "collaborated_creators_num": 0, "promoted_creator_num": 0, "sample_requested_creator_num": 0, "campaign_product_detail": { "product_id": "12344", "product_status": "PRODUCT_UNSPECIFIED", "product_name": "summer underwear soft dress summer underwear-001", "product_stock_count": "100", "total_commission_percent": "6000", "creator_commission_percent": "1000", "partner_commission_percent": "5000", "plan_commission_percent": "1400", "product_price": { "min_price": "1.00", "max_price": "3.00", "currency": "USD" }, "product_thumbnail": { "uri": "tos-useast5-i-omjb5zjo8w-tx/178e97ee3b254f9ab237ea7516828266", "url_list": [ "https://p19-oec-ttp.tiktokcdn-us.com/tos-useast5-i-omjb5zjo8w-tx/178e97ee3b254f9ab237ea7516828266~tplv-omjb5zjo8w-resize-jpeg:300:300.jpeg?from=520841845", "https://p16-oec-ttp.tiktokcdn-us.com/tos-useast5-i-omjb5zjo8w-tx/178e97ee3b254f9ab237ea7516828266~tplv-omjb5zjo8w-resize-jpeg:300:300.jpeg?from=520841845" ] }, "indicator_data": { "paid_order_num": "3", "actual_order_num": "0", "estimated_amount": "0", "actual_amount": "0", "estimated_partner_commission": "0", "actual_partner_commission": "0", "creator_sales_num": "0", "collaborated_creators_num": "0", "promoted_creator_num": "0", "sample_requested_creator_num": "0" } } } ], "next_page_token": "0" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 6, "x-tts-scopes": [ "Read Affiliate Partner Campaigns" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-campaign-product-performance-list-202501" } }, "/affiliate_partner/202505/campaigns/{campaign_id}/products/promotion_links/generate_batch": { "post": { "operationId": "generateCampaignProductPromotionLinksInBatch", "summary": "Generate Campaign Product Promotion Links in Batch", "description": "Generate promotion links for multiple products in an online campaign. For OPS or seller-initiated campaigns, use the joined campaign ID created after the partner joins the campaign, not the original campaign ID.", "tags": [ "Affiliate partner" ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "The ID of the campaign", "schema": { "type": "string" } }, { "name": "category_asset_cipher", "in": "query", "required": false, "description": "The partner identifier used in API requests. Retrieve this value by using the [Get Authorized Category Assets API](https://partner.tiktokshop.com/docv2/page/666012dd609d4402cc3be995).", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateCampaignProductPromotionLinksInBatchRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateCampaignProductPromotionLinksInBatchResponse" } } } } }, "x-tts-scenario": 6, "x-tts-scopes": [ "Read Affiliate Partner Campaigns" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/generate-campaign-product-promotion-links-in-batch-202505" } }, "/affiliate_partner/202508/campaigns/{campaign_id}/products/{product_id}/creator/{creator_temp_id}/content/statistics": { "get": { "operationId": "getAffiliateCampaignCreatorProductContentStatistics", "summary": "Get Affiliate Campaign Creator Product Content Statistics", "description": "Retrieves performance statistics for a creator's video or live-room content associated with an affiliate campaign product.", "tags": [ "Affiliate partner" ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "The campaign identifier.", "schema": { "type": "string" } }, { "name": "product_id", "in": "path", "required": true, "description": "The product identifier.", "schema": { "type": "string" } }, { "name": "creator_temp_id", "in": "path", "required": true, "description": "Creator Open ID. [More details](https://partner.tiktokshop.com/docv2/page/3obfokj6)", "schema": { "type": "string" } }, { "name": "affiliate_product_id", "in": "query", "required": true, "description": "The affiliate product identifier used to filter the returned content statistics.", "schema": { "type": "string" } }, { "name": "content_type", "in": "query", "required": false, "description": "Content type. Use `VIDEO` for video content or `LIVE_ROOM` for live-room content.", "schema": { "type": "string" } }, { "name": "category_asset_cipher", "in": "query", "required": true, "description": "The partner identifier used in API requests. Retrieve this value by using the [Get Authorized Category Assets API](https://partner.tiktokshop.com/docv2/page/666012dd609d4402cc3be995).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAffiliateCampaignCreatorProductContentStatisticsResponse" }, "example": { "code": 0, "data": { "creator_content_statistics": [ { "content_type": "VIDEO", "cover_img_url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/fa0387fa5a204dcfa44d5be75877a163~tplv-o3syd03w52-origin-webp.webp?from=3478900499", "source_url": "https://www.tiktok.com/@cbseveningnews/video/7458098283332767006?q=Victor%20Shaw%20Dies%20In%20Fire%20Rescue%20Attempt&t=1736545359958", "view_count": "1", "like_count": "1", "comment_num": "0", "paid_order_num": "0", "paid_amount": "0", "linked_tiktok_video": "http://xxx.tiktok.com/xxxx", "published_date": "2024-11-13", "content_end_date": "2024-11-13" } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 6, "x-tts-scopes": [ "Read Affiliate Partner Campaigns" ], "x-tts-error-codes": [ { "code": "16032001", "message": "nvalid parameter Creator and Seller, please ensure Region mismatch." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-affiliate-campaign-creator-product-content-statistics-202508" } }, "/affiliate_partner/202508/campaigns/{campaign_id}/products/{product_id}/creator/{creator_temp_id}/content/statistics/sample/status": { "get": { "operationId": "getAffiliateCampaignCreatorProductSampleStatus", "summary": "Get Affiliate Campaign Creator Product Sample Status", "description": "Retrieves delivery and tracking details for a creator's product sample in an affiliate campaign. The creator must have applied for a sample of the specified product before calling this API.", "tags": [ "Affiliate partner" ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "The campaign identifier.", "schema": { "type": "string" } }, { "name": "product_id", "in": "path", "required": true, "description": "The product identifier.", "schema": { "type": "string" } }, { "name": "creator_temp_id", "in": "path", "required": true, "description": "Creator Open ID. [More details](https://partner.tiktokshop.com/docv2/page/3obfokj6)", "schema": { "type": "string" } }, { "name": "category_asset_cipher", "in": "query", "required": true, "description": "The partner identifier used in API requests. Retrieve this value by using the [Get Authorized Category Assets API](https://partner.tiktokshop.com/docv2/page/666012dd609d4402cc3be995).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAffiliateCampaignCreatorProductSampleStatusResponse" }, "example": { "code": 0, "data": { "sample_status": { "shipping_provider_name": "USPS", "delivery_option": "PREMIUM_SHIPPING", "estimated_earliest_delivery_date": "1712941200", "estimated_latest_delivery_date": "1712941200", "quantity": 1, "tracking_results": [ { "tracking_event_update_date": "1712941200", "tracking_event_description": "THE_PACKAGE_HAS_BEEN_DELIVERED", "tracking_event_description_extended": "delivering" } ] } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 6, "x-tts-scopes": [ "Read Affiliate Partner Campaigns" ], "x-tts-error-codes": [ { "code": "16032001", "message": "nvalid parameter Creator and Seller, please ensure Region mismatch." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-affiliate-campaign-creator-product-sample-status-202508" } }, "/affiliate_partner/202508/campaigns/{campaign_id}/products/{product_id}/performance": { "get": { "operationId": "getCreatorPerformanceForCampaignProduct", "summary": "Get Creator Performance for Campaign Product", "description": "Returns a paginated list of creators associated with a product in an affiliate partner campaign, together with available collaboration and performance details such as commission, free-sample status, follower count, and video and live broadcast counts.", "tags": [ "Affiliate partner" ], "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "product_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page_size", "in": "query", "required": false, "description": "The number of results to be returned per page. Valid range: 1-50.", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 50 } }, { "name": "page_token", "in": "query", "required": false, "description": "An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the `next_page_token` from a previous response. It is not needed for the first page.", "schema": { "type": "string" } }, { "name": "category_asset_cipher", "in": "query", "required": true, "description": "The partner identifier used in API requests. Retrieve this value by using the [Get Authorized Category Assets API](https://partner.tiktokshop.com/docv2/page/666012dd609d4402cc3be995).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCreatorPerformanceForCampaignProductResponse" }, "example": { "code": 0, "data": { "total_creator_count": 1, "promotion_creators": [ { "paid_amount": { "currency": "USD", "amount": "3.00" }, "room_count": 1, "video_count": 1, "free_sample_status": "AWAITING_COLLECTION", "commission": "100", "effective_end_time": "1731020040687", "effective_start_time": "1731019880391", "creator": { "nick_name": "Test_Creator_E", "avatar_url": "https://p19-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/c614d3b6ba4d93b31fbda5add0802dd7~c5_1080x1080.webp?lk3s=a5d48078&nonce=6796&refresh_token=634d776ec39c2291053675f60c576515&x-expires=1736478000&x-signature=0G6NmM8H8nDRYYVN7e8QazDMRb0%3D&shp=a5d48078&shcp=9f007bb8", "follower_num": 19, "user_name": "us_lxq6213", "creator_open_id": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg" }, "affiliate_product_id": "123456789" } ], "next_page_token": "cGFnZV9udW1iZXI9Mg==" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 6, "x-tts-scopes": [ "Read Affiliate Partner Campaigns" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-creator-performance-for-campaign-product-202508" } }, "/affiliate_partner/202603/cap_order/search": { "post": { "operationId": "searchCAPAffiliateOrders", "summary": "Search CAP Affiliate Orders", "description": "Search affiliate orders for an MCN (Creator Agency Partner) within the specified or default creation-time range. When multiple request-body filters are provided, `order_id`, `product_id`, `settle_status`, and the creation-time range are combined using AND semantics, so an order must match every supplied filter.", "tags": [ "Affiliate partner" ], "parameters": [ { "name": "page_token", "in": "query", "required": false, "description": "Pagination token returned in `next_page_token` from the previous response. The token contains only the search-after sort position; it does not preserve the search filters or `page_size`. Omit this parameter for the first page. For each subsequent page, pass the returned token, provide a valid `page_size`, and resend the same partner authorization context and request-body filters used for the first page. The `page_size` value can be set independently for each page. For stable pagination, explicitly provide the same fixed `create_time_ge` and `create_time_lt` values on every request instead of relying on the rolling default time range.", "schema": { "type": "string" } }, { "name": "page_size", "in": "query", "required": true, "description": "The default is 20, it must be positive integer, the range is 1-100", "schema": { "type": "integer", "format": "int64" } }, { "name": "category_asset_cipher", "in": "query", "required": true, "description": "The partner identifier used in API requests. Retrieve this value by using the [Get Authorized Category Assets API](https://partner.tiktokshop.com/docv2/page/666012dd609d4402cc3be995).", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchCAPAffiliateOrdersRequest" }, "example": { "order_id": "576962796354307765", "product_id": "1729435310697057093", "settle_status": 1, "create_time_ge": 1791222188, "create_time_lt": 1791229388 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchCAPAffiliateOrdersResponse" }, "example": { "code": 0, "data": { "sku_orders": [ { "id": "576962796354307765", "tags": "test-01", "create_time": 1685548800, "delivery_time": 1685548800, "settle_status": "SETTLED", "sku_id": "1729478689395213981", "open_collaboration_id": "7324371012170024705", "target_collaboration_id": "7324371012170024705", "creator_username": "liuyi_id_creator1jigo", "product_name": "Black Hoodie", "product_id": "1729435310697057093", "price": { "amount": "99", "currency": "USD" }, "quantity": 1, "shop_name": "xuyann aaaaa", "content_type": "VIDEO", "content_id": "7494337156519332665", "attribution_type": "Direct", "commission_model": "Tiered commission", "commission_tier_setting": "3 OR 5", "standard_commission_rate": 3000, "commission_bonus_rate": 3000, "shop_ads_commission_rate": 3000, "tap_bonus_commission_rate": 3000, "revenue_sharing_portion_rate": 3000, "estimated_commission_base": { "amount": "99", "currency": "USD" }, "estimated_standard_commission": { "amount": "99", "currency": "USD" }, "estimated_bonus_commission": { "amount": "99", "currency": "USD" }, "estimated_shop_ads_commission": { "amount": "99", "currency": "USD" }, "estimated_tap_bonus_commission": { "amount": "99", "currency": "USD" }, "estimated_creator_tax_isr": { "amount": "99", "currency": "USD" }, "estimated_creator_tax_iva": { "amount": "99", "currency": "USD" }, "estimated_creator_tax_pit": { "amount": "99", "currency": "USD" }, "estimated_creator_total_earnings_after_tax": { "amount": "99", "currency": "USD" }, "estimated_total_agency_earnings": { "amount": "1", "currency": "USD" }, "estimated_agency_isr": { "amount": "99", "currency": "USD" }, "estimated_agency_iva": { "amount": "99", "currency": "USD" }, "actual_commission_base": { "amount": "100", "currency": "USD" }, "actual_standard_commission": { "amount": "100", "currency": "USD" }, "actual_bonus_commission": { "amount": "100", "currency": "USD" }, "actual_shop_ads_commission": { "amount": "100", "currency": "USD" }, "actual_tap_bonus_commission": { "amount": "100", "currency": "USD" }, "actual_creator_tax_isr": { "amount": "1", "currency": "USD" }, "actual_creator_tax_iva": { "amount": "1", "currency": "USD" }, "actual_creator_tax_pit": { "amount": "1", "currency": "USD" }, "actual_creator_total_earnings_after_tax": { "amount": "1", "currency": "USD" }, "actual_total_agency_commission": { "amount": "1", "currency": "USD" }, "actual_agency_isr": { "amount": "99", "currency": "USD" }, "actual_agency_iva": { "amount": "99", "currency": "USD" }, "fully_return": "Yes", "settlement_time": 1775548800, "last_update_time": 1685548800, "is_carousel": false } ], "next_page_token": "6AsPQsUMvH3RkchNUPPh22NROHkE0D8pmq/N5M1kHYcZmtRyv9aVrNv65W7Q6tFA+7D1ud64MPNz5OaT", "total_count": 100 }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 6, "x-tts-scopes": [ "Read CAP earnings order" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-cap-affiliate-orders-202603" } }, "/affiliate_partner/202603/orders/search": { "post": { "operationId": "searchTAPAffiliateOrders", "summary": "Search TAP Affiliate Orders", "description": "TAP can use this API to retrieve a list of affiliate orders and track the affiliate conversions.", "tags": [ "Affiliate partner" ], "parameters": [ { "name": "page_token", "in": "query", "required": false, "description": "The pagination token returned in `next_page_token` from the previous response. When paginating, provide `create_time_ge` and `create_time_lt` in the first request, then pass this token and reuse the same `campaign_id` (if specified), `create_time_ge`, and `create_time_lt` values in every subsequent request.", "schema": { "type": "string" } }, { "name": "page_size", "in": "query", "required": true, "description": "The default is 20, it must be positive integer, the range is 1-100", "schema": { "type": "integer", "format": "int64" } }, { "name": "category_asset_cipher", "in": "query", "required": true, "description": "The partner identifier used in API requests. Retrieve this value by using the [Get Authorized Category Assets API](https://partner.tiktokshop.com/docv2/page/666012dd609d4402cc3be995).", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchTAPAffiliateOrdersRequest" }, "example": { "create_time_ge": 1623812664, "create_time_lt": 1623899064, "campaign_id": "7324371012170024705" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchTAPAffiliateOrdersResponse" }, "example": { "code": 0, "data": { "sku_orders": [ { "id": "576962796354307765", "create_time": 1685548800, "delivery_time": 1685548800, "settle_status": "SETTLED", "sku_id": "1729793769377925388", "campaign_id": "7324371012170024705", "creator_username": "liuyi_id_creator1jigo", "product_name": "Black Hoodie", "product_id": "1729435310697057093", "price": { "amount": "99", "currency": "USD" }, "quantity": 1, "content_type": "VIDEO", "content_id": "7494337156519332665", "creator_standard_commission_rate": 3000, "partner_standard_commission_rate": 4000, "creator_shop_ads_commission_rate": 3000, "partner_shop_ads_commission_rate": 4000, "partner_tap_bonus_commission_rate": 1000, "creator_tap_bonus_commission_rate": 2000, "estimated_commission_base": { "amount": "99", "currency": "USD" }, "estimated_creator_standard_commission": { "amount": "100", "currency": "USD" }, "estimated_partner_standard_commission": { "amount": "100", "currency": "USD" }, "estimated_creator_shop_ads_commission": { "amount": "99", "currency": "USD" }, "estimated_partner_shop_ads_commission": { "amount": "99", "currency": "USD" }, "estimated_partner_tap_bonus_commission": { "amount": "100", "currency": "USD" }, "estimated_creator_tap_bonus_commission": { "amount": "100", "currency": "USD" }, "estimated_partner_isr": { "amount": "99", "currency": "USD" }, "estimated_partner_iva": { "amount": "99", "currency": "USD" }, "actual_commission_base": { "amount": "200", "currency": "USD" }, "actual_creator_standard_commission": { "amount": "100", "currency": "USD" }, "actual_partner_standard_commission": { "amount": "99", "currency": "USD" }, "actual_creator_shop_ads_commission": { "amount": "99", "currency": "USD" }, "actual_partner_shop_ads_commission": { "amount": "99", "currency": "USD" }, "actual_partner_isr": { "amount": "99", "currency": "USD" }, "actual_partner_iva": { "amount": "99", "currency": "USD" }, "actual_partner_tap_bonus_commission": { "amount": "200", "currency": "USD" }, "actual_creator_tap_bonus_commission": { "amount": "100", "currency": "USD" }, "fully_return": "Yes", "settlement_time": 1685548800, "last_update_time": 1685548800, "is_carousel": false } ], "next_page_token": "6AsPQsUMvH3RkchNUPPh22NROHkE0D8pmq/N5M1kHYcZmtRyv9aVrNv65W7Q6tFA+7D1ud64MPNz5OaT", "total_count": 100 }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 6, "x-tts-scopes": [ "Read Affiliate Partner Campaigns" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-tap-affiliate-orders-202603" } }, "/affiliate_seller/202405/open_collaboration_settings": { "post": { "operationId": "editOpenCollaborationSettings", "summary": "Edit Open Collaboration Settings", "description": "This API is used to edit a Seller's open collaboration settings. It allows you to enroll your existing product catalog and all future products into an open collaboration plan. It also allows you to turn this setting off at any point. By default, this option is turned off for all Sellers.", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditOpenCollaborationSettingsRequest" }, "example": { "auto_add_product": { "enable": true, "commission_rate": 1000 } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditOpenCollaborationSettingsResponse" }, "example": { "code": 0, "data": {}, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Manage Seller Affiliate Collaboration" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/edit-open-collaboration-settings-202405" } }, "/affiliate_seller/202405/open_collaborations/products/search": { "post": { "operationId": "sellerSearchOpenCollaborationProducts", "summary": "Seller Search Open Collaboration Products", "description": "Searches for open-collaboration products on the TikTok Shop Affiliate Product Marketplace within the regions where the seller is registered to sell. Category, commission rate, sales price, and title keyword filters are optional. When multiple filter groups are supplied, a product must match every supplied group. When none of these filter groups is supplied, no filter from these groups is applied; results remain scoped to eligible open-collaboration products in the seller's registered regions and are returned through pagination.", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "sort_order", "in": "query", "required": false, "description": "The sort order for the sort_field parameter. Default: ASC\nPossible values:\n- ASC: Ascending order\n- DESC: Descending order", "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "x-enum-descriptions": [ "Ascending order", "Descending order" ] } }, { "name": "sort_field", "in": "query", "required": false, "description": "The returned results will be sorted by the specified field. See the description of the field values in the request body for more information about each field.\nDefault: commission_rate\nPossible values:\n- commission_rate\n- product_sales_price\n- commission\n- units_sold", "schema": { "type": "string", "enum": [ "commission_rate", "product_sales_price", "commission", "units_sold" ] } }, { "name": "page_token", "in": "query", "required": false, "description": "An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the next_page_token from a previous response. It is not needed for the first page.", "schema": { "type": "string" } }, { "name": "page_size", "in": "query", "required": true, "description": "The number of results to be returned per page. Valid range: [1-20].", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 20 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellerSearchOpenCollaborationProductsRequest" }, "example": { "title_keywords": [ "Men", "Fashion", " Sports Short" ], "sales_price_range": { "amount_ge": "12.44", "amount_lt": "100" }, "category": { "id": "3412342" }, "commission_rate_range": { "rate_ge": 100, "rate_lt": 8000 } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellerSearchOpenCollaborationProductsResponse" }, "example": { "code": 0, "data": { "products": [ { "shop": { "name": "Test shop" }, "id": "1729432087292775344", "has_inventory": false, "units_sold": 12123, "title": "Blue t-shirt", "sale_region": "ID", "main_image_url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/fa0387fa5a204dcfa44d5be75877a163~tplv-o3syd03w52-origin-webp.webp?from=3478900499", "detail_link": "https://shop.tiktok.com/view/product/1729624807198591373?region=ID&local=en", "original_price": { "currency": "USD", "minimum_amount": "12.21", "maximum_amount": "100.00" }, "category_chains": [ { "id": "343554", "local_name": "COMPUTER", "is_leaf": false, "parent_id": "342948" } ], "commission": { "rate": 3000, "currency": "USD", "amount": "121.32" }, "sales_price": { "currency": "USD", "minimum_amount": "34.3", "maximum_amount": "55.7" } } ], "next_page_token": "b2Zmc2V0PTEw", "total_count": 10000 }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Read Seller Affiliate Collaboration" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/seller-search-open-collaboration-products-202405" } }, "/affiliate_seller/202405/products/{product_id}/promotion_link/generate": { "post": { "operationId": "generateAffiliateProductPromotionLink", "summary": "Generate Affiliate Product Promotion Link", "description": "Partner developers acting on behalf of sellers use this API to generate an affiliate-exclusive promotion link for a specific open-collaboration product, identified by `product_id`, in the TikTok Shop Affiliate Product Marketplace.\n\nThe partner developer can distribute the generated link to creators. A creator can use the link to add the product to the creator's showcase. If a creator adds the product to a showcase through this link, subsequent consumer purchases can be attributed to the partner.", "tags": [ "Affiliate seller" ], "parameters": [ { "name": "product_id", "in": "path", "required": true, "description": "The product identifier.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateAffiliateProductPromotionLinkRequest" }, "example": {} } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateAffiliateProductPromotionLinkResponse" }, "example": { "code": 0, "data": { "product_promotion_link": "https://www.example.com/t/acibsnsgSIngls" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Manage Seller Affiliate Collaboration" ], "x-tts-error-codes": [ { "code": "16015001", "message": "Invalid parameter, the product Ids are not correct. Please ensure the products are in the showcase right now." }, { "code": "16015014", "message": "get product meta failed" } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/generate-affiliate-product-promotion-link-202405" } }, "/affiliate_seller/202409/open_collaboration_settings": { "get": { "operationId": "getOpenCollaborationSettings", "summary": "Get Open Collaboration Settings", "description": "Get the open collaboration settings, including auto add settings.", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOpenCollaborationSettingsResponse" }, "example": { "code": 0, "data": { "open_collaboration_settings": { "auto_add_product": { "enable": true, "commission_rate": 1000 } } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Read Seller Affiliate Collaboration" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-open-collaboration-settings-202409" } }, "/affiliate_seller/202409/open_collaborations/products/{product_id}": { "delete": { "operationId": "removeOpenCollaboration", "summary": "Remove Open Collaboration", "description": "Remove a product's open collaboration. You can remove only an open collaboration with `status == NORMAL`. Use the published `POST /affiliate_seller/202409/open_collaborations/search` endpoint to find the product's open collaboration and confirm that its status is `NORMAL` before calling this API. To protect creators' interests, termination is not immediate and takes effect at the returned `terminated_effective_time`. After that time, call the same search endpoint to verify that the open collaboration is no longer returned.", "tags": [ "Affiliate seller" ], "parameters": [ { "name": "product_id", "in": "path", "required": true, "description": "The product id of the open collaboration to be terminated", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveOpenCollaborationRequest" }, "example": {} } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveOpenCollaborationResponse" }, "example": { "code": 0, "data": { "terminated_effective_time": 1725334422 }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Manage Seller Affiliate Collaboration" ], "x-tts-error-codes": [ { "code": "16003025", "message": "The seller's account is deactivated." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/remove-open-collaboration-202409" } }, "/affiliate_seller/202409/sample_applications/{application_id}/fulfillments/search": { "post": { "operationId": "searchSampleApplicationFulfillments", "summary": "Search Sample Application Fulfillments", "description": "You, the seller, can use this API to get the fulfillment status of the specific sample application and whether the fulfillment resulted in orders. This allows Sellers to track the current progress or analyze the results of their sample distribution program.", "tags": [ "Affiliate seller" ], "parameters": [ { "name": "application_id", "in": "path", "required": true, "description": "The application identifier.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchSampleApplicationFulfillmentsRequest" }, "example": { "content_format": "LIVE" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchSampleApplicationFulfillmentsResponse" }, "example": { "code": 0, "data": { "fulfillments": [ { "product": { "id": "123456", "main_image_url": "https://www.example.com" }, "content": { "id": "123456", "format": "LIVE", "url": "https://www.example.com", "view_count": 100, "like_count": 123, "comment_count": 10, "paid_order_count": 1, "page_link": "https://www.example.com", "description": "abc def gh", "create_time": 1723529426, "live_end_time": 1723529426 } } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Read Seller Affiliate Collaboration" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-sample-application-fulfillments-202409" } }, "/affiliate_seller/202409/target_collaborations/{target_collaboration_id}": { "delete": { "operationId": "removeTargetCollaboration", "summary": "Remove Target Collaboration", "description": "This API is used by Seller to remove affiliate target collaboration.", "tags": [ "Affiliate seller" ], "parameters": [ { "name": "target_collaboration_id", "in": "path", "required": true, "description": "The unique id of the specified target collaboration.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveTargetCollaborationRequest" }, "example": {} } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveTargetCollaborationResponse" }, "example": { "code": 0, "data": {}, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Manage Seller Affiliate Collaboration" ], "x-tts-error-codes": [ { "code": "600001001", "message": "seller call this function is too many" }, { "code": "600001002", "message": "try lock failed" } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/remove-target-collaboration-202409" } }, "/affiliate_seller/202410/open_collaborations/sample_rules": { "get": { "operationId": "getOpenCollaborationSampleRules", "summary": "Get Open Collaboration Sample Rules", "description": "Use this API to get the status and the details of the sample rules for products under an open collaboration. With this API, you can efficiently review the sample distribution criteria for products within the open collaboration context.", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "product_ids", "in": "query", "required": true, "description": "The product IDs whose sample rules to retrieve. Specify 1 to 200 product IDs per request.", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOpenCollaborationSampleRulesResponse" }, "example": { "code": 0, "data": { "sample_rules": [ { "product_id": "123456", "sample_quota": 100, "is_sample_time_unlimited": true, "status": "ONGOING", "available_quantity": 50, "start_time": 1728546888, "end_time": 1728546888, "thresholds": { "minimum_follower_count": 200, "minimum_gmv": 1000, "avg_ec_video_views": 5, "category_ids": [ "601152" ], "predicted_fulfillment_rank": "ALL" } } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Read Seller Affiliate Collaboration" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-open-collaboration-sample-rules-202410" }, "post": { "operationId": "editOpenCollaborationSampleRule", "summary": "Edit Open Collaboration Sample Rule", "description": "Use this API to manage sample rules in open collaborations, like valid time periods, or thresholds for creators to request samples. You can create, update, or deactivate rules.", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditOpenCollaborationSampleRuleRequest" }, "example": { "product_id": "123456", "sample_rule": { "sample_quota": 100, "is_sample_time_unlimited": true, "start_time": 1728552553, "end_time": 1728552553, "thresholds": { "minimum_follower_count": 2000, "minimum_gmv": 1000, "avg_ec_video_views": 5, "category_ids": [ "601152" ], "predicted_fulfillment_rank": "LOW" }, "activate_status": "ACTIVATE" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditOpenCollaborationSampleRuleResponse" }, "example": { "code": 0, "data": {}, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Manage Seller Affiliate Collaboration" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/edit-open-collaboration-sample-rule-202410" } }, "/affiliate_seller/202410/orders/search": { "post": { "operationId": "searchSellerAffiliateOrders", "summary": "Search Seller Affiliate Orders", "description": "This API allows the partner to retrieve a list of affiliate orders (orders which are affiliate-commission eligible) generated by a seller, returning the order ID and the product ID. Using this, the partner can track their affiliate-conversions on behalf of a seller, using the order ID.", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "page_token", "in": "query", "required": false, "description": "An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the `next_page_token` from a previous response. It is not needed for the first page.", "schema": { "type": "string" } }, { "name": "page_size", "in": "query", "required": true, "description": "The number of results to be returned per page. Default: 20\nValid Range: [1-100]", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 100 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchSellerAffiliateOrdersRequest" }, "example": { "create_time_lt": 1722485856, "create_time_ge": 1719807456, "program_id": "73661290629" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchSellerAffiliateOrdersResponse" }, "example": { "code": 0, "data": { "orders": [ { "id": "579125529499110202", "delivery_time": 1723748656, "create_time": 1722420186, "status": "COMPLETED", "skus": [ { "sku_id": "1729791975232997145", "settlement_status": "SETTLED", "open_collaboration_id": "73661290629", "target_collaboration_id": "73661290629", "campaign_id": "73661290629", "creator_username": "exampleTikTokCreatorUsername", "price": { "amount": "1000", "currency": "VND" }, "quantity": 1, "content_type": "LIVE", "content_id": "7493990579714164574", "product_id": "1729503179457070324", "commission_model": "Tiered commission", "commission_tier_setting": "3.0 OR 5.0", "commission_rate": "1000", "partner_commission_rate": "1000", "shop_ads_commission_rate": "5000", "estimated_commission_base": { "amount": "1000", "currency": "VND" }, "estimated_paid_shop_ads_commission": { "amount": "1000", "currency": "VND" }, "estimated_paid_commission": { "amount": "20000", "currency": "VND" }, "estimated_paid_partner_commission": { "amount": "100", "currency": "USD" }, "actual_commission_base": { "amount": "50000", "currency": "VND" }, "actual_paid_commission": { "amount": "10000", "currency": "VND" }, "actual_paid_partner_commission": { "amount": "20000", "currency": "VND" }, "actual_paid_shop_ads_commission": { "amount": "20000", "currency": "VND" }, "estimated_cofunded_creator_bonus_amount": { "amount": "100", "currency": "USD" }, "actual_cofunded_creator_bonus_amount": { "amount": "100", "currency": "USD" }, "refunded_quantity": 1, "returned_quantity": 1, "fully_return": "Yes", "is_carousel": false } ] } ], "next_page_token": "WzE2OTUxMTY2NTQ2OTMsNTc2NDczNDg5ODYxNDEyMDI1XQ==", "total_count": 10000 }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Read Seller Affiliate Collaboration" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-seller-affiliate-orders-202410" } }, "/affiliate_seller/202412/conversation/{conversation_id}/messages": { "get": { "operationId": "getCreatorConversationMessages", "summary": "Get Creator Conversation Messages", "description": "Retrieves a page of messages from a conversation.", "tags": [ "Affiliate seller" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "The identifier of a conversation that belongs to the current seller.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" }, { "name": "page_size", "in": "query", "required": true, "description": "The maximum number of messages to return. Must be between 1 and 20.", "schema": { "type": "integer", "format": "int64" } }, { "name": "page_token", "in": "query", "required": false, "description": "The pagination cursor. Omit this parameter for the first request. When `has_more` is `true`, pass the previous response's `next_page_token` to retrieve the next page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCreatorConversationMessagesResponse" }, "example": { "code": 0, "data": { "has_more": true, "next_page_token": "1735032460678899", "messages": [ { "conversation_index": "1735032460678899", "message_body": { "id": "7451907556216407553", "conversation_id": "7451873679308620048", "type": "TEXT", "content": "{\"content\": \"simple text message\"}", "create_time": 1691411573, "sender_id": "2368694990397660924" } } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Manage Affiliate Messages" ], "x-tts-error-codes": [ { "code": "16032001", "message": "nvalid parameter Creator and Seller, please ensure Region mismatch." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-creator-conversation-messages-202412" } }, "/affiliate_seller/202412/conversations": { "get": { "operationId": "getConversationList", "summary": "Get Conversation List", "description": "Retrieve the seller's IM conversations.", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "page_size", "in": "query", "required": true, "description": "Number of conversations to return per page. Range: 1–50.", "schema": { "type": "integer", "format": "int64" } }, { "name": "page_token", "in": "query", "required": false, "description": "Pagination cursor. Omit this parameter for the first request. For subsequent pages, use the `next_page_token` returned by the previous response.", "schema": { "type": "string" } }, { "name": "only_need_conversation_id", "in": "query", "required": false, "description": "- If `true`, only `conversation_id` in `conversation` is returned. \n- If `false`, all fields in conversation` are returned.\n`true` by default.", "schema": { "type": "boolean" } }, { "name": "conversation_status", "in": "query", "required": false, "description": "Filter the returned IM conversations by status. If omitted, the API returns conversations from all statuses.\n\nPossible values:\n- `ALL`: Retrieve all conversations regardless of status.\n- `UNREAD`: Retrieve conversations with messages the seller has not read. Messages remain unread until explicitly marked as read by calling [Mark Conversation Read](6791db761882810314a991a8); replying does not change the read status.\n- `UNREPLIED`: Retrieve conversations in which the seller is not the last message sender.\n- `STARRED`: Retrieve conversations the seller starred.\n- `ARCHIVED`: Retrieve conversations the seller archived.", "schema": { "type": "string", "enum": [ "ALL", "UNREAD", "UNREPLIED", "STARRED", "ARCHIVED" ], "x-enum-descriptions": [ "Retrieve all conversations regardless of status.", "Retrieve conversations with messages the seller has not read. Messages remain unread until explicitly marked as read by calling [Mark Conversation Read](6791db761882810314a991a8); replying does not change the read status.", "Retrieve conversations in which the seller is not the last message sender.", "Retrieve conversations the seller starred.", "Retrieve conversations the seller archived." ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetConversationListRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetConversationListResponse" }, "example": { "code": 0, "data": { "has_more": true, "next_page_token": "12345678", "conversations": [ { "id": "12345678", "unread_count": 2, "username": "test_creator_name", "avatar": "https://p16-sign-useast2a.tiktokcdn.com/tos-useast2a-avt-0068-giso/2bf6a2485ec8bf93483e4a6ed907e6fd~c5_720x720.webp", "creator_im_id": "12345678" } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Manage Affiliate Messages" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-conversation-list-202412" } }, "/affiliate_seller/202412/conversations/messages/list/newest": { "get": { "operationId": "getLatestUnreadMessages", "summary": "Get Latest Unread Messages", "description": "Get the unread messages from the last minute.\nYou are recommended to use the Webhook, New Message Listener, for the message notification.", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetLatestUnreadMessagesResponse" }, "example": { "code": 0, "data": { "newest_message_list": [ { "conversation_id": "12345", "content": "{\"content\": \"simple text message\"}", "type": "TEXT", "sender_id": "12345678", "unread_message_count": 1 } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Manage Affiliate Messages" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-latest-unread-messages-202412" } }, "/affiliate_seller/202412/conversations/{conversation_id}/messages": { "post": { "operationId": "sendIMMessage", "summary": "Send IM Message", "description": "Sends a message of the selected type in the specified conversation.", "tags": [ "Affiliate seller" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "conversation_id", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendIMMessageRequest" }, "example": { "msg_type": "TEXT", "content": "{\"content\": \"simple text message\"}" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendIMMessageResponse" }, "example": { "code": 0, "data": { "message_id": "1234444" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Manage Affiliate Messages" ], "x-tts-error-codes": [ { "code": "16030100", "message": "Shop has reached IM send message quota with this creator" }, { "code": "16030101", "message": "Seller account is abnormal or you can't contact this creator because shop level didn't meet the GMV requirement." }, { "code": "16032001", "message": "nvalid parameter Creator and Seller, please ensure Region mismatch." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "45101004", "message": "The query quota has been reached (10000 request per day). Please try again tomorrow." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/send-im-message-202412" } }, "/affiliate_seller/202412/conversatons/read": { "post": { "operationId": "markConversationsAsRead", "summary": "Mark Conversations as Read", "description": "Mark the messages in the specified conversations to be read.", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkConversationsAsReadRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkConversationsAsReadResponse" }, "example": { "code": 0, "data": { "failed_conversation_ids": [ "123" ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Manage Affiliate Messages" ], "x-tts-error-codes": [ { "code": "16032001", "message": "nvalid parameter Creator and Seller, please ensure Region mismatch." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/mark-conversations-as-read-202412" } }, "/affiliate_seller/202412/open_collaborations": { "post": { "operationId": "createOpenCollaboration", "summary": "Create Open Collaboration", "description": "This API allows the seller to create an open collaboration. You create an open collaboration by selecting products and setting a commission rate.", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOpenCollaborationRequest" }, "example": { "product_id": "789078671231", "commission_rate": 1000 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOpenCollaborationResponse" }, "example": { "code": 0, "data": { "open_collaboration": { "id": "7365861555575916210", "product_id": "789078671231", "effective_time": 1715654330 } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Manage Seller Affiliate Collaboration" ], "x-tts-error-codes": [ { "code": "16003012", "message": "An open collaboration containing this product already exists." }, { "code": "16003025", "message": "The seller's account is deactivated." }, { "code": "16003033", "message": "The commission rate must be between 1% and 80%." }, { "code": "16003035", "message": "One or more of the products you are trying to add are currently restricted by the platform." }, { "code": "16603010", "message": "The seller is currently restricted by the platform." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/create-open-collaboration-202412" } }, "/affiliate_seller/202412/open_collaborations/search": { "post": { "operationId": "searchOpenCollaborations", "summary": "Search Open Collaborations", "description": "Search the merchant's open collaborations. The response includes product details, current commission information, the number of creators who added each product to their showcase, and the number of creators who posted LIVE or video content.", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "page_token", "in": "query", "required": false, "description": "Pagination token that determines where the search starts. Leave this parameter empty for the first request. For subsequent requests, pass the `next_page_token` returned by the previous response and reuse the same request-body filters, `sort_field`, `sort_order`, and `page_size`.", "schema": { "type": "string" } }, { "name": "page_size", "in": "query", "required": true, "description": "The value of \"page_size\" must be greater than 0 and less than or equal to 100.", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 100 } }, { "name": "sort_order", "in": "query", "required": false, "description": "Default value of \"sort_order\" is DESC.\nEnum:\n- ASC：means to sort data in ascending order\n- DESC：means to sort data in descending order", "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "x-enum-descriptions": [ "means to sort data in ascending order", "means to sort data in descending order" ] } }, { "name": "sort_field", "in": "query", "required": false, "description": "Some sorting fields are as follows:\n- product_original_price: sort by products' original price.\nBy default, the open collaborations are sorted in descending order by creation time.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchOpenCollaborationsRequest" }, "example": { "keyword_type": "PRODUCT_ID", "keyword": "7625459350921", "top_level_category_id": "60001" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchOpenCollaborationsResponse" }, "example": { "code": 0, "data": { "next_page_token": "b2Zmc2V0PTEw", "total_count": 10000, "open_collaborations": [ { "id": "94297006405", "status": "NORMAL", "current_commission": { "rate": 3000, "start_time": 1725334422, "end_time": 1727625600 }, "showcase_creator_count": 15, "content_creator_count": 10, "product": { "id": "1729432087292775344", "title": "Blue t-shirt", "main_image_url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/fa0387fa5a204dcfa44d5be75877a163~tplv-o3syd03w52-origin-webp.webp?from=3478900499", "status": "LIVE", "inventory": 1274, "original_price": { "currency": "USD", "minimum_amount": "12.21", "maximum_amount": "100.00" } } } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Read Seller Affiliate Collaboration" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-open-collaborations-202412" } }, "/affiliate_seller/202507/sample_applications/{application_id}/review": { "post": { "operationId": "reviewASampleApplication", "summary": "Review a Sample Application", "description": "This API allows the seller to approve or reject a creator's sample application in an open collaboration. Only applications in the PENDING status can be approved or rejected. When rejecting an application, the seller must provide a supported rejection reason.", "tags": [ "Affiliate seller" ], "parameters": [ { "name": "application_id", "in": "path", "required": true, "description": "The unique id of sample request application ID", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewASampleApplicationRequest" }, "example": { "review_result": "APPROVE", "reject_reason": "NOT_MATCH" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewASampleApplicationResponse" }, "example": { "code": 0, "data": {}, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Manage Seller Affiliate Collaboration" ], "x-tts-error-codes": [ { "code": "16022020", "message": "seller has no permission to operate agency's sample request" } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/review-a-sample-application-202507" } }, "/affiliate_seller/202508/conversations": { "post": { "operationId": "getOrCreateCreatorConversation", "summary": "Get or Create Creator Conversation", "description": "Get the existing conversation or create a new conversation with the specified TikTok creator. To send a message in the conversation, pass the returned `data.conversation_id` as the `conversation_id` path parameter of Send IM Message (`POST /affiliate_seller/202412/conversations/{conversation_id}/messages`).", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrCreateCreatorConversationRequest" }, "example": { "creator_open_id": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg", "only_need_conversation_id": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrCreateCreatorConversationResponse" }, "example": { "code": 0, "data": { "conversation_id": "1234567890", "is_new": true, "username": "test_creator_name", "avatar": "https://p16-sign-useast2a.tiktokcdn.com/tos-useast2a-avt-0068-giso/2bf6a2485ec8bf93483e4a6ed907e6fd~c5_720x720.webp", "unread_count": 2, "creator_im_id": "12345678" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Manage Affiliate Messages" ], "x-tts-error-codes": [ { "code": "16030001", "message": "creator has been cleard" }, { "code": "16030002", "message": "shop has reached IM quota. More information please check [https://seller.tiktokglobalshop.com/university/essay?identity=1&role=1&knowledge_id=2766765165102865&from=feature_guide]" }, { "code": "16030003", "message": "This shop cannot message the creator at the moment because the Affiliate GMV requirement has not been met." }, { "code": "16030007", "message": "shop status invalid" }, { "code": "16030009", "message": "test account isolate. please don't use the test account to send message." }, { "code": "16032001", "message": "nvalid parameter Creator and Seller, please ensure Region mismatch." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "45101021", "message": "unauthorized operation on users who hit privacy control" } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-or-create-creator-conversation-202508" } }, "/affiliate_seller/202508/open_collaborations/creator_content_details": { "get": { "operationId": "getOpenCollaborationCreatorContentDetails", "summary": "Get Open Collaboration Creator Content Details", "description": "This API allows a seller to retrieve creator profiles, content counts, and promotion details for a specified product in open collaboration.", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "page_token", "in": "query", "required": false, "description": "Pagination token. Omit this parameter or pass an empty string for the first request. For subsequent requests, pass the `next_page_token` returned by the previous response and reuse the same `product_id` and `page_size`.", "schema": { "type": "string" } }, { "name": "page_size", "in": "query", "required": true, "description": "The value of \"page_size\" must be greater than 0 and less than or equal to 100.", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 100 } }, { "name": "product_id", "in": "query", "required": true, "description": "The product ID that needs to be queried.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOpenCollaborationCreatorContentDetailsResponse" }, "example": { "code": 0, "data": { "next_page_token": "b2Zmc2V0PTEw", "total_count": 1, "creator_content_details": [ { "creator_profile": { "username": "example_creator", "nickname": "nickname", "follower_count": 10023, "avatar": { "url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/fa0387fa5a204dcfa44d5be75877a163~tplv-o3syd03w52-origin-webp.webp?from=3478900499" }, "creator_open_id": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg" }, "video_count": 101, "live_count": 2, "promotion_status": "NORMAL", "promotion_end_time": 1734682697 } ], "product": { "id": "1734823553672710512", "image_url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/fa0387fa5a204dcfa44d5be75877a163~tplv-o3syd03w52-origin-webp.webp?from=3478900499" } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Read Seller Affiliate Collaboration" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-open-collaboration-creator-content-details-202508" } }, "/affiliate_seller/202508/open_collaborations/{open_collaboration_id}/remove_creator": { "post": { "operationId": "removeCreatorFromOpenCollaborationProduct", "summary": "Remove Creator From Open Collaboration Product", "description": "This API is used to remove creators from open collaboration. Please note, due to current platform design, creators can still rejoin an open collaboration after removal. Partners/Sellers can call this API again to remove the creator again.", "tags": [ "Affiliate seller" ], "parameters": [ { "name": "open_collaboration_id", "in": "path", "required": true, "description": "Open collaboration ID. This API is only applicable to the seller removing creators from open collaboration.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveCreatorFromOpenCollaborationProductRequest" }, "example": { "creator_user_open_id": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg", "product_id": "789078671231" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveCreatorFromOpenCollaborationProductResponse" }, "example": { "code": 0, "data": {}, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Manage Seller Affiliate Collaboration" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/remove-creator-from-open-collaboration-product-202508" } }, "/affiliate_seller/202508/sample_applications/search": { "post": { "operationId": "searchSampleApplications", "summary": "Search Sample Applications", "description": "This API is provided for sellers to query sample applications based on various criteria such as products, creators, or application statuses. By using this API, sellers can retrieve detailed information about sample application records, including the creator's information and the specifics of each application.", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "page_token", "in": "query", "required": false, "description": "Pagination offset determines where you begin to search for. It's empty when raise your first request.", "schema": { "type": "string" } }, { "name": "page_size", "in": "query", "required": false, "description": "The value of \"page_size\" must be greater than 0 and less than or equal to 50.", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 50 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchSampleApplicationsRequest" }, "example": { "product_id": "123456", "title": "product name", "creator_user_oepn_id": "123456", "username": "test_tt_name", "target_collabration_id": "123456", "order_id": "123456", "status": "PENDING" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchSampleApplicationsResponse" }, "example": { "code": 0, "data": { "next_page_token": "b2Zmc2V0PTUw", "total_count": 100, "sample_applications": [ { "id": "123456", "commission_rate": "0.20", "status": "PENDING", "order_id": "123456", "available_quantity": 50, "approve_expiration_time": 1728674995, "shipment_expiration_time": 1728674995, "tracking_number": "123456", "fulfillment_status": "ONGOING", "is_approvable": true, "disapprovable_reasons": [ "Product out of stock" ], "partner_name": "ABC", "creator": { "creator_open_id": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg", "username": "test.name", "nickname": "Test Name", "follower_count": 200, "avatar_url": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068xxxxx", "gmv": { "amount": "500", "currency": "USD" }, "content_count": 4, "fulfillment_percentage": "60.50", "ec_video_view": 1200 }, "product": { "id": "123456", "title": "A women dress", "sku_id": "123456", "sku_image_url": "https://p16-oec-va.ibyteimg.com/tos-malivaxxxxx", "sku_name": "Soft Cover" } } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Read Seller Affiliate Collaboration" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-sample-applications-202508" } }, "/affiliate_seller/202508/target_collaborations": { "post": { "operationId": "createTargetCollaboration", "summary": "Create Target Collaboration", "description": "This API is used to create a target collaboration.\nA target collaboration is a collaboration between a seller selected set of products (including a commission payout) and a set of creators the seller has added (invited) to the collaboration. Target collaborations are private and not visible in the Creator Marketplace to all creators; they are only visible to those that have been added to the collaboration.", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTargetCollaborationRequest" }, "example": { "name": "openapi_test", "message": "this is a message", "end_time": "1715654330", "products": [ { "id": "789078671231312312", "target_commission_rate": 1000, "shop_ads_commission_rate": 1000 } ], "creator_user_open_ids": [ "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg" ], "seller_contact_info": { "email": "test@tiktokshop.com", "phone_number": "1234567890", "whatsapp": "1234567890", "telegram": "1234567890", "line": "1234567890" }, "free_sample_rule": { "has_free_sample": true, "is_sample_approval_exempt": true }, "preferred_content_type": "LIVE" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTargetCollaborationResponse" }, "example": { "code": 0, "data": { "target_collaboration": { "id": "7365861555575916210" }, "target_collaboration_conflicts": [ { "creator_user_open_id": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg", "product_id": "789078671231" } ], "invalid_open_id_list": [ "xxxx" ], "invalid_product_id_list": [ "1234" ], "create_time": 1715654330 }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Manage Seller Affiliate Collaboration" ], "x-tts-error-codes": [ { "code": "16024004", "message": "test account and non test account can not cross invite" }, { "code": "16024006", "message": "The seller cannot invite their official creator." }, { "code": "16024008", "message": "There are products that do not belong to this merchant." }, { "code": "16024016", "message": "The invitation failed because the creator is already linked with a shop account." }, { "code": "16024019", "message": "in sufficient quota to create invitation" }, { "code": "16024020", "message": "remove excluded creators to create invitation" }, { "code": "16024021", "message": "invitation contains creator exceed follower limit" }, { "code": "16024022", "message": "This invitation has exist creator and product, please check conflict pair." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "50001702", "message": "Your invitation target contains an unavailable creator or product. Please check your request params.Remove the unavailable creator or product id and try again." }, { "code": "50001703", "message": "The request parameters contain sensitive words." }, { "code": "98001004", "message": "Parameter {param_name} is invalid. Reason: {reason}. Expected: {expected_value}" } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/create-target-collaboration-202508" } }, "/affiliate_seller/202508/target_collaborations/search": { "post": { "operationId": "searchTargetCollaborations", "summary": "Search Target Collaborations", "description": "This API is used by Seller to search for all existing target collaborations. Sellers can search based on filters such as Invitation name, Invitation ID, Product name, Product ID and Creator name.", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "page_size", "in": "query", "required": false, "description": "The value of \"page_size\" must be 20, 50 or 100.", "schema": { "type": "integer", "format": "int64" } }, { "name": "page_token", "in": "query", "required": false, "description": "Pagination token that specifies where to continue the search. Omit this parameter or leave it empty in the first request. For subsequent pages, pass the `next_page_token` returned by the previous response and reuse the same request-body filters and `page_size`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchTargetCollaborationsRequest" }, "example": { "creator_accept_status": "ACCEPT", "free_sample_setting": "WITH_FREE_SAMPLE", "search_param": { "keyword_type": "TARGET_COLLABORATION_NAME", "keyword": "test" }, "creator_user_open_id": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg", "collaboration_status": "ONGOING" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchTargetCollaborationsResponse" }, "example": { "code": 0, "data": { "total_count": 100, "next_page_token": "b2Zmc2V0PTIw", "target_collaborations": [ { "id": "789078671231123124", "name": "target_collaboration", "message": "test", "start_time": 1715654330, "end_time": 1715654330, "create_time": 1715654330, "update_time": 1715654330, "creator_inivited_count": 10, "showcase_creator_count": 2, "content_creator_count": 1, "product_count": 30, "free_sample_rule": { "has_free_sample": true, "is_sample_approval_exempt": true }, "type": "STANDARD" } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Read Seller Affiliate Collaboration" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-target-collaborations-202508" } }, "/affiliate_seller/202508/target_collaborations/{target_collaboration_id}": { "get": { "operationId": "queryTargetCollaborationDetail", "summary": "Query Target Collaboration Detail", "description": "This API is used by Sellers to get target collaboration information.", "tags": [ "Affiliate seller" ], "parameters": [ { "name": "target_collaboration_id", "in": "path", "required": true, "description": "The ID of the target collaboration", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryTargetCollaborationDetailResponse" }, "example": { "code": 0, "data": { "target_collaboration": { "id": "789078671231123124", "name": "target_collaboration", "message": "test", "seller_contact_info": { "email": "test@bytedance.com", "phone_number": "1234", "whatsapp": "aaaa", "telegram": "1234", "line": "asd" }, "start_time": 1715654330, "end_time": 1715654330, "update_time": 1715654330, "creator_invited_count": 10, "showcase_creator_count": 2, "content_creator_count": 1, "product_count": 30, "free_sample_rule": { "has_free_sample": true, "is_sample_approval_exempt": true }, "products": [ { "id": "789078671231312312", "main_image_url": "https://p16-sign-useast2a.tiktokcdn.com/tos-useast2a/12345~c5_168x168.webp?lk3s=a5d48078&nonce=49646&refresh_token=b53364a3a1947c4ac7a0c4bea62e31ea&x-expires=1727175600&x-signature=ASPIxFDNDkN1cknLEItlyC%2Bcfbw%3D&shp=a5d48078&shcp=39dffb78", "title": "Christmas Gift", "original_price": { "currency": "USD", "minimum_amount": "12.21", "maximum_amount": "100.00" }, "commission": { "rate": 3000, "effective_time": "1715654330", "currency": "USD", "minimum_amount": "34.3", "maximum_amount": "55.7", "shop_ads_commission_rate": 100 }, "status": "LIVE", "commission_effective_status": "EFFECTIVE_ALL", "collaboration_status": "NORMAL" } ], "creators": [ { "username": "123456", "nickname": "123456", "avatar": { "url": "https://p16-sign-useast2a.tiktokcdn.com/tos-useast2a-avt-0068-giso/2bf6a2485ec8bf93483e4a6ed907e6fd~c5_720x720.webp?lk3s=a5d48078&x-expires=1712988000&x-signature=E8US22KfUCwKz0R%2FMFF6%2FMOmogs%3D" }, "selection_region": "US", "showcase_product_count": 2, "content_product_count": 1, "collaboration_status": "NORMAL", "product_effective_status": "EFFECTIVE_ALL", "creator_open_id": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg" } ], "type": "STANDARD" } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Read Seller Affiliate Collaboration" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "50001700", "message": "seller cannot access this target collaboration" } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/query-target-collaboration-detail-202508" }, "put": { "operationId": "updateTargetCollaboration", "summary": "Update Target Collaboration", "description": "This API is used by sellers to update a STANDARD target collaboration. A successful response can still report creators or products that were not updated. Check `data.update_failed` and `data.target_collaboration_conflicts` before treating the update as complete.", "tags": [ "Affiliate seller" ], "parameters": [ { "name": "target_collaboration_id", "in": "path", "required": true, "description": "The unique id of specific target collaboration.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTargetCollaborationRequest" }, "example": { "name": "openapi_test", "end_time": "1715654330", "products": [ { "id": "789078671231312312", "commission_rate": 1000, "target_ad_commission_rate": 1000 } ], "creator_user_open_ids": [ "123123213213" ], "seller_contact_info": { "email": "test@bytedance.com", "phone_number": "1234567890", "whatsapp": "1234567890", "telegram": "1234567890", "line": "1234567890" }, "free_sample_rule": { "has_free_sample": true, "is_sample_approval_exempt": true } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTargetCollaborationResponse" }, "example": { "code": 0, "data": { "target_collaboration_conflicts": [ { "creator_user_open_id": "7494656937121841111", "product_id": "789078671231" } ], "update_failed": { "remove_creator_open_ids": [ "12345" ], "remove_product_ids": [ "12345" ], "add_creator_open_ids": [ "12345" ], "add_products": { "id": "789078671231312312", "commission_rate": 1000 }, "change_commissions": { "product_id": "789078671231312312", "commission_rate": 1000 }, "end_time": 1715654330, "seller_contact_info": { "email": "test@bytedance.com", "phone_number": "(+62) 1234567890\n", "whatsapp": "(+62) 1234567890\n", "telegram": "(+62) 1234567890\n", "line": "(+62) 1234567890\n" }, "name": "openapi_test", "invalid_product_id_list": [ "1234" ], "invalid_open_id_list": [ "xxxxxx" ] } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Manage Seller Affiliate Collaboration" ], "x-tts-error-codes": [ { "code": "16024004", "message": "test account and non test account can not cross invite" }, { "code": "16024006", "message": "The seller cannot invite their official creator." }, { "code": "16024008", "message": "There are products that do not belong to this merchant." }, { "code": "16024016", "message": "The invitation failed because the creator is already linked with a shop account." }, { "code": "16024018", "message": "seller can not invite his block creator" }, { "code": "16024019", "message": "in sufficient quota to create invitation" }, { "code": "16024020", "message": "remove excluded creators to create invitation" }, { "code": "16024021", "message": "invitation contains creator exceed follower limit" }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "36009007", "message": "request timeout" }, { "code": "50001701", "message": "target collaboration has expired" }, { "code": "50001702", "message": "Your invitation target contains an unavailable creator or product. Please check your request params.Remove the unavailable creator or product id and try again." }, { "code": "50001703", "message": "The request parameters contain sensitive words." }, { "code": "98001004", "message": "Parameter {param_name} is invalid. Reason: {reason}. Expected: {expected_value}" } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/update-target-collaboration-202508" } }, "/affiliate_seller/202509/target_collaboration/{target_collaboration_id}/link": { "post": { "operationId": "generateTargetCollaborationLink", "summary": "Generate Target Collaboration Link", "description": "Generate a Target Collaboration Link that the seller can share with the creator. This link directs the creator to a guided flow to review details and formally accept the target collaboration", "tags": [ "Affiliate seller" ], "parameters": [ { "name": "target_collaboration_id", "in": "path", "required": true, "description": "Target collaboration ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateTargetCollaborationLinkRequest" }, "example": {} } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateTargetCollaborationLinkResponse" }, "example": { "code": 0, "data": { "link": "https://affiliate-id.tokopedia.com/api/v1/oec/affiliate/seller/invitation_group/share/long_url/AJBNfIPZXGcc" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Manage Seller Affiliate Collaboration" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/generate-target-collaboration-link-202509" } }, "/affiliate_seller/202511/images/upload": { "post": { "operationId": "uploadMessageImage", "summary": "Upload Message Image", "description": "You must use this API to upload the image first, before sending an image as a message using [Send IM Messsage](https://partner.tiktokshop.com/docv2/page/send-im-message-202412)", "tags": [ "Affiliate seller" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UploadMessageImageRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadMessageImageResponse" }, "example": { "code": 0, "data": { "url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/2ca53c34ad8443e6b39f4e0153d3aed4~tplv-o3syd03w52-origin-image.image?from=1320446476", "width": 1280, "height": 720 }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 2, "x-tts-scopes": [ "Manage Affiliate Messages" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "45101001", "message": "Internal error. Please try again later or contact the technical support team for help." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/upload-message-image-202511" } }, "/affiliate_seller/202512/sample_applications/deeplink": { "get": { "operationId": "sellerGetSampleRequestDeeplink", "summary": "Seller Get Sample Request Deeplink", "description": "Use this API to get a TikTok deeplink, use this deeplink to launch the TikTok app and land the user on the sample request page.\n- The seller can encode the deeplink into an QR code and send it to a creator via email.", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "product_id", "in": "query", "required": true, "description": "The ID of a product that belongs to the authenticated shop. If neither `campaign_id` nor `collaboration_id` is provided, the product must be in an active open collaboration.", "schema": { "type": "string" } }, { "name": "sku_id", "in": "query", "required": true, "description": "The ID of a SKU that belongs to the product identified by `product_id`.", "schema": { "type": "string" } }, { "name": "campaign_id", "in": "query", "required": false, "description": "If the product belongs to a TAP campaign, `campaign_id` is required. The specified campaign must be active and contain the product identified by `product_id`.\n\nSupported campaign types:\n- `MY_CAMPAIGNS`\n- `SELLER_CAMPAIGNS`", "schema": { "type": "string" } }, { "name": "collaboration_id", "in": "query", "required": false, "description": "If the product belongs to a seller collaboration, `collaboration_id` is required. Do not provide `collaboration_id` together with `campaign_id`.", "schema": { "type": "string" } }, { "name": "valid_days", "in": "query", "required": false, "description": "7 days by default.\n14 days maximum.\n1 day minimum.", "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellerGetSampleRequestDeeplinkResponse" }, "example": { "code": 0, "data": { "deeplink": "snssdk1180://roma_redirect/?_pia_=1&app_key=aaaa&callback_dp_key=f3318dbad42e495eaa12f3b9bec5af92&enter_from=deeplink&product_id=1729504817131129797&roma_group_key=spark_page_seller_free_sample_apply&roma_page_key=p&sample_apply_source=1&sku_id=1729504817131195333&spark_page=seller_free_sample_apply&track_data=%7B%22is_from_selection_scenarios%22%3A%221%22%2C%22selection_channel%22%3A%22deeplink%22%7D" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Read Seller Affiliate Collaboration" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/seller-get-sample-request-deeplink-202512" } }, "/affiliate_seller/202603/compass/offline_task": { "post": { "operationId": "createCompassOfflineExportTask", "summary": "Create Compass Offline Export Task", "description": "Create an asynchronous offline export task for the specified doc_type and plan_type within a given time window. Returns a task_id for subsequent status query and file download.", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCompassOfflineExportTaskRequest" }, "example": { "module_type": "BASE", "window_type": "PAST_24H", "end_day": 20260301, "plan_type": "ALL" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCompassOfflineExportTaskResponse" }, "example": { "code": 0, "data": { "task": { "id": "1234" } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Read Seller Affiliate Collaboration" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/create-compass-offline-export-task-202603" } }, "/affiliate_seller/202603/compass/offline_tasks": { "get": { "operationId": "getCompassTaskList", "summary": "Get Compass Task List", "description": "Retrieve the list of export tasks created via Open API for the authorized seller (last 7 days). Supports pagination and returns task status, file_name and timestamps.", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "doc_type", "in": "query", "required": true, "description": "Export-task category to retrieve.\n- CREATOR: Selects creator-list export tasks.\n- BASE: Selects core-performance export tasks.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCompassTaskListResponse" }, "example": { "code": 0, "data": { "tasks": [ { "module_type": "BASE", "id": "1234", "file_name": "Transaction_Analysis_Core_Metrics_20240301-20240331", "status": "RUNNING" } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Read Seller Affiliate Collaboration" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-compass-task-list-202603" } }, "/affiliate_seller/202603/compass/offline_tasks/{task_id}/file": { "get": { "operationId": "downloadCompassTaskFile", "summary": "Download Compass Task File", "description": "Download the result file of a completed export task by taskId. Requires ownership validation; returns file.", "tags": [ "Affiliate seller" ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "The id of the task", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadCompassTaskFileResponse" }, "example": { "code": 0, "data": { "file": { "base64": "ZXhhbXBsZQ==" } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Read Seller Affiliate Collaboration" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/download-compass-task-file-202603" } }, "/affiliate_seller/202605/target_collaborations/conflicts/check": { "post": { "operationId": "checkTargetCollaborationConflicts", "summary": "Check Target Collaboration Conflicts", "description": "Retrieve conflicting target collaborations for the product and determine if they can be terminated", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckTargetCollaborationConflictsRequest" }, "example": { "creator_open_id_list": [ " " ], "product_id_list": [ " " ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckTargetCollaborationConflictsResponse" }, "example": { "code": 0, "data": { "has_conflict": false, "conflict_items": [ { "creator_open_id": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg", "product_id": "1234", "existing_collaboration_id": "1234" } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Manage Seller Affiliate Collaboration" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/check-target-collaboration-conflicts-202605" } }, "/affiliate_seller/202605/target_collaborations/conflicts/resolve": { "post": { "operationId": "resolveTargetCollaborationConflicts", "summary": "Resolve Target Collaboration Conflicts", "description": "Execute resolution actions on resolvable conflict items within the scope of seller authorization.", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveTargetCollaborationConflictsRequest" }, "example": { "conflict_items": [ { "existing_collaboration_id": "123", "creator_open_id": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg" } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveTargetCollaborationConflictsResponse" }, "example": { "code": 0, "data": { "success_items": [ { "creator_open_id": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg", "existing_collaboration_id": "123" } ], "failed_items": [ { "creator_open_id": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg", "existing_collaboration_id": "1234" } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Manage Seller Affiliate Collaboration" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/resolve-target-collaboration-conflicts-202605" } }, "/affiliate_seller/202607/creator_outreach/quota": { "get": { "operationId": "getWeeklyCreatorOutreachQuota", "summary": "Get Weekly Creator Outreach Quota", "description": "Query the weekly outreach invitation quota for a shop. It returns the current GMV tier, maximum reachable creator follower count corresponding to the tier, consumed quota, remaining quota and other related information.", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetWeeklyCreatorOutreachQuotaResponse" }, "example": { "code": 0, "data": { "data": { "shop_id": "1234", "quota_type": "BONUS", "gmv_tier": "1", "quota_sum": "1000", "quota_use": "500", "unlimited": false, "reached_max_follower_cnt": "1000", "new_connect_count": "100", "pair_connect_count": "100", "start_time": "1754296736852", "end_time": "1754296736852", "gmv_level_rule": [ { "reached_max_follower_cnt": "1000", "gmv_tier": "1", "left_gmv": { "amount": "1000", "currency": "JPY" }, "right_gmv": { "amount": "2000", "currency": "JPY" }, "quota_details": [ { "creator_levels": [ 1, 2 ], "quota_period_sum": 100, "quota_bonus_sum": 60 } ] } ], "quota_details": [ { "creator_levels": [ 1, 2 ], "quota_period_sum": 100, "quota_period_use": 1, "quota_bonus_sum": 60, "quota_bonus_use": 60 } ], "bonus_exposure_post_percentile_threshold": "0.8" } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Read Seller Affiliate Collaboration" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-weekly-creator-outreach-quota-202607" } }, "/affiliate_seller/202608/conversations/group_counts": { "get": { "operationId": "getInboxCategoryCounts", "summary": "Get Inbox Category Counts", "description": "Query the number of sessions grouped by status such as read, unread, starred and archived.", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetInboxCategoryCountsResponse" }, "example": { "code": 0, "data": { "data": { "group_counts": [ { "group_type": "UNREAD", "count": 10 } ] } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Manage Affiliate Messages" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-inbox-category-counts-202608" } }, "/affiliate_seller/202608/conversations/{conversation_id}/status": { "post": { "operationId": "updateConversationStatus", "summary": "Update Conversation Status", "description": "Support starring or archiving a given conversation with creator.", "tags": [ "Affiliate seller" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "conversation id", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConversationStatusRequest" }, "example": { "action": "STARRED" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConversationStatusResponse" }, "example": { "code": 0, "data": {}, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Manage Affiliate Messages" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/update-conversation-status-202608" } }, "/affiliate_seller/202608/creator_outreach/records/query": { "post": { "operationId": "getWeeklyCreatorOutreachRecords", "summary": "Get Weekly Creator Outreach Records", "description": "Query weekly detailed outreach‑invitation records for a specified seller, including whether IM messages/invitations were sent to a unconnected creator, and whether the creator added products or replied to IM messages.", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetWeeklyCreatorOutreachRecordsRequest" }, "example": { "page_index": 1, "page_size": 50 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetWeeklyCreatorOutreachRecordsResponse" }, "example": { "code": 0, "data": { "data": { "total": 10, "connect_list": [ { "id": "1234", "creator_open_id": "1234", "has_sent_im_message": false, "has_sent_invitation": false, "is_paired": false } ] } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Manage Seller Affiliate Collaboration", "Read Seller Affiliate Collaboration" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-weekly-creator-outreach-records-202608" } }, "/affiliate_seller/202608/marketplace_creators/search": { "post": { "operationId": "searchCreatorsInCreatorMarketplace", "summary": "Search Creators in Creator Marketplace", "description": "This API is used by Sellers to search for Creators in the Creator Marketplace. Sellers can search based on filters such as GMV, keywords, and Creator follower demographics. All the data returned is for the last 30 days.", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "page_token", "in": "query", "required": false, "description": "Pagination token that identifies where to continue the search. For the first request, omit this parameter or leave it empty. For each subsequent request, pass the next_page_token returned by the previous response.", "schema": { "type": "string" } }, { "name": "page_size", "in": "query", "required": true, "description": "The value of \"page_size\" must be 12 or 20", "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchCreatorsInCreatorMarketplaceRequest" }, "example": { "search_key": "2E+0EcXoSk2HWdEWh2nITfkBRMbwuug0mt9s3fWgV0k=", "keyword": "JefreeStar", "follower_demographics": { "age_ranges": [ "AGE_RANGE_18_24", "AGE_RANGE_35_44" ], "count_range": { "count_ge": 1000, "count_le": 10000 }, "gender_distribution": { "gender": "MALE", "percentage_ge": 6000 } }, "gmv_ranges": [ "GMV_RANGE_0_100", "GMV_RANGE_100_1000" ], "units_sold_ranges": [ "UNITS_SOLD_RANGE_0_10", "UNITS_SOLD_RANGE_100_1000", "UNITS_SOLD_RANGE_1000_AND_ABOVE" ], "category": [ { "parent_category_id": "600001", "child_category_id_list": [ "851848" ] } ], "content_performance": { "avg_video_views": "1", "avg_shoppable_video_views": "1", "avg_engagement_rate": "1", "avg_shopable_engagement_rate": "1", "avg_live_avg_viewers_ge": "1", "avg_shoppable_live_avg_viewers_ge": "1" }, "affiliate_data": { "avg_commission_rate": "LESS_THAN_20%", "post_rate": "GOOD", "creator_agency_staus": "AGENCY_MANAGED", "is_fast_growing": false, "not_invited_l90_days": false }, "advanced_filters": { "content_preference_type": [ "VIDEO" ], "eligible_flat_fee": false, "option_list": [ { "options": [ { "id": "1", "name": "English", "option_children": [ { "id": "2", "name": "SubTypeName" } ] } ], "option_type": "OPTION_LANGUAGE" } ], "sorter_algorithm_id": "1" }, "data_groups": [ "BASIC_CREATOR_INFORMATION", "SALES_AND_GMV" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchCreatorsInCreatorMarketplaceResponse" }, "example": { "code": 0, "data": { "next_page_token": "b2Zmc2V0PTEy", "search_key": "k1ChOzI9e+j5BHHHEnt+VhItjVFEkPUCCXNsrU8/v4U=", "creators": [ { "username": "abc", "nickname": "cde", "avatar": { "url": "https://p16-sign-useast2a.tiktokcdn.com/tos-useast2a-avt-0068-giso/2bf6a2485ec8bf93483e4a6ed907e6fd~c5_720x720.webp?lk3s=a5d48078&x-expires=1712988000&x-signature=E8US22KfUCwKz0R%2FMFF6%2FMOmogs%3D" }, "selection_region": "GB", "category_ids": [ "60001" ], "avg_ec_live_uv": 1331, "avg_ec_video_view_count": 112, "follower_count": 23241, "gmv": { "currency": "USD", "amount": "1232.90" }, "live_gmv": { "currency": "USD", "amount": "0.34" }, "video_gmv": { "currency": "USD", "amount": "23.34" }, "gmv_range": { "currency": "USD", "minimum_amount": "0", "maximum_amount": "100", "formatted_range": "$0-$100" }, "units_sold_range": { "minimum_amount": 100, "maximum_amount": 1000, "formatted_range": "100-1K" }, "top_follower_demographics": { "age_ranges": [ "AGE_RANGE_18_24", "AGE_RANGE_25_34" ], "major_gender": { "gender": "FEMALE", "percentage": 6524 } }, "creator_open_id": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg", "creator_profile": { "is_official_recommend": false, "creator_bind_mcn_name": "name", "is_fast_growing": false, "has_collaborated": false, "user_type_tag": [ 1 ], "has_invited_90d": false, "is_creator_blocked": false, "pps_score": "4.3", "is_eligible_flat_fee": false, "is_rising_star": false, "creator_level": 2 } } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Read Creator Marketplace" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "45101004", "message": "The query quota has been reached (10000 request per day). Please try again tomorrow." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-creators-in-creator-marketplace-202608" } }, "/affiliate_seller/202608/marketplace_creators/search/filter": { "post": { "operationId": "getCreatorMarketplaceAdvancedSearchFilters", "summary": "Get Creator Marketplace Advanced Search Filters", "description": "This API allows you to obtain the advanced filters available in Seller Search Creator Marketplace. Because we are constantly releasing new filters which are specific to each country or region, this API serves as a way for developers to retrieve the latest available search filters.", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCreatorMarketplaceAdvancedSearchFiltersRequest" }, "example": { "options": [ { "option_type": "OPTION_SORTER" } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCreatorMarketplaceAdvancedSearchFiltersResponse" }, "example": { "code": 0, "data": { "data": { "option_list": [ { "option_type": "OPTION_LANGUAGE", "options": [ { "id": "1", "name": "English", "option_children": [ { "id": "12", "name": "SubTypeName" } ] } ] } ], "sorters": [ { "algorithm_id": "1", "name": "related" } ] } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Read Creator Marketplace" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-creator-marketplace-advanced-search-filters-202608" } }, "/affiliate_seller/202608/marketplace_creators/{creator_user_id}": { "get": { "operationId": "getMarketplaceCreatorPerformance", "summary": "Get Marketplace Creator Performance", "description": "Returns marketplace information and performance metrics for the specified creator.", "tags": [ "Affiliate seller" ], "parameters": [ { "name": "creator_user_id", "in": "path", "required": true, "description": "Creator Open ID. [More details](https://partner.tiktokshop.com/docv2/page/3obfokj6)", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" }, { "name": "data_groups", "in": "query", "required": false, "description": "Creator data groups to include in the response. If omitted, all five groups are selected. Individual field availability remains subject to the documented market, permission, and availability conditions for each field. To request multiple groups, provide the values as a comma-separated query string, for example, BASIC_CREATOR_INFORMATION,CONTENT_PERFORMANCE.\nAvailable values:\n- BASIC_CREATOR_INFORMATION: Basic creator profile information.\n- CONTENT_PERFORMANCE: Content performance metrics, Promotion Performance Score (PPS), fulfillment score, and promoted product count.\n- FOLLOWER_INFORMATION: Follower location, age, and gender distributions.\n- COLLABORATION: Collaborated brands and commission information.\n- SALES_AND_GMV: Units sold; GMV and GPM metrics and distributions; product price range; and average GMV per buyer.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "BASIC_CREATOR_INFORMATION", "CONTENT_PERFORMANCE", "FOLLOWER_INFORMATION", "COLLABORATION", "SALES_AND_GMV" ], "x-enum-descriptions": [ "Basic creator profile information.", "Content performance metrics, Promotion Performance Score (PPS), fulfillment score, and promoted product count.", "Follower location, age, and gender distributions.", "Collaborated brands and commission information.", "Units sold; GMV and GPM metrics and distributions; product price range; and average GMV per buyer." ] } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMarketplaceCreatorPerformanceResponse" }, "example": { "code": 0, "data": { "creator": { "username": "dioab", "nickname": "Dion", "avatar": { "url": "https://p16-sign-useast2a.tiktokcdn.com/tos-useast2a-avt-0068-giso/2bf6a2485ec8bf93483e4a6ed907e6fd~c5_720x720.webp?lk3s=a5d48078&x-expires=1712988000&x-signature=E8US22KfUCwKz0R%2FMFF6%2FMOmogs%3D" }, "selection_region": "US", "bio_description": "This is my personal introduction", "follower_count": 2323, "profile_tt_uri": "aweme://user/profile/7200669046446064666?sec_uid=MS4wLjABAAAAvkrSOIMxn2YpXW5qBFVHIbfQ11u2L1hamtgg3mbk5GRPpl1TrnKo5zzQe5T77YLw&from_scene=8&enter_from=scan", "category_ids": [ "60001" ], "top_collaborated_brand_ids": [ "8363021" ], "brand_collaboration_count": 76, "units_sold": 234, "units_sold_range": { "minimum_amount": 100, "maximum_amount": 1000, "formatted_range": "0-10" }, "gmv": { "currency": "USD", "amount": "3434.23" }, "video_gmv": { "currency": "USD", "amount": "39232.34" }, "live_gmv": { "currency": "USD", "amount": "3432.34" }, "gmv_range": { "currency": "USD", "minimum_amount": "1000.00", "maximum_amount": "10000.00", "formatted_range": "$0-$100" }, "ec_live_engagement_rate": "6000", "category_gmv_distribution": [ { "category_id": "66666", "value": "0.3035" } ], "content_gmv_distribution": [ { "content_type": "VIDEO", "value": "0.3035" } ], "product_original_price_range": { "currency": "USD", "minimum_amount": "2.59", "maximum_amount": "343.23" }, "gpm": { "currency": "USD", "amount": "10.23" }, "live_gpm": { "currency": "USD", "amount": "44.96" }, "video_gpm": { "currency": "USD", "amount": "28.89" }, "gpm_range": { "currency": "USD", "minimum_amount": "100.00", "maximum_amount": "1000.00", "formatted_range": "$0-$100" }, "video_gpm_range": { "currency": "USD", "minimum_amount": "100.00", "maximum_amount": "1000.00", "formatted_range": "$0-$100" }, "live_gpm_range": { "currency": "USD", "minimum_amount": "100.00", "maximum_amount": "1000.00", "formatted_range": "$0-$100" }, "promoted_product_num": 311, "ec_live_count": 12, "ec_video_count": 34, "avg_ec_video_play_count": 1234, "avg_commission_rate": 6000, "avg_commission_rate_range": { "minimum_amount": 6000, "maximum_amount": 7000 }, "avg_gmv_per_buyer": { "currency": "USD", "amount": "45.68" }, "avg_gmv_per_buyer_range": { "currency": "USD", "minimum_amount": "100.00", "maximum_amount": "1000.00", "formatted_range": "$15-$20" }, "avg_ec_live_view_count": 4355, "avg_ec_live_like_count": 344, "avg_ec_live_comment_count": 23, "avg_ec_live_share_count": 3434, "avg_ec_video_like_count": 324, "avg_ec_video_comment_count": 343, "avg_ec_video_share_count": 22, "follower_location": [ { "key": "ID", "value": "0.3705" } ], "follower_age": [ { "key": "18-23", "value": "0.2500" } ], "follower_gender": [ { "key": "Male", "value": "0.5000" } ], "pps": "4.5", "rating": "3.2", "ec_video_engagement_rate": "3000", "post_rate": "100", "creator_profile": { "is_official_recommend": false, "contact_info_available": false, "creator_bind_mcn_name": "name", "live_engagement_rate_30d": 50, "video_play_cnt_30d_med": 10, "live_view_cnt_30d_med": 10, "live_like_cnt_30d": 10, "live_comment_cnt_30d_med": 10, "live_share_cnt_30d_med": 10, "video_publish_cnt_30d_med": 10, "has_invited_90d": false, "is_creator_blocked": false, "creator_level": 2, "creator_fulfillment_reviews": 10, "is_eligible_flat_fee": false, "is_rising_star": false, "creator_fulfillment_score_90d": "4.1", "sample_score": 75, "creator_connect_info": { "is_paired": false, "is_connect": false, "is_blocked": false }, "creator_trend_profile": [ { "start_timestamp": 1784419200, "end_timestamp": 1784419200, "gmv": { "amount": "1000", "symbol": "$" }, "units_sold": 1000, "follower": 1000, "engagement_rate": 558 } ] } } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Read Creator Marketplace" ], "x-tts-error-codes": [ { "code": "16032012", "message": "only affiliate partner cipher can access this api" }, { "code": "16901005", "message": "this creator does't have e-commerce permission,please check the request params." }, { "code": "16901006", "message": "creator selection region doesn't match seller's region" }, { "code": "16901007", "message": "The seller could not obtain an official creator profile due to insufficient permissions." }, { "code": "16901008", "message": "The creator didn't didn't have e-commerce permissions or has been deactivated." }, { "code": "16901009", "message": "can't access tiktok linkshare creator" }, { "code": "36009002", "message": "Too many requests. You've made too many requests in a short period of time." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "45101004", "message": "The query quota has been reached (10000 request per day). Please try again tomorrow." }, { "code": "98001004", "message": "Parameter {param_name} is invalid. Reason: {reason}. Expected: {expected_value}" } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-marketplace-creator-performance-202608" } }, "/affiliate_seller/202608/media/upload": { "post": { "operationId": "uploadMessageImageV2", "summary": "Upload Message Image V2", "description": "You must use this API to upload the image first, before sending an image as a message using [Send IM Messsage](https://partner.tiktokshop.com/docv2/page/send-im-message-202412)", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UploadMessageImageV2Request" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadMessageImageV2Response" }, "example": { "code": 0, "data": { "url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/2ca53c34ad8443e6b39f4e0153d3aed4~tplv-o3syd03w52-origin-image.image?from=1320446476", "width": 1280, "height": 720 }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Manage Affiliate Messages" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/upload-message-image-v2-202608" } }, "/affiliate_seller/202608/target_collaborations/creator_promotion_details/query": { "post": { "operationId": "queryCreatorPromotionDetailsInTargetCollaboration", "summary": "Query Creator Promotion Details in Target Collaboration", "description": "Query the creator commission rate, number of promotional video contents and number of live‑stream promotions for specified creator, specified invitation and specified product.", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryCreatorPromotionDetailsInTargetCollaborationRequest" }, "example": { "creator_user_open_id": "abc", "invitation_group_id": "1234", "query": "abc", "query_type": "PRODUCT_ID", "invitation_id": "1234", "product_filter": { "added_types": [ "ALL" ] } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryCreatorPromotionDetailsInTargetCollaborationResponse" }, "example": { "code": 0, "data": { "data": { "product_details": [ { "product_base_info": { "product_id": "1234", "title": "product title", "image": { "url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/2ca53c34ad8443e6b39f4e0153d3aed4~tplv-o3syd03w52-origin-image.image?from=1320446476" }, "price": { "min_price": { "amount": "1", "currency": "GBP" }, "max_price": { "amount": "1", "currency": "GBP" } }, "promotion_price": { "min_price": { "amount": "1", "currency": "GBP" }, "max_price": { "amount": "1", "currency": "GBP" } }, "target_commission": 2200, "open_commission": 2200, "target_ads_commission": 2200, "old_target_commission": 2200, "old_target_ads_commission": 2200, "commission_effective_time": 1786592565735, "ads_commission_effective_time": 1786592565735, "product_status": "1" }, "product_add_status": false, "video_count": 1, "live_count": 1, "is_commission_effective": false } ] } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Manage Seller Affiliate Collaboration", "Read Seller Affiliate Collaboration" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/query-creator-promotion-details-in-target-collaboration-202608" } }, "/affiliate_seller/202610/creator_outreach/eligibility/check": { "post": { "operationId": "checkCreatorOutreachEligibility", "summary": "Check Creator Outreach Eligibility", "description": "Check whether creators meet the shop's connection and quota requirements before initiating creator outreach.", "tags": [ "Affiliate seller" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckCreatorOutreachEligibilityRequest" }, "example": { "creator_infos": [ { "creator_open_id": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg" }, { "creator_open_id": "uBXcdQAAAABnVV3ron5S1wVZvVW4QD7DJCJQ3n6B3-xe88k9S0H1zh" } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckCreatorOutreachEligibilityResponse" }, "example": { "code": 0, "data": { "creator_eligibility_results": [ { "creator_level": 3, "creator_open_id": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg", "is_blocked": false, "is_connected": false, "is_creator_follower_count_threshold_met": true, "is_creator_level_quota_available": false, "is_paired": false }, { "creator_level": 1, "creator_open_id": "uBXcdQAAAABnVV3ron5S1wVZvVW4QD7DJCJQ3n6B3-xe88k9S0H1zh", "is_blocked": false, "is_connected": true, "is_creator_follower_count_threshold_met": true, "is_creator_level_quota_available": true, "is_paired": false } ], "ineligible_creator_levels": [ 3 ], "is_batch_quota_consumable": false }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/check-creator-outreach-eligibility-202610" } }, "/analytics/202403/videos/performances": { "get": { "operationId": "getVideoPerformances", "summary": "Get Video Performances", "description": "Use this US-creator-only API to retrieve TikTok e-commerce video metrics, including anchor_display_rate, click_through_rate, orders, items_sold, and GMV, for the requested videos.", "tags": [ "Analytics" ], "parameters": [ { "name": "video_ids", "in": "query", "required": true, "description": "Comma-separated video IDs for which to retrieve e-commerce metrics. All video IDs must belong to the same author. Maximum: 100 video IDs per request.", "schema": { "type": "string" } }, { "name": "start_time_ge", "in": "query", "required": true, "description": "Start date for the metrics, set with a one-day delay from today due to latency in the data pipeline. The start_time parameter must be within the last 180 days from the current date. Only date value is processed, hour/mininute/second values will be ignored. \nFor example, if the start_time value is: 1703507696 (\"26-12-2023 04:34:56\"), backend service will only consider the part \"26-12-2023\" when doing the query because by default, in offline data analytics, there is no hour/min/sec data level.", "schema": { "type": "integer", "format": "int64" } }, { "name": "end_time_le", "in": "query", "required": true, "description": "End date for the metrics, set with a one-day delay from today due to latency in the data pipeline. Only date value is processed, hour/mininute/second values will be ignored.", "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetVideoPerformancesResponse" }, "example": { "code": 0, "data": { "videos": [ { "id": "7271486684427046149", "performances": [ { "time_range": { "start_time": 1704067200, "end_time": 1704067200 }, "metrics": { "anchor_display_rate": "0.64", "click_through_rate": "0.08", "order_count": 3, "item_sold_count": 3, "gmv": { "amount": "27.85", "currency": "USD" } } } ] } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 4, "x-tts-scopes": [ "Content Posting" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-video-performances-202403" } }, "/analytics/202502/live_rooms/{live_room_id}/core_stats": { "get": { "operationId": "getLiveRoomCoreStats", "summary": "Get Live Room Core Stats", "description": "Returns core stats for the specified live room, including GMV, order counts, buyer counts, product click counts, and view counts.", "tags": [ "Analytics" ], "parameters": [ { "name": "live_room_id", "in": "path", "required": true, "description": "the live stream room id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetLiveRoomCoreStatsResponse" }, "example": { "code": 0, "data": { "stats": { "sales": 123, "local_gmv": { "amount": "123.45", "currency": "USD" }, "created_order_count": 123, "current_visitor_count": 123, "paid_order_count": 123, "local_unit_price": { "amount": "12.34", "currency": "USD" }, "product_reach_count": 123, "watch_pv": 123, "click_through_rate": "0.11", "accumulated_new_follower_count": 123, "buyer_count": 123, "accumulated_comment_count": 123, "product_view_count": 123, "click_order_rate": "0.11", "avg_watching_duration": 123, "accumulated_sharing_count": 123, "peak_concurrent_user_count": 123 } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 4, "x-tts-scopes": [ "Live Data" ], "x-tts-error-codes": [ { "code": "66009302", "message": "Invalid param. Please check room id." }, { "code": "66009315", "message": "No permission for the action." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-live-room-core-stats-202502" } }, "/analytics/202502/live_rooms/{live_room_id}/gmv_trend_performances": { "get": { "operationId": "getLiveRoomGMVAndOrderTrends", "summary": "Get Live Room GMV and Order Trends", "description": "Returns GMV trend performance points for the specified live room, including GMV and created-order trend values.", "tags": [ "Analytics" ], "parameters": [ { "name": "live_room_id", "in": "path", "required": true, "description": "The ID of a live room owned by the authenticated creator.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetLiveRoomGMVAndOrderTrendsResponse" }, "example": { "code": 0, "data": { "gmv_trend_performances": [ { "stats_type": "TREND_GMV", "data_points": [ { "order_count": 123, "timestamp": 1623812664, "gmv": { "currency": "USD", "amount": "123.45" } } ] } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 4, "x-tts-scopes": [ "Live Data" ], "x-tts-error-codes": [ { "code": "66009302", "message": "Invalid param. Please check room id." }, { "code": "66009315", "message": "No permission for the action." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-live-room-gmv-and-order-trends-202502" } }, "/analytics/202502/live_rooms/{live_room_id}/interactive_trend_performances": { "get": { "operationId": "getLiveRoomInteractiveTrends", "summary": "Get Live Room Interactive Trends", "description": "Returns interactive trend performance points for the specified live room, including watch, comment, and share counts.", "tags": [ "Analytics" ], "parameters": [ { "name": "live_room_id", "in": "path", "required": true, "description": "The ID of the live room owned by the authenticated creator.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetLiveRoomInteractiveTrendsResponse" }, "example": { "code": 0, "data": { "interactive_trend_performances": [ { "stats_type": "TREND_WATCH_PV", "data_points": [ { "value": "456", "timestamp": 1623812664 } ] } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 4, "x-tts-scopes": [ "Live Data" ], "x-tts-error-codes": [ { "code": "66009302", "message": "Invalid param. Please check room id." }, { "code": "66009315", "message": "No permission for the action." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-live-room-interactive-trends-202502" } }, "/analytics/202502/live_rooms/{live_room_id}/product_stats": { "get": { "operationId": "getLiveRoomProductStats", "summary": "Get Live Room Product Stats", "description": "Returns product performance statistics for the specified live room, including product IDs, names, GMV, unit price, inventory counts, and click counts. The live room must belong to the creator associated with the access token.", "tags": [ "Analytics" ], "parameters": [ { "name": "live_room_id", "in": "path", "required": true, "description": "live stream room id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetLiveRoomProductStatsResponse" }, "example": { "code": 0, "data": { "product_stats": [ { "main_image_url": "https://example.com/images/products/1732333333333333629-main.jpg", "product_id": "1732333333333333629", "is_live": true, "click_through_rate": "0.11", "sellable_region": "ID", "created_order_count": 123, "exposure_count": 123, "total_click_count": 123, "local_gmv": { "amount": "123.45", "currency": "USD" }, "product_name": "Wireless Charging Stand", "local_unit_price": { "amount": "12.34", "currency": "USD" }, "paid_order_count": 123, "inventory_left_count": 123, "inventory_consumption_count": 123, "created_order_user_count": 123, "paid_user_count": 123, "click_order_rate": "0.11" } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 4, "x-tts-scopes": [ "Live Data" ], "x-tts-error-codes": [ { "code": "66009302", "message": "Invalid param. Please check room id." }, { "code": "66009315", "message": "No permission for the action." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-live-room-product-stats-202502" } }, "/analytics/202502/live_rooms/{live_room_id}/traffic_performances": { "get": { "operationId": "getLiveRoomTrafficPerformance", "summary": "Get Live Room Traffic Performance", "description": "Returns traffic performance for a live room owned by the authenticated creator, including watch counts grouped by primary traffic source and sub-source for distribution analysis.", "tags": [ "Analytics" ], "parameters": [ { "name": "live_room_id", "in": "path", "required": true, "description": "live stream room id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetLiveRoomTrafficPerformanceResponse" }, "example": { "code": 0, "data": { "traffic_performances": [ { "source": { "name": "card_click", "watch_pv": 123 }, "sub_sources": [ { "name": "card_click", "watch_pv": 123 } ] } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 4, "x-tts-scopes": [ "Live Data" ], "x-tts-error-codes": [ { "code": "66009302", "message": "Invalid param. Please check room id." }, { "code": "66009315", "message": "No permission for the action." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-live-room-traffic-performance-202502" } }, "/analytics/202502/live_rooms/{live_room_id}/user_portraits": { "get": { "operationId": "getLiveRoomUserPortraits", "summary": "Get Live Room User Portraits", "description": "Returns user portrait indicators for the specified live room, including age, gender, fan, advertisement, and region distributions.", "tags": [ "Analytics" ], "parameters": [ { "name": "live_room_id", "in": "path", "required": true, "description": "The ID of the live stream room whose user portrait indicators are requested.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetLiveRoomUserPortraitsResponse" }, "example": { "code": 0, "data": { "all_ads_gender_indicators": [ { "type": "USER_PORTRAIT_GENDER_UNKNOWN", "value": "123" } ], "all_fan_indicators": [ { "type": "USER_PORTRAIT_FOLLOWER", "value": "123" } ], "all_ads_age_indicators": [ { "type": "USER_PORTRAIT_AGE_LESS_THAN_15", "value": "123" } ], "region_indicators": [ { "value": "123", "type": "ID" } ], "paid_ads_age_indicators": [ { "type": "USER_PORTRAIT_AGE_LESS_THAN_15", "value": "123" } ], "paid_ads_gender_indicators": [ { "type": "USER_PORTRAIT_GENDER_UNKNOWN", "value": "123" } ], "paid_fan_indicators": [ { "type": "USER_PORTRAIT_FOLLOWER", "value": "123" } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 4, "x-tts-scopes": [ "Live Data" ], "x-tts-error-codes": [ { "code": "66009302", "message": "Invalid param. Please check room id." }, { "code": "66009315", "message": "No permission for the action." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-live-room-user-portraits-202502" } }, "/analytics/202502/live_rooms/{live_room_id}/view_trend_performances": { "get": { "operationId": "getLiveRoomViewTrends", "summary": "Get Live Room View Trends", "description": "Returns viewer count trend data points for the specified live room, grouped by online, entering, and leaving viewers.", "tags": [ "Analytics" ], "parameters": [ { "name": "live_room_id", "in": "path", "required": true, "description": "The ID of the live streaming room whose viewer trend data is requested. The live room must be associated with the authorized creator.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetLiveRoomViewTrendsResponse" }, "example": { "code": 0, "data": { "view_trend_performances": [ { "stats_type": "TREND_ONLINE_VIEWER", "data_points": [ { "value": "123", "timestamp": 1623812664 } ] } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 4, "x-tts-scopes": [ "Live Data" ], "x-tts-error-codes": [ { "code": "66009302", "message": "Invalid param. Please check room id." }, { "code": "66009315", "message": "No permission for the action." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-live-room-view-trends-202502" } }, "/analytics/202509/shop_products/{product_id}/performance": { "get": { "operationId": "getShopProductPerformanceDetail", "summary": "Get Shop Product Performance Detail", "description": "Returns detailed performance metrics for the specified product.", "tags": [ "Analytics" ], "parameters": [ { "name": "product_id", "in": "path", "required": true, "description": "The ID of the product whose performance metrics are requested.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" }, { "name": "start_date_ge", "in": "query", "required": true, "description": "Start date (ISO 8601 YYYY-MM-DD format) in shop registered timezone.\nIn the parameter name, \"ge\" refers to \"greater than or equal to\" (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "end_date_lt", "in": "query", "required": true, "description": "End date of the requested range in the shop's registered timezone, in ISO 8601 `YYYY-MM-DD` format. This date is exclusive and must be later than `start_date_ge`.", "schema": { "type": "string", "format": "date" } }, { "name": "granularity", "in": "query", "required": false, "description": "Granularity of the data.\nAvailable values: ALL, 1D\nDefault value: ALL\n* ALL: aggregate\n* 1D: daily", "schema": { "type": "string", "enum": [ "ALL", "1D" ] } }, { "name": "currency", "in": "query", "required": false, "description": "Currency.\nAvailable values: USD, LOCAL\nDefault value: LOCAL\n* USD: US dollars\n* LOCAL: local currency where the shop is located", "schema": { "type": "string", "enum": [ "USD", "LOCAL" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetShopProductPerformanceDetailResponse" }, "example": { "code": 0, "data": { "performance": { "intervals": [ { "start_date": "2024-04-01", "end_date": "2024-04-08", "sales": { "gmv": { "amount": "233", "currency": "USD" }, "orders": 23, "items_sold": 23, "breakdowns": [ { "content_type": "LIVE", "sales": { "gmv": { "amount": "43", "currency": "USD" }, "items_sold": 454, "avg_customers": 34 } } ] }, "traffic": { "breakdowns": [ { "traffic": { "impressions": 34, "page_views": 43, "avg_unique_page_views": 34, "ctr": "0.034", "avg_conversion_rate": "0.033" }, "content_type": "LIVE" } ] }, "cancel_and_refunds": { "returned": 2, "canceled": 23, "refunded": 3, "replacements": 3 } } ], "ratings": [ { "stars": "1_STAR", "count": 23, "percentage": "0.23" } ], "top_contents": [ { "type": "LIVE", "contents": [ { "content_id": "2304002883", "items_sold": 23, "gmv": { "amount": "323", "currency": "GBP" } } ] } ], "top_creators": [ { "creator_open_id": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg", "creator_name": "nick.name", "creator_profile": "https://www.example.com/images/creator-profile.webp", "gmv": { "amount": "2365", "currency": "GBP" }, "items_sold": 32 } ] }, "latest_available_date": "2024-04-07" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "TikTok Shop Analytics" ], "x-tts-error-codes": [ { "code": "28001007", "message": "can't find any related data; detail: Product not found. Please make sure the product_id you send belongs to a valid product under the current shop." }, { "code": "28001022", "message": "invalid request params; detail: start time or end time is invalid." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-shop-product-performance-detail-202509" } }, "/analytics/202509/shop_skus/performance": { "get": { "operationId": "getShopSKUPerformanceList", "summary": "Get Shop SKU Performance List", "description": "Returns a paginated list of performance metrics for the shop's SKUs over the requested date range.", "tags": [ "Analytics" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "start_date_ge", "in": "query", "required": true, "description": "Start time (ISO 8601 YYYY-MM-DD format) in shop registered timezone, inclusive.", "schema": { "type": "string", "format": "date" } }, { "name": "end_date_lt", "in": "query", "required": true, "description": "End date of the performance period, exclusive, in the shop's registered time zone. Use YYYY-MM-DD format. It must be later than start_date_ge.", "schema": { "type": "string", "format": "date" } }, { "name": "page_size", "in": "query", "required": false, "description": "Number of records per page. If omitted, defaults to 10. Maximum: 100.", "schema": { "type": "integer", "format": "int64", "maximum": 100 } }, { "name": "page_token", "in": "query", "required": false, "description": "Token that identifies the page to retrieve. Omit it for the first page. For later pages, pass the `next_page_token` returned by the previous response and reuse the same `start_date_ge`, `end_date_lt`, `sort_field`, `sort_order`, `category_filter`, `product_status_filter`, `product_ids`, `currency`, and `page_size` values.", "schema": { "type": "string" } }, { "name": "sort_field", "in": "query", "required": false, "description": "Sort field, possible values:\n- gmv (default)\n- sku_orders\n- units_sold", "schema": { "type": "string", "enum": [ "gmv", "sku_orders", "units_sold" ], "x-enum-descriptions": [ "default", "", "" ] } }, { "name": "sort_order", "in": "query", "required": false, "description": "Sort direction, possible values:\n- DESC (default)\n- ASC", "schema": { "type": "string", "enum": [ "DESC", "ASC" ], "x-enum-descriptions": [ "default", "" ] } }, { "name": "category_filter", "in": "query", "required": false, "description": "List of category IDs used to filter returned SKU performance records.", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "product_status_filter", "in": "query", "required": false, "description": "Filter SKUs by product status. Possible values:\n- LIVE\n- INACTIVE\n- ALL (default)", "schema": { "type": "string", "enum": [ "LIVE", "INACTIVE", "ALL" ], "x-enum-descriptions": [ "", "", "default" ] } }, { "name": "product_ids", "in": "query", "required": false, "description": "Filter SKUs by product IDs. If product_ids are provided, the API will only return SKUs for the given product IDs, otherwise it will return all SKUs for the shop", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "currency", "in": "query", "required": false, "description": "Currency used to report GMV:\n- USD: U.S. dollars\n- LOCAL (default): Local currency where the shop is located", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetShopSKUPerformanceListResponse" }, "example": { "code": 0, "data": { "skus": [ { "id": 18354627263453, "product_id": 123456789, "gmv": { "amount": "135.42", "currency": "USD" }, "sku_orders": 10, "units_sold": 10 } ], "next_page_token": "cGFnZV9udW1iZXI9MQ==", "total_count": 20, "latest_available_date": "2024-04-07" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "TikTok Shop Analytics" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-shop-sku-performance-list-202509" } }, "/analytics/202509/shop_skus/{sku_id}/performance": { "get": { "operationId": "getShopSKUPerformanceDetail", "summary": "Get Shop SKU Performance Detail", "description": "Returns performance metrics for the specified SKU.", "tags": [ "Analytics" ], "parameters": [ { "name": "sku_id", "in": "path", "required": true, "description": "The ID of the SKU whose performance metrics are requested.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" }, { "name": "start_date_ge", "in": "query", "required": true, "description": "Start time (ISO 8601 YYYY-MM-DD format) in shop registered timezone, inclusive.", "schema": { "type": "string", "format": "date" } }, { "name": "end_date_lt", "in": "query", "required": true, "description": "End date (ISO 8601 YYYY-MM-DD format) in shop registered timezone, exclusive. It must be later than start_date_ge.", "schema": { "type": "string", "format": "date" } }, { "name": "granularity", "in": "query", "required": false, "description": "Granularity of the data.\nAvailable values: ALL, 1D\nDefault value: ALL\n* ALL: aggregate\n* 1D: daily", "schema": { "type": "string", "enum": [ "ALL", "1D" ] } }, { "name": "currency", "in": "query", "required": false, "description": "Currency:\n- USD: US dollars\n- LOCAL (default): Local currency where the shop is located", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetShopSKUPerformanceDetailResponse" }, "example": { "code": 0, "data": { "latest_available_date": "2024-04-07", "performance": { "product_id": 123456789, "sku_id": "123456789", "intervals": [ { "start_date": "2024-04-01", "end_date": "2024-04-07", "gmv": { "amount": "135.42", "currency": "USD" }, "gmv_breakdown": [ { "amount": "82.15", "currency": "USD", "type": "LIVE" } ], "items_sold": 10, "items_sold_breakdown": [ { "amount": 10, "type": "LIVE" } ], "sku_orders": 10 } ] } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "TikTok Shop Analytics" ], "x-tts-error-codes": [ { "code": "28001007", "message": "can't find any related data; detail: Product not found. Please make sure the product_id you send belongs to a valid product under the current shop." }, { "code": "28001022", "message": "invalid request params; detail: start time or end time is invalid." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-shop-sku-performance-detail-202509" } }, "/analytics/202509/shop_videos/{video_id}/performance": { "get": { "operationId": "getShopVideoPerformanceDetails", "summary": "Get Shop Video Performance Details", "description": "Returns detailed performance metrics for a (requested) video.", "tags": [ "Analytics" ], "parameters": [ { "name": "video_id", "in": "path", "required": true, "description": "The ID of the shop video whose performance details are requested.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" }, { "name": "start_date_ge", "in": "query", "required": true, "description": "Start date (ISO 8601 YYYY-MM-DD format) in shop registered timezone.\nIn the parameter name, \"ge\" refers to \"greater than or equal to\" (inclusive)\n\nThe time range between start and end must not exceed 60 days.", "schema": { "type": "string", "format": "date" } }, { "name": "end_date_lt", "in": "query", "required": true, "description": "End date (ISO 8601 YYYY-MM-DD format) in shop registered timezone.\nIn the parameter name, \"lt\" refers to \"less than\" (exclusive)\n\nThe time range between start and end must not exceed 60 days.", "schema": { "type": "string", "format": "date" } }, { "name": "granularity", "in": "query", "required": false, "description": "Granularity of the data.\nAvailable values: ALL, 1D\nDefault value: ALL\n* ALL: aggregate\n* 1D: daily", "schema": { "type": "string", "enum": [ "ALL", "1D" ] } }, { "name": "currency", "in": "query", "required": false, "description": "Currently, only local currency is supported in the response.\n\nAvailable values: USD, LOCAL\nDefault value: LOCAL\n* USD: US dollars\n* LOCAL: local currency where the shop is located", "schema": { "type": "string", "enum": [ "USD", "LOCAL" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetShopVideoPerformanceDetailsResponse" }, "example": { "code": 0, "data": { "performance": { "intervals": [ { "start_date": "2024-09-01", "end_date": "2024-09-08", "sales": { "overall": { "gmv": { "amount": "230.02", "currency": "USD" }, "gpm": { "amount": "1.02", "currency": "USD" }, "customers": 12, "items_sold": 22, "ctr": "0.029", "product_impressions": 32092, "product_clicks": 21232 }, "breakdowns": [ { "product_id": "19332235", "gmv": { "amount": "230.02", "currency": "USD" }, "gpm": { "amount": "1.02", "currency": "USD" }, "customers": 12, "items_sold": 22, "ctr": "0.029", "product_impressions": 32092, "product_clicks": 21232 } ] }, "traffic": { "views": 76649, "new_followers": 11, "shares": 23, "comments": 8, "likes": 2 } } ], "viewer_profile": [ { "type": "VIEWERS", "gender_distribution": [ { "gender": "MALE", "percentage": "0.349" } ], "age_distribution": [ { "age": "25-34", "percentage": "0.293" } ], "country_distribution": [ { "country_code": "MY", "percentage": "0.993" } ] } ] }, "latest_available_date": "2024-09-07" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "TikTok Shop Analytics" ], "x-tts-error-codes": [ { "code": "28001022", "message": "invalid request params; detail: start time or end time is invalid." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-shop-video-performance-details-202509" } }, "/analytics/202509/shop_videos/{video_id}/products/performance": { "get": { "operationId": "getShopVideoProductPerformanceList", "summary": "Get Shop Video Product Performance List", "description": "Returns performance metrics for a list of products promoted in a given video.", "tags": [ "Analytics" ], "parameters": [ { "name": "video_id", "in": "path", "required": true, "description": "The ID of the shop video whose promoted product performance list is requested.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" }, { "name": "end_date_lt", "in": "query", "required": true, "description": "End date (ISO 8601 YYYY-MM-DD format) in shop registered timezone. It must be later than start_date_ge.\nIn the parameter name, \"lt\" refers to \"less than\" (exclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "page_size", "in": "query", "required": false, "description": "Number of products per page.\nMin value: 1\nMax value: 100\nDefault value: 10", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 100 } }, { "name": "sort_field", "in": "query", "required": false, "description": "Sort on.\nAvailable values: gmv, units_sold, daily_avg_buyers\nDefault value: gmv", "schema": { "type": "string", "enum": [ "gmv", "units_sold", "daily_avg_buyers" ] } }, { "name": "sort_order", "in": "query", "required": false, "description": "Sort direction.\nAvailable values: ASC, DESC\nDefault value: DESC\n* ASC: ascending\n* DESC: descending", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] } }, { "name": "currency", "in": "query", "required": false, "description": "Currency.\nAvailable values: USD, LOCAL\nDefault value: LOCAL\n* USD: US dollars\n* LOCAL: local currency where the shop is located", "schema": { "type": "string", "enum": [ "USD", "LOCAL" ] } }, { "name": "page_token", "in": "query", "required": false, "description": "Page token, indicating the current position. Used for requesting next page data.\nLeave this field empty for first time queries.", "schema": { "type": "string" } }, { "name": "start_date_ge", "in": "query", "required": true, "description": "Start date (ISO 8601 YYYY-MM-DD format) in shop registered timezone.\nIn the parameter name, \"ge\" refers to \"greater than or equal to\" (inclusive)", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetShopVideoProductPerformanceListResponse" }, "example": { "code": 0, "data": { "latest_available_date": "2024-09-07", "next_page_token": "cGFnZV9udW1iZXI9MQ==", "products": [ { "ctr": "0", "customers": 0, "daily_avg_buyers": "0", "gmv": { "amount": "0", "currency": "USD" }, "gpm": { "amount": "0", "currency": "USD" }, "id": "105xxxxxxxxxxxxx247", "name": "Product Name", "product_clicks": 0, "product_impressions": 0, "units_sold": 0 } ], "total_count": 10 }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "TikTok Shop Analytics" ], "x-tts-error-codes": [ { "code": "28001022", "message": "invalid request params; detail: start time or end time is invalid." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-shop-video-product-performance-list-202509" } }, "/analytics/202510/shop/performance/{date}/performance_per_hour": { "get": { "operationId": "getShopPerformancePerHour", "summary": "Get Shop Performance Per Hour", "description": "Returns hourly shop performance details for the requested date. The date can be within the last 30 days, including today.", "tags": [ "Analytics" ], "parameters": [ { "name": "date", "in": "path", "required": true, "description": "(ISO 8601 YYYY-MM-DD format) in shop registered timezone.", "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/ShopCipher" }, { "name": "currency", "in": "query", "required": false, "description": "Currency.\nAvailable values: USD, LOCAL\nDefault value: LOCAL\n* USD: US dollars\n* LOCAL: local currency where the shop is located", "schema": { "type": "string", "enum": [ "USD", "LOCAL" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetShopPerformancePerHourResponse" }, "example": { "code": 0, "data": { "performance": { "intervals": [ { "avg_order_value": { "amount": "2.29", "currency": "USD" }, "avg_sku_order_value": { "amount": "2.29", "currency": "USD" }, "customers": 223, "customers_count": 7, "gmv": { "amount": "2332.22", "currency": "SGD" }, "index": 2, "items_sold": 23, "live_attributed_gmv": { "amount": "0.00", "currency": "USD" }, "orders_count": 13, "product_card_attributed_gmv": { "amount": "29.71", "currency": "USD" }, "product_clicks": 12654, "product_impressions": 86234, "sku_orders_count": 13, "unique_clicks": 8342, "unique_product_impressions": 52314, "video_attributed_gmv": { "amount": "0.00", "currency": "USD" }, "visitors": 2332 } ], "latest_available_timestamp": 1623812664, "overall": { "avg_order_value": { "amount": "2.29", "currency": "USD" }, "avg_sku_order_value": { "amount": "2.29", "currency": "USD" }, "customers": 2332, "customers_count": 7, "gmv": { "amount": "2344.00", "currency": "SGD" }, "items_sold": 543, "live_attributed_gmv": { "amount": "0.00", "currency": "USD" }, "orders_count": 13, "product_card_attributed_gmv": { "amount": "29.71", "currency": "USD" }, "product_clicks": 12654, "product_impressions": 86234, "sku_orders_count": 13, "unique_clicks": 8342, "unique_product_impressions": 52314, "video_attributed_gmv": { "amount": "0.00", "currency": "USD" }, "visitors": 234324 } } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "TikTok Shop Analytics" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-shop-performance-per-hour-202510" } }, "/analytics/202510/shop_lives/{live_id}/performance_per_minutes": { "get": { "operationId": "getShopLIVEMinutePerformance", "summary": "Get Shop LIVE Minute Performance", "description": "Returns minute-level performance for a LIVE session after the session is finished. This API only returns data for live streams hosted by the shop official account or marketing account.", "tags": [ "Analytics" ], "parameters": [ { "name": "live_id", "in": "path", "required": true, "description": "TTS LIVE session ID", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" }, { "name": "page_token", "in": "query", "required": false, "description": "Token that identifies the page to retrieve. Omit it for the first page; for later pages, pass the next_page_token returned by the previous response.", "schema": { "type": "string" } }, { "name": "currency", "in": "query", "required": false, "description": "Currency for monetary values. Use USD for US dollars or LOCAL for the local currency where the shop is registered. If omitted, the shop's local currency is used.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetShopLIVEMinutePerformanceResponse" }, "example": { "code": 0, "data": { "performance": { "overall": { "live_title": "BAJU BARU!!!", "start_time": 1623812664, "end_time": 1623812664, "duration": 3600, "gmv": { "amount": "39440.00", "currency": "USD" }, "items_sold": 432, "unique_viewers": 10230, "impressions": 87939 }, "intervals": [ { "start_time": 1623812664, "end_time": 1623812664, "sales": { "gmv": { "amount": "39440.00", "currency": "USD" }, "items_sold": 57, "customers": 49, "sku_orders": 57, "main_orders": 51 }, "traffic": { "viewers": 229, "views": 2092, "product_impressions": 8989, "ctr": "0.3264", "enter_room_rate": "0.1636", "product_clicks": 595, "impressions": 13862 }, "interactions": { "new_followers": 9, "shares": 4, "comments": 42, "likes": 1146, "comment_rate": "0.0242", "follow_rate": "0.0040", "like_rate": "0.8956", "share_rate": "0.0022" }, "conversion": { "avg_price": { "amount": "7.29", "currency": "SGD" }, "click_to_order_rate": { "sku_order_ctor": "0.0187", "main_order_ctor": "0.015757" }, "gpm": { "watch_gpm": "158.18", "show_gpm": "20.75" }, "created_sku_orders": 12, "sku_order_rate": "0.0057" } } ] }, "next_page_token": "cGFnZV9udW1iZXI9MQ==", "total_count": 20 }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "TikTok Shop Analytics" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-shop-live-minute-performance-202510" } }, "/analytics/202511/creators/bestselling": { "get": { "operationId": "getBestsellingCreators", "summary": "Get Bestselling Creators", "description": "Returns up to 100 creators, filtered by `author_type`, ranked by GMV in the selected `currency` for the reporting period ending on `date` and defined by `time_slot`.", "tags": [ "Analytics" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "date", "in": "query", "required": true, "description": "The inclusive end date of the reporting period, in ISO 8601 YYYY-MM-DD format and the shop's registered timezone. The period extends backward from this date according to `time_slot` (for example, `7D` covers the seven days ending on this date). The date must not be later than the latest available date; when a later date is submitted, the error message identifies the latest available date.", "schema": { "type": "string", "format": "date" } }, { "name": "time_slot", "in": "query", "required": true, "description": "The length of the query period ending on `date`. Supported values are:\n- 1D — 1 day\n- 7D — 7 days\n- 30D — 30 days", "schema": { "type": "string", "enum": [ "1D", "7D", "30D" ], "x-enum-descriptions": [ "1 day", "7 days", "30 days" ] } }, { "name": "author_type", "in": "query", "required": true, "description": "The creator type to include. Supported values are:\n- ALL — include all creator types\n- OFFICIAL — include official creators\n- CHANNEL — include channel creators\n- AFFILIATE — include affiliate creators", "schema": { "type": "string", "enum": [ "ALL", "OFFICIAL", "CHANNEL", "AFFILIATE" ], "x-enum-descriptions": [ "include all creator types", "include official creators", "include channel creators", "include affiliate creators" ] } }, { "name": "currency", "in": "query", "required": false, "description": "Currency for monetary values. Supported values are:\n- USD — US dollars\n- LOCAL — the local currency where the shop is registered\nIf omitted, defaults to LOCAL.", "schema": { "type": "string", "enum": [ "USD", "LOCAL" ], "x-enum-descriptions": [ "US dollars", "the local currency where the shop is registered" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBestsellingCreatorsResponse" }, "example": { "code": 0, "data": { "creators": [ { "rank": 1, "gmv_range": "$97000.00~$191000.00", "open_id": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg", "user_name": "creator_example_01", "nick_name": "abc_bec", "followers_count": 11234, "likes_count": 23342 } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Bestsellers" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-bestselling-creators-202511" } }, "/analytics/202511/lives/bestselling": { "get": { "operationId": "getBestsellingLIVESessions", "summary": "Get Bestselling LIVE Sessions", "description": "Get up to 100 LIVE sessions ranked by GMV for the period defined by `date` and `time_slot`.", "tags": [ "Analytics" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "date", "in": "query", "required": false, "description": "The reference date, in ISO 8601 YYYY-MM-DD format and the shop's registered timezone. The period ends on this date, inclusive, and extends backward according to `time_slot` (for example, `7D` covers the seven days ending on this date). The date must be on or before the latest available data date. If a later date is submitted, the error response states the latest available data date; retry the request with that date or an earlier one.", "schema": { "type": "string", "format": "date" } }, { "name": "time_slot", "in": "query", "required": false, "description": "Specifies the query time range. Supported values are:\n\n- 1D: query data for 1 day\n\n- 7D: query data for 7 days\n\n- 30D: query data for 30 days\n\nThis field determines the maximum range that can be queried using the date field.", "schema": { "type": "string", "enum": [ "1D", "7D", "30D" ], "x-enum-descriptions": [ "query data for 1 day", "query data for 7 days", "query data for 30 days" ] } }, { "name": "currency", "in": "query", "required": false, "description": "Currency for monetary values. Use USD for US dollars or LOCAL for the local currency where the shop is registered. If omitted, this parameter defaults to LOCAL.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBestsellingLIVESessionsResponse" }, "example": { "code": 0, "data": { "lives": [ { "rank": 1, "gmv_range": "$97000.00~$191000.00", "id": "399123", "title": "Dude's deal", "start_time": 1623812664, "duration": 7602, "creator_name": "abc_bec", "open_id": "41YL0AAAAAD7kUt1BK3H07WBF3MZWzCgL79vJ-xBgswGeL2BCGdmeQ", "creator_nick_name": "ttnickname" } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Bestsellers" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-bestselling-live-sessions-202511" } }, "/analytics/202511/products/bestselling": { "get": { "operationId": "getBestsellingProducts", "summary": "Get Bestselling Products", "description": "Returns up to 100 products ranked by GMV for the target date range.", "tags": [ "Analytics" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "category_id", "in": "query", "required": false, "description": "Filter products by a Level 1 category ID.", "schema": { "type": "string" } }, { "name": "date", "in": "query", "required": true, "description": "The inclusive end date of the query period, in ISO 8601 YYYY-MM-DD format and the shop's registered time zone. The period spans the selected time_slot and ends on this date (for example, 7D queries the seven days ending on this date). The date must be on or before the latest available date. If a request uses a later date, the error response identifies the latest available date; retry with that date or an earlier date.", "schema": { "type": "string", "format": "date" } }, { "name": "time_slot", "in": "query", "required": true, "description": "The length of the query period ending on date. Supported values are:\n- 1D — 1 day\n- 7D — 7 days\n- 30D — 30 days", "schema": { "type": "string", "enum": [ "1D", "7D", "30D" ], "x-enum-descriptions": [ "1 day", "7 days", "30 days" ] } }, { "name": "currency", "in": "query", "required": false, "description": "Currency for monetary values. Use USD for US dollars or LOCAL for the local currency where the shop is registered. Default: LOCAL.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBestsellingProductsResponse" }, "example": { "code": 0, "data": { "products": [ { "rank": 1, "gmv_range": "$97000.00~$191000.00", "id": "123456", "name": "Labubu", "rating": "4.5", "product_image": { "height": 2000, "width": 2000, "thumb_urls": [ "tos-useast5-i-omjb5zjo8w-tx/cad4b7c7409f459a87c54baf31ff8a20" ], "uri": "tos-useast5-i-omjb5zjo8w-tx/cad4b7c7409f459a87c54baf31ff8a20", "urls": [ "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/157d5bf9ac5a4af5855a2284626605c8~tplv-o3syd03w52-origin-jpeg.jpeg" ] }, "shop_name": "Nia Batik", "shop_id": "7028916274713380866" } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Bestsellers" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-bestselling-products-202511" } }, "/analytics/202511/videos/bestselling": { "get": { "operationId": "getBestsellingVideos", "summary": "Get Bestselling Videos", "description": "Returns up to 100 videos ranked by gross merchandise value (GMV) in descending order for the date range selected by `date` and `time_slot`.", "tags": [ "Analytics" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "date", "in": "query", "required": true, "description": "The reference date (ISO 8601 YYYY-MM-DD format) in the shop's registered timezone. The query calculates data backwards from this date based on `time_slot` (for example, `7D` returns data for the 7 days ending on this date). This date is inclusive and must be on or before the latest available data date.", "schema": { "type": "string", "format": "date" } }, { "name": "time_slot", "in": "query", "required": true, "description": "The length of the query period ending on `date`. Supported values are:\n\n- 1D: 1 day\n\n- 7D: 7 days\n\n- 30D: 30 days", "schema": { "type": "string", "enum": [ "1D", "7D", "30D" ], "x-enum-descriptions": [ "1 day", "7 days", "30 days" ] } }, { "name": "currency", "in": "query", "required": false, "description": "Currency for monetary values. Use `USD` for US dollars or `LOCAL` for the local currency where the shop is registered. If omitted, the default is `LOCAL`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBestsellingVideosResponse" }, "example": { "code": 0, "data": { "videos": [ { "rank": 1, "id": "10484583", "nick_name": "abc_bec", "gmv_range": "$97000.00~$191000.00", "views": 939829, "likes": 83894, "comments": 1934, "shares": 223, "product_infos": [ { "product_id": "1731736614984386107", "product_name": "labubu" } ], "publish_time": 1623812664, "duration": 7602 } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Bestsellers" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-bestselling-videos-202511" } }, "/analytics/202512/shop/{live_id}/products_performance": { "get": { "operationId": "getShopLIVEProductsPerformanceList", "summary": "Get Shop LIVE Products Performance List", "description": "Returns sale performance for each product in a shop-related LIVE session from the official account or marketing accounts.", "tags": [ "Analytics" ], "parameters": [ { "name": "live_id", "in": "path", "required": true, "description": "TTS LIVE session ID", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" }, { "name": "sort_order", "in": "query", "required": false, "description": "Sort direction.\n\nAvailable values: ASC, DESC\n\nDefault value: DESC\n\n* ASC: ascending\n\n* DESC: descending", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] } }, { "name": "sort_field", "in": "query", "required": false, "description": "Field to sort on.\n\nAvailable values:\n- gmv\n- items_sold\n- customers\n- created_sku_orders\n- sku_orders\n- main_orders\n- product_impressions\n- product_clicks\n\nDefault value: gmv", "schema": { "type": "string", "enum": [ "gmv", "items_sold", "customers", "created_sku_orders", "sku_orders", "main_orders", "product_impressions", "product_clicks" ] } }, { "name": "currency", "in": "query", "required": false, "description": "Currency for monetary values. Use USD for US dollars or LOCAL for the local currency where the shop is registered.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetShopLIVEProductsPerformanceListResponse" }, "example": { "code": 0, "data": { "products": [ { "id": "1731736614984386107", "name": "PANDAEYES \nWAHIDA \nKNITWEAR \nCARDIGAN (CLO-CNSNSL97002BL)", "sales": { "direct_gmv": { "currency": "SGD", "amount": "737.97" }, "items_sold": 24, "customers": 24, "created_sku_orders": 27, "avg_price": { "currency": "SGD", "amount": "30.75" }, "sku_orders": 24, "main_orders": 24, "payment_rate": "0.8888" }, "traffic": { "product_impressions": 14815, "ctr": "0.0908", "add_to_cart_count": 102, "click_to_order_rate": { "sku_order_ctor": "0.0178", "main_order_ctor": "0.0178" }, "gpm": { "watch_gpm": "49.81" }, "produt_clicks": 1346 } } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "TikTok Shop Analytics" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-shop-live-products-performance-list-202512" } }, "/analytics/202605/shop_products/performance": { "get": { "operationId": "getShopProductPerformanceList", "summary": "Get Shop Product Performance List", "description": "Returns a paginated list of shop products and their total, seller-channel, affiliate-channel, and Shop Tab performance metrics for the specified date range.", "tags": [ "Analytics" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "start_date_ge", "in": "query", "required": true, "description": "Start date (ISO 8601 YYYY-MM-DD format) in shop registered timezone.\nIn the parameter name, \"ge\" refers to \"greater than or equal to\" (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "end_date_lt", "in": "query", "required": true, "description": "End date of the requested range in the shop's registered timezone, in ISO 8601 `YYYY-MM-DD` format. This date is exclusive and must be later than `start_date_ge`.", "schema": { "type": "string", "format": "date" } }, { "name": "page_size", "in": "query", "required": false, "description": "Number of products per page.\nMax value: 100\nDefault value: 10", "schema": { "type": "integer", "format": "int64", "maximum": 100 } }, { "name": "page_token", "in": "query", "required": false, "description": "Page token, indicating the current position. Used for requesting next page data.\nLeave this field empty for first time queries.", "schema": { "type": "string" } }, { "name": "sort_field", "in": "query", "required": false, "description": "Field to sort on.\nDefault: gmv\nAvailable values:\n- gmv\n- items_sold\n- orders", "schema": { "type": "string", "enum": [ "gmv", "items_sold", "orders" ] } }, { "name": "sort_order", "in": "query", "required": false, "description": "Sort direction.\nAvailable values: ASC, DESC\nDefault value: DESC\n* ASC: ascending\n* DESC: descending", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] } }, { "name": "currency", "in": "query", "required": false, "description": "Currency.\nAvailable values: USD, LOCAL\nDefault value: LOCAL\n* USD: US dollars\n* LOCAL: local currency where the shop is located", "schema": { "type": "string", "enum": [ "USD", "LOCAL" ] } }, { "name": "category_filter", "in": "query", "required": false, "description": "Level 1 category IDs used to filter the returned shop product performance list.", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "product_status_filter", "in": "query", "required": false, "description": "Product status filter.\n\nAvailable values:\n\n- LIVE: live products\n\n- INACTIVE: inactive products\n\n- ALL: all product statuses; this is the default", "schema": { "type": "string", "enum": [ "LIVE", "INACTIVE", "ALL" ], "x-enum-descriptions": [ "live products", "inactive products", "all product statuses; this is the default" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetShopProductPerformanceListResponse" }, "example": { "code": 0, "data": { "products": [ { "id": "1732333333333333629", "total_performance": { "gmv": { "amount": "395.03", "currency": "GBP" }, "orders": 12, "sku_orders": 12, "items_sold": 12, "estimated_customers": 10, "aov": { "amount": "32.92", "currency": "GBP" }, "product_impressions": 5420, "product_clicks": 438, "ctr": "0.0808", "add_cart_count": 57, "add_cart_rate": "0.1301", "click_order_rate": "0.0274", "unique_product_impressions": 4890, "unique_clicks": 401, "unique_ctr": "0.082", "add_cart_users": 45, "unique_atc_rate": "0.1122", "unique_click_order_rate": "0.0299", "gmv_incl_tax": { "amount": "426.63", "currency": "GBP" }, "tax": { "amount": "31.6", "currency": "GBP" }, "gross_merchandise_value": { "amount": "395.03", "currency": "GBP" }, "shipping_fees": { "amount": "18.5", "currency": "GBP" }, "refunds": { "amount": "24.99", "currency": "GBP" }, "refunded_items": 1, "refund_customers": 1 }, "seller_live_performance": { "attributed_gmv": { "amount": "142.8", "currency": "GBP" }, "attributed_orders": 4, "attributed_sku_orders": 4, "attributed_sold_items": 5, "estimated_customers": 4, "aov": { "amount": "35.7", "currency": "GBP" }, "new_live_count": 2, "product_impressions": 1680, "product_clicks": 156, "ctr": "0.0929", "add_cart_count": 21, "add_cart_rate": "0.1346", "click_order_rate": "0.0256", "unique_product_impressions": 1510, "unique_clicks": 141, "unique_ctr": "0.0934", "add_cart_users": 17, "unique_atc_rate": "0.1206", "unique_click_order_rate": "0.0284" }, "seller_video_performance": { "attributed_gmv": { "amount": "96.45", "currency": "GBP" }, "attributed_orders": 3, "attributed_sku_orders": 3, "attributed_sold_items": 3, "estimated_customers": 3, "aov": { "amount": "32.15", "currency": "GBP" }, "new_video_count": 3, "product_impressions": 2140, "product_clicks": 173, "ctr": "0.0808", "add_cart_count": 19, "add_cart_rate": "0.1098", "click_order_rate": "0.0173", "unique_product_impressions": 1985, "unique_clicks": 160, "unique_ctr": "0.0806", "add_cart_users": 15, "unique_atc_rate": "0.0938", "unique_click_order_rate": "0.0188" }, "seller_product_card_performance": { "attributed_gmv": { "amount": "118.6", "currency": "GBP" }, "attributed_orders": 4, "attributed_sku_orders": 5, "attributed_sold_items": 4, "estimated_customers": 4, "aov": { "amount": "29.65", "currency": "GBP" }, "product_impressions": 1600, "product_clicks": 109, "ctr": "0.0681", "add_cart_count": 17, "add_cart_rate": "0.156", "click_order_rate": "0.0367", "unique_product_impressions": 1395, "unique_clicks": 100, "unique_ctr": "0.0717", "add_cart_users": 13, "unique_atc_rate": "0.13", "unique_click_order_rate": "0.04" }, "affiliate_total_performance": { "attributed_gmv": { "amount": "204.3", "currency": "GBP" }, "attributed_orders": 6, "attributed_sku_orders": 6, "attributed_sold_items": 7, "estimated_customers": 5, "aov": { "amount": "34.05", "currency": "GBP" }, "avg_daily_creator_posted_content": 8, "product_impressions": 3840, "product_clicks": 265, "ctr": "0.069", "add_cart_count": 31, "add_cart_rate": "0.117", "click_order_rate": "0.0226", "unique_product_impressions": 3410, "unique_clicks": 238, "unique_ctr": "0.0698", "add_cart_users": 24, "unique_atc_rate": "0.1008", "unique_click_order_rate": "0.0252" }, "affiliate_live_performance": { "live_attributed_gmv": { "amount": "121.4", "currency": "GBP" }, "new_live_count": 3, "product_impressions": 1320, "product_clicks": 102, "ctr": "0.0773", "add_cart_count": 14, "add_cart_rate": "0.1373", "click_order_rate": "0.0294", "unique_product_impressions": 1208, "unique_clicks": 94, "unique_ctr": "0.0778", "atc_users": 12, "unique_atc_rate": "0.1277", "unique_click_order_rate": "0.0319" }, "affiliate_video_performance": { "attributed_video_gmv": { "amount": "82.9", "currency": "GBP" }, "new_video_count": 5, "product_impressions": 2520, "product_clicks": 163, "ctr": "0.0647", "add_cart_count": 17, "add_cart_rate": "0.1043", "click_order_rate": "0.0184", "unique_product_impressions": 2202, "unique_clicks": 144, "unique_ctr": "0.0654", "atc_users": 12, "unique_atc_rate": "0.0833", "unique_click_order_rate": "0.0208" }, "shop_tab_performance": { "shop_tab_product_impressions": 2520, "shop_tab_product_clicks": 245, "unique_shop_tab_product_clicks": 210, "estimated_shop_tab_customers": 18, "shop_tab_ctr": "0.1551", "shop_tab_ctor_sku": "0.0735", "shop_tab_gmv": { "amount": "128.4", "currency": "GBP" }, "shop_tab_sold_items": 4 } } ], "next_page_token": "cGFnZV9udW1iZXI9MQ==", "total_count": 10, "latest_available_date": "2024-04-07" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "TikTok Shop Analytics" ], "x-tts-error-codes": [ { "code": "28001022", "message": "invalid request params; detail: start time or end time is invalid." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-shop-product-performance-list-202605" } }, "/analytics/202605/shop_videos/performance": { "get": { "operationId": "getShopVideoPerformanceList", "summary": "Get Shop Video Performance List", "description": "Returns a list of videos and associated metrics for a shop.", "tags": [ "Analytics" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "start_date_ge", "in": "query", "required": true, "description": "Start date (ISO 8601 YYYY-MM-DD format) in shop registered timezone.\nIn the parameter name, \"ge\" refers to \"greater than or equal to\" (inclusive)\n\nThe time range between start and end must not exceed 60 days.", "schema": { "type": "string", "format": "date" } }, { "name": "end_date_lt", "in": "query", "required": true, "description": "End date (ISO 8601 YYYY-MM-DD format) in shop registered timezone.\nIn the parameter name, \"lt\" refers to \"less than\" (exclusive).\n\nThe time range between start and end must not exceed 60 days.", "schema": { "type": "string", "format": "date" } }, { "name": "page_size", "in": "query", "required": false, "description": "Number of videos per page.\nMinimum value: 1\nMaximum value: 100\nDefault value: 10", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 100 } }, { "name": "sort_field", "in": "query", "required": false, "description": "Field used to sort the shop video performance list.\nDefault value: gmv\nAvailable values:\n- gmv: sort by overall Gross Merchandise Value (GMV).\n- gpm: sort by average GMV generated from 1,000 views.\n- avg_customers: sort by daily average customers.\n- sku_orders: sort by paid SKU orders.\n- items_sold: sort by units sold.\n- views: sort by video views.\n- click_through_rate: sort by the ratio of product clicks to video views.\n- post_time: sort by the time the video was posted.", "schema": { "type": "string", "enum": [ "gmv", "gpm", "avg_customers", "sku_orders", "items_sold", "views", "click_through_rate", "post_time" ], "x-enum-descriptions": [ "sort by overall Gross Merchandise Value (GMV).", "sort by average GMV generated from 1,000 views.", "sort by daily average customers.", "sort by paid SKU orders.", "sort by units sold.", "sort by video views.", "sort by the ratio of product clicks to video views.", "sort by the time the video was posted." ] } }, { "name": "sort_order", "in": "query", "required": false, "description": "Sort direction.\nAvailable values: ASC, DESC\nDefault value: DESC\n* ASC: ascending\n* DESC: descending", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] } }, { "name": "currency", "in": "query", "required": false, "description": "Currently, only local currency is supported in the response.\n\nAvailable values: USD, LOCAL\nDefault value: LOCAL\n* USD: US dollars\n* LOCAL: local currency where the shop is located", "schema": { "type": "string", "enum": [ "USD", "LOCAL" ] } }, { "name": "page_token", "in": "query", "required": false, "description": "Page token, indicating the current position. Used for requesting next page data.\nLeave this field empty for first time queries.", "schema": { "type": "string" } }, { "name": "account_type", "in": "query", "required": false, "description": "Types of the accounts under which videos were created.\nAvailable values: ALL, OFFICIAL_ACCOUNTS, MARKETING_ACCOUNTS, AFFILIATE_ACCOUNTS\nDefault value: ALL\n- ALL: all account types\n- OFFICIAL_ACCOUNTS: official accounts\n- MARKETING_ACCOUNTS: marketing accounts\n- AFFILIATE_ACCOUNTS: affiliate accounts", "schema": { "type": "string", "enum": [ "ALL", "OFFICIAL_ACCOUNTS", "MARKETING_ACCOUNTS", "AFFILIATE_ACCOUNTS" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetShopVideoPerformanceListResponse" }, "example": { "code": 0, "data": { "latest_available_date": "2024-09-07", "next_page_token": "cGFnZV9udW1iZXI9MQ==", "total_count": 10, "videos": [ { "advertisable": true, "attributed_gmv": { "amount": "125.50", "currency": "USD" }, "avg_customers": 35, "click_through_rate": "0.0525", "comments": 12, "creator": { "author_type": "OFFICIAL", "creator_country": "US", "creator_id": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg", "nick_name": "abc_bec", "open_id": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg", "user_name": "creator_shop_01" }, "ctor": "0.0528", "duration": 34, "gmv": { "amount": "125.50", "currency": "USD" }, "gpm": { "amount": "32.40", "currency": "USD" }, "hash_tags": [ "#racuntiktok", "fyp" ], "id": "172xxxxxxxxxxxxx089", "indirect_gmv": { "amount": "125.50", "currency": "USD" }, "items_sold": 18, "likes": 86, "new_followers": 10, "product_clicks": 63, "product_impressions": 1200, "products": [ { "id": "105xxxxxxxxxxxxx247", "name": "Wireless Earbuds" } ], "review_type": "IMPROVEMENT", "shares": 8, "sku_orders": 12, "title": "How to Style Summer Outfits", "username": "creator_shop_01", "v_to_l_clicks": 42, "v_to_l_rate": "0.0350", "video_finish_rate": "0.3800", "video_post_time": "2025-01-01 00:00:00", "views": 1200 } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "TikTok Shop Analytics" ], "x-tts-error-codes": [ { "code": "28001022", "message": "invalid request params; detail: start time or end time is invalid." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-shop-video-performance-list-202605" } }, "/analytics/202606/shop_performances/metrics": { "get": { "operationId": "getSPSMetrics", "summary": "Get SPS Metrics", "description": "Returns SPS metric details and benchmark thresholds for the authorized shop. \nShop Performance Score (SPS) reflects a shop’s performance across key operational and service metrics on TikTok Shop. By integrating the read-only SPS APIs, ISVs can retrieve a shop’s score, tier, benefits, and metric benchmarks, diagnose performance gaps, and drill down to the products, logistics providers, aftersales types, orders, or chats associated with specific issues. This enables ISVs to embed actionable performance insights into their solutions, helping merchants identify problem areas faster and take targeted actions to improve shop performance. Available only for US-region shops.\nUse case guide: [Click here](https://partner.tiktokshop.com/docv2/page/ph0ccose)", "tags": [ "Analytics" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "locale", "in": "query", "required": false, "description": "BCP 47 locale code used to localize response text. If omitted, the default locale is resolved from the request context.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSPSMetricsResponse" }, "example": { "code": 0, "data": { "metrics": [ { "benchmarks": { "excellent_threshold": "0.02", "poor_threshold": "0.08" }, "dimension": "Product satisfaction", "evaluate_duration_days": 30, "end_evaluation_time": 1761264000, "start_evaluation_time": 1758672000, "metric_code": "NRR", "metric_name": "60-day negative review rate", "score": "4.7", "status": "EXCELLENT", "status_text": "Excellent", "value": "0.97", "value_unit": "PERCENT", "top_reason_text": "Top opportunity" } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "TikTok Shop Analytics" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-sps-metrics-202606" } }, "/analytics/202606/shop_performances/metrics/{metric_code}/diagnosis": { "get": { "operationId": "getSPSMetricDiagnosis", "summary": "Get SPS Metric Diagnosis", "description": "Returns diagnosis details for a single SPS metric, including benchmark thresholds, trends, calculation details, and distribution details. \nShop Performance Score (SPS) reflects a shop’s performance across key operational and service metrics on TikTok Shop. By integrating the read-only SPS APIs, ISVs can retrieve a shop’s score, tier, benefits, and metric benchmarks, diagnose performance gaps, and drill down to the products, logistics providers, aftersales types, orders, or chats associated with specific issues. This enables ISVs to embed actionable performance insights into their solutions, helping merchants identify problem areas faster and take targeted actions to improve shop performance. Available only for US-region shops.\nUse case guide: [Click here](https://partner.tiktokshop.com/docv2/page/ph0ccose)", "tags": [ "Analytics" ], "parameters": [ { "name": "metric_code", "in": "path", "required": true, "description": "Metric code. Possible values: NRR, NBFR, SFCR, OTDR, AHT, and IM_DSAT.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" }, { "name": "locale", "in": "query", "required": false, "description": "BCP 47 locale code used to localize response text. If omitted, the default locale is resolved from the request context.", "schema": { "type": "string" } }, { "name": "trend_duration_days", "in": "query", "required": false, "description": "Number of days to look back for metric trend data. The value must be from 1 to 90. Default: 30.", "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSPSMetricDiagnosisResponse" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "TikTok Shop Analytics" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-sps-metric-diagnosis-202606" } }, "/analytics/202606/shop_performances/metrics/{metric_code}/problem_details": { "get": { "operationId": "getSPSMetricProblemDetails", "summary": "Get SPS Metric Problem Details", "description": "Returns problem order or chat details for a selected SPS metric. \nShop Performance Score (SPS) reflects a shop’s performance across key operational and service metrics on TikTok Shop. By integrating the read-only SPS APIs, ISVs can retrieve a shop’s score, tier, benefits, and metric benchmarks, diagnose performance gaps, and drill down to the products, logistics providers, aftersales types, orders, or chats associated with specific issues. This enables ISVs to embed actionable performance insights into their solutions, helping merchants identify problem areas faster and take targeted actions to improve shop performance. Available only for US-region shops.\nUse case guide: [Click here](https://partner.tiktokshop.com/docv2/page/ph0ccose)", "tags": [ "Analytics" ], "parameters": [ { "name": "metric_code", "in": "path", "required": true, "description": "Metric code. Possible values: NRR, NBFR, SFCR, OTDR, AHT, and IM_DSAT.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" }, { "name": "locale", "in": "query", "required": false, "description": "BCP 47 locale code used to localize response text. If omitted, the default locale is resolved from the request context.", "schema": { "type": "string" } }, { "name": "page_token", "in": "query", "required": false, "description": "For the first page, leave this parameter empty. For later pages, pass the opaque `next_page_token` returned by the previous response unchanged and use the same `page_size`.", "schema": { "type": "string" } }, { "name": "page_size", "in": "query", "required": false, "description": "The number of results to return per page. Minimum value is 1. Default value is 10. Maximum value is 50.", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSPSMetricProblemDetailsResponse" }, "example": { "code": 0, "data": { "aht_problem_order_items": [ { "aftersales_type_name": "Only Return", "approve_duration_hours": "12.5", "inspect_duration_hours": "30.0", "order_id": "576461413038785752", "return_order_id": "576461413038785753", "review_count": 2, "total_handle_duration_hours": "42.5" } ], "im_dsat_chat_items": [ { "chat_duration_hours": "1.5", "chat_record_id": "745961413038785752", "customer_name": "J*** D***", "customer_rating": 2, "first_reply_time": 1761264060, "rating_reasons": [ "other" ], "service_agent": "Agent A" } ], "metric_code": "NRR", "nbfr_problem_order_items": [ { "deliver_time": 1761523200, "order_create_time": 1761264000, "order_id": "576461413038785752", "product_id": "1729592969712207010", "product_name": "Cotton T-Shirt", "return_refund_reason": "Wrong size", "sku_id": "1729592969712207013" } ], "next_page_token": "2", "nrr_problem_order_items": [ { "deliver_time": 1761523200, "order_create_time": 1761264000, "order_id": "576461413038785752", "product_id": "1729592969712207008", "product_name": "Wireless Headphones", "sku_id": "1729592969712207012", "user_review_rating": 2 } ], "otdr_problem_order_items": [ { "actual_deliver_time": 1761609600, "expect_deliver_time": 1761523200, "order_id": "576461413038785752", "product_name": "Wireless Headphones", "sku_id": "1729592969712207014" } ], "sfcr_problem_order_items": [ { "cancellation_reasons": [ "Defective item" ], "order_create_time": 1761264000, "order_id": "576461413038785752", "product_id": "1729592969712207011", "product_name": "Smart Watch", "sku_id": "1729592969712207014" } ], "total_count": 200 }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "TikTok Shop Analytics" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-sps-metric-problem-details-202606" } }, "/analytics/202606/shop_performances/metrics/{metric_code}/top_items": { "get": { "operationId": "getSPSMetricTopItems", "summary": "Get SPS Metric Top Items", "description": "Returns the top products for NRR, NBFR, or AHT, or the top logistics providers for OTDR.\nShop Performance Score (SPS) reflects a shop’s performance across key operational and service metrics on TikTok Shop. By integrating the read-only SPS APIs, ISVs can retrieve a shop’s score, tier, benefits, and metric benchmarks, diagnose performance gaps, and drill down to the products, logistics providers, aftersales types, orders, or chats associated with specific issues. This enables ISVs to embed actionable performance insights into their solutions, helping merchants identify problem areas faster and take targeted actions to improve shop performance. Available only for US-region shops.\nUse case guide: [Click here](https://partner.tiktokshop.com/docv2/page/ph0ccose)", "tags": [ "Analytics" ], "parameters": [ { "name": "metric_code", "in": "path", "required": true, "description": "Metric code that selects the returned top-items list:\n- NRR: products with negative reviews (`nrr_top_product_items`).\n- NBFR: products with returns or refunds (`nbfr_top_product_items`).\n- OTDR: logistics providers and their on-time delivery performance (`otdr_logistics_items`).\n- AHT: products and their aftersales handling details (`aht_aftersales_type_items`).", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" }, { "name": "locale", "in": "query", "required": false, "description": "BCP 47 locale code used to localize response text. If omitted, the default locale is resolved from the request context.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSPSMetricTopItemsResponse" }, "example": { "code": 0, "data": { "aht_aftersales_type_items": [ { "handle_duration_hours": "18.5", "product_id": "1729592969712207011", "product_name": "Smart Watch", "return_order_count": 30, "top_aftersales_type_name": "Only Refund", "top_type_order_count": 20, "image_url": "https://example.com/product.jpg" } ], "metric_code": "NRR", "nbfr_top_product_items": [ { "product_id": "1729592969712207010", "product_name": "Cotton T-Shirt", "return_order_count": 8, "top_reason_order_count": 5, "top_return_reasons": [ "Item doesn't match description" ], "image_url": "https://example.com/product.jpg" } ], "nrr_top_product_items": [ { "delivered_order_count": 300, "image_url": "https://example.com/product.jpg", "negative_order_count": 12, "product_id": "1729592969712207008", "product_name": "Wireless Headphones", "top_review_reasons": [ "Item doesn't match description" ] } ], "otdr_logistics_items": [ { "delivered_order_count": 1000, "logistics_provider": "TikTok Shipping", "on_time_deliver_order_count": 947, "on_time_deliver_rate": "0.947" } ], "total_count": 120 }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "TikTok Shop Analytics" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-sps-metric-top-items-202606" } }, "/analytics/202606/shop_performances/overview": { "get": { "operationId": "getSPSOverview", "summary": "Get SPS Overview", "description": "Returns the SPS overview for the authorized shop, including the score, tier, dimensions, benefits, and top issues. \nShop Performance Score (SPS) reflects a shop’s performance across key operational and service metrics on TikTok Shop. By integrating the read-only SPS APIs, ISVs can retrieve a shop’s score, tier, benefits, and metric benchmarks, diagnose performance gaps, and drill down to the products, logistics providers, aftersales types, orders, or chats associated with specific issues. This enables ISVs to embed actionable performance insights into their solutions, helping merchants identify problem areas faster and take targeted actions to improve shop performance. Available only for US-region shops.\nUse case guide: [Click here](https://partner.tiktokshop.com/docv2/page/ph0ccose)", "tags": [ "Analytics" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "locale", "in": "query", "required": false, "description": "BCP 47 locale code used to localize response text. If omitted, the default locale is resolved from the request context.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSPSOverviewResponse" }, "example": { "code": 0, "data": { "benefits": [ { "benefit_name": "LIVE giveaway", "is_unlocked": true, "unlock_score": "4.5" } ], "dimensions": [ { "name": "Product satisfaction", "score": "4.8", "status": "EXCELLENT", "status_text": "Excellent", "weight": "70" } ], "evaluate_duration_days": 90, "end_evaluation_time": 1782518400, "start_evaluation_time": 1774828800, "peer_percentile": "86.5", "primary_category": { "category_id": "601450", "category_name": "Home Supplies" }, "sps_score": "4.6", "sps_tier": "GOOD", "sps_tier_text": "Excellent", "top_issues": { "issues": [ { "description": "Your on-time delivery performance is lower than peer shops.", "evaluate_duration_days": 31, "end_evaluation_time": 1761264000, "start_evaluation_time": 1758672000, "metric_code": "OTDR", "metric_name": "On-time delivery rate", "percentile": "72.4", "rank": 1 } ], "summary": "Improve late dispatch and negative reviews to increase your SPS score." }, "update_time": 1761264000 }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "TikTok Shop Analytics" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-sps-overview-202606" } }, "/analytics/202609/shop/performance": { "get": { "operationId": "getShopPerformance", "summary": "Get Shop Performance", "description": "Returns performance metrics at shop/seller level.", "tags": [ "Analytics" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "start_date_ge", "in": "query", "required": true, "description": "Start date (ISO 8601 YYYY-MM-DD format) in shop registered timezone.\nIn the parameter name, \"ge\" refers to \"greater than or equal to\" (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "end_date_lt", "in": "query", "required": true, "description": "End date (ISO 8601 YYYY-MM-DD format) in shop registered timezone.\nIn the parameter name, \"lt\" refers to \"less than\" (exclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "granularity", "in": "query", "required": false, "description": "Granularity of the data.\nAvailable values: ALL, 1D\nDefault value: ALL\n* ALL: aggregate\n* 1D: daily", "schema": { "type": "string", "enum": [ "ALL", "1D" ] } }, { "name": "currency", "in": "query", "required": false, "description": "Currently, only local currency is supported in the response.\n\nAvailable values: USD, LOCAL\nDefault value: LOCAL\n* USD: US dollars\n* LOCAL: local currency where the shop is located", "schema": { "type": "string", "enum": [ "USD", "LOCAL" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetShopPerformanceResponse" }, "example": { "code": 0, "data": { "latest_available_date": "2024-04-07", "performance": { "intervals": [ { "breakdowns": { "affiliate_product_card_attributed_gmv": { "amount": "2363.83", "currency": "USD" }, "content_breakdown": [ { "channel": "CREATOR", "content_type": "LIVE", "gmv": { "amount": "0.00", "currency": "USD" }, "indirect_gmv": { "amount": "0.00", "currency": "USD" } } ], "seller_product_card_gmv": { "amount": "2363.83", "currency": "USD" }, "shop_tab_and_search": { "others": { "amount": "0.00", "currency": "USD" }, "search_attributed": { "amount": "1484.40", "currency": "USD" }, "shop_tab_attributed": { "amount": "879.43", "currency": "USD" } } }, "end_date": "2024-04-08", "sales": { "avg_order_value": { "amount": "2.29", "currency": "USD" }, "avg_sku_order_value": { "amount": "2.29", "currency": "USD" }, "cancellations_and_returns": 0, "creator_live_attributed_gmv": { "amount": "0.00", "currency": "USD" }, "creator_live_gmv": { "amount": "0.00", "currency": "USD" }, "creator_live_indirect_gmv": { "amount": "0.00", "currency": "USD" }, "creator_video_attributed_gmv": { "amount": "0.00", "currency": "USD" }, "creator_video_gmv": { "amount": "0.00", "currency": "USD" }, "creator_video_indirect_gmv": { "amount": "0.00", "currency": "USD" }, "customers_count": 7, "gmv": { "amount": "29.71", "currency": "USD" }, "gmv_with_tax": { "amount": "0.00", "currency": "USD" }, "gmv_with_tiktok_co_funding": { "amount": "0.00", "currency": "USD" }, "items_sold": 13, "live_attributed_gmv": { "amount": "0.00", "currency": "USD" }, "live_gmv": { "amount": "0.00", "currency": "USD" }, "live_indirect_gmv": { "amount": "0.00", "currency": "USD" }, "orders_count": 13, "product_card_attributed_gmv": { "amount": "0.00", "currency": "USD" }, "refunds": { "amount": "0.00", "currency": "USD" }, "seller_live_attributed_gmv": { "amount": "0.00", "currency": "USD" }, "seller_live_gmv": { "amount": "0.00", "currency": "USD" }, "seller_live_indirect_gmv": { "amount": "0.00", "currency": "USD" }, "seller_video_attributed_gmv": { "amount": "0.00", "currency": "USD" }, "seller_video_gmv": { "amount": "0.00", "currency": "USD" }, "seller_video_indirect_gmv": { "amount": "0.00", "currency": "USD" }, "shipping_fees": { "amount": "0.00", "currency": "USD" }, "sku_orders_count": 13, "tax": { "amount": "0.00", "currency": "USD" }, "video_attributed_gmv": { "amount": "0.00", "currency": "USD" }, "video_gmv": { "amount": "0.00", "currency": "USD" }, "video_indirect_gmv": { "amount": "0.00", "currency": "USD" } }, "start_date": "2024-04-01", "traffic": { "avg_conversation_rate": "0.3342", "avg_page_views": 56234, "avg_visitors": 3433, "product_clicks": 12654, "product_impressions": 86234, "unique_clicks": 8342, "unique_product_impressions": 52314 } } ] } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "TikTok Shop Analytics" ], "x-tts-error-codes": [ { "code": "28001022", "message": "invalid request params; detail: start time or end time is invalid." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-shop-performance-202609" } }, "/analytics/202609/shop_lives/overview_performance": { "get": { "operationId": "getShopLIVEPerformanceOverview", "summary": "Get Shop LIVE Performance Overview", "description": "Returns overall performance metrics for all LIVE stream sessions under a certain shop.", "tags": [ "Analytics" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "start_date_ge", "in": "query", "required": true, "description": "Start date (ISO 8601 YYYY-MM-DD format) in shop registered timezone.\nIn the parameter name, \"ge\" refers to \"greater than or equal to\" (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "end_date_lt", "in": "query", "required": true, "description": "End date (ISO 8601 YYYY-MM-DD format) in shop registered timezone.\nIn the parameter name, \"lt\" refers to \"less than\" (exclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "today", "in": "query", "required": false, "description": "If \"today\" is set to true, start_date_ge and end_date_lt will be overwritten.\nThe response will contain real-time metrics of today (local time)", "schema": { "type": "boolean" } }, { "name": "granularity", "in": "query", "required": false, "description": "Granularity of the data.\nAvailable values:\n- ALL: Aggregate data for the full requested time range.\n- 1D: Daily data.\nDefault value: ALL", "schema": { "type": "string", "enum": [ "ALL", "1D" ], "x-enum-descriptions": [ "Aggregate data for the full requested time range.", "Daily data." ] } }, { "name": "currency", "in": "query", "required": false, "description": "Currently, only local currency is supported in the response.\n\nAvailable values:\n- USD: US dollars.\n- LOCAL: Local currency where the shop is located.\nDefault value: LOCAL", "schema": { "type": "string", "enum": [ "USD", "LOCAL" ], "x-enum-descriptions": [ "US dollars.", "Local currency where the shop is located." ] } }, { "name": "account_type", "in": "query", "required": false, "description": "Types of the accounts under which videos were created.\nAvailable values:\n- ALL: All account types.\n- LINKED_ACCOUNTS: Linked accounts.\n- AFFILIATE_ACCOUNTS: Affiliate accounts.\nDefault value: ALL", "schema": { "type": "string", "enum": [ "ALL", "LINKED_ACCOUNTS", "AFFILIATE_ACCOUNTS" ], "x-enum-descriptions": [ "All account types.", "Linked accounts.", "Affiliate accounts." ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetShopLIVEPerformanceOverviewResponse" }, "example": { "code": 0, "data": { "latest_available_date": "2024-09-07", "performance": { "intervals": [ { "avg_live_auction_price": { "amount": "0.00", "currency": "USD" }, "avg_viewing_duration": 0, "ctor_sku_order": "0.0000", "end_date": "2026-09-02", "live_attributed_gmv": { "amount": "0.00", "currency": "USD" }, "live_attributed_items_sold": 0, "live_attributed_sku_orders": 0, "live_auction_attributed_gmv": { "amount": "0.00", "currency": "USD" }, "live_auction_attributed_items_sold": 0, "live_auction_attributed_sku_orders": 0, "live_ctr": "0.0000", "live_gmv": { "amount": "0.00", "currency": "USD" }, "live_indirect_gmv": { "amount": "0.00", "currency": "USD" }, "show_gpm": { "amount": "0.00", "currency": "USD" }, "start_date": "2026-08-27", "views": 0 } ] }, "updated_at": "2026-09-02 21:25:00" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "TikTok Shop Analytics" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-shop-live-performance-overview-202609" } }, "/analytics/202609/shop_lives/performance": { "get": { "operationId": "getShopLIVEPerformanceList", "summary": "Get Shop LIVE Performance List", "description": "Returns a list of LIVE stream sessions and associated metrics for a shop. Sellers can only query room ID data for their own official creator accounts.", "tags": [ "Analytics" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "start_date_ge", "in": "query", "required": true, "description": "Start date (ISO 8601 YYYY-MM-DD format) in shop registered timezone.\nIn the parameter name, \"ge\" refers to \"greater than or equal to\" (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "end_date_lt", "in": "query", "required": true, "description": "End date (ISO 8601 YYYY-MM-DD format) in shop registered timezone.\nIn the parameter name, \"lt\" refers to \"less than\" (exclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "account_type", "in": "query", "required": true, "description": "Types of the accounts under which videos were created.\nAvailable values:\n- OFFICIAL_ACCOUNTS: Official accounts.\n- MARKETING_ACCOUNTS: Marketing accounts.\n- AFFILIATE_ACCOUNTS: Affiliate accounts.", "schema": { "type": "string", "enum": [ "OFFICIAL_ACCOUNTS", "MARKETING_ACCOUNTS", "AFFILIATE_ACCOUNTS" ], "x-enum-descriptions": [ "Official accounts.", "Marketing accounts.", "Affiliate accounts." ] } }, { "name": "page_size", "in": "query", "required": false, "description": "Number of products per page.\nMax value: 100\nDefault value: 10", "schema": { "type": "integer", "format": "int64", "maximum": 100 } }, { "name": "sort_field", "in": "query", "required": false, "description": "Field to sort on.\nDefault: live_attributed_gmv\nAvailable values:\n- live_attributed_gmv\n- products_added\n- products_sold\n- live_attributed_sku_orders\n- live_attributed_items_sold\n- attributed_customers", "schema": { "type": "string", "enum": [ "live_attributed_gmv", "products_added", "products_sold", "live_attributed_sku_orders", "live_attributed_items_sold", "attributed_customers" ] } }, { "name": "sort_order", "in": "query", "required": false, "description": "Sort direction.\nAvailable values:\n- ASC: Ascending order.\n- DESC: Descending order.\nDefault value: DESC", "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "x-enum-descriptions": [ "Ascending order.", "Descending order." ] } }, { "name": "currency", "in": "query", "required": false, "description": "Currency.\nAvailable values:\n- USD: US dollars.\n- LOCAL: Local currency where the shop is located.\nDefault value: LOCAL", "schema": { "type": "string", "enum": [ "USD", "LOCAL" ], "x-enum-descriptions": [ "US dollars.", "Local currency where the shop is located." ] } }, { "name": "page_token", "in": "query", "required": false, "description": "Page token, indicating the current position. Used for requesting next page data.\nLeave this field empty for first time queries.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetShopLIVEPerformanceListResponse" }, "example": { "code": 0, "data": { "latest_available_date": "2024-09-07", "live_stream_sessions": [ { "creator": { "author_type": "OFFICIAL", "creator_country": "US", "nick_name": "abc_bec", "open_id": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg", "user_name": "creator_shop_01" }, "end_time": "1623812864", "id": "75xxxxxxxxxxxxxxx28", "interaction_performance": { "comment_rate": "0.0047", "comments": 534, "follow_rate": "0.0007", "like_rate": "0.0216", "likes": 2442, "new_followers": 12, "share_rate": "0.0014", "shares": 156 }, "sales_performance": { "aov": { "amount": "19.80", "currency": "USD" }, "attributed_customers": 50, "avg_live_auction_price": { "amount": "0.00", "currency": "USD" }, "avg_price": { "amount": "9", "currency": "USD" }, "created_sku_orders": 100, "gmv_with_tiktok_coupons": { "amount": "105.00", "currency": "USD" }, "live_attributed_gmv": { "amount": "99.00", "currency": "USD" }, "live_attributed_items_sold": 122, "live_attributed_orders": 60, "live_attributed_sku_orders": 80, "live_auction_attributed_gmv": { "amount": "0.00", "currency": "USD" }, "live_auction_attributed_items_sold": 0, "live_auction_attributed_sku_orders": 0, "live_auction_gmv": { "amount": "0.00", "currency": "USD" }, "live_auction_indirect_gmv": { "amount": "0.00", "currency": "USD" }, "live_gmv": { "amount": "99.00", "currency": "USD" }, "live_indirect_gmv": { "amount": "0.00", "currency": "USD" }, "payment_rate": "0.8000", "products_sold": 5 }, "start_time": "1623812664", "title": "abxxxxx", "traffic": { "acu": 123, "avg_viewing_duration": 46, "avg_viewing_duration_per_viewer": 284, "ctor": "0.0129", "ctor_sku_order": "0.0206", "ctr": "0.0290", "gmv_per_hour": { "amount": "49.50", "currency": "USD" }, "impressions": 130000, "impressions_per_hour": 65000, "live_ctr": "0.1399", "order_rate_sku_orders": "0.0044", "over_1m_live_viewing_rate": "0.1774", "over_1m_views": 3250, "pcu": 1332, "product_clicks": 3882, "product_impressions": 27749, "products_added": 12, "show_gpm": { "amount": "0.76", "currency": "USD" }, "tap_through_rate": "0.8692", "viewers": 18323, "views": 112993, "watch_gpm": { "amount": "0.88", "currency": "USD" } } } ], "next_page_token": "cGFnZV9udW1iZXI9MQ==", "total_count": 233, "updated_at": "2026-09-02 21:52:00" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "TikTok Shop Analytics" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-shop-live-performance-list-202609" } }, "/analytics/202609/shop_videos/batch_performance": { "get": { "operationId": "getShopVideosPerformanceDetails", "summary": "Get Shop Videos Performance Details", "description": "Returns detailed performance metrics for the requested videos.", "tags": [ "Analytics" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "video_ids", "in": "query", "required": true, "description": "The IDs of the shop videos whose performance details are requested.", "explode": false, "schema": { "type": "array", "items": { "type": "integer", "format": "int64" } } }, { "name": "start_date_ge", "in": "query", "required": true, "description": "Start date (ISO 8601 YYYY-MM-DD format) in shop registered timezone.\nIn the parameter name, \"ge\" refers to \"greater than or equal to\" (inclusive)\n\nThe time range between start and end must not exceed 60 days.", "schema": { "type": "string", "format": "date" } }, { "name": "end_date_lt", "in": "query", "required": true, "description": "End date (ISO 8601 YYYY-MM-DD format) in shop registered timezone.\nIn the parameter name, \"lt\" refers to \"less than\" (exclusive)\n\nThe time range between start and end must not exceed 60 days.", "schema": { "type": "string", "format": "date" } }, { "name": "granularity", "in": "query", "required": false, "description": "Granularity of the data.\nAvailable values: ALL, 1D\nDefault value: ALL\n* ALL: aggregate\n* 1D: daily", "schema": { "type": "string", "enum": [ "ALL", "1D" ] } }, { "name": "currency", "in": "query", "required": false, "description": "Currently, only local currency is supported in the response.\n\nAvailable values: USD, LOCAL\nDefault value: LOCAL\n* USD: US dollars\n* LOCAL: local currency where the shop is located", "schema": { "type": "string", "enum": [ "USD", "LOCAL" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetShopVideosPerformanceDetailsResponse" }, "example": { "code": 0, "data": { "latest_available_date": "2024-09-07", "videos": [ { "error": { "code": "300001", "message": "Invalid video ID." }, "performance": { "intervals": [ { "end_date": "2024-09-08", "sales": { "overall": { "ctr": "0.029", "customers": 12, "gmv": { "amount": "230.02", "currency": "USD" }, "gpm": { "amount": "230.02", "currency": "USD" }, "items_sold": 22, "product_clicks": 21232, "product_impressions": 32092 } }, "start_date": "2024-09-01", "traffic": { "comments": 8, "likes": 2, "new_followers": 11, "shares": 23, "views": 76649 } } ], "viewer_profile": [ { "age_distribution": [ { "age": "25-34", "percentage": "0.293" } ], "country_distribution": [ { "country_code": "MY", "percentage": "0.993" } ], "gender_distribution": [ { "gender": "MALE", "percentage": "0.349" } ], "type": "VIEWERS" } ] }, "video": { "duration": 10, "id": "7523456789012345678", "play_url": "`https://example.com/video.mp4`", "thumbnail_url": "`https://example.com/thumbnail.jpg`", "title": "`Summer collection`", "username": "`shop_creator`", "video_post_time": "1725148800" }, "video_id": "7523456789012345678" } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "TikTok Shop Analytics" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-shop-videos-performance-details-202609" } }, "/analytics/202609/shop_videos/overview_performance": { "get": { "operationId": "getShopVideoPerformanceOverview", "summary": "Get Shop Video Performance Overview", "description": "Returns overall performance metrics for all videos under a shop.", "tags": [ "Analytics" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "start_date_ge", "in": "query", "required": true, "description": "Start date (ISO 8601 YYYY-MM-DD format) in shop registered timezone.\nIn the parameter name, \"ge\" refers to \"greater than or equal to\" (inclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "end_date_lt", "in": "query", "required": true, "description": "End date (ISO 8601 YYYY-MM-DD format) in shop registered timezone.\nIn the parameter name, \"lt\" refers to \"less than\" (exclusive)", "schema": { "type": "string", "format": "date" } }, { "name": "today", "in": "query", "required": false, "description": "If \"today\" is set to true, start_date_ge and end_date_lt will be overwritten.\nThe response will contain real-time metrics of today (local time)", "schema": { "type": "boolean" } }, { "name": "granularity", "in": "query", "required": false, "description": "Granularity of the data.\nAvailable values: ALL, 1D\nDefault value: ALL\n* ALL: aggregate\n* 1D: daily", "schema": { "type": "string", "enum": [ "ALL", "1D" ] } }, { "name": "currency", "in": "query", "required": false, "description": "Currently, only local currency is supported in the response.\n\nCurrency.\nAvailable values: USD, LOCAL\nDefault value: LOCAL\n* USD: US dollars\n* LOCAL: local currency where the shop is located", "schema": { "type": "string", "enum": [ "USD", "LOCAL" ] } }, { "name": "account_type", "in": "query", "required": false, "description": "Types of the accounts under which videos were created.\nAvailable values:\n- ALL: All account types.\n- OFFICIAL_ACCOUNTS: Official accounts.\n- MARKETING_ACCOUNTS: Marketing accounts.\n- AFFILIATE_ACCOUNTS: Affiliate accounts.\nDefault value: ALL", "schema": { "type": "string", "enum": [ "ALL", "OFFICIAL_ACCOUNTS", "MARKETING_ACCOUNTS", "AFFILIATE_ACCOUNTS" ], "x-enum-descriptions": [ "All account types.", "Official accounts.", "Marketing accounts.", "Affiliate accounts." ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetShopVideoPerformanceOverviewResponse" }, "example": { "code": 0, "data": { "latest_available_date": "2024-09-08", "performance": { "intervals": [ { "avg_daily_customers": 23, "ctor_sku_order": "0.0528", "ctr": "0.0528", "end_date": "2024-09-08", "gpm": { "amount": "0.00", "currency": "USD" }, "product_clicks": 23, "product_impressions": 23, "shoppable_video_attributed_gmv": { "amount": "0.00", "currency": "USD" }, "start_date": "2024-09-01", "today": false, "video_attributed_gmv": { "amount": "246.80", "currency": "USD" }, "video_attributed_sku_orders": 13, "video_gmv": { "amount": "0.00", "currency": "USD" }, "video_indirect_gmv": { "amount": "0.00", "currency": "USD" }, "video_product_viewers": 500, "video_views": 1000 } ] } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "TikTok Shop Analytics" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-shop-video-performance-overview-202609" } }, "/authorization/202309/shops": { "get": { "operationId": "getAuthorizedShops", "summary": "Get Authorized Shops", "description": "Retrieves the list of shops that a seller has authorized for an app.\nSeller authorization is required before an app can access the data of a shop. Use this API to check which shops are currently authorized for an app and obtain the corresponding shop cipher for use as an input parameter in shop related APIs. \nFor more information about seller authorization, refer to [Seller authorization guide](https://partner.tiktokshop.com/docv2/page/678e3a344ddec3030b238fa0).\nTarget seller: All", "tags": [ "Authorization" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAuthorizedShopsResponse" }, "example": { "code": 0, "data": { "shops": [ { "id": "7000714532876273420", "name": "Maomao beauty shop", "region": "GB", "seller_type": "CROSS_BORDER", "cipher": "GCP_XF90igAAAABh00qsWgtvOiGFNqyubMt3", "code": "CNGBCBA4LLU8" } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 2, "x-tts-scopes": [ "FS Order&Fulfillment Management", "Shop Authorized Information" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-authorized-shops-202309" } }, "/authorization/202405/category_assets": { "get": { "operationId": "getAuthorizedCategoryAssets", "summary": "Get Authorized Category Assets", "description": "Retrieves the list of business category assets authorized by a partner for an app.\nPartner authorization is required before an app can access the data of a partner, and this access is granted based on business categories. Use this API to check which business category assets are currently authorized for an app and obtain the corresponding category asset cipher for use as an input parameter in affiliate partner related APIs. \nFor more information about partner authorization, refer to [Partner authorization guide](678e3a3978f4c20311b8b555).\nTarget partner: All", "tags": [ "Authorization" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAuthorizedCategoryAssetsResponse" }, "example": { "code": 0, "data": { "category_assets": [ { "cipher": "TTP_XF90igAAAABh0sddwer0qsWgt233vOiG", "target_market": "US", "category": { "id": 3, "name": "Customer Support" } } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 7, "x-tts-scopes": [ "Partner Authorized Information" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-authorized-category-assets-202405" } }, "/customer_engagement/202412/engagement_tasks": { "post": { "operationId": "createEngagementTask", "summary": "Create Engagement Task", "description": "Create an engagement task that acts as a container for grouping messages with similar content and rules, allowing sellers to track and compare task performance across different types of content.\nNote that each task has a mandatory end time, and once expired, it cannot be used to send additional messages.", "tags": [ "Customer engagement" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "idempotency_key", "in": "query", "required": true, "description": "A unique key to recognize a request and prevent duplicate processing of the same request, especially in cases of connection issues. Ensure this key is unique for each request to avoid accidental duplicates.\n**Note**: We recommend that you generate v4 UUIDs for use as keys.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEngagementTaskRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEngagementTaskResponse" }, "example": { "code": 0, "data": { "task_id": "475910475643" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Customer Engagement - Write" ], "x-tts-error-codes": [ { "code": "68009001", "message": "Access denied. This endpoint is not available for this shop as the seller does not meet the access criteria for CRM features. See TikTok Shop Academy for details." }, { "code": "68009005", "message": "Failed to create an engagement task. Error details:" } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/create-engagement-task-202412" } }, "/customer_engagement/202412/message_templates": { "get": { "operationId": "getMessageTemplates", "summary": "Get Message Templates", "description": "Get a library of customer engagement message templates predefined by TikTok Shop, which you can use directly in your customer engagement communications.", "tags": [ "Customer engagement" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "locale", "in": "query", "required": true, "description": "The BCP-47 locale codes for displaying the message content, delimited by commas.\n\nRefer to [Locale codes](678e3a47bae28f030a8c7523) for the list of supported locale codes.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMessageTemplatesResponse" }, "example": { "code": 0, "data": { "message_templates": [ { "id": "123456789_987654321", "message_title": "Meet your next favorite thing!", "message_body": "We strive to create products with you in mind. Check out our newest drop to find your perfect fit that’s built for a confidence boost.", "product_card_rules": { "min_count": 0, "max_count": 4 }, "coupon_card_rules": { "min_count": 1, "max_count": 1, "coupon_type": [ "REGULAR_ALL", "REGULAR_REPEAT" ] } } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Customer Engagement - Read" ], "x-tts-error-codes": [ { "code": "68009001", "message": "Access denied. This endpoint is not available for this shop as the seller does not meet the access criteria for CRM features. See TikTok Shop Academy for details." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-message-templates-202412" } }, "/customer_engagement/202412/messages": { "post": { "operationId": "sendEngagementMessage", "summary": "Send Engagement Message", "description": "Send messages to specific customers for a particular engagement task.", "tags": [ "Customer engagement" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEngagementMessageRequest" }, "example": { "buyer_emails": [ "v43424bDOUSGKQQ7YLNEGXPED3CNCQO24@scs.tiktokw.us", "v4b1232DOUSGKQQ7YLNEMPPEPBORFEQ2A@scs.tiktokw.us" ], "task_id": "1381478460934" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEngagementMessageResponse" }, "example": { "code": 0, "data": { "errors": [ { "code": 68009003, "message": "The user adresss is invalid", "detail": { "buyer_email": "v4b1232DOUSGKQQ7YLNEMPPEPBORFEQ2A@scs.tiktokw.us" } } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Customer Engagement - Write" ], "x-tts-error-codes": [ { "code": "68009001", "message": "Access denied. This endpoint is not available for this shop as the seller does not meet the access criteria for CRM features. See TikTok Shop Academy for details." }, { "code": "68009002", "message": "The specified task has ended, and sending of messages is no longer allowed." }, { "code": "68009003", "message": "The user adresss is invalid" }, { "code": "68009004", "message": "Unable to send messages to the specified buyer email as the buyer has not placed an order with the shop in the past 365 days." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/send-engagement-message-202412" } }, "/customer_engagement/202412/performances": { "post": { "operationId": "getEngagementTaskPerformances", "summary": "Get Engagement Task Performances", "description": "Retrieve detailed performance metrics for a customer engagement task, including message reads, order conversions, and other key engagement statistics.", "tags": [ "Customer engagement" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEngagementTaskPerformancesRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEngagementTaskPerformancesResponse" }, "example": { "code": 0, "data": { "task_performances": [ { "id": "8646958016719848812", "status": "SENDING", "sent_recipient_count": 100, "read_recipient_count": 20, "order_count": 10, "gmv_amount": "5.50", "claimed_coupons_count": 1 } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Customer Engagement - Read" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-engagement-task-performances-202412" } }, "/customer_engagement/202502/engagement_tasks/custom": { "post": { "operationId": "createCustomEngagementTask", "summary": "Create Custom Engagement Task", "description": "Create an engagement task that uses a self-defined custom message instead of predefined message templates from TikTok Shop. The task acts as a container for grouping messages with similar content and rules, allowing sellers to track and compare task performance across different types of content.\nNote that each task has a mandatory end time, and once expired, it cannot be used to send additional messages.", "tags": [ "Customer engagement" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "idempotency_key", "in": "query", "required": true, "description": "A unique key to recognize a request and prevent duplicate processing of the same request, especially in cases of connection issues. Ensure this key is unique for each request to avoid accidental duplicates.\nNote: We recommend that you generate v4 UUIDs for use as keys.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomEngagementTaskRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomEngagementTaskResponse" }, "example": { "code": 0, "data": { "task_id": "475910475643" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Customer Engagement - Write" ], "x-tts-error-codes": [ { "code": "68008004", "message": "Policy violation. The message contains content that violates TikTok Shop policies. Modify it and try again." }, { "code": "68008016", "message": "You're currently ineligible to send customized messages. Please use a message template." }, { "code": "68009001", "message": "Access denied. This endpoint is not available for this shop as the seller does not meet the access criteria for CRM features. See TikTok Shop Academy for details." }, { "code": "68009005", "message": "Failed to create an engagement task. Error details:" } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/create-custom-engagement-task-202502" } }, "/customer_engagement/202502/permissions": { "get": { "operationId": "getEngagementFeaturePermissions", "summary": "Get Engagement Feature Permissions", "description": "Retrieve the shop's authorization status for customer engagement features.", "tags": [ "Customer engagement" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEngagementFeaturePermissionsResponse" }, "example": { "code": 0, "data": { "features": [ { "name": "CUSTOM_MSG", "is_authorized": true } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Customer Engagement - Read" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-engagement-feature-permissions-202502" } }, "/customer_service/202309/agents/settings": { "get": { "operationId": "getAgentSettings", "summary": "Get Agent Settings", "description": "This API is used to get agent settings. This API allows the agent to see whether the agent can accept chats from buyers. This API is a read-only endpoint. There will be no side effects, and can be retried safely. Note: 1. The current API version can only get settings on behalf of the shop, or the owner account holder on Seller Center. The owner in this case is acting as the customer service agent. In the future, we plan to make this API available to subaccount holders (who has customer service role) in Seller Center. 2. This API is to allow the agent to get his/her own setting. See more information in API overview", "tags": [ "Customer service" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAgentSettingsResponse" }, "example": { "code": 0, "data": { "can_accept_chat": true }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Customer Service" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-agent-settings-202309" }, "put": { "operationId": "updateAgentSettings", "summary": "Update Agent Settings", "description": "Use this API to set whether the shop owner's customer service account can accept auto-assigned chats. The authenticated shop owner can update only their own setting; customer service subaccounts are not supported in this API version. Set `can_accept_chat` to `true` to accept auto-assigned chats.", "tags": [ "Customer service" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentSettingsRequest" }, "example": { "can_accept_chat": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentSettingsResponse" }, "example": { "code": 0, "data": {}, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Customer Service" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "45101001", "message": "Internal error. Please try again later or contact the technical support team for help." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/update-agent-settings-202309" } }, "/customer_service/202309/conversations": { "get": { "operationId": "getConversations", "summary": "Get Conversations", "description": "Use this API to retrieve a shop's conversations with buyers.", "tags": [ "Customer service" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "page_token", "in": "query", "required": false, "description": "Paging cursor, this means where this query should start.\nFor the next page, use \"next_page_token\" in response.", "schema": { "type": "string" } }, { "name": "page_size", "in": "query", "required": true, "description": "Number of conversations to return per page. Must be between 1 and 20.", "schema": { "type": "integer", "format": "int64" } }, { "name": "locale", "in": "query", "required": false, "description": "System message's display language. The messages sent by System will be returned in the setting language; The messages sent by the buyer, the shop, the CS agent will not be affected. The default value is en (English).\n\nPossible enumerations:\n- de-DE (German, Germany)\n- en (English)\n- en-GB (English, United Kingdom)\n- es-ES (Spanish, Spain)\n- es-MX (Spanish, Latin America)\n- fr-FR (French, France)\n- id-ID (Indonesian, Indonesia)\n- it-IT (Italian, Italy)\n- ja-JP (Japanese)\n- ms-MY (Malay, Malaysia)\n- th-TH (Thai, Thailand)\n- vi-VN (Vietnamese, Vietnam)\n- pt-BR (Portuguese, Brazil)\n- zh-CN (Simplified Chinese, China)", "schema": { "type": "string", "enum": [ "de-DE", "en", "en-GB", "es-ES", "es-MX", "fr-FR", "id-ID", "it-IT", "ja-JP", "ms-MY", "th-TH", "vi-VN", "pt-BR", "zh-CN" ], "x-enum-descriptions": [ "German, Germany", "English", "English, United Kingdom", "Spanish, Spain", "Spanish, Latin America", "French, France", "Indonesian, Indonesia", "Italian, Italy", "Japanese", "Malay, Malaysia", "Thai, Thailand", "Vietnamese, Vietnam", "Portuguese, Brazil", "Simplified Chinese, China" ] } }, { "name": "need_session_id", "in": "query", "required": false, "description": "Set to `true` to request `cur_session_id`. The field is returned only when the conversation has a current open session whose public phase is `AUTO_REPLY`, `QUEUED`, or `ASSIGNED`. Setting `need_session_info` to `true` also requests this field.", "schema": { "type": "boolean" } }, { "name": "need_session_info", "in": "query", "required": false, "description": "Set to `true` to request `cur_session` and `cur_session_id`. These fields are returned only when the conversation has a current open session whose public phase is `AUTO_REPLY`, `QUEUED`, or `ASSIGNED`.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetConversationsResponse" }, "example": { "code": 0, "data": { "next_page_token": "1612353423", "conversations": [ { "id": "7494560109732334261", "participant_count": 3, "can_send_message": true, "unread_count": 0, "create_time": 1691411573, "participants": [ { "im_user_id": "7494560109732334261", "avatar": "https://p16-oec-ttp.tiktokcdn-us.com/tos-useast5-i-omjb5zjo8w-tx/566c497faaaf4491a84d3ce55d9cb095~tplv-omjb5zjo8w-origin-image.image?", "user_id": "7494560109732334262", "role": "BUYER", "nickname": "Albert", "buyer_platform": "TIKTOK_SHOP" } ], "latest_message": { "id": "7494560109732334263", "type": "TEXT", "content": "{\"content\": \"simple text message\"}", "create_time": 1691411573, "is_visible": true, "sender": { "im_user_id": "7494560109732334261", "avatar": "https://p16-oec-ttp.tiktokcdn-us.com/tos-useast5-i-omjb5zjo8w-tx/566c497faaaf4491a84d3ce55d9cb095~tplv-omjb5zjo8w-origin-image.image?", "role": "BUYER", "nickname": "Albert" }, "index": "7494560109732334274" }, "cur_session_id": "7494472109882334261", "cur_session": { "id": "7494472109882334261", "phase": "ASSIGNED" } } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Customer Service" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "45101001", "message": "Internal error. Please try again later or contact the technical support team for help." }, { "code": "45101003", "message": "Record not found. Please check the parameters." }, { "code": "45101004", "message": "The query quota has been reached (10000 request per day). Please try again tomorrow." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-conversations-202309" }, "post": { "operationId": "createConversation", "summary": "Create Conversation", "description": "Use this API to create a conversation with the specified buyer, on behalf of a shop. When there's no prior conversation, calling this API creates a new conversation; when there's a prior conversation, no matter whether it's active, finished, or closed, calling this API reopens the conversation and returns the same conversation ID as the prior one.", "tags": [ "Customer service" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConversationRequest" }, "example": { "buyer_user_id": "7494560109732338459" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConversationResponse" }, "example": { "code": 0, "data": { "conversation_id": "7106888323922608389" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Customer Service" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "45101001", "message": "Internal error. Please try again later or contact the technical support team for help." }, { "code": "45109003", "message": "Unable to create a conversation as you did not meet the criteria for initiating conversations. For details, please refer to [Customer Service API overview](659645f9a46cdd02bc8aeacf#Important%20Concepts)." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/create-conversation-202309" } }, "/customer_service/202309/conversations/{conversation_id}/messages": { "get": { "operationId": "getConversationMessages", "summary": "Get Conversation Messages", "description": "Use this API to retrieve a page of messages in a conversation between a buyer and a shop.\nCalling this API does not mark messages as read. Call [Read Message](650a59f7c16ffe02b8e8db3f) to mark them as read.", "tags": [ "Customer service" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "Conversation ID", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" }, { "name": "page_token", "in": "query", "required": false, "description": "Paging cursor, this means where this query should start.\nFor the next page, use \"next_page_token\" in response.", "schema": { "type": "string" } }, { "name": "page_size", "in": "query", "required": true, "description": "Number of messages to return per page. The value must be between 1 and 10, inclusive.", "schema": { "type": "integer", "format": "int64" } }, { "name": "locale", "in": "query", "required": false, "description": "System message's display language. The messages sent by System will be returned in the setting language; The messages sent by the buyer, the shop, the CS agent will not be affected. The default value is en (English).\n\nPossible enumerations:\n- de-DE (German, Germany)\n- en (English)\n- en-GB (English, United Kingdom)\n- es-ES (Spanish, Spain)\n- es-MX (Spanish, Latin America)\n- fr-FR (French, France)\n- id-ID (Indonesian, Indonesia)\n- it-IT (Italian, Italy)\n- ja-JP (Japanese)\n- ms-MY (Malay, Malaysia)\n- th-TH (Thai, Thailand)\n- vi-VN (Vietnamese, Vietnam)\n- pt-BR (Portuguese, Brazil)\n- zh-CN (Simplified Chinese, China)", "schema": { "type": "string", "enum": [ "de-DE", "en", "en-GB", "es-ES", "es-MX", "fr-FR", "id-ID", "it-IT", "ja-JP", "ms-MY", "th-TH", "vi-VN", "pt-BR", "zh-CN" ], "x-enum-descriptions": [ "German, Germany", "English", "English, United Kingdom", "Spanish, Spain", "Spanish, Latin America", "French, France", "Indonesian, Indonesia", "Italian, Italy", "Japanese", "Malay, Malaysia", "Thai, Thailand", "Vietnamese, Vietnam", "Portuguese, Brazil", "Simplified Chinese, China" ] } }, { "name": "sort_order", "in": "query", "required": false, "description": "Sort order.\nPossible enumerations:\n- DESC(default)\n- ASC", "schema": { "type": "string", "enum": [ "DESC", "ASC" ], "x-enum-descriptions": [ "default", "" ] } }, { "name": "sort_field", "in": "query", "required": false, "description": "Sort messages by one of the following properties:\n- `create_time` (default)\n- `index`", "schema": { "type": "string" } }, { "name": "need_data", "in": "query", "required": false, "description": "Whether to request the `data` field for visible messages when structured data is available. Default: `false`.", "schema": { "type": "boolean" } }, { "name": "need_plaintext", "in": "query", "required": false, "description": "Whether to request the `plaintext` field for visible messages when a human-readable representation is available. Default: `false`.", "schema": { "type": "boolean" } }, { "name": "time_zone", "in": "query", "required": false, "description": "Time zone used to format date and time values in supported message content, including generated plaintext. This parameter does not change `create_time`, which remains a Unix timestamp in seconds. Use an IANA time zone name, such as `Asia/Shanghai` or `America/Los_Angeles`. Default: `UTC`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetConversationMessagesResponse" }, "example": { "code": 0, "data": { "next_page_token": "162312320", "unsupported_msg_tips": "Please check this message in Seller Center.\n", "messages": [ { "id": "7494560109732334263", "type": "TEXT", "content": "{\"content\": \"simple text message\"}", "create_time": 1691411573, "is_visible": true, "sender": { "im_user_id": "7494560109732334261", "role": "BUYER", "nickname": "Albert", "avatar": "https://p16-oec-ttp.tiktokcdn-us.com/tos-useast5-i-omjb5zjo8w-tx/566c497faaaf4491a84d3ce55d9cb095~tplv-omjb5zjo8w-origin-image.image?" }, "index": "7494560109732334274", "data": "{}", "plaintext": "Product card shared:\n- Product ID: 1732529206731441911; \n- Product name: Áo Khoác Cardigan Logo Thêu Phong Cách Hàn Quốc By Zonef, Áo Khoác Thu Đông Chất Vải Cotton Tổ Ong Nam Nữ Unisex; \n- Product price: ; \n- Strike-through price: \n- Sold: 40013. \n\nView full details at: https://seller-vn.tiktok.com/product/manage?search_content=1732529206731441911" } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Customer Service" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "45101001", "message": "Internal error. Please try again later or contact the technical support team for help." }, { "code": "45101003", "message": "Record not found. Please check the parameters." }, { "code": "45101004", "message": "The query quota has been reached (10000 request per day). Please try again tomorrow." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-conversation-messages-202309" } }, "/customer_service/202309/conversations/{conversation_id}/messages/read": { "post": { "operationId": "markBuyerMessagesAsRead", "summary": "Mark Buyer Messages as Read", "description": "Use this API to mark all messages sent by the buyer as read. You are suggested to call this API before replying to their messages.", "tags": [ "Customer service" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "The conversation ID, provided as a base-10 integer string. The conversation must belong to the authorized shop.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkBuyerMessagesAsReadRequest" }, "example": {} } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkBuyerMessagesAsReadResponse" }, "example": { "code": 0, "data": {}, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Customer Service" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "45101003", "message": "Record not found. Please check the parameters." }, { "code": "45101004", "message": "The query quota has been reached (10000 request per day). Please try again tomorrow." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/mark-buyer-messages-as-read-202309" } }, "/customer_service/202309/images/upload": { "post": { "operationId": "uploadImageForBuyerMessages", "summary": "Upload Image for Buyer Messages", "description": "You must use this API to upload the image first, before sending an image as a message using [Send Message](650a58bbbace3e02b7556286).", "tags": [ "Customer service" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UploadImageForBuyerMessagesRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadImageForBuyerMessagesResponse" }, "example": { "code": 0, "data": { "url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/2ca53c34ad8443e6b39f4e0153d3aed4~tplv-o3syd03w52-origin-image.image?from=1320446476", "width": 1280, "height": 720 }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Customer Service" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "45101001", "message": "Internal error. Please try again later or contact the technical support team for help." }, { "code": "45101008", "message": "Internal error. Please try again later or contact the technical support team for help." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/upload-image-for-buyer-messages-202309" } }, "/customer_service/202407/performance": { "get": { "operationId": "getCustomerServicePerformance", "summary": "Get Customer Service Performance", "description": "Retrieves customer service performance metrics for a shop over a selected time period.", "tags": [ "Customer service" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "support_date_ge", "in": "query", "required": true, "description": "The start date (YYYY-MM-DD) of the period for selecting chat support sessions to be included in the performance evaluation.", "schema": { "type": "string", "format": "date" } }, { "name": "support_date_lt", "in": "query", "required": true, "description": "The end date (YYYY-MM-DD) of the period for selecting chat support sessions to be included in the performance evaluation.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCustomerServicePerformanceResponse" }, "example": { "code": 0, "data": { "performance": { "support_session_count": 15, "response_percentage": "93.4", "satisfaction_percentage": "95.2", "response_time_mins": "3.4", "conversion_rate": "66.67", "cs_guided_gmv": "36500", "currency": "USD" } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Customer Service" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "45101001", "message": "Internal error. Please try again later or contact the technical support team for help." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-customer-service-performance-202407" } }, "/customer_service/202601/conversations/{conversation_id}": { "get": { "operationId": "getConversation", "summary": "Get Conversation", "description": "Use this API to retrieve information about a conversation by ID.", "tags": [ "Customer service" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "Conversation ID", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" }, { "name": "need_session_id", "in": "query", "required": false, "description": "Set to `true` to request `cur_session_id`. The field is returned when current open session information is available; it can also be returned when `need_session_info` is `true`.", "schema": { "type": "boolean" } }, { "name": "need_session_info", "in": "query", "required": false, "description": "Set to `true` to request `cur_session` and `cur_session_id`. These fields are returned when current open session information is available.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetConversationResponse" }, "example": { "code": 0, "data": { "conversation": { "id": "7494560109732334261", "participant_count": 3, "participants": [ { "im_user_id": "7494560109732334261", "role": "BUYER", "nickname": "Albert", "avatar": "https://p16-oec-ttp.tiktokcdn-us.com/tos-useast5-i-omjb5zjo8w-tx/566c497faaaf4491a84d3ce55d9cb095~tplv-omjb5zjo8w-origin-image.image?", "user_id": "7494560109732334262", "platform": "TIKTOK_SHOP" } ], "create_time": 1691411573, "unread_count": 0, "cur_session_id": "7494472109882334261", "cur_session": { "id": "7494472109882334261", "phase": "ASSIGNED" } } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Customer Service" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "45101001", "message": "Internal error. Please try again later or contact the technical support team for help." }, { "code": "45101003", "message": "Record not found. Please check the parameters." }, { "code": "45101004", "message": "The query quota has been reached (10000 request per day). Please try again tomorrow." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-conversation-202601" } }, "/customer_service/202602/sessions/search": { "post": { "operationId": "searchSessions", "summary": "Search Sessions", "description": "Search customer service sessions by their start-time range and, optionally, the buyer's nickname.", "tags": [ "Customer service" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "page_size", "in": "query", "required": true, "description": "The number of results to be returned per page. \nValid range: [1-100]", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 100 } }, { "name": "page_token", "in": "query", "required": false, "description": "An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the next_page_token from a previous response. It is not needed for the first page.", "schema": { "type": "string" } }, { "name": "locale", "in": "query", "required": false, "description": "The BCP-47 locale codes for displaying the rejection reason, delimited by commas. Default: en-US\nRefer to https://partner.tiktokshop.com/docv2/page/678e3a47bae28f030a8c7523 for the list of supported locale codes.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchSessionsRequest" }, "example": { "begin_time_ge": 1773222516, "begin_time_lt": 1773242516, "buyer_nickname": "Albert" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchSessionsResponse" }, "example": { "code": 0, "data": { "next_page_token": "10", "sessions": [ { "id": "7494560109732334261", "conversation_id": "7601726193700929800", "begin_time": 1773222516, "end_time": 1773232516, "buyer_nickname": "Albert", "chat_tags": [ "Logistics" ], "satisfaction_score": 4, "dissatisfaction_reason": "Slow response or resolution", "first_response_late": false, "first_response_time": 123 } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Customer Service" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "45101001", "message": "Internal error. Please try again later or contact the technical support team for help." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-sessions-202602" } }, "/customer_service/202605/conversations/{conversation_id}/sessions/{session_id}/end": { "post": { "operationId": "endSession", "summary": "End Session", "description": "Use this API to end an active customer service session assigned to an agent.", "tags": [ "Customer service" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "Conversation id.", "schema": { "type": "string" } }, { "name": "session_id", "in": "path", "required": true, "description": "Current session id.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndSessionRequest" }, "example": {} } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndSessionResponse" }, "example": { "code": 0, "data": {}, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Customer Service" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/end-session-202605" } }, "/customer_service/202606/conversations/{conversation_id}/messages": { "post": { "operationId": "sendMessage", "summary": "Send Message", "description": "Use this API to send a message to the buyer in a conversation.", "tags": [ "Customer service" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "Conversation ID", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageRequest" }, "example": { "type": "TEXT", "content": "{\"content\": \"test\"}", "sender_role": "CUSTOMER_SERVICE" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageResponse" }, "example": { "code": 0, "data": { "message_id": "7494560109732334261" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Customer Service" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "45101001", "message": "Internal error. Please try again later or contact the technical support team for help." }, { "code": "45101002", "message": "Invalid params. The RETURN_REFUND_CARD must meet the conditions listed above." }, { "code": "45101003", "message": "Record not found. Please check the parameters." }, { "code": "45101004", "message": "The query quota has been reached (10000 request per day). Please try again tomorrow." }, { "code": "45101006", "message": "You cannot send the message containing sensitive content. Please check the message." }, { "code": "45102007", "message": "No permission to access this conversation. There may be data corruption. Please try again later or contact the technical support team for help." }, { "code": "45109001", "message": "Unable to send messages due to conversation rules. For details, please refer to [Customer Service API overview](659645f9a46cdd02bc8aeacf#Important%20Concepts)." }, { "code": "45111001", "message": "not support" }, { "code": "45111007", "message": "The buyer has already reached the maximum claim limit for this coupon." }, { "code": "45111012", "message": "Failed to send the coupon card message due to exceeding the QPS limit. The QPS limit of sending coupon card messages is 0.5." }, { "code": "45111017", "message": "Invalid params. The COUPON_CARD must meet the conditions listed above." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/send-message-202606" } }, "/event/202309/webhooks": { "get": { "operationId": "getShopWebhooks", "summary": "Get Shop Webhooks", "description": "Retrieves the enabled webhooks configured for the shop and their corresponding webhook URLs.", "tags": [ "Event" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetShopWebhooksResponse" }, "example": { "code": 0, "data": { "webhooks": [ { "event_type": "ORDER_STATUS_CHANGE", "address": "https://partner.tiktokshop.com", "create_time": 1635338186000, "update_time": 1635338186000 } ], "total_count": 1 }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Shop Authorized Information" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-shop-webhooks-202309" }, "put": { "operationId": "updateShopWebhook", "summary": "Update Shop Webhook", "description": "Updates the shop's webhook URL for a specific event topic.", "tags": [ "Event" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShopWebhookRequest" }, "example": { "address": "https://partner.tiktokshop.com", "event_type": "ORDER_STATUS_CHANGE" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShopWebhookResponse" }, "example": { "code": 0, "data": {}, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Shop Authorized Information" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/update-shop-webhook-202309" }, "delete": { "operationId": "deleteWebhookForAnEvent", "summary": "Delete Webhook for an Event", "description": "Deletes the shop's webhook URL for the specified event topic. The request succeeds even if no webhook URL is currently configured for that topic.", "tags": [ "Event" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteWebhookForAnEventRequest" }, "example": { "event_type": "ORDER_STATUS_CHANGE" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteWebhookForAnEventResponse" }, "example": { "code": 0, "data": {}, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Shop Authorized Information" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/delete-webhook-for-an-event-202309" } }, "/fbt/202408/inventory/search": { "post": { "operationId": "searchFBTInventory", "summary": "Search FBT Inventory", "description": "This API is used to retrieve detailed inventory information for goods and matched SKUs, including sellable inventory, reserved inventory, unsellable inventory, and in-transit inventory at the warehouse level.", "tags": [ "Fulfilled by TikTok (FBT)" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "page_size", "in": "query", "required": true, "description": "The number of results to be returned per page. \nValid range: [1-100].", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 100 } }, { "name": "page_token", "in": "query", "required": false, "description": "Pagination page token. It should be empty for the first page.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchFBTInventoryRequest" }, "example": { "goods_ids": [ "256080616234", "2231616264" ], "fbt_warehouse_ids": [ "7232382932030232" ], "sku_ids": [ "256080616234" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchFBTInventoryResponse" }, "example": { "code": 0, "data": { "next_page_token": "cGFnZV9udW1iZXI9Mg==", "total_count": 22113, "inventory": [ { "goods": { "id": "69167899745030", "reference_code": "water01", "name": "100ml water", "skus": [ { "id": "73243612345", "on_hand_detail": { "total_quantity": 20, "available_quantity": 5, "reserved_quantity": 15 } } ] }, "fbt_warehouse_id": "7232382932030232", "in_transit_quantity": 10, "on_hand_detail": { "total_quantity": 20, "available_quantity": 5, "reserved_quantity": 15, "unfulfillable_quantity": 0 } } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfilled by TikTok(FBT) Info" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-fbt-inventory-202408" } }, "/fbt/202408/warehouses": { "get": { "operationId": "getFBTWarehouseList", "summary": "Get FBT Warehouse List", "description": "This API is used to retrieve all Fulfilled by TikTok warehouse information including the warehouse name, warehouse address information, etc. The IDs of subscribed warehouses can be used to query inventory-related information.", "tags": [ "Fulfilled by TikTok (FBT)" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetFBTWarehouseListResponse" }, "example": { "code": 0, "data": { "warehouses": [ { "fbt_warehouse_id": "121219993203023", "warehouse_ids": [ "161213293423029", "181213293423030" ], "name": "TikTok_Eastvale(CA)", "type": "PLATFORM_WAREHOUSE", "subscribed": true, "addresses": [ { "postal_code": "92376", "region_code": "US", "state": "CA", "district": "San Bernardino", "city": "Rialto", "address_line_1": "1420 Tamarind Ave, Rialto, San Bernardino", "address_line_2": " ", "address_line_3": " " } ], "logistics_services": [ { "id": "12123232323", "name": "Fulfilled by TikTok Shop-Standard", "subscribed": true } ] } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfilled by TikTok(FBT) Info" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-fbt-warehouse-list-202408" } }, "/fbt/202409/merchants/onboarded_regions": { "get": { "operationId": "getFBTMerchantOnboardedRegions", "summary": "Get FBT Merchant Onboarded Regions", "description": "This API verifies whether a seller is registered as a Fulfillment by TikTok (FBT) merchant. If the seller is onboarded, the API returns the regions where the merchant is authorized to operate under the FBT system.", "tags": [ "Fulfilled by TikTok (FBT)" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetFBTMerchantOnboardedRegionsResponse" }, "example": { "code": 0, "data": { "onboarded_regions": [ { "region_code": "GB" } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfilled by TikTok(FBT) Info" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-fbt-merchant-onboarded-regions-202409" } }, "/fbt/202410/inventory_records/search": { "post": { "operationId": "searchFBTInventoryRecord", "summary": "Search FBT Inventory Record", "description": "This API is used to retrieve detailed inventory change records for goods at the warehouse level.", "tags": [ "Fulfilled by TikTok (FBT)" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "page_size", "in": "query", "required": true, "description": "The number of results to return per page.\nValid range: [1-100].\nPagination is limited to the first 20,000 results.", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 100 } }, { "name": "page_token", "in": "query", "required": false, "description": "Pagination page token. It should be empty for the first page.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchFBTInventoryRecordRequest" }, "example": { "goods_ids": [ "256080616234", "2231616264" ], "fbt_warehouse_ids": [ "7232382932030232" ], "create_time_ge": 1293013251, "create_time_le": 1393013251 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchFBTInventoryRecordResponse" }, "example": { "code": 0, "data": { "inventory_records": [ { "goods": { "id": "12324323", "reference_code": "water01", "name": "100ml water" }, "fbt_warehouse_id": "7232392932323", "order": { "id": "OBF8932302030203", "type": "INBOUND_ORDER" }, "create_time": 1212139230, "inventory_goods_type": "NORMAL", "initial_on_hand_quantity": 10, "final_on_hand_quantity": 12, "changed_quantity": 2 } ], "next_page_token": "cGFnZV9udW1iZXI9Mg==", "total_count": 22113 }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfilled by TikTok(FBT) Info" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-fbt-inventory-record-202410" } }, "/fbt/202601/mcf/goods/inventory/search": { "post": { "operationId": "queryGoodsInventoryForMCF", "summary": "Query Goods Inventory For MCF", "description": "Search available inventory for MCF goods. Use this API to retrieve available quantities for the specified Fulfilled by TikTok goods IDs.", "tags": [ "Fulfilled by TikTok (FBT)" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryGoodsInventoryForMCFRequest" }, "example": { "goods": [ { "goods_id": "69167899745030" } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryGoodsInventoryForMCFResponse" }, "example": { "code": 0, "data": { "goods_inventory_list": [ { "goods_id": "69167899745030", "available_qty": 10 } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfilled by TikTok(FBT) Info" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/query-goods-inventory-for-mcf-202601" } }, "/fbt/202601/mcf_outbound_orders": { "get": { "operationId": "getFBTMCFOrderStatus", "summary": "Get FBT MCF Order Status", "description": "Use this API to retrieve an MCF order and the current status and fulfillment details of its consign orders. If the order requires multiple packages because of carrier restrictions or package-size limits, the FBT system splits it for fulfillment and returns one entry in `consign_orders` for each package.", "tags": [ "Fulfilled by TikTok (FBT)" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "mcf_order_id", "in": "query", "required": true, "description": "A unique ID that identifies different MCF orders", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetFBTMCFOrderStatusResponse" }, "example": { "code": 0, "data": { "mcf_order": { "external_order_id": "shopify202208291503530001100220033", "mcf_order_id": "7136104329798256386", "consign_orders": [ { "id": "1234", "goods": [ { "id": "123124124", "quantity": 1 } ], "tracking_number": "TN87654321", "carrier": "USPS", "status": "PENDING", "is_platform_closed": false, "issue": "Lack of inventory", "shipping_provider": { "id": "7345645330412603141", "name": "UPS" } } ], "create_time": 1661756811 } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfilled by TikTok(FBT) Info" ], "x-tts-error-codes": [ { "code": "177001009", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "177001010", "message": "Order information cannot be retrieved via the mcf_order_id you provided; please check if your ID is correct." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-fbt-mcf-order-status-202601" } }, "/fbt/202601/mcf_outbound_orders/cancel": { "post": { "operationId": "cancelFBTMCFOrder", "summary": "Cancel FBT MCF Order", "description": "An FBT multi-channel fulfillment (MCF) order may be split into one or more consign orders for fulfillment. Use this API to cancel the MCF order or selected consign orders by providing the `mcf_order_id`. To cancel selected consign orders, provide their consign order IDs. You can retrieve IDs that have already been assigned by calling the **Get FBT MCF Order Status** API; use IDs returned while the target consign orders are still in a cancellable pre-shipment state.\n\nCancellation is rejected for target consign orders that have reached `SHIPPED`, `HANDOVER`, `COMPLETED`, or a shipping-exception state such as `LOST`, `DAMAGE`, `RETURNED`, or `SCRAP`.\n\nAfter the request, match the target consign order IDs against this API's response. A returned status of `CLOSED` means that the consign order has been canceled.", "tags": [ "Fulfilled by TikTok (FBT)" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelFBTMCFOrderRequest" }, "example": { "mcf_order_id": "7136104329798256386", "consign_orders": [ { "id": "7136104329798256386" } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelFBTMCFOrderResponse" }, "example": { "code": 0, "data": { "mcf_order": { "external_order_id": "shopify7136104329798256386", "mcf_order_id": "7136104329798256386", "consign_orders": [ { "id": "1234", "status": "CLOSED" } ] } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfilled by TikTok(FBT) Info" ], "x-tts-error-codes": [ { "code": "177001009", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/cancel-fbt-mcf-order-202601" } }, "/fbt/202601/merchants/mcf_status": { "get": { "operationId": "getFBTMerchantMCFStatus", "summary": "Get FBT Merchant MCF Status", "description": "Checks whether a seller is onboarded to Fulfillment by TikTok (FBT) and enrolled in Multi-Channel Fulfillment (MCF). This API currently supports only sellers in the US. If both conditions are met, `mcf_status.is_mcf` is `1` (active).", "tags": [ "Fulfilled by TikTok (FBT)" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetFBTMerchantMCFStatusResponse" }, "example": { "code": 0, "data": { "mcf_status": { "is_mcf": 0 } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfilled by TikTok(FBT) Info" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-fbt-merchant-mcf-status-202601" } }, "/fbt/202602/create_update_inbound_plan": { "post": { "operationId": "createOrUpdateInboundPlan", "summary": "Create or Update Inbound Plan", "description": "Creates a new inbound plan or fully replaces the contents of an existing inbound plan by using a goods item list or carton configurations with dimensions. Omit `plan_id` to create a plan; provide it to update one. Provide exactly one non-empty array: `goods_items` or `cartons`; do not provide both.\n\nFor an update, submit the complete desired goods or carton contents; previously stored goods or cartons omitted from the request are not retained. Using `goods_items` clears existing carton and lot/expiration data. Using `cartons` rebuilds the carton and item data.", "tags": [ "Fulfilled by TikTok (FBT)" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrUpdateInboundPlanRequest" }, "example": { "plan_id": "5766071177167344427", "idempotent_key": "9ef6857095f84893", "goods_items": [ { "goods_id": "231313", "quantity": 400 } ], "cartons": [ { "carton_type": "SINGLE_SKU", "items": [ { "goods_id": "12345", "quantity": 20, "lot_code": "sfsfnjkfvv", "expiration_timestamp": "1623812664" } ], "quantity": 2, "carton_nums": [ "C0001", "C0002" ], "box_measurements": { "weight": "3.50", "weight_unit": "POUNDS", "width": "1.2", "height": "2", "length": "5", "length_unit": "INCH" } } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrUpdateInboundPlanResponse" }, "example": { "code": 0, "data": { "inbound_plan": { "plan_id": "5766071177167344427" } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfilled by TikTok(FBT) Info" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "39001002", "message": "Request or request parameters are empty. Please recheck the input parameters." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/create-or-update-inbound-plan-202602" } }, "/fbt/202602/inbound_method_detail": { "post": { "operationId": "getInboundMethodDetail", "summary": "Get Inbound Method Detail", "description": "Retrieves placement details for an inbound plan. First call the List Available Inbound Methods API for the plan, then use the `inbound_method` and estimated arrival window from the same returned option. The response reports the placement task status and, when available, placement options with shipment allocations; `ONE_HUB` options can also include an estimated placement fee.", "tags": [ "Fulfilled by TikTok (FBT)" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetInboundMethodDetailRequest" }, "example": { "plan_id": "5766071177167344427", "inbound_method": "D2FC", "estimate_arrival_time": { "start_timestamp": "1774162800", "end_timestamp": "1774767600" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetInboundMethodDetailResponse" }, "example": { "code": 0, "data": { "info": [ { "allocation_shipments": [ { "warehouse_id": "7542187927317874487", "goods_items": [ { "goods_id": "2134566", "quantity": 400 } ], "cartons": [ { "carton_type": "SINGLE_SKU", "items": [ { "goods_id": "12345", "quantity": 20, "lot_code": "sfsfnjkfvv", "expiration_timestamp": "1623812664" } ], "quantity": 2, "carton_nums": [ "C0001", "C0002" ], "box_measurements": { "weight": "3.5", "weight_unit": "POUNDS", "width": "1.2", "height": "2", "length": "5", "length_unit": "INCH" } } ], "shipment_options": [ { "shipping_method": "SMALL_PARCEL" } ] } ], "placement_option_id": "5766071177167344420", "placement_fee_estimate": { "amount": "13.50", "currency": "USD" } } ], "placement_task_status": "Executing", "expiration_timestamp": "1774767600" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfilled by TikTok(FBT) Info" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "39001002", "message": "Request or request parameters are empty. Please recheck the input parameters." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-inbound-method-detail-202602" } }, "/fbt/202602/inbound_orders": { "get": { "operationId": "getFBTInboundOrderDetails", "summary": "Get FBT Inbound Order Details", "description": "Retrieves details for the specified FBT inbound orders, including planned and actual receiving information and status history. Set `include_carton_details` to `true` to request carton dimensions and item quantities.", "tags": [ "Fulfilled by TikTok (FBT)" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "order_ids", "in": "query", "required": true, "description": "The list of numeric identifiers of the inbound orders to fetch information for. \n**Note:** Provide the numeric sequence only; do not include the \"IBR\" prefix (e.g., use `123456` instead of `IBR123456`). There is a **limit of 10 orders** to be fetched in each request.\n\nOnly orders that are found and accessible to the current seller are returned. Missing or inaccessible order IDs are omitted from the response; the request fails if none of the requested orders can be returned.\n\nYou can get the value in `data.inbound_order_id` in [Inbound FBT order status change](6708f866a88d1103246fed6a) webhook or in `data.inventory_records.order.id` in the response of [Search FBT Inventory Record](670d584ba83c5f030f3071e4).", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "include_carton_details", "in": "query", "required": false, "description": "A boolean flag that determines whether the response should include granular information for each individual carton within the shipment.\n\n**Note**: When set to `true`, the response will include the `carton_details` field. If set to `false` or omitted, this field will be excluded from the response payload to optimize performance.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetFBTInboundOrderDetailsResponse" }, "example": { "code": 0, "data": { "inbound_orders": [ { "order_id": "5766071177167344427", "order_id_string": "IBR5766071177167344427", "order_plan_id": "5766071177167345050", "merchant": { "id": "493493403043", "name": "ExampleCompany" }, "create_time": 1773778751, "ship_time": 1773778751, "expected_arrival_time": 1773778751, "actual_arrival_time": 1773778751, "warehouse": { "fbt_warehouse_id": "121219993203023", "business_warehouse_ids": [ "121219993209983" ], "name": "TikTok Warehouse", "type": "FC" }, "status_logs": [ { "operate_time": 1715398048, "new_status": "RECEIVED", "previous_status": "PARTIALLY_RECEIVED", "operator": "Warehouse" } ], "logistic_info_list": [ { "provider_name": "UPS", "waybill_number": "889042812410", "related_number": "C0001" } ], "carton_details": [ { "carton_no": "C0001", "carton_type": "SINGLE_SKU", "box_measurements": { "weight": "5", "weight_unit": "KILOGRAM", "width": "6", "height": "7", "length": "8", "length_unit": "METER" }, "items": [ { "goods_id": "7603596185", "quantity": 10 } ] } ], "inbound_goods_lot_receive_item_details": [ { "goods_id": "7603596185", "lot_code": "LOT-2024-XP9", "expiration_time": 1735689600, "planned_count": 100, "normal_received_count": 98, "defective_received_count": 2, "total_received_count": 100 } ] } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfilled by TikTok(FBT) Info" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "39001002", "message": "Request or request parameters are empty. Please recheck the input parameters." }, { "code": "39015009", "message": "SellerId input is invalid" }, { "code": "39015010", "message": "No inbound orders found for the merchant." }, { "code": "39015020", "message": "Number of orders in request exceeds the configured limit." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-fbt-inbound-order-details-202602" } }, "/fbt/202602/inbound_orders/cancel": { "post": { "operationId": "cancelInboundOrder", "summary": "Cancel Inbound Order", "description": "This API is used to cancel one inbound order per request prior to warehouse arrival, preventing further processing and updating the order status.\n\n**If the inbound order is part of a D2FC inbound plan, call this API separately for every order under the plan. Otherwise, non-compliance fees may be charged.**", "tags": [ "Fulfilled by TikTok (FBT)" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelInboundOrderRequest" }, "example": { "order_id": "5766071177167344427", "cancel_reason": "Order created by mistake." } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelInboundOrderResponse" }, "example": { "code": 0, "data": {}, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfilled by TikTok(FBT) Info" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "39001002", "message": "Request or request parameters are empty. Please recheck the input parameters." }, { "code": "39015007", "message": "Access denied. The API requires the seller to be bound to exactly one merchant." }, { "code": "39015009", "message": "SellerId input is invalid" }, { "code": "39015010", "message": "No inbound orders found for the merchant." }, { "code": "39015013", "message": "Invalid or missing cancel reason." }, { "code": "39015014", "message": "Failed to cancel inbound order due to status or other business restrictions. Please check the inbound order status and try again. If the issue persists and the cause is unknown, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/cancel-inbound-order-202602" } }, "/fbt/202602/inbound_orders/label_print": { "post": { "operationId": "printInboundOrderLabels", "summary": "Print Inbound Order Labels", "description": "This API generates label files for an inbound order using an **asynchronous Long-Running Operation (LRO)**. The inbound order must be shipped or in a later eligible status and must not be canceled.\n\n**Format applicability**\n* `carton_label_format` controls the carton or pallet label layout only when `print_items` includes `CARTON_PALLET_LABEL`.\n* `barcode_format` controls the goods-barcode label layout only when `print_items` includes `FBT_BARCODE`.\n\nThe selected `print_items` and both resolved format values are part of the print task identifier, so keep the same selections in every polling request.\n\n**Workflow**\n1. **Initiate.** Send a request with the child inbound `order_id` and the desired `print_items`. The API returns `PROCESSING` while the label file is being generated; a completed task for the same request values may return `SUCCESS` immediately.\n2. **Poll.** If `task_status` is `PROCESSING`, repeat the request with the same `order_id`, `print_items`, `carton_label_format`, and `barcode_format` values. Poll every 3–5 seconds.\n3. **Complete.** When `task_status` is `SUCCESS`, `download_url` contains the generated ZIP file.", "tags": [ "Fulfilled by TikTok (FBT)" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintInboundOrderLabelsRequest" }, "example": { "order_id": "5766071177167344427", "print_items": [ "CARTON_PALLET_LABEL", "FBT_BARCODE", "PACKING_PICKING_LIST" ], "carton_label_format": "DEFAULT_1UP", "barcode_format": "DEFAULT_40MM_60MM" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintInboundOrderLabelsResponse" }, "example": { "code": 0, "data": { "download_url": "https://example.com/fbt/inbound_files.zip?download_token=sample_token", "task_status": "PROCESSING" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfilled by TikTok(FBT) Info" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "39001002", "message": "Request or request parameters are empty. Please recheck the input parameters." }, { "code": "39015007", "message": "Access denied. The API requires the seller to be bound to exactly one merchant." }, { "code": "39015009", "message": "SellerId input is invalid" }, { "code": "39015010", "message": "No inbound orders found for the merchant." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/print-inbound-order-labels-202602" } }, "/fbt/202602/inbound_orders/tracking_update": { "post": { "operationId": "updateInboundOrderTracking", "summary": "Update Inbound Order Tracking", "description": "Updates carton-level tracking information for an inbound order after shipment and before the order is marked as `Delivered` or `Received`. When updating tracking, send the complete desired `parcel_tracking_info` list; entries omitted from a non-empty submission are not retained, so this is not a partial patch. The first tracking value for a carton does not count as an edit, and resubmitting the same normalized value does not consume another edit. Changing an existing carton's tracking number consumes one of the five allowed edits for that carton; a sixth change is rejected before the local update. The submitted carton updates are applied atomically to the stored tracking list: either the complete local replacement is saved or none of it is. Warehouse synchronization and logistics tracking registration occur outside this atomic update; warehouse synchronization failures are not returned, and tracking registration runs asynchronously.", "tags": [ "Fulfilled by TikTok (FBT)" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInboundOrderTrackingRequest" }, "example": { "order_id": "5766071177167344427", "parcel_tracking_info": [ { "provider_name": "FEDEX", "tracking_number": "889042812410", "carton_number": "C0001" } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInboundOrderTrackingResponse" }, "example": { "code": 0, "data": {}, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfilled by TikTok(FBT) Info" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "39001002", "message": "Request or request parameters are empty. Please recheck the input parameters." }, { "code": "39015007", "message": "Access denied. The API requires the seller to be bound to exactly one merchant." }, { "code": "39015009", "message": "SellerId input is invalid" }, { "code": "39015010", "message": "No inbound orders found for the merchant." }, { "code": "39015015", "message": "Parcel tracking info list is empty." }, { "code": "39015016", "message": "Tracking provider is invalid or unsupported." }, { "code": "39015017", "message": "Carton number is invalid or missing." }, { "code": "39015018", "message": "Failed to update tracking info for inbound order. Please check that the inbound order is in \"Shipped\" status and try again. If the issue persists and the cause is unknown, please contact platform support." }, { "code": "39015019", "message": "Tracking number is invalid or missing." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/update-inbound-order-tracking-202602" } }, "/fbt/202602/list_available_inbound_method": { "post": { "operationId": "listAvailableInboundMethods", "summary": "List Available Inbound Methods", "description": "Retrieves valid inbound shipping methods and arrival time windows for a specific plan. After selecting an `inbound_method` and one complete arrival time window, call **Get Inbound Method Detail** (`POST /fbt/202602/inbound_method_detail`) using the same `plan_id`, the selected `inbound_method`, and that window's exact `start_timestamp` and `end_timestamp` pair as `estimate_arrival_time`.", "tags": [ "Fulfilled by TikTok (FBT)" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAvailableInboundMethodsRequest" }, "example": { "plan_id": "5766071177167344427" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAvailableInboundMethodsResponse" }, "example": { "code": 0, "data": { "available_inbound_method_list": [ { "inbound_method": "D2FC", "available_time_window_list": [ { "start_timestamp": "1774162800", "end_timestamp": "1774767600" } ], "warehouse_list": [ { "warehouse_name": "FC09_ATL2", "warehouse_id": "7542187927317874487" } ], "placement_fee_estimate": { "amount": "13.50", "currency": "USD" } } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfilled by TikTok(FBT) Info" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "39001002", "message": "Request or request parameters are empty. Please recheck the input parameters." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/list-available-inbound-methods-202602" } }, "/fbt/202603/confirm_inbound_method": { "post": { "operationId": "confirmInboundMethod", "summary": "Confirm Inbound Method", "description": "Confirm a currently available warehouse placement option for an FBT inbound plan. First call the List Available Inbound Methods API and select an `inbound_method` with one exact `estimate_arrival_time` window. Then call the Get Inbound Method Detail API with that selection and choose a returned `placement_option_id`. Confirm using the `placement_option_id`, `inbound_method`, and `estimate_arrival_time` from the same selection. If the option has expired, repeat both prerequisite calls to obtain a current selection and a new `placement_option_id`, then retry. The response contains the child inbound order IDs generated for the plan.", "tags": [ "Fulfilled by TikTok (FBT)" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmInboundMethodRequest" }, "example": { "plan_id": "5766071177167344427", "placement_option_id": "5766071177167344420", "inbound_method": "D2FC", "estimate_arrival_time": { "start_timestamp": "1774162800", "end_timestamp": "1774767600" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmInboundMethodResponse" }, "example": { "code": 0, "data": { "inbound_order_ids": [ "5766071177167344427", "5766071177167344428" ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfilled by TikTok(FBT) Info" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "39001002", "message": "Request or request parameters are empty. Please recheck the input parameters." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/confirm-inbound-method-202603" } }, "/fbt/202603/goods/hazmat_and_expiration_info/search": { "post": { "operationId": "searchGoodsHazmatAndExpirationInfo", "summary": "Search Goods Hazmat And Expiration Info", "description": "Search hazmat and expiration information for goods by TikTok Shop SKU IDs.", "tags": [ "Fulfilled by TikTok (FBT)" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchGoodsHazmatAndExpirationInfoRequest" }, "example": { "tts_sku_ids": [ "723456789012345678" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchGoodsHazmatAndExpirationInfoResponse" }, "example": { "code": 0, "data": { "hazmat_and_expiration_info": { "hazmat_and_expiration_dto_list": [ { "tts_sku_id": "723456789012345678", "is_hazmat": false, "is_lot_code": true, "is_expiration_management": true, "exp_base_info": { "inbound_cutoff_days": 90, "expiration_alert_days": 80, "sales_cutoff_days": 70 } } ] } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfilled by TikTok(FBT) Info" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-goods-hazmat-and-expiration-info-202603" } }, "/fbt/202603/goods/update_goods_sku_relation": { "post": { "operationId": "updateGoodsSKURelations", "summary": "Update Goods-SKU Relations", "description": "Bind or unbind TikTok Shop SKUs to FBT goods.", "tags": [ "Fulfilled by TikTok (FBT)" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGoodsSKURelationsRequest" }, "example": { "operate_goods_sku_relation_list": [ { "tts_goods_id": "334556677", "tts_sku_ids": [ "723456789012345678" ] } ], "operation_type": "BIND" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGoodsSKURelationsResponse" }, "example": { "code": 0, "data": { "operate_goods_sku_relation_info": { "operate_result_list": [ { "tts_goods_id": "9988776655", "tts_sku_id": "723456789012345678", "is_success": false, "fail_reason": "SKU does not exist." } ] } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfilled by TikTok(FBT) Info" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/update-goods-sku-relations-202603" } }, "/fbt/202603/ship_inbound_order": { "post": { "operationId": "shipInboundOrder", "summary": "Ship Inbound Order", "description": "Finalizes carton and shipping details for an inbound order that is ready to ship. For an order that has not already been shipped, a successful response means the details were saved and the order moved to the receiving stage. Repeating the request after the order has already been shipped returns success without applying the supplied details again.", "tags": [ "Fulfilled by TikTok (FBT)" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipInboundOrderRequest" }, "example": { "inbound_order_id": "5766071177167344427", "cartons": [ { "carton_type": "SINGLE_SKU", "items": [ { "goods_id": "723456789012345678", "quantity": 100, "lot_code": "sfsfnjkfvv", "expiration_timestamp": "1623812664" } ], "quantity": 2, "carton_nums": [ "C0001", "C0002" ], "box_measurements": { "weight": "10", "weight_unit": "POUNDS", "width": "20", "height": "2", "length": "3", "length_unit": "INCH" } } ], "shipment_option": { "shipping_method": "SMALL_PARCEL", "freight_type": "FTL" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipInboundOrderResponse" }, "example": { "code": 0, "data": { "inbound_order_id": "5766071177167344427" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfilled by TikTok(FBT) Info" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "39001002", "message": "Request or request parameters are empty. Please recheck the input parameters." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/ship-inbound-order-202603" } }, "/fbt/202607/goods/create_goods": { "post": { "operationId": "createFBTGoods", "summary": "Create FBT Goods", "description": "Create FBT goods records and link each record to a TikTok Shop SKU. Request-level errors can be returned before per-item results are populated. When `create_result_info.create_result_list` contains entries, correlate them by `tts_sku_id`, check `is_success` for each returned item, read `fail_reason` for failures, and use `tts_goods_id` for successes.\n\nThe request supports dimensions and weight, return handling, hazardous-material, shelf-life, SIOC, bulky-item, and safety attributes.", "tags": [ "Fulfilled by TikTok (FBT)" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFBTGoodsRequest" }, "example": { "create_goods_dto_list": [ { "tts_sku_id": "723456789012345678", "create_goods_type": "CREATE_AND_BIND", "goods_name": "Wireless Charging Cable", "goods_image_url": "https://example.com/fbt/goods-image.jpg", "reference_code": "ABDK999d", "barcode_infos": [ { "barcode_type": "UPC", "barcode_value": "12345678905" } ], "return_handling_method": "RESTOCK_SELLABLE_DISPOSE_UNSELLABLE", "dimension_and_weight_base_info": { "weight_value": "500", "length_value": "2", "width_value": "2", "height_value": "3", "weight_unit": "GRAM", "dimension_unit": "CENTIMETER" }, "is_hazmat": false, "hazmat_info": { "hazmat_type": "BATTERY", "battery_extra_info": { "battery_type": "LITHIUM_ION", "battery_packaging_type": "STANDALONE", "total_battery_weight": "10", "total_battery_weight_unit": "GRAM", "total_battery_capacity": "2", "total_battery_capacity_unit": "WATTHOUR", "is_need_un_38_3_test": false, "un_38_3_test_file_url": "https://example.com/fbt/un38-3-test-report.pdf", "battery_count_per_package": "3" }, "flammable_liquids_extra_info": { "flammable_liquids_type": "PAINT", "flammable_liquids_volume": "1", "volume_unit": "MILLILITERS" }, "dg_class": "CLASS_2", "dg_uncode": "UN3480", "msds_file_url": "https://example.com/fbt/msds-report.pdf", "aerosol_extra_info": { "volume": "1", "volume_unit": "MILLILITERS" } }, "is_lot_code": false, "is_expiration_management": false, "shelf_life_attribute_info": { "shelf_life": 90, "inbound_cutoff_days": 100, "expiration_alert_days": 90, "sales_cutoff_days": 80, "handling_method_expired_goods": "DISPOSE" }, "is_sioc": false, "sioc_attribute": { "sioc_files": [ { "sioc_certification_url": "https://example.com/fbt/sioc-certification.jpg", "sioc_file_type": "PHOTO" } ] }, "bulky_item_attribute": { "is_bulky_item_accessories": false }, "goods_safety_attributes": { "is_fragile": false, "is_liquid": false, "is_sharp": false } } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFBTGoodsResponse" }, "example": { "code": 0, "data": { "create_result_info": { "create_result_list": [ { "tts_sku_id": "723456789012345678", "is_success": false, "tts_goods_id": "9988776655", "fail_reason": "Goods creation failed." } ] } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfilled by TikTok(FBT) Info" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/create-fbt-goods-202607" } }, "/fbt/202607/goods/search": { "post": { "operationId": "searchGoodsInfo", "summary": "Search Goods Info", "description": "Retrieves goods belonging to the merchant that match the specified filters and returns their IDs, names, goods-SKU relationships, merchant-declared measurements, warehouse-confirmed measurements, and other attributes. When more than one of `goods_ids`, `product_ids`, `reference_codes`, and `sku_ids` is provided, the API returns only goods that match all provided filter fields. If all four filters are empty or omitted, the API returns the merchant's goods in descending creation-time order, limited by `page_size`.", "tags": [ "Fulfilled by TikTok (FBT)" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "page_size", "in": "query", "required": true, "description": "The number of results to be returned per page. \nValid range: [1-100].", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 100 } }, { "name": "page_token", "in": "query", "required": false, "description": "An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the `next_page_token` from a previous response. It is not needed for the first page.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchGoodsInfoRequest" }, "example": { "goods_ids": [ "256080616234" ], "product_ids": [ "256990616123" ], "reference_codes": [ "SELLERSKU 123456" ], "sku_ids": [ "256086568895" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchGoodsInfoResponse" }, "example": { "code": 0, "data": { "next_page_token": "cGFnZV9udW1iZXI9Mg==", "total_count": 123, "goods": [ { "id": "86533997569", "name": "water1.0", "barcodes": [ { "code": "014673829105", "type": "UPC" } ], "reference_code": "abc32323", "image_url": "https://example.com/fbt/goods-image.jpg", "merchant_declaration_info": { "weight": { "value": "1.122", "unit": "GRAM" }, "dimension": { "width": "1.122", "length": "2.122", "height": "3.122", "unit": "CENTIMETER" } }, "warehouse_confirmation_info": { "weight": { "value": "1", "unit": "GRAM" }, "dimension": { "width": "1", "length": "2.5", "height": "3", "unit": "CENTIMETER" } }, "skus": [ { "id": "1729439634328225260", "name": "Testcase SKU", "image_url": "https://example.com/fbt/sku-image.jpg", "product": { "id": "1729439631253210604", "name": "Testcase_xd2.0_test_goods", "image_url": "https://example.com/fbt/product-image.jpg" }, "regions": [ "US" ], "matched": true } ], "lot_expiration_info": { "is_lot_control": true, "is_expiration_management": true, "shelf_life_days": 12, "inbound_cutoff_days": 90, "expiration_alert_days": 60, "sales_cutoff_days": 20, "handling_method": "DISPOSE" }, "is_hazmat": false, "hazmat_info": { "hazmat_type": "MAGNETIZED", "battery_extra_info": { "battery_type": "LITHIUM_ION", "battery_packaging_type": "STANDALONE", "total_battery_weight": "1", "total_battery_weight_unit": "GRAM", "total_battery_capacity": "1", "battery_count_per_package": "2", "is_need_un_38_3_test": false, "un_38_3_test_file_url": "https://example.com/fbt/msds-report.pdf", "total_battery_capacity_unit": "WATT_HOURS" }, "flammable_liquids_extra_info": { "flammable_liquids_type": "PAINT", "flammable_liquids_volume": "1", "volume_unit": "MILLILITER" }, "aerosol_extra_info": { "volume": "1", "volume_unit": "MILLILITER" }, "dg_class": "CLASS_2", "dg_uncode": "UN1266", "msds_file_url": "https://example.com/fbt/msds-report.pdf" }, "sioc_approval_status": "SIOC_APPROVAL_STATUS_APPROVE", "hazmat_approval_status": "APPROVAL_STATUS_UNDER_REVIEW", "bulky_item_attribute": { "is_bulky_item": false, "is_bulky_item_accessories": false }, "goods_safety_attributes": { "is_fragile": false, "is_liquid": false, "is_sharp": false }, "is_sioc": false, "sioc_attribute": { "sioc_files": [ { "sioc_certification_url": "https://example.com/fbt/sioc-certification.jpg", "sioc_file_type": "PHOTO" } ] } } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfilled by TikTok(FBT) Info" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-goods-info-202607" } }, "/fbt/202607/goods/update_goods_info": { "post": { "operationId": "updateFBTGoodsInfo", "summary": "Update FBT Goods Info", "description": "Update FBT goods information, including goods name, image URL, dimensions, hazmat details, shelf-life attributes, and return address information.", "tags": [ "Fulfilled by TikTok (FBT)" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFBTGoodsInfoRequest" }, "example": { "update_goods_dto": { "tts_goods_id": "8839232030", "goods_name": "Wireless Charging Cable", "goods_image_url": "https://example.com/fbt/goods-image.jpg", "reference_code": "ABDK999d", "barcode_infos": [ { "barcode_type": "UPC", "barcode_value": "223333" } ], "return_handling_method": "RESTOCK_SELLABLE_DISPOSE_UNSELLABLE", "dimension_and_weight_base_info": { "weight_value": "500", "length_value": "40", "width_value": "20", "height_value": "30", "weight_unit": "GRAM", "dimension_unit": "CENTIMETER" }, "is_hazmat": false, "hazmat_info": { "hazmat_type": "BATTERY", "battery_extra_info": { "battery_type": "LITHIUM_ION", "battery_packaging_type": "STANDALONE", "total_battery_weight": "10", "total_battery_weight_unit": "GRAM", "total_battery_capacity": "2", "total_battery_capacity_unit": "WATTHOUR", "is_need_un_38_3_test": false, "un_38_3_test_file_url": "https://example.com/fbt/un38-3-test-report.pdf", "battery_count_per_package": "3" }, "flammable_liquids_extra_info": { "flammable_liquids_type": "PAINT", "flammable_liquids_volume": "1", "volume_unit": "MILLILITERS" }, "dg_class": "CLASS_3", "dg_uncode": "UN2807", "msds_file_url": "https://example.com/fbt/msds-report.pdf", "aerosol_extra_info": { "volume": "1", "volume_unit": "MILLILITERS" } }, "is_lot_code": false, "is_expiration_management": false, "shelf_life_attribute_info": { "shelf_life": 10, "inbound_cutoff_days": 90, "expiration_alert_days": 80, "sales_cutoff_days": 70, "handling_method_expired_goods": "DISPOSE" }, "is_sioc": false, "sioc_attribute": { "sioc_files": [ { "sioc_certification_url": "https://example.com/fbt/sioc-certification.jpg", "sioc_file_type": "PHOTO" } ] }, "bulky_item_attribute": { "is_bulky_item_accessories": false }, "goods_safety_attributes": { "is_fragile": false, "is_liquid": false, "is_sharp": false } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFBTGoodsInfoResponse" }, "example": { "code": 0, "data": { "update_result_info": { "tts_goods_id": "1233444", "is_success": true, "fail_reason": "Goods update failed." } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfilled by TikTok(FBT) Info" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/update-fbt-goods-info-202607" } }, "/fbt/202607/mcf_outbound_orders": { "post": { "operationId": "createFBTMCFOrder", "summary": "Create FBT MCF Order", "description": "For orders created on other sales channels that require fulfillment via FBT, this API enables you to create corresponding orders (hereinafter referred to as MCF Orders). Once MCF Orders are successfully created, they will be automatically submitted to the FBT system for fulfillment.", "tags": [ "Fulfilled by TikTok (FBT)" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFBTMCFOrderRequest" }, "example": { "external_order_id": "shopify202208291503530001100220033", "goods": [ { "id": "1234567", "quantity": 1 } ], "consignee": { "name": "username", "phone_number": "(+1)1211223910", "email": "username@example.com", "address": { "country_code": "US", "state_or_region": "Alabama", "district_or_county": "Baldwin", "city": "Bay Minette", "address_line_1": "312 Courthouse Square", "address_line_2": "Suite 10", "postal_code": "36507" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFBTMCFOrderResponse" }, "example": { "code": 0, "data": { "mcf_order": { "external_order_id": "shopify202208291503530001100220033", "mcf_order_id": "7136104329798256386", "create_time": 1661756811 } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfilled by TikTok(FBT) Info" ], "x-tts-error-codes": [ { "code": "177001001", "message": "Missing parameters or parameters have incorrect format" }, { "code": "177001002", "message": "Item data does not exist in the FBT system. You must provide valid item IDs; otherwise, the FBT system cannot fulfill the order." }, { "code": "177001003", "message": "The address information has failed verification. Please check the validity of the address, Please make sure your address is accurate, check address via USPS ZIP Lookup Tool." }, { "code": "177001004", "message": "Insufficient inventory; unable to fulfill the order. Please replenish the inventory or arrange delivery via alternative methods." }, { "code": "177001006", "message": "The merchant has no permission to create external orders; please check your permissions or contact the platform." }, { "code": "177001007", "message": "The external_order_number has been associated with an active MCF Order. The FBT system is currently processing the order delivery, and duplicate order creation is not allowed." }, { "code": "177001008", "message": "The order creation rate limit has been exceeded; please reduce the call frequency or try again later." }, { "code": "177001009", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "177001010", "message": "Order information cannot be retrieved via the mcf_order_id you provided; please check if your ID is correct." }, { "code": "177001011", "message": "address is unreachable" }, { "code": "177001012", "message": "order has been pushed to fulfillment system, cannot push again" }, { "code": "177001013", "message": "no permission,please pay for the FBT billing first" }, { "code": "177001014", "message": "the zipcode is wrong" }, { "code": "177001015", "message": "new goods have not yet arrived at the warehouse" }, { "code": "177001016", "message": "the maximum number of goods per order cannot exceed 99" } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/create-fbt-mcf-order-202607" } }, "/finance/202309/statements": { "get": { "operationId": "getStatements", "summary": "Get Statements", "description": "Retrieves the statements generated for a shop and the key statement information based on a specified date range or their payment status. Use this API to get an overview of your daily statements over a range of time, or to find out which statements have been paid or not. For the detailed transactions, refer to [Get Statement Transactions](650a6749defece02be67da87) or [Get Order Statement Transactions](650a6734defece02be67d724).\nApplicable for all regions' sellers. Only data after 2023-07-01 is available.", "tags": [ "Finance" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "statement_time_lt", "in": "query", "required": false, "description": "Filter statements to show only those generated before the specified date and time. Unix timestamp in seconds.\nRefer to the notes in `statement_time_ge` for more usage information.", "schema": { "type": "integer", "format": "int64" } }, { "name": "payment_status", "in": "query", "required": false, "description": "Filter statements based on the payment status.\nPossible values:\n- PAID: Payment has been transferred to the seller.\n- FAILED: Payment transfer failed.\n- PROCESSING: Payment is currently being processed.\nDefault: All statuses are returned.", "schema": { "type": "string", "enum": [ "PAID", "FAILED", "PROCESSING" ], "x-enum-descriptions": [ "Payment has been transferred to the seller.", "Payment transfer failed.", "Payment is currently being processed." ] } }, { "name": "page_size", "in": "query", "required": false, "description": "The number of results to be returned per page. \nDefault: 20\nValid range: [1-100]", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 100 } }, { "name": "page_token", "in": "query", "required": false, "description": "An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the `next_page_token` from a previous response. It is not needed for the first page.", "schema": { "type": "string" } }, { "name": "sort_field", "in": "query", "required": true, "description": "The returned results will be sorted by the specified field. Only supports `statement_time`.", "schema": { "type": "string" } }, { "name": "sort_order", "in": "query", "required": false, "description": "The sort order for the `sort_field` parameter. \nDefault: ASC \nPossible values:\n- ASC: Ascending order\n- DESC: Descending order", "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "x-enum-descriptions": [ "Ascending order", "Descending order" ] } }, { "name": "statement_time_ge", "in": "query", "required": false, "description": "Filter statements to show only those generated on or after the specified date and time. Unix timestamp in seconds.\n\n**Note:**\n`statement_time_ge` and `statement_time_lt` together define a half-open statement-generation time range: `statement_time_ge` is inclusive and `statement_time_lt` is exclusive.\n- If `statement_time_ge` is provided but `statement_time_lt` is omitted, `statement_time_lt` defaults to the current time.\n- If `statement_time_lt` is provided but `statement_time_ge` is omitted, `statement_time_ge` defaults to the earliest shop time.\n\n**Example:**\nStatements are generated daily at 00:00 UTC and cover transactions from the previous day. To query the statement generated for transactions on April 28, 2026, use the exact statement-generation interval `[2026-04-29T00:00:00Z, 2026-04-30T00:00:00Z)`:\n- Set `statement_time_ge` to `1777420800` (inclusive).\n- Set `statement_time_lt` to `1777507200` (exclusive).", "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetStatementsResponse" }, "example": { "code": 0, "data": { "next_page_token": "6AsPQsUMvH3RkchNUPPh22NROHkE0D8pmq/N5M1kHYcZmtRyv9aVrNv65W7Q6tFA+7D1ud64MPNz5OaT", "statements": [ { "id": "7238804564097517339", "statement_time": 1685548800, "settlement_amount": "100", "currency": "GBP", "revenue_amount": "200", "fee_amount": "-30", "adjustment_amount": "-70", "payment_status": "PAID", "payment_id": "3459275187040258849", "net_sales_amount": "-70", "shipping_cost_amount": "-70", "payment_time": 1685548800 } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Finance Information" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-statements-202309" } }, "/finance/202309/withdrawals": { "get": { "operationId": "getSellerFinancialTransactions", "summary": "Get Seller Financial Transactions", "description": "Retrieves seller financial transaction records within an optional creation-time range, filtered by the required transaction types.", "tags": [ "Finance" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "create_time_lt", "in": "query", "required": false, "description": "Unix timestamp representing the end of transactions time range one wants to request", "schema": { "type": "integer", "format": "int64" } }, { "name": "types", "in": "query", "required": true, "description": "The transaction types to return.\nPossible values:\n- WITHDRAW: The seller withdraws the settlement amount to a bank card.\n- SETTLE: The platform settles the amount to the seller.\n- TRANSFER: A platform subsidy or deduction due to platform policies.\n- REVERSE: A withdrawal failure caused by incorrect bank card information.\n- PAYMENT: A payment transaction.\n- REFUND: A refund transaction.", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "WITHDRAW", "SETTLE", "TRANSFER", "REVERSE", "PAYMENT", "REFUND" ], "x-enum-descriptions": [ "The seller withdraws the settlement amount to a bank card.", "The platform settles the amount to the seller.", "A platform subsidy or deduction due to platform policies.", "A withdrawal failure caused by incorrect bank card information.", "A payment transaction.", "A refund transaction." ] } } }, { "name": "page_size", "in": "query", "required": false, "description": "The default is 20, it must be positive integer,the range is 1-100", "schema": { "type": "integer", "format": "int64" } }, { "name": "page_token", "in": "query", "required": false, "description": "The `next_page_token` returned by the previous response. Omit this parameter when requesting the first page. When paginating, specify `create_time_ge` and `create_time_lt` in the first request, then reuse the same `types`, `create_time_ge`, and `create_time_lt` values for every page.", "schema": { "type": "string" } }, { "name": "create_time_ge", "in": "query", "required": false, "description": "Unix timestamp representing the start of transactions time range one wants to request", "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSellerFinancialTransactionsResponse" }, "example": { "code": 0, "data": { "next_page_token": "6AsPQsUMvH3RkchNUPPh22NROHkE0D8pmq/N5M1kHYcZmtRyv9aVrNv65W7Q6tFA+7D1ud64MPNz5OaT", "total_count": 1, "withdrawals": [ { "id": "EFASDFSAFDA23432DFAFDSA", "type": "WITHDRAW", "amount": "100", "currency": "IDR", "status": "PROCESSING", "create_time": 1623812664 } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Finance Information" ], "x-tts-error-codes": [ { "code": "22005007", "message": "given merchant does not exist" }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-seller-financial-transactions-202309" } }, "/finance/202501/orders/{order_id}/statement_transactions": { "get": { "operationId": "getTransactionsByOrder", "summary": "Get Transactions by Order", "description": "Retrieves the SKU-level details of an order transaction. This covers transactions related to sales, fees, commissions, shipping, taxes, and refunds.\nApplicable for all regions' sellers. Only data after 2023-07-01 is available (Please note that for US cross-border sellers, data before 2025-04-30 is unavailable).", "tags": [ "Finance" ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "description": "The order ID in TikTok Shop.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTransactionsByOrderResponse" }, "example": { "code": 0, "data": { "order_id": "5793990727963214852", "order_create_time": 1685548800, "currency": "GBP", "revenue_amount": "200", "fee_and_tax_amount": "-30", "shipping_cost_amount": "-70", "settlement_amount": "130", "sku_transactions": [ { "sku_id": "1636700041413599290", "sku_name": "Test SKU name", "statement_id": "7238804564097517339", "product_name": "Test Product name", "quantity": "1", "settlement_amount": "130", "revenue_amount": "200", "revenue_breakdown": { "subtotal_before_discount_amount": "210", "seller_discount_amount": "-10", "refund_subtotal_before_discount_amount": "0", "seller_discount_refund_amount": "0", "cod_service_fee_amount": "0", "refund_cod_service_fee_amount": "0", "distant_item_fee_amount": "0" }, "shipping_cost_amount": "-70", "shipping_cost_breakdown": { "actual_shipping_fee_amount": "-50", "international_leg_logistics_amount": "0", "shipping_fee_discount_amount": "0", "customer_paid_shipping_fee_amount": "0", "return_shipping_fee_amount": "-10", "replacement_shipping_fee_amount": "-10", "exchange_shipping_fee_amount": "5", "signature_confirmation_fee_amount": "5", "shipping_insurance_fee_amount": "0", "fbt_fulfillment_fee_reimbursement_amount": "5", "return_shipping_label_fee_amount": "5", "seller_self_shipping_service_fee_amount": "5", "return_shipping_fee_paid_buyer_amount": "5", "failed_delivery_subsidy_amount": "5", "fbt_free_shipping_fee_amount": "5", "free_return_subsidy_amount": "5", "distant_shipping_fee_amount": "0", "shipping_app_service_fee_amount": "0", "logistics_service_fee": "0", "fbt_overall_merchant_subsidy": "0", "fbt_key_merchant_subsidy": "0", "tiktok_shop_shipping_incentive_amount": "0", "supplementary_component": { "fbt_fulfillment_fee_reimbursement_amount": "5", "platform_shipping_fee_discount_amount": "20", "promo_shipping_incentive_amount": "0", "shipping_fee_subsidy_amount": "0", "seller_shipping_fee_discount_amount": "0", "fbt_shipping_cost_amount": "-30", "customer_shipping_fee_offset_amount": "-6.99", "fbm_shipping_cost_amount": "30", "fbt_fulfillment_fee_amount": "0", "return_refund_subsidy_amount": "0", "refunded_customer_shipping_fee_amount": "0", "shipping_fee_guarantee_reimbursement": "0" }, "hazmat_noncompliance_fee": "0", "hazmat_handling_fee": "0", "non_standard_weight_fee": "0", "non_standard_dimension_fee": "0" }, "fee_tax_amount": "-30", "fee_tax_breakdown": { "fee": { "platform_commission_amount": "0", "referral_fee_amount": "-2", "refund_administration_fee_amount": "0", "transaction_fee_amount": "-2", "credit_card_handling_fee_amount": "0", "affiliate_commission_amount": "0", "affiliate_commission_amount_before_pit": "-2", "affiliate_partner_commission_amount": "0", "affiliate_ads_commission_amount": "0", "sfp_service_fee_amount": "2", "live_specials_fee_amount": "2", "bonus_cashback_service_fee_amount": "0", "mall_service_fee_amount": "0", "voucher_xtra_service_fee_amount": "100", "flash_sales_service_fee_amount": "50", "cofunded_promotion_service_fee_amount": "100", "pre_order_service_fee_amount": "10", "tsp_commission_amount": "10", "dt_handling_fee_amount": "10", "epr_pob_service_fee_amount": "-10", "fee_per_item_sold_amount": "0", "seller_paylater_handling_fee_amount": "-10", "cofunded_creator_bonus_amount": "-10", "dynamic_commission_amount": "5", "external_affiliate_marketing_fee_amount": "10", "vn_fix_infrastructure_fee": "0", "affiliate_commission_deposit": "0", "affiliate_commission_release": "0", "tap_shop_ads_commission": "0", "shipping_fee_guarantee_service_fee": "0", "installation_service_fee": "0", "campaign_resource_fee": "0", "platform_special_service_fee_amount": "0", "smart_promotion_fee_amount": "0", "gmv_max_ad_fee_amount": "0", "platform_semi_managed_commission_fee": "0", "platform_semi_managed_commission_fee_tax": "0", "campaign_period_fee_cfp_amount": "0", "campaign_period_fee_sp_amount": "0", "campaign_period_fee_sp_tax_amount": "0", "campaign_period_fee_cfp_tax_amount": "0", "seller_growth_fee_amount": "0", "category_led_campaign_fee_amount": "0", "category_led_campaign_fee_tax_amount": "0", "brand_amplification_program_commission": "0", "brand_amplification_program_fee_tax": "0", "brand_campaign_fee": "0", "brand_campaign_fee_tax": "0", "failed_delivery_shipping_fee": "0", "buyer_fault_return_shipping_fee": "0", "insurance_fee": "0", "gmv_max_coupon_fee": "0", "cps_shop_ads_commission_tax_amount": "0", "shipping_insurance_fee_tax_amount": "0", "new_customer_growth_package_fee": "0", "target_product_gmv_growth_package_fee": "0", "store_gmv_growth_package_fee": "0", "auto_post_shoppable_video_commission_fee": "0", "seller_funded_user_spoint_service_fee": "0" }, "tax": { "vat_amount": "0", "import_vat_amount": "0", "customs_duty_amount": "0", "customs_clearance_amount": "0", "sst_amount": "0", "gst_amount": "0", "iva_amount": "0", "isr_amount": "0", "anti_dumping_duty_amount": "20", "local_vat_amount": "10", "pit_amount": "10", "sales_tax_referral_fee_amount": "0", "smart_promotion_fee_tax_amount": "0", "cedular_tax": "0", "new_customer_growth_package_fee_tax": "0", "store_gmv_growth_package_fee_sales_tax": "0", "target_product_gmv_growth_package_tax": "0", "auto_post_shoppable_video_sales_tax": "0", "article_22_income_tax_withheld": "0" } } } ], "total_count": 2 }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Finance Information" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-transactions-by-order-202501" } }, "/finance/202501/statements/{statement_id}/statement_transactions": { "get": { "operationId": "getTransactionsByStatement", "summary": "Get Transactions by Statement", "description": "Retrieves the details of a statement, including the transactions, which can be a standard order transaction, an adjustment transaction, or a reserve-related transaction. For the SKU-level details of an order transaction, refer to [Get Transactions by Order](650a6734defece02be67d724).\nApplicable for all regions' sellers. Only data after 2023-07-01 is available (Please note that for US cross-border sellers, data before 2025-04-30 is unavailable).", "tags": [ "Finance" ], "parameters": [ { "name": "statement_id", "in": "path", "required": true, "description": "The unique id of statement", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" }, { "name": "page_token", "in": "query", "required": false, "description": "An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the `next_page_token` from a previous response. It is not needed for the first page.", "schema": { "type": "string" } }, { "name": "sort_field", "in": "query", "required": true, "description": "The returned results will be sorted by the specified field. Only supports `order_create_time`.", "schema": { "type": "string" } }, { "name": "sort_order", "in": "query", "required": false, "description": "The sort order for the `sort_field` parameter. \nDefault: ASC \nPossible values:\n- ASC: Ascending order\n- DESC: Descending order", "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "x-enum-descriptions": [ "Ascending order", "Descending order" ] } }, { "name": "page_size", "in": "query", "required": false, "description": "The number of results to be returned per page. \nDefault: 20\nValid range: [1-100]", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTransactionsByStatementResponse" }, "example": { "code": 0, "data": { "next_page_token": "6AsPQsUMvH3RkchNUPPh22NROHkE0D8pmq/N5M1kHYcZmtRyv9aVrNv65W7Q6tFA+7D1ud64MPNz5OaT", "id": "7238804564097517339", "create_time": 1685548800, "status": "SETTLED", "currency": "GBP", "payable_amount": "150", "total_reserve_amount": "20", "total_settlement_amount": "130", "total_settlement_breakdown": { "total_revenue_amount": "100", "total_shipping_cost_amount": "120", "total_fee_tax_amount": "20", "total_adjustment_amount": "0" }, "total_count": 2, "transactions": [ { "id": "1636700041413599290", "type": "ORDER", "order_id": "576463220456522968", "order_create_time": 1685548800, "adjustment_id": "7238804564097517332", "adjustment_order_id": "576463220456522968", "adjustment_amount": "170", "settlement_amount": "130", "revenue_amount": "200", "revenue_breakdown": { "subtotal_before_discount_amount": "30", "refund_subtotal_before_discount_amount": "-20", "seller_discount_amount": "10", "seller_discount_refund_amount": "12", "cod_service_fee_amount": "10", "refund_cod_service_fee_amount": "-10", "distant_item_fee_amount": "0" }, "shipping_cost_amount": "-70", "shipping_cost_breakdown": { "actual_shipping_fee_amount": "0", "international_leg_logistics_amount": "0", "shipping_fee_discount_amount": "0", "customer_paid_shipping_fee_amount": "-10", "return_shipping_fee_amount": "-10", "replacement_shipping_fee_amount": "12", "exchange_shipping_fee_amount": "0", "signature_confirmation_fee_amount": "10", "shipping_insurance_fee_amount": "-10", "fbt_fulfillment_fee_reimbursement_amount": "5", "return_shipping_label_fee_amount": "5", "seller_self_shipping_service_fee_amount": "5", "return_shipping_fee_paid_buyer_amount": "5", "failed_delivery_subsidy_amount": "5", "shipping_fee_guarantee_reimbursement": "0", "fbt_free_shipping_fee_amount": "0", "free_return_subsidy_amount": "0", "distant_shipping_fee_amount": "0", "shipping_app_service_fee_amount": "0", "logistics_service_fee": "0", "fbt_overall_merchant_subsidy": "0", "fbt_key_merchant_subsidy": "0", "tiktok_shop_shipping_incentive_amount": "0", "supplementary_component": { "platform_shipping_fee_discount_amount": "-10", "promo_shipping_incentive_amount": "-5", "shipping_fee_subsidy_amount": "5", "seller_shipping_fee_discount_amount": "4", "customer_shipping_fee_offset_amount": "23", "fbm_shipping_cost_amount": "20", "fbt_shipping_cost_amount": "30", "fbt_fulfillment_fee_amount": "-30", "fbt_fulfillment_fee_reimbursement_amount": "5", "return_refund_subsidy_amount": "5", "refunded_customer_shipping_fee_amount": "5", "customer_shipping_fee": "5", "refund_customer_shipping_fee": "1" }, "hazmat_noncompliance_fee": "0", "hazmat_handling_fee": "0", "non_standard_weight_fee": "0", "non_standard_dimension_fee": "0" }, "fee_tax_amount": "-30", "fee_tax_breakdown": { "fee": { "platform_commission_amount": "20", "referral_fee_amount": "11", "refund_administration_fee_amount": "10", "transaction_fee_amount": "0", "credit_card_handling_fee_amount": "0", "affiliate_commission_amount": "5", "affiliate_commission_amount_before_pit": "3", "affiliate_partner_commission_amount": "12", "affiliate_ads_commission_amount": "10", "sfp_service_fee_amount": "5", "live_specials_fee_amount": "4", "bonus_cashback_service_fee_amount": "2", "mall_service_fee_amount": "12", "voucher_xtra_service_fee_amount": "10", "flash_sales_service_fee_amount": "12", "cofunded_promotion_service_fee_amount": "4", "pre_order_service_fee_amount": "10", "tsp_commission_amount": "10", "dt_handling_fee_amount": "10", "epr_pob_service_fee_amount": "10", "seller_paylater_handling_fee_amount": "-10", "fee_per_item_sold_amount": "0", "cofunded_creator_bonus_amount": "-10", "dynamic_commission_amount": "5", "external_affiliate_marketing_fee_amount": "10", "vn_fix_infrastructure_fee": "0", "affiliate_commission_deposit": "0", "affiliate_commission_release": "0", "tap_shop_ads_commission": "0", "shipping_fee_guarantee_service_fee": "0", "installation_service_fee": "0", "campaign_resource_fee": "0", "platform_special_service_fee_amount": "0", "smart_promotion_fee_amount": "0", "gmv_max_ad_fee_amount": "0", "platform_semi_managed_commission_fee": "0", "platform_semi_managed_commission_fee_tax": "0", "campaign_period_fee_cfp_amount": "0", "campaign_period_fee_sp_amount": "0", "campaign_period_fee_sp_tax_amount": "0", "campaign_period_fee_cfp_tax_amount": "0", "seller_growth_fee_amount": "0", "category_led_campaign_fee_amount": "0", "category_led_campaign_fee_tax_amount": "0", "brand_amplification_program_commission": "0", "brand_amplification_program_fee_tax": "0", "brand_campaign_fee": "0", "brand_campaign_fee_tax": "0", "failed_delivery_shipping_fee": "0", "buyer_fault_return_shipping_fee": "0", "insurance_fee": "0", "gmv_max_coupon_fee": "0", "cps_shop_ads_commission_tax_amount": "0", "shipping_insurance_fee_tax_amount": "0", "new_customer_growth_package_fee": "0", "target_product_gmv_growth_package_fee": "0", "store_gmv_growth_package_fee": "0", "auto_post_shoppable_video_commission_fee": "0", "seller_funded_user_spoint_service_fee": "0" }, "tax": { "vat_amount": "30", "import_vat_amount": "10", "customs_duty_amount": "5", "customs_clearance_amount": "4", "sst_amount": "3", "gst_amount": "1", "iva_amount": "5", "isr_amount": "5", "anti_dumping_duty_amount": "10", "local_vat_amount": "10", "pit_amount": "10", "sales_tax_referral_fee_amount": "0", "smart_promotion_fee_tax_amount": "0", "cedular_tax": "0", "new_customer_growth_package_fee_tax": "0", "store_gmv_growth_package_fee_sales_tax": "0", "target_product_gmv_growth_package_tax": "0", "auto_post_shoppable_video_sales_tax": "0", "article_22_income_tax_withheld": "0" } }, "supplementary_component": { "customer_payment_amount": "0", "customer_refund_amount": "0", "platform_discount_amount": "10", "platform_discount_refund_amount": "1", "seller_cofunded_discount_amount": "44", "seller_cofunded_discount_refund_amount": "23", "platform_cofunded_discount_amount": "11", "platform_cofunded_discount_refund_amount": "10", "retail_delivery_fee_amount": "-1", "retail_delivery_fee_payment_amount": "4", "retail_delivery_fee_refund_amount": "2", "sales_tax_amount": "10", "sales_tax_payment_amount": "0", "sales_tax_refund_amount": "0 " }, "reserve_id": "56789910", "reserve_amount": "100", "associated_order_id": "78217892102382101", "reserve_status": "COLLECTED", "estimated_release_time": "1685548800" } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Finance Information" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-transactions-by-statement-202501" } }, "/finance/202507/orders/unsettled": { "get": { "operationId": "getUnsettledTransactions", "summary": "Get Unsettled Transactions", "description": "This API allows the partner to retrieve a list of unsettled transactions (incl. Orders & Adjustments) generated by a seller, returning the detailed fee breakdown for a list of order ID and adjustment ID. \nFor now, this API only returns transactions which were created after 2025.01.01. Once one transaction is settled, which won't be returned by this API anymore, please get from Get Statement Transaction API. \n**Pay attention to that all data returned through this API is an estimated amount which subject to change before settlement and can only used for seller's reference, final settlement amount per each transaction can only provided through statement related API.", "tags": [ "Finance" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "page_token", "in": "query", "required": false, "description": "An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the `next_page_token` from a previous response. It is not needed for the first page.", "schema": { "type": "string" } }, { "name": "page_size", "in": "query", "required": false, "description": "The number of results to be returned per page. \nDefault: 20\nValid range: [1-100]", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 100 } }, { "name": "sort_field", "in": "query", "required": true, "description": "The returned results will be sorted by the specified field. Only supports `order_create_time`.", "schema": { "type": "string" } }, { "name": "sort_order", "in": "query", "required": false, "description": "The sort order for the `sort_field` parameter. \nDefault: ASC \nPossible values:\n- ASC: Ascending order\n- DESC: Descending order", "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "x-enum-descriptions": [ "Ascending order", "Descending order" ] } }, { "name": "search_time_ge", "in": "query", "required": false, "description": "Filter statements to show only those that are generated on or after the\nspecified date and time. Unix timestamp. Note:statement_time_ge and statement_time_lt together constitute the creation time filter condition. - If statement_time_ge is filled but statement_time_lt is empty, statement_time_lt will default to the current time. - If statement_time_lt is filled but statement_time_ge is empty, statement_time_ge will default to 20250101.", "schema": { "type": "integer", "format": "int64" } }, { "name": "search_time_lt", "in": "query", "required": false, "description": "the search range's end time", "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetUnsettledTransactionsResponse" }, "example": { "code": 0, "data": { "next_page_token": "6AsPQsUMvH3RkchNUPPh22NROHkE0D8pmq/N5M1kHYcZmtRyv9aVrNv65W7Q6tFA+7D1ud64MPNz5OaT", "total_count": 2, "sum_est_settlement_amount": "100", "sum_est_revenue_amount": "10", "sum_est_adjustment_amount": "-10", "sum_est_fee_amount": "-10", "transactions": [ { "type": "ORDER", "id": "1636700041413599290", "status": "UNSETTLED", "currency": "USD", "estimated_settlement": "1685548800", "unsettled_reason": "waiting for deliveery", "order_create_time": 1685548800, "order_delivery_time": 1685548800, "order_id": "576463220456522968", "adjustment_id": "7238804564097517332", "adjustment_order_id": "576463220456522968", "est_adjustment_amount": "170", "est_settlement_amount": "130", "est_revenue_amount": "200", "revenue_breakdown": { "subtotal_before_discount_amount": "210", "seller_discount_amount": "-10", "refund_subtotal_before_discount_amount": "0", "seller_discount_refund_amount": "0", "cod_service_fee_amount": "0", "refund_cod_service_fee_amount": "0", "distant_item_fee_amount": "0" }, "est_shipping_cost_amount": "-70", "shipping_cost_breakdown": { "actual_shipping_fee_amount": "-50", "international_leg_logistics_amount": "0", "shipping_fee_discount_amount": "50", "customer_paid_shipping_fee_amount": "70", "return_shipping_fee_amount": "-10", "replacement_shipping_fee_amount": "-10", "exchange_shipping_fee_amount": "-10", "signature_confirmation_fee_amount": "-5", "shipping_insurance_fee_amount": "-5", "distant_shipping_fee_amount": "0", "shipping_app_service_fee_amount": "0", "logistics_service_fee": "0", "fbt_overall_merchant_subsidy": "0", "fbt_key_merchant_subsidy": "0", "supplementary_component": { "customer_shipping_fee_offset_amount": "-6.99", "shipping_fee_subsidy_amount": "0", "platform_shipping_fee_discount_amount": "20", "fbm_shipping_cost_amount": "0", "fbt_shipping_cost_amount": "0", "promo_shipping_incentive_amount": "30", "fbt_fulfillment_fee_amount": "-50", "seller_shipping_fee_discount_amount": "0" }, "sfr_reimbursement": "0", "tiktok_shop_shipping_incentive_amount": "0", "hazmat_noncompliance_fee": "0", "hazmat_handling_fee": "0", "non_standard_weight_fee": "0", "non_standard_dimension_fee": "0" }, "est_fee_tax_amount": "-30", "fee_tax_breakdown": { "fee": { "platform_commission_amount": "0", "referral_fee_amount": "-2", "refund_administration_fee_amount": "0", "transaction_fee_amount": "-2", "credit_card_handling_fee_amount": "-2", "affiliate_commission_amount": "-4", "affiliate_commission_before_pit_amount": "-6", "pit_withheld_from_ads_commission_amount": "2", "affiliate_partner_commission_amount": "0", "affiliate_ads_commission_amount": "-3", "sfp_service_fee_amount": "0", "live_specials_fee_amount": "0", "bonus_cashback_service_fee_amount": "0", "mall_service_fee_amount": "0", "retail_delivery_fee_amount": "0", "retail_delivery_fee_payment_amount": "0", "retail_delivery_fee_refund_amount": "0", "platform_special_service_fee_amount": "0", "smart_promotion_fee_amount": "0", "vn_fix_infrastructure_fee": "0", "dynamic_commission_amount": "0", "campaign_period_fee_cfp_amount": "0", "campaign_period_fee_sp_amount": "0", "campaign_period_fee_sp_tax_amount": "0", "campaign_period_fee_cfp_tax_amount": "0", "seller_growth_fee_amount": "0", "failed_delivery_shipping_fee": "0", "buyer_fault_return_shipping_fee": "0", "insurance_fee": "0", "cps_shop_ads_commission_tax_amount": "0", "shipping_insurance_fee_tax_amount": "0", "new_customer_growth_package_fee": "0", "target_product_gmv_growth_package_fee": "0", "store_gmv_growth_package_fee": "0", "auto_post_shoppable_video_commission_fee": "0", "seller_funded_user_spoint_service_fee": "0", "flash_sales_service_fee_amount": "0" }, "tax": { "sales_tax_amount": "-10", "sales_tax_payment_amount": "10", "sales_tax_refund_amount": "0", "vat_amount": "0", "import_vat_amount": "0", "customs_duty_amount": "0", "customs_clearance_amount": "0", "sst_amount": "0", "gst_amount": "0", "sales_tax_referral_fee_amount": "0", "smart_promotion_fee_tax_amount": "0", "cedular_tax": "0", "new_customer_growth_package_fee_tax": "0", "store_gmv_growth_package_fee_sales_tax": "0", "target_product_gmv_growth_package_tax": "0", "auto_post_shoppable_video_sales_tax": "0" } } } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Finance Information" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-unsettled-transactions-202507" } }, "/finance/202605/payments": { "get": { "operationId": "getPayments", "summary": "Get Payments", "description": "**This API is currently unavailable to SEA markets.**\nRetrieves records of automated payments for a shop based on a specified date range.\nUse the returned list to verify and reconcile payments with the transactions in the seller's bank account.", "tags": [ "Finance" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "create_time_lt", "in": "query", "required": false, "description": "Filter payments to show only those initiated before the specified date and time. Unix timestamp in seconds.\nRefer to notes in `create_time_ge` for more usage information.", "schema": { "type": "integer", "format": "int64" } }, { "name": "page_size", "in": "query", "required": false, "description": "The number of results to be returned per page. \nDefault: 20\nValid range: [1-100]", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 100 } }, { "name": "page_token", "in": "query", "required": false, "description": "An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the `next_page_token` from a previous response. It is not needed for the first page.", "schema": { "type": "string" } }, { "name": "sort_field", "in": "query", "required": true, "description": "The returned results will be sorted by the specified field. Only supports `create_time`.", "schema": { "type": "string" } }, { "name": "sort_order", "in": "query", "required": false, "description": "The sort order for the `sort_field` parameter. \nDefault: ASC \nPossible values:\n- ASC: Ascending order\n- DESC: Descending order", "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "x-enum-descriptions": [ "Ascending order", "Descending order" ] } }, { "name": "create_time_ge", "in": "query", "required": false, "description": "Filter payments to show only those that occurred on or after the specified date and time. Unix timestamp.\n\n**Note:**\n`create_time_ge` and `create_time_lt` together constitute the creation time filter condition.\n- If `create_time_ge` is filled but `create_time_lt` is empty, `create_time_lt` will default to the current time.\n- If `create_time_lt` is filled but `create_time_ge` is empty, `create_time_ge` will default to the earliest shop time.", "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPaymentsResponse" }, "example": { "code": 0, "data": { "next_page_token": "6AsPQsUMvH3RkchNUPPh22NROHkE0D8pmq/N5M1kHYcZmtRyv9aVrNv65W7Q6tFA+7D1ud64MPNz5OaT", "payments": [ { "create_time": 1636105796, "id": "3458767051733897992", "status": "PAID", "amount": { "value": "100", "currency": "GBP" }, "settlement_amount": { "value": "130", "currency": "GBP" }, "payment_amount_before_exchange": { "value": "100", "currency": "GBP" }, "exchange_rate": "1.000000", "paid_time": 1685548800, "bank_account": "***********1234" } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Finance Information" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-payments-202605" } }, "/finance/202609/account_balances": { "get": { "operationId": "getTradeInSupplierAccountBalance", "summary": "Get TradeIn Supplier Account Balance", "description": "Retrieves the available account balance for the currently authorized TradeIn supplier.\nThe supplier identity is resolved from the authorization context. The caller cannot specify supplier_id or party_id.", "tags": [ "Finance" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "currency", "in": "query", "required": true, "description": "The currency code in ISO 4217 format.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTradeInSupplierAccountBalanceResponse" }, "example": { "code": 0, "data": { "available_balance": { "amount": "125.50", "currency": "USD" } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Finance Information" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-tradein-supplier-account-balance-202609" } }, "/finance/202609/account_transactions": { "get": { "operationId": "getTradeInAccountTransactions", "summary": "Get TradeIn Account Transactions", "description": "Retrieves account transaction records for the currently authorized TradeIn supplier.\nThe supplier identity and associated seller identity are resolved from the authorization context. The caller cannot specify seller_id.\nOnly account transactions generated by the TradeIn business are returned.", "tags": [ "Finance" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "start_time", "in": "query", "required": false, "description": "Filter account transactions created on or after this time. Use RFC 3339 format with timezone.", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "required": false, "description": "Filter account transactions created before this time. Use RFC 3339 format with timezone.", "schema": { "type": "string", "format": "date-time" } }, { "name": "flow_type", "in": "query", "required": false, "description": "Filters account transactions by business transaction type. Allowed values: RECHARGE, WITHDRAW, REVERSE. If omitted, all supported transaction types are returned.", "schema": { "type": "string", "enum": [ "RECHARGE", "WITHDRAW", "REVERSE" ] } }, { "name": "page_size", "in": "query", "required": true, "description": "The number of account transactions to return per page.", "schema": { "type": "integer", "format": "int64" } }, { "name": "page_token", "in": "query", "required": false, "description": "An opaque token returned by the previous request. Omit it when requesting the first page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTradeInAccountTransactionsResponse" }, "example": { "code": 0, "data": { "flows": [ { "amount": { "amount": "125.50", "currency": "USD" }, "create_time": "2026-09-01T10:15:30Z", "direction": "IN", "origin_transaction_id": "7894561230123456001", "reference_id": "TI202609010001", "transaction_id": "7894561230123456789", "type": "RECHARGE" } ], "has_more": true, "next_page_token": "6AsPQsUMvH3RkchNUPPh22NROHkE0D8pmqN5M1kHYcZmtRyv9aVrNv65W7Q6tFA", "total_count": 100 }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Finance Information" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-tradein-account-transactions-202609" } }, "/fulfillment/202309/combinable_packages/search": { "get": { "operationId": "searchCombinablePackages", "summary": "Search Combinable Packages", "description": "Use this API to query orders eligible for combined shipping.", "tags": [ "Fulfillment" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "page_token", "in": "query", "required": false, "description": "An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the `next_page_token` from a previous response. It is not needed for the first page.", "schema": { "type": "string" } }, { "name": "page_size", "in": "query", "required": true, "description": "The number of results to be returned per page. Valid range: [1-50].", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchCombinablePackagesResponse" }, "example": { "code": 0, "data": { "combinable_packages": [ { "id": "57466538837665", "order_ids": [ "57466538837665", "57466538837666" ] } ], "next_page_token": "6AsPQsUMvH3RkchNUPPh22NROHkE0D8pmq/N5M1kHYcZmtRyv9aVrNv65W7Q6tFA", "total_count": 10 }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Package Split And Combine" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-combinable-packages-202309" } }, "/fulfillment/202309/files/upload": { "post": { "operationId": "uploadProofOfDeliveryFile", "summary": "Upload Proof of Delivery File", "description": "This API is used for the seller to upload the proof of delivery file for a package, and to generate the URL of the corresponding file. The generated URL is used for the [Update Package Delivery Status API](https://partner.tiktokshop.com/docv2/page/650aa332c16ffe02b8f0ba82?external_id=650aa332c16ffe02b8f0ba82). \n\nThis API only supports uploading qualification files in `PDF` format. The file size can not exceed 10MB.\n\nNote: Only sellers utilizing the SOF (Seller Own Fleet) capability can use this API.", "tags": [ "Fulfillment" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UploadProofOfDeliveryFileRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadProofOfDeliveryFileResponse" }, "example": { "code": 0, "data": { "url": "https://maellane.bytedance.net/wsos_v2/oec_fulfillment_doc_tts/o", "name": "attachment_file.pdf" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfillment Basic" ], "x-tts-error-codes": [ { "code": "12038002", "message": "Invalid upload file. Please ensure you are passing the correct file data." }, { "code": "12038004", "message": "Invalid file type. Please ensure you are providing a PDF file." }, { "code": "12038005", "message": "Invalid file size. Please ensure your file is smaller than 10MB." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/upload-proof-of-delivery-file-202309" } }, "/fulfillment/202309/images/upload": { "post": { "operationId": "uploadProofOfDeliveryImage", "summary": "Upload Proof of Delivery Image", "description": "This API is used for the seller to upload the proof of delivery image for a package, and to generate the URL of the corresponding file. The generated URL is used in the [Update Package Delivery Status API](https://partner.tiktokshop.com/docv2/page/650aa332c16ffe02b8f0ba82?external_id=650aa332c16ffe02b8f0ba82) to indicate that the parcel has been delivered. \n\nUsage requirements:\n- The image format must be `JPEG`, `PNG`, or `JPG`. \n- The image size can not exceed 5MB.", "tags": [ "Fulfillment" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UploadProofOfDeliveryImageRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadProofOfDeliveryImageResponse" }, "example": { "code": 0, "data": { "url": "https://p-pbe38.byted.org/tos-ppdi18n-i-0euhj0x6u9/0a119a90d90b41e3838608bc384", "height": 256, "width": 256 }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfillment Basic" ], "x-tts-error-codes": [ { "code": "12019116", "message": "Invalid image resolution. Please ensure your image is between 100 x 100 pixels and 20000 x 20000 pixels." }, { "code": "12038002", "message": "Invalid upload file. Please ensure you are passing the correct file data." }, { "code": "12038004", "message": "Invalid image file type. Please ensure your image is in JPG, JPEG, or PNG format." }, { "code": "12038005", "message": "Invalid image file size. Please ensure your image file size does not exceed 5MB." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/upload-proof-of-delivery-image-202309" } }, "/fulfillment/202309/orders/split_attributes": { "get": { "operationId": "getOrderSplitAttributes", "summary": "Get Order Split Attributes", "description": "Checks whether one or more TikTok Shop orders can be split into multiple packages. For each evaluated order, the response indicates whether it can be split and may include a reason when splitting is not allowed and mandatory package-splitting limits when applicable.", "tags": [ "Fulfillment" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "order_ids", "in": "query", "required": true, "description": "A comma-separated list of TikTok Shop order IDs to check for package split eligibility.", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrderSplitAttributesResponse" }, "example": { "code": 0, "data": { "split_attributes": [ { "order_id": "556643423444", "can_split": false, "reason": "Order has been canceled", "must_split": false, "must_split_reasons": [ { "type": "CATEGORY_ITEM_LIMITATION", "category_id": "601990", "max_count": "2" } ] } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "FS Order&Fulfillment Management", "Package Split And Combine" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-order-split-attributes-202309" } }, "/fulfillment/202309/orders/{order_id}/shipping_info/update": { "post": { "operationId": "updateOrderShippingInfo", "summary": "Update Order Shipping Info", "description": "If the seller entered an incorrect tracking number, this API allows the seller to update the tracking number and shipping provider for an order that has already been shipped.\n\n- This API is only applicable to orders (or packages) shipped by the seller. \n- It is only used to update the tracking number and shipping provider for packages that have already been shipped. \n- For orders that have been split for shipping, please use the [Update Package Shipping Info API](https://partner.tiktokshop.com/docv2/page/650aa666c16ffe02b8f1203c?external_id=650aa666c16ffe02b8f1203c). \n\nPlease note that TikTok Shop only allows merchants to update shipping information within 72 hours after shipping.", "tags": [ "Fulfillment" ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "description": "TikTok Shop order ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrderShippingInfoRequest" }, "example": { "tracking_number": "576460868968549926", "shipping_provider_id": "6965352555291346690" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrderShippingInfoResponse" }, "example": { "code": 0, "data": {}, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Logistics Basic" ], "x-tts-error-codes": [ { "code": "10007002", "message": "Current order is not a merchant blind box order." }, { "code": "21001028", "message": "The order is being processed. Try again later." }, { "code": "21011001", "message": "Package not found. If the error persists, please contact the platform for assistance." }, { "code": "21011004", "message": "This API cannot be used to update package shipping information for packages that are not shipped by sellers." }, { "code": "21011007", "message": "Package item has after-sale request, please process the after-sale request first." }, { "code": "21011022", "message": "Invalid tracking number or provider ID. Please double check and try again." }, { "code": "21011028", "message": "The package does not belong to the current shop. Please ensure you are providing the correct package ID and/or shop cipher." }, { "code": "21011030", "message": "fulfillment not allow update tracking no" }, { "code": "21011041", "message": "Cannot complete the operation when order is cancelled." }, { "code": "21011042", "message": "Cannot complete the operation when order is cancelled." }, { "code": "21011043", "message": "The package has not been shipped yet." }, { "code": "21011049", "message": "Due to platform rule limitations, you are unable to update the tracking number." }, { "code": "25001010", "message": "A return request has already been completed, or the order has already been cancelled." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/update-order-shipping-info-202309" } }, "/fulfillment/202309/orders/{order_id}/shipping_services/query": { "post": { "operationId": "getEligibleShippingServices", "summary": "Get Eligible Shipping Services", "description": "Retrieve available shipping services in the US and JP. Package dimensions and weight are optional inputs used to calculate the available options. Shipping fees and delivery times are estimates based on the package attributes used for the query, and the available options may change if those attributes change at the time of shipping.", "tags": [ "Fulfillment" ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "description": "TikTok Shop order ID", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEligibleShippingServicesRequest" }, "example": { "order_line_item_ids": [ "32132124331234" ], "weight": { "value": "0.4", "unit": "GRAM" }, "dimension": { "length": "0.3", "width": "0.2", "height": "0.2", "unit": "INCH" }, "order_line_list": [ { "order_line_id": "57632132124331234", "sub_item_id": "57632132124331234" } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEligibleShippingServicesResponse" }, "example": { "code": 0, "data": { "order_id": "28823355942588", "order_line_id": [ "32132124331234" ], "weight": { "value": "1.2", "unit": "GRAM" }, "shipping_services": [ { "id": "288233559123860015", "name": "UPS-first class", "price": "5", "currency": "USD", "earliest_delivery_days": 3, "latest_delivery_days": 5, "is_default": false, "shipping_provider_name": "UPS", "shipping_provider_id": "288233559123860012", "shipping_fee": "3", "shipping_app_service_fee": "1", "signature_fee": "1" } ], "dimension": { "length": "0.3", "width": "0.2", "height": "0.04", "unit": "INCH" } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfillment Basic" ], "x-tts-error-codes": [ { "code": "10006402", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "21001001", "message": "Invalid parameters. Please ensure you are passing the correct request parameter(s)." }, { "code": "21011001", "message": "Package not found. If the error persists, please contact the platform for assistance." }, { "code": "21011006", "message": "These orders are already shipped." }, { "code": "21011029", "message": "order does not belong to fulfill unit" }, { "code": "21011037", "message": "There are no available shipping services for this request. Please modify the package weight, or double check the recipient address. If after multiple retries you continue to experience this error, please contact the platform for assistance." }, { "code": "21011048", "message": "There are multiple packages that can be shipped, please specify the order line that needs to be shipped." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-eligible-shipping-services-202309" } }, "/fulfillment/202309/orders/{order_id}/split": { "post": { "operationId": "confirmOrderSplit", "summary": "Confirm Order Split", "description": "Use this API to confirm an order split. Supported split levels vary by region:\n- Some regions support item-level splits (splitting individual units of the same SKU).\n- Others only support all-units splits (splitting different SKUs into separate packages).\n\nHere are two examples of supported splits:\n- **Case 1: all-units split**, applicable for orders in BR, SEA, MX (local sellers)\n Split a buyer order of SKU A of quantity 2 and SKU B of quantity 1 into two separate packages:\n - **Package 1**: all units of SKU A\n - **Package 2**: all units of SKU B\n\n- **Case 2: item-level split**, applicable for orders in EU, JP, MX (global sellers), UK, US\n Split the same order contents into three individual packages:\n - **Package 1**: 1 unit of SKU A\n - **Package 2**: 1 unit of SKU A\n - **Package 3**: 1 unit of SKU B", "tags": [ "Fulfillment" ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "description": "TikTok Shop order ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOrderSplitRequest" }, "example": { "splittable_groups": [ { "id": "123", "order_line_item_ids": [ "57646237751283022", "576462377512830223" ] } ], "splittable_groups_v2": [ { "id": "123", "order_line_list": [ { "order_line_id": "57646237751283022", "sub_item_id": "57646237751283022" } ] } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOrderSplitResponse" }, "example": { "code": 0, "data": { "packages": [ { "splittable_group_id": "123", "id": "223362377512830222" } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "FS Order&Fulfillment Management", "Package Split And Combine" ], "x-tts-error-codes": [ { "code": "21001028", "message": "The order is being processed. Try again later." }, { "code": "21011005", "message": "An invalid request parameter was passed. Please check that you have the correct parameter type(s) and format." }, { "code": "21011035", "message": "split order not allowed" }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/confirm-order-split-202309" } }, "/fulfillment/202309/orders/{order_id}/tracking": { "get": { "operationId": "getOrderTracking", "summary": "Get Order Tracking", "description": "This API can use the order number to obtain the corresponding logistics tracking information.", "tags": [ "Fulfillment" ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "description": "TikTok Shop order ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrderTrackingResponse" }, "example": { "code": 0, "data": { "tracking": [ { "description": "Your package was delivered!\n", "update_time_millis": 1694685539000, "action_code": 50101 } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Logistics Basic" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-order-tracking-202309" } }, "/fulfillment/202309/packages/combine": { "post": { "operationId": "combinePackage", "summary": "Combine Package", "description": "Use this API to combine orders from each specified package into new fulfillment packages.", "tags": [ "Fulfillment" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CombinePackageRequest" }, "example": { "combinable_packages": [ { "id": "12321313133", "order_ids": [ "1233213123123", "32132131231" ] } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CombinePackageResponse" }, "example": { "code": 0, "data": { "packages": [ { "id": "413234134123412", "order_ids": [ "1233213123123", "32132131231" ] } ], "errors": [ { "code": 10007014, "message": "fulfillment not allow combine package", "detail": { "package_id": "1231231231231313123132" } } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Package Split And Combine" ], "x-tts-error-codes": [ { "code": "21011028", "message": "The package does not belong to the current shop. Please ensure you are providing the correct package ID and/or shop cipher." }, { "code": "21011031", "message": "Order does not belong to pre_pkg. Please ensure you are providing the correct order ID(s)." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/combine-package-202309" } }, "/fulfillment/202309/packages/deliver": { "post": { "operationId": "updatePackageDeliveryStatus", "summary": "Update Package Delivery Status", "description": "Use this API to report delivery outcomes for SOF (Seller Own Fleet) packages or confirm O2O (Store Pickup) package delivery. For SOF, use `DELIVERY_SUCCESS`, `DELIVERY_FAILED`, or `UPDATE_POD`. For O2O, use `DELIVERY_SUCCESS` and provide the pickup verification code. Only sellers using SOF or O2O can use this API. This API is available only in the SEA region.", "tags": [ "Fulfillment" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePackageDeliveryStatusRequest" }, "example": { "packages": [ { "id": "11529598723402", "delivery_type": "DELIVERY_SUCCESS", "fail_delivery_reason": "INVALID_ADDRESS", "file_type": "IMG", "file_url": "https://tiktok.shopcenter.cn/file/CWvBsBZ9mhbMiHtmbZecKshon6f?table=tblTW", "verification_code": "123456" } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePackageDeliveryStatusResponse" }, "example": { "code": 0, "data": { "errors": [ { "code": 10007014, "message": "order not in sof service", "detail": { "package_id": "1231231231231" } } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Update Delivery Status" ], "x-tts-error-codes": [ { "code": "21001011", "message": "System process error, please try again later." }, { "code": "21011028", "message": "The package does not belong to the current shop. Please ensure you are providing the correct package ID and/or shop cipher." }, { "code": "21042247", "message": "The code you entered is incorrect. Please try again." }, { "code": "21042248", "message": "The maximum number of attempts has been reached. Please try again in 30 minutes." }, { "code": "21042252", "message": "Abnormal order status, failed to update delivery status, please try again later." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/update-package-delivery-status-202309" } }, "/fulfillment/202309/packages/search": { "post": { "operationId": "searchPackage", "summary": "Search Package", "description": "Retrieve packages, optionally filtered by creation time, update time, or package status.", "tags": [ "Fulfillment" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "page_size", "in": "query", "required": true, "description": "The number of results to be returned per page. Valid range: [1-50].", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 50 } }, { "name": "sort_field", "in": "query", "required": false, "description": "The returned results will be sorted by the specified field. \nDefault: `create_time`\nPossible values:\n- `create_time`\n- `update_time`\n- `order_pay_time`\n\nSpecify the order for sorting the returned results by using the sort_order parameter.", "schema": { "type": "string", "enum": [ "create_time", "update_time", "order_pay_time" ] } }, { "name": "sort_order", "in": "query", "required": false, "description": "The sort order for the sort_field parameter. Default: `DESC`\nPossible values:\n- `ASC`: Ascending order\n- `DESC`: Descending order", "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "x-enum-descriptions": [ "Ascending order", "Descending order" ] } }, { "name": "page_token", "in": "query", "required": false, "description": "An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the `next_page_token` from a previous response. It is not needed for the first page.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchPackageRequest" }, "example": { "create_time_ge": 1623812664, "create_time_lt": 1623812664, "update_time_ge": 1623812664, "update_time_lt": 1623812664, "package_status": "PROCESSING" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchPackageResponse" }, "example": { "code": 0, "data": { "next_page_token": "6AsPQsUMvH3RkchNUPPh22NROHkE0D8pmq/N5M1kHYcZmtRyv9aVrNv65W7Q6tFA", "total_count": 221, "packages": [ { "id": "577828281214600000", "orders": [ { "id": "577828281214600000", "skus": [ { "id": "577828281214883345", "name": "white,128g", "image_url": "https://p19-oec-sg.ibyteimg.com/tos-maliva-i-o3syd03w52-us/12345670", "quantity": 5 } ] } ], "create_time": 1635338186, "update_time": 1635338186, "status": "PROCESSING", "tracking_number": "6617675021119438849", "shipping_provider_name": "TT Virtual express", "shipping_provider_id": "6617675021119438849", "order_line_item_ids": [ "1729382476852921560" ] } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfillment Basic" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-package-202309" } }, "/fulfillment/202309/packages/ship": { "post": { "operationId": "batchShipPackages", "summary": "Batch Ship Packages", "description": "Use this API to ship one or more packages in a single request. The API supports TikTok Shipping, Seller Shipping, and In-store Pickup.\n\n- `TikTok Shipping`: Set each package's `handover_method` to `PICKUP` for carrier pickup from the seller's pickup address, or to `DROP_OFF` when the seller will drop it off at a designated location.\n- `Seller Shipping`: Provide `self_shipment.shipping_provider_id` and `self_shipment.tracking_number` for each package. Obtain package IDs from [Get Order Detail](https://partner.tiktokshop.com/docv2/page/650aa8ccc16ffe02b8f167a0?external_id=650aa8ccc16ffe02b8f167a0).\n- `In-store Pickup`: Confirm shipment and notify the buyer that the order is ready for pickup.\n\nA response with a top-level `code` of `0` can still contain package-specific failures. Check `data.errors` before treating every package as shipped.", "tags": [ "Fulfillment" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchShipPackagesRequest" }, "example": { "packages": [ { "id": "12321312312431", "handover_method": "PICKUP", "pickup_slot": { "start_time": 1623812664, "end_time": 1623812664 }, "self_shipment": { "tracking_number": "JX12345", "shipping_provider_id": "6617675021119438849" } } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchShipPackagesResponse" }, "example": { "code": 0, "data": { "errors": [ { "code": 10007014, "message": "package in freeze status", "detail": { "package_id": "123123123123131" } } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "FS Order&Fulfillment Management", "Fulfillment Basic" ], "x-tts-error-codes": [ { "code": "11006013", "message": "Failed to ship package. Products under the Phones & Tablets category cannot be shipped together with other items in the same package. Please split the order." }, { "code": "11006014", "message": "Failed to ship package. If you are shipping multiple products under the Phones & Tablets category, they must be shipped in individual packages. Please split the order to continue." }, { "code": "11021009", "message": "No available shipping services for this request. Please modify the package weight or check the recipient address. If the error persists, please contact the platform for assistance." }, { "code": "11021010", "message": "The shipment failed due to an invalid postal code. Please ask the buyer to edit the address. If the address cannot be changed, you may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "11021011", "message": "Fail to ship package because the product name is invalid. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "11021012", "message": "illegal address" }, { "code": "11021013", "message": "The shipment failed because the delivery address is too long. Please ask the buyer to shorten the address. If the address cannot be changed, you may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "11021014", "message": "product oversize" }, { "code": "11021015", "message": "Fail to ship package because the package is overweight. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "11021016", "message": "Fail to ship package because the weight of the SKU exceeds the allowed limit. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "11021017", "message": "Fail to ship package because the SKU dimensions exceed the allowed limits. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "11021018", "message": "Fail to ship package because the number of items in the package exceeds the allowed limit." }, { "code": "11021019", "message": "Fail to ship package because the package dimensions exceed the allowed limits. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "11021020", "message": "Fail to ship package because the package's circumference exceeds the allowed limit. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "11021021", "message": "Fail to ship package because the SKU name is invalid. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "11021022", "message": "Fail to ship package because the longest dimension of the package exceeds the allowed limit. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "11021023", "message": "Fail to ship package because the buyer and/or seller addresses are invalid. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "11021024", "message": "Fail to ship package because the buyer recipient address is invalid. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "11021025", "message": "Fail to ship package because the seller shipping address is invalid. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "11028006", "message": "This tracking number cannot be matched to any carrier, please check the tracking number and upload again." }, { "code": "21001003", "message": "System timeout. If the error persists, please contact the platform for assistance." }, { "code": "21001011", "message": "System process error, please try again later." }, { "code": "21001028", "message": "The order is being processed. Try again later." }, { "code": "21004006", "message": "Failed to ship. Please ensure an invoice is uploaded before shipping." }, { "code": "21008044", "message": "SellerFulfillUnitInReverseCannotOperate" }, { "code": "21011001", "message": "Package not found. If the error persists, please contact the platform for assistance." }, { "code": "21011003", "message": "fulfill_unit action not allowed" }, { "code": "21011007", "message": "Package item has after-sale request, please process the after-sale request first." }, { "code": "21011008", "message": "Package is not complete. If the error persists, please contact the platform for assistance." }, { "code": "21011020", "message": "These orders are already shipped." }, { "code": "21011022", "message": "Invalid tracking number or provider ID. Please double check and try again." }, { "code": "21011025", "message": "Duplicate tracking number." }, { "code": "21011027", "message": "Package has already been delivered." }, { "code": "21011028", "message": "The package does not belong to the current shop. Please ensure you are providing the correct package ID and/or shop cipher." }, { "code": "21011040", "message": "Package has already been shipped." }, { "code": "21011041", "message": "Cannot complete the operation when order is cancelled." }, { "code": "21011053", "message": "Fail to ship package because the shipment time is outside of the pick-up time slot." }, { "code": "21011054", "message": "No available shipping services for this request due to missing pick-up time slot. Please contact customer service for assistance." }, { "code": "21014009", "message": "Failed to ship. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "21042227", "message": "For pop 4pl（cross-border），the return warehouse for the shipping location has not been configured." }, { "code": "21042251", "message": "Abnormal order status, item cannot be shipped." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/batch-ship-packages-202309" } }, "/fulfillment/202309/packages/{package_id}": { "get": { "operationId": "getPackageDetail", "summary": "Get Package Detail", "description": "Returns information about a package, including handover time slot, tracking number, and shipping provider information.", "tags": [ "Fulfillment" ], "parameters": [ { "name": "package_id", "in": "path", "required": true, "description": "TikTok Shop package ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPackageDetailResponse" }, "example": { "code": 0, "data": { "package_id": "5433567853345", "orders": [ { "id": "54335448533296", "skus": [ { "id": "2729382476852921560", "name": "white,128g", "image_url": "https://p19-oec-sg.ibyteimg.com/tos-maliva-i-o3syd03w52-us/12345670c", "quantity": 5 } ] } ], "package_status": "PROCESSING", "package_sub_status": "CREATED", "ship_exception_reason": "PACKAGE_LOST", "split_and_combine_tag": "SPLIT", "has_multi_skus": true, "note_tag": "BUYER_UNNOTED", "shipping_provider_name": "TT Virtual express", "shipping_provider_id": "6617675021119438849", "shipping_type": "TIKTOK", "delivery_option_name": "Shipped from seller\n", "delivery_option_id": "7091146663229654785", "tracking_number": "6617675021119438849", "last_mile_tracking_number": "6617675021119438849", "pickup_slot": { "start_time": 1635338186, "end_time": 1635338186 }, "create_time": 1635338186, "handover_method": "PICKUP", "order_line_item_ids": [ "1729382476852921560" ], "recipient_address": { "full_address": "1*** Coleman Ave San Jose, CA 95110\n", "phone_number": "(+1)213-***-1234\n", "name": "Zay", "postal_code": "95110\n", "address_detail": "Unit one building 8\n", "region_code": "US", "address_line1": "TikTok 5800 bristol Pkwy\n", "address_line2": "Suite 100\n", "address_line3": "Suite 100\n", "address_line4": "Suite 100\n" }, "sender_address": { "full_address": "1*** Coleman Ave San Jose, CA 95110", "phone_number": "(+1)213-***-1234\n", "name": "Zay", "postal_code": "95110", "address_detail": "Unit one building 8", "region_code": "US", "address_line1": "TikTok 5800 bristol Pkwy", "address_line2": "Suite 100", "address_line3": "Suite 100", "address_line4": "Suite 100" }, "weight": { "value": "1.2", "unit": "GRAM" }, "dimension": { "length": "1.2", "width": "0.2", "height": "0.03", "unit": "CM" }, "update_time": 1635338186, "insurance": { "is_purchased": true, "coverage_amount": "200", "is_claim_eligible": true, "claim_status": "CLAIM_PENDING" }, "biz_extension_tags": [ "NON_MCF" ], "warehouse_id": "7317467398322308906" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "FS Order&Fulfillment Management", "Fulfillment Basic" ], "x-tts-error-codes": [ { "code": "10006402", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-package-detail-202309" } }, "/fulfillment/202309/packages/{package_id}/handover_time_slots": { "get": { "operationId": "getPackageHandoverTimeSlots", "summary": "Get Package Handover Time Slots", "description": "Use this API to retrieve a specified package's door-to-door pickup time slots and handover availability for pickup, drop-off, and, in the UK, van collection. When available, the response also provides a URL for finding drop-off locations.", "tags": [ "Fulfillment" ], "parameters": [ { "name": "package_id", "in": "path", "required": true, "description": "TikTok Shop package ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPackageHandoverTimeSlotsResponse" }, "example": { "code": 0, "data": { "can_pickup": true, "can_drop_off": true, "can_van_collection": true, "drop_off_point_url": "https://jtexpress.my/location", "pickup_slots": [ { "start_time": 1623812664, "end_time": 1623812664, "avaliable": true } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Package Split And Combine" ], "x-tts-error-codes": [ { "code": "11001027", "message": "System timeout. If this error persists, please contact the platform for assistance." }, { "code": "11021009", "message": "No available shipping services for this request. Please modify the package weight or check the recipient address. If the error persists, please contact the platform for assistance." }, { "code": "21001001", "message": "Invalid parameters. Please ensure you are passing the correct request parameter(s)." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-package-handover-time-slots-202309" } }, "/fulfillment/202309/packages/{package_id}/ship": { "post": { "operationId": "shipPackage", "summary": "Ship Package", "description": "Use this API to ship a package. There are two kinds of shipping options available: `TikTok Shipping` or `Seller Shipping`.\n\n- `TikTok Shipping`: Schedule a package handover time for TikTok Shipping carriers to pickup a package from seller.\n- `Seller Shipping`: Seller arranges their own shipping, and uploads a tracking number and `shipping_provider_id`. Package ID can be obtained from [Get Order Detail](https://partner.tiktokshop.com/docv2/page/650aa8ccc16ffe02b8f167a0?external_id=650aa8ccc16ffe02b8f167a0#Back%20To%20Top).\n- `In-store Pickup`: Confirms shipment and notifies the buyer that the order is ready for pickup.", "tags": [ "Fulfillment" ], "parameters": [ { "name": "package_id", "in": "path", "required": true, "description": "TikTok Shop package ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipPackageRequest" }, "example": { "handover_method": "PICKUP", "pickup_slot": { "start_time": 1623812664, "end_time": 1623812664 }, "self_shipment": { "tracking_number": "JX12345", "shipping_provider_id": "6617675021119438849" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipPackageResponse" }, "example": { "code": 0, "data": {}, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "FS Order&Fulfillment Management", "Fulfillment Basic" ], "x-tts-error-codes": [ { "code": "11001002", "message": "invalid param." }, { "code": "11001031", "message": "System process error, please try again later." }, { "code": "11006013", "message": "Failed to ship package. Products under the Phones & Tablets category cannot be shipped together with other items in the same package. Please split the order." }, { "code": "11006014", "message": "Failed to ship package. If you are shipping multiple products under the Phones & Tablets category, they must be shipped in individual packages. Please split the order to continue." }, { "code": "11006021", "message": "Package has been shipped. Please not ship the package again." }, { "code": "11021009", "message": "No available shipping services for this request. Please modify the package weight or check the recipient address. If the error persists, please contact the platform for assistance." }, { "code": "11021010", "message": "The shipment failed due to an invalid postal code. Please ask the buyer to edit the address. If the address cannot be changed, you may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "11021011", "message": "Fail to ship package because the product name is invalid. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "11021012", "message": "illegal address" }, { "code": "11021013", "message": "The shipment failed because the delivery address is too long. Please ask the buyer to shorten the address. If the address cannot be changed, you may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "11021014", "message": "product oversize" }, { "code": "11021015", "message": "Fail to ship package because the package is overweight. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "11021016", "message": "Fail to ship package because the weight of the SKU exceeds the allowed limit. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "11021017", "message": "Fail to ship package because the SKU dimensions exceed the allowed limits. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "11021018", "message": "Fail to ship package because the number of items in the package exceeds the allowed limit." }, { "code": "11021019", "message": "Fail to ship package because the package dimensions exceed the allowed limits. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "11021020", "message": "Fail to ship package because the package's circumference exceeds the allowed limit. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "11021021", "message": "Fail to ship package because the SKU name is invalid. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "11021022", "message": "Fail to ship package because the longest dimension of the package exceeds the allowed limit. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "11021023", "message": "Fail to ship package because the buyer and/or seller addresses are invalid. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "11021024", "message": "Fail to ship package because the buyer recipient address is invalid. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "11021025", "message": "Fail to ship package because the seller shipping address is invalid. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "11028006", "message": "This tracking number cannot be matched to any carrier, please check the tracking number and upload again." }, { "code": "11050001", "message": "invalid param" }, { "code": "21001001", "message": "Invalid parameters. Please ensure you are passing the correct request parameter(s)." }, { "code": "21001003", "message": "System timeout. If the error persists, please contact the platform for assistance." }, { "code": "21001008", "message": "not found error" }, { "code": "21001011", "message": "System process error, please try again later." }, { "code": "21001028", "message": "The order is being processed. Try again later." }, { "code": "21004006", "message": "Failed to ship. Please ensure an invoice is uploaded before shipping." }, { "code": "21004017", "message": "ON DEMAND RTS NOT IN PICKUP TIME." }, { "code": "21004019", "message": "Need invoice uploaded for all order before rts." }, { "code": "21004020", "message": "Fulfillment Invoice status is not success, can not rts pkg." }, { "code": "21004024", "message": "ship order failed due to platform limitations." }, { "code": "21008025", "message": "Seller cannot operate orders which are fulfilled by platform" }, { "code": "21008044", "message": "SellerFulfillUnitInReverseCannotOperate" }, { "code": "21008099", "message": "Package has been shipped. Please not ship the package again." }, { "code": "21011001", "message": "Package not found. If the error persists, please contact the platform for assistance." }, { "code": "21011003", "message": "fulfill_unit action not allowed" }, { "code": "21011007", "message": "Package item has after-sale request, please process the after-sale request first." }, { "code": "21011008", "message": "Package is not complete. If the error persists, please contact the platform for assistance." }, { "code": "21011020", "message": "These orders are already shipped." }, { "code": "21011022", "message": "Invalid tracking number or provider ID. Please double check and try again." }, { "code": "21011025", "message": "Duplicate tracking number." }, { "code": "21011026", "message": "fulfillment tracking no used times over limit" }, { "code": "21011027", "message": "Package has already been delivered." }, { "code": "21011028", "message": "The package does not belong to the current shop. Please ensure you are providing the correct package ID and/or shop cipher." }, { "code": "21011030", "message": "fulfillment not allow update tracking no" }, { "code": "21011040", "message": "Package has already been shipped." }, { "code": "21011041", "message": "Cannot complete the operation when order is cancelled." }, { "code": "21011050", "message": "The tracking number can only be updated within a certain number of hours." }, { "code": "21011051", "message": "The tracking number can only be updated once." }, { "code": "21011053", "message": "Fail to ship package because the shipment time is outside of the pick-up time slot." }, { "code": "21011054", "message": "No available shipping services for this request due to missing pick-up time slot. Please contact customer service for assistance." }, { "code": "21014009", "message": "Failed to ship. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "21021010", "message": "Failed to ship. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "21022029", "message": "System process error, please try again later." }, { "code": "21022032", "message": "match provider failed." }, { "code": "21034012", "message": "tracking no has been used" }, { "code": "21042001", "message": "System process error, please try again later." }, { "code": "21042067", "message": "The logistics service provider couldn't process your order." }, { "code": "21042076", "message": "System process error, please try again later." }, { "code": "21042227", "message": "For pop 4pl（cross-border），the return warehouse for the shipping location has not been configured." }, { "code": "21042251", "message": "Abnormal order status, item cannot be shipped." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/ship-package-202309" } }, "/fulfillment/202309/packages/{package_id}/shipping_documents": { "get": { "operationId": "getPackageShippingDocument", "summary": "Get Package Shipping Document", "description": "For packages shipped with TikTok Shipping, use this API to retrieve the URL of the shipping document selected by `document_type` for the package specified by `package_id`. First call `Ship Package` to arrange shipment, then retrieve the document before the package is picked up.", "tags": [ "Fulfillment" ], "parameters": [ { "name": "package_id", "in": "path", "required": true, "description": "TikTok Shop package ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" }, { "name": "document_type", "in": "query", "required": true, "description": "Available document types: \n- `SHIPPING_LABEL`: Returns the shipping label in PDF format by default.\n- `PACKING_SLIP`: Returns the packing slip in PDF format by default.\n- `SHIPPING_LABEL_AND_PACKING_SLIP`: Returns both the shipping label and the packing slip for the package, both in PDF format by default. \n- `SHIPPING_LABEL_PICTURE`: Returns the shipping label in PNG format. \n- `HAZMAT_LABEL`: Returns the hazmat label in PDF format by default. You must only use this value when there are hazmat items in the package. When you use the value, `document_size` is fixed to A4, and you don't need to specify `document_size`.\n- `INVOICE_LABEL`: For Brazil market only, document_size is fixed to A6, and you don't need to specify `document_size`. Returns the invoice label in PDF format by default", "schema": { "type": "string" } }, { "name": "document_size", "in": "query", "required": false, "description": "Use this field to specify the size of the document to obtain. This parameter is only applicable to shipping labels, picking slips, and packing slips that are in the PDF format. It is not applicable for hazmat labels as these are fixed to A4. \nIf you specify `SHIPPING_LABEL_PICTURE` for the `document_type`, any value specified in the `document_size` will be ignored. \n\nPossible values: \n- `A6` (Default)\n- `A5`", "schema": { "type": "string", "enum": [ "A6", "A5" ], "x-enum-descriptions": [ "Default", "" ] } }, { "name": "document_format", "in": "query", "required": false, "description": "The format of the shipping document.\nPossible values: \n- PDF (Default)\n- ZPL (Only for BR and MX market)\n\n**Note**: Not applicable for `SHIPPING_LABEL_PICTURE` document type.", "schema": { "type": "string", "enum": [ "PDF", "ZPL" ], "x-enum-descriptions": [ "Default", "Only for BR and MX market" ] } }, { "name": "shipping_period", "in": "query", "required": false, "description": "Obtain shipping labels from designated last-mile delivery providers for cross-border scenarios.\nPossible values: \n- DEFAULT (Default)\n- LAST_MILE (Only cross-border services under the 4PL model with the business solution of 3PL for main transport & customs clearance + 4PL for last-mile delivery will return the last-mile shipping label; calls from all other scenarios will be invalid.\n)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPackageShippingDocumentResponse" }, "example": { "code": 0, "data": { "doc_url": "https://magelng.bytedance.net2/wsos_v2/oec_fulfillment_doc_tts/object/wsos641232", "tracking_number": "752455325694" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "FS Order&Fulfillment Management", "Fulfillment Basic" ], "x-tts-error-codes": [ { "code": "11006010", "message": "Internal package status error, please try again later." }, { "code": "11034002", "message": "This API is only applicable to TikTok Shipping orders. For seller shipping, please obtain the shipping label offline and upload it to TikTok Shop via API or Seller Center." }, { "code": "11034009", "message": "Warehouse does not exist." }, { "code": "11034023", "message": "Shipping document generation timeout error, please try again later." }, { "code": "11034025", "message": "Internal package tag error, pleaser try again later." }, { "code": "11034037", "message": "The shipping document is still being generated by the logistics provider, please try again later." }, { "code": "21008017", "message": "This API is only applicable to TikTok Shipping orders. For seller shipping, please obtain the shipping label offline and upload it to TikTok Shop via API or Seller Center." }, { "code": "21008043", "message": "This package is fulfilled by TikTok. Shipping documents cannot be printed." }, { "code": "21008109", "message": "Unable to retrieve shipping information, please double check the order status." }, { "code": "21011001", "message": "Package not found. If the error persists, please contact the platform for assistance." }, { "code": "21021010", "message": "Failed to ship. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "21023022", "message": "Unknown label print timeout error. If the error persists, please contact the platform for assistance." }, { "code": "21023034", "message": "Internal package update error, please try again later." }, { "code": "21023035", "message": "Please arrange shipment before retrieving the shipping document." }, { "code": "21023046", "message": "Package has already been shipped." }, { "code": "21023059", "message": "Package has already been cancelled." }, { "code": "21042102", "message": "Documents couldn't be printed after the package has been pickup." }, { "code": "21042104", "message": "Documents couldn't be printed before shipped.Please check shipping is arranged and try again." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-package-shipping-document-202309" } }, "/fulfillment/202309/packages/{package_id}/uncombine": { "post": { "operationId": "uncombinePackages", "summary": "Uncombine Packages", "description": "Use this API to uncombine one or more orders from an already combined package.", "tags": [ "Fulfillment" ], "parameters": [ { "name": "package_id", "in": "path", "required": true, "description": "Package ID you wish to uncombine an order(s) from.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UncombinePackagesRequest" }, "example": { "order_ids": [ "11132131131" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UncombinePackagesResponse" }, "example": { "code": 0, "data": { "packages": [ { "id": "123456", "order_ids": [ "576462377512830168" ] } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Package Split And Combine" ], "x-tts-error-codes": [ { "code": "10006402", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "11001027", "message": "System timeout. If this error persists, please contact the platform for assistance." }, { "code": "21001001", "message": "Invalid parameters. Please ensure you are passing the correct request parameter(s)." }, { "code": "21001008", "message": "not found error" }, { "code": "21001028", "message": "The order is being processed. Try again later." }, { "code": "21008042", "message": "seller already print shipping label" }, { "code": "21011001", "message": "Package not found. If the error persists, please contact the platform for assistance." }, { "code": "21011005", "message": "An invalid request parameter was passed. Please check that you have the correct parameter type(s) and format." }, { "code": "21011006", "message": "These orders are already shipped." }, { "code": "21011007", "message": "Package item has after-sale request, please process the after-sale request first." }, { "code": "21011017", "message": "no need to combine single order" }, { "code": "21011028", "message": "The package does not belong to the current shop. Please ensure you are providing the correct package ID and/or shop cipher." }, { "code": "21011029", "message": "order does not belong to fulfill unit" }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/uncombine-packages-202309" } }, "/fulfillment/202407/bundles": { "post": { "operationId": "createFirstMileBundle", "summary": "Create First Mile Bundle", "description": "If you send multiple packages to TikTok Shop warehouse in a single first-mile bundle, you can use the API to create a first-mile bundle on TikTok Shop and get the bundle ID.", "tags": [ "Fulfillment" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFirstMileBundleRequest" }, "example": { "order_ids": [ "578967030217083407" ], "handover_method": "PICKUP", "shipping_provider_id": "7463353253533", "tracking_number": "SF1244442424", "phone_tail_number": "1234" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFirstMileBundleResponse" }, "example": { "code": 0, "data": { "first_mile_bundle_id": "BA123444534", "url": "https://open-fs-va.tiktokshop.com/doc_tts/object/28b05?skipCookie=true&timeStamp=1721272360&sign=ef63cd6", "errors": [ { "code": 21008121, "message": "invalid order id", "detail": { "order_id": "578967030217083407" } } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 2, "x-tts-scopes": [ "Fulfillment Basic" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/create-first-mile-bundle-202407" } }, "/fulfillment/202502/invoice/upload": { "post": { "operationId": "uploadInvoice", "summary": "Upload Invoice", "description": "Upload the invoice document.\n**Note**: Applicable only for local sellers in the Brazil market.", "tags": [ "Fulfillment" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadInvoiceRequest" }, "example": { "invoices": [ { "package_id": "1231231231231", "order_ids": [ "58747683456" ], "file_type": "XML", "file": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGL" } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadInvoiceResponse" }, "example": { "code": 0, "data": { "errors": [ { "code": 10007014, "message": "The invoice already exists in the upload. Please try again later", "detail": { "package_id": "1231231231231", "order_ids": [ "58747683456" ] } } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfillment Basic" ], "x-tts-error-codes": [ { "code": "21001028", "message": "The order is being processed. Try again later." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/upload-invoice-202502" } }, "/fulfillment/202508/tts_tracking_validation": { "get": { "operationId": "checkTikTokShippingAndCollectionByTikTokCoverage", "summary": "Check TikTok Shipping and Collection by TikTok Coverage", "description": "Enables a seller or warehouse to validate whether a tracking number is covered by TikTok Shipping (TTS) or Collection by TikTok (CBT). \n\nAvailable only in the **US Market**.", "tags": [ "Fulfillment" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "tracking_number", "in": "query", "required": true, "description": "The tracking number provided by shipping provider", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckTikTokShippingAndCollectionByTikTokCoverageResponse" }, "example": { "code": 0, "data": { "is_tiktok_shipping": false, "is_tiktok_collection": false }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Logistics Basic" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/check-tiktok-shipping-and-collection-by-tiktok-coverage-202508" } }, "/fulfillment/202510/first_mile_bundle": { "post": { "operationId": "createFirstMileBundleV2", "summary": "Create First Mile Bundle(V2)", "description": "If you send multiple packages to TikTok Shop warehouse in a single first-mile bundle, you can use the API to create a first-mile bundle on TikTok Shop and get the bundle ID.", "tags": [ "Fulfillment" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFirstMileBundleV2Request" }, "example": { "order_ids": [ "578967030217083407" ], "handover_method": "PICKUP", "shipping_provider_id": "7463353253533", "tracking_number": "SF1244442424", "phone_tail_number": "1234" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFirstMileBundleV2Response" }, "example": { "code": 0, "data": { "first_mile_bundle_id": "BA123444534", "url": "https://open-fs-va.tiktokshop.com/doc_tts/object/28b05?skipCookie=true&timeStamp=1721272360&sign=ef63cd6", "errors": [ { "code": 21008121, "message": "invalid order id", "detail": { "order_id": "578967030217083407" } } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfillment Basic" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/create-first-mile-bundle-v2-202510" } }, "/fulfillment/202512/packages": { "post": { "operationId": "createPackages", "summary": "Create Packages", "description": "Use this API to ship orders (purchase labels). This API is available in the US, UK, EMEA, and JP regions. The shipping fee and delivery time is an estimate only and is based on the package dimensions and weight you provided.", "tags": [ "Fulfillment" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePackagesRequest" }, "example": { "ship_type": "2", "order_id": "2882335594258860015", "order_line_item": [ { "order_line_id": "2882335594258860015", "sub_item_id": "2882335594258860015" } ], "order_list_ids": [ "2882335594258860015", "2882335594258860016" ], "dimension": { "length": "1.2", "width": "0.2", "height": "0.03", "unit": "CM" }, "shipping_service_id": "288233559123860015", "weight": { "value": "1.2", "unit": "GRAM" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePackagesResponse" }, "example": { "code": 0, "data": { "dimension": { "length": "1.2", "width": "0.2", "height": "0.03", "unit": "CM" }, "shipping_service_info": { "id": "288233559123860015", "name": "UPS-first class", "price": "10", "currency": "USD", "earliest_delivery_days": 3, "latest_delivery_days": 5, "shipping_provider_id": "2882322591238", "shipping_provider_name": "UPS" }, "package_id": "2882335594258860015", "weight": { "value": "1.2", "unit": "GRAM" }, "create_time": 1623812664 }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "FS Order&Fulfillment Management", "Fulfillment Basic" ], "x-tts-error-codes": [ { "code": "11001002", "message": "invalid param." }, { "code": "11001027", "message": "System timeout. If this error persists, please contact the platform for assistance." }, { "code": "11003011", "message": "Shipping service operation conflict error, please double check the shipping service ID." }, { "code": "11021009", "message": "No available shipping services for this request. Please modify the package weight or check the recipient address. If the error persists, please contact the platform for assistance." }, { "code": "11021012", "message": "illegal address" }, { "code": "11021014", "message": "product oversize" }, { "code": "11028006", "message": "This tracking number cannot be matched to any carrier, please check the tracking number and upload again." }, { "code": "11050001", "message": "invalid param" }, { "code": "21001001", "message": "Invalid parameters. Please ensure you are passing the correct request parameter(s)." }, { "code": "21001011", "message": "System process error, please try again later." }, { "code": "21004008", "message": "create label shipping service not found" }, { "code": "21004010", "message": "Your country does not support the use of this feature." }, { "code": "21008025", "message": "Seller cannot operate orders which are fulfilled by platform" }, { "code": "21008042", "message": "seller already print shipping label" }, { "code": "21008106", "message": "This interface cannot be used in this region." }, { "code": "21011001", "message": "Package not found. If the error persists, please contact the platform for assistance." }, { "code": "21011003", "message": "fulfill_unit action not allowed" }, { "code": "21011006", "message": "These orders are already shipped." }, { "code": "21011007", "message": "Package item has after-sale request, please process the after-sale request first." }, { "code": "21011012", "message": "not match trade rule" }, { "code": "21011020", "message": "These orders are already shipped." }, { "code": "21011029", "message": "order does not belong to fulfill unit" }, { "code": "21011033", "message": "order already combined" }, { "code": "21011035", "message": "split order not allowed" }, { "code": "21011037", "message": "There are no available shipping services for this request. Please modify the package weight, or double check the recipient address. If after multiple retries you continue to experience this error, please contact the platform for assistance." }, { "code": "21011046", "message": "Order has combine, not allow split order" }, { "code": "21011048", "message": "There are multiple packages that can be shipped, please specify the order line that needs to be shipped." }, { "code": "21022025", "message": "A shipping label has already been purchased." }, { "code": "21022026", "message": "Cannot purchase shipping label, please try again later." }, { "code": "21022029", "message": "System process error, please try again later." }, { "code": "21030005", "message": "Processing create_label_status not allow to operate this action" }, { "code": "21030006", "message": "Shipping label purchase successful. This operation is not allowed in the current order status." }, { "code": "21032001", "message": "fulfill unit status not allow to update pkg attr" }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/create-packages-202512" } }, "/fulfillment/202601/redeem_info/callback": { "post": { "operationId": "submitRedemptionInformation", "summary": "Submit Redemption Information", "description": "Submit redemption information for one or more line items in a TikTok Shop order so TikTok Shop can fulfill those items.", "tags": [ "Fulfillment" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitRedemptionInformationRequest" }, "example": { "order_id": "576461413038785752", "order_info_list": [ { "order_line_id": "577086512123755123", "redeem_info": { "redeem_type": "CODE", "redeem_data": "abc12344", "redeem_instruction_info": "{\"instruction_url\": \"https://example.com/redeem\"}" }, "source_unique_id": "134448484339393" } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitRedemptionInformationResponse" }, "example": { "code": 0, "data": { "order_statuses": [ { "order_line_id": "577086512123755123", "status_code": 0 } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Manage Seller Redeem Info Callback" ], "x-tts-error-codes": [ { "code": "10006402", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "164004001", "message": "permission denied, please check if you have the permission to operate the orders." }, { "code": "164004006", "message": "req is invalid, please check your request params" }, { "code": "164004008", "message": "no orders available for fulfillment" }, { "code": "185001003", "message": "no orders need to call back" }, { "code": "185002001", "message": "req is invalid, please check your request params" }, { "code": "185005001", "message": "permission denied, please check if you have the permission to operate the orders." }, { "code": "185005002", "message": "current order status not support call back" }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/submit-redemption-information-202601" } }, "/fulfillment/202606/pod_details/get": { "post": { "operationId": "getPODCustomizationDetails", "summary": "Get POD Customization Details", "description": "Retrieves the POD customization details for specified order lines in a TikTok Shop order.", "tags": [ "Fulfillment" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPODCustomizationDetailsRequest" }, "example": { "main_order_id": "576461413038785752", "query_order_lines": [ { "order_line_id": "577086512123755123", "product_id": "1732453831920750867", "sku_id": "1732453830297817363", "pod_order_data_id": "123456" } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPODCustomizationDetailsResponse" }, "example": { "code": 0, "data": { "pod_details": [ { "pod_info_json": "{\"pod_template_id\":123456}", "order_line_id": "577457287176491132" } ], "status_code": 0 }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Manage Seller Redeem Info Callback" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-pod-customization-details-202606" } }, "/fulfillment/202607/orders/customs_info/query": { "post": { "operationId": "getOrderCustomsRequirements", "summary": "Get Order Customs Requirements", "description": "This API is used to query whether an order requires extra customs clearance information, whether such information has been submitted, and the list of submitted customs clearance information.\nIf extra customs clearance information is required but not yet provided, the merchant must complete and submit it before shipment can proceed.", "tags": [ "Fulfillment" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrderCustomsRequirementsRequest" }, "example": { "order_ids": [ "584882846571464153", "584881010662934016" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrderCustomsRequirementsResponse" }, "example": { "code": 0, "data": { "order_clearance_list": [ { "order_id": "584882846571463232", "need_fill_clearance": true, "already_filled_clearance": false, "target_country": "JP", "biz_type": 1, "shipment_type": 1, "item_list": [ { "order_line_id": "584882846571423334", "product_id": "1729476373250999503", "sku_id": "1735885807280883357", "is_virtual_unboxing": true, "is_temporary_listing": false, "related_item_detail": [ { "product_id": "1729476373250999503", "sku_id": "1735885807280883357", "qty": 2, "price_percent": 10 } ] } ] } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 2, "x-tts-scopes": [ "Fulfillment Basic" ], "x-tts-error-codes": [ { "code": "11001002", "message": "invalid param." }, { "code": "11036004", "message": "system error, please retry" } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-order-customs-requirements-202607" } }, "/fulfillment/202607/orders/customs_info/submit": { "post": { "operationId": "submitCustomsClearanceInformation", "summary": "Submit Customs Clearance Information", "description": "This API is used to submit extra customs clearance information for discrepancies between declared information and physical goods.", "tags": [ "Fulfillment" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitCustomsClearanceInformationRequest" }, "example": { "order_list": [ { "order_id": "584882846571463232", "item_list": [ { "order_line_id": "584882846571423334", "sku_id": "1735885807280883357", "item_detail": [ { "sku_id": "1735885807280883357", "qty": 2, "price_percent": 10 } ] } ] } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitCustomsClearanceInformationResponse" }, "example": { "code": 0, "data": {}, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 2, "x-tts-scopes": [ "Fulfillment Basic" ], "x-tts-error-codes": [ { "code": "11001002", "message": "invalid param." }, { "code": "11036004", "message": "system error, please retry" } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/submit-customs-clearance-information-202607" } }, "/fulfillment/202609/order/sof/track/update": { "post": { "operationId": "trackingStatusUpdate", "summary": "Tracking status update", "description": "**This API is currently exclusive to the following markets: US, BR.**\nThis API is suitable for merchants to deliver and carry orders by themselves, without shipping orders through third-party service providers, that is, without shipping packages through 3PL, but orders sent by merchants. Merchants are allowed to use this API to return such orders and update the order track. The Action Code and Failed Reason in the input parameter are enumerated, as detailed in the document: https://partner.tiktokshop.com/docv2/page/1cjht3qx", "tags": [ "Fulfillment" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackingStatusUpdateRequest" }, "example": { "country": "BR", "order_id": "577071607420326620", "external_tracking_url": "https://www.correios.com.br/rastreamento/BR3PL202609090001", "tracks": [ { "action_code": 20201, "occur_time": 1788920100000, "description": "Package picked up by 3PL carrier", "failed_reason": "R110", "proof_url": "https://carrier-proof.example.com/proof/BR3PL202609090001", "location": { "country": "BR", "state": "SP", "city": "Campinas", "zip_code": "13010-000" }, "tracking_no": "BR443310090002" } ], "provider_id": "7189579428429563650" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackingStatusUpdateResponse" }, "example": { "code": 0, "data": { "track_results": [ { "action_code": 32401, "occur_time": 1788920100012, "description": "Line-haul transport departed", "code": 0, "message": "Success", "tracking_no": "BR123456789" } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Fulfillment Basic" ], "x-tts-error-codes": [ { "code": "11007010", "message": "System is busy, please try again later." }, { "code": "11007016", "message": "The merchant is not in the merchant allowlist." }, { "code": "11007017", "message": "The action_code is not in the allowlist table." }, { "code": "11007018", "message": "The order cannot be located using the provided TrackingNO and OrderId." }, { "code": "11007019", "message": "The merchant in the request does not match the actual merchant of the order." }, { "code": "11007020", "message": "Invalid trajectory. Please check the parameters in tracks." }, { "code": "11007021", "message": "Invalid provider id. Please check whether the postback provider id you submitted is a provider id allowed under the merchant self-shipping and self-delivery method." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/tracking-status-update-202609" } }, "/fulfillment/202610/orders/{order_id}/packages": { "post": { "operationId": "markPackageAsShipped", "summary": "Mark Package As Shipped", "description": "**This API is currently exclusive to the following markets: US, UK, ES, IE, IT, DE, FR, JP.**\nThis API is for sellers who fulfill orders through their own selected/preferred logistics carrier, and allows sellers to upload valid package information (items in packages, shipping provider information, and tracking number) orders/order line items to TikTok Shop. Use [Get Shipping Providers API](https://partner.tiktokshop.com/docv2/page/650aa48d4a0bb702c06d85cd?external_id=650aa48d4a0bb702c06d85cd) to retrieve the `shipping_provider_id` for shipping providers.", "tags": [ "Fulfillment" ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "description": "The unique identifier for a TikTok Shop order.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkPackageAsShippedRequest" }, "example": { "order_line_list": [ { "order_line_id": "5767675021119438849", "sub_item_id": "5767675021119438849" } ], "shipping_info_list": [ { "tracking_number": "6617675021119438849", "shipping_provider_id": "12312312321323432", "note": "this is a table" } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkPackageAsShippedResponse" }, "example": { "code": 0, "data": { "order_id": "32131324123321", "order_line_item_ids": [ "31322412312312" ], "package_id": "32141235124234", "warning": { "message": "match more than one provider" } }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "FS Order&Fulfillment Management", "Fulfillment Basic" ], "x-tts-error-codes": [ { "code": "11001027", "message": "System timeout. If this error persists, please contact the platform for assistance." }, { "code": "11001031", "message": "System process error, please try again later." }, { "code": "11005004", "message": "warehouse not exist" }, { "code": "11005010", "message": "get lead time from card service error" }, { "code": "11006005", "message": "System process error, please try again later." }, { "code": "11006026", "message": "System process error, please try again later." }, { "code": "11021009", "message": "No available shipping services for this request. Please modify the package weight or check the recipient address. If the error persists, please contact the platform for assistance." }, { "code": "11028006", "message": "This tracking number cannot be matched to any carrier, please check the tracking number and upload again." }, { "code": "11050001", "message": "invalid param" }, { "code": "21001001", "message": "Invalid parameters. Please ensure you are passing the correct request parameter(s)." }, { "code": "21001008", "message": "not found error" }, { "code": "21001011", "message": "System process error, please try again later." }, { "code": "21001028", "message": "The order is being processed. Try again later." }, { "code": "21001029", "message": "rpc logistics_logistics_service_4b failed" }, { "code": "21001043", "message": "System process error, please try again later." }, { "code": "21001055", "message": "System process error, please try again later." }, { "code": "21004012", "message": "Tracking number has special characters, verify failed." }, { "code": "21004015", "message": "Tracking number mismatch provider." }, { "code": "21004016", "message": "Tracking number verify, not avalible logsitics service or provider" }, { "code": "21004019", "message": "Need invoice uploaded for all order before rts." }, { "code": "21004020", "message": "Fulfillment Invoice status is not success, can not rts pkg." }, { "code": "21008025", "message": "Seller cannot operate orders which are fulfilled by platform" }, { "code": "21008042", "message": "seller already print shipping label" }, { "code": "21008044", "message": "SellerFulfillUnitInReverseCannotOperate" }, { "code": "21008099", "message": "Package has been shipped. Please not ship the package again." }, { "code": "21008106", "message": "This interface cannot be used in this region." }, { "code": "21008300", "message": "System process error, please try again later." }, { "code": "21011001", "message": "Package not found. If the error persists, please contact the platform for assistance." }, { "code": "21011003", "message": "fulfill_unit action not allowed" }, { "code": "21011004", "message": "This API cannot be used to update package shipping information for packages that are not shipped by sellers." }, { "code": "21011006", "message": "These orders are already shipped." }, { "code": "21011007", "message": "Package item has after-sale request, please process the after-sale request first." }, { "code": "21011012", "message": "not match trade rule" }, { "code": "21011013", "message": "not match logistics rule" }, { "code": "21011020", "message": "These orders are already shipped." }, { "code": "21011022", "message": "Invalid tracking number or provider ID. Please double check and try again." }, { "code": "21011025", "message": "Duplicate tracking number." }, { "code": "21011026", "message": "fulfillment tracking no used times over limit" }, { "code": "21011029", "message": "order does not belong to fulfill unit" }, { "code": "21011030", "message": "fulfillment not allow update tracking no" }, { "code": "21011033", "message": "order already combined" }, { "code": "21011036", "message": "split same sku in Multi Package not allow." }, { "code": "21011046", "message": "Order has combine, not allow split order" }, { "code": "21011048", "message": "There are multiple packages that can be shipped, please specify the order line that needs to be shipped." }, { "code": "21011050", "message": "The tracking number can only be updated within a certain number of hours." }, { "code": "21011051", "message": "The tracking number can only be updated once." }, { "code": "21021010", "message": "Failed to ship. You may cancel the order without penalty by selecting the following reason: Unable to deliver to buyer address." }, { "code": "21022025", "message": "A shipping label has already been purchased." }, { "code": "21022026", "message": "Cannot purchase shipping label, please try again later." }, { "code": "21022028", "message": "split pkg fail." }, { "code": "21022029", "message": "System process error, please try again later." }, { "code": "21022030", "message": "System process error, please try again later." }, { "code": "21032001", "message": "fulfill unit status not allow to update pkg attr" }, { "code": "21034006", "message": "decision route occurs error" }, { "code": "21034012", "message": "tracking no has been used" }, { "code": "21042056", "message": "These orders are already shipped." }, { "code": "21042057", "message": "These orders are not in the Awaiting shipment status. Couldn't create labels for them." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/mark-package-as-shipped-202610" } }, "/fulfillment/202610/packages/{package_id}/shipping_info/update": { "post": { "operationId": "updatePackageShippingInfo", "summary": "Update Package Shipping Info", "description": "If the seller entered an incorrect tracking number, this API allows the seller to update the tracking number and shipping provider for a package that has already been shipped. Attention: This API is only applicable to orders (or packages) shipped by the seller. It is only used to update the tracking number and shipping provider for packages that have already been shipped.", "tags": [ "Fulfillment" ], "parameters": [ { "name": "package_id", "in": "path", "required": true, "description": "TikTok Shop package ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePackageShippingInfoRequest" }, "example": { "shipping_info_list": [ { "tracking_number": "6617675021119438849", "shipping_provider_id": "12312312321323432", "note": "this is a table" } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePackageShippingInfoResponse" }, "example": { "code": 0, "data": {}, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "FS Order&Fulfillment Management", "Fulfillment Basic" ], "x-tts-error-codes": [ { "code": "10007002", "message": "Current order is not a merchant blind box order." }, { "code": "21001028", "message": "The order is being processed. Try again later." }, { "code": "21011001", "message": "Package not found. If the error persists, please contact the platform for assistance." }, { "code": "21011004", "message": "This API cannot be used to update package shipping information for packages that are not shipped by sellers." }, { "code": "21011007", "message": "Package item has after-sale request, please process the after-sale request first." }, { "code": "21011022", "message": "Invalid tracking number or provider ID. Please double check and try again." }, { "code": "21011028", "message": "The package does not belong to the current shop. Please ensure you are providing the correct package ID and/or shop cipher." }, { "code": "21011030", "message": "fulfillment not allow update tracking no" }, { "code": "21011042", "message": "Cannot complete the operation when order is cancelled." }, { "code": "21011043", "message": "The package has not been shipped yet." }, { "code": "21011049", "message": "Due to platform rule limitations, you are unable to update the tracking number." }, { "code": "21011050", "message": "The tracking number can only be updated within a certain number of hours." }, { "code": "21011051", "message": "The tracking number can only be updated once." }, { "code": "21011052", "message": "The tracking number can only be updated a limited number of times." }, { "code": "25001010", "message": "A return request has already been completed, or the order has already been cancelled." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/update-package-shipping-info-202610" } }, "/logistics/202309/delivery_options/{delivery_option_id}/shipping_providers": { "get": { "operationId": "getShippingProviders", "summary": "Get Shipping Providers", "description": "Returns the shipping providers available for the specified delivery option. If the delivery option is fulfilled by TikTok, the request returns an error and no shipping providers are returned.", "tags": [ "Logistics" ], "parameters": [ { "name": "delivery_option_id", "in": "path", "required": true, "description": "The delivery option ID, represented as a decimal integer string.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" }, { "name": "warehouse_region", "in": "query", "required": false, "description": "Warehouse country, indicating the shipping country.", "schema": { "type": "string" } }, { "name": "buyer_region", "in": "query", "required": false, "description": "Buyer's country, indicating the destination country for delivery.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetShippingProvidersResponse" }, "example": { "code": 0, "data": { "shipping_providers": [ { "id": "7117858858072016686", "name": "USPS" } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "FS Order&Fulfillment Management", "Fulfillment Basic", "Logistics Basic" ], "x-tts-error-codes": [ { "code": "21008116", "message": "No Subscription without specified delivery option." }, { "code": "21008117", "message": "The delivery of the specified delivery_option_id is fulfilled by TikTok. No shipping provider will be returned." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-shipping-providers-202309" } }, "/logistics/202309/global_warehouses": { "get": { "operationId": "getGlobalSellerWarehouses", "summary": "Get Global Seller Warehouses", "description": "This API retrieves global warehouses associated with the seller, including each warehouse's global warehouse ID, name, and ownership.", "tags": [ "Logistics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetGlobalSellerWarehousesResponse" }, "example": { "code": 0, "data": { "global_warehouses": [ { "id": "7000714532876273411", "name": "Guangzhou", "ownership": "SELLER" } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 2, "x-tts-scopes": [ "Global Shop Information" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-global-seller-warehouses-202309" } }, "/logistics/202309/warehouses": { "get": { "operationId": "getWarehouseList", "summary": "Get Warehouse List", "description": "Retrieves warehouses associated with the seller, including names, effective statuses, types, default designations, and available address information.", "tags": [ "Logistics" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetWarehouseListResponse" }, "example": { "code": 0, "data": { "warehouses": [ { "id": "7000714532876273410", "entity_id": "7395366865142499073", "name": "Guangzhou", "effect_status": "ENABLED", "type": "SALES_WAREHOUSE", "sub_type": "DOMESTIC_WAREHOUSE", "is_default": true, "address": { "region": "China", "state": "GuangDong", "city": "GuanZhou", "distict": "HuaDu", "town": "town", "contact_person": "Lee", "first_name": "新一", "last_name": "工藤", "first_name_local_script": "しんいち", "last_name_local_script": "くどう", "postal_code": "510000", "full_address": "South Sea 11 floor", "region_code": "CN", "phone_number": "188****2234", "address_line1": "Bairro/Distrito", "address_line2": "Caminho Trinta e Três", "address_line3": "3", "address_line4": "11 floor", "geolocation": { "latitude": "45.41634", "longitude": "-75.6868" } } } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Logistics Basic" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-warehouse-list-202309" } }, "/logistics/202309/warehouses/{warehouse_id}/delivery_options": { "get": { "operationId": "getWarehouseDeliveryOptions", "summary": "Get Warehouse Delivery Options", "description": "This API is used to obtain a list of delivery options available through the seller's designated warehouse.", "tags": [ "Logistics" ], "parameters": [ { "name": "warehouse_id", "in": "path", "required": true, "description": "The warehouse ID, represented as a decimal integer string.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" }, { "name": "scope", "in": "query", "required": false, "description": "Specify which delivery options to retrieve.\n- `WAREHOUSE`: Returns the delivery options currently active for the warehouse. Orders use these options by default.\n- `PRODUCT`: Returns delivery options that can be assigned directly to a product to override the default warehouse options. The response can contain `id`, `name`, `type`, `description`, and `platform`; this scope does not populate `dimension_limit` or `weight_limit`.\nDefault: `WAREHOUSE`", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetWarehouseDeliveryOptionsResponse" }, "example": { "code": 0, "data": { "delivery_options": [ { "id": "6955034615128000261", "name": "LSV-TTS-STD", "type": "STANDARD", "description": "LSV-TTS-STD S", "dimension_limit": { "max_height": 100, "max_length": 100, "max_width": 100, "unit": "INCH" }, "weight_limit": { "max_weight": 100, "min_weight": 100, "unit": "GRAM" }, "platform": [ "TOKOPEDIA", "TIKTOK_SHOP" ] } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Logistics Basic" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-warehouse-delivery-options-202309" } }, "/logistics/202510/seller_templates": { "get": { "operationId": "getShippingTemplateAvailability", "summary": "Get Shipping Template Availability", "description": "get seller's available shipping template and return the reason why the template is not available，this api is now only available for JP and UK market", "tags": [ "Logistics" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetShippingTemplateAvailabilityRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetShippingTemplateAvailabilityResponse" }, "example": { "code": 0, "data": { "templates": [ { "template_is_available": false, "template": { "template_name": "test template", "template_id": "1234566", "is_default": false, "template_party": 1 }, "service_unreachable_reason": [ { "service_id": "23241", "filter_reason": [ { "filter_type": "9", "reason": "Ship by seller is banned" } ] } ] } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Logistics Basic" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-shipping-template-availability-202510" } }, "/logistics/202604/orders/{order_id}/tracking": { "get": { "operationId": "getLogisticsTracking", "summary": "Get Logistics Tracking", "description": "Use this API to retrieve detailed logistics tracking information for an order. This API currently supports only cross-border trade (CBT) orders. Compared with Get Tracking, this API groups information by parcel and can include each parcel's carrier, latest tracking number, and tracking-event history.\n\nFor the mapping between `action_code` and `action_code_name`, see https://partner.tiktokshop.com/docv2/page/37tihrdq.", "tags": [ "Logistics" ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "description": "TikTok Shop order ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetLogisticsTrackingResponse" }, "example": { "code": 0, "data": { "order_id": "577071607420326620", "logistics_details": [ { "newest_tracking_no": "861651122474", "carrier_name": "J&T Express", "track_list": [ { "description": "Package has been delivered!\\n", "tracking_no": "861651122474", "update_time_millis": 1694686949000, "action_code": 50101, "action_code_name": "signed_personally" } ] } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Logistics Basic" ], "x-tts-error-codes": [ { "code": "11007009", "message": "This order is not in supported business scenes" }, { "code": "11007010", "message": "System is busy, please try again later." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-logistics-tracking-202604" } }, "/logistics/202606/seller_template/template_exist": { "get": { "operationId": "checkShippingTemplateExistence", "summary": "Check Shipping Template Existence", "description": "Checks whether the authenticated shop has a shipping template for the specified business warehouse.", "tags": [ "Logistics" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "access_token", "in": "query", "required": true, "description": "Authorization Token, provided for all eligible TikTok Shop Partner Developers.", "schema": { "type": "string" } }, { "name": "shop_id", "in": "query", "required": false, "description": "Shop id", "schema": { "type": "integer", "format": "int64" } }, { "name": "biz_warehouse_id", "in": "query", "required": true, "description": "Biz warehouse id", "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckShippingTemplateExistenceResponse" }, "example": { "code": 0, "data": { "template_exist": false }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Logistics Basic" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/check-shipping-template-existence-202606" } }, "/open/202512/file/init": { "post": { "operationId": "uploadFileInit", "summary": "Upload File Init", "description": "Use this API to initialize a file upload session. Then upload the file to the returned upload URL. Files of 5 MiB (5,242,880 bytes) or less must be uploaded as a single, non-chunked request with `total_chunk_count` set to `1`; larger files use a multipart upload. After the upload step returns a ResourceId, pass that ResourceId to the API for the target path.\n\nFor more details, see https://partner.tiktokshop.com/docv2/page/wfi3nz36.", "tags": [ "Tools" ], "parameters": [ { "name": "shop_cipher", "in": "query", "required": false, "description": "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. \nGet by API [Get Authorization Shop](https://partner.tiktokshop.com/docv2/page/6507ead7b99d5302be949ba9?external_id=6507ead7b99d5302be949ba9)", "schema": { "type": "string" } }, { "name": "category_asset_cipher", "in": "query", "required": false, "description": "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 The partner identifier used in API requests. \nRetrieve this value by using the [Get Authorized Category Assets API](https://partner.tiktokshop.com/docv2/page/666012dd609d4402cc3be995).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadFileInitRequest" }, "example": { "file_name": "video_20251201.mp4", "file_type": "video", "file_size": 1024, "total_chunk_count": 1, "target_path": "[POST]/affiliate_seller/202501/images/upload" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadFileInitResponse" }, "example": { "code": 0, "data": { "upload_url": "https://open-api.tiktokglobalshop.com/file/202512/upload", "upload_token": "50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccac74c50b88" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 100, "x-tts-scopes": [ "Content Posting", "Customer Service" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/upload-file-init-202512" } }, "/order/202309/orders/search": { "post": { "operationId": "getOrderList", "summary": "Get Order List", "description": "Returns a list of orders created or updated during the timeframe indicated by the specified parameters. You can also apply a range of filtering criteria to narrow the list of orders returned, such as order status, delivery option type, and buyer user ID.", "tags": [ "Orders" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "page_size", "in": "query", "required": true, "description": "The number of results to be returned per page. Default: 20. Valid range: [1-100].", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 100 } }, { "name": "sort_order", "in": "query", "required": false, "description": "The sort order for the `sort_field` parameter. Default: DESC\nPossible values:\n- ASC: Ascending order\n- DESC: Descending order", "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "x-enum-descriptions": [ "Ascending order", "Descending order" ] } }, { "name": "page_token", "in": "query", "required": false, "description": "An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the `next_page_token` from a previous response. It is not needed for the first page.", "schema": { "type": "string" } }, { "name": "sort_field", "in": "query", "required": false, "description": "The returned results will be sorted by the specified field. \nDefault: `create_time`\nPossible values:\n- `create_time`\n- `update_time`\n\nSpecify the order for sorting the returned results by using the `sort_order` parameter.", "schema": { "type": "string", "enum": [ "create_time", "update_time" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrderListRequest" }, "example": { "order_status": "UNPAID", "create_time_ge": 1623812664, "create_time_lt": 1623812664, "update_time_ge": 1623812664, "update_time_lt": 1623812664, "shipping_type": "TIKTOK", "buyer_user_id": "7213489962827123654", "is_buyer_request_cancel": false, "warehouse_ids": [ "7000714532876273888", "7000714532876273666" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrderListResponse" }, "example": { "code": 0, "data": { "next_page_token": "6AsPQsUMvH3RkchNUPPh22NROHkE0D8pmq/N5M1kHYcZmtRyv9aVrNv65W7Q6tFA+7D1ud64MPNz5OaT", "total_count": 22113, "orders": [ { "id": "576461413038785752", "buyer_message": "Please ship asap!", "cancellation_initiator": "SELLER", "shipping_provider_id": "6617675021119438849", "create_time": 1619611561, "shipping_provider": "TT Virtual express", "packages": [ { "id": "1152321127278713123" } ], "payment": { "currency": "IDR", "sub_total": "5000", "shipping_fee": "5000", "seller_discount": "5000", "platform_discount": "5000", "payment_platform_discount": "10", "payment_discount_service_fee": "10", "total_amount": "5000", "original_total_product_price": "5000", "original_shipping_fee": "5000", "shipping_fee_seller_discount": "5000", "shipping_fee_platform_discount": "5000", "shipping_fee_cofunded_discount": "5000", "tax": "5000", "small_order_fee": "3000", "shipping_fee_tax": "11", "product_tax": "21.3", "retail_delivery_fee": "1.28", "buyer_service_fee": "1000", "handling_fee": "1000", "shipping_insurance_fee": "1000", "item_insurance_fee": "1000", "item_insurance_tax": "10", "distance_shipping_fee": "1000", "distance_fee": "2000" }, "recipient_address": { "full_address": "1199 Coleman Ave San Jose, CA 95110", "phone_number": "(+1)213-***-1234", "name": "David Kong", "first_name": "David", "last_name": "Kong", "first_name_local_script": "ジョン", "last_name_local_script": "ドゥ", "address_detail": "Unit one building 8", "address_line1": "TikTok 5800 bristol Pkwy", "address_line2": "Suite 100", "address_line3": " ", "address_line4": " ", "district_info": [ { "address_level_name": "Country", "address_name": "United Kingdom", "address_level": "L0", "iso_code": "VAN" } ], "delivery_preferences": { "drop_off_location": "Front Door" }, "postal_code": "95110", "region_code": "US", "post_town": "Ribbleton" }, "status": "UNPAID", "fulfillment_type": "FULFILLMENT_BY_SELLER", "delivery_type": "HOME_DELIVERY", "paid_time": 1619611563, "rts_sla_time": 1619611688, "tts_sla_time": 1619611761, "cancel_reason": "Pricing error", "update_time": 1619621355, "payment_method_name": "CCDC", "rts_time": 1619611563, "tracking_number": "JX12345", "split_or_combine_tag": "COMBINED", "has_updated_recipient_address": false, "cancel_order_sla_time": 1619621355, "warehouse_id": "6955005333819123123", "request_cancel_time": 1678389618, "shipping_type": "TIKTOK", "user_id": "7021436810468230477", "seller_note": "seller note", "delivery_sla_time": 1678389618, "is_cod": false, "delivery_option_id": "7091146663229654785", "cancel_time": 1678389618, "need_upload_invoice": "NEED_INVOICE", "delivery_option_name": "Standard Shipping", "cpf": "3213-31231412", "line_items": [ { "id": "577086512123755123", "sku_id": "2729382476852921560", "combined_listing_skus": [ { "sku_id": "2729382476852921123", "sku_count": 1, "product_id": "1729582718312380456", "seller_sku": "yellow-24-XL " } ], "display_status": "UNPAID", "product_name": "Women's Winter Crochet Clothes", "seller_sku": "red_iphone_256", "sku_image": "https://p16-oec-va.itexeitg.com/tos-maliva-d-o5syd03w52-us/46123e87d14f40b69b839", "sku_name": "Iphone", "product_id": "1729582718312380123", "sale_price": "0.01", "pfand_fee": "1.50", "platform_discount": "0", "seller_discount": "0", "sku_type": "PRE_ORDER", "cancel_reason": "Discount not as expected", "original_price": "0.01", "rts_time": 1678389618, "package_status": "TO_FULFILL", "currency": "IDR", "shipping_provider_name": "TT Virtual express", "cancel_user": "BUYER", "shipping_provider_id": "6617675021119438849", "is_gift": false, "item_tax": [ { "tax_type": "SALES_TAX", "tax_amount": "21.2", "tax_rate": "0.35" } ], "tracking_number": "JX12345", "package_id": "1153132168123859123", "retail_delivery_fee": "1.28", "buyer_service_fee": "1000", "small_order_fee": "5000", "handling_duration_days": "7", "is_dangerous_good": false, "needs_prescription": false, "gift_retail_price": "20", "is_unboxing_item": false, "unboxing_sku_code": "14531134", "unboxing_case_list": [ { "unbox_sku": "14531134", "unbox_sku_type": "GIFT" } ], "room_id": "7652884452049160991", "sub_item_info": [ { "id": "577086512123755123", "sku_id": "2729382476852921560", "display_status": "UNPAID", "product_name": "Women's Winter Crochet Clothes", "seller_sku": "red_iphone_256", "sku_image": "https://p16-oec-va.itexeitg.com/tos-maliva-d-o5syd03w52-us/46123e87d14f40b69b839", "sku_name": "Iphone", "product_id": "1729582718312380123", "sale_price": "0.01", "platform_discount": "0", "seller_discount": "0", "cancel_reason": "Discount not as expected", "original_price": "0.01", "rts_time": 1678389618, "package_status": "TO_FULFILL", "currency": "USD", "shipping_provider_name": "TT Virtual express", "cancel_user": "BUYER", "shipping_provider_id": "6617675021119438849", "item_tax": [ { "tax_type": "SALES_TAX", "tax_amount": "21.2", "tax_rate": "0.35" } ], "tracking_number": "JX12345", "package_id": "1153132168123859123", "retail_delivery_fee": "1.28", "is_dangerous_good": false, "warehouse_id": "6955005333819123123" } ], "distance_shipping_fee": "1000", "distance_fee": "2000", "shipping_vat_amount": "3.5", "shipping_vat_rate": "0.25", "is_pod_customized": false, "pod_info_id": "789821378123", "product_listing_type": "TEMPORARY_LISTING" } ], "buyer_email": "v2b2V5@chat.seller.tiktok.com", "delivery_due_time": 1678389618, "is_sample_order": false, "shipping_due_time": 1678389618, "collection_due_time": 1678389618, "delivery_option_required_delivery_time": 1678389618, "is_on_hold_order": false, "delivery_time": 1678389618, "is_replacement_order": false, "is_subscription_order": true, "is_refundable_sample": false, "authentication_required": false, "collection_time": 1678389618, "replaced_order_id": "576461416728782174", "is_buyer_request_cancel": false, "pick_up_cut_off_time": 1678389618, "fast_dispatch_sla_time": 1678389618, "commerce_platform": "TIKTOK_SHOP", "order_type": "ZERO_LOTTERY", "release_date": 1619611762, "handling_duration": { "days": "7", "type": "BUSINESS_DAY" }, "auto_combine_group_id": "12345677", "cpf_name": "John Smith", "is_exchange_order": false, "exchange_source_order_id": "576461413038785752", "consultation_id": "123456", "fast_delivery_program": "3_DAY_DELIVERY", "fulfillment_priority_level": 100, "recommended_shipping_time": 1619611561, "buyer_nickname": "user213123", "buyer_avatar": "https://p16-oec-va.itexeitg.com/tos-maliva-d-o5syd03w52-us/46123e87d14f40b69b839", "order_rights": [ 1 ], "instore_pickup_sla_time": 1784090976, "fast_rts_sla_time": 1784090976, "fast_collection_sla_time": 1784090976 } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "FS Order&Fulfillment Management", "Order Information" ], "x-tts-error-codes": [ { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-order-list-202309" } }, "/order/202406/orders/external_order_search": { "post": { "operationId": "searchOrdersByExternalOrderReference", "summary": "Search Orders by External Order Reference", "description": "If you have used the `Add External Order References` API to sync information from your external order management system (OMS) to corresponding orders in TikTok Shop, you may call this API to search for order information in TikTok Shop based on information in your OMS.", "tags": [ "Orders" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "platform", "in": "query", "required": true, "description": "The alias of your external order management system (OMS).\nPossible values:\n- SHOPIFY\n- WOOCOMMERCE\n- BIGCOMMERCE\n- MAGENTO\n- SALESFORCE_COMMERCE_CLOUD\n- CHANNEL_ADVISOR\n- AMAZON\n- ORDER_MANAGEMENT_SYSTEM\n- WAREHOUSE_MANAGEMENT_SYSTEM\n- ERP_SYSTEM", "schema": { "type": "string", "enum": [ "SHOPIFY", "WOOCOMMERCE", "BIGCOMMERCE", "MAGENTO", "SALESFORCE_COMMERCE_CLOUD", "CHANNEL_ADVISOR", "AMAZON", "ORDER_MANAGEMENT_SYSTEM", "WAREHOUSE_MANAGEMENT_SYSTEM", "ERP_SYSTEM" ] } }, { "name": "external_order_id", "in": "query", "required": true, "description": "Order ID in your OMS.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchOrdersByExternalOrderReferenceRequest" }, "example": {} } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchOrdersByExternalOrderReferenceResponse" }, "example": { "code": 0, "data": { "orders": [ { "id": "576461413038785752", "external_order": { "id": "676461413038785752", "platform": "SHOPIFY", "line_items": [ { "id": "577086512123755123", "origin_id": "677086512123755123" } ] } } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Read External Order References" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-orders-by-external-order-reference-202406" } }, "/order/202406/orders/external_orders": { "post": { "operationId": "addExternalOrderReferences", "summary": "Add External Order References", "description": "If you use an external order management system (OMS), its order and line item IDs may differ from the corresponding TikTok Shop IDs. Use this endpoint to attach external OMS references to up to 100 TikTok Shop orders. To update an existing reference, call the endpoint again with the same TikTok Shop order and OMS. Each order is processed independently. On a successful API response, references for orders not listed in `data.errors` are saved; use that list to identify per-order errors.", "tags": [ "Orders" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddExternalOrderReferencesRequest" }, "example": { "orders": [ { "id": "576461413038785752", "external_order": { "id": "676461413038785752", "platform": "SHOPIFY", "line_items": [ { "id": "577086512123755123", "origin_id": "677086512123755123" } ] } } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddExternalOrderReferencesResponse" }, "example": { "code": 0, "data": { "errors": [ { "code": "36020001", "message": "Invalid order_id", "detail": { "order_id": "576461413038785752", "external_order": { "id": "676461413038785752", "platform": "SHOPIFY" } } } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Write External Order References" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/add-external-order-references-202406" } }, "/order/202406/orders/{order_id}/external_orders": { "get": { "operationId": "getExternalOrderReferences", "summary": "Get External Order References", "description": "If you have used the `Add External Order References` API, use this API to retrieve the external order references associated with a TikTok Shop order for the specified external order management system (OMS) platform.", "tags": [ "Orders" ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "description": "The unique identifier for a TikTok Shop order.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" }, { "name": "platform", "in": "query", "required": true, "description": "The alias of your external order management system (OMS). \nPossible values:\n- SHOPIFY\n- WOOCOMMERCE\n- BIGCOMMERCE\n- MAGENTO\n- SALESFORCE_COMMERCE_CLOUD\n- CHANNEL_ADVISOR\n- AMAZON\n- ORDER_MANAGEMENT_SYSTEM\n- WAREHOUSE_MANAGEMENT_SYSTEM\n- ERP_SYSTEM", "schema": { "type": "string", "enum": [ "SHOPIFY", "WOOCOMMERCE", "BIGCOMMERCE", "MAGENTO", "SALESFORCE_COMMERCE_CLOUD", "CHANNEL_ADVISOR", "AMAZON", "ORDER_MANAGEMENT_SYSTEM", "WAREHOUSE_MANAGEMENT_SYSTEM", "ERP_SYSTEM" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetExternalOrderReferencesResponse" }, "example": { "code": 0, "data": { "external_orders": [ { "id": "676461413038785752", "platform": "SHOPIFY", "line_items": [ { "id": "577086512123755123", "origin_id": "677086512123755123" } ] } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Read External Order References" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-external-order-references-202406" } }, "/order/202407/orders/{order_id}/price_detail": { "get": { "operationId": "getOrderPriceDetails", "summary": "Get Order Price Details", "description": "Get the detailed pricing calculation information of an order or a line item, including vouchers, tax, etc.", "tags": [ "Orders" ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "description": "Order ID", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ShopCipher" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrderPriceDetailsResponse" }, "example": { "code": 0, "data": { "currency": "USD", "total": "122.00", "payment": "101.00", "sku_list_price": "97.00", "sku_sale_price": "96.00", "subtotal": "98.00", "subtotal_deduction_seller": "0.50", "subtotal_deduction_platform": "0.50", "subtotal_tax_amount": "2.00", "voucher_deduction_platform": "1010000", "voucher_deduction_seller": "1020000", "shipping_list_price": "25.00", "shipping_sale_price": "3.00", "shipping_fee_deduction_seller": "10.00", "shipping_fee_deduction_platform": "12.00", "shipping_fee_deduction_platform_voucher": "1010000", "tax_amount": "2.00", "tax_rate": "0.021", "net_price_amount": "97.00", "cod_fee": "0.00", "cod_fee_net_amount": "0.00", "sku_gift_original_price": "2.00", "sku_gift_net_price": "2.02", "distance_shipping_fee": "1.00", "distance_fee": "2.00", "line_items": [ { "id": "576461413032342720", "currency": "USD", "total": "122.00", "payment": "101.00", "sku_list_price": "97.00", "sku_sale_price": "96.00", "subtotal": "98.00", "subtotal_deduction_seller": "0.50", "subtotal_deduction_platform": "0.50", "subtotal_tax_amount": "2.00", "voucher_deduction_platform": "1010000", "voucher_deduction_seller": "1020000", "shipping_list_price": "25.00", "shipping_sale_price": "3.00", "shipping_fee_deduction_seller": "10.00", "shipping_fee_deduction_platform": "12.00", "shipping_fee_deduction_platform_voucher": "1010000", "tax_amount": "2.00", "tax_rate": "0.021", "net_price_amount": "97.00", "cod_fee": "0.00", "cod_fee_amount": "0.00", "sku_gift_original_price": "2.00", "sku_gift_net_price": "2.02", "distance_shipping_fee": "1.00", "distance_fee": "2.00", "seller_funded_product_promotions": [ { "activity_id": "7136104329798256386", "discount_amount": "2.25", "discount_type": "COUPON" } ], "seller_funded_shipping_promotions": [ { "activity_id": "7136104329798256386", "discount_amount": "2.25", "discount_type": "COUPON" } ] } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Order Information" ], "x-tts-error-codes": [ { "code": "21001001", "message": "Invalid parameters. Please ensure you are passing the correct request parameter(s)." }, { "code": "21008111", "message": "The order or package does not belong to the current seller." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-order-price-details-202407" } }, "/order/202507/orders": { "get": { "operationId": "getOrderDetail", "summary": "Get Order Detail", "description": "Get the detailed order information of an order, including important attributes such as order status, shipping addresses, payment details, price and tax info, and package information.", "tags": [ "Orders" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "ids", "in": "query", "required": true, "description": "A list of TikTok Shop order ID values.\nMax count: 50", "explode": false, "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrderDetailResponse" }, "example": { "code": 0, "data": { "orders": [ { "id": "576461413038785752", "cancellation_initiator": "SELLER", "shipping_provider": "TT Virtual express", "shipping_provider_id": "6617675021119438849", "user_id": "7021436810468230477", "status": "UNPAID", "rts_time": 1619611563, "payment": { "currency": "IDR", "sub_total": "5000", "shipping_fee": "5000", "seller_discount": "5000", "platform_discount": "5000", "payment_platform_discount": "10", "payment_discount_service_fee": "10", "total_amount": "5000", "original_total_product_price": "5000", "original_shipping_fee": "5000", "shipping_fee_seller_discount": "5000", "shipping_fee_platform_discount": "5000", "shipping_fee_cofunded_discount": "7", "tax": "5000", "small_order_fee": "3000", "shipping_fee_tax": "11", "product_tax": "21.3", "retail_delivery_fee": "1.28", "buyer_service_fee": "1000", "handling_fee": "1000", "shipping_insurance_fee": "1000", "item_insurance_fee": "1000", "item_insurance_tax": "10", "distance_shipping_fee": "1000", "distance_fee": "2000" }, "recipient_address": { "full_address": "1199 Coleman Ave San Jose, CA 95110", "phone_number": "(+1)213-***-1234", "name": "David Kong", "first_name": "David", "last_name": "Kong", "first_name_local_script": "ジョン", "last_name_local_script": "ドゥ", "region_code": "US", "postal_code": "95110", "post_town": "Ribbleton", "address_line1": "TikTok 5800 bristol Pkwy", "address_line2": "Suite 100", "address_line3": "Vila Olímpia", "address_line4": "Avenida Presidente Juscelino Kubitschek", "district_info": [ { "address_level_name": "Country", "address_name": "United Kingdom", "address_level": "L0", "iso_code": "VAN" } ], "delivery_preferences": { "drop_off_location": "Front Door" }, "address_detail": "Unit one building 8" }, "buyer_message": "Please ship asap!", "create_time": 1619611561, "tracking_number": "JX12345", "cancel_reason": "Pricing error", "rts_sla_time": 1619611688, "paid_time": 1619611563, "fulfillment_type": "FULFILLMENT_BY_SELLER", "seller_note": "seller note", "tts_sla_time": 1619611761, "cancel_order_sla_time": 1619621355, "update_time": 1619621355, "packages": [ { "id": "1152321127278713123" } ], "delivery_type": "HOME_DELIVERY", "is_sample_order": false, "warehouse_id": "6955005333819123123", "split_or_combine_tag": "COMBINED", "has_updated_recipient_address": false, "cpf": "3213-31231412", "delivery_option_id": "7091146663229654785", "delivery_sla_time": 1678389618, "payment_method_name": "CCDC", "payment_card_type": "Debit", "channel_entity_national_registry_id": "26.545.167/0001-21", "payment_method_code": "pm_pi_ccdc_visa_c_d", "payment_auth_code": "AUTH123457", "shipping_due_time": 1678389618, "line_items": [ { "id": "577086512123755123", "sku_id": "2729382476852921560", "combined_listing_skus": [ { "sku_id": "2729382476852921123", "sku_count": 1, "product_id": "1729582718312380456", "seller_sku": "yellow-24-XL" } ], "product_id": "1729582718312380123", "product_name": "Women's Winter Crochet Clothes", "sku_name": "Iphone", "sku_image": "https://p16-oec-va.itexeitg.com/tos-maliva-d-o5syd03w52-us/46123e87d14f40b69b839", "original_price": "0.01", "sale_price": "0.01", "pfand_fee": "1.5", "platform_discount": "0", "display_status": "TO_SHIP", "cancel_user": "BUYER", "sku_type": "PRE_ORDER", "seller_sku": "red_iphone_256", "shipping_provider_id": "6617675021119438849", "seller_discount": "0", "currency": "IDR", "package_id": "1153132168123859123", "rts_time": 1678389618, "item_tax": [ { "tax_type": "SALES_TAX", "tax_amount": "21.2", "tax_rate": "0.35" } ], "package_status": "TO_FULFILL", "shipping_provider_name": "TT Virtual express", "is_gift": false, "cancel_reason": "Discount not as expected", "small_order_fee": "5000", "retail_delivery_fee": "1.28", "tracking_number": "JX12345", "buyer_service_fee": "1000", "handling_duration_days": "7", "is_dangerous_good": true, "needs_prescription": true, "gift_retail_price": "20", "is_unboxing_item": false, "unboxing_sku_code": "14531134", "unboxing_case_list": [ { "unbox_sku": "14531134", "unbox_sku_type": "GIFT" } ], "sub_item_info": [ { "id": "577086512123755123", "sku_id": "2729382476852921560", "display_status": "UNPAID", "product_name": "Women's Winter Crochet Clothes", "seller_sku": "red_iphone_256", "sku_image": "https://p16-oec-va.itexeitg.com/tos-maliva-d-o5syd03w52-us/46123e87d14f40b69b839", "sku_name": "Iphone", "product_id": "1729582718312380123", "sale_price": "0.01", "platform_discount": "0", "seller_discount": "0", "cancel_reason": "Discount not as expected", "original_price": "0.01", "rts_time": 1678389618, "package_status": "TO_FULFILL", "currency": "USD", "shipping_provider_name": "TT Virtual express", "cancel_user": "BUYER", "shipping_provider_id": "6617675021119438849", "item_tax": [ { "tax_type": "SALES_TAX", "tax_amount": "21.2", "tax_rate": "0.35" } ], "tracking_number": "JX12345", "package_id": "1153132168123859123", "retail_delivery_fee": "1.28", "is_dangerous_good": false, "warehouse_id": "6955005333819123123" } ], "distance_shipping_fee": "1000", "distance_fee": "2000", "shipping_vat_amount": "3.5", "shipping_vat_rate": "0.25", "is_pod_customized": false, "pod_info_id": "789123812334", "room_id": "7652884452049160991", "product_listing_type": "TEMPORARY_LISTING" } ], "shipping_type": "TIKTOK", "buyer_email": "v2b2V5@chat.seller.tiktok.com", "delivery_time": 1678389618, "need_upload_invoice": "NEED_INVOICE", "is_cod": false, "request_cancel_time": 1678389618, "delivery_option_required_delivery_time": 1678389618, "delivery_option_name": "Express shipping", "is_buyer_request_cancel": false, "delivery_due_time": 1678389618, "collection_time": 1678389618, "is_on_hold_order": false, "cancel_time": 1678389618, "is_replacement_order": false, "replaced_order_id": "576461416728782174", "collection_due_time": 1678389618, "pick_up_cut_off_time": 1678389618, "fast_dispatch_sla_time": 1678389618, "commerce_platform": "TIKTOK_SHOP", "order_type": "ZERO_LOTTERY", "release_date": 1619611762, "handling_duration": { "days": "7", "type": "BUSINESS_DAY" }, "auto_combine_group_id": "12345677", "cpf_name": "John Smith", "is_exchange_order": false, "exchange_source_order_id": "576461413038785752", "is_subscription_order": true, "is_refundable_sample": false, "authentication_required": false, "consultation_id": "123241", "fast_delivery_program": "3_DAY_DELIVERY", "buyer_nickname": "user213123", "buyer_avatar": "https://p16-oec-va.itexeitg.com/tos-maliva-d-o5syd03w52-us/46123e87d14f40b69b839", "order_rights": [ 1 ], "fulfillment_priority_level": 100, "recommended_shipping_time": 1619611561, "instore_pickup_sla_time": 1784090976, "fast_rts_sla_time": 1784090976, "fast_collection_sla_time": 1784090976 } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "FS Order&Fulfillment Management", "Order Information" ], "x-tts-error-codes": [ { "code": "10002014", "message": "Failed to get orders, If multiple retry have failed, please contact the platform for assistance" }, { "code": "10002015", "message": "Failed to get orders, If multiple retry have failed, please contact the platform for assistance" }, { "code": "10006402", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." }, { "code": "10037002", "message": "Failed to get orders, If multiple retry have failed, please contact the platform for assistance" }, { "code": "10037003", "message": "Failed to get orders, If multiple retry have failed, please contact the platform for assistance" }, { "code": "10037004", "message": "Failed to get orders, If multiple retry have failed, please contact the platform for assistance" }, { "code": "21008111", "message": "The order or package does not belong to the current seller." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-order-detail-202507" } }, "/order/202605/orders/blind_box_result/callback": { "post": { "operationId": "updateTheBlindBoxOpeningResults", "summary": "Update The Blind Box Opening Results", "description": "After the merchant completes blind box opening in a live room, use this callback to send the opening results for an order back to the platform. The request supports two result shapes: `blind_box_results` contains one unboxed product per item, while `blind_batch_box_results` groups one or more unboxed products under an order line. If `blind_batch_box_results` is non-empty, the platform processes it and ignores `blind_box_results`. Buyers can then view the unboxing results in the order details.", "tags": [ "Orders" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTheBlindBoxOpeningResultsRequest" }, "example": { "main_order_id": "576461413038785752", "blind_box_results": [ { "order_line_id": "577086512123755123", "blind_result_product_id": "1732042550463074704", "blind_result_sku_id": "1732042694638604688", "blind_open_time": 1762782183118 } ], "blind_batch_box_results": [ { "order_line_id": "577086512123755123", "blind_box_order_line_list": [ { "blind_result_product_id": "1732042550463074704", "blind_result_sku_id": "1732042694638604688", "blind_open_time": 1762782183118, "product_type": "NORMAL" } ] } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTheBlindBoxOpeningResultsResponse" }, "example": { "code": 0, "data": {}, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Order Information" ], "x-tts-error-codes": [ { "code": "10007002", "message": "Current order is not a merchant blind box order." }, { "code": "10007006", "message": "Invalid params, please check that all required parameters are not illegal." }, { "code": "10007008", "message": "The order information has not been obtained." }, { "code": "10007109", "message": "Order update failed, please contract platform." }, { "code": "10007143", "message": "The product information has not been obtained. Please confirm whether the product information is synchronized to Tiktok Shop." }, { "code": "10007999", "message": "System Exception, please contract platform." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/update-the-blind-box-opening-results-202605" } }, "/order/202606/pod_details/search": { "post": { "operationId": "searchPODCustomizationDetails", "summary": "Search POD Customization Details", "description": "Search for POD customization details for the specified order lines.", "tags": [ "Orders" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchPODCustomizationDetailsRequest" }, "example": { "main_order_id": "577449529742299260", "query_order_lines": [ { "order_line_id": "577449529742430332", "product_id": "1732453831920750867", "sku_id": "1732453830297817363", "pod_order_data_id": "122343" } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchPODCustomizationDetailsResponse" }, "example": { "code": 0, "data": { "pod_details": [ { "order_line_id": "577457287176491132", "pod_detail": "pod_info_json" } ], "status_code": 0 }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Order Information" ], "x-tts-error-codes": [], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-pod-customization-details-202606" } }, "/product/202309/brands": { "get": { "operationId": "getBrands", "summary": "Get Brands", "description": "Retrieve brands for your shop, including the built-in brands and any custom brands created using the [Create Custom Brands API](650a0926f1fd3102b91bbfb0). Pass the returned brand ID when creating or editing a product to associate the brand with the product.\n- To check if a brand is fully authorized for use in a specific product category, specify the **category ID**.\n- To obtain the full list of brands that your shop can potentially use and their authorization status, omit the category ID. We recommend that you specify the **brand name** to narrow down the list of brands returned.\n**Key concept**\nWhether you can select and display a brand depends on the brand's authorization status, the categories authorized for the brand, and whether the brand is classified as T1 (internationally renowned brands that require prior brand authorization).\n**- Brand selection rules**: You can only select the following types of brands during product creation/editing.\n - Authorized brands which contain the desired category (`authorized_status=AUTHORIZED` and `brand_status=AVAILABLE`)\n - Unauthorized non-T1 brands (`authorized_status=UNAUTHORIEZD` and `is_t1_brand=false`) \n**- Brand display rules**: Note however that brands will only appear on the product display page if the brand is authorized (`authorized_status=AUTHORIZED`) and available in the desired category (`brand_status=AVAILABLE`). This means that you need to obtain brand authorization for unauthorized non-T1 brands before they can be displayed. Obtain brand authorization or add categories to an authorized brand through TikTok Shop Seller Center > Qualification Center > Brand qualification.\n**For Tokopedia sellers**: You can select and display any returned brand on Tokopedia regardless of these rules.", "tags": [ "Products" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "category_id", "in": "query", "required": false, "description": "Specify a category ID to show the availability of **authorized brands** in the category.\n**Note**: Specify this value to obtain an accurate list of brands that you can use in a category.", "schema": { "type": "string" } }, { "name": "is_authorized", "in": "query", "required": false, "description": "Filter results by the brand authorization status.\nPossible values:\n- 1: Returns only authorized brands\n- 0: Returns all brands", "schema": { "type": "boolean" } }, { "name": "brand_name", "in": "query", "required": false, "description": "Filter results to include brand names that begin with the specified value.", "schema": { "type": "string" } }, { "name": "page_size", "in": "query", "required": true, "description": "The number of results to be returned per page.\nValid range: [1-100]", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 100 } }, { "name": "page_token", "in": "query", "required": false, "description": "An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the `next_page_token` from a previous response. It is not needed for the first page.", "schema": { "type": "string" } }, { "name": "category_version", "in": "query", "required": false, "description": "Filter categories by the category tree version.Possible values based on region:\n- US, EU and SEA: v2, represents the 7-level category tree. \nImportant: For US, EU and SEA shops, you must pass v2 when using this API.\n- Other regions: v1, represents the 3-level category tree.Default: v1", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetBrandsResponse" }, "example": { "code": 0, "data": { "brands": [ { "id": "7082427311584347905", "name": "Teas", "authorized_status": "AUTHORIZED", "is_t1_brand": true, "brand_status": "AVAILABLE" } ], "total_count": 10000, "next_page_token": "cGFnZV9udW1iZXI9Mg==" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Product Basic" ], "x-tts-error-codes": [ { "code": "12019108", "message": "page number is invalid" }, { "code": "12019109", "message": "page size is invalid" }, { "code": "12019123", "message": "product of pageSize and pageNumber exceeds the maximum limit" }, { "code": "12019124", "message": "pageSize and pageNumber need to be used together" }, { "code": "12052023", "message": "Category does not exist" }, { "code": "12052217", "message": "All region shops must use V2 categories. Check the documentation for further details." }, { "code": "12052230", "message": "Category version and categoryID are not matched." }, { "code": "12052700", "message": "The seller is inactive." }, { "code": "12052704", "message": "seller id not exist" }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-brands-202309" }, "post": { "operationId": "createCustomBrands", "summary": "Create Custom Brands", "description": "Create custom brands for your own use across all markets.\nAuthorization is not required when creating a brand. You can create the brand first and obtain brand authorization later through the Qualification Center in TikTok Shop Seller Center.\n**Note**: You can create up to 50 brands per day, with a total limit of 1,000 brands.", "tags": [ "Products" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomBrandsRequest" }, "example": { "name": "Teas" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomBrandsResponse" }, "example": { "code": 0, "data": { "id": "7082427311584347905" }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-scenario": 2, "x-tts-scopes": [ "Product Basic" ], "x-tts-error-codes": [ { "code": "12052189", "message": "Brand names must be at least 2 characters." }, { "code": "12052190", "message": "Brand names must not be longer than 30 characters." }, { "code": "12052191", "message": "Brand names can't include special fonts or emoticons." }, { "code": "12052192", "message": "The brand name can't contain 5 or more consecutive numbers." }, { "code": "12052202", "message": "The total number of brands you have created today exceeds the limit." }, { "code": "12052203", "message": "The total number of brands you have created exceeds the limit." }, { "code": "12052204", "message": "The brand name you created is invalid." }, { "code": "12052205", "message": "This brand name already exists." }, { "code": "12052206", "message": "The number of characters of the created brand name is invalid." }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/create-custom-brands-202309" } }, "/product/202309/categories": { "get": { "operationId": "getCategories", "summary": "Get Categories", "description": "Retrieve the list of product categories available for your shop.\nProduct categories are updated frequently, so it's recommended to call the API in real time to ensure you are using the latest category data. Caching category data locally may result in using outdated information, leading to errors when creating products.\n**For the Indonesia market**: To list a product on both TikTok Shop and Tokopedia, use only categories available on both platforms. Call this API once with `listing_platform` set to `TIKTOK_SHOP` and once with it set to `TOKOPEDIA`, then identify the categories returned by both calls.", "tags": [ "Products" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" }, { "name": "locale", "in": "query", "required": false, "description": "The BCP-47 locale codes for displaying category information.\nDefault: The default locale of your shop.\nPossible values:\n- `cs-CZ`\n- `de-AT`\n- `de-BE`\n- `de-DE`\n- `el-GR`\n- `en-GB`\n- `en-IE`\n- `en-US`\n- `es-ES`\n- `es-MX`\n- `fr-FR`\n- `fr-BE`\n- `hu-HU`\n- `id-ID`\n- `it-IT`\n- `ja-JP`\n- `ms-MY`\n- `nl-NL`\n- `nl-BE`\n- `pl-PL`\n- `pt-BR`\n- `pt-PT`\n- `th-TH`\n- `vi-VN`\n- `zh-CN`", "schema": { "type": "string", "enum": [ "cs-CZ", "de-AT", "de-BE", "de-DE", "el-GR", "en-GB", "en-IE", "en-US", "es-ES", "es-MX", "fr-FR", "fr-BE", "hu-HU", "id-ID", "it-IT", "ja-JP", "ms-MY", "nl-NL", "nl-BE", "pl-PL", "pt-BR", "pt-PT", "th-TH", "vi-VN", "zh-CN" ] } }, { "name": "keyword", "in": "query", "required": false, "description": "Filter categories by this keyword in `local_name`.", "schema": { "type": "string" } }, { "name": "category_version", "in": "query", "required": false, "description": "Filter categories by the category tree version.Possible values based on region:\n- US, EU and SEA: v2, represents the 7-level category tree. \nImportant: For US, EU and SEA shops, you must pass v2 when using this API.\n- Other regions: v1, represents the 3-level category tree.Default: v1", "schema": { "type": "string" } }, { "name": "listing_platform", "in": "query", "required": false, "description": "Filter categories by the specified platform.\nPossible values:\n- TIKTOK_SHOP\n- TOKOPEDIA\nDefault: TIKTOK_SHOP\n\nApplicable only for sellers that migrated from Tokopedia.", "schema": { "type": "string", "enum": [ "TIKTOK_SHOP", "TOKOPEDIA" ] } }, { "name": "include_prohibited_categories", "in": "query", "required": false, "description": "A flag to indicate whether to include categories that are prohibited on TikTok Shop. Set this to `true` to identify which are the product categories that you can't list on TikTok Shop in any circumstances.\nApplicable only for BR, MX, EU and SEA markets.", "schema": { "type": "boolean" } }, { "name": "is_live_quick", "in": "query", "required": false, "description": "false — NORMAL products\ntrue — LIVE_QUICK products. Only seller with the required permissions can creat LIVE_QUICK products.\nDefault: false", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCategoriesResponse" }, "example": { "code": 0, "data": { "categories": [ { "id": "600002", "parent_id": "600001", "local_name": "Home Supplies", "is_leaf": false, "permission_statuses": [ "INVITE_ONLY", "NON_MAIN_CATEGORY" ] } ] }, "message": "Success", "request_id": "202203070749000101890810281E8C70B7" } } } } }, "x-tts-requires-shop-cipher": true, "x-tts-scenario": 1, "x-tts-scopes": [ "Product Basic" ], "x-tts-error-codes": [ { "code": "12019210", "message": "publish param invalid" }, { "code": "12052023", "message": "Category does not exist" }, { "code": "12052217", "message": "All region shops must use V2 categories. Check the documentation for further details." }, { "code": "12052230", "message": "Category version and categoryID are not matched." }, { "code": "12052700", "message": "The seller is inactive." }, { "code": "12052704", "message": "seller id not exist" }, { "code": "36009003", "message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support." } ], "x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-categories-202309" } }, "/product/202309/categories/recommend": { "post": { "operationId": "recommendCategory", "summary": "Recommend Category", "description": "Retrieve the recommended category for a candidate product based on its title, description, and images.\nIf you are syncing product catalogs from an external system to TikTok Shop, use this API to facilitate product categorization.\n**Note**: The language used in text fields such as descriptions and titles must align with the target market's language (e.g. don't use Chinese).", "tags": [ "Products" ], "parameters": [ { "$ref": "#/components/parameters/ShopCipher" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecommendCategoryRequest" }, "example": { "category_version": "v1", "description": "Please check the measurements before purchase.
\n![](\"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/181595ea7d26489284b5667488d708c1~tplv-o3syd03w52-origin-jpeg.jpeg?from=1432613627\")
",
"images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
],
"include_prohibited_categories": false,
"listing_platform": "TIKTOK_SHOP",
"locale": "en-US",
"origin_platform_product_type": "Handbags",
"origin_platform_vendor": "Chanel",
"origin_platform_tags": [
"blastcornhole",
"Shopify Collective"
],
"origin_platform_category": {
"id": "gid://shopify/TaxonomyCategory/na",
"name": "Uncategorized",
"full_name": "Uncategorized",
"is_leaf": true,
"is_root": true
},
"origin_platform_product_meta_data": {
"attribute_value_list": [
{
"name": "mark_out_of_stock",
"values": [
"true"
]
}
]
},
"product_title": "Men's Fashion Sports Low Cut Cotton Breathable Ankle Short",
"is_live_quick": false
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecommendCategoryResponse"
},
"example": {
"code": 0,
"data": {
"categories": [
{
"id": "605254",
"is_leaf": true,
"level": 1,
"name": "Teas",
"permission_statuses": [
"INVITE_ONLY"
]
}
],
"leaf_category_id": "605254"
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [
{
"code": "12019006",
"message": "product description is invalid"
},
{
"code": "12019009",
"message": "product image list is invalid"
},
{
"code": "12019064",
"message": "No matching categories. Provide the full name of your product, edit its product properties, and try again."
},
{
"code": "12052013",
"message": "The product description cannot exceed maximum characters"
},
{
"code": "12052051",
"message": "The product name exceed max limit characters"
},
{
"code": "12052056",
"message": "The num of image in description cannot exceed max limit"
},
{
"code": "12052217",
"message": "All region shops must use V2 categories. Check the documentation for further details."
},
{
"code": "12052230",
"message": "Category version and categoryID are not matched."
},
{
"code": "12052261",
"message": "product name is empty"
},
{
"code": "12052262",
"message": "Chinese characters are not supported in product name"
},
{
"code": "12052266",
"message": "The product name contains non-English characters."
},
{
"code": "12052300",
"message": "product main image uri illegal"
},
{
"code": "12052301",
"message": "Width and length of main image must be at least {{min_limit}}, check uri {{uri}}"
},
{
"code": "12052305",
"message": "The main images aspect ratio cannot exceed max limit."
},
{
"code": "12052306",
"message": "main product images count exceed limit"
},
{
"code": "12052340",
"message": "product description image uri illegal"
},
{
"code": "12052341",
"message": "The description images size cannot exceed limit."
},
{
"code": "12052343",
"message": "Product description image format not support."
},
{
"code": "12052345",
"message": "The product description html tag not support."
},
{
"code": "12052346",
"message": "The product description has Chinese characters"
},
{
"code": "12052348",
"message": "The product description html tag required attribute is miss."
},
{
"code": "12052349",
"message": "The product description html tag not support nest."
},
{
"code": "12052350",
"message": "The product description html tag contain illegal attribute."
},
{
"code": "12052351",
"message": "The product description contains non-English characters."
},
{
"code": "12052352",
"message": "The product description nest exceeding limit"
},
{
"code": "12052700",
"message": "The seller is inactive."
},
{
"code": "12052704",
"message": "seller id not exist"
},
{
"code": "12052722",
"message": "The image URI does not exist in TikTok Shop."
},
{
"code": "12052912",
"message": "No matching category found within your account's main category. Check your main category in the seller profile on Seller Center and ensure your product falls within its scope."
},
{
"code": "12052931",
"message": "The title must follow these formatting rules: it cannot contain HTML escape characters (e.g., ), emojis, or ASCII control characters (e.g., \\u007F). It also cannot consist solely of symbols (e.g., //// or !@#$$$&), nor can it have more than 9 consecutive repeated characters (e.g., aaaaaaaaa or 111111111)."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/recommend-category-202309"
}
},
"/product/202309/categories/{category_id}/attributes": {
"get": {
"operationId": "getCategoryAttributes",
"summary": "Get Category Attributes",
"description": "Retrieve the standard built-in product and sales attributes for listing a product in a particular category based on your shop's location.\nProducts on TikTok Shop are grouped into categories predefined by TikTok Shop, and each category is associated with a standard set of product attributes and sales attributes.\n- **Sales attributes** (e.g. size, color, length) define product variants and are optional if your product is straightforward and has no variants.\n- **Product attributes** (e.g. manufacturer, country of origin, materials used) describe the product as a whole, regardless of variant. Some product attributes are mandatory based on listing policies.\nUse this API to determine the mandatory and optional attributes before listing a product.\n**Note**: It must be a [leaf category](6509c89d0fcef602bf1acd9b) that corresponds to the category tree type specified in the `category_version` property.",
"tags": [
"Products"
],
"parameters": [
{
"name": "category_id",
"in": "path",
"required": true,
"description": "The ID of the category of this product. It must be a leaf category.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "locale",
"in": "query",
"required": false,
"description": "The BCP-47 locale codes for displaying category information.\nDefault: The default locale of your shop.\nPossible values:\n- `cs-CZ`\n- `de-AT`\n- `de-BE`\n- `de-DE`\n- `el-GR`\n- `en-GB`\n- `en-IE`\n- `en-US`\n- `es-ES`\n- `es-MX`\n- `fr-FR`\n- `fr-BE`\n- `hu-HU`\n- `id-ID`\n- `it-IT`\n- `ja-JP`\n- `ms-MY`\n- `nl-NL`\n- `nl-BE`\n- `pl-PL`\n- `pt-BR`\n- `pt-PT`\n- `th-TH`\n- `vi-VN`\n- `zh-CN`",
"schema": {
"type": "string",
"enum": [
"cs-CZ",
"de-AT",
"de-BE",
"de-DE",
"el-GR",
"en-GB",
"en-IE",
"en-US",
"es-ES",
"es-MX",
"fr-FR",
"fr-BE",
"hu-HU",
"id-ID",
"it-IT",
"ja-JP",
"ms-MY",
"nl-NL",
"nl-BE",
"pl-PL",
"pt-BR",
"pt-PT",
"th-TH",
"vi-VN",
"zh-CN"
]
}
},
{
"name": "category_version",
"in": "query",
"required": false,
"description": "Filter categories by the category tree version.Possible values based on region:\n- US, EU and SEA: v2, represents the 7-level category tree. \nImportant: For US, EU and SEA shops, you must pass v2 when using this API.\n- Other regions: v1, represents the 3-level category tree.Default: v1",
"schema": {
"type": "string"
}
},
{
"name": "is_live_quick",
"in": "query",
"required": false,
"description": "false — NORMAL products\ntrue — LIVE_QUICK products. Only seller with the required permissions can creat LIVE_QUICK products.\nDefault: false",
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetCategoryAttributesResponse"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [
{
"code": "12052023",
"message": "Category does not exist"
},
{
"code": "12052024",
"message": "Category is not final category"
},
{
"code": "12052025",
"message": "The category is invalid"
},
{
"code": "12052217",
"message": "All region shops must use V2 categories. Check the documentation for further details."
},
{
"code": "12052230",
"message": "Category version and categoryID are not matched."
},
{
"code": "12052704",
"message": "seller id not exist"
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-category-attributes-202309"
}
},
"/product/202309/categories/{category_id}/global_attributes": {
"get": {
"operationId": "getGlobalAttributes",
"summary": "Get Global Attributes",
"description": "Retrieve the standard built-in product and sales attributes for listing a global product in a particular category across the seller's markets.\nProducts on TikTok Shop are grouped into categories predefined by TikTok Shop, and each category is associated with a standard set of product attributes and sales attributes.\n- **Sales attributes** (e.g. size, color, length) define product variants and are optional if your product is straightforward and has no variants.\n- **Product attributes** (e.g. manufacturer, country of origin, materials used) describe the product as a whole, regardless of variant. Some product attributes are mandatory based on listing policies.\nUse this API to determine the mandatory and optional attributes, including market-specific requirements, before listing a global product.\n**Note**: It must be a [leaf category](650a03f8f1fd3102b91b338a) that corresponds to the category tree type specified in the `category_version` property.",
"tags": [
"Products"
],
"parameters": [
{
"name": "category_id",
"in": "path",
"required": true,
"description": "The ID of the category. It must be a leaf category.",
"schema": {
"type": "string"
}
},
{
"name": "locale",
"in": "query",
"required": false,
"description": "The BCP-47 locale codes for displaying category information.\nDefault: The default locale of your shop.\nPossible values:\n- `cs-CZ`\n- `de-AT`\n- `de-BE`\n- `de-DE`\n- `el-GR`\n- `en-GB`\n- `en-IE`\n- `en-US`\n- `es-ES`\n- `es-MX`\n- `fr-FR`\n- `fr-BE`\n- `hu-HU`\n- `id-ID`\n- `it-IT`\n- `ja-JP`\n- `ms-MY`\n- `nl-NL`\n- `nl-BE`\n- `pl-PL`\n- `pt-BR`\n- `pt-PT`\n- `th-TH`\n- `vi-VN`\n- `zh-CN`",
"schema": {
"type": "string",
"enum": [
"cs-CZ",
"de-AT",
"de-BE",
"de-DE",
"el-GR",
"en-GB",
"en-IE",
"en-US",
"es-ES",
"es-MX",
"fr-FR",
"fr-BE",
"hu-HU",
"id-ID",
"it-IT",
"ja-JP",
"ms-MY",
"nl-NL",
"nl-BE",
"pl-PL",
"pt-BR",
"pt-PT",
"th-TH",
"vi-VN",
"zh-CN"
]
}
},
{
"name": "category_version",
"in": "query",
"required": false,
"description": "Filter categories by the category tree version.Possible values based on region:\n- US, EU and SEA: v2, represents the 7-level category tree. \nImportant: For US, EU and SEA shops, you must pass v2 when using this API.\n- Other regions: v1, represents the 3-level category tree.Default: v1",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetGlobalAttributesResponse"
},
"example": {
"code": 0,
"data": {
"attributes": [
{
"id": "100392",
"name": "Occasion",
"type": "PRODUCT_PROPERTY",
"is_requried": false,
"values": [
{
"id": "1001533",
"name": "Birthday"
}
],
"is_multiple_selection": false,
"is_customizable": false,
"requirement_conditions": [
{
"region": "IE",
"condition_type": "VALUE_ID_MATCH",
"attribute_id": "101610",
"attribute_value_id": "1024358"
}
],
"optional_regions": [
"US"
],
"required_regions": [
"GB",
"MY",
"PH",
"SG",
"TH",
"VN"
]
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-scenario": 2,
"x-tts-scopes": [
"Global Category Infomation"
],
"x-tts-error-codes": [
{
"code": "12052023",
"message": "Category does not exist"
},
{
"code": "12052024",
"message": "Category is not final category"
},
{
"code": "12052217",
"message": "All region shops must use V2 categories. Check the documentation for further details."
},
{
"code": "12052230",
"message": "Category version and categoryID are not matched."
},
{
"code": "12052700",
"message": "The seller is inactive."
},
{
"code": "12052704",
"message": "seller id not exist"
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-global-attributes-202309"
}
},
"/product/202309/categories/{category_id}/global_rules": {
"get": {
"operationId": "getGlobalCategoryRules",
"summary": "Get Global Category Rules",
"description": "Retrieve the additional requirements (beyond mandatory product attributes) for listing a global product in a particular category, regardless of market variations. Requirements may include product certifications, size charts, dimensions and more.\nUse this API to determine the supporting information that you must prepare before listing a global product.\n**Note**: It must be a [leaf category](650a03f8f1fd3102b91b338a) that corresponds to the category tree type specified in the `category_version` property.",
"tags": [
"Products"
],
"parameters": [
{
"name": "category_id",
"in": "path",
"required": true,
"description": "The ID of the category. It must be a leaf category.",
"schema": {
"type": "string"
}
},
{
"name": "category_version",
"in": "query",
"required": false,
"description": "Filter categories by the category tree version.Possible values based on region:\n- US, EU and SEA: v2, represents the 7-level category tree. \nImportant: For US, EU and SEA shops, you must pass v2 when using this API.\n- Other regions: v1, represents the 3-level category tree.Default: v1",
"schema": {
"type": "string"
}
},
{
"name": "locale",
"in": "query",
"required": false,
"description": "The BCP-47 locale codes for displaying category information.\nDefault: The default locale of your shop.\nPossible values:\n- `cs-CZ`\n- `de-AT`\n- `de-BE`\n- `de-DE`\n- `el-GR`\n- `en-GB`\n- `en-IE`\n- `en-US`\n- `es-ES`\n- `es-MX`\n- `fr-FR`\n- `fr-BE`\n- `hu-HU`\n- `id-ID`\n- `it-IT`\n- `ja-JP`\n- `ms-MY`\n- `nl-NL`\n- `nl-BE`\n- `pl-PL`\n- `pt-BR`\n- `pt-PT`\n- `th-TH`\n- `vi-VN`\n- `zh-CN`",
"schema": {
"type": "string",
"enum": [
"cs-CZ",
"de-AT",
"de-BE",
"de-DE",
"el-GR",
"en-GB",
"en-IE",
"en-US",
"es-ES",
"es-MX",
"fr-FR",
"fr-BE",
"hu-HU",
"id-ID",
"it-IT",
"ja-JP",
"ms-MY",
"nl-NL",
"nl-BE",
"pl-PL",
"pt-BR",
"pt-PT",
"th-TH",
"vi-VN",
"zh-CN"
]
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetGlobalCategoryRulesResponse"
},
"example": {
"code": 0,
"data": {
"product_certifications": [
{
"id": "7267563252536723205",
"name": "product_cert_name",
"is_required": false,
"sample_image_url": "https://p-boei18n.byted.org/tos-boei18n-i-jvtte31kaf/80b32f2896829eeb69d4b278c4f3aa75.jpg~tplv-jvtte31kaf-origin-jpeg.jpeg",
"required_regions": [
"GB",
"MY",
"PH",
"SG",
"TH",
"VN"
],
"optional_regions": [
"US"
],
"requirement_conditions": [
{
"region": "IE",
"condition_type": "VALUE_ID_MATCH",
"attribute_id": "101610",
"attribute_value_id": "1024358"
}
]
}
],
"size_chart": {
"is_supported": true,
"is_required": true
},
"responsible_person": {
"is_required": false,
"optional_regions": [
"IE"
],
"required_regions": [
"DE",
"ES"
]
},
"manufacturer": {
"is_required": false,
"optional_regions": [
"IE"
],
"required_regions": [
"DE",
"ES"
]
}
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-scenario": 2,
"x-tts-scopes": [
"Global Category Infomation"
],
"x-tts-error-codes": [
{
"code": "12019002",
"message": "category is invalid"
},
{
"code": "12052023",
"message": "Category does not exist"
},
{
"code": "12052024",
"message": "Category is not final category"
},
{
"code": "12052217",
"message": "All region shops must use V2 categories. Check the documentation for further details."
},
{
"code": "12052220",
"message": "This category is prohibited or unsupported on TikTok Shop. Select another category."
},
{
"code": "12052223",
"message": "This category is restricted. To sell in this category, apply through the Qualification Center in Seller Center."
},
{
"code": "12052230",
"message": "Category version and categoryID are not matched."
},
{
"code": "12052700",
"message": "The seller is inactive."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-global-category-rules-202309"
}
},
"/product/202309/categories/{category_id}/rules": {
"get": {
"operationId": "getCategoryRules",
"summary": "Get Category Rules",
"description": "Retrieve the additional requirements (beyond mandatory product attributes) for listing a product in a particular category based on your shop's location. Requirements may include product certifications, size charts, dimensions and more.\nUse this API to determine the supporting information that you must prepare before listing a product.\n**Note**: It must be a [leaf category](6509c89d0fcef602bf1acd9b) that corresponds to the category tree type specified in the `category_version` property.",
"tags": [
"Products"
],
"parameters": [
{
"name": "category_id",
"in": "path",
"required": true,
"description": "The ID of the category. It must be a leaf category.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "category_version",
"in": "query",
"required": false,
"description": "Filter categories by the category tree version.Possible values based on region:\n- US, EU and SEA: v2, represents the 7-level category tree. \nImportant: For US, EU and SEA shops, you must pass v2 when using this API.\n- Other regions: v1, represents the 3-level category tree.Default: v1",
"schema": {
"type": "string"
}
},
{
"name": "locale",
"in": "query",
"required": false,
"description": "The BCP-47 locale codes for displaying category information.\nDefault: The default locale of your shop.\nPossible values:\n- `cs-CZ`\n- `de-AT`\n- `de-BE`\n- `de-DE`\n- `el-GR`\n- `en-GB`\n- `en-IE`\n- `en-US`\n- `es-ES`\n- `es-MX`\n- `fr-FR`\n- `fr-BE`\n- `hu-HU`\n- `id-ID`\n- `it-IT`\n- `ja-JP`\n- `ms-MY`\n- `nl-NL`\n- `nl-BE`\n- `pl-PL`\n- `pt-BR`\n- `pt-PT`\n- `th-TH`\n- `vi-VN`\n- `zh-CN`",
"schema": {
"type": "string",
"enum": [
"cs-CZ",
"de-AT",
"de-BE",
"de-DE",
"el-GR",
"en-GB",
"en-IE",
"en-US",
"es-ES",
"es-MX",
"fr-FR",
"fr-BE",
"hu-HU",
"id-ID",
"it-IT",
"ja-JP",
"ms-MY",
"nl-NL",
"nl-BE",
"pl-PL",
"pt-BR",
"pt-PT",
"th-TH",
"vi-VN",
"zh-CN"
]
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetCategoryRulesResponse"
},
"example": {
"code": 0,
"data": {
"product_certifications": [
{
"id": "602362",
"name": "SNI Certificate",
"is_required": true,
"document_details": "Upload a user manual or instructions in the official local language.\n\nWhere there are multiple items sold as a part of a bundle, please clearly indicate which specific product the certification pertains to in the uploaded file or image.",
"sample_image_url": "https://p-boei18n.byted.org/tos-boei18n-i-jvtte31kaf/80b32f2896829eeb69d4b278c4f3aa75.jpg~tplv-jvtte31kaf-origin-jpeg.jpeg",
"requirement_conditions": [
{
"condition_type": "VALUE_ID_MATCH",
"attribute_id": "101610",
"attribute_value_id": "1024358"
}
],
"expiration_date": {
"is_required": true
}
}
],
"size_chart": {
"is_supported": true,
"is_required": true,
"measurement_and_options": [
{
"measurement_type": "BODY_MEASUREMENTS",
"options": [
{
"name": "Bust",
"id": "size_chart_option_bust",
"role": "KEY",
"unit": "LENGTH",
"metric_value_range": [
"70",
"160"
],
"imperial_value_range": [
"27.5",
"63"
]
}
]
}
],
"size_types": [
"size_chart_size_type_regular",
"size_chart_size_type_petite"
]
},
"cod": {
"is_supported": true
},
"package_dimension": {
"is_required": true
},
"epr": {
"is_required": false
},
"responsible_person": {
"is_required": false
},
"manufacturer": {
"is_required": false
},
"allowed_special_product_types": [
"PRE_ORDER"
],
"fees": [
{
"type": "PFAND",
"is_required": true
}
],
"seller_sku": {
"is_required": true
}
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [
{
"code": "12052023",
"message": "Category does not exist"
},
{
"code": "12052024",
"message": "Category is not final category"
},
{
"code": "12052217",
"message": "All region shops must use V2 categories. Check the documentation for further details."
},
{
"code": "12052220",
"message": "This category is prohibited or unsupported on TikTok Shop. Select another category."
},
{
"code": "12052223",
"message": "This category is restricted. To sell in this category, apply through the Qualification Center in Seller Center."
},
{
"code": "12052226",
"message": "This category is restricted. To sell in this category, apply through the Qualification Center in Seller Center."
},
{
"code": "12052230",
"message": "Category version and categoryID are not matched."
},
{
"code": "12052446",
"message": "Category is not open in this market"
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-category-rules-202309"
}
},
"/product/202309/files/upload": {
"post": {
"operationId": "uploadProductFile",
"summary": "Upload Product File",
"description": "Upload non-image files, such as PDF or video to TikTok Shop. \nUse this API when you need to add videos to your product to improve the shopping experience, or submit certifications or reports to meet TikTok Shop requirements for listing restricted products. \n**Note**: Retain the file ID from the response and pass it when creating or editing a product to associate the file with the product.",
"tags": [
"Products"
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/UploadProductFileRequest"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadProductFileResponse"
},
"example": {
"code": 0,
"data": {
"id": "v09e40f40000cfu0ovhc77ub7fl97k4w",
"url": "https://p-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe\n",
"name": "SNI.PDF",
"format": "PDF"
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-scenario": 2,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [
{
"code": "12019103",
"message": "Couldn't upload file, the file is empty."
},
{
"code": "12019104",
"message": "The file name is empty."
},
{
"code": "12019105",
"message": "Failed to process the file. The format or content is not supported."
},
{
"code": "12019122",
"message": "The video ratio must be between 9:16 and 16:9."
},
{
"code": "12038002",
"message": "Invalid upload file. Please ensure you are passing the correct file data."
},
{
"code": "12038004",
"message": "Failed to process the image. The format or content is not supported."
},
{
"code": "12038005",
"message": "The file size exceeds the maximum allowed size."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/upload-product-file-202309"
}
},
"/product/202309/global_categories": {
"get": {
"operationId": "getGlobalCategories",
"summary": "Get Global Categories",
"description": "Retrieve all available product categories, regardless of market variations.\nProduct categories are updated frequently, so it's recommended to call the API in real time to ensure you are using the latest category data. Caching category data locally may result in using outdated information, leading to errors when creating global products.",
"tags": [
"Products"
],
"parameters": [
{
"name": "locale",
"in": "query",
"required": false,
"description": "The BCP-47 locale codes for displaying category information.\nDefault: The default locale of your shop.\nPossible values:\n- `cs-CZ`\n- `de-AT`\n- `de-BE`\n- `de-DE`\n- `el-GR`\n- `en-GB`\n- `en-IE`\n- `en-US`\n- `es-ES`\n- `es-MX`\n- `fr-FR`\n- `fr-BE`\n- `hu-HU`\n- `id-ID`\n- `it-IT`\n- `ja-JP`\n- `ms-MY`\n- `nl-NL`\n- `nl-BE`\n- `pl-PL`\n- `pt-BR`\n- `pt-PT`\n- `th-TH`\n- `vi-VN`\n- `zh-CN`",
"schema": {
"type": "string",
"enum": [
"cs-CZ",
"de-AT",
"de-BE",
"de-DE",
"el-GR",
"en-GB",
"en-IE",
"en-US",
"es-ES",
"es-MX",
"fr-FR",
"fr-BE",
"hu-HU",
"id-ID",
"it-IT",
"ja-JP",
"ms-MY",
"nl-NL",
"nl-BE",
"pl-PL",
"pt-BR",
"pt-PT",
"th-TH",
"vi-VN",
"zh-CN"
]
}
},
{
"name": "keyword",
"in": "query",
"required": false,
"description": "Filter categories by this keyword in `local_name`.",
"schema": {
"type": "string"
}
},
{
"name": "category_version",
"in": "query",
"required": false,
"description": "Filter categories by the category tree version.Possible values based on region:\n- US, EU and SEA: v2, represents the 7-level category tree. \nImportant: For US, EU and SEA shops, you must pass v2 when using this API.\n- Other regions: v1, represents the 3-level category tree.Default: v1",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetGlobalCategoriesResponse"
},
"example": {
"code": 0,
"data": {
"categories": [
{
"id": "600001",
"parent_id": "0",
"local_name": "Home Supplies",
"is_leaf": false,
"permission_statuses": [
"AVAILABLE"
]
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-scenario": 2,
"x-tts-scopes": [
"Global Category Infomation"
],
"x-tts-error-codes": [
{
"code": "12052023",
"message": "Category does not exist"
},
{
"code": "12052217",
"message": "All region shops must use V2 categories. Check the documentation for further details."
},
{
"code": "12052230",
"message": "Category version and categoryID are not matched."
},
{
"code": "12052700",
"message": "The seller is inactive."
},
{
"code": "12052704",
"message": "seller id not exist"
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-global-categories-202309"
}
},
"/product/202309/global_categories/recommend": {
"post": {
"operationId": "recommendGlobalCategories",
"summary": "Recommend Global Categories",
"description": "Retrieve a recommended leaf category and its category hierarchy for a candidate global product based on its title, description, and images.\nIf you are syncing product catalogs from an external system to TikTok Shop, use this API to facilitate product classification.\n**Note**: Double-byte characters (e.g. Chinese characters) are not supported in text fields such as descriptions and titles. If you include them, the API request will fail.",
"tags": [
"Products"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecommendGlobalCategoriesRequest"
},
"example": {
"product_title": "Men's Fashion Sports Low Cut Cotton Breathable Ankle Short",
"description": "Please check the measurements before purchase.
\n \n ",
"images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
],
"category_version": "v1"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecommendGlobalCategoriesResponse"
},
"example": {
"code": 0,
"data": {
"leaf_category_id": "605254",
"categories": [
{
"id": "605254",
"name": "Christmas Gifts",
"level": 3,
"is_leaf": true
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-scenario": 2,
"x-tts-scopes": [
"Global Category Infomation"
],
"x-tts-error-codes": [
{
"code": "12019006",
"message": "product description is invalid"
},
{
"code": "12019009",
"message": "product image list is invalid"
},
{
"code": "12019064",
"message": "No matching categories. Provide the full name of your product, edit its product properties, and try again."
},
{
"code": "12052013",
"message": "The product description cannot exceed maximum characters"
},
{
"code": "12052051",
"message": "The product name exceed max limit characters"
},
{
"code": "12052056",
"message": "The num of image in description cannot exceed max limit"
},
{
"code": "12052217",
"message": "All region shops must use V2 categories. Check the documentation for further details."
},
{
"code": "12052230",
"message": "Category version and categoryID are not matched."
},
{
"code": "12052261",
"message": "product name is empty"
},
{
"code": "12052262",
"message": "Chinese characters are not supported in product name"
},
{
"code": "12052266",
"message": "The product name contains non-English characters."
},
{
"code": "12052301",
"message": "Width and length of main image must be at least {{min_limit}}, check uri {{uri}}"
},
{
"code": "12052305",
"message": "The main images aspect ratio cannot exceed max limit."
},
{
"code": "12052306",
"message": "main product images count exceed limit"
},
{
"code": "12052340",
"message": "product description image uri illegal"
},
{
"code": "12052345",
"message": "The product description html tag not support."
},
{
"code": "12052346",
"message": "The product description has Chinese characters"
},
{
"code": "12052348",
"message": "The product description html tag required attribute is miss."
},
{
"code": "12052349",
"message": "The product description html tag not support nest."
},
{
"code": "12052350",
"message": "The product description html tag contain illegal attribute."
},
{
"code": "12052351",
"message": "The product description contains non-English characters."
},
{
"code": "12052700",
"message": "The seller is inactive."
},
{
"code": "12052704",
"message": "seller id not exist"
},
{
"code": "12052722",
"message": "The image URI does not exist in TikTok Shop."
},
{
"code": "12052912",
"message": "No matching category found within your account's main category. Check your main category in the seller profile on Seller Center and ensure your product falls within its scope."
},
{
"code": "12052931",
"message": "The title must follow these formatting rules: it cannot contain HTML escape characters (e.g., ), emojis, or ASCII control characters (e.g., \\u007F). It also cannot consist solely of symbols (e.g., //// or !@#$$$&), nor can it have more than 9 consecutive repeated characters (e.g., aaaaaaaaa or 111111111)."
},
{
"code": "12056001",
"message": "System error, try again later"
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/recommend-global-categories-202309"
}
},
"/product/202309/global_products": {
"post": {
"operationId": "createGlobalProduct",
"summary": "Create Global Product",
"description": "Create global products to be sold in one or multiple shops outside of the seller's base country.\nYou can only create global products in `AVAILABLE` product categories. For other categories, contact your account manager for assistance. After product creation, use the [Publish Global Product API](https://partner.tiktokshop.com/docv2/page/650a64d6defece02be678fd6) to publish and translate the product in the desired markets.\n**Key concept**: Global products are products created by cross-border sellers to be sold in shops outside of their base country. With global products, cross-border sellers operating across multiple markets can avoid creating the same product for each shop individually. Instead, they just need to create a single global product, which can be published and synced to all their shops, simplifying product management across markets.\n**Note**:\n- This API is applicable only for intra-EU sellers and global sellers. To create and list local products intended for sale exclusively in local shops, use the [Create Product API](https://partner.tiktokshop.com/docv2/page/6502fc8da57708028b42b18a) instead.\n- There may be a limit to the number of products you can list per day. We recommend prioritizing the creation of key products first to ensure they get published. You can find your listing limit on the Seller Center homepage.\n- The language used in the product content must align with the target market's language (e.g. don't use Chinese), otherwise the listing will fail or be rejected.",
"tags": [
"Products"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateGlobalProductRequest"
},
"example": {
"title": "Men's Fashion Sports Low Cut Cotton Breathable Ankle Short Boat Invisible Socks\n",
"description": " ",
"category_id": "600001",
"brand_id": "7082427311584347905",
"main_images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
],
"skus": [
{
"global_quantity": 999,
"sales_attributes": [
{
"id": "100089",
"name": "Color",
"value_id": "1729592969712207000\n",
"value_name": "Red",
"sku_img": {
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe\n"
}
}
],
"seller_sku": "XL-COLOR-RED-001",
"price": {
"amount": "999",
"currency": "USD"
},
"identifier_code": {
"code": "10000000000000",
"type": "GTIN"
},
"inventory": [
{
"global_warehouse_id": "7068517275539719942",
"quantity": 999
}
],
"sku_unit_count": "1",
"extra_identifier_codes": [
"10000000000000"
],
"external_global_sku_id": "1234567890"
}
],
"package_weight": {
"value": "1.31",
"unit": "KILOGRAM"
},
"certifications": [
{
"id": "7182427311584347905",
"images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
],
"files": [
{
"id": "v09ea0g40000cj91373c77u3mid3g1s0",
"name": "SNI.PDF",
"format": "PDF"
}
]
}
],
"package_dimensions": {
"length": "10",
"width": "10",
"height": "10",
"unit": "CENTIMETER"
},
"product_attributes": [
{
"id": "100392",
"values": [
{
"id": "1001533",
"name": "Steel"
}
]
}
],
"size_chart": {
"image": {
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
},
"template": {
"id": "7267563252536723205"
}
},
"video": {
"id": "v09e40f40000cfu0ovhc77ub7fl97k4w"
},
"manufacturer": {
"name": "Sample Manufacturer Name",
"address": "123W 106th St, New York, NY, USA, 10025",
"phone_number": "+1-2124108036",
"email": "samplemanufacturer101@outlook.com"
},
"category_version": "v1",
"responsible_person_ids": [
"67726293bf1eb1e92401a"
],
"manufacturer_ids": [
"67726293bf1eb1e92401a"
],
"source_locale": "de-DE",
"external_global_product_id": "123456789"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateGlobalProductResponse"
},
"example": {
"code": 0,
"data": {
"global_product_id": "1729592969712207008",
"global_skus": [
{
"id": "1729592969712207012",
"seller_sku": "Color-Red-XM001",
"sales_attributes": [
{
"id": "100000",
"value_id": "1729592969712207123"
}
],
"external_global_sku_id": "1234567890"
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-scenario": 2,
"x-tts-scopes": [
"Global Product Modify"
],
"x-tts-error-codes": [
{
"code": "12019006",
"message": "product description is invalid"
},
{
"code": "12019011",
"message": "product package weight is invalid"
},
{
"code": "12019013",
"message": "brand id is invalid"
},
{
"code": "12019030",
"message": "property is invalid"
},
{
"code": "12019064",
"message": "No matching categories. Provide the full name of your product, edit its product properties, and try again."
},
{
"code": "12019117",
"message": "Missing variations (sales attributes). When there are multiple SKUs in a product, each SKU must include variation (sales attribute) details that explain how it is different from other SKUs in the product."
},
{
"code": "12052012",
"message": "Incorrect price format"
},
{
"code": "12052013",
"message": "The product description cannot exceed maximum characters"
},
{
"code": "12052015",
"message": "The product description is required"
},
{
"code": "12052016",
"message": "The parcel weight is required"
},
{
"code": "12052023",
"message": "Category does not exist"
},
{
"code": "12052024",
"message": "Category is not final category"
},
{
"code": "12052026",
"message": "Brand does not exist"
},
{
"code": "12052028",
"message": "Main product image is required"
},
{
"code": "12052048",
"message": "You cannot edit the specified product(s) as it isn't listed in your account or shop."
},
{
"code": "12052050",
"message": "A single product cannot have more than 100 different SKUs"
},
{
"code": "12052051",
"message": "The product name exceed max limit characters"
},
{
"code": "12052054",
"message": "The seller SKU text length cannot exceed max limit characters"
},
{
"code": "12052055",
"message": "The SKU inventory quantity for the warehouse must be within allowed limits."
},
{
"code": "12052056",
"message": "The num of image in description cannot exceed max limit"
},
{
"code": "12052073",
"message": "The product price is invalid"
},
{
"code": "12052084",
"message": "The provided currency is not available for this shop/region."
},
{
"code": "12052096",
"message": "Unable to update the price for SKUs with no warehouse. Assign a warehouse and try again."
},
{
"code": "12052104",
"message": "property is required"
},
{
"code": "12052105",
"message": "required qualification miss"
},
{
"code": "12052116",
"message": "product package size is invalid"
},
{
"code": "12052128",
"message": "Size chart not found"
},
{
"code": "12052142",
"message": "no permission of multi global warehouse"
},
{
"code": "12052143",
"message": "sku warehouse must equal"
},
{
"code": "12052200",
"message": "brand is expired"
},
{
"code": "12052201",
"message": "You are not authorized to sell this brand in this category. To do so, apply through the Qualification Center in Seller Center."
},
{
"code": "12052208",
"message": "A brand authorization is required to publish this listing."
},
{
"code": "12052217",
"message": "All region shops must use V2 categories. Check the documentation for further details."
},
{
"code": "12052220",
"message": "This category is prohibited or unsupported on TikTok Shop. Select another category."
},
{
"code": "12052221",
"message": "Only whitelisted sellers are permitted to trade under current category"
},
{
"code": "12052222",
"message": "category do not support cod"
},
{
"code": "12052225",
"message": "You are not authorized to sell in this category because it does not fall under your shop's main category. Contact your account manager for help or select another category."
},
{
"code": "12052226",
"message": "This category is restricted. To sell in this category, apply through the Qualification Center in Seller Center."
},
{
"code": "12052227",
"message": "the category is unauthorized or unavailable"
},
{
"code": "12052230",
"message": "Category version and categoryID are not matched."
},
{
"code": "12052240",
"message": "Do not support custom property."
},
{
"code": "12052241",
"message": "attribute name or attribute id is empty."
},
{
"code": "12052242",
"message": "The attribute name characters cannot exceed max_limit"
},
{
"code": "12052243",
"message": "The product attribute or sale attribute name characters contain Chinese."
},
{
"code": "12052244",
"message": "The attribute name duplicate."
},
{
"code": "12052245",
"message": "The product attributes contained invalid characters. Please modify and re-submit."
},
{
"code": "12052246",
"message": "The {{property_type}} not support multi selected, attribute id is :{{property_id}}."
},
{
"code": "12052247",
"message": "Do not support custom product attribute."
},
{
"code": "12052248",
"message": "The {{property_type}} value name or attribute value id is empty."
},
{
"code": "12052249",
"message": "The {{property_type}} value name characters cannot exceed {{max_limit}}, attribute value name is :{{property_value_name}}."
},
{
"code": "12052250",
"message": "The {{property_type}} value name characters contain Chinese."
},
{
"code": "12052251",
"message": "Duplicated attribute values found for an attribute. Remove or modify the duplicated value."
},
{
"code": "12052254",
"message": "Duplicate attribute id"
},
{
"code": "12052260",
"message": "The product ID does not exist"
},
{
"code": "12052261",
"message": "product name is empty"
},
{
"code": "12052262",
"message": "Chinese characters are not supported in product name"
},
{
"code": "12052266",
"message": "The product name contains non-English characters."
},
{
"code": "12052282",
"message": "Product manufacturer is required."
},
{
"code": "12052285",
"message": "Manufacturer ID {{manufacturer_id}} is not associated with the seller"
},
{
"code": "12052287",
"message": "Product responsible person is required"
},
{
"code": "12052288",
"message": "The number of responsible person ids cannot exceed {{max_limit}}, and cannot less {{min_limit}}."
},
{
"code": "12052290",
"message": "Responsible person ID {{rp_id}} is not associated with the seller"
},
{
"code": "12052293",
"message": "When identifier code is not filled in, extra identification code is not allowed to be filled in."
},
{
"code": "12052295",
"message": "Duplicate manufacturer IDs associated with the same product"
},
{
"code": "12052296",
"message": "Duplicate responsible person IDs associated with the same product"
},
{
"code": "12052300",
"message": "product main image uri illegal"
},
{
"code": "12052301",
"message": "Width and length of main image must be at least {{min_limit}}, check uri {{uri}}"
},
{
"code": "12052302",
"message": "The main images size exceed limit."
},
{
"code": "12052304",
"message": "Main product image format not support."
},
{
"code": "12052305",
"message": "The main images aspect ratio cannot exceed max limit."
},
{
"code": "12052306",
"message": "main product images count exceed limit"
},
{
"code": "12052324",
"message": "Product description image file format is not supported"
},
{
"code": "12052340",
"message": "product description image uri illegal"
},
{
"code": "12052341",
"message": "The description images size cannot exceed limit."
},
{
"code": "12052342",
"message": "The description images space cannot exceed limit."
},
{
"code": "12052343",
"message": "Product description image format not support."
},
{
"code": "12052344",
"message": "The product description html syntax with error"
},
{
"code": "12052345",
"message": "The product description html tag not support."
},
{
"code": "12052346",
"message": "The product description has Chinese characters"
},
{
"code": "12052348",
"message": "The product description html tag required attribute is miss."
},
{
"code": "12052349",
"message": "The product description html tag not support nest."
},
{
"code": "12052350",
"message": "The product description html tag contain illegal attribute."
},
{
"code": "12052351",
"message": "The product description contains non-English characters."
},
{
"code": "12052352",
"message": "The product description nest exceeding limit"
},
{
"code": "12052360",
"message": "The video id is not exist."
},
{
"code": "12052401",
"message": "package weight exceed limit."
},
{
"code": "12052520",
"message": "product sale property image uri illegal"
},
{
"code": "12052521",
"message": "The sale property images size over limit."
},
{
"code": "12052522",
"message": "Product sale property image is required"
},
{
"code": "12052523",
"message": "Product sale property image format not support."
},
{
"code": "12052524",
"message": "The sale property image aspect ratio invalid"
},
{
"code": "12052525",
"message": "The attribute max num cannot exceed 3."
},
{
"code": "12052526",
"message": "The attribute value max num over limit."
},
{
"code": "12052527",
"message": "The sale attribute id not exist."
},
{
"code": "12052528",
"message": "You can add images to only 1 product variation, which will serve as the primary variation for display in the product options gallery."
},
{
"code": "12052529",
"message": "The property value id not exist."
},
{
"code": "12052530",
"message": "The warehouse ' {{warehouse ID}} ' does not belong to this shop/seller."
},
{
"code": "12052531",
"message": "The warehouse is disabled."
},
{
"code": "12052550",
"message": "SKU property must contain all properties"
},
{
"code": "12052554",
"message": "sku name contain Chinese characters"
},
{
"code": "12052570",
"message": "product price exceed limit"
},
{
"code": "12052574",
"message": "unit price config is invalid"
},
{
"code": "12052591",
"message": "Invalid number of digits of identifier code"
},
{
"code": "12052592",
"message": "Identifier code already entered, cannot enter the same code twice"
},
{
"code": "12052598",
"message": "Only the last digit supports input X"
},
{
"code": "12052600",
"message": "The identifier code type must be selected"
},
{
"code": "12052650",
"message": "product qualification image uri illegal"
},
{
"code": "12052656",
"message": "qualification id duplicate"
},
{
"code": "12052657",
"message": "qualification image and pdf file is out of limit."
},
{
"code": "12052670",
"message": "The size chart image URI is invalid. Note: API users must use the URI generated by the Upload Product Image API."
},
{
"code": "12052671",
"message": "The sizechart images size over limit."
},
{
"code": "12052673",
"message": "Product sizechart image is required"
},
{
"code": "12052700",
"message": "The seller is inactive."
},
{
"code": "12052701",
"message": "do not support cross-boarder seller create local product directly"
},
{
"code": "12052702",
"message": "seller does not support pre-order"
},
{
"code": "12052703",
"message": "Invalid seller tax number"
},
{
"code": "12052704",
"message": "seller id not exist"
},
{
"code": "12052910",
"message": "Invalid input parameters. Refer to the API documentation for details."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/create-global-product-202309"
},
"delete": {
"operationId": "deleteGlobalProducts",
"summary": "Delete Global Products",
"description": "Delete global products that you no longer need.",
"tags": [
"Products"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteGlobalProductsRequest"
},
"example": {
"global_product_ids": [
"1729715829872102020",
"1729715829872036484"
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteGlobalProductsResponse"
},
"example": {
"code": 0,
"data": {
"errors": [
{
"message": "Seller has no permission.",
"code": 12019114,
"detail": {
"global_product_id": "1729715829872102020"
}
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-scenario": 2,
"x-tts-scopes": [
"Global Product Delete"
],
"x-tts-error-codes": [
{
"code": "12019008",
"message": "Product id is invalid"
},
{
"code": "12019114",
"message": "Seller has no permission"
},
{
"code": "12019120",
"message": "The number of provided product IDs exceeds the limit."
},
{
"code": "12019150",
"message": "The product ID does not exist."
},
{
"code": "12052700",
"message": "The seller is inactive."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/delete-global-products-202309"
}
},
"/product/202309/global_products/{global_product_id}": {
"get": {
"operationId": "getGlobalProduct",
"summary": "Get Global Product",
"description": "Retrieve all properties of a global product that is in the \"DRAFT\", \"UNPUBLISHED\", or \"PUBLISHED\" status, and the corresponding local product IDs in the published markets.",
"tags": [
"Products"
],
"parameters": [
{
"name": "global_product_id",
"in": "path",
"required": true,
"description": "Global product ID",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetGlobalProductResponse"
},
"example": {
"code": 0,
"data": {
"id": "1729592969712207008",
"title": "Short Boat Invisible Socks",
"main_images": [
{
"height": 600,
"width": 600,
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
],
"video": {
"id": "v09ea0g40000cj91373c77u3mid3g1s0"
},
"description": " ",
"package_dimensions": {
"length": "10",
"width": "10",
"height": "10",
"unit": "CENTIMETER"
},
"package_weight": {
"value": "1.32",
"unit": "KILOGRAM"
},
"certifications": [
{
"id": "7267563252536723205",
"title": "SNI Certificate",
"files": [
{
"id": "v09ea0g40000cj91373c77u3mid3g1s0",
"urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
],
"name": "SNI.PDF",
"format": "PDF"
}
],
"images": [
{
"height": 600,
"width": 600,
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
]
}
],
"skus": [
{
"id": "1729592969712207234",
"seller_sku": "Color-Red-XM001",
"price": {
"amount": "1.01",
"currency": "USD",
"unit_price": "1.00"
},
"global_quantity": 100,
"identifier_code": {
"code": "10000000000010",
"type": "GTIN"
},
"sales_attributes": [
{
"id": "100000",
"name": "Color",
"value_id": "7267563252536723205",
"value_name": "Red\n",
"sku_img": {
"height": 600,
"width": 600,
"thumb_urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
],
"uri": "tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4",
"urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
]
}
}
],
"inventory": [
{
"global_warehouse_id": "6966568648651605766",
"quantity": 100
}
],
"sku_unit_count": "100.00",
"extra_identifier_codes": [
"12345678901234"
],
"external_global_sku_id": "1234567890"
}
],
"update_time": 1694522875,
"create_time": 1694522875,
"product_attributes": [
{
"id": "100392",
"name": "Occasion",
"values": [
{
"id": "1001533",
"name": "Birthday"
}
]
}
],
"size_chart": {
"image": {
"height": 600,
"width": 600,
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
},
"template": {
"id": "7267563252536723205"
}
},
"products": [
{
"region": "GB",
"id": "1729592969712207922",
"sku_mappings": [
{
"global_sku_id": "1729592969712207234",
"local_sku_id": "1729592969712207230",
"sales_attribute_mappings": [
{
"global_attribute_id": "100000",
"local_attribute_id": "100000",
"global_value_id": "1001064",
"local_value_id": "1001064"
}
]
}
]
}
],
"global_seller_id": "7494083603082020484",
"brand": {
"id": "7082427311584347905"
},
"category": {
"id": "600002"
},
"manufacturer": {
"name": "Sample Manufacturer Name",
"address": "123W 106th St, New York, NY, USA, 10025",
"phone_number": "+1-2124108036",
"email": "samplemanufacturer101@outlook.com\n"
},
"responsible_person_ids": [
"67726293bf1eb1e92401a"
],
"manufacturer_ids": [
"67726293bf1eb1e92401a"
],
"source_locale": "fr-FR",
"external_global_product_id": "123456789"
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-scenario": 2,
"x-tts-scopes": [
"Global Product Information"
],
"x-tts-error-codes": [
{
"code": "12052032",
"message": "The product does not exist"
},
{
"code": "12052048",
"message": "You cannot edit the specified product(s) as it isn't listed in your account or shop."
},
{
"code": "12052260",
"message": "The product ID does not exist"
},
{
"code": "12052901",
"message": "The product in its current status is not available for this operation. Change the product status and try again."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-global-product-202309"
},
"put": {
"operationId": "editGlobalProduct",
"summary": "Edit Global Product",
"description": "Edit all properties (e.g. description, brand, images, attributes) of a global product.\n**IMPORTANT**: For published products, the changes will be automatically retranslated and synced to all markets where the product is published. If you have already edited the product information or translations of the associated local products, they will be overwritten by the information in this API. For example, if you have customized the local prices such as the local pre-tax price or the local display price, they will be overwritten each time this API is called.\n**Note**:\n- There may be a limit to the number of products you can relist per day. We recommend prioritizing key products first to ensure they get published. You can find your listing limit on the Seller Center homepage.\n- All inputs, including blanks, in the request payload will overwrite existing values. To retain an existing value, make sure to include it in your request. Therefore, **it is strongly recommended to retrieve the latest product data using [Get Global Product](6509e2b0bace3e02b7490c96) and submit the complete data when editing**. This ensures accuracy and helps avoid errors or unintentional data loss due to missing fields.\n- The language used in the product content must align with the target market's language (e.g. don't use Chinese), otherwise the listing will fail or be rejected.",
"tags": [
"Products"
],
"parameters": [
{
"name": "global_product_id",
"in": "path",
"required": true,
"description": "The global product ID generated by TikTok Shop.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EditGlobalProductRequest"
},
"example": {
"title": "Men's Fashion Sports Low Cut Cotton Breathable Ankle Short Boat Invisible Socks",
"description": " ",
"category_id": "600001",
"brand_id": "7082427311584347905",
"main_images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
],
"skus": [
{
"id": "1782427311584347905",
"global_quantity": 999,
"seller_sku": "Color-Red-XM01",
"price": {
"amount": "1.32",
"currency": "USD"
},
"sales_attributes": [
{
"id": "100089",
"name": "Specification",
"value_id": "1729592969712207000",
"value_name": "XL",
"sku_img": {
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
}
],
"inventory": [
{
"global_warehouse_id": "7068517275539719942",
"quantity": 999
}
],
"identifier_code": {
"code": "10000000000000",
"type": "GTIN"
},
"sku_unit_count": "1",
"extra_identifier_codes": [
"12345678901234"
],
"external_global_sku_id": "1234567890",
"sale_prices": [
{
"region": "US",
"amount": "100"
}
]
}
],
"package_weight": {
"value": "1.99",
"unit": "KILOGRAM"
},
"certifications": [
{
"id": "7182427311584347905",
"images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
],
"files": [
{
"id": "v09ea0g40000cj91373c77u3mid3g1s0",
"name": "SNI.PDF",
"format": "PDF"
}
]
}
],
"package_dimensions": {
"length": "10",
"width": "10",
"height": "10",
"unit": "CENTIMETER"
},
"product_attributes": [
{
"id": "100392",
"values": [
{
"id": "1001533",
"name": "Birthday"
}
]
}
],
"size_chart": {
"image": {
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
},
"template": {
"id": "7267563252536723205"
}
},
"video": {
"id": "v09e40f40000cfu0ovhc77ub7fl97k4w"
},
"manufacturer": {
"name": "Sample Manufacturer Name",
"address": "123W 106th St, New York, NY, USA, 10025",
"phone_number": "+1-2124108036\n",
"email": "samplemanufacturer101@outlook.com"
},
"manufacturer_ids": [
"67726293bf1eb1e92401a"
],
"responsible_person_ids": [
"67726293bf1eb1e92401a"
],
"category_version": "v1",
"external_global_product_id": "123456789"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EditGlobalProductResponse"
},
"example": {
"code": 0,
"data": {
"global_skus": [
{
"id": "1729592969712207012",
"seller_sku": "Color-Red-XM01",
"sales_attributes": [
{
"id": "100000",
"value_id": "1729592969712207123"
}
],
"external_global_sku_id": "1234567890"
}
],
"publish_results": [
{
"region": "MY",
"status": "SUCCESS",
"fail_reasons": [
{
"message": "The publish region is inactive."
}
]
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-scenario": 2,
"x-tts-scopes": [
"Global Product Modify"
],
"x-tts-error-codes": [
{
"code": "12019010",
"message": "product price is invalid"
},
{
"code": "12019011",
"message": "product package weight is invalid"
},
{
"code": "12019013",
"message": "brand id is invalid"
},
{
"code": "12019016",
"message": "Unable to publish or sync products to target markets due to missing or invalid warehouse details."
},
{
"code": "12019064",
"message": "No matching categories. Provide the full name of your product, edit its product properties, and try again."
},
{
"code": "12019113",
"message": "product status is invalid"
},
{
"code": "12019114",
"message": "Seller has no permission"
},
{
"code": "12019117",
"message": "Missing variations (sales attributes). When there are multiple SKUs in a product, each SKU must include variation (sales attribute) details that explain how it is different from other SKUs in the product."
},
{
"code": "12019121",
"message": "calculate price error"
},
{
"code": "12019150",
"message": "The product ID does not exist."
},
{
"code": "12052012",
"message": "Incorrect price format"
},
{
"code": "12052013",
"message": "The product description cannot exceed maximum characters"
},
{
"code": "12052015",
"message": "The product description is required"
},
{
"code": "12052016",
"message": "The parcel weight is required"
},
{
"code": "12052023",
"message": "Category does not exist"
},
{
"code": "12052024",
"message": "Category is not final category"
},
{
"code": "12052026",
"message": "Brand does not exist"
},
{
"code": "12052028",
"message": "Main product image is required"
},
{
"code": "12052048",
"message": "You cannot edit the specified product(s) as it isn't listed in your account or shop."
},
{
"code": "12052050",
"message": "A single product cannot have more than 100 different SKUs"
},
{
"code": "12052051",
"message": "The product name exceed max limit characters"
},
{
"code": "12052054",
"message": "The seller SKU text length cannot exceed max limit characters"
},
{
"code": "12052055",
"message": "The SKU inventory quantity for the warehouse must be within allowed limits."
},
{
"code": "12052056",
"message": "The num of image in description cannot exceed max limit"
},
{
"code": "12052073",
"message": "The product price is invalid"
},
{
"code": "12052084",
"message": "The provided currency is not available for this shop/region."
},
{
"code": "12052096",
"message": "Unable to update the price for SKUs with no warehouse. Assign a warehouse and try again."
},
{
"code": "12052104",
"message": "property is required"
},
{
"code": "12052105",
"message": "required qualification miss"
},
{
"code": "12052116",
"message": "product package size is invalid"
},
{
"code": "12052142",
"message": "no permission of multi global warehouse"
},
{
"code": "12052143",
"message": "sku warehouse must equal"
},
{
"code": "12052145",
"message": "activity warehouse not allowed to be deleted"
},
{
"code": "12052146",
"message": "The specified inventory quantity is too low. It must be greater than the locked quantity (e.g. for committed orders, campaigns, creators) to ensure a non-negative available stock."
},
{
"code": "12052200",
"message": "brand is expired"
},
{
"code": "12052201",
"message": "You are not authorized to sell this brand in this category. To do so, apply through the Qualification Center in Seller Center."
},
{
"code": "12052208",
"message": "A brand authorization is required to publish this listing."
},
{
"code": "12052217",
"message": "All region shops must use V2 categories. Check the documentation for further details."
},
{
"code": "12052220",
"message": "This category is prohibited or unsupported on TikTok Shop. Select another category."
},
{
"code": "12052221",
"message": "Only whitelisted sellers are permitted to trade under current category"
},
{
"code": "12052222",
"message": "category do not support cod"
},
{
"code": "12052225",
"message": "You are not authorized to sell in this category because it does not fall under your shop's main category. Contact your account manager for help or select another category."
},
{
"code": "12052226",
"message": "This category is restricted. To sell in this category, apply through the Qualification Center in Seller Center."
},
{
"code": "12052227",
"message": "the category is unauthorized or unavailable"
},
{
"code": "12052230",
"message": "Category version and categoryID are not matched."
},
{
"code": "12052240",
"message": "Do not support custom property."
},
{
"code": "12052241",
"message": "attribute name or attribute id is empty."
},
{
"code": "12052242",
"message": "The attribute name characters cannot exceed max_limit"
},
{
"code": "12052243",
"message": "The product attribute or sale attribute name characters contain Chinese."
},
{
"code": "12052244",
"message": "The attribute name duplicate."
},
{
"code": "12052245",
"message": "The product attributes contained invalid characters. Please modify and re-submit."
},
{
"code": "12052246",
"message": "The {{property_type}} not support multi selected, attribute id is :{{property_id}}."
},
{
"code": "12052247",
"message": "Do not support custom product attribute."
},
{
"code": "12052248",
"message": "The {{property_type}} value name or attribute value id is empty."
},
{
"code": "12052249",
"message": "The {{property_type}} value name characters cannot exceed {{max_limit}}, attribute value name is :{{property_value_name}}."
},
{
"code": "12052250",
"message": "The {{property_type}} value name characters contain Chinese."
},
{
"code": "12052251",
"message": "Duplicated attribute values found for an attribute. Remove or modify the duplicated value."
},
{
"code": "12052254",
"message": "Duplicate attribute id"
},
{
"code": "12052260",
"message": "The product ID does not exist"
},
{
"code": "12052261",
"message": "product name is empty"
},
{
"code": "12052262",
"message": "Chinese characters are not supported in product name"
},
{
"code": "12052266",
"message": "The product name contains non-English characters."
},
{
"code": "12052282",
"message": "Product manufacturer is required."
},
{
"code": "12052285",
"message": "Manufacturer ID {{manufacturer_id}} is not associated with the seller"
},
{
"code": "12052287",
"message": "Product responsible person is required"
},
{
"code": "12052288",
"message": "The number of responsible person ids cannot exceed {{max_limit}}, and cannot less {{min_limit}}."
},
{
"code": "12052290",
"message": "Responsible person ID {{rp_id}} is not associated with the seller"
},
{
"code": "12052296",
"message": "Duplicate responsible person IDs associated with the same product"
},
{
"code": "12052300",
"message": "product main image uri illegal"
},
{
"code": "12052301",
"message": "Width and length of main image must be at least {{min_limit}}, check uri {{uri}}"
},
{
"code": "12052302",
"message": "The main images size exceed limit."
},
{
"code": "12052303",
"message": "The algo prediction for category v2 of this product failed"
},
{
"code": "12052304",
"message": "Main product image format not support."
},
{
"code": "12052305",
"message": "The main images aspect ratio cannot exceed max limit."
},
{
"code": "12052306",
"message": "main product images count exceed limit"
},
{
"code": "12052324",
"message": "Product description image file format is not supported"
},
{
"code": "12052340",
"message": "product description image uri illegal"
},
{
"code": "12052341",
"message": "The description images size cannot exceed limit."
},
{
"code": "12052342",
"message": "The description images space cannot exceed limit."
},
{
"code": "12052343",
"message": "Product description image format not support."
},
{
"code": "12052344",
"message": "The product description html syntax with error"
},
{
"code": "12052345",
"message": "The product description html tag not support."
},
{
"code": "12052346",
"message": "The product description has Chinese characters"
},
{
"code": "12052348",
"message": "The product description html tag required attribute is miss."
},
{
"code": "12052349",
"message": "The product description html tag not support nest."
},
{
"code": "12052350",
"message": "The product description html tag contain illegal attribute."
},
{
"code": "12052351",
"message": "The product description contains non-English characters."
},
{
"code": "12052360",
"message": "The video id is not exist."
},
{
"code": "12052379",
"message": "the cover region of share warehouse can not cover the the product region"
},
{
"code": "12052401",
"message": "package weight exceed limit."
},
{
"code": "12052447",
"message": "You still have stock reserved for campaigns in your Chinese warehouse(s), so you cannot add an overseas warehouse yet. If you have an overseas warehouse, you must use it to fulfill orders for your {{country}} shop."
},
{
"code": "12052448",
"message": "Local fulfillment is required for {{country}} shop. You must have at least one {{country}} overseas warehouse for it."
},
{
"code": "12052520",
"message": "product sale property image uri illegal"
},
{
"code": "12052521",
"message": "The sale property images size over limit."
},
{
"code": "12052522",
"message": "Product sale property image is required"
},
{
"code": "12052523",
"message": "Product sale property image format not support."
},
{
"code": "12052524",
"message": "The sale property image aspect ratio invalid"
},
{
"code": "12052525",
"message": "The attribute max num cannot exceed 3."
},
{
"code": "12052527",
"message": "The sale attribute id not exist."
},
{
"code": "12052528",
"message": "You can add images to only 1 product variation, which will serve as the primary variation for display in the product options gallery."
},
{
"code": "12052529",
"message": "The property value id not exist."
},
{
"code": "12052530",
"message": "The warehouse ' {{warehouse ID}} ' does not belong to this shop/seller."
},
{
"code": "12052531",
"message": "The warehouse is disabled."
},
{
"code": "12052550",
"message": "SKU property must contain all properties"
},
{
"code": "12052554",
"message": "sku name contain Chinese characters"
},
{
"code": "12052570",
"message": "product price exceed limit"
},
{
"code": "12052574",
"message": "unit price config is invalid"
},
{
"code": "12052591",
"message": "Invalid number of digits of identifier code"
},
{
"code": "12052592",
"message": "Identifier code already entered, cannot enter the same code twice"
},
{
"code": "12052593",
"message": "The identifier code cannot be changed once be submitted"
},
{
"code": "12052594",
"message": "The identifier code type cannot be changed once be submitted"
},
{
"code": "12052598",
"message": "Only the last digit supports input X"
},
{
"code": "12052600",
"message": "The identifier code type must be selected"
},
{
"code": "12052650",
"message": "product qualification image uri illegal"
},
{
"code": "12052670",
"message": "The size chart image URI is invalid. Note: API users must use the URI generated by the Upload Product Image API."
},
{
"code": "12052673",
"message": "Product sizechart image is required"
},
{
"code": "12052700",
"message": "The seller is inactive."
},
{
"code": "12052701",
"message": "do not support cross-boarder seller create local product directly"
},
{
"code": "12052702",
"message": "seller does not support pre-order"
},
{
"code": "12052703",
"message": "Invalid seller tax number"
},
{
"code": "12052704",
"message": "seller id not exist"
},
{
"code": "12052901",
"message": "The product in its current status is not available for this operation. Change the product status and try again."
},
{
"code": "12052910",
"message": "Invalid input parameters. Refer to the API documentation for details."
},
{
"code": "12052912",
"message": "No matching category found within your account's main category. Check your main category in the seller profile on Seller Center and ensure your product falls within its scope."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/edit-global-product-202309"
}
},
"/product/202309/global_products/{global_product_id}/inventory/update": {
"post": {
"operationId": "updateGlobalInventory",
"summary": "Update Global Inventory",
"description": "Update the inventory of a global product in `DRAFT`, `UNPUBLISHED`, or `PUBLISHED` status. You must have access to the Multi-Warehouse feature.",
"tags": [
"Products"
],
"parameters": [
{
"name": "global_product_id",
"in": "path",
"required": true,
"description": "The global product ID to be updated.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateGlobalInventoryRequest"
},
"example": {
"global_skus": [
{
"id": "1729592969712207013",
"inventory": [
{
"global_warehouse_id": "7068517275539719942",
"quantity": 999
}
]
}
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateGlobalInventoryResponse"
},
"example": {
"code": 0,
"data": {},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-scenario": 2,
"x-tts-scopes": [
"Global Product Modify"
],
"x-tts-error-codes": [
{
"code": "12019113",
"message": "product status is invalid"
},
{
"code": "12019114",
"message": "Seller has no permission"
},
{
"code": "12019117",
"message": "Missing variations (sales attributes). When there are multiple SKUs in a product, each SKU must include variation (sales attribute) details that explain how it is different from other SKUs in the product."
},
{
"code": "12019150",
"message": "The product ID does not exist."
},
{
"code": "12052048",
"message": "You cannot edit the specified product(s) as it isn't listed in your account or shop."
},
{
"code": "12052055",
"message": "The SKU inventory quantity for the warehouse must be within allowed limits."
},
{
"code": "12052094",
"message": "No multiple warehouse permission"
},
{
"code": "12052142",
"message": "no permission of multi global warehouse"
},
{
"code": "12052143",
"message": "sku warehouse must equal"
},
{
"code": "12052145",
"message": "activity warehouse not allowed to be deleted"
},
{
"code": "12052146",
"message": "The specified inventory quantity is too low. It must be greater than the locked quantity (e.g. for committed orders, campaigns, creators) to ensure a non-negative available stock."
},
{
"code": "12052260",
"message": "The product ID does not exist"
},
{
"code": "12052379",
"message": "the cover region of share warehouse can not cover the the product region"
},
{
"code": "12052447",
"message": "You still have stock reserved for campaigns in your Chinese warehouse(s), so you cannot add an overseas warehouse yet. If you have an overseas warehouse, you must use it to fulfill orders for your {{country}} shop."
},
{
"code": "12052448",
"message": "Local fulfillment is required for {{country}} shop. You must have at least one {{country}} overseas warehouse for it."
},
{
"code": "12052530",
"message": "The warehouse ' {{warehouse ID}} ' does not belong to this shop/seller."
},
{
"code": "12052531",
"message": "The warehouse is disabled."
},
{
"code": "12052533",
"message": "Removal, addition, and change of warehouses are not permitted. Please specify the original warehouses for the SKUs."
},
{
"code": "12052556",
"message": "The SKU id not exist."
},
{
"code": "12052700",
"message": "The seller is inactive."
},
{
"code": "12052902",
"message": "The SKU list is empty. Either omit the list entirely, or provide all required details."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/update-global-inventory-202309"
}
},
"/product/202309/global_products/{global_product_id}/publish": {
"post": {
"operationId": "publishGlobalProduct",
"summary": "Publish Global Product",
"description": "Publish and convert a global product to local products in one or multiple shops in supported markets. After publishing, the product is sent for review by TikTok Shop in the respective markets. For sellers in the EU market, the provided information will also be automatically translated into all EU languages supported by TikTok Shop.\n**Note**: \n- You can only publish in each market once. To change product information, edit the global product by using the [Edit Global Product API](6509e1bcc16ffe02b8dc3cd7). The changes will be automatically synchronized to all markets where the product is published\n- Use the [Get Product API](6509d85b4a0bb702c057fdda) to obtain the converted local product information in the target market's language. \n- Use the [Edit Product API](6509da7d0fcef602bf1caddf) or [Partial Edit Product API](650a98d74a0bb702c06c3289) to edit the local product information, if necessary.",
"tags": [
"Products"
],
"parameters": [
{
"name": "global_product_id",
"in": "path",
"required": true,
"description": "The global product id.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublishGlobalProductRequest"
},
"example": {
"publish_target": [
{
"region": "MY",
"responsible_person_ids": [
"67726293bf1eb1e92401a"
],
"manufacturer_ids": [
"67726293bf1eb1e92401a"
],
"skus": [
{
"related_global_sku_id": "1729592969712207400",
"price": {
"amount": "10.01",
"currency": "MYR",
"sale_price": "100.00"
},
"inventory": {
"warehouse_id": "7068517275539719942",
"quantity": 999
},
"fees": [
{
"type": "PFAND",
"amount": "1.01",
"additional_attribute": "SINGLE_USE"
}
]
}
]
}
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublishGlobalProductResponse"
},
"example": {
"code": 0,
"data": {
"products": [
{
"region": "MY",
"shop_id": "7494083603082020484",
"skus": [
{
"related_global_sku_id": "1729696746528737924",
"id": "1729592969712207400",
"seller_sku": "XL-COLOR-001",
"sale_attributes": [
{
"id": "100001",
"value_id": "7272008676829824800"
}
]
}
],
"id": "1929592969712207410"
}
],
"publish_result": [
{
"region": "MY",
"status": "SUCCESS",
"fail_reasons": [
{
"message": "The publish region is inactive."
}
]
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-scenario": 2,
"x-tts-scopes": [
"Global Product Modify"
],
"x-tts-error-codes": [
{
"code": "12019004",
"message": "Seller is inactive"
},
{
"code": "12019010",
"message": "product price is invalid"
},
{
"code": "12019016",
"message": "Unable to publish or sync products to target markets due to missing or invalid warehouse details."
},
{
"code": "12019028",
"message": "Multiple warehouses detected. Include all warehouse IDs and the corresponding details and try again."
},
{
"code": "12019113",
"message": "product status is invalid"
},
{
"code": "12019121",
"message": "calculate price error"
},
{
"code": "12019150",
"message": "The product ID does not exist."
},
{
"code": "12019212",
"message": "region already published"
},
{
"code": "12052055",
"message": "The SKU inventory quantity for the warehouse must be within allowed limits."
},
{
"code": "12052084",
"message": "The provided currency is not available for this shop/region."
},
{
"code": "12052117",
"message": "seller publish global product over limit and save draft"
},
{
"code": "12052145",
"message": "activity warehouse not allowed to be deleted"
},
{
"code": "12052146",
"message": "The specified inventory quantity is too low. It must be greater than the locked quantity (e.g. for committed orders, campaigns, creators) to ensure a non-negative available stock."
},
{
"code": "12052260",
"message": "The product ID does not exist"
},
{
"code": "12052379",
"message": "the cover region of share warehouse can not cover the the product region"
},
{
"code": "12052424",
"message": "Missing 'sale price' value"
},
{
"code": "12052531",
"message": "The warehouse is disabled."
},
{
"code": "12052556",
"message": "The SKU id not exist."
},
{
"code": "12052700",
"message": "The seller is inactive."
},
{
"code": "12052701",
"message": "do not support cross-boarder seller create local product directly"
},
{
"code": "12052901",
"message": "The product in its current status is not available for this operation. Change the product status and try again."
},
{
"code": "12052903",
"message": "The publish region is inactive."
},
{
"code": "12052910",
"message": "Invalid input parameters. Refer to the API documentation for details."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/publish-global-product-202309"
}
},
"/product/202309/images/upload": {
"post": {
"operationId": "uploadProductImage",
"summary": "Upload Product Image",
"description": "Upload a local image to TikTok Shop for use as a product image, variant image, size chart, certification image, or another supported image use case.\n\n**Note**:\n- All images used in TikTok Shop products must be uploaded through this API. You cannot use image URLs that are not hosted by TikTok Shop.\n- Store `data.uri` to associate the uploaded image with a product when creating or editing it. Store `data.url` when you need to display the image in a product description by using an HTML `Please check the measurements before purchase.
\n ",
"category_id": "600001",
"brand_id": "7082427311584347905",
"main_images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
],
"skus": [
{
"sales_attributes": [
{
"id": "100089",
"value_id": "1729592969712207000",
"value_name": "Red",
"sku_img": {
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
},
"name": "Color",
"supplementary_sku_images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
]
}
],
"inventory": [
{
"warehouse_id": "7068517275539719942",
"quantity": 999,
"backorder_quantity": 888,
"handling_time": 5
}
],
"seller_sku": "Color-Red-XM001",
"price": {
"amount": "1.21",
"currency": "USD",
"sale_price": "1.21",
"starting_bid_price": "2.22"
},
"external_sku_id": "1729592969712207012",
"identifier_code": {
"code": "10000000000000",
"type": "GTIN"
},
"combined_skus": [
{
"product_id": "1729582718312380123",
"sku_id": "2729382476852921560",
"sku_count": 1
}
],
"sku_unit_count": "100.00",
"external_urls": [
"https://example.com/path1",
"https://example.com/path2"
],
"extra_identifier_codes": [
"00012345678905",
"9780596520687"
],
"pre_sale": {
"type": "PRE_ORDER",
"fulfillment_type": {
"handling_duration_days": 7,
"release_date": 1619611761
}
},
"list_price": {
"amount": "1",
"currency": "USD"
},
"external_list_prices": [
{
"source": "SHOPIFY_COMPARE_AT_PRICE",
"amount": "1",
"currency": "USD"
}
],
"fees": [
{
"type": "PFAND",
"amount": "1.01",
"additional_attribute": "SINGLE_USE"
}
],
"sku_dimensions": {
"length": "10",
"width": "10",
"height": "10",
"unit": "CENTIMETER"
},
"sku_weight": {
"value": "1.32",
"unit": "KILOGRAM"
}
}
],
"title": "Men's Fashion Sports Low Cut Cotton Breathable Ankle Short Boat Invisible Socks",
"is_cod_allowed": false,
"certifications": [
{
"id": "7182427311584347905",
"images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
],
"files": [
{
"id": "v09ea0g40000cj91373c77u3mid3g1s0",
"name": "brand_cert.PDF",
"format": "PDF"
}
],
"expiration_date": 1741234626
}
],
"package_dimensions": {
"length": "10",
"width": "10",
"height": "10",
"unit": "CENTIMETER"
},
"product_attributes": [
{
"id": "100392",
"values": [
{
"id": "1001533",
"name": "Birthday",
"metric_standard_info": {
"id": "7678592839487784712",
"metric_value_module_infos": [
{
"id": "7678592839487735560",
"value": "2026",
"unit_id": "7678592839484720903"
}
]
}
}
]
}
],
"package_weight": {
"value": "1.32",
"unit": "KILOGRAM"
},
"video": {
"id": "v09e40f40000cfu0ovhc77ub7fl97k4w"
},
"external_product_id": "172959296971220002",
"delivery_option_ids": [
"1729592969712203232"
],
"size_chart": {
"image": {
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
},
"template": {
"id": "7267563252536723205"
}
},
"primary_combined_product_id": "1729582718312380123",
"is_not_for_sale": true,
"category_version": "v1",
"manufacturer_ids": [
"172959296971220002"
],
"responsible_person_ids": [
"172959296971220003"
],
"listing_platforms": [
"TIKTOK_SHOP"
],
"shipping_insurance_requirement": "REQUIRED",
"minimum_order_quantity": 1,
"is_pre_owned": false,
"idempotency_key": "create202208291503530001100220033",
"shipping_template_id": "7552764259994699538",
"scheduled_sale": {
"is_enabled_scheduled_sale": false,
"schedule_sale_time": 1768899145000
},
"locale": "en-US",
"auto_translate_enabled": false,
"search_terms": [
"sneakers",
"running shoes",
"athletic"
],
"key_product_features": [
"Breathable mesh upper",
"Cushioned foam midsole"
],
"product_tag_operations": [
{
"product_tag": "AUCTION",
"enable": false
}
],
"purchase_order_quantity_limit": {
"maximum_order_quantity": 2,
"cumulative_order_quantity": 20
},
"selling_format": "FIXED_PRICE",
"is_live_quick": false,
"is_blind_box": false
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateProductResponse"
},
"example": {
"code": 0,
"data": {
"product_id": "1729592969712207008",
"skus": [
{
"id": "1729592969712207012",
"seller_sku": "Color-Red-XM001",
"sales_attributes": [
{
"id": "100000",
"value_id": "1729592969712207123"
}
],
"external_sku_id": "1729592969712207234",
"fees": [
{
"type": "PFAND",
"amount": "1.01",
"additional_attribute": "SINGLE_USE"
}
]
}
],
"warnings": [
{
"message": "The [brand_id]:123 field is incorrect and has been automatically cleared by the system. Reason: [Brand does not exist]. You can edit it later."
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Modify"
],
"x-tts-error-codes": [
{
"code": "12001000",
"message": "product api internal error"
},
{
"code": "12019006",
"message": "product description is invalid"
},
{
"code": "12019011",
"message": "product package weight is invalid"
},
{
"code": "12019012",
"message": "product package size is invalid"
},
{
"code": "12019013",
"message": "brand id is invalid"
},
{
"code": "12019059",
"message": "seller sku is invalid"
},
{
"code": "12019061",
"message": "Product weight or dimensions unit does not support the imperial units on non-US local products."
},
{
"code": "12019095",
"message": "`pre_sale.fulfillment_type` is missing or empty."
},
{
"code": "12019096",
"message": "The value for `pre_sale.type` is missing."
},
{
"code": "12019097",
"message": "`pre_sale.fulfillment_type.release_date` must be set to a non-zero value."
},
{
"code": "12019098",
"message": "`pre_sale.fulfillment_type.handling_duration_days` must be set to a non-zero value."
},
{
"code": "12019099",
"message": "The specified `pre_sale.type` is not supported in your region. Refer to the API documentation for details."
},
{
"code": "12019100",
"message": "All SKUs of a product must have the same `pre_sale.type`. Do not assign different values."
},
{
"code": "12019215",
"message": "deposit balance is not enough"
},
{
"code": "12052002",
"message": "Incorrect category format"
},
{
"code": "12052003",
"message": "Incorrect parcel height format"
},
{
"code": "12052004",
"message": "Incorrect parcel width format"
},
{
"code": "12052005",
"message": "Incorrect parcel length format"
},
{
"code": "12052006",
"message": "Incorrect parcel weight format"
},
{
"code": "12052013",
"message": "The product description cannot exceed maximum characters"
},
{
"code": "12052015",
"message": "The product description is required"
},
{
"code": "12052023",
"message": "Category does not exist"
},
{
"code": "12052024",
"message": "Category is not final category"
},
{
"code": "12052025",
"message": "The category is invalid"
},
{
"code": "12052026",
"message": "Brand does not exist"
},
{
"code": "12052028",
"message": "Main product image is required"
},
{
"code": "12052034",
"message": "This product doesn't belong to this shop"
},
{
"code": "12052048",
"message": "You cannot edit the specified product(s) as it isn't listed in your account or shop."
},
{
"code": "12052050",
"message": "A single product cannot have more than 100 different SKUs"
},
{
"code": "12052051",
"message": "The product name exceed max limit characters"
},
{
"code": "12052054",
"message": "The seller SKU text length cannot exceed max limit characters"
},
{
"code": "12052055",
"message": "The SKU inventory quantity for the warehouse must be within allowed limits."
},
{
"code": "12052056",
"message": "The num of image in description cannot exceed max limit"
},
{
"code": "12052073",
"message": "The product price is invalid"
},
{
"code": "12052084",
"message": "The provided currency is not available for this shop/region."
},
{
"code": "12052092",
"message": "product sale price is invalid"
},
{
"code": "12052093",
"message": "Exceeded the product listing limit for the seller."
},
{
"code": "12052094",
"message": "No multiple warehouse permission"
},
{
"code": "12052096",
"message": "Unable to update the price for SKUs with no warehouse. Assign a warehouse and try again."
},
{
"code": "12052097",
"message": "The warehouse does not exist"
},
{
"code": "12052104",
"message": "property is required"
},
{
"code": "12052105",
"message": "required qualification miss"
},
{
"code": "12052109",
"message": "number of requests from merchants over limit"
},
{
"code": "12052115",
"message": "seller has no warehouse"
},
{
"code": "12052116",
"message": "product package size is invalid"
},
{
"code": "12052128",
"message": "Size chart not found"
},
{
"code": "12052144",
"message": "platform warehouse not support to edit"
},
{
"code": "12052151",
"message": "product property value contain restricted words"
},
{
"code": "12052152",
"message": "sale property name contains restricted words"
},
{
"code": "12052153",
"message": "sale property value contains restricted words"
},
{
"code": "12052159",
"message": "unique item total quantity must be one"
},
{
"code": "12052162",
"message": "unique item sku count must be one and disable varialbes"
},
{
"code": "12052172",
"message": "sale type is invalid"
},
{
"code": "12052181",
"message": "The package weight of the product can not be zero."
},
{
"code": "12052182",
"message": "The '{{sub_property_name}}' field is required as you've selected '{{parent_property_value}}' for '{{parent_property_name}}'."
},
{
"code": "12052183",
"message": "The '{{sub_property_name}}' field should be left empty as you've selected '{{parent_property_value}}' for '{{parent_property_name}}'."
},
{
"code": "12052200",
"message": "brand is expired"
},
{
"code": "12052201",
"message": "You are not authorized to sell this brand in this category. To do so, apply through the Qualification Center in Seller Center."
},
{
"code": "12052207",
"message": "receipt brand not support warehouse"
},
{
"code": "12052208",
"message": "A brand authorization is required to publish this listing."
},
{
"code": "12052217",
"message": "All region shops must use V2 categories. Check the documentation for further details."
},
{
"code": "12052219",
"message": "instant product not support not for sale"
},
{
"code": "12052220",
"message": "This category is prohibited or unsupported on TikTok Shop. Select another category."
},
{
"code": "12052221",
"message": "Only whitelisted sellers are permitted to trade under current category"
},
{
"code": "12052222",
"message": "category do not support cod"
},
{
"code": "12052223",
"message": "This category is restricted. To sell in this category, apply through the Qualification Center in Seller Center."
},
{
"code": "12052225",
"message": "You are not authorized to sell in this category because it does not fall under your shop's main category. Contact your account manager for help or select another category."
},
{
"code": "12052226",
"message": "This category is restricted. To sell in this category, apply through the Qualification Center in Seller Center."
},
{
"code": "12052227",
"message": "the category is unauthorized or unavailable"
},
{
"code": "12052228",
"message": "combo product not support not for sale"
},
{
"code": "12052229",
"message": "pre order product not support not for sale"
},
{
"code": "12052230",
"message": "Category version and categoryID are not matched."
},
{
"code": "12052235",
"message": "The format of url is invalid"
},
{
"code": "12052236",
"message": "The protocol of the url is unsafe"
},
{
"code": "12052237",
"message": "The path of url is unsafe"
},
{
"code": "12052238",
"message": "The length of the url is greater than 200"
},
{
"code": "12052240",
"message": "Do not support custom property."
},
{
"code": "12052241",
"message": "attribute name or attribute id is empty."
},
{
"code": "12052242",
"message": "The attribute name characters cannot exceed max_limit"
},
{
"code": "12052243",
"message": "The product attribute or sale attribute name characters contain Chinese."
},
{
"code": "12052244",
"message": "The attribute name duplicate."
},
{
"code": "12052245",
"message": "The product attributes contained invalid characters. Please modify and re-submit."
},
{
"code": "12052246",
"message": "The {{property_type}} not support multi selected, attribute id is :{{property_id}}."
},
{
"code": "12052247",
"message": "Do not support custom product attribute."
},
{
"code": "12052248",
"message": "The {{property_type}} value name or attribute value id is empty."
},
{
"code": "12052249",
"message": "The {{property_type}} value name characters cannot exceed {{max_limit}}, attribute value name is :{{property_value_name}}."
},
{
"code": "12052250",
"message": "The {{property_type}} value name characters contain Chinese."
},
{
"code": "12052251",
"message": "Duplicated attribute values found for an attribute. Remove or modify the duplicated value."
},
{
"code": "12052253",
"message": "Duplicate attribute value id"
},
{
"code": "12052254",
"message": "Duplicate attribute id"
},
{
"code": "12052256",
"message": "The {{property_name}} value need to be positive integers or positive decimals ."
},
{
"code": "12052260",
"message": "The product ID does not exist"
},
{
"code": "12052261",
"message": "product name is empty"
},
{
"code": "12052262",
"message": "Chinese characters are not supported in product name"
},
{
"code": "12052263",
"message": "product name prefix illegal"
},
{
"code": "12052268",
"message": "seller does not support pre sale"
},
{
"code": "12052269",
"message": "The selected time is outside the limit"
},
{
"code": "12052274",
"message": "pre-sale and pre-order modes are mutually exclusive."
},
{
"code": "12052275",
"message": "sku's mto day is invalid"
},
{
"code": "12052278",
"message": "seller does not support make to order"
},
{
"code": "12052282",
"message": "Product manufacturer is required."
},
{
"code": "12052283",
"message": "The number of manufacturers cannot exceed the allowed limits."
},
{
"code": "12052284",
"message": "Manufacturer ID {{manufacturer_id}} is not found"
},
{
"code": "12052285",
"message": "Manufacturer ID {{manufacturer_id}} is not associated with the seller"
},
{
"code": "12052287",
"message": "Product responsible person is required"
},
{
"code": "12052288",
"message": "The number of responsible person ids cannot exceed {{max_limit}}, and cannot less {{min_limit}}."
},
{
"code": "12052289",
"message": "Responsible person ID {{rp_id}} is not found"
},
{
"code": "12052290",
"message": "Responsible person ID {{rp_id}} is not associated with the seller"
},
{
"code": "12052291",
"message": "Extra identification code information is not supported in this region."
},
{
"code": "12052293",
"message": "When identifier code is not filled in, extra identification code is not allowed to be filled in."
},
{
"code": "12052294",
"message": "The format of the extra identification code is incorrect."
},
{
"code": "12052295",
"message": "Duplicate manufacturer IDs associated with the same product"
},
{
"code": "12052296",
"message": "Duplicate responsible person IDs associated with the same product"
},
{
"code": "12052300",
"message": "product main image uri illegal"
},
{
"code": "12052301",
"message": "Width and length of main image must be at least {{min_limit}}, check uri {{uri}}"
},
{
"code": "12052302",
"message": "The main images size exceed limit."
},
{
"code": "12052304",
"message": "Main product image format not support."
},
{
"code": "12052305",
"message": "The main images aspect ratio cannot exceed max limit."
},
{
"code": "12052306",
"message": "main product images count exceed limit"
},
{
"code": "12052309",
"message": "The seller does not have backorder permission."
},
{
"code": "12052310",
"message": "The futures information filled in by the seller does not meet the requirements."
},
{
"code": "12052311",
"message": "The number of backorder product exceeds the limit max_num, or the proportion of backorder product exceeds the limit max_ratio"
},
{
"code": "12052313",
"message": "This product does not allow backorder inventory."
},
{
"code": "12052316",
"message": "product second hand not applicable in this sale platform"
},
{
"code": "12052324",
"message": "Product description image file format is not supported"
},
{
"code": "12052330",
"message": "product is not supported to list in designated sale platform"
},
{
"code": "12052332",
"message": "The seller center is locked during shop integration, only editing stock and price is allowed"
},
{
"code": "12052340",
"message": "product description image uri illegal"
},
{
"code": "12052341",
"message": "The description images size cannot exceed limit."
},
{
"code": "12052342",
"message": "The description images space cannot exceed limit."
},
{
"code": "12052343",
"message": "Product description image format not support."
},
{
"code": "12052344",
"message": "The product description html syntax with error"
},
{
"code": "12052345",
"message": "The product description html tag not support."
},
{
"code": "12052346",
"message": "The product description has Chinese characters"
},
{
"code": "12052348",
"message": "The product description html tag required attribute is miss."
},
{
"code": "12052349",
"message": "The product description html tag not support nest."
},
{
"code": "12052350",
"message": "The product description html tag contain illegal attribute."
},
{
"code": "12052352",
"message": "The product description nest exceeding limit"
},
{
"code": "12052356",
"message": "The number of 'supplementary_sku_images' for the sales attribute value exceeds the maximum limit."
},
{
"code": "12052357",
"message": "'supplementary_sku_images' is only allowed when 'sku_img' is specified. Add an image to 'sku_img' and try again."
},
{
"code": "12052358",
"message": "Tokopedia platform doesn't support this kind of product"
},
{
"code": "12052360",
"message": "The video id is not exist."
},
{
"code": "12052361",
"message": "This base unit value count is not supported. The supported base unit values can be obtained from the Get Attribute API."
},
{
"code": "12052362",
"message": "SKU unit count is required."
},
{
"code": "12052364",
"message": "The warehouse is unavailable because this product cannot be shipped to the target market from this warehouse."
},
{
"code": "12052365",
"message": "The manufacturer lacks language version information for this market."
},
{
"code": "12052366",
"message": "The responsible person lacks language version information for this market."
},
{
"code": "12052369",
"message": "external_id length check fail"
},
{
"code": "12052372",
"message": "Generate EU energy label image failed"
},
{
"code": "12052375",
"message": "product list price is invalid"
},
{
"code": "12052376",
"message": "list price not support"
},
{
"code": "12052382",
"message": "Can't edit Dilayani Tokopedia warehouse quantity"
},
{
"code": "12052383",
"message": "product list price exceed limit"
},
{
"code": "12052385",
"message": "Please enter valid certificate expiration date"
},
{
"code": "12052402",
"message": "seller shipping template is empty"
},
{
"code": "12052403",
"message": "The warehouse does not support fulfillment for the current shop."
},
{
"code": "12052404",
"message": "multi-warehouse not support customize logistics service"
},
{
"code": "12052405",
"message": "The warehouse has not opened the subscribed logistics service"
},
{
"code": "12052419",
"message": "The shop tasks necessary for posting products have not been completed. Please go to complete them"
},
{
"code": "12052420",
"message": "warehouse didn't set logistics service"
},
{
"code": "12052424",
"message": "Missing 'sale price' value"
},
{
"code": "12052446",
"message": "Category is not open in this market"
},
{
"code": "12052488",
"message": "This region doesn't support save draft after product submitted"
},
{
"code": "12052490",
"message": "The handling time must be within the allowed limits."
},
{
"code": "12052495",
"message": "Pfand packaging type is required"
},
{
"code": "12052497",
"message": "Pfand field is not supported in this country"
},
{
"code": "12052498",
"message": "Pfand amount should not be filled."
},
{
"code": "12052520",
"message": "product sale property image uri illegal"
},
{
"code": "12052521",
"message": "The sale property images size over limit."
},
{
"code": "12052522",
"message": "Product sale property image is required"
},
{
"code": "12052523",
"message": "Product sale property image format not support."
},
{
"code": "12052524",
"message": "The sale property image aspect ratio invalid"
},
{
"code": "12052525",
"message": "The attribute max num cannot exceed 3."
},
{
"code": "12052526",
"message": "The attribute value max num over limit."
},
{
"code": "12052527",
"message": "The sale attribute id not exist."
},
{
"code": "12052528",
"message": "You can add images to only 1 product variation, which will serve as the primary variation for display in the product options gallery."
},
{
"code": "12052529",
"message": "The property value id not exist."
},
{
"code": "12052530",
"message": "The warehouse ' {{warehouse ID}} ' does not belong to this shop/seller."
},
{
"code": "12052531",
"message": "The warehouse is disabled."
},
{
"code": "12052532",
"message": "the warehouse not delivery warehouse"
},
{
"code": "12052535",
"message": "Couldn't publish this product as you haven't set the return warehouse for your shop. Add the return warehouse information on TikTok Shop Seller Center first and try again."
},
{
"code": "12052543",
"message": "Products that support pfand are not supported in the creation of Virtual Bundles."
},
{
"code": "12052549",
"message": "The current shipping template is unavailable due to the unavailability of shipping method. Please change the shipping template."
},
{
"code": "12052550",
"message": "SKU property must contain all properties"
},
{
"code": "12052554",
"message": "sku name contain Chinese characters"
},
{
"code": "12052555",
"message": "The warehouse id is duplicate"
},
{
"code": "12052560",
"message": "The SKU contains duplicate sales attribute."
},
{
"code": "12052570",
"message": "product price exceed limit"
},
{
"code": "12052571",
"message": "Missing price for SKU(s)"
},
{
"code": "12052574",
"message": "unit price config is invalid"
},
{
"code": "12052585",
"message": "deposit balance is not enough"
},
{
"code": "12052591",
"message": "Invalid number of digits of identifier code"
},
{
"code": "12052592",
"message": "Identifier code already entered, cannot enter the same code twice"
},
{
"code": "12052598",
"message": "Only the last digit supports input X"
},
{
"code": "12052600",
"message": "The identifier code type must be selected"
},
{
"code": "12052603",
"message": "Scheduled listing is not supported"
},
{
"code": "12052604",
"message": "The scheduled listing time is invalid"
},
{
"code": "12052650",
"message": "product qualification image uri illegal"
},
{
"code": "12052655",
"message": "qualification id not exist"
},
{
"code": "12052656",
"message": "qualification id duplicate"
},
{
"code": "12052657",
"message": "qualification image and pdf file is out of limit."
},
{
"code": "12052658",
"message": "product qualification file uri illegal"
},
{
"code": "12052670",
"message": "The size chart image URI is invalid. Note: API users must use the URI generated by the Upload Product Image API."
},
{
"code": "12052671",
"message": "The sizechart images size over limit."
},
{
"code": "12052673",
"message": "Product sizechart image is required"
},
{
"code": "12052700",
"message": "The seller is inactive."
},
{
"code": "12052701",
"message": "do not support cross-boarder seller create local product directly"
},
{
"code": "12052702",
"message": "seller does not support pre-order"
},
{
"code": "12052703",
"message": "Invalid seller tax number"
},
{
"code": "12052704",
"message": "seller id not exist"
},
{
"code": "12052706",
"message": "The minimum sales quantity should not be exceed limit"
},
{
"code": "12052707",
"message": "Setting minimum sales quantity is not supported"
},
{
"code": "12052712",
"message": "sku's pre_order is invalid"
},
{
"code": "12052722",
"message": "The image URI does not exist in TikTok Shop."
},
{
"code": "12052830",
"message": "The number of sub-products contained in each combo cannot exceed {{max_limit}}."
},
{
"code": "12052831",
"message": "The number of sub-skus contained in each combo sku cannot exceed {{max_limit}}."
},
{
"code": "12052832",
"message": "The sub-SKU coefficient associated with each combo SKU cannot exceed {{max_limit}}, and cannot less {{min_limit}}."
},
{
"code": "12052833",
"message": "The number of combo associated with a product cannot exceed the max limit."
},
{
"code": "12052834",
"message": "The number of combo sku associated with a sku cannot exceed limit."
},
{
"code": "12052835",
"message": "Sub product ID not exist"
},
{
"code": "12052836",
"message": "The category of the combo is inconsistent with the category of the main sub-product."
},
{
"code": "12052837",
"message": "The category of the combo is not in the set of restricted categories."
},
{
"code": "12052838",
"message": "The first-level categories of the sub-products in the combo are inconsistent"
},
{
"code": "12052840",
"message": "Sub-skus in a combo sku cannot be duplicated"
},
{
"code": "12052841",
"message": "The sub-sku relationship corresponding to different combo sku cannot be duplicated."
},
{
"code": "12052842",
"message": "The combo does not include the main sub-product"
},
{
"code": "12052844",
"message": "The sub-sku is not in the sub-product"
},
{
"code": "12052845",
"message": "Failed to create, does not support non-live status product"
},
{
"code": "12052846",
"message": "combo does not support adding this product type"
},
{
"code": "12052848",
"message": "Combo cannot set minimum sale quantity"
},
{
"code": "12052849",
"message": "You don't have the permission to operate combo."
},
{
"code": "12052851",
"message": "The warehouse of combo sku is empty."
},
{
"code": "12052853",
"message": "The sale property of combo mismatch."
},
{
"code": "12052854",
"message": "The sale property of combo is not unique."
},
{
"code": "12052855",
"message": "The warehouse of combo mismatch."
},
{
"code": "12052856",
"message": "The combo does not support customize logistics service"
},
{
"code": "12052857",
"message": "Combined products and normal products cannot be converted to each other."
},
{
"code": "12052858",
"message": "The SKU of a combined product cannot be associated with the SKU of other combined products."
},
{
"code": "12052859",
"message": "When the combined SKU is only associated with one sub-SKU, the coefficient of this sub-SKU cannot be less than 2."
},
{
"code": "12052861",
"message": "The price of combined SKU cannot exceed the sum of the prices of the sub-SKUs."
},
{
"code": "12052862",
"message": "The brand of the combined product must be within the range of sub-product brands."
},
{
"code": "12052863",
"message": "All SKU of a combined product need to be the combined SKU."
},
{
"code": "12052864",
"message": "Unable to add deactivated SKUs to the combined product."
},
{
"code": "12052881",
"message": "identity internal error"
},
{
"code": "12052910",
"message": "Invalid input parameters. Refer to the API documentation for details."
},
{
"code": "12052915",
"message": "package weight unit and dimension unit miss match."
},
{
"code": "12052923",
"message": "contact info required"
},
{
"code": "12052930",
"message": "Seller SKU is required"
},
{
"code": "12052931",
"message": "The title must follow these formatting rules: it cannot contain HTML escape characters (e.g., ), emojis, or ASCII control characters (e.g., \\u007F). It also cannot consist solely of symbols (e.g., //// or !@#$$$&), nor can it have more than 9 consecutive repeated characters (e.g., aaaaaaaaa or 111111111)."
},
{
"code": "12052932",
"message": "The description must follow these formatting rules: it cannot contain HTML escape characters (e.g., ), emojis, or ASCII control characters (e.g., \\\\u007F). It also cannot consist solely of symbols (e.g., //// or !@#$$$&), nor can it have more than 9 consecutive repeated characters (e.g., aaaaaaaaa or 111111111)."
},
{
"code": "12052933",
"message": "Sales attribute names must follow these formatting rules: it cannot contain HTML escape characters (e.g., ), emojis, or ASCII control characters (e.g., \\u007F). It also cannot consist solely of symbols (e.g., //// or !@#$$$&), nor can it have more than 9 consecutive repeated characters (e.g., aaaaaaaaa or 111111111)."
},
{
"code": "12052934",
"message": "Sales attribute value names must follow these formatting rules: it cannot contain HTML escape characters (e.g., ), emojis, or ASCII control characters (e.g., \\\\u007F). It also cannot consist solely of symbols (e.g., //// or !@#$$$&), nor can it have more than 9 consecutive repeated characters (e.g., aaaaaaaaa or 111111111)."
},
{
"code": "12052935",
"message": "Product attribute value names must follow these formatting rules: it cannot contain HTML escape characters (e.g., ), emojis, or ASCII control characters (e.g., \\\\u007F). It also cannot consist solely of symbols (e.g., //// or !@#$$$&), nor can it have more than 9 consecutive repeated characters (e.g., aaaaaaaaa or 111111111)."
},
{
"code": "12052936",
"message": "Seller SKU format invalid. SKU name must contain 6 - 50 characters and use alphabets, numbers, hyphens (-), or underscores (_) only."
},
{
"code": "12052990",
"message": "The check failed."
},
{
"code": "12052992",
"message": "no permission to create gift product"
},
{
"code": "12052994",
"message": "seller is not toko seller"
},
{
"code": "12052995",
"message": "seller has not finished onboarding to tts"
},
{
"code": "12052996",
"message": "external_id duplicated"
},
{
"code": "33001002",
"message": "internal error"
},
{
"code": "36009002",
"message": "Too many requests. You've made too many requests in a short period of time."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
},
{
"code": "36009004",
"message": "invalid param error"
},
{
"code": "98001004",
"message": "Parameter {param_name} is invalid. Reason: {reason}. Expected: {expected_value}"
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/create-product-202309"
},
"delete": {
"operationId": "deleteProducts",
"summary": "Delete Products",
"description": "Delete non-frozen products that you no longer need.\n**For the Indonesia market**: You can only delete products that are not frozen on all listing platforms. If the product is frozen on any platform, it cannot be deleted.",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteProductsRequest"
},
"example": {
"product_ids": [
"1749456684124612452",
"1742456684124612451"
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteProductsResponse"
},
"example": {
"code": 0,
"data": {
"errors": [
{
"code": 12052048,
"message": "You can't edit other sellers' products.",
"detail": {
"product_id": "1729382588639839583"
}
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Delete & Recover"
],
"x-tts-error-codes": [
{
"code": "12019120",
"message": "The number of provided product IDs exceeds the limit."
},
{
"code": "12052032",
"message": "The product does not exist"
},
{
"code": "12052048",
"message": "You cannot edit the specified product(s) as it isn't listed in your account or shop."
},
{
"code": "12052332",
"message": "The seller center is locked during shop integration, only editing stock and price is allowed"
},
{
"code": "12052371",
"message": "Auction product is bidding when it is not supported to change product info"
},
{
"code": "12052377",
"message": "The product has dt stocks, not allow to delete."
},
{
"code": "12052700",
"message": "The seller is inactive."
},
{
"code": "12052703",
"message": "Invalid seller tax number"
},
{
"code": "12052705",
"message": "seller can not manage local product."
},
{
"code": "12052901",
"message": "The product in its current status is not available for this operation. Change the product status and try again."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/delete-products-202309"
}
},
"/product/202309/products/activate": {
"post": {
"operationId": "activateProducts",
"summary": "Activate Products",
"description": "Activate hidden products that are in the `Seller_deactivated` or `Platform_deactivated` status and display them in the TikTok Shop catalog. \nAfter submitting the activation request, the products will be sent to TikTok Shop for auditing and their status will change to `Pending`. If a product passes the audit, its status will change back to `Activate`. You can use the [Product status change webhook](https://partner.tiktokshop.com/docv2/page/650956aff1fd3102b90b6261) to monitor the audit status.",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ActivateProductsRequest"
},
"example": {
"product_ids": [
"1729592969712207008",
"1729592969712207021"
],
"listing_platforms": [
"TIKTOK_SHOP"
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ActivateProductsResponse"
},
"example": {
"code": 0,
"data": {
"errors": [
{
"code": 12052990,
"message": "Batch activate business error.",
"detail": {
"product_id": "1729382588639839583",
"extra_errors": [
{
"code": 12052048,
"message": "You can't edit other sellers' products"
}
]
}
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [
{
"code": "12019022",
"message": "SKU must contain a valid warehouse."
},
{
"code": "12019120",
"message": "The number of provided product IDs exceeds the limit."
},
{
"code": "12052048",
"message": "You cannot edit the specified product(s) as it isn't listed in your account or shop."
},
{
"code": "12052093",
"message": "Exceeded the product listing limit for the seller."
},
{
"code": "12052330",
"message": "product is not supported to list in designated sale platform"
},
{
"code": "12052332",
"message": "The seller center is locked during shop integration, only editing stock and price is allowed"
},
{
"code": "12052700",
"message": "The seller is inactive."
},
{
"code": "12052901",
"message": "The product in its current status is not available for this operation. Change the product status and try again."
},
{
"code": "12052910",
"message": "Invalid input parameters. Refer to the API documentation for details."
},
{
"code": "12052990",
"message": "The check failed."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/activate-products-202309"
}
},
"/product/202309/products/deactivate": {
"post": {
"operationId": "deactivateProducts",
"summary": "Deactivate Products",
"description": "Deactivate products that are in the `Activate` status and hide them from buyers. The status changes to `Seller_deactivated` after deactivation.\nIn the event there's some issue with a product (e.g. out of stock), you can deactivate the product and hide it temporarily from buyers. When the issues are resolved, you can activate the product again by using the [Activate Product API](https://partner.tiktokshop.com/docv2/page/650306ff5a12ff0294eab4a9).",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeactivateProductsRequest"
},
"example": {
"product_ids": [
"1729592969712207008"
],
"listing_platforms": [
"TIKTOK_SHOP",
"TOKOPEDIA"
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeactivateProductsResponse"
},
"example": {
"code": 0,
"data": {
"errors": [
{
"code": 12052048,
"message": "You can't edit other sellers' products",
"detail": {
"product_id": "1729382588639839583"
}
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [
{
"code": "12019120",
"message": "The number of provided product IDs exceeds the limit."
},
{
"code": "12052032",
"message": "The product does not exist"
},
{
"code": "12052048",
"message": "You cannot edit the specified product(s) as it isn't listed in your account or shop."
},
{
"code": "12052330",
"message": "product is not supported to list in designated sale platform"
},
{
"code": "12052332",
"message": "The seller center is locked during shop integration, only editing stock and price is allowed"
},
{
"code": "12052371",
"message": "Auction product is bidding when it is not supported to change product info"
},
{
"code": "12052700",
"message": "The seller is inactive."
},
{
"code": "12052703",
"message": "Invalid seller tax number"
},
{
"code": "12052901",
"message": "The product in its current status is not available for this operation. Change the product status and try again."
},
{
"code": "12052910",
"message": "Invalid input parameters. Refer to the API documentation for details."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/deactivate-products-202309"
}
},
"/product/202309/products/listing_check": {
"post": {
"operationId": "checkProductListing",
"summary": "Check Product Listing",
"description": "Identify any issues with your product properties in advance to ensure your product is ready for listing.\nEvery product must meet TikTok Shop requirements before it can be listed. Before listing, you can submit all relevant product information to this API to check whether a listing meets these requirements. You'll receive a list of issues to resolve before listing. This process helps reduce the risk of failure when creating products.\n**Note**: \n- The language used in the product content must align with the target market's language (e.g. don't use Chinese), otherwise the listing will fail or be rejected.",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "is_diagnosis_required",
"in": "query",
"required": false,
"description": "(**Deprecated**: This field is deprecated and will be removed in a future API version. Use [Diagnose and Optimize Product](677c9523f7765c0308b3d68d) API instead to get listing quality related information.)\nA flag to indicate whether to return the listing quality information (US only) and optimization diagnosis results for the product. If this is set to `false`, the response body will exclude the `listing_quality` and `diagnoses` objects.\nDefault: true",
"deprecated": true,
"schema": {
"type": "boolean"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckProductListingRequest"
},
"example": {
"description": "Please compare above detailed size with your measurement before purchase.
\n\n",
"category_id": "600001",
"brand_id": "7082427311584347905",
"main_images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
],
"skus": [
{
"sales_attributes": [
{
"id": "100089",
"name": "Specification",
"value_id": "1729592969712207000",
"value_name": "XL",
"sku_img": {
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
},
"supplementary_sku_images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
]
}
],
"seller_sku": "Color-Red-XM01",
"price": {
"amount": "1.23",
"currency": "USD",
"sale_price": "1.21",
"starting_bid_price": "2.3"
},
"external_sku_id": "1729592969712207012",
"identifier_code": {
"code": "10000000000000",
"type": "GTIN"
},
"inventory": [
{
"warehouse_id": "7068517275539719942",
"quantity": 999,
"backorder_quantity": 888,
"handling_time": 5
}
],
"combined_skus": [
{
"product_id": "1729582718312380123",
"sku_id": "1729582718312380123",
"sku_count": 11
}
],
"sku_unit_count": "100.00",
"external_urls": [
"https://example.com/path1",
"https://example.com/path2"
],
"extra_identifier_codes": [
"00012345678905",
"9780596520687"
],
"pre_sale": {
"type": "PRE_ORDER",
"fulfillment_type": {
"handling_duration_days": 24,
"release_date": 1619611761
}
},
"list_price": {
"amount": "1",
"currency": "USD"
},
"external_list_prices": [
{
"source": "SHOPIFY_COMPARE_AT_PRICE",
"amount": "1",
"currency": "USD"
}
],
"fees": [
{
"type": "PFAND",
"amount": "1.01",
"additional_attribute": "SINGLE_USE"
}
],
"sku_dimensions": {
"length": "10",
"width": "10",
"height": "10",
"unit": "CENTIMETER"
},
"sku_weight": {
"value": "1.32",
"unit": "KILOGRAM"
}
}
],
"title": "Men's Fashion Sports Low Cut Cotton Breathable Ankle Short Boat Invisible Socks",
"is_cod_allowed": false,
"certifications": [
{
"id": "7182427311584347905",
"images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe\n"
}
],
"files": [
{
"id": "v09ea0g40000cj91373c77u3mid3g1s0",
"name": "SNI.PDF",
"format": "PDF"
}
],
"expiration_date": 1741234626
}
],
"package_weight": {
"value": "1.32",
"unit": "KILOGRAM"
},
"product_attributes": [
{
"id": "100392",
"values": [
{
"id": "1001533",
"name": "Birthday"
}
]
}
],
"size_chart": {
"image": {
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
},
"template": {
"id": "7267563252536723205"
}
},
"package_dimensions": {
"length": "10",
"width": "10",
"height": "10",
"unit": "CENTIMETER"
},
"external_product_id": "172959296971220002",
"delivery_option_ids": [
"1729592969712203232"
],
"video": {
"id": "v09e40f40000cfu0ovhc77ub7fl97k4w"
},
"primary_combined_product_id": "1729582718312380123",
"manufacturer_ids": [
"172959296971220002"
],
"responsible_person_ids": [
"172959296971220003"
],
"listing_platforms": [
"TIKTOK_SHOP"
],
"shipping_insurance_requirement": "NOT_SUPPORTED",
"is_pre_owned": false,
"minimum_order_quantity": 4,
"shipping_template_id": "7552764259994699538",
"option": {
"need_trigger_gne_async_check": false,
"gne_async_check_session_id": "20260122085233268"
},
"scheduled_sale": {
"is_enabled_scheduled_sale": false,
"schedule_sale_time": 1768899145000
},
"search_terms": [
"sneakers",
"running shoes",
"athletic"
],
"key_product_features": [
"Breathable mesh upper",
"Cushioned foam midsole"
],
"product_tag_operations": [
{
"product_tag": "AUCTION",
"enable": true
}
],
"locale": "en-US",
"selling_format": "FIXED_PRICE_AND_LIVE_AUCTION",
"is_live_quick": false
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckProductListingResponse"
},
"example": {
"code": 0,
"data": {
"check_result": "FAILED",
"fail_reasons": [
{
"code": 12052700,
"message": "Product title invalid"
}
],
"warnings": {
"message": "Your product will not be sent for review. "
},
"listing_quality": {
"current_tier": "POOR",
"remaining_recommendations": 3
},
"diagnoses": [
{
"field": "TITLE",
"diagnosis_results": [
{
"code": "TITLE_LESS_THAN_40_CHARACTERS",
"how_to_solve": "Names must be at least 40 characters long and contain product-identifying information, such as \"hiking boots\" or \"lipstick\".",
"quality_tier": "FAIR"
}
],
"suggestions": {
"seo_words": [
{
"text": "dress"
}
],
"smart_texts": [
{
"text": "this is a good title"
}
],
"images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/53b55d6e8cdf1f315affa7e70b45707d",
"url": "https://p16-graph-va.ibyteimg.com/tos-maliva-i-1por3rr4fy-us/v2/53b55d6e8cdf1f315affa7e70b45707d~tplv-1por3rr4fy-image.webp",
"optimized_uri": "tos-maliva-i-o3syd03w52-us/0266127022264e54ad2f639f5e0fb5e6",
"optimized_url": "https://p16-graph-va.ibyteimg.com/tos-maliva-i-1por3rr4fy-us/v2/0266127022264e54ad2f639f5e0fb5e6~tplv-1por3rr4fy-image.webp",
"height": 600,
"width": 600
}
]
}
}
],
"pre_check_results": [
{
"pre_check_item": "INCOMPLETE_INFO",
"pre_check_details": [
{
"short_reason": "Insufficient or Incomplete Product Information",
"long_reason": "Ensure product title and description contain complete information that accurately describes the product",
"related_fields": [
"PRE_CHECK_FIELD_TITLE"
]
}
]
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Basic",
"Product Optimization"
],
"x-tts-error-codes": [
{
"code": "12001000",
"message": "product api internal error"
},
{
"code": "12019006",
"message": "product description is invalid"
},
{
"code": "12019011",
"message": "product package weight is invalid"
},
{
"code": "12019095",
"message": "`pre_sale.fulfillment_type` is missing or empty."
},
{
"code": "12019097",
"message": "`pre_sale.fulfillment_type.release_date` must be set to a non-zero value."
},
{
"code": "12019098",
"message": "`pre_sale.fulfillment_type.handling_duration_days` must be set to a non-zero value."
},
{
"code": "12019099",
"message": "The specified `pre_sale.type` is not supported in your region. Refer to the API documentation for details."
},
{
"code": "12019121",
"message": "calculate price error"
},
{
"code": "12052003",
"message": "Incorrect parcel height format"
},
{
"code": "12052004",
"message": "Incorrect parcel width format"
},
{
"code": "12052005",
"message": "Incorrect parcel length format"
},
{
"code": "12052023",
"message": "Category does not exist"
},
{
"code": "12052024",
"message": "Category is not final category"
},
{
"code": "12052084",
"message": "The provided currency is not available for this shop/region."
},
{
"code": "12052220",
"message": "This category is prohibited or unsupported on TikTok Shop. Select another category."
},
{
"code": "12052223",
"message": "This category is restricted. To sell in this category, apply through the Qualification Center in Seller Center."
},
{
"code": "12052226",
"message": "This category is restricted. To sell in this category, apply through the Qualification Center in Seller Center."
},
{
"code": "12052300",
"message": "product main image uri illegal"
},
{
"code": "12052356",
"message": "The number of 'supplementary_sku_images' for the sales attribute value exceeds the maximum limit."
},
{
"code": "12052357",
"message": "'supplementary_sku_images' is only allowed when 'sku_img' is specified. Add an image to 'sku_img' and try again."
},
{
"code": "12052446",
"message": "Category is not open in this market"
},
{
"code": "12052520",
"message": "product sale property image uri illegal"
},
{
"code": "12052650",
"message": "product qualification image uri illegal"
},
{
"code": "12052670",
"message": "The size chart image URI is invalid. Note: API users must use the URI generated by the Upload Product Image API."
},
{
"code": "12052700",
"message": "The seller is inactive."
},
{
"code": "12052722",
"message": "The image URI does not exist in TikTok Shop."
},
{
"code": "12052881",
"message": "identity internal error"
},
{
"code": "12052910",
"message": "Invalid input parameters. Refer to the API documentation for details."
},
{
"code": "12052915",
"message": "package weight unit and dimension unit miss match."
},
{
"code": "12052916",
"message": "The package unit is not supported in the current region."
},
{
"code": "12052930",
"message": "Seller SKU is required"
},
{
"code": "12052931",
"message": "The title must follow these formatting rules: it cannot contain HTML escape characters (e.g., ), emojis, or ASCII control characters (e.g., \\u007F). It also cannot consist solely of symbols (e.g., //// or !@#$$$&), nor can it have more than 9 consecutive repeated characters (e.g., aaaaaaaaa or 111111111)."
},
{
"code": "12052932",
"message": "The description must follow these formatting rules: it cannot contain HTML escape characters (e.g., ), emojis, or ASCII control characters (e.g., \\\\u007F). It also cannot consist solely of symbols (e.g., //// or !@#$$$&), nor can it have more than 9 consecutive repeated characters (e.g., aaaaaaaaa or 111111111)."
},
{
"code": "12052933",
"message": "Sales attribute names must follow these formatting rules: it cannot contain HTML escape characters (e.g., ), emojis, or ASCII control characters (e.g., \\u007F). It also cannot consist solely of symbols (e.g., //// or !@#$$$&), nor can it have more than 9 consecutive repeated characters (e.g., aaaaaaaaa or 111111111)."
},
{
"code": "12052934",
"message": "Sales attribute value names must follow these formatting rules: it cannot contain HTML escape characters (e.g., ), emojis, or ASCII control characters (e.g., \\\\u007F). It also cannot consist solely of symbols (e.g., //// or !@#$$$&), nor can it have more than 9 consecutive repeated characters (e.g., aaaaaaaaa or 111111111)."
},
{
"code": "12052935",
"message": "Product attribute value names must follow these formatting rules: it cannot contain HTML escape characters (e.g., ), emojis, or ASCII control characters (e.g., \\\\u007F). It also cannot consist solely of symbols (e.g., //// or !@#$$$&), nor can it have more than 9 consecutive repeated characters (e.g., aaaaaaaaa or 111111111)."
},
{
"code": "12052936",
"message": "Seller SKU format invalid. SKU name must contain 6 - 50 characters and use alphabets, numbers, hyphens (-), or underscores (_) only."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/check-product-listing-202309"
}
},
"/product/202309/products/recover": {
"post": {
"operationId": "recoverProducts",
"summary": "Recover Products",
"description": "Recover products that are in the `Deleted` status. The status changes to `Seller_deactivated` after recovery.",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoverProductsRequest"
},
"example": {
"product_ids": [
"1729592969712207008"
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoverProductsResponse"
},
"example": {
"code": 0,
"data": {
"errors": [
{
"code": 12052048,
"message": "You can't edit other sellers' products",
"detail": {
"product_id": "1729382588639839583"
}
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Delete & Recover"
],
"x-tts-error-codes": [
{
"code": "12019120",
"message": "The number of provided product IDs exceeds the limit."
},
{
"code": "12052032",
"message": "The product does not exist"
},
{
"code": "12052048",
"message": "You cannot edit the specified product(s) as it isn't listed in your account or shop."
},
{
"code": "12052332",
"message": "The seller center is locked during shop integration, only editing stock and price is allowed"
},
{
"code": "12052700",
"message": "The seller is inactive."
},
{
"code": "12052703",
"message": "Invalid seller tax number"
},
{
"code": "12052705",
"message": "seller can not manage local product."
},
{
"code": "12052901",
"message": "The product in its current status is not available for this operation. Change the product status and try again."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/recover-products-202309"
}
},
"/product/202309/products/{product_id}": {
"get": {
"operationId": "getProduct",
"summary": "Get Product",
"description": "Retrieve product details by product ID, including products in the `FREEZE` or `DELETED` status.",
"tags": [
"Products"
],
"parameters": [
{
"name": "product_id",
"in": "path",
"required": true,
"description": "The product ID in TikTok Shop.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "return_under_review_version",
"in": "query",
"required": false,
"description": "A flag to indicate what product information to retrieve if a live product (`ACTIVATE` status) is edited and resent for TikTok Shop review.\n- True: Retrieves the latest version of the product information that is currently under review.\n- False: Retrieves a snapshot of the product information that is live and online (before the edit).\nDefault: False",
"schema": {
"type": "boolean"
}
},
{
"name": "return_draft_version",
"in": "query",
"required": false,
"description": "A flag to indicate what product information to retrieve if a product has a draft in TikTok Shop.\n- True: Retrieves the draft version of the product information.\n- False: Retrieves the latest product information.\nDefault: False\n\n**Note**: \n- Applicable only if the product is in the `DRAFT`, `ACTIVATE`, `SELLER_DEACTIVATED`, or `PLATFORM_DEACTIVATED` status.\n- This field and `return_under_review_version` are mutually exclusive. Specify only one to receive results.",
"schema": {
"type": "boolean"
}
},
{
"name": "locale",
"in": "query",
"required": false,
"description": "The BCP-47 locale codes for displaying category information.\nDefault: The default locale of your shop.\nPossible values:\n- cs-CZ\n- de-AT\n- de-BE\n- de-DE\n- el-GR\n- en-GB\n- en-IE\n- en-US\n- es-ES\n- es-MX\n- fr-FR\n- fr-BE\n- hu-HU\n- id-ID\n- it-IT\n- ja-JP\n- ms-MY\n- nl-NL\n- nl-BE\n- pl-PL\n- pt-BR\n- pt-PT\n- th-TH\n- vi-VN\n- zh-CN",
"schema": {
"type": "string",
"enum": [
"cs-CZ",
"de-AT",
"de-BE",
"de-DE",
"el-GR",
"en-GB",
"en-IE",
"en-US",
"es-ES",
"es-MX",
"fr-FR",
"fr-BE",
"hu-HU",
"id-ID",
"it-IT",
"ja-JP",
"ms-MY",
"nl-NL",
"nl-BE",
"pl-PL",
"pt-BR",
"pt-PT",
"th-TH",
"vi-VN",
"zh-CN"
]
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetProductResponse"
},
"example": {
"code": 0,
"data": {
"audit": {
"pre_approved_reasons": [
"KYC_PENDING"
],
"status": "AUDITING",
"not_submitted_reasons": [
"SHOP_INACTIVE"
]
},
"audit_failed_reasons": [
{
"listing_platform": "TIKTOK_SHOP",
"position": "product",
"reasons": [
"violate listing rules"
],
"suggestions": [
"The product violates TikTok Shopping listing rules, please check and resubmit."
]
}
],
"brand": {
"id": "7082427311584347905",
"name": "brand xxx aaa"
},
"category_chains": [
{
"id": "853000",
"is_leaf": true,
"local_name": "Botol & Stoples Penyimpanan",
"parent_id": "851848"
}
],
"certifications": [
{
"expiration_date": 1741235456,
"files": [
{
"format": "PDF",
"id": "v09ea0g40000cj91373c77u3mid3g1s0",
"name": "CERT_X2.PDF",
"urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
]
}
],
"id": "602362",
"images": [
{
"height": 600,
"thumb_urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
],
"uri": "tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4",
"urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
],
"width": 600
}
],
"title": "SNI Certificate"
}
],
"create_time": 1234567890,
"delivery_options": [
{
"id": "1729592969712203232",
"is_available": true,
"name": "SEND_BY_SELLER"
}
],
"description": "Please compare above detailed size with your measurement before purchase.
\n\n",
"external_product_id": "172959296971220002",
"global_product_association": {
"global_product_id": "1729592969712207920",
"sku_mappings": [
{
"global_sku_id": "1729592969712207234",
"local_sku_id": "1729592969712207230",
"sales_attribute_mappings": [
{
"global_attribute_id": "100000",
"global_value_id": "1001064",
"local_attribute_id": "100000",
"local_value_id": "1001064"
}
]
}
]
},
"has_draft": true,
"id": "1729592969712207008",
"integrated_platform_statuses": [
{
"platform": "TOKOPEDIA",
"status": "PLATFORM_DEACTIVATED"
}
],
"is_cod_allowed": true,
"is_not_for_sale": true,
"is_pre_owned": false,
"is_replicated": false,
"key_product_features": [
"Breathable mesh upper",
"Cushioned foam midsole"
],
"listing_quality_tier": "POOR",
"main_images": [
{
"height": 600,
"thumb_urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
],
"uri": "tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4",
"urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
],
"width": 600
}
],
"manufacturer_ids": [
"172959296971220002"
],
"minimum_order_quantity": 1,
"package_dimensions": {
"height": "10",
"length": "10",
"unit": "CENTIMETER",
"width": "10"
},
"package_weight": {
"unit": "KILOGRAM",
"value": "1.32"
},
"pod_info": {
"pod_templates": [
{
"pod_template_id": "172959296971220002",
"remark": "Front side customization template for basic tee",
"sku_ids": [
"172959296971220002"
],
"surfaces": [
{
"background_image": {
"height": 600,
"thumb_urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
],
"uri": "tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4",
"urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
],
"width": 600
},
"custom_areas": [
{
"area_name": "logo area",
"area_placement": {
"height": "200",
"rotate_degree": "0",
"width": "200",
"x_coordinate": "0",
"y_coordinate": "0"
},
"area_type": "TEXT",
"external_area_id": "172959296971220002",
"image_area": {
"default_image": {
"height": 600,
"thumb_urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
],
"uri": "tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4",
"urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
],
"width": 600
},
"min_height": 300,
"min_width": 300
},
"is_required": false,
"text_area": {
"align_type": "CENTER",
"colors": [
"#FFFFFF"
],
"default_text": "Hello World",
"fonts": [
"Roboto"
],
"max_text_length": 20
}
}
],
"external_surface_id": "172959296971220002",
"mask_image": {
"height": 600,
"thumb_urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
],
"uri": "tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4",
"urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
],
"width": 600
},
"surface_name": "Front Side"
}
],
"template_name": "T-Shirt Front Print"
}
]
},
"prescription_requirement": {
"needs_prescription": false
},
"primary_combined_product_id": "1729592969712207008",
"product_attributes": [
{
"id": "100392",
"name": "Occasion",
"values": [
{
"id": "1001533",
"name": "Birthday",
"metric_standard_info": {
"id": "7678592839487784712",
"metric_value_module_infos": [
{
"id": "7678592839487784712",
"value": "2026",
"unit_id": "7678592839484720903",
"unit_name": "piece",
"suffix": "and",
"prefix": "daily"
}
]
}
}
]
}
],
"product_families": [
{
"id": "1000592969712207000",
"products": [
{
"id": "1729592969712207008"
}
]
}
],
"product_status": "SELLER_DEACTIVATED",
"product_tags": [
"AUCTION"
],
"product_types": [
"COMBINED_PRODUCT"
],
"recommended_categories": [
{
"id": "850003",
"local_name": "\t\nBotol & Stoples Penyimpanan"
}
],
"responsible_person_ids": [
"172959296971220003"
],
"scheduled_sale": {
"is_enabled_scheduled_sale": false,
"schedule_sale_time": 1768899145000
},
"search_terms": [
"sneakers",
"running shoes",
"athletic"
],
"shipping_insurance_requirement": "OPTIONAL",
"shipping_template_id": "7552764259994699538",
"size_chart": {
"image": {
"height": 600,
"thumb_urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
],
"uri": "tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4",
"urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
],
"width": 600
},
"template": {
"id": "7267563252536723205"
}
},
"skus": [
{
"combined_skus": [
{
"brand": {
"id": "7082427311584347905",
"name": "brand xxx aaa"
},
"categories": [
{
"id": "853000",
"is_leaf": true,
"local_name": "Botol & Stoples Penyimpanan",
"parent_id": "851848"
}
],
"combined_listing_not_live_reasons": [
"SUB_PRODUCT_DELETE"
],
"inventory": [
{
"quantity": 999,
"warehouse_id": "6966568648651605766"
}
],
"price": {
"currency": "USD",
"sale_price": "117.5",
"tax_exclusive_price": "110"
},
"product_id": "1729582718312380123",
"product_main_image": {
"height": 600,
"thumb_urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
],
"uri": "tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4",
"urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
],
"width": 600
},
"sales_attributes": [
{
"id": "100000",
"name": "Color",
"sku_img": {
"height": 100,
"thumb_urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
],
"uri": "tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4",
"urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
],
"width": 100
},
"supplementary_sku_images": [
{
"height": 100,
"thumb_urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
],
"uri": "tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4",
"urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
],
"width": 100
}
],
"value_id": "100000",
"value_name": "Red"
}
],
"seller_sku": "sku_name",
"sku_count": 1,
"sku_id": "1729582718312380123",
"title": "Short Boat Invisible Socks"
}
],
"external_list_prices": [
{
"amount": "1",
"currency": "USD",
"source": "SHOPIFY_COMPARE_AT_PRICE"
}
],
"external_sku_id": "1729592969712207234",
"external_urls": [
"https://example.com/path1",
"https://example.com/path2"
],
"extra_identifier_codes": [
"00012345678905",
"9780596520687"
],
"fees": [
{
"additional_attribute": "SINGLE_USE",
"amount": "1.01",
"type": "PFAND"
}
],
"global_listing_policy": {
"inventory_type": "SHARED",
"price_sync": true,
"replicate_source": {
"product_id": "1729592969712203232",
"shop_id": "7295929697122032321",
"sku_id": "1729592969712203232"
}
},
"id": "10001",
"identifier_code": {
"code": "10000000000010",
"type": "GTIN"
},
"inventory": [
{
"backorder_quantity": 888,
"handling_time": 5,
"quantity": 999,
"warehouse_id": "6966568648651605766"
}
],
"list_price": {
"amount": "1",
"currency": "USD"
},
"pre_sale": {
"fulfillment_type": {
"handling_duration_days": 3,
"release_date": 1619611761
},
"type": "PRE_ORDER"
},
"price": {
"currency": "USD",
"sale_price": "117.5",
"starting_bid_price": "2",
"tax_exclusive_price": "110",
"unit_price": "1"
},
"sales_attributes": [
{
"id": "100000",
"name": "Color",
"sku_img": {
"height": 100,
"thumb_urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
],
"uri": "tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4",
"urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
],
"width": 100
},
"supplementary_sku_images": [
{
"height": 100,
"thumb_urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
],
"uri": "tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4",
"urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
],
"width": 100
}
],
"value_id": "100000",
"value_name": "Red"
}
],
"seller_sku": "sku name",
"sku_dimensions": {
"height": "10",
"length": "10",
"unit": "CENTIMETER",
"width": "10"
},
"sku_unit_count": "1.00",
"sku_weight": {
"unit": "KILOGRAM",
"value": "1.32"
},
"status_info": {
"deactivation_source": "PLATFORM",
"status": "DEACTIVATED"
},
"purchase_order_quantity_limit": {
"maximum_order_quantity": 2,
"cumulative_order_quantity": 20
}
}
],
"status": "SELLER_DEACTIVATED",
"subscribe_info": {
"subscribe_discount_details": [
{
"discount_level": "REGULAR",
"discount_value": 10
}
],
"subscribe_promotion_config": [
{
"discount_level": "REGULAR",
"discount_options": [
5,
10,
15,
20
],
"max_discount": 90,
"min_discount": 5
}
],
"subscribe_status": "ENABLED",
"support_subscribe": false
},
"title": "Short Boat Invisible Socks",
"update_time": 1234567899,
"video": {
"cover_url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036",
"format": "MP4",
"height": 480,
"id": "v09ea0g40000cj91373c77u3mid3g1s0",
"size": 1000,
"url": "https://v16m-default.akamaized.net/bbae7099581b26cd340beaa7821b2d8c/64de6020/video/tos/alisg/tos-alisg-v-f466fc-sg/oMne9QuzIBN3fIDN7bFCCMbBKuGigg12ghDC8k/?a=0&ch=0&cr=0&dr=0&er=0&lr=default&cd=0%7C0%7C0%7C0&br=2212&bt=1106&cs=0&ds=3&ft=dl9~j-Inz7TKnfsfiyq8Z&mime_type=video_mp4&qs=13&rc=anR4Ojk6ZmYzbTMzODRmNEBpanR4Ojk6ZmYzbTMzODRmNEBsYWFwcjRva2NgLS1kLy1zYSNsYWFwcjRva2NgLS1kLy1zcw%3D%3D&l=202308171159498F7B108584E58B010932&btag=e00048000",
"width": 1280
},
"selling_format": "FIXED_PRICE",
"is_blind_box": false
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [
{
"code": "12019150",
"message": "The product ID does not exist."
},
{
"code": "12052032",
"message": "The product does not exist"
},
{
"code": "12052048",
"message": "You cannot edit the specified product(s) as it isn't listed in your account or shop."
},
{
"code": "12052260",
"message": "The product ID does not exist"
},
{
"code": "12052547",
"message": "There is no version of this product that is under review. Please obtain the online version."
},
{
"code": "12052704",
"message": "seller id not exist"
},
{
"code": "12052901",
"message": "The product in its current status is not available for this operation. Change the product status and try again."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-product-202309"
}
},
"/product/202309/products/{product_id}/inventory/update": {
"post": {
"operationId": "updateInventory",
"summary": "Update Inventory",
"description": "Update the inventory quantity of SKUs belonging to a product. The product must be in `DRAFT`, `PENDING`, `FAILED`, `ACTIVATE`, or `SELLER_DEACTIVATED` status.",
"tags": [
"Products"
],
"parameters": [
{
"name": "product_id",
"in": "path",
"required": true,
"description": "The product ID generated by TikTok Shop.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateInventoryRequest"
},
"example": {
"skus": [
{
"id": "1729592969712207013",
"inventory": [
{
"warehouse_id": "7068517275539719942",
"quantity": 999,
"backorder_quantity": 888,
"handling_time": 5
}
]
}
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateInventoryResponse"
},
"example": {
"code": 0,
"data": {
"errors": [
{
"code": 12052990,
"message": "Batch update inventory error.",
"detail": {
"sku_id": "1729592969712207013",
"extra_errors": [
{
"warehouse_id": "7068517275539719942",
"code": 12052097,
"message": "The warehouse does not exist"
}
]
}
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Modify"
],
"x-tts-error-codes": [
{
"code": "12019022",
"message": "SKU must contain a valid warehouse."
},
{
"code": "12019024",
"message": "stock count is invalid"
},
{
"code": "12019028",
"message": "Multiple warehouses detected. Include all warehouse IDs and the corresponding details and try again."
},
{
"code": "12052031",
"message": "Invalid product ID(s) found"
},
{
"code": "12052032",
"message": "The product does not exist"
},
{
"code": "12052036",
"message": "The SKU ID is necessary"
},
{
"code": "12052037",
"message": "Couldn't update inventory. Possible causes:\n- Inventory is automatically allocated and cannot be modified manually\n- Warehouse IDs provided are incorrect\n- Missing warehouse IDs (all warehouses that stock the product must be included)"
},
{
"code": "12052048",
"message": "You cannot edit the specified product(s) as it isn't listed in your account or shop."
},
{
"code": "12052050",
"message": "A single product cannot have more than 100 different SKUs"
},
{
"code": "12052055",
"message": "The SKU inventory quantity for the warehouse must be within allowed limits."
},
{
"code": "12052094",
"message": "No multiple warehouse permission"
},
{
"code": "12052096",
"message": "Unable to update the price for SKUs with no warehouse. Assign a warehouse and try again."
},
{
"code": "12052097",
"message": "The warehouse does not exist"
},
{
"code": "12052115",
"message": "seller has no warehouse"
},
{
"code": "12052141",
"message": "please edit stock from global"
},
{
"code": "12052160",
"message": "sku count must be one and disable variables"
},
{
"code": "12052207",
"message": "receipt brand not support warehouse"
},
{
"code": "12052260",
"message": "The product ID does not exist"
},
{
"code": "12052308",
"message": "There's an ongoing appeal. If you wish to edit product details, please revoke the appeal first."
},
{
"code": "12052364",
"message": "The warehouse is unavailable because this product cannot be shipped to the target market from this warehouse."
},
{
"code": "12052371",
"message": "Auction product is bidding when it is not supported to change product info"
},
{
"code": "12052393",
"message": "Product locked for Promotion and stock can't be updated below current stock"
},
{
"code": "12052403",
"message": "The warehouse does not support fulfillment for the current shop."
},
{
"code": "12052465",
"message": "warehouse is unavailable for eu gpr product"
},
{
"code": "12052530",
"message": "The warehouse ' {{warehouse ID}} ' does not belong to this shop/seller."
},
{
"code": "12052531",
"message": "The warehouse is disabled."
},
{
"code": "12052532",
"message": "the warehouse not delivery warehouse"
},
{
"code": "12052533",
"message": "Removal, addition, and change of warehouses are not permitted. Please specify the original warehouses for the SKUs."
},
{
"code": "12052535",
"message": "Couldn't publish this product as you haven't set the return warehouse for your shop. Add the return warehouse information on TikTok Shop Seller Center first and try again."
},
{
"code": "12052553",
"message": "Sku id duplicate"
},
{
"code": "12052556",
"message": "The SKU id not exist."
},
{
"code": "12052700",
"message": "The seller is inactive."
},
{
"code": "12052703",
"message": "Invalid seller tax number"
},
{
"code": "12052704",
"message": "seller id not exist"
},
{
"code": "12052849",
"message": "You don't have the permission to operate combo."
},
{
"code": "12052850",
"message": "The stock of combo does not support being edited."
},
{
"code": "12052901",
"message": "The product in its current status is not available for this operation. Change the product status and try again."
},
{
"code": "12052902",
"message": "The SKU list is empty. Either omit the list entirely, or provide all required details."
},
{
"code": "12052921",
"message": "Couldn't edit the inventory quantity because this product shares the inventory with the source shop"
},
{
"code": "12052990",
"message": "The check failed."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/update-inventory-202309"
}
},
"/product/202309/products/{product_id}/prices/update": {
"post": {
"operationId": "updatePrice",
"summary": "Update Price",
"description": "Update the price of multiple SKUs belonging to a product in the `ACTIVATE` status and not included in any ongoing promotions.\n**Note**: The `data` response field is always empty as there is no additional response data.",
"tags": [
"Products"
],
"parameters": [
{
"name": "product_id",
"in": "path",
"required": true,
"description": "The product ID generated by TikTok Shop.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdatePriceRequest"
},
"example": {
"skus": [
{
"id": "1729592969712207013",
"price": {
"amount": "1.32",
"currency": "USD",
"sale_price": "1.32"
},
"list_price": {
"amount": "1",
"currency": "USD"
},
"external_list_prices": [
{
"source": "SHOPIFY_COMPARE_AT_PRICE",
"amount": "1",
"currency": "USD"
}
]
}
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdatePriceResponse"
},
"example": {
"code": 0,
"data": {},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Modify"
],
"x-tts-error-codes": [
{
"code": "12019022",
"message": "SKU must contain a valid warehouse."
},
{
"code": "12019045",
"message": "price is locked"
},
{
"code": "12019059",
"message": "seller sku is invalid"
},
{
"code": "12019113",
"message": "product status is invalid"
},
{
"code": "12052012",
"message": "Incorrect price format"
},
{
"code": "12052023",
"message": "Category does not exist"
},
{
"code": "12052032",
"message": "The product does not exist"
},
{
"code": "12052038",
"message": "Product price locked due to ongoing promotion."
},
{
"code": "12052048",
"message": "You cannot edit the specified product(s) as it isn't listed in your account or shop."
},
{
"code": "12052073",
"message": "The product price is invalid"
},
{
"code": "12052084",
"message": "The provided currency is not available for this shop/region."
},
{
"code": "12052092",
"message": "product sale price is invalid"
},
{
"code": "12052096",
"message": "Unable to update the price for SKUs with no warehouse. Assign a warehouse and try again."
},
{
"code": "12052097",
"message": "The warehouse does not exist"
},
{
"code": "12052163",
"message": "The gift product are not allowed to be edited"
},
{
"code": "12052260",
"message": "The product ID does not exist"
},
{
"code": "12052308",
"message": "There's an ongoing appeal. If you wish to edit product details, please revoke the appeal first."
},
{
"code": "12052371",
"message": "Auction product is bidding when it is not supported to change product info"
},
{
"code": "12052376",
"message": "list price not support"
},
{
"code": "12052383",
"message": "product list price exceed limit"
},
{
"code": "12052424",
"message": "Missing 'sale price' value"
},
{
"code": "12052531",
"message": "The warehouse is disabled."
},
{
"code": "12052553",
"message": "Sku id duplicate"
},
{
"code": "12052557",
"message": "The SKU ID does not belong to the product."
},
{
"code": "12052570",
"message": "product price exceed limit"
},
{
"code": "12052572",
"message": "the sale price is invalid"
},
{
"code": "12052700",
"message": "The seller is inactive."
},
{
"code": "12052703",
"message": "Invalid seller tax number"
},
{
"code": "12052704",
"message": "seller id not exist"
},
{
"code": "12052861",
"message": "The price of combined SKU cannot exceed the sum of the prices of the sub-SKUs."
},
{
"code": "12052881",
"message": "identity internal error"
},
{
"code": "12052901",
"message": "The product in its current status is not available for this operation. Change the product status and try again."
},
{
"code": "12052902",
"message": "The SKU list is empty. Either omit the list entirely, or provide all required details."
},
{
"code": "12052910",
"message": "Invalid input parameters. Refer to the API documentation for details."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/update-price-202309"
}
},
"/product/202312/global_products/search": {
"post": {
"operationId": "searchGlobalProducts",
"summary": "Search Global Products",
"description": "Retrieve a list of global products that meet the specified conditions. Results are sorted by creation time in descending order. This API returns only key product properties. To obtain more details, pass a returned global product ID to the [Get Global Product API](https://partner.tiktokshop.com/docv2/page/6509e2b0bace3e02b7490c96).",
"tags": [
"Products"
],
"parameters": [
{
"name": "page_size",
"in": "query",
"required": true,
"description": "The number of results to be returned per page. \nValid range: [1-100]",
"schema": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maximum": 100
}
},
{
"name": "page_token",
"in": "query",
"required": false,
"description": "An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the `next_page_token` from a previous response. It is not needed for the first page.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchGlobalProductsRequest"
},
"example": {
"status": "PUBLISHED",
"seller_skus": [
"Color-Red-001"
],
"create_time_ge": 1694576429,
"create_time_le": 1694576429,
"update_time_ge": 1694576429,
"update_time_le": 1694576429
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchGlobalProductsResponse"
},
"example": {
"code": 0,
"data": {
"next_page_token": "b2Zmc2V0PTAK",
"total_count": 100,
"global_products": [
{
"id": "1729592969712207008",
"title": "Men's Fashion Sports Low Cut Cotton Breathable Ankle Short Boat Invisible Socks",
"status": "PUBLISHED",
"skus": [
{
"id": "1729592969712207012",
"seller_sku": "Color-Red-XM001"
}
],
"create_time": 1694576429,
"update_time": 1694576429
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-scenario": 2,
"x-tts-scopes": [
"Global Product Information"
],
"x-tts-error-codes": [
{
"code": "12019015",
"message": "The number of SKU exceed the limit"
},
{
"code": "12019108",
"message": "page number is invalid"
},
{
"code": "12019109",
"message": "page size is invalid"
},
{
"code": "12019118",
"message": "search create time invalid"
},
{
"code": "12019119",
"message": "search update time invalid"
},
{
"code": "12052032",
"message": "The product does not exist"
},
{
"code": "12052180",
"message": "The total number of search results can not exceed 10000."
},
{
"code": "12052700",
"message": "The seller is inactive."
},
{
"code": "12052901",
"message": "The product in its current status is not available for this operation. Change the product status and try again."
},
{
"code": "12052910",
"message": "Invalid input parameters. Refer to the API documentation for details."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-global-products-202312"
}
},
"/product/202312/prerequisites": {
"get": {
"operationId": "checkListingPrerequisites",
"summary": "Check Listing Prerequisites",
"description": "Check if a TikTok shop is ready to list products.\nEach shop needs to satisfy a series of TikTok Shop requirements before you can start listing products. Before you proceed to list products, use this API to check if your shop has satisfied all requirements.\n**Tip**: We recommend that you run this check before any bulk updates to avoid listing issues. For example, sellers may change the delivery option to \"Shipped by seller\" but fail to add a shipping template, thus blocking the shop from listing products. In this case, the API would return `is_failed=true` for the `SHIPPING_TEMPLATE` check item and you can prompt the seller to fix the problem.",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckListingPrerequisitesResponse"
},
"example": {
"code": 0,
"data": {
"check_results": [
{
"check_item": "RETURN_WAREHOUSE",
"is_failed": true,
"fail_reasons": [
"Couldn't publish this product as you haven't set the return warehouse for your shop. Add the return warehouse information on TikTok Shop Seller Center first and try again."
]
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [
{
"code": "33001002",
"message": "internal error"
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/check-listing-prerequisites-202312"
}
},
"/product/202404/images/optimize": {
"post": {
"operationId": "optimizeImages",
"summary": "Optimize Images",
"description": "Optimize images used in your TikTok Shop by changing the background to white.\nThis is especially useful for images displayed in the product image gallery as it enhances product visibility. \n**Note**: \n- The images to be optimized must first be uploaded to TikTok Shop through the [Upload Product Image API](https://partner.tiktokshop.com/docv2/page/6509df95defece02be598a22). You will not be able to optimize any images that are not hosted by TikTok Shop.\n- Images that were previously optimized will not be processed again.\n- The optimization is processed asynchronously and typically completes within a few seconds. If no stored optimization result exists, `optimize_status` is `PROCESSING`, indicating that optimization is underway. If a stored final result already exists, the API may return it immediately. When `optimize_status` is `PROCESSING`, call the API again after a few seconds to get the final optimization status.",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OptimizeImagesRequest"
},
"example": {
"images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/53b55d6e8cdf1f315affa7e70b45707d",
"optimization_mode": [
"WHITE_BACKGROUND"
]
}
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OptimizeImagesResponse"
},
"example": {
"code": 0,
"data": {
"images": [
{
"height": 600,
"width": 600,
"original_uri": "tos-maliva-i-o3syd03w52-us/53b55d6e8cdf1f315affa7e70b45707d",
"original_url": "https://p16-graph-va.ibyteimg.com/tos-maliva-i-1por3rr4fy-us/v2/53b55d6e8cdf1f315affa7e70b45707d~tplv-1por3rr4fy-image.webp",
"optimized_uri": "tos-maliva-i-o3syd03w52-us/0266127022264e54ad2f639f5e0fb5e6",
"optimized_url": "https://p16-graph-va.ibyteimg.com/tos-maliva-i-1por3rr4fy-us/v2/0266127022264e54ad2f639f5e0fb5e6~tplv-1por3rr4fy-image.webp",
"optimize_status": "SUCCESS"
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [
{
"code": "12019065",
"message": "The image URI is invalid. Please use the URI generated by the Upload Product Image API."
},
{
"code": "12019070",
"message": "The optimization mode is invalid."
},
{
"code": "12038007",
"message": "The number of image URIs exceeded the limit of 200."
},
{
"code": "12052722",
"message": "The image URI does not exist in TikTok Shop."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/optimize-images-202404"
}
},
"/product/202405/products/diagnoses": {
"get": {
"operationId": "getProductDiagnoses",
"summary": "Get Product Diagnoses",
"description": "Diagnose multiple existing live (status: `ACTIVATE`) products to obtain information that helps you to improve the product content, enhancing product visibility and customer trust. The returned information includes:\n- Listing quality information (available only for the US market).\n- Issues with the current product details and the overall recommendations\n- Auto-generated optimization suggestions targeted for specific product fields, including the title, description, and image.\n**Note**: This API focuses solely on optimizing product visibility and does not evaluate whether your product meets listing requirements. Quality issues identified by this API do not block your product from being listed. To verify listing requirements, use the [Check Product Listing API](650a0ee8f1fd3102b91c6493).",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "product_ids",
"in": "query",
"required": true,
"description": "The list of product IDs that you want to diagnose.\n\n**Note**:\n- Max number of IDs: 200\n- The product must be live (status: `ACTIVATE`)",
"explode": false,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetProductDiagnosesResponse"
},
"example": {
"code": 0,
"data": {
"products": [
{
"id": "123456",
"listing_quality": {
"current_tier": "POOR",
"remaining_recommendations": 3
},
"diagnoses": [
{
"field": "TITLE",
"diagnosis_results": [
{
"code": "TITLE_LESS_THAN_40_CHARACTERS",
"how_to_solve": "Names must be at least 40 characters long and contain product-identifying information, such as \"hiking boots\" or \"lipstick\".",
"quality_tier": "GOOD"
}
],
"suggestion": {
"seo_words": [
{
"text": "dress"
}
],
"smart_texts": [
{
"text": "this is a good title"
}
],
"images": [
{
"height": 600,
"width": 600,
"uri": "tos-maliva-i-o3syd03w52-us/53b55d6e8cdf1f315affa7e70b45707d",
"url": "https://p16-graph-va.ibyteimg.com/tos-maliva-i-1por3rr4fy-us/v2/53b55d6e8cdf1f315affa7e70b45707d~tplv-1por3rr4fy-image.webp",
"optimized_uri": "tos-maliva-i-o3syd03w52-us/0266127022264e54ad2f639f5e0fb5e6",
"optimized_url": "https://p16-graph-va.ibyteimg.com/tos-maliva-i-1por3rr4fy-us/v2/0266127022264e54ad2f639f5e0fb5e6~tplv-1por3rr4fy-image.webp"
}
]
}
}
]
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Optimization"
],
"x-tts-error-codes": [
{
"code": "12009014",
"message": "seller no permission for product error"
},
{
"code": "12019114",
"message": "Seller has no permission"
},
{
"code": "12019120",
"message": "The number of provided product IDs exceeds the limit."
},
{
"code": "12052260",
"message": "The product ID does not exist"
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-product-diagnoses-202405"
}
},
"/product/202405/products/seo_words": {
"get": {
"operationId": "getProductsSEOWords",
"summary": "Get Products SEO Words",
"description": "Obtain SEO suggestions for product titles of live products (status: `ACTIVATE`) to enhance product visibility.\nApplicable only for the US, UK, and SEA markets.",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "product_ids",
"in": "query",
"required": true,
"description": "The product IDs for which you want to obtain SEO suggestions.\n- Max IDs: 20\n- The product must be live (`ACTIVATE` status)",
"explode": false,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetProductsSEOWordsResponse"
},
"example": {
"code": 0,
"data": {
"products": [
{
"id": "12345",
"seo_words": [
{
"text": "dress"
}
]
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [
{
"code": "12009014",
"message": "seller no permission for product error"
},
{
"code": "12019114",
"message": "Seller has no permission"
},
{
"code": "12019120",
"message": "The number of provided product IDs exceeds the limit."
},
{
"code": "12052260",
"message": "The product ID does not exist"
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-products-seo-words-202405"
}
},
"/product/202405/products/suggestions": {
"get": {
"operationId": "getRecommendedProductTitleAndDescription",
"summary": "Get Recommended Product Title And Description",
"description": "Obtain AI-optimized product titles and descriptions for live products (status: `ACTIVATE`).",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "product_ids",
"in": "query",
"required": true,
"description": "The product IDs for which you want to optimize the information.\n- Max IDs: 20\n- The product must be live (status: `ACTIVATE`)",
"explode": false,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetRecommendedProductTitleAndDescriptionResponse"
},
"example": {
"code": 0,
"data": {
"products": [
{
"id": "123456",
"suggestions": [
{
"field": "TITLE",
"items": [
{
"text": "this is a good title"
}
]
}
]
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Optimization"
],
"x-tts-error-codes": [
{
"code": "12009014",
"message": "seller no permission for product error"
},
{
"code": "12019114",
"message": "Seller has no permission"
},
{
"code": "12019120",
"message": "The number of provided product IDs exceeds the limit."
},
{
"code": "12052260",
"message": "The product ID does not exist"
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-recommended-product-title-and-description-202405"
}
},
"/product/202407/products/category_upgrade_task": {
"post": {
"operationId": "createCategoryUpgradeTask",
"summary": "Create Category Upgrade Task",
"description": "Create a task to upgrade live products (status: `ACTIVATE`) from a 3-level to a 7-level category tree.\nThe task runs for up to 2 hours, depending on the number of products. If the upgrade is incomplete after 2 hours, call the API again. To figure out which products' categories have not been upgraded, call the [Search Product API](https://partner.tiktokshop.com/docv2/page/65854ffb8f559302d8a6acda) and set \"category_version\" to \"v1\".\n**Note**: You must wait at least 24 hours after a product goes live to successfully upgrade its category. If you call this API on the same day a new product goes live, the system will be unable to detect it.",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateCategoryUpgradeTaskRequest"
},
"example": {}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateCategoryUpgradeTaskResponse"
},
"example": {
"code": 0,
"data": {},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [
{
"code": "12052234",
"message": "The number of running tasks exceeds the limit."
},
{
"code": "12052265",
"message": "Category upgrading is not available for your shop."
},
{
"code": "12052700",
"message": "The seller is inactive."
},
{
"code": "35003001",
"message": "access db failed"
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/create-category-upgrade-task-202407"
}
},
"/product/202407/sizecharts/search": {
"post": {
"operationId": "searchSizeCharts",
"summary": "Search Size Charts",
"description": "Retrieve size charts that a seller has created.",
"tags": [
"Products"
],
"parameters": [
{
"name": "page_size",
"in": "query",
"required": true,
"description": "The number of results to be returned per page. \nValid range: [1-100]",
"schema": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maximum": 100
}
},
{
"name": "page_token",
"in": "query",
"required": false,
"description": "An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the `next_page_token` from a previous response. It is not needed for the first page.",
"schema": {
"type": "string"
}
},
{
"name": "locales",
"in": "query",
"required": false,
"description": "The BCP-47 locale codes for displaying the size charts.\nDefault: The default locale of your shop.\nPossible values:\n- de-DE\n- en-GB\n- en-IE\n- en-US\n- es-ES\n- es-MX\n- fr-FR\n- id-ID\n- it-IT\n- ja-JP\n- ms-MY\n- pt-BR\n- th-TH\n- vi-VN\n- zh-CN",
"explode": false,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"de-DE",
"en-GB",
"en-IE",
"en-US",
"es-ES",
"es-MX",
"fr-FR",
"id-ID",
"it-IT",
"ja-JP",
"ms-MY",
"pt-BR",
"th-TH",
"vi-VN",
"zh-CN"
]
}
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchSizeChartsRequest"
},
"example": {
"ids": [
"7362027385890244398"
],
"keyword": "size chart",
"size_chart_mode": "REUSABLE_TEMPLATE"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchSizeChartsResponse"
},
"example": {
"code": 0,
"data": {
"size_chart": [
{
"template_id": "7362027385890244398",
"template_name": "size chart",
"images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe",
"url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036",
"locale": "en-US"
}
],
"related_category_ids": [
"601739",
"601740"
],
"size_chart_datas": [
{
"locale": "en-US",
"size_chart_data": {
"table": {
"headers": [
{
"name": "Bust (cm)",
"id": "size_chart_size_system_size"
}
],
"rows": [
{
"cells": [
{
"value": "M"
}
]
}
]
},
"description": "Use body measurements.",
"is_one_size": false,
"measurement_type": "BODY_MEASUREMENTS",
"unit_system": "METRIC",
"size_types": [
"size_chart_size_type_regular"
]
}
}
],
"size_chart_mode": "REUSABLE_TEMPLATE"
}
],
"next_page_token": "cGFnZV9udW1iZXI9Mg==",
"total_count": 100
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-scenario": 2,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [
{
"code": "12019108",
"message": "page number is invalid"
},
{
"code": "12019109",
"message": "page size is invalid"
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-size-charts-202407"
}
},
"/product/202409/compliance/manufacturers": {
"post": {
"operationId": "createManufacturer",
"summary": "Create Manufacturer",
"description": "Add a manufacturer for a seller. The provided information will be automatically translated into all EU languages supported by TikTok Shop.\n- Use the [Search Manufacturers API](67066a580dcee902fa03ccf9) to obtain the translations.\n- Use the [Partial Edit Manufacturer API](67066a55c55b3a03044eea29) to edit the translations, if necessary.\n- When creating a product, pass the returned `manufacturer_id` to associate the product with the manufacturer.\nTarget seller: Local sellers operating in EU countries",
"tags": [
"Products"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateManufacturerRequest"
},
"example": {
"name": "John Doe",
"registered_trade_name": "TikTok Shop",
"email": "johndoe@email.com",
"phone_number": {
"availability": "AVAILABLE",
"country_code": "+353",
"local_number": "81234567"
},
"address": "10 Earlsfort Terrace, Dublin, Ireland",
"locale": "en-IE"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateManufacturerResponse"
},
"example": {
"code": 0,
"data": {
"manufacturer_id": "66d3cbe4d9c8b09ddca932a7"
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-scenario": 2,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [
{
"code": "38023025",
"message": "Internal error"
},
{
"code": "38023032",
"message": "Number of manufacturers exceeds the limit"
},
{
"code": "38023033",
"message": "Invalid manufacturer's name"
},
{
"code": "38023034",
"message": "Invalid manufacturer's address"
},
{
"code": "38023037",
"message": "Invalid manufacturer's registered trade name"
},
{
"code": "38023041",
"message": "Invalid phone number length"
},
{
"code": "38023042",
"message": "Invalid email format"
},
{
"code": "38023043",
"message": "Invalid address length"
},
{
"code": "38023044",
"message": "Invalid name length"
},
{
"code": "38023045",
"message": "Invalid registered trade name length"
},
{
"code": "38023046",
"message": "Invalid phone country code format"
},
{
"code": "38023050",
"message": "Operation is not supported for global seller"
},
{
"code": "38023060",
"message": "Invalid phone number availability. Supported values: `AVAILABLE`, `UNAVAILABLE`"
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/create-manufacturer-202409"
}
},
"/product/202409/compliance/manufacturers/{manufacturer_id}/partial_edit": {
"post": {
"operationId": "partialEditManufacturer",
"summary": "Partial Edit Manufacturer",
"description": "Edit the details of a manufacturer in the EU languages supported by TikTok Shop. Include the locale code to edit the manufacturer's information in a particular language.\nTarget seller: Local sellers operating in EU countries\n**Note**:\n- The manufacturer name, registered trade name, email address, local phone number, and the address field must not contain Chinese characters.\n- Updates are handled per top-level property, so all non-empty fields within an updated object must be supplied to prevent overwriting with blanks.\n- For top-level properties (e.g. `name`, `email`) that are not nested in an object, you can update them individually. Omitting these properties in the request will leave them unchanged.\n- If you need to edit any nested property within an object, you must provide values for all nested properties of that object. Any omitted nested properties will be overwritten with blanks. For an available phone number, provide `availability=AVAILABLE`, `country_code`, and `local_number` together. If `availability=UNAVAILABLE` is supported for the seller, provide `availability=UNAVAILABLE` and omit `country_code` and `local_number`; otherwise, a valid phone number is still required.",
"tags": [
"Products"
],
"parameters": [
{
"name": "manufacturer_id",
"in": "path",
"required": true,
"description": "The manufacturer ID in TikTok Shop.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PartialEditManufacturerRequest"
},
"example": {
"name": "John Doe",
"registered_trade_name": "TikTok Shop",
"email": "johndoe@email.com",
"phone_number": {
"availability": "AVAILABLE",
"country_code": "+353",
"local_number": "81234567"
},
"address": "10 Earlsfort Terrace, Dublin, Ireland",
"locale": "en-IE"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PartialEditManufacturerResponse"
},
"example": {
"code": 0,
"data": {},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-scenario": 2,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [
{
"code": "38023025",
"message": "Internal error"
},
{
"code": "38023033",
"message": "Invalid manufacturer's name"
},
{
"code": "38023034",
"message": "Invalid manufacturer's address"
},
{
"code": "38023037",
"message": "Invalid manufacturer's registered trade name"
},
{
"code": "38023041",
"message": "Invalid phone number length"
},
{
"code": "38023042",
"message": "Invalid email format"
},
{
"code": "38023043",
"message": "Invalid address length"
},
{
"code": "38023044",
"message": "Invalid name length"
},
{
"code": "38023045",
"message": "Invalid registered trade name length"
},
{
"code": "38023046",
"message": "Invalid phone country code format"
},
{
"code": "38023050",
"message": "Operation is not supported for global seller"
},
{
"code": "38023051",
"message": "Resource not found"
},
{
"code": "38023052",
"message": "Seller is not authorised to access resource"
},
{
"code": "38023060",
"message": "Invalid phone number availability. Supported values: `AVAILABLE`, `UNAVAILABLE`"
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/partial-edit-manufacturer-202409"
}
},
"/product/202409/compliance/responsible_persons": {
"post": {
"operationId": "createResponsiblePerson",
"summary": "Create Responsible Person",
"description": "Add a new EU responsible person who ensures a seller's products comply with EU regulations. The provided information will be automatically translated into all EU languages supported by TikTok Shop.\n- Use the [Search Responsible Persons API](67066a55f17b7d02f95d2fb1) to obtain the translations.\n- Use the [Partial Edit Responsible Person API](67066a5587019802fdce19b3) to edit the translations, if necessary.\n- When creating a product, pass the returned `responsible_person_id` to associate the product with the responsible person.\n\nTarget seller: Local sellers operating in EU countries",
"tags": [
"Products"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateResponsiblePersonRequest"
},
"example": {
"name": "John Doe",
"email": "john.doe@email.com",
"phone_number": {
"country_code": "+353",
"local_number": "80915151"
},
"address": {
"street_address_line1": "63 Cardiff Ln, Grand Canal Dock, Dublin City, Dublin",
"street_address_line2": "-",
"district": "-",
"city": "-",
"postal_code": "D02 HD23",
"province": "-",
"country": "IE"
},
"locale": "en-IE"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateResponsiblePersonResponse"
},
"example": {
"code": 0,
"data": {
"responsible_person_id": "66d3cbe4d9c8b09ddca023f1"
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-scenario": 2,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [
{
"code": "38023022",
"message": "Invalid responsible person's name"
},
{
"code": "38023024",
"message": "Invalid responsible person's address"
},
{
"code": "38023025",
"message": "Internal error"
},
{
"code": "38023026",
"message": "Invalid EU country"
},
{
"code": "38023027",
"message": "Number of responsible person exceeds the limit"
},
{
"code": "38023028",
"message": "Invalid EU phone country code"
},
{
"code": "38023041",
"message": "Invalid phone number length"
},
{
"code": "38023042",
"message": "Invalid email format"
},
{
"code": "38023043",
"message": "Invalid address length"
},
{
"code": "38023044",
"message": "Invalid name length"
},
{
"code": "38023050",
"message": "Operation is not supported for global seller"
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/create-responsible-person-202409"
}
},
"/product/202409/compliance/responsible_persons/{responsible_person_id}/partial_edit": {
"post": {
"operationId": "partialEditResponsiblePerson",
"summary": "Partial Edit Responsible Person",
"description": "Edit the details of an EU responsible person in the EU languages supported by TikTok Shop. Include the locale code to edit the responsible person's information in a particular language.\nTarget seller: Local sellers operating in EU countries\n**Note**:\n- Updates are handled per top-level property, so all non-empty fields within an updated object must be supplied to prevent overwriting with blanks.\n- For top-level properties (e.g. `name`, `email`) that are not nested in an object, you can update them individually. Omitting these properties in the request will leave them unchanged.\n- If you need to edit any nested property within an object, you must provide values for all nested properties of that object. Any omitted nested properties will be overwritten with blanks. For example, if you want to update `phone_number.local_number`, you must also include the `country_code` property to avoid data loss for that property.",
"tags": [
"Products"
],
"parameters": [
{
"name": "responsible_person_id",
"in": "path",
"required": true,
"description": "The responsible person ID in TikTok Shop.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PartialEditResponsiblePersonRequest"
},
"example": {
"name": "John Doe",
"email": "john.doe@email.com",
"phone_number": {
"country_code": "+353",
"local_number": "80915151"
},
"address": {
"street_address_line1": "63 Cardiff Ln, Grand Canal Dock, Dublin City, Dublin",
"street_address_line2": "-",
"district": "-",
"city": "-",
"postal_code": "D02 HD23",
"province": "-",
"country": "IE"
},
"locale": "en-IE"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PartialEditResponsiblePersonResponse"
},
"example": {
"code": 0,
"data": {},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-scenario": 2,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [
{
"code": "38023022",
"message": "Invalid responsible person's name"
},
{
"code": "38023024",
"message": "Invalid responsible person's address"
},
{
"code": "38023025",
"message": "Internal error"
},
{
"code": "38023026",
"message": "Invalid EU country"
},
{
"code": "38023028",
"message": "Invalid EU phone country code"
},
{
"code": "38023041",
"message": "Invalid phone number length"
},
{
"code": "38023042",
"message": "Invalid email format"
},
{
"code": "38023043",
"message": "Invalid address length"
},
{
"code": "38023044",
"message": "Invalid name length"
},
{
"code": "38023050",
"message": "Operation is not supported for global seller"
},
{
"code": "38023051",
"message": "Resource not found"
},
{
"code": "38023052",
"message": "Seller is not authorised to access resource"
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/partial-edit-responsible-person-202409"
}
},
"/product/202411/products/diagnose_optimize": {
"post": {
"operationId": "diagnoseAndOptimizeProduct",
"summary": "Diagnose and Optimize Product",
"description": "Diagnose products to obtain information that helps you to improve the product content, enhancing product visibility and customer trust. The returned information includes:\n- Listing quality information (available only for the US market).\n- Issues with the current product details and the overall recommendations\n- Auto-generated optimization suggestions targeted for specific product fields, including the title, description, and image.\nThis API enables you to diagnose both live products (status: `ACTIVATE`) and brand-new products not yet listed in TikTok Shop.\n- To diagnose a **live product**, provide the `product_id` and `category_id` and leave all other product details blank.\n- To diagnose a **brand-new product** not yet listed in TikTok Shop, omit the `product_id` and provide the product details as necessary.\n- To diagnose a **product similar to an existing one**, provide the `product_id` and `category_id`, along with any new details. The diagnosis will combine the existing product's information with the new details you provide. For example, if you provide a new `title`, the diagnosis will use the new title instead of the existing one while keeping the other values from the product ID.\n**Note**: \n- To diagnose multiple live products, use the [Product Information Issue Diagnosis API](665048f380b6b302e73917d9).\n- This API focuses solely on optimizing product visibility and does not evaluate whether your product meets listing requirements. Quality issues identified by this API do not block your product from being listed. To verify listing requirements, use the [Check Product Listing API](650a0ee8f1fd3102b91c6493).",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DiagnoseAndOptimizeProductRequest"
},
"example": {
"product_id": "1729592969712203232",
"category_id": "600001",
"description": "Please check the measurements before purchase.
\n ",
"brand_id": "7082427311584347905",
"main_images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
],
"title": "Men's Fashion Sports Low Cut Cotton Breathable Ankle Short Boat Invisible Socks",
"product_attributes": [
{
"id": "100392",
"values": [
{
"id": "1001533",
"name": "Birthday"
}
]
}
],
"size_chart": {
"template": {
"id": "7267563252536723205"
},
"image": {
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe\n"
}
},
"optimization_fields": [
"ALL"
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DiagnoseAndOptimizeProductResponse"
},
"example": {
"code": 0,
"data": {
"listing_quality": {
"current_tier": "POOR",
"remaining_recommendations": 3
},
"diagnoses": [
{
"field": "TITLE",
"diagnosis_results": [
{
"code": "TITLE_LESS_THAN_40_CHARACTERS",
"how_to_solve": "Names must be at least 40 characters long and contain product-identifying information, such as \"hiking boots\" or \"lipstick\".",
"quality_tier": "FAIR"
}
],
"suggestion": {
"seo_words": [
{
"text": "dress"
}
],
"smart_texts": [
{
"text": "this is a good title"
}
],
"images": [
{
"height": 600,
"width": 600,
"uri": "tos-maliva-i-o3syd03w52-us/53b55d6e8cdf1f315affa7e70b45707d",
"url": "https://p16-graph-va.ibyteimg.com/tos-maliva-i-1por3rr4fy-us/v2/53b55d6e8cdf1f315affa7e70b45707d~tplv-1por3rr4fy-image.webp",
"optimized_uri": "tos-maliva-i-o3syd03w52-us/0266127022264e54ad2f639f5e0fb5e6",
"optimized_url": "https://p16-graph-va.ibyteimg.com/tos-maliva-i-1por3rr4fy-us/v2/0266127022264e54ad2f639f5e0fb5e6~tplv-1por3rr4fy-image.webp"
}
]
}
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Optimization"
],
"x-tts-error-codes": [],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/diagnose-and-optimize-product-202411"
}
},
"/product/202501/compliance/manufacturers/search": {
"post": {
"operationId": "searchManufacturers",
"summary": "Search Manufacturers",
"description": "Retrieve a list of manufacturers in the EU languages supported by TikTok Shop based on their IDs or keyword.\nWhen creating a product with the [Create Product API](https://partner.tiktokshop.com/docv2/page/6502fc8da57708028b42b18a), pass a returned manufacturer's `id` as an element of `manufacturer_ids`.\nTarget seller: Local sellers operating in EU countries",
"tags": [
"Products"
],
"parameters": [
{
"name": "page_size",
"in": "query",
"required": true,
"description": "The number of results to be returned per page. \nValid range: [1-100]",
"schema": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maximum": 100
}
},
{
"name": "page_token",
"in": "query",
"required": false,
"description": "An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the `next_page_token` from a previous response. It is not needed for the first page.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchManufacturersRequest"
},
"example": {
"manufacturer_ids": [
"66d3cbe4d9c8b09ddca932a7"
],
"keyword": "John",
"locales": [
"en-IE",
"es-ES"
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchManufacturersResponse"
},
"example": {
"code": 0,
"data": {
"manufacturers": [
{
"id": "66d3cbe4d9c8b09ddca932a7",
"regional_profiles": [
{
"locale": "en-IE",
"name": "John Doe",
"registered_trade_name": "TikTok Shop",
"email": "johndoe@email.com",
"phone_number": {
"availability": "AVAILABLE",
"country_code": "+353",
"local_number": "81234567"
},
"address": "10 Earlsfort Terrace, Dublin, Ireland"
}
]
}
],
"total_count": 26,
"next_page_token": "66d3cbe3d9c8b09ddca932a1"
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-scenario": 2,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [
{
"code": "38023025",
"message": "Internal error"
},
{
"code": "38023047",
"message": "Invalid page size"
},
{
"code": "38023048",
"message": "Invalid page token"
},
{
"code": "38023049",
"message": "The number of ids is larger than page size"
},
{
"code": "38023050",
"message": "Operation is not supported for global seller"
},
{
"code": "38023057",
"message": "Unsupported locale"
},
{
"code": "38023060",
"message": "Invalid phone number availability. Supported values: `AVAILABLE`, `UNAVAILABLE`"
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-manufacturers-202501"
}
},
"/product/202501/compliance/responsible_persons/search": {
"post": {
"operationId": "searchResponsiblePersons",
"summary": "Search Responsible Persons",
"description": "Retrieve a list of responsible persons in the EU languages supported by TikTok Shop based on their ID or keywords.\nWhen creating a product with the [Create Product API](https://partner.tiktokshop.com/docv2/page/6502fc8da57708028b42b18a), pass a returned responsible person's `id` as an element of `responsible_person_ids`.\nTarget seller: Local sellers operating in EU countries",
"tags": [
"Products"
],
"parameters": [
{
"name": "page_size",
"in": "query",
"required": true,
"description": "The number of results to be returned per page. \nValid range: [1-100]",
"schema": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maximum": 100
}
},
{
"name": "page_token",
"in": "query",
"required": false,
"description": "An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the `next_page_token` from a previous response. It is not needed for the first page.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponsiblePersonsRequest"
},
"example": {
"responsible_person_ids": [
"66d3cbe4d9c8b09ddca932a7"
],
"keyword": "John",
"locales": [
"en-IE",
"es-ES"
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchResponsiblePersonsResponse"
},
"example": {
"code": 0,
"data": {
"responsible_persons": [
{
"id": "66d3cbe4d9c8b09ddca932a7",
"regional_profiles": [
{
"locale": "en-IE",
"name": "John Doe",
"email": "john.doe@email.com",
"phone_number": {
"country_code": "+353",
"local_number": "80915151"
},
"address": {
"street_address_line1": "63 Cardiff Ln, Grand Canal Dock, Dublin City, Dublin",
"street_address_line2": "-",
"district": "-",
"city": "-",
"postal_code": "D02 HD23",
"province": "-",
"country": "IE"
}
}
]
}
],
"total_count": 26,
"next_page_token": "66d3cbe3d9c8b09ddca932a1"
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-scenario": 2,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [
{
"code": "38023025",
"message": "Internal error"
},
{
"code": "38023047",
"message": "Invalid page size"
},
{
"code": "38023048",
"message": "Invalid page token"
},
{
"code": "38023049",
"message": "The number of ids is larger than page size"
},
{
"code": "38023050",
"message": "Operation is not supported for global seller"
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-responsible-persons-202501"
}
},
"/product/202502/products/search": {
"post": {
"operationId": "searchProducts",
"summary": "Search Products",
"description": "Retrieve a list of products that meet the specified conditions. \nThis API will only return the key product properties. You can pass a returned product ID to the [Get Product API](https://partner.tiktokshop.com/docv2/page/6509d85b4a0bb702c057fdda) to obtain more details about the product.",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "page_size",
"in": "query",
"required": true,
"description": "The number of results to be returned per page. \nValid range: [1-100]",
"schema": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maximum": 100
}
},
{
"name": "page_token",
"in": "query",
"required": false,
"description": "An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the `next_page_token` from a previous response. It is not needed for the first page.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchProductsRequest"
},
"example": {
"status": "ALL",
"seller_skus": [
"Color-Red-XM001"
],
"create_time_ge": 1694309208,
"create_time_le": 1694319208,
"update_time_ge": 1694319208,
"update_time_le": 1694319208,
"category_version": "v1",
"listing_quality_tiers": [
"POOR",
"FAIR"
],
"listing_platforms": [
"TIKTOK_SHOP"
],
"audit_status": [
"AUDITING"
],
"sku_ids": [
"1729592969712207230"
],
"sns_filter": "CONFIGURED",
"return_draft_version": true,
"locale": "en-US",
"include_live_quick_products": false
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchProductsResponse"
},
"example": {
"code": 0,
"data": {
"total_count": 200,
"products": [
{
"id": "1729592969712207008",
"title": "Short Boat Invisible Socks",
"status": "ACTIVATE",
"skus": [
{
"id": "1729592969712207012",
"seller_sku": "Color-Red-XM01",
"price": {
"currency": "USD",
"tax_exclusive_price": "111.01",
"sale_price": "121.11",
"starting_bid_price": "2"
},
"inventory": [
{
"warehouse_id": "7068517275539719942",
"quantity": 999,
"backorder_quantity": 888,
"handling_time": 5
}
],
"list_price": {
"amount": "1",
"currency": "USD"
},
"external_list_prices": [
{
"source": "SHOPIFY_COMPARE_AT_PRICE",
"amount": "1",
"currency": "USD"
}
],
"pre_sale": {
"type": "PRE_ORDER",
"fulfillment_type": {
"handling_duration_days": 7,
"release_date": 1619611761
}
},
"status_info": {
"status": "DEACTIVATED",
"deactivation_source": "PLATFORM"
},
"fees": [
{
"type": "PFAND",
"amount": "1.01",
"additional_attribute": "SINGLE_USE"
}
]
}
],
"sales_regions": [
"US"
],
"create_time": 1234567890,
"update_time": 1234567800,
"product_sync_fail_reasons": [
"The required qualification is missed."
],
"is_not_for_sale": true,
"recommended_categories": [
{
"id": "853000",
"local_name": "Botol & Stoples Penyimpanan"
}
],
"listing_quality_tier": "POOR",
"integrated_platform_statuses": [
{
"platform": "TOKOPEDIA",
"status": "PLATFORM_DEACTIVATED"
}
],
"audit": {
"status": "AUDITING",
"pre_approved_reasons": [
"KYC_PENDING"
]
},
"product_families": [
{
"id": "1000592969712207000",
"products": [
{
"id": "1729592969712207008"
}
]
}
],
"has_draft": true,
"scheduled_sale": {
"is_enabled_scheduled_sale": false,
"schedule_sale_time": 1768899145000
},
"product_tags": [
"AUCTION"
],
"selling_format": "FIXED_PRICE"
}
],
"next_page_token": "WzE3ODY0Njk5NDg1MTgsIjE3MzY5OTA2MTM0NTI5ODE4MTciXQ=="
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [
{
"code": "12019027",
"message": "The maximum count of “seller_skus” in the search filter is 10."
},
{
"code": "12019087",
"message": "The number of SKU IDs exceeds the limit of 10"
},
{
"code": "12019108",
"message": "page number is invalid"
},
{
"code": "12019109",
"message": "page size is invalid"
},
{
"code": "12019118",
"message": "search create time invalid"
},
{
"code": "12019119",
"message": "search update time invalid"
},
{
"code": "12052180",
"message": "The total number of search results can not exceed 10000."
},
{
"code": "12052700",
"message": "The seller is inactive."
},
{
"code": "12052704",
"message": "seller id not exist"
},
{
"code": "12052910",
"message": "Invalid input parameters. Refer to the API documentation for details."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-products-202502"
}
},
"/product/202505/images/translation_tasks": {
"post": {
"operationId": "createImageTranslationTasks",
"summary": "Create Image Translation Tasks",
"description": "Initiates a translation task for one or more images. This asynchronous API queues the images for processing in the specified target language. \nApplicable only for sellers that sell across EU.\nUse the [Image Translation Completed webhook](684f8d9bcc4e44049347a12e) to monitor the translation progress, or pass the task ID to the [Get Image Translation Tasks API](684f8b2d535a9d048f234564) to retrieve the status and the translated images.\n**Note**: \n- Please wait 5 minutes after task creation before calling the Get endpoint, and retry at intervals over 10 seconds to avoid rate limiting.\n- Each task corresponds to the translation of 1 image into 1 target language.\n- You can create up to 20 tasks per call and 500 tasks per day. Any tasks beyond the daily limit will be rejected.",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateImageTranslationTasksRequest"
},
"example": {
"images": [
{
"image_uri": "tos-useast2a-i-tulkllf4y5-euttp/748e39ecff38453ab8396a36a53dbb92",
"target_languages": [
"it-IT",
"fr-FR"
]
}
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateImageTranslationTasksResponse"
},
"example": {
"code": 0,
"data": {
"translation_tasks": [
{
"image_uri": "tos-useast2a-i-tulkllf4y5-euttp/748e39ecff38453ab8396a36a53dbb92",
"target_language": "it-IT",
"id": "764c6e87eedcea90399a0dafcd572b71"
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Optimization"
],
"x-tts-error-codes": [
{
"code": "12038008",
"message": "The image URI is invalid. Please use the URI generated by the Upload Product Image API."
},
{
"code": "12038009",
"message": "The specified `target_language` is invalid or unsupported."
},
{
"code": "12038010",
"message": "The number of translation task IDs exceeded the limit of 20."
},
{
"code": "12038012",
"message": "Exceeded the daily limit of 500 translation tasks."
},
{
"code": "12038013",
"message": "This operation is not available for this shop."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/create-image-translation-tasks-202505"
}
},
"/product/202506/images/translation_tasks": {
"get": {
"operationId": "getImageTranslationTasks",
"summary": "Get Image Translation Tasks",
"description": "Retrieves the image translation task status and translated images for one or more previously submitted images.\n**Note**: Please wait 5 minutes after [task creation](684f8b2d6e0b37048b2448b4) before calling this API, and retry at intervals over 10 seconds to avoid rate limiting.\nApplicable only for sellers that sell across EU.",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "translation_task_ids",
"in": "query",
"required": false,
"description": "The image translation task IDs for retrieving translation results.\nMax count: 20",
"explode": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 20
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetImageTranslationTasksResponse"
},
"example": {
"code": 0,
"data": {
"translation_tasks": [
{
"original_image": {
"uri": "tos-useast2a-i-tulkllf4y5-euttp/748e39ecff38453ab8396a36a53dbb92",
"url": "https://p16-oec-sg.ibyteimg.com/tos-alisg-i-aphluv4xwc-sg/sample.jpeg"
},
"id": "764c6e87eedcea90399a0dafcd572b71",
"target_language": "it-IT",
"status": "COMPLETED",
"fail_reason": "This image can't be translated. Try a different image.",
"translated_image": {
"uri": "tos-maliva-i-o3syd03w52-us/53b55d6e8cdf1f315affa7e70b45707d",
"url": "https://p16-oec-sg.ibyteimg.com/tos-alisg-i-aphluv4xwc-sg/sample.jpeg"
}
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Optimization"
],
"x-tts-error-codes": [
{
"code": "12038010",
"message": "The number of translation task IDs exceeded the limit of 20."
},
{
"code": "12038011",
"message": "The translation task ID is invalid."
},
{
"code": "12038013",
"message": "This operation is not available for this shop."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-image-translation-tasks-202506"
}
},
"/product/202507/global_listing_rules": {
"get": {
"operationId": "getGlobalListingRules",
"summary": "Get Global Listing Rules",
"description": "Retrieves the global listing rules for a local shop that belongs to a global seller. E.g. The supported listing methods or the inventory allocation rules. The rules differ by the markets they serve.\n**Note**: Applicable only for global sellers.",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetGlobalListingRulesResponse"
},
"example": {
"code": 0,
"data": {
"listing_methods": [
"GLOBAL_PUBLISHING"
],
"inventory_rules": [
{
"local_warehouse_id": "7068517275539719942",
"allocation_mode": "SHARED",
"associated_warehouses": [
{
"warehouse_id": "7068517275539718842",
"region": "DE"
}
]
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-global-listing-rules-202507"
}
},
"/product/202507/products/{product_id}/global_replicate": {
"post": {
"operationId": "replicateProduct",
"summary": "Replicate Product",
"description": "Description of [POST]/product/:version/Replicate_Product",
"tags": [
"Products"
],
"parameters": [
{
"name": "product_id",
"in": "path",
"required": true,
"description": "The product ID in TikTok Shop.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReplicateProductRequest"
},
"example": {
"inventory_mode": "SHARED",
"replicate_target": [
{
"certifications": [
{
"expiration_date": 1741234626,
"files": [
{
"format": "PDF",
"id": "v09ea0g40000cj91373c77u3mid3g1s0",
"name": "brand_cert.PDF"
}
],
"id": "7182427311584347905",
"images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
]
}
],
"inventory_mode": "SHARED",
"manufacturer_ids": [
"172959296971220002"
],
"product_attributes": [
{
"id": "100392",
"values": [
{
"id": "1001533",
"name": "Birthday"
}
]
}
],
"region": "US",
"responsible_person_ids": [
"172959296971220003"
],
"skus": [
{
"inventory": [
{
"quantity": 100,
"warehouse_id": "1732057700058170433"
}
],
"price": {
"currency": "EUR",
"sale_price": "100"
},
"source_sku_id": "1732057700058170433",
"seller_sku": "Color-Red-XM01"
}
]
}
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReplicateProductResponse"
},
"example": {
"code": 0,
"data": {
"errors": [
{
"code": 12052223,
"detail": {
"region": "US"
},
"message": "the category is unauthorized."
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Modify"
],
"x-tts-error-codes": [
{
"code": "12052500",
"message": "A replica already exists for this product in the stated region. Only one replica is allowed per region."
},
{
"code": "12052501",
"message": "This operation is only available for shops using the LOCAL_REPLICATION listing method. Your shop is currently using the GLOBAL_PUBLISHING method."
},
{
"code": "12052503",
"message": "If the inventory allocation mode is SHARED, the inventory quantity must be the same across all SKUs."
},
{
"code": "12052518",
"message": "The number of SKUs provided do not match that of the source product. Please ensure that you provide complete SKU data."
},
{
"code": "12052930",
"message": "Seller SKU is required"
},
{
"code": "12052936",
"message": "Seller SKU format invalid. SKU name must contain 6 - 50 characters and use alphabets, numbers, hyphens (-), or underscores (_) only."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/replicate-product-202507"
}
},
"/product/202507/products/{product_id}/replicated_products": {
"get": {
"operationId": "getGlobalReplicatedProducts",
"summary": "Get Global Replicated Products",
"description": "Retrieves the globally associated replicas in other markets if the product has been replicated through local replication.\nApplicable only for global sellers.",
"tags": [
"Products"
],
"parameters": [
{
"name": "product_id",
"in": "path",
"required": true,
"description": "The ID of the product.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetGlobalReplicatedProductsResponse"
},
"example": {
"code": 0,
"data": {
"replicated_products": [
{
"region": "US",
"shop_id": "1732057700058170433",
"product_id": "1732057700058170433",
"product_status": "ACTIVATE"
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-global-replicated-products-202507"
}
},
"/product/202509/global_products/{global_product_id}/partial_edit": {
"put": {
"operationId": "partialEditGlobalProduct",
"summary": "Partial Edit Global Product",
"description": "Partially update an existing global product. Only the fields included in the request are considered for update. If the global product is linked to local products, applicable changes are also synchronized to those markets; check `publish_results` for each market's synchronization result.",
"tags": [
"Products"
],
"parameters": [
{
"name": "global_product_id",
"in": "path",
"required": true,
"description": "The global product ID generated by TikTok Shop.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PartialEditGlobalProductRequest"
},
"example": {
"title": "Men's Fashion Sports Low Cut Cotton Breathable Ankle Short Boat Invisible Socks",
"description": " ",
"category_id": "600001",
"brand_id": "7082427311584347905",
"main_images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
],
"skus": [
{
"id": "1782427311584347905",
"global_quantity": 999,
"seller_sku": "Color-Red-XM01",
"price": {
"amount": "1.32",
"currency": "USD"
},
"sales_attributes": [
{
"id": "100089",
"name": "Specification",
"value_id": "1729592969712207000",
"value_name": "XL",
"sku_img": {
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
}
],
"inventory": [
{
"global_warehouse_id": "7068517275539719942",
"quantity": 999
}
],
"identifier_code": {
"code": "10000000000000",
"type": "GTIN"
},
"sku_unit_count": "1",
"extra_identifier_codes": [
"12345678901234"
],
"external_global_sku_id": "1234567890",
"sale_prices": [
{
"region": "US",
"amount": "100"
}
]
}
],
"package_weight": {
"value": "1.99",
"unit": "KILOGRAM"
},
"certifications": [
{
"id": "7182427311584347905",
"images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
],
"files": [
{
"id": "v09ea0g40000cj91373c77u3mid3g1s0",
"name": "SNI.PDF",
"format": "PDF"
}
]
}
],
"package_dimensions": {
"length": "10",
"width": "10",
"height": "10",
"unit": "CENTIMETER"
},
"product_attributes": [
{
"id": "100392",
"values": [
{
"id": "1001533",
"name": "Birthday"
}
]
}
],
"size_chart": {
"image": {
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
},
"template": {
"id": "7267563252536723205"
}
},
"video": {
"id": "v09e40f40000cfu0ovhc77ub7fl97k4w"
},
"manufacturer": {
"name": "Sample Manufacturer Name",
"address": "123W 106th St, New York, NY, USA, 10025",
"phone_number": "+1-2124108036\n",
"email": "samplemanufacturer101@outlook.com"
},
"manufacturer_ids": [
"67726293bf1eb1e92401a"
],
"responsible_person_ids": [
"67726293bf1eb1e92401a"
],
"category_version": "v1",
"external_global_product_id": "123456789"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PartialEditGlobalProductResponse"
},
"example": {
"code": 0,
"data": {
"global_skus": [
{
"id": "1729592969712207012",
"seller_sku": "Color-Red-XM01",
"sales_attributes": [
{
"id": "100000",
"value_id": "1729592969712207123"
}
],
"external_global_sku_id": "1234567890"
}
],
"publish_results": [
{
"region": "MY",
"status": "SUCCESS",
"fail_reasons": [
{
"message": "The publish region is inactive."
}
]
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-scenario": 2,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/partial-edit-global-product-202509"
}
},
"/product/202509/products/{product_id}": {
"put": {
"operationId": "editProduct",
"summary": "Edit Product",
"description": "Edit all properties (e.g. description, brand, images) of an existing product that is not in the `FREEZE` or `DELETED` state.\nAfter editing the product, the latest product content (referred to as v2) will be resent for audit review. If the audit passes, v2 is published to the shop, otherwise, the existing product stays live and remains unchanged (keeping v1). However, edits to the `price` or `inventory` fields do not require a reaudit and will be immediately published on the platform. Use the [Product status change](https://partner.tiktokshop.com/docv2/page/650956aff1fd3102b90b6261) webhook to keep track of the review status.\n**Note**: \n- This API is applicable only for **active sellers/shops** that have completed the KYC onboarding process.\n- There may be a limit to the number of products you can relist per day. We recommend prioritizing key products first to ensure they get published. You can find your listing limit on the Seller Center homepage.\n- All inputs, including blanks, in the request payload will overwrite existing values. To retain an existing value, make sure to include it in your request. Exceptions to this rule are the `price` and `inventory` fields, which will remain unchanged if they are omitted from the request. Therefore, **it is strongly recommended to retrieve the latest product data using [Get Product](6509d85b4a0bb702c057fdda) and submit the complete data when editing**. This ensures accuracy and helps avoid errors or unintentional data loss due to missing fields.\n- If you wish to edit only certain properties, you can use the [Partial Edit Product API](650a98d74a0bb702c06c3289), [Update Inventory API](6503068fc20ad60284b38858), or the [Update Price API](650307de5a12ff0294eac8b0).\n- The language used in the product content must align with the target market's language (e.g. don't use Chinese), otherwise the listing will fail or be rejected.\n**For global sellers**:\nIf you're using the local replication listing method, note the following sync rules:\n- To sync any changes to other markets, please provide the `seller_sku` and complete `replicated_products` data. \n- Note that **category changes** and **sales attribute changes** (in sales attribute id/name) must be synced to other markets. The API call will fail if you don't provide these details.\n**For Tokopedia sellers**:\nNote that a product can have **only one active version** across all platforms at any time. If a product is live on both platforms, audit results for the latest version are handled as follows:\n- **Mixed audit results**: If the product passes audit on one platform but fails on another, on the successful platform, the product will stay live and be updated with content from the latest version (v2), while on the failed platform, the product will be deactivated and hidden entirely.\n- **Audit failure on all platforms**: If the product fails audit on all platforms, the existing product stays live and remains unchanged (keeping v1).",
"tags": [
"Products"
],
"parameters": [
{
"name": "product_id",
"in": "path",
"required": true,
"description": "The product ID generated by TikTok Shop.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EditProductRequest"
},
"example": {
"save_mode": "AS_DRAFT",
"description": " Please compare above detailed size with your measurement before purchase.
\n",
"category_id": "600001",
"brand_id": "7082427311584347905",
"main_images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
],
"skus": [
{
"id": "1729592969712207000",
"sales_attributes": [
{
"id": "100089",
"name": "Specification",
"value_id": "1729592969712401100",
"value_name": "XL",
"sku_img": {
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
},
"supplementary_sku_images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
]
}
],
"seller_sku": "Color-Red-XM001",
"price": {
"amount": "1.21",
"currency": "USD",
"sale_price": "1.21",
"starting_bid_price": "2.3"
},
"external_sku_id": "1729592969712207012",
"identifier_code": {
"code": "12345678901234",
"type": "GTIN"
},
"inventory": [
{
"warehouse_id": "7068517275539719942",
"quantity": 999,
"backorder_quantity": 888,
"handling_time": 5
}
],
"combined_skus": [
{
"product_id": "1729582718312380123",
"sku_id": "2729382476852921560",
"sku_count": 2
}
],
"sku_unit_count": "100.00",
"external_urls": [
"https://example.com/path1",
"https://example.com/path2"
],
"extra_identifier_codes": [
"00012345678905",
"9780596520687"
],
"pre_sale": {
"type": "PRE_ORDER",
"fulfillment_type": {
"handling_duration_days": 7,
"release_date": 1619611761
}
},
"list_price": {
"amount": "1",
"currency": "USD"
},
"external_list_prices": [
{
"source": "SHOPIFY_COMPARE_AT_PRICE",
"amount": "1",
"currency": "USD"
}
],
"fees": [
{
"type": "PFAND",
"amount": "1.01",
"additional_attribute": "SINGLE_USE"
}
],
"sku_dimensions": {
"length": "10",
"width": "10",
"height": "10",
"unit": "CENTIMETER"
},
"sku_weight": {
"value": "1.32",
"unit": "KILOGRAM"
}
}
],
"title": "Men's Fashion Sports Low Cut Cotton Breathable Ankle Short Boat Invisible Socks\n",
"is_cod_allowed": false,
"certifications": [
{
"id": "7182427311584347905",
"images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
],
"files": [
{
"id": "v09e40f40000cfu0ovhc77ub7fl97k4w",
"name": "Certificate.pdf",
"format": "PDF"
}
],
"expiration_date": 1741235456
}
],
"package_weight": {
"value": "1.32",
"unit": "KILOGRAM"
},
"product_attributes": [
{
"id": "100392",
"values": [
{
"id": "1001533",
"name": "Birthday",
"metric_standard_info": {
"id": "7678592839487784712",
"metric_value_module_infos": [
{
"id": "7678592839487735560",
"value": "2026",
"unit_id": "7678592839484720903"
}
]
}
}
]
}
],
"size_chart": {
"image": {
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
},
"template": {
"id": "7267563252536723205"
}
},
"package_dimensions": {
"length": "10",
"width": "10",
"height": "10",
"unit": "CENTIMETER"
},
"external_product_id": "172959296971220002",
"delivery_option_ids": [
"1729592969712203232"
],
"video": {
"id": "v09e40f40000cfu0ovhc77ub7fl97k4w"
},
"category_version": "v1",
"manufacturer_ids": [
"172959296971220002"
],
"responsible_person_ids": [
"172959296971220003"
],
"listing_platforms": [
"TIKTOK_SHOP"
],
"shipping_insurance_requirement": "REQUIRED",
"is_pre_owned": false,
"minimum_order_quantity": 1,
"replicated_products": [
{
"region": "US",
"skus": [
{
"id": "1729592969712207001",
"seller_sku": "Color-Red-XM002",
"price": {
"currency": "USD",
"sale_price": "1.21"
},
"inventory": [
{
"warehouse_id": "7068517275539719942",
"quantity": 999
}
]
}
],
"inventory_mode": "SHARED"
}
],
"subscribe_info_edit": {
"subscribe_status": "ENABLED",
"discount_details": [
{
"discount_level": "REGULAR",
"discount_value": 10
}
]
},
"shipping_template_id": "7552764259994699538",
"scheduled_sale": {
"is_enabled_scheduled_sale": false,
"schedule_sale_time": 1768899145000
},
"locale": "en-US",
"auto_translate_enabled": false,
"search_terms": [
"sneakers",
"running shoes",
"athletic"
],
"key_product_features": [
"Breathable mesh upper",
"Cushioned foam midsole"
],
"inventory_mode": "SHARED",
"product_tag_operations": [
{
"product_tag": "AUCTION",
"enable": false
}
],
"purchase_order_quantity_limit": {
"maximum_order_quantity": 2,
"cumulative_order_quantity": 20
},
"selling_format": "FIXED_PRICE_AND_LIVE_AUCTION",
"is_live_quick": false,
"is_blind_box": false
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EditProductResponse"
},
"example": {
"code": 0,
"data": {
"product_id": "1729592969712207008",
"skus": [
{
"id": "1729592969712207012",
"seller_sku": "Color-Red-XM001",
"sales_attributes": [
{
"id": "100000",
"value_id": "1729592969712207123"
}
],
"external_sku_id": "1729592969712207234",
"fees": [
{
"type": "PFAND",
"amount": "1.01",
"additional_attribute": "SINGLE_USE"
}
]
}
],
"warnings": [
{
"message": "The [brand_id]:123 field is incorrect and has been automatically cleared by the system. Reason: [Brand does not exist]. You can edit it later."
}
],
"audit": {
"status": "AUDITING"
}
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Modify"
],
"x-tts-error-codes": [
{
"code": "12019006",
"message": "product description is invalid"
},
{
"code": "12019011",
"message": "product package weight is invalid"
},
{
"code": "12019012",
"message": "product package size is invalid"
},
{
"code": "12019013",
"message": "brand id is invalid"
},
{
"code": "12019019",
"message": "sale property is invalid"
},
{
"code": "12019022",
"message": "SKU must contain a valid warehouse."
},
{
"code": "12019056",
"message": "sku not allow add"
},
{
"code": "12019057",
"message": "sku not allow delete"
},
{
"code": "12019061",
"message": "Product weight or dimensions unit does not support the imperial units on non-US local products."
},
{
"code": "12019095",
"message": "`pre_sale.fulfillment_type` is missing or empty."
},
{
"code": "12019096",
"message": "The value for `pre_sale.type` is missing."
},
{
"code": "12019097",
"message": "`pre_sale.fulfillment_type.release_date` must be set to a non-zero value."
},
{
"code": "12019098",
"message": "`pre_sale.fulfillment_type.handling_duration_days` must be set to a non-zero value."
},
{
"code": "12019100",
"message": "All SKUs of a product must have the same `pre_sale.type`. Do not assign different values."
},
{
"code": "12019215",
"message": "deposit balance is not enough"
},
{
"code": "12052002",
"message": "Incorrect category format"
},
{
"code": "12052003",
"message": "Incorrect parcel height format"
},
{
"code": "12052004",
"message": "Incorrect parcel width format"
},
{
"code": "12052005",
"message": "Incorrect parcel length format"
},
{
"code": "12052013",
"message": "The product description cannot exceed maximum characters"
},
{
"code": "12052015",
"message": "The product description is required"
},
{
"code": "12052023",
"message": "Category does not exist"
},
{
"code": "12052024",
"message": "Category is not final category"
},
{
"code": "12052025",
"message": "The category is invalid"
},
{
"code": "12052026",
"message": "Brand does not exist"
},
{
"code": "12052028",
"message": "Main product image is required"
},
{
"code": "12052032",
"message": "The product does not exist"
},
{
"code": "12052034",
"message": "This product doesn't belong to this shop"
},
{
"code": "12052037",
"message": "Couldn't update inventory. Possible causes:\n- Inventory is automatically allocated and cannot be modified manually\n- Warehouse IDs provided are incorrect\n- Missing warehouse IDs (all warehouses that stock the product must be included)"
},
{
"code": "12052038",
"message": "Product price locked due to ongoing promotion."
},
{
"code": "12052048",
"message": "You cannot edit the specified product(s) as it isn't listed in your account or shop."
},
{
"code": "12052050",
"message": "A single product cannot have more than 100 different SKUs"
},
{
"code": "12052051",
"message": "The product name exceed max limit characters"
},
{
"code": "12052054",
"message": "The seller SKU text length cannot exceed max limit characters"
},
{
"code": "12052055",
"message": "The SKU inventory quantity for the warehouse must be within allowed limits."
},
{
"code": "12052056",
"message": "The num of image in description cannot exceed max limit"
},
{
"code": "12052073",
"message": "The product price is invalid"
},
{
"code": "12052084",
"message": "The provided currency is not available for this shop/region."
},
{
"code": "12052092",
"message": "product sale price is invalid"
},
{
"code": "12052094",
"message": "No multiple warehouse permission"
},
{
"code": "12052095",
"message": "Warehouse information parsing error"
},
{
"code": "12052096",
"message": "Unable to update the price for SKUs with no warehouse. Assign a warehouse and try again."
},
{
"code": "12052097",
"message": "The warehouse does not exist"
},
{
"code": "12052104",
"message": "property is required"
},
{
"code": "12052105",
"message": "required qualification miss"
},
{
"code": "12052115",
"message": "seller has no warehouse"
},
{
"code": "12052116",
"message": "product package size is invalid"
},
{
"code": "12052128",
"message": "Size chart not found"
},
{
"code": "12052141",
"message": "please edit stock from global"
},
{
"code": "12052144",
"message": "platform warehouse not support to edit"
},
{
"code": "12052151",
"message": "product property value contain restricted words"
},
{
"code": "12052152",
"message": "sale property name contains restricted words"
},
{
"code": "12052153",
"message": "sale property value contains restricted words"
},
{
"code": "12052158",
"message": "category unable to change"
},
{
"code": "12052159",
"message": "unique item total quantity must be one"
},
{
"code": "12052160",
"message": "sku count must be one and disable variables"
},
{
"code": "12052162",
"message": "unique item sku count must be one and disable varialbes"
},
{
"code": "12052163",
"message": "The gift product are not allowed to be edited"
},
{
"code": "12052181",
"message": "The package weight of the product can not be zero."
},
{
"code": "12052182",
"message": "The '{{sub_property_name}}' field is required as you've selected '{{parent_property_value}}' for '{{parent_property_name}}'."
},
{
"code": "12052183",
"message": "The '{{sub_property_name}}' field should be left empty as you've selected '{{parent_property_value}}' for '{{parent_property_name}}'."
},
{
"code": "12052200",
"message": "brand is expired"
},
{
"code": "12052201",
"message": "You are not authorized to sell this brand in this category. To do so, apply through the Qualification Center in Seller Center."
},
{
"code": "12052207",
"message": "receipt brand not support warehouse"
},
{
"code": "12052208",
"message": "A brand authorization is required to publish this listing."
},
{
"code": "12052217",
"message": "All region shops must use V2 categories. Check the documentation for further details."
},
{
"code": "12052220",
"message": "This category is prohibited or unsupported on TikTok Shop. Select another category."
},
{
"code": "12052221",
"message": "Only whitelisted sellers are permitted to trade under current category"
},
{
"code": "12052222",
"message": "category do not support cod"
},
{
"code": "12052223",
"message": "This category is restricted. To sell in this category, apply through the Qualification Center in Seller Center."
},
{
"code": "12052225",
"message": "You are not authorized to sell in this category because it does not fall under your shop's main category. Contact your account manager for help or select another category."
},
{
"code": "12052226",
"message": "This category is restricted. To sell in this category, apply through the Qualification Center in Seller Center."
},
{
"code": "12052227",
"message": "the category is unauthorized or unavailable"
},
{
"code": "12052230",
"message": "Category version and categoryID are not matched."
},
{
"code": "12052235",
"message": "The format of url is invalid"
},
{
"code": "12052238",
"message": "The length of the url is greater than 200"
},
{
"code": "12052240",
"message": "Do not support custom property."
},
{
"code": "12052241",
"message": "attribute name or attribute id is empty."
},
{
"code": "12052242",
"message": "The attribute name characters cannot exceed max_limit"
},
{
"code": "12052243",
"message": "The product attribute or sale attribute name characters contain Chinese."
},
{
"code": "12052244",
"message": "The attribute name duplicate."
},
{
"code": "12052245",
"message": "The product attributes contained invalid characters. Please modify and re-submit."
},
{
"code": "12052246",
"message": "The {{property_type}} not support multi selected, attribute id is :{{property_id}}."
},
{
"code": "12052247",
"message": "Do not support custom product attribute."
},
{
"code": "12052248",
"message": "The {{property_type}} value name or attribute value id is empty."
},
{
"code": "12052249",
"message": "The {{property_type}} value name characters cannot exceed {{max_limit}}, attribute value name is :{{property_value_name}}."
},
{
"code": "12052250",
"message": "The {{property_type}} value name characters contain Chinese."
},
{
"code": "12052251",
"message": "Duplicated attribute values found for an attribute. Remove or modify the duplicated value."
},
{
"code": "12052253",
"message": "Duplicate attribute value id"
},
{
"code": "12052254",
"message": "Duplicate attribute id"
},
{
"code": "12052256",
"message": "The {{property_name}} value need to be positive integers or positive decimals ."
},
{
"code": "12052260",
"message": "The product ID does not exist"
},
{
"code": "12052261",
"message": "product name is empty"
},
{
"code": "12052262",
"message": "Chinese characters are not supported in product name"
},
{
"code": "12052263",
"message": "product name prefix illegal"
},
{
"code": "12052273",
"message": "After the pre-sale product has been onlive product, the pre-sale info cannot be modified."
},
{
"code": "12052275",
"message": "sku's mto day is invalid"
},
{
"code": "12052278",
"message": "seller does not support make to order"
},
{
"code": "12052282",
"message": "Product manufacturer is required."
},
{
"code": "12052284",
"message": "Manufacturer ID {{manufacturer_id}} is not found"
},
{
"code": "12052285",
"message": "Manufacturer ID {{manufacturer_id}} is not associated with the seller"
},
{
"code": "12052287",
"message": "Product responsible person is required"
},
{
"code": "12052289",
"message": "Responsible person ID {{rp_id}} is not found"
},
{
"code": "12052294",
"message": "The format of the extra identification code is incorrect."
},
{
"code": "12052300",
"message": "product main image uri illegal"
},
{
"code": "12052301",
"message": "Width and length of main image must be at least {{min_limit}}, check uri {{uri}}"
},
{
"code": "12052302",
"message": "The main images size exceed limit."
},
{
"code": "12052304",
"message": "Main product image format not support."
},
{
"code": "12052305",
"message": "The main images aspect ratio cannot exceed max limit."
},
{
"code": "12052306",
"message": "main product images count exceed limit"
},
{
"code": "12052307",
"message": "skus in the lottery cannot be deleted"
},
{
"code": "12052308",
"message": "There's an ongoing appeal. If you wish to edit product details, please revoke the appeal first."
},
{
"code": "12052310",
"message": "The futures information filled in by the seller does not meet the requirements."
},
{
"code": "12052311",
"message": "The number of backorder product exceeds the limit max_num, or the proportion of backorder product exceeds the limit max_ratio"
},
{
"code": "12052314",
"message": "Standard product cannot be converted to MTO product"
},
{
"code": "12052315",
"message": "Standard product cannot be converted to preorder product"
},
{
"code": "12052316",
"message": "product second hand not applicable in this sale platform"
},
{
"code": "12052317",
"message": "purchase order quantity not support"
},
{
"code": "12052319",
"message": "maximum order quantity smaller than minimum order quantity"
},
{
"code": "12052324",
"message": "Product description image file format is not supported"
},
{
"code": "12052329",
"message": "A pre-order product can't be changed to a regular product"
},
{
"code": "12052330",
"message": "product is not supported to list in designated sale platform"
},
{
"code": "12052332",
"message": "The seller center is locked during shop integration, only editing stock and price is allowed"
},
{
"code": "12052340",
"message": "product description image uri illegal"
},
{
"code": "12052341",
"message": "The description images size cannot exceed limit."
},
{
"code": "12052342",
"message": "The description images space cannot exceed limit."
},
{
"code": "12052343",
"message": "Product description image format not support."
},
{
"code": "12052344",
"message": "The product description html syntax with error"
},
{
"code": "12052345",
"message": "The product description html tag not support."
},
{
"code": "12052346",
"message": "The product description has Chinese characters"
},
{
"code": "12052348",
"message": "The product description html tag required attribute is miss."
},
{
"code": "12052349",
"message": "The product description html tag not support nest."
},
{
"code": "12052350",
"message": "The product description html tag contain illegal attribute."
},
{
"code": "12052352",
"message": "The product description nest exceeding limit"
},
{
"code": "12052357",
"message": "'supplementary_sku_images' is only allowed when 'sku_img' is specified. Add an image to 'sku_img' and try again."
},
{
"code": "12052359",
"message": "save subscribe not support"
},
{
"code": "12052360",
"message": "The video id is not exist."
},
{
"code": "12052361",
"message": "This base unit value count is not supported. The supported base unit values can be obtained from the Get Attribute API."
},
{
"code": "12052362",
"message": "SKU unit count is required."
},
{
"code": "12052364",
"message": "The warehouse is unavailable because this product cannot be shipped to the target market from this warehouse."
},
{
"code": "12052365",
"message": "The manufacturer lacks language version information for this market."
},
{
"code": "12052371",
"message": "Auction product is bidding when it is not supported to change product info"
},
{
"code": "12052372",
"message": "Generate EU energy label image failed"
},
{
"code": "12052375",
"message": "product list price is invalid"
},
{
"code": "12052376",
"message": "list price not support"
},
{
"code": "12052382",
"message": "Can't edit Dilayani Tokopedia warehouse quantity"
},
{
"code": "12052383",
"message": "product list price exceed limit"
},
{
"code": "12052385",
"message": "Please enter valid certificate expiration date"
},
{
"code": "12052393",
"message": "Product locked for Promotion and stock can't be updated below current stock"
},
{
"code": "12052402",
"message": "seller shipping template is empty"
},
{
"code": "12052403",
"message": "The warehouse does not support fulfillment for the current shop."
},
{
"code": "12052404",
"message": "multi-warehouse not support customize logistics service"
},
{
"code": "12052405",
"message": "The warehouse has not opened the subscribed logistics service"
},
{
"code": "12052420",
"message": "warehouse didn't set logistics service"
},
{
"code": "12052424",
"message": "Missing 'sale price' value"
},
{
"code": "12052446",
"message": "Category is not open in this market"
},
{
"code": "12052465",
"message": "warehouse is unavailable for eu gpr product"
},
{
"code": "12052490",
"message": "The handling time must be within the allowed limits."
},
{
"code": "12052503",
"message": "If the inventory allocation mode is SHARED, the inventory quantity must be the same across all SKUs."
},
{
"code": "12052508",
"message": "The SKU ID in `replicated_products` is invalid and cannot be found."
},
{
"code": "12052509",
"message": "Missing seller_sku in `replicated_products`. You must indicate the seller_sku for all new SKUs."
},
{
"code": "12052510",
"message": "No matching seller_sku found in the source product. Ensure you indicate the seller_sku in both `skus.seller_sku` and `replicated_products.skus.seller_sku`."
},
{
"code": "12052511",
"message": "Missing SKU details in `replicated_products`. You must complete the SKU details."
},
{
"code": "12052512",
"message": "No replicas exist for this product. You can replicate the product first by using the Replicate Product endpoint."
},
{
"code": "12052513",
"message": "No replicas exist for this product in the stated region. You can replicate the product first by using the Replicate Product endpoint."
},
{
"code": "12052514",
"message": "Missing regions in `replicated_products`. The category was changed, therefore you must sync the product to all other markets where replicas exist."
},
{
"code": "12052515",
"message": "Missing regions in `replicated_products`. The sales attributes were changed, therefore you must sync the product to all other markets where replicas exist."
},
{
"code": "12052516",
"message": "Missing inventory details. You must include all warehouse IDs assigned to the SKU, along with the respective quantity. Do not omit any or add unrelated warehouses."
},
{
"code": "12052520",
"message": "product sale property image uri illegal"
},
{
"code": "12052521",
"message": "The sale property images size over limit."
},
{
"code": "12052522",
"message": "Product sale property image is required"
},
{
"code": "12052523",
"message": "Product sale property image format not support."
},
{
"code": "12052524",
"message": "The sale property image aspect ratio invalid"
},
{
"code": "12052525",
"message": "The attribute max num cannot exceed 3."
},
{
"code": "12052526",
"message": "The attribute value max num over limit."
},
{
"code": "12052527",
"message": "The sale attribute id not exist."
},
{
"code": "12052528",
"message": "You can add images to only 1 product variation, which will serve as the primary variation for display in the product options gallery."
},
{
"code": "12052529",
"message": "The property value id not exist."
},
{
"code": "12052530",
"message": "The warehouse ' {{warehouse ID}} ' does not belong to this shop/seller."
},
{
"code": "12052531",
"message": "The warehouse is disabled."
},
{
"code": "12052532",
"message": "the warehouse not delivery warehouse"
},
{
"code": "12052533",
"message": "Removal, addition, and change of warehouses are not permitted. Please specify the original warehouses for the SKUs."
},
{
"code": "12052534",
"message": "warehouse unable to delete"
},
{
"code": "12052535",
"message": "Couldn't publish this product as you haven't set the return warehouse for your shop. Add the return warehouse information on TikTok Shop Seller Center first and try again."
},
{
"code": "12052550",
"message": "SKU property must contain all properties"
},
{
"code": "12052553",
"message": "Sku id duplicate"
},
{
"code": "12052554",
"message": "sku name contain Chinese characters"
},
{
"code": "12052557",
"message": "The SKU ID does not belong to the product."
},
{
"code": "12052558",
"message": "Number of product skus exceed limit."
},
{
"code": "12052559",
"message": "The product with duplicate default sku."
},
{
"code": "12052560",
"message": "The SKU contains duplicate sales attribute."
},
{
"code": "12052570",
"message": "product price exceed limit"
},
{
"code": "12052571",
"message": "Missing price for SKU(s)"
},
{
"code": "12052572",
"message": "the sale price is invalid"
},
{
"code": "12052574",
"message": "unit price config is invalid"
},
{
"code": "12052592",
"message": "Identifier code already entered, cannot enter the same code twice"
},
{
"code": "12052593",
"message": "The identifier code cannot be changed once be submitted"
},
{
"code": "12052650",
"message": "product qualification image uri illegal"
},
{
"code": "12052651",
"message": "The qualification images size over limit."
},
{
"code": "12052655",
"message": "qualification id not exist"
},
{
"code": "12052656",
"message": "qualification id duplicate"
},
{
"code": "12052657",
"message": "qualification image and pdf file is out of limit."
},
{
"code": "12052658",
"message": "product qualification file uri illegal"
},
{
"code": "12052670",
"message": "The size chart image URI is invalid. Note: API users must use the URI generated by the Upload Product Image API."
},
{
"code": "12052671",
"message": "The sizechart images size over limit."
},
{
"code": "12052673",
"message": "Product sizechart image is required"
},
{
"code": "12052700",
"message": "The seller is inactive."
},
{
"code": "12052701",
"message": "do not support cross-boarder seller create local product directly"
},
{
"code": "12052702",
"message": "seller does not support pre-order"
},
{
"code": "12052703",
"message": "Invalid seller tax number"
},
{
"code": "12052704",
"message": "seller id not exist"
},
{
"code": "12052706",
"message": "The minimum sales quantity should not be exceed limit"
},
{
"code": "12052707",
"message": "Setting minimum sales quantity is not supported"
},
{
"code": "12052712",
"message": "sku's pre_order is invalid"
},
{
"code": "12052805",
"message": "Bundle does not support adding this product type"
},
{
"code": "12052815",
"message": "product in bundle deal cannot set minimum sale quantity"
},
{
"code": "12052832",
"message": "The sub-SKU coefficient associated with each combo SKU cannot exceed {{max_limit}}, and cannot less {{min_limit}}."
},
{
"code": "12052834",
"message": "The number of combo sku associated with a sku cannot exceed limit."
},
{
"code": "12052835",
"message": "Sub product ID not exist"
},
{
"code": "12052836",
"message": "The category of the combo is inconsistent with the category of the main sub-product."
},
{
"code": "12052838",
"message": "The first-level categories of the sub-products in the combo are inconsistent"
},
{
"code": "12052841",
"message": "The sub-sku relationship corresponding to different combo sku cannot be duplicated."
},
{
"code": "12052843",
"message": "The main sub-product in the combo cannot be changed"
},
{
"code": "12052844",
"message": "The sub-sku is not in the sub-product"
},
{
"code": "12052846",
"message": "combo does not support adding this product type"
},
{
"code": "12052847",
"message": "The combo sku relationship cannot be changed"
},
{
"code": "12052850",
"message": "The stock of combo does not support being edited."
},
{
"code": "12052853",
"message": "The sale property of combo mismatch."
},
{
"code": "12052857",
"message": "Combined products and normal products cannot be converted to each other."
},
{
"code": "12052859",
"message": "When the combined SKU is only associated with one sub-SKU, the coefficient of this sub-SKU cannot be less than 2."
},
{
"code": "12052863",
"message": "All SKU of a combined product need to be the combined SKU."
},
{
"code": "12052864",
"message": "Unable to add deactivated SKUs to the combined product."
},
{
"code": "12052881",
"message": "identity internal error"
},
{
"code": "12052901",
"message": "The product in its current status is not available for this operation. Change the product status and try again."
},
{
"code": "12052902",
"message": "The SKU list is empty. Either omit the list entirely, or provide all required details."
},
{
"code": "12052910",
"message": "Invalid input parameters. Refer to the API documentation for details."
},
{
"code": "12052915",
"message": "package weight unit and dimension unit miss match."
},
{
"code": "12052921",
"message": "Couldn't edit the inventory quantity because this product shares the inventory with the source shop"
},
{
"code": "12052922",
"message": "edit fields limit"
},
{
"code": "12052930",
"message": "Seller SKU is required"
},
{
"code": "12052931",
"message": "The title must follow these formatting rules: it cannot contain HTML escape characters (e.g., ), emojis, or ASCII control characters (e.g., \\u007F). It also cannot consist solely of symbols (e.g., //// or !@#$$$&), nor can it have more than 9 consecutive repeated characters (e.g., aaaaaaaaa or 111111111)."
},
{
"code": "12052932",
"message": "The description must follow these formatting rules: it cannot contain HTML escape characters (e.g., ), emojis, or ASCII control characters (e.g., \\\\u007F). It also cannot consist solely of symbols (e.g., //// or !@#$$$&), nor can it have more than 9 consecutive repeated characters (e.g., aaaaaaaaa or 111111111)."
},
{
"code": "12052933",
"message": "Sales attribute names must follow these formatting rules: it cannot contain HTML escape characters (e.g., ), emojis, or ASCII control characters (e.g., \\u007F). It also cannot consist solely of symbols (e.g., //// or !@#$$$&), nor can it have more than 9 consecutive repeated characters (e.g., aaaaaaaaa or 111111111)."
},
{
"code": "12052934",
"message": "Sales attribute value names must follow these formatting rules: it cannot contain HTML escape characters (e.g., ), emojis, or ASCII control characters (e.g., \\\\u007F). It also cannot consist solely of symbols (e.g., //// or !@#$$$&), nor can it have more than 9 consecutive repeated characters (e.g., aaaaaaaaa or 111111111)."
},
{
"code": "12052935",
"message": "Product attribute value names must follow these formatting rules: it cannot contain HTML escape characters (e.g., ), emojis, or ASCII control characters (e.g., \\\\u007F). It also cannot consist solely of symbols (e.g., //// or !@#$$$&), nor can it have more than 9 consecutive repeated characters (e.g., aaaaaaaaa or 111111111)."
},
{
"code": "12052936",
"message": "Seller SKU format invalid. SKU name must contain 6 - 50 characters and use alphabets, numbers, hyphens (-), or underscores (_) only."
},
{
"code": "12052994",
"message": "seller is not toko seller"
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/edit-product-202509"
}
},
"/product/202509/products/{product_id}/partial_edit": {
"post": {
"operationId": "partialEditProduct",
"summary": "Partial Edit Product",
"description": "Edit some properties (e.g. description, images, attributes) of a product that is not in the `FREEZE` or `DELETED` state.\nAfter editing the product, the latest product content (referred to as v2) will be resent for audit review. If the audit passes, v2 is published to the shop, otherwise, the existing product stays live and remains unchanged (keeping v1). However, edits to the `price` or `inventory` fields do not require a reaudit and will be immediately published on the platform. Use the [Product status change](650956aff1fd3102b90b6261) webhook to keep track of the review status.\n**Note**: \n- This API is applicable for all sellers.\n- There may be a limit to the number of products you can relist per day. We recommend prioritizing key products first to ensure they get published. You can find your listing limit on the Seller Center homepage.\n- If a draft or audit-review version exists, unedited fields will retain their values over those of the base (live) version.\n- **Updates are handled per top-level property**, so all non-empty fields within an updated object must be supplied to prevent overwriting with blanks. For top-level properties (e.g. `description`, `brand_id`) that are not nested in an object, you can update them individually. Omitting these properties in the request will leave them unchanged. If you need to edit any nested property within an object, you must provide values for all nested properties of that object. Any omitted nested properties will be overwritten with blanks.\n- If new mandatory product attributes were added by TikTok Shop after the creation of your product, ensure that you provide these attributes too.\n**For global sellers**:\nIf you're using the local replication listing method, note the following sync rules:\n**Sales attribute changes** (in sales attribute id/name) must be synced to other markets. Therefore, you must provide the `seller_sku` and complete `replicated_products` data. The API call will fail if you don't provide these details.\n**New SKUs* (new sales attribute value id/name) are optional to sync to other markets. To sync, please provide the `seller_sku` and complete `replicated_products` data.\n**General changes** are optional to sync to other markets. To sync, you only need to provide `replicated_products.region`.\n**For Tokopedia sellers**:\nNote that a product can have **only one active version** across all platforms at any time. If a product is live on both platforms, audit results for the latest version are handled as follows:\n- **Mixed audit results**: If the product passes audit on one platform but fails on another, on the successful platform, the product will stay live and be updated with content from the latest version (v2), while on the failed platform, the product will be deactivated and hidden entirely.\n- **Audit failure on all platforms**: If the product fails audit on all platforms, the existing product stays live and remains unchanged (keeping v1).",
"tags": [
"Products"
],
"parameters": [
{
"name": "product_id",
"in": "path",
"required": true,
"description": "The product ID in TikTok Shop.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PartialEditProductRequest"
},
"example": {
"auto_translate_enabled": false,
"brand_id": "7082427311584347905",
"category_version": "v1",
"certifications": [
{
"expiration_date": 1741235047,
"files": [
{
"format": "PDF",
"id": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe",
"name": "Certificate.pdf"
}
],
"id": "7182427311584347905",
"images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
]
}
],
"description": " ",
"external_product_id": "172959296971220002",
"inventory_mode": "SHARED",
"is_cod_allowed": false,
"key_product_features": [
"Breathable mesh upper",
"Cushioned foam midsole"
],
"listing_platforms": [
"TIKTOK_SHOP"
],
"locale": "en-US",
"main_images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
],
"manufacturer_ids": [
"172959296971220002"
],
"package_dimensions": {
"height": "12",
"length": "10",
"unit": "CENTIMETER",
"width": "11"
},
"package_weight": {
"unit": "KILOGRAM",
"value": "1.32"
},
"pod_info": {
"pod_templates": [
{
"pod_template_id": "172959296971220002",
"remark": "Front side customization template for basic tee",
"sku_ids": [
"172959296971220002"
],
"surfaces": [
{
"background_image": {
"uri": "tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4"
},
"custom_areas": [
{
"area_name": "Front Text Area",
"area_placement": {
"height": "600",
"rotate_degree": "0",
"width": "600",
"x_coordinate": "0",
"y_coordinate": "0"
},
"area_type": "TEXT",
"external_area_id": "172959296971220002",
"image_area": {
"default_image": {
"uri": "tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4"
},
"min_height": 300,
"min_width": 300
},
"is_required": false,
"text_area": {
"align_type": "CENTER",
"colors": [
"#FFFFFF"
],
"default_text": "Hello World",
"fonts": [
"Roboto"
],
"max_text_length": 20
}
}
],
"external_surface_id": "172959296971220002",
"mask_image": {
"uri": "tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4"
},
"surface_name": "Front Side"
}
],
"template_name": "T-Shirt Front Print"
}
]
},
"product_attributes": [
{
"id": "100392",
"values": [
{
"id": "1001533",
"name": "Birthday",
"metric_standard_info": {
"id": "7678592839487784712",
"metric_value_module_infos": [
{
"id": "7678592839487735560",
"value": "2026",
"unit_id": "7678592839484720903"
}
]
}
}
]
}
],
"replicated_products": [
{
"inventory_mode": "SHARED",
"region": "US",
"skus": [
{
"external_sku_id": "1729592969712207012",
"id": "1729592969712207000",
"inventory": [
{
"quantity": 999,
"warehouse_id": "7068517275539719942"
}
],
"price": {
"currency": "USD",
"sale_price": "1.21"
},
"seller_sku": "Color-Red-XM001"
}
]
}
],
"responsible_person_ids": [
"172959296971220003"
],
"save_mode": "AS_DRAFT",
"scheduled_sale": {
"is_enabled_scheduled_sale": false,
"schedule_sale_time": 1768899145000
},
"search_terms": [
"sneakers",
"running shoes",
"athletic"
],
"size_chart": {
"image": {
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
},
"template": {
"id": "7267563252536723205"
}
},
"skus": [
{
"external_list_prices": [
{
"amount": "1",
"currency": "USD",
"source": "SHOPIFY_COMPARE_AT_PRICE"
}
],
"external_sku_id": "1729592969712207012",
"external_urls": [
"https://example.com/path1",
"https://example.com/path2"
],
"extra_identifier_codes": [
"00012345678905",
"9780596520687"
],
"fees": [
{
"additional_attribute": "SINGLE_USE",
"amount": "1.01",
"type": "PFAND"
}
],
"id": "1729592969712207012",
"identifier_code": {
"code": "12345678901234",
"type": "GTIN"
},
"inventory": [
{
"backorder_quantity": 888,
"handling_time": 5,
"quantity": 999,
"warehouse_id": "7068517275539719942"
}
],
"list_price": {
"amount": "1",
"currency": "USD"
},
"pre_sale": {
"fulfillment_type": {
"handling_duration_days": 7,
"release_date": 1619611761
},
"type": "PRE_ORDER"
},
"price": {
"amount": "100.00",
"currency": "USD",
"sale_price": "1.21"
},
"sales_attributes": [
{
"id": "100089",
"name": "Specification",
"sku_img": {
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
},
"supplementary_sku_images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
],
"value_id": "1729592969712207000",
"value_name": "XL"
}
],
"seller_sku": "seller_sku_xxaa",
"sku_dimensions": {
"height": "10",
"length": "10",
"unit": "CENTIMETER",
"width": "10"
},
"sku_unit_count": "100.00",
"sku_weight": {
"unit": "KILOGRAM",
"value": "1.32"
}
}
],
"subscribe_info_edit": {
"discount_details": [
{
"discount_level": "REGULAR",
"discount_value": 10
}
],
"subscribe_status": "ENABLED"
},
"title": "Title-xxaa",
"video": {
"id": "v09e40f40000cfu0ovhc77ub7fl97k4w"
},
"is_blind_box": false
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PartialEditProductResponse"
},
"example": {
"code": 0,
"data": {
"audit": {
"status": "AUDITING"
},
"product_id": "1729592969712207008",
"skus": [
{
"external_sku_id": "1729592969712207012",
"fees": [
{
"additional_attribute": "SINGLE_USE",
"amount": "1.01",
"type": "PFAND"
}
],
"id": "1729592969712207012",
"sales_attributes": [
{
"id": "100000",
"value_id": "1729592969712207123"
}
],
"seller_sku": "seller sku xxaa"
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Modify"
],
"x-tts-error-codes": [
{
"code": "12019011",
"message": "product package weight is invalid"
},
{
"code": "12019022",
"message": "SKU must contain a valid warehouse."
},
{
"code": "12019060",
"message": "package_dimension_unit field is for America market(US) only."
},
{
"code": "12019094",
"message": "Conflicting presale fields. Remove `pre_sale.fulfillment_type` if you want to set `pre_sale.type` to `NONE`."
},
{
"code": "12019096",
"message": "The value for `pre_sale.type` is missing."
},
{
"code": "12019097",
"message": "`pre_sale.fulfillment_type.release_date` must be set to a non-zero value."
},
{
"code": "12019098",
"message": "`pre_sale.fulfillment_type.handling_duration_days` must be set to a non-zero value."
},
{
"code": "12019099",
"message": "The specified `pre_sale.type` is not supported in your region. Refer to the API documentation for details."
},
{
"code": "12019100",
"message": "All SKUs of a product must have the same `pre_sale.type`. Do not assign different values."
},
{
"code": "12052003",
"message": "Incorrect parcel height format"
},
{
"code": "12052004",
"message": "Incorrect parcel width format"
},
{
"code": "12052005",
"message": "Incorrect parcel length format"
},
{
"code": "12052013",
"message": "The product description cannot exceed maximum characters"
},
{
"code": "12052015",
"message": "The product description is required"
},
{
"code": "12052023",
"message": "Category does not exist"
},
{
"code": "12052024",
"message": "Category is not final category"
},
{
"code": "12052025",
"message": "The category is invalid"
},
{
"code": "12052026",
"message": "Brand does not exist"
},
{
"code": "12052028",
"message": "Main product image is required"
},
{
"code": "12052031",
"message": "Invalid product ID(s) found"
},
{
"code": "12052032",
"message": "The product does not exist"
},
{
"code": "12052038",
"message": "Product price locked due to ongoing promotion."
},
{
"code": "12052048",
"message": "You cannot edit the specified product(s) as it isn't listed in your account or shop."
},
{
"code": "12052050",
"message": "A single product cannot have more than 100 different SKUs"
},
{
"code": "12052051",
"message": "The product name exceed max limit characters"
},
{
"code": "12052054",
"message": "The seller SKU text length cannot exceed max limit characters"
},
{
"code": "12052055",
"message": "The SKU inventory quantity for the warehouse must be within allowed limits."
},
{
"code": "12052056",
"message": "The num of image in description cannot exceed max limit"
},
{
"code": "12052073",
"message": "The product price is invalid"
},
{
"code": "12052084",
"message": "The provided currency is not available for this shop/region."
},
{
"code": "12052092",
"message": "product sale price is invalid"
},
{
"code": "12052094",
"message": "No multiple warehouse permission"
},
{
"code": "12052096",
"message": "Unable to update the price for SKUs with no warehouse. Assign a warehouse and try again."
},
{
"code": "12052104",
"message": "property is required"
},
{
"code": "12052105",
"message": "required qualification miss"
},
{
"code": "12052115",
"message": "seller has no warehouse"
},
{
"code": "12052116",
"message": "product package size is invalid"
},
{
"code": "12052128",
"message": "Size chart not found"
},
{
"code": "12052144",
"message": "platform warehouse not support to edit"
},
{
"code": "12052151",
"message": "product property value contain restricted words"
},
{
"code": "12052152",
"message": "sale property name contains restricted words"
},
{
"code": "12052153",
"message": "sale property value contains restricted words"
},
{
"code": "12052157",
"message": "One or more of the product attributes cannot be edited by cross-border sellers"
},
{
"code": "12052159",
"message": "unique item total quantity must be one"
},
{
"code": "12052160",
"message": "sku count must be one and disable variables"
},
{
"code": "12052163",
"message": "The gift product are not allowed to be edited"
},
{
"code": "12052181",
"message": "The package weight of the product can not be zero."
},
{
"code": "12052182",
"message": "The '{{sub_property_name}}' field is required as you've selected '{{parent_property_value}}' for '{{parent_property_name}}'."
},
{
"code": "12052183",
"message": "The '{{sub_property_name}}' field should be left empty as you've selected '{{parent_property_value}}' for '{{parent_property_name}}'."
},
{
"code": "12052200",
"message": "brand is expired"
},
{
"code": "12052201",
"message": "You are not authorized to sell this brand in this category. To do so, apply through the Qualification Center in Seller Center."
},
{
"code": "12052208",
"message": "A brand authorization is required to publish this listing."
},
{
"code": "12052216",
"message": "manufacturer info is invalid"
},
{
"code": "12052220",
"message": "This category is prohibited or unsupported on TikTok Shop. Select another category."
},
{
"code": "12052221",
"message": "Only whitelisted sellers are permitted to trade under current category"
},
{
"code": "12052222",
"message": "category do not support cod"
},
{
"code": "12052223",
"message": "This category is restricted. To sell in this category, apply through the Qualification Center in Seller Center."
},
{
"code": "12052225",
"message": "You are not authorized to sell in this category because it does not fall under your shop's main category. Contact your account manager for help or select another category."
},
{
"code": "12052226",
"message": "This category is restricted. To sell in this category, apply through the Qualification Center in Seller Center."
},
{
"code": "12052227",
"message": "the category is unauthorized or unavailable"
},
{
"code": "12052240",
"message": "Do not support custom property."
},
{
"code": "12052241",
"message": "attribute name or attribute id is empty."
},
{
"code": "12052242",
"message": "The attribute name characters cannot exceed max_limit"
},
{
"code": "12052243",
"message": "The product attribute or sale attribute name characters contain Chinese."
},
{
"code": "12052244",
"message": "The attribute name duplicate."
},
{
"code": "12052245",
"message": "The product attributes contained invalid characters. Please modify and re-submit."
},
{
"code": "12052246",
"message": "The {{property_type}} not support multi selected, attribute id is :{{property_id}}."
},
{
"code": "12052247",
"message": "Do not support custom product attribute."
},
{
"code": "12052248",
"message": "The {{property_type}} value name or attribute value id is empty."
},
{
"code": "12052249",
"message": "The {{property_type}} value name characters cannot exceed {{max_limit}}, attribute value name is :{{property_value_name}}."
},
{
"code": "12052250",
"message": "The {{property_type}} value name characters contain Chinese."
},
{
"code": "12052251",
"message": "Duplicated attribute values found for an attribute. Remove or modify the duplicated value."
},
{
"code": "12052253",
"message": "Duplicate attribute value id"
},
{
"code": "12052254",
"message": "Duplicate attribute id"
},
{
"code": "12052256",
"message": "The {{property_name}} value need to be positive integers or positive decimals ."
},
{
"code": "12052260",
"message": "The product ID does not exist"
},
{
"code": "12052261",
"message": "product name is empty"
},
{
"code": "12052262",
"message": "Chinese characters are not supported in product name"
},
{
"code": "12052263",
"message": "product name prefix illegal"
},
{
"code": "12052269",
"message": "The selected time is outside the limit"
},
{
"code": "12052273",
"message": "After the pre-sale product has been onlive product, the pre-sale info cannot be modified."
},
{
"code": "12052282",
"message": "Product manufacturer is required."
},
{
"code": "12052283",
"message": "The number of manufacturers cannot exceed the allowed limits."
},
{
"code": "12052284",
"message": "Manufacturer ID {{manufacturer_id}} is not found"
},
{
"code": "12052285",
"message": "Manufacturer ID {{manufacturer_id}} is not associated with the seller"
},
{
"code": "12052287",
"message": "Product responsible person is required"
},
{
"code": "12052288",
"message": "The number of responsible person ids cannot exceed {{max_limit}}, and cannot less {{min_limit}}."
},
{
"code": "12052289",
"message": "Responsible person ID {{rp_id}} is not found"
},
{
"code": "12052290",
"message": "Responsible person ID {{rp_id}} is not associated with the seller"
},
{
"code": "12052292",
"message": "The number of extra identification codes cannot exceed the allowed limits."
},
{
"code": "12052294",
"message": "The format of the extra identification code is incorrect."
},
{
"code": "12052300",
"message": "product main image uri illegal"
},
{
"code": "12052301",
"message": "Width and length of main image must be at least {{min_limit}}, check uri {{uri}}"
},
{
"code": "12052302",
"message": "The main images size exceed limit."
},
{
"code": "12052304",
"message": "Main product image format not support."
},
{
"code": "12052305",
"message": "The main images aspect ratio cannot exceed max limit."
},
{
"code": "12052306",
"message": "main product images count exceed limit"
},
{
"code": "12052307",
"message": "skus in the lottery cannot be deleted"
},
{
"code": "12052308",
"message": "There's an ongoing appeal. If you wish to edit product details, please revoke the appeal first."
},
{
"code": "12052314",
"message": "Standard product cannot be converted to MTO product"
},
{
"code": "12052315",
"message": "Standard product cannot be converted to preorder product"
},
{
"code": "12052316",
"message": "product second hand not applicable in this sale platform"
},
{
"code": "12052324",
"message": "Product description image file format is not supported"
},
{
"code": "12052329",
"message": "A pre-order product can't be changed to a regular product"
},
{
"code": "12052330",
"message": "product is not supported to list in designated sale platform"
},
{
"code": "12052332",
"message": "The seller center is locked during shop integration, only editing stock and price is allowed"
},
{
"code": "12052340",
"message": "product description image uri illegal"
},
{
"code": "12052341",
"message": "The description images size cannot exceed limit."
},
{
"code": "12052342",
"message": "The description images space cannot exceed limit."
},
{
"code": "12052343",
"message": "Product description image format not support."
},
{
"code": "12052344",
"message": "The product description html syntax with error"
},
{
"code": "12052345",
"message": "The product description html tag not support."
},
{
"code": "12052346",
"message": "The product description has Chinese characters"
},
{
"code": "12052348",
"message": "The product description html tag required attribute is miss."
},
{
"code": "12052349",
"message": "The product description html tag not support nest."
},
{
"code": "12052350",
"message": "The product description html tag contain illegal attribute."
},
{
"code": "12052352",
"message": "The product description nest exceeding limit"
},
{
"code": "12052356",
"message": "The number of 'supplementary_sku_images' for the sales attribute value exceeds the maximum limit."
},
{
"code": "12052357",
"message": "'supplementary_sku_images' is only allowed when 'sku_img' is specified. Add an image to 'sku_img' and try again."
},
{
"code": "12052359",
"message": "save subscribe not support"
},
{
"code": "12052360",
"message": "The video id is not exist."
},
{
"code": "12052361",
"message": "This base unit value count is not supported. The supported base unit values can be obtained from the Get Attribute API."
},
{
"code": "12052362",
"message": "SKU unit count is required."
},
{
"code": "12052365",
"message": "The manufacturer lacks language version information for this market."
},
{
"code": "12052366",
"message": "The responsible person lacks language version information for this market."
},
{
"code": "12052371",
"message": "Auction product is bidding when it is not supported to change product info"
},
{
"code": "12052375",
"message": "product list price is invalid"
},
{
"code": "12052376",
"message": "list price not support"
},
{
"code": "12052382",
"message": "Can't edit Dilayani Tokopedia warehouse quantity"
},
{
"code": "12052383",
"message": "product list price exceed limit"
},
{
"code": "12052385",
"message": "Please enter valid certificate expiration date"
},
{
"code": "12052393",
"message": "Product locked for Promotion and stock can't be updated below current stock"
},
{
"code": "12052402",
"message": "seller shipping template is empty"
},
{
"code": "12052403",
"message": "The warehouse does not support fulfillment for the current shop."
},
{
"code": "12052520",
"message": "product sale property image uri illegal"
},
{
"code": "12052521",
"message": "The sale property images size over limit."
},
{
"code": "12052522",
"message": "Product sale property image is required"
},
{
"code": "12052523",
"message": "Product sale property image format not support."
},
{
"code": "12052524",
"message": "The sale property image aspect ratio invalid"
},
{
"code": "12052525",
"message": "The attribute max num cannot exceed 3."
},
{
"code": "12052526",
"message": "The attribute value max num over limit."
},
{
"code": "12052527",
"message": "The sale attribute id not exist."
},
{
"code": "12052528",
"message": "You can add images to only 1 product variation, which will serve as the primary variation for display in the product options gallery."
},
{
"code": "12052529",
"message": "The property value id not exist."
},
{
"code": "12052530",
"message": "The warehouse ' {{warehouse ID}} ' does not belong to this shop/seller."
},
{
"code": "12052531",
"message": "The warehouse is disabled."
},
{
"code": "12052532",
"message": "the warehouse not delivery warehouse"
},
{
"code": "12052533",
"message": "Removal, addition, and change of warehouses are not permitted. Please specify the original warehouses for the SKUs."
},
{
"code": "12052534",
"message": "warehouse unable to delete"
},
{
"code": "12052535",
"message": "Couldn't publish this product as you haven't set the return warehouse for your shop. Add the return warehouse information on TikTok Shop Seller Center first and try again."
},
{
"code": "12052550",
"message": "SKU property must contain all properties"
},
{
"code": "12052554",
"message": "sku name contain Chinese characters"
},
{
"code": "12052557",
"message": "The SKU ID does not belong to the product."
},
{
"code": "12052558",
"message": "Number of product skus exceed limit."
},
{
"code": "12052559",
"message": "The product with duplicate default sku."
},
{
"code": "12052560",
"message": "The SKU contains duplicate sales attribute."
},
{
"code": "12052570",
"message": "product price exceed limit"
},
{
"code": "12052571",
"message": "Missing price for SKU(s)"
},
{
"code": "12052572",
"message": "the sale price is invalid"
},
{
"code": "12052574",
"message": "unit price config is invalid"
},
{
"code": "12052591",
"message": "Invalid number of digits of identifier code"
},
{
"code": "12052592",
"message": "Identifier code already entered, cannot enter the same code twice"
},
{
"code": "12052593",
"message": "The identifier code cannot be changed once be submitted"
},
{
"code": "12052598",
"message": "Only the last digit supports input X"
},
{
"code": "12052600",
"message": "The identifier code type must be selected"
},
{
"code": "12052650",
"message": "product qualification image uri illegal"
},
{
"code": "12052655",
"message": "qualification id not exist"
},
{
"code": "12052656",
"message": "qualification id duplicate"
},
{
"code": "12052657",
"message": "qualification image and pdf file is out of limit."
},
{
"code": "12052670",
"message": "The size chart image URI is invalid. Note: API users must use the URI generated by the Upload Product Image API."
},
{
"code": "12052673",
"message": "Product sizechart image is required"
},
{
"code": "12052700",
"message": "The seller is inactive."
},
{
"code": "12052702",
"message": "seller does not support pre-order"
},
{
"code": "12052703",
"message": "Invalid seller tax number"
},
{
"code": "12052704",
"message": "seller id not exist"
},
{
"code": "12052706",
"message": "The minimum sales quantity should not be exceed limit"
},
{
"code": "12052712",
"message": "sku's pre_order is invalid"
},
{
"code": "12052722",
"message": "The image URI does not exist in TikTok Shop."
},
{
"code": "12052805",
"message": "Bundle does not support adding this product type"
},
{
"code": "12052842",
"message": "The combo does not include the main sub-product"
},
{
"code": "12052846",
"message": "combo does not support adding this product type"
},
{
"code": "12052847",
"message": "The combo sku relationship cannot be changed"
},
{
"code": "12052849",
"message": "You don't have the permission to operate combo."
},
{
"code": "12052863",
"message": "All SKU of a combined product need to be the combined SKU."
},
{
"code": "12052864",
"message": "Unable to add deactivated SKUs to the combined product."
},
{
"code": "12052881",
"message": "identity internal error"
},
{
"code": "12052901",
"message": "The product in its current status is not available for this operation. Change the product status and try again."
},
{
"code": "12052902",
"message": "The SKU list is empty. Either omit the list entirely, or provide all required details."
},
{
"code": "12052910",
"message": "Invalid input parameters. Refer to the API documentation for details."
},
{
"code": "12052915",
"message": "package weight unit and dimension unit miss match."
},
{
"code": "12052916",
"message": "The package unit is not supported in the current region."
},
{
"code": "12052921",
"message": "Couldn't edit the inventory quantity because this product shares the inventory with the source shop"
},
{
"code": "12052922",
"message": "edit fields limit"
},
{
"code": "12052930",
"message": "Seller SKU is required"
},
{
"code": "12052931",
"message": "The title must follow these formatting rules: it cannot contain HTML escape characters (e.g., ), emojis, or ASCII control characters (e.g., \\u007F). It also cannot consist solely of symbols (e.g., //// or !@#$$$&), nor can it have more than 9 consecutive repeated characters (e.g., aaaaaaaaa or 111111111)."
},
{
"code": "12052932",
"message": "The description must follow these formatting rules: it cannot contain HTML escape characters (e.g., ), emojis, or ASCII control characters (e.g., \\\\u007F). It also cannot consist solely of symbols (e.g., //// or !@#$$$&), nor can it have more than 9 consecutive repeated characters (e.g., aaaaaaaaa or 111111111)."
},
{
"code": "12052933",
"message": "Sales attribute names must follow these formatting rules: it cannot contain HTML escape characters (e.g., ), emojis, or ASCII control characters (e.g., \\u007F). It also cannot consist solely of symbols (e.g., //// or !@#$$$&), nor can it have more than 9 consecutive repeated characters (e.g., aaaaaaaaa or 111111111)."
},
{
"code": "12052934",
"message": "Sales attribute value names must follow these formatting rules: it cannot contain HTML escape characters (e.g., ), emojis, or ASCII control characters (e.g., \\\\u007F). It also cannot consist solely of symbols (e.g., //// or !@#$$$&), nor can it have more than 9 consecutive repeated characters (e.g., aaaaaaaaa or 111111111)."
},
{
"code": "12052935",
"message": "Product attribute value names must follow these formatting rules: it cannot contain HTML escape characters (e.g., ), emojis, or ASCII control characters (e.g., \\\\u007F). It also cannot consist solely of symbols (e.g., //// or !@#$$$&), nor can it have more than 9 consecutive repeated characters (e.g., aaaaaaaaa or 111111111)."
},
{
"code": "12052936",
"message": "Seller SKU format invalid. SKU name must contain 6 - 50 characters and use alphabets, numbers, hyphens (-), or underscores (_) only."
},
{
"code": "12052994",
"message": "seller is not toko seller"
},
{
"code": "12052995",
"message": "seller has not finished onboarding to tts"
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/partial-edit-product-202509"
}
},
"/product/202601/compliance/auditing/research": {
"post": {
"operationId": "searchProductsForComplianceAuditing",
"summary": "Search Products for Compliance Auditing",
"description": "Search live products and retrieve the product information needed by a compliance vendor to prepare a compliance testing report. The selection behavior is:\n- If `product_ids` is non-empty, the operation retrieves those known products. This branch takes precedence; seller, product-title, category, and brand filters and pagination are not used to select products.\n- Otherwise, the operation performs a shop search and requires `seller_id`, `seller_name`, or both. When both shop identifiers are provided, their matching sellers are combined. You can further filter this search by product title, category IDs, and brand IDs and paginate the results.",
"tags": [
"Products"
],
"parameters": [
{
"name": "shop_cipher",
"in": "query",
"required": false,
"description": "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. \nGet by API [Get Authorization Shop](https://partner.tiktokshop.com/docv2/page/6507ead7b99d5302be949ba9?external_id=6507ead7b99d5302be949ba9)",
"schema": {
"type": "string"
}
},
{
"name": "category_asset_cipher",
"in": "query",
"required": false,
"description": "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 The partner identifier used in API requests. \nRetrieve this value by using the [Get Authorized Category Assets API](https://partner.tiktokshop.com/docv2/page/666012dd609d4402cc3be995).",
"schema": {
"type": "string"
}
},
{
"name": "page_token",
"in": "query",
"required": false,
"description": "The opaque token used to retrieve the next page. Omit this parameter or pass an empty string for the first page. For subsequent pages, pass the `next_page_token` returned by the previous response.",
"schema": {
"type": "string"
}
},
{
"name": "page_size",
"in": "query",
"required": true,
"description": "The number of results to be returned per page. \nValid range: [1-50]",
"schema": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maximum": 50
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchProductsForComplianceAuditingRequest"
},
"example": {
"product_title": "mike noritama cute calico cat",
"product_ids": [
"123123",
"1235677",
"456756"
],
"seller_id": "1733337095719126364",
"category_ids": [
"602118"
],
"brand_ids": [
"602118"
],
"seller_name": "shopname1"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchProductsForComplianceAuditingResponse"
},
"example": {
"code": 0,
"data": {
"next_page_token": "[\\\"1733419489460520284\\\"]",
"total_count": 454,
"products": [
{
"id": "1729592969712207008",
"title": "mike noritama cute calico cat",
"country": "FR",
"description": "Please compare above detailed size with your measurement before purchase.
\n\n",
"variants": [
{
"id": "11111"
}
],
"listing_url": "https://shop.tiktok.com/view/product/1733990243784295749?region=FR",
"seller_name": "Essential Shop",
"seller_id": "11111",
"main_image_urls": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/6c8519a3663a4d728c4e3c131dc914b4~tplv-o3syd03w52-resize-jpeg:300:300.jpeg?from=522366036"
],
"brand_id": "1111",
"brand_name": "Labor",
"categories": [
{
"id": "1111",
"name": "Kostum",
"level": 1,
"parent_id": "1111",
"is_leaf": false
}
]
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-scenario": 100,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-products-for-compliance-auditing-202601"
}
},
"/product/202602/packages/recommend": {
"post": {
"operationId": "getProductPackageRecommendations",
"summary": "Get Product Package Recommendations",
"description": "Retrieve recommended weight and dimension ranges for product packages. Only available in BR and MX.",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "page_size",
"in": "query",
"required": true,
"description": "The number of results to be returned per page.\nValid range: [1-100]",
"schema": {
"type": "integer",
"format": "int64",
"minimum": 1,
"maximum": 100
}
},
{
"name": "page_token",
"in": "query",
"required": false,
"description": "An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the `next_page_token` from a previous response. It is not needed for the first page.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetProductPackageRecommendationsRequest"
},
"example": {
"product_ids": [
"12345678",
"12345679"
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetProductPackageRecommendationsResponse"
},
"example": {
"code": 0,
"data": {
"next_page_token": "b2Zmc2V0PTAK",
"total_count": 200,
"products": [
{
"product_id": "23423",
"abnormality_types": [
"Dimension",
"Weight"
],
"weight_recommendation": {
"unit": "GRAM",
"weight": {
"min_value": "550",
"max_value": "650"
}
},
"dimension_recommendation": {
"unit": "CENTIMETER",
"length": {
"min_value": "19",
"max_value": "22"
},
"height": {
"min_value": "19",
"max_value": "22"
},
"width": {
"min_value": "19",
"max_value": "22"
}
}
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-product-package-recommendations-202602"
}
},
"/product/202604/appeals/submit": {
"post": {
"operationId": "submitSizeChartAppeal",
"summary": "Submit Size Chart Appeal",
"description": "#### Appeal Size Chart Verification\nInitiates an appeal process for a product that was blocked during the listing phase due to a size chart verification failure.\nThis API is used when a seller believes their product was incorrectly blocked by our automated size chart validation system. The validation checks for three potential issues:\n1. Whether the size chart contains all mandatory dimensions.\n2. Whether the size chart covers all Stock-Keeping Units (SKUs) for sale.\n3. Whether the numerical values within the size chart are valid.\nIf the validation system detects an issue, the product listing will be blocked. By using this API, sellers can submit an appeal. If the appeal is approved, the block will be lifted, and the seller can re-list the product.\nUse the `[Appeal Status Webhook]` to monitor the appeal's progress, or pass the `appeal_id` to the `[Get Appeal Status API]` to retrieve the current status.\nNote:\n- Please wait at least 5 minutes after submitting an appeal before checking its status via the API to ensure the data is synchronized.\n- You can submit up to 50 appeals per day. Any requests exceeding this limit will be rejected.",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubmitSizeChartAppealRequest"
},
"example": {
"product_id": 1729532326804361713,
"appeal_message": {
"field_name": "APPEAL_MESSAGE_FIELD_SIZE_CHART",
"indicator_details": [
{
"indicator_type": "CONTAINS_ALL_SALE_PROPERTY"
}
],
"size_chart_id": "7597302357391361806",
"size_chart_image_uri": "tos-alisg-i-aphluv4xwc-sg/ebf6d1b2204a4aa883abb0befb6fee50"
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubmitSizeChartAppealResponse"
},
"example": {
"code": 0,
"data": {},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/submit-size-chart-appeal-202604"
}
},
"/product/202604/opportunities/query": {
"post": {
"operationId": "listOpportunities",
"summary": "List Opportunities",
"description": "Search and retrieve a paginated list of opportunity leads available to the authorized seller, with optional filters by type, status, category, etc and ordered by the algorithm ranking model.",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "page_size",
"in": "query",
"required": true,
"description": "Number of results per page. Max: 100. Default: 20.",
"schema": {
"type": "integer",
"format": "int64",
"maximum": 100
}
},
{
"name": "page_token",
"in": "query",
"required": false,
"description": "Pagination token from previous response. Omit for first page.",
"schema": {
"type": "string"
}
},
{
"name": "locale",
"in": "query",
"required": false,
"description": "The locale for localized category names, tags, and reward information, expressed as a BCP-47 language-country code, for example `en-US`. If omitted, the primary locale for the seller's shop region is used.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListOpportunitiesRequest"
},
"example": {
"opportunity_type": "PRODUCT",
"category_ids": [
"601310",
"601311"
],
"create_time_ge": 1775976752,
"create_time_lt": 1776976752,
"tag_codes": [
"core_product",
"top_product"
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListOpportunitiesResponse"
},
"example": {
"code": 0,
"data": {
"data": {
"opportunities": [
{
"id": "7123456789012345678",
"title": "title info",
"reference_images": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/61e605ce483f4f7b9b419d510f74fd22~tplv-o3syd03w52-resize-image:400:400.image?dr=15586&t=555f072d&ps=933b5bde&shp=5563f2fb&shcp=122e87b3&idc=maliva&from=1432613627&from_p=305039283"
],
"category_id_level_1": "901128",
"category_id_level_2": "30122212",
"category_id_level_3": "3321212",
"category_name_level_1": "Shoes",
"category_name_level_2": "Women's Shoes",
"category_name_level_3": "Sandals & Flip Flops",
"is_collected": false,
"query_words": "word1,word2",
"opportunity_type": "PRODUCT",
"brand_name": "brand1",
"create_time": 1712544000,
"expire_time": 1712544000,
"est_market_sales_volume": "100k+",
"est_market_gmv": "9M+",
"search_volume": "3312",
"competitor_product_count": "100+",
"video_view_pv": "7k+",
"tags": "Pencarian teratas,Pencarian trending,Persaingan rendah,Trending di TikTok,Terlaris",
"tag_codes": [
"core_product"
],
"reward_info": "Boost shoptab visibility",
"external_product_id": "SH1234567890",
"reference_source": "1"
}
],
"next_page_token": "100",
"total_count": 200
}
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/list-opportunities-202604"
}
},
"/product/202604/opportunities/submissions": {
"get": {
"operationId": "getSubmissionRecords",
"summary": "Get Submission Records",
"description": "Retrieve a paginated list of submission records for the authorized seller, including submission status, review results, and linked opportunity/product information. Useful for tracking submission history and monitoring review outcomes.",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "status",
"in": "query",
"required": false,
"description": "Filter by submission status: PENDING_REVIEW / APPROVED / REJECTED. Leave empty to return all statuses.",
"schema": {
"type": "string"
}
},
{
"name": "opportunity_id",
"in": "query",
"required": false,
"description": "Filter by specific opportunity ID.",
"schema": {
"type": "string"
}
},
{
"name": "product_id",
"in": "query",
"required": false,
"description": "Filter by specific product ID.",
"schema": {
"type": "string"
}
},
{
"name": "submit_time_ge",
"in": "query",
"required": false,
"description": "Return submissions created at or after this Unix timestamp, in seconds.",
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "submit_time_lt",
"in": "query",
"required": false,
"description": "Filter submissions created before this time, second-level timestamp",
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "page_token",
"in": "query",
"required": false,
"description": "Pagination token from previous response. Omit for first page.",
"schema": {
"type": "string"
}
},
{
"name": "page_size",
"in": "query",
"required": true,
"description": "Number of results per page. Max: 100. Default: 20.",
"schema": {
"type": "integer",
"format": "int64",
"maximum": 100
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetSubmissionRecordsResponse"
},
"example": {
"code": 0,
"data": {
"data": {
"submissions": [
{
"id": "8001234567890123456",
"opportunity_id": "7123456789012345678",
"opportunity_title": "Women's High-Waist Yoga Leggings",
"status": "APPROVED",
"product_id": "7298374612938475620",
"product_name": "Premium Yoga Leggings - Black",
"submit_time": 1775973876,
"review_time": 1775973876,
"rejection_reason": "Product does not match the opportunity category requirements",
"product_orders": 121,
"product_pv": 320
}
],
"next_page_token": "100",
"total_count": 300
}
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-submission-records-202604"
}
},
"/product/202604/opportunities/{opportunity_id}": {
"get": {
"operationId": "getOpportunityDetail",
"summary": "Get Opportunity Detail",
"description": "Retrieve the full details of a single opportunity lead by its ID, including market trend data, competition level, and recommended actions.",
"tags": [
"Products"
],
"parameters": [
{
"name": "opportunity_id",
"in": "path",
"required": true,
"description": "The unique ID of the opportunity lead generated by TikTok Shop.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "locale",
"in": "query",
"required": false,
"description": "The locale used for localized opportunity content, expressed as `{language_code}-{COUNTRY_CODE}` in accordance with BCP 47. If omitted, the API uses the first configured locale for the authenticated shop's region.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetOpportunityDetailResponse"
},
"example": {
"code": 0,
"data": {
"opportunity": {
"id": "7123456789012345678",
"action_type": "LIST_SAME",
"listing_criteria": {
"product_brand": "brand1",
"product_category": "Phones & Electronics > Gaming & Consoles > Console Accessories",
"product_status": "LIVE",
"keywords": "word1,word2"
},
"content_data": {
"video_view_pv": "7k+",
"shoppable_video_search_pv": "336k+",
"trending_hashtag": "tag1,tag2",
"top_shoppable_video_links": [
"https://www.tiktok.com/@/video/v15044gf0000d4l7p57og65m3s0tqfa0",
"https://www.tiktok.com/@/video/v15044gf0000d306lrnog65h1a6283ug"
]
},
"market_data": {
"est_market_sales_volume": "100k+",
"est_market_gmv": "9M+",
"market_buzz": "HOT",
"search_volume": "100000",
"search_keyword": "holiday",
"competitor_product_count": "100+",
"competitor_seller_count": "35"
},
"basic_info": {
"opportunity_type": "PRODUCT",
"status": "ACTIVE",
"create_time": 1775973876,
"expire_time": 1775973876,
"title": "title",
"category_id_level_1": "901128",
"category_id_level_2": "30122212",
"category_id_level_3": "40122212",
"category_name_level_1": "Shoes",
"category_name_level_2": "Women's Shoes",
"category_name_level_3": "Sandals & Flip Flops",
"reference_price": "$36.300 - $38.500",
"reference_images": [
"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/61e605ce483f4f7b9b419d510f74fd22~tplv-o3syd03w52-resize-image:400:400.image?dr=15586&t=555f072d&ps=933b5bde&shp=5563f2fb&shcp=122e87b3&idc=maliva&from=1432613627&from_p=305039283"
],
"brand_info": "some brand info",
"reward_info": "Boost shoptab visibility",
"recom_info": "Trending, but out of stock",
"tags": "Pencarian teratas,Pencarian trending,Persaingan rendah,Trending di TikTok,Terlaris",
"tag_codes": [
"core_product"
],
"external_product_id": "SH1234567890",
"reference_source": "1"
}
}
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-opportunity-detail-202604"
}
},
"/product/202604/opportunities/{opportunity_id}/submit": {
"post": {
"operationId": "submitProductViaOpportunity",
"summary": "Submit Product via Opportunity",
"description": "Submit an existing product as a response to a specific opportunity lead. The product must belong to the authorized shop and be in `ACTIVATE` status. It will be linked to the opportunity and enter the standard submission review flow.\n\nIf you need a new local product, call the [Create Product API](https://partner.tiktokshop.com/docv2/page/create-product-202309) with `save_mode=LISTING`, use the returned `data.product_id`, and wait until the product reaches `ACTIVATE`. A product saved with `save_mode=AS_DRAFT` is not yet eligible. For a global seller that has not migrated to local replication, first call the [Create Global Product API](https://partner.tiktokshop.com/docv2/page/6509de61bace3e02b7489cba) to get a `global_product_id`, then call the [Publish Global Product API](https://partner.tiktokshop.com/docv2/page/publish-global-product-202309). From `data.products`, select the local product `id` for the authorized shop and wait until that product reaches `ACTIVATE` before submitting it here.\n\nAfter submission, use the [Get Submission Records API](https://partner.tiktokshop.com/docv2/page/get-submission-records-202604) and filter by `opportunity_id` or `product_id` to track the review outcome.",
"tags": [
"Products"
],
"parameters": [
{
"name": "opportunity_id",
"in": "path",
"required": true,
"description": "The opportunity lead to respond to. This API does not support opportunities whose `opportunity_type` is `CATEGORY`.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubmitProductViaOpportunityRequest"
},
"example": {
"product_id": "7298374612938475620"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubmitProductViaOpportunityResponse"
},
"example": {
"code": 0,
"data": {
"submission": {
"id": "8001234567890123456",
"opportunity_id": "7123456789012345678",
"product_id": "7298374612938475620",
"status": "PENDING_REVIEW",
"submit_time": 1775979270,
"rejection_reason": "The submitted product does not match the opportunity"
}
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/submit-product-via-opportunity-202604"
}
},
"/product/202604/products/gpa_upgrade_task": {
"post": {
"operationId": "createGPAUpgradeTask",
"summary": "Create GPA Upgrade Task",
"description": "This interface is only available for EU L2L sellers. The interface is used to upgrade products on EU interconnection. After the upgrade, products can be managed using the new interface, but not using interfaces related to Global Product.",
"tags": [
"Products"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateGPAUpgradeTaskRequest"
},
"example": {}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateGPAUpgradeTaskResponse"
},
"example": {
"code": 0,
"data": {},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-scenario": 2,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [
{
"code": "12052234",
"message": "The number of running tasks exceeds the limit."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/create-gpa-upgrade-task-202604"
}
},
"/product/202606/skpps/search": {
"post": {
"operationId": "listProductSKPPStatuses",
"summary": "List Product SKPP Statuses",
"description": "Batch query SKPP status for the seller's products.",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "locale",
"in": "query",
"required": false,
"description": "The BCP-47 locale codes for displaying category information.\nDefault: The default locale of your shop.\nPossible values:\n- en\n- en-GB\n- zh-CN\n- de-DE\n- id-ID\n- it-IT\n- ja-JP\n- ms-MY\n- pt-BR\n- th-TH\n- vi-VN。",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListProductSKPPStatusesRequest"
},
"example": {
"product_ids": [
"7345678901",
"7345678902"
],
"skpp_status": "QUALIFIED",
"page_size": 50,
"page_no": 1
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListProductSKPPStatusesResponse"
},
"example": {
"code": 0,
"data": {
"products": [
{
"product_id": "7345678901234567890",
"title": "Premium Cotton T-Shirt",
"skpp_status": "QUALIFIED",
"affiliate_program_status": "ACTIVE",
"total_score": 8,
"target_score": 7,
"rewards": [
{
"reward_type": "ADS_CREDIT",
"status": "AVAILABLE",
"value": "$15",
"ad_credit_claim_status": "CLAIMED"
}
]
}
],
"total_count": 1234,
"update_time": 1779148799
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [
{
"code": "12081001",
"message": "Invalid request parameters."
},
{
"code": "12081003",
"message": "Internal server error."
},
{
"code": "12081006",
"message": "Unauthorized for SKPP on this shop."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/list-product-skpp-statuses-202606"
}
},
"/product/202606/skpps/sum": {
"get": {
"operationId": "getShopSKPPSummary",
"summary": "Get Shop SKPP Summary",
"description": "Return the shop-level SKPP summary, including qualified and eligible product counts, earned ad credit, and incremental visibility in the last 30 days. This API is available only to shops enrolled as eligible SKPP sellers.",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetShopSKPPSummaryResponse"
},
"example": {
"code": 0,
"data": {
"shop_summary": {
"qualified_products_count": 1,
"eligible_products_count": 5,
"earned_ad_credit": "$500",
"increased_visibility_l30d": "12345"
}
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [
{
"code": "12081001",
"message": "Invalid request parameters."
},
{
"code": "12081003",
"message": "Internal server error."
},
{
"code": "12081006",
"message": "Unauthorized for SKPP on this shop."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-shop-skpp-summary-202606"
}
},
"/product/202606/skpps/{product_id}": {
"get": {
"operationId": "getProductSKPPDetail",
"summary": "Get Product SKPP Detail",
"description": "Return the SKPP qualification status, current and target scores, task progress and suggested actions, reward eligibility and status, and offline snapshot time for one product. This API is available only to sellers authorized for SKPP in the US market.",
"tags": [
"Products"
],
"parameters": [
{
"name": "product_id",
"in": "path",
"required": true,
"description": "Product ID generated by Tiktok Shop.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "locale",
"in": "query",
"required": false,
"description": "The BCP-47 locale codes for displaying category information.\nDefault: The default locale of your shop.\nPossible values:\n- en\n- en-GB\n- zh-CN\n- de-DE\n- id-ID\n- it-IT\n- ja-JP\n- ms-MY\n- pt-BR\n- th-TH\n- vi-VN",
"schema": {
"type": "string",
"enum": [
"en",
"en-GB",
"zh-CN",
"de-DE",
"id-ID",
"it-IT",
"ja-JP",
"ms-MY",
"pt-BR",
"th-TH",
"vi-VN"
]
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetProductSKPPDetailResponse"
},
"example": {
"code": 0,
"data": {
"product_id": "7311223344556677889",
"affiliate_program_status": "ACTIVE",
"total_score": 6,
"target_score": 8,
"rewards": [
{
"reward_type": "BIG_PROMOTION_CAMPAIGN",
"title": "Ad credit reward",
"status": "AVAILABLE",
"ad_credit_claim_status": "UNCLAIMED",
"value": "100",
"claim_conditions": [
{
"condition_type": "GMV",
"current_value": "72",
"target_value": "100"
}
],
"campaign_id": "7390000000000000000"
}
],
"task_details": [
{
"category": "INFORMATION_QUALITY",
"name": "Improve product title",
"current_value": "12",
"target_value": "20",
"passed": false,
"action_suggestions": [
{
"score_increase": 8,
"url": "https://seller.tiktokglobalshop.com/product/edit"
}
]
}
],
"update_time": 1779148799,
"skpp_status": "QUALIFIED"
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [
{
"code": "12081001",
"message": "Invalid request parameters."
},
{
"code": "12081003",
"message": "Internal server error."
},
{
"code": "12081006",
"message": "Unauthorized for SKPP on this shop."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-product-skpp-detail-202606"
}
},
"/product/202608/inventory/operation/settings": {
"post": {
"operationId": "updateStockOperationSettings",
"summary": "Update Stock Operation Settings",
"description": "Configure auto-restock behavior for 1 to 500 SKUs in one request. For seller-fulfilled orders, this setting controls whether inventory reserved for a canceled order is returned to the SKU's available inventory.",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateStockOperationSettingsRequest"
},
"example": {
"seller_id": "124129082343241",
"sku_ids": [
"124148921741214"
],
"stock_operation_setting": {
"enable_auto_restock": false
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateStockOperationSettingsResponse"
},
"example": {
"code": 0,
"data": {
"stock_operation": {
"failed_sku_ids": [
"124148921741214"
],
"success_sku_ids": [
"124148921741214"
]
}
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Product Basic"
],
"x-tts-error-codes": [
{
"code": "12001017",
"message": "sku id is invalid"
},
{
"code": "12019017",
"message": "The stock of SKU exceed the limit"
},
{
"code": "12019112",
"message": "seller id is invalid"
},
{
"code": "12019114",
"message": "Seller has no permission"
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/update-stock-operation-settings-202608"
}
},
"/product/202609/brands/suggest": {
"post": {
"operationId": "suggestBrands",
"summary": "Suggest Brands",
"description": "Recommend brands based on product information.",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuggestBrandsRequest"
},
"example": {
"product_title": "Teas Green Tea",
"category_id": "600006",
"description": "Green tea.",
"images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuggestBrandsResponse"
},
"example": {
"code": 0,
"data": {
"brands": [
{
"id": "7082427311584347905",
"is_authorized": true,
"name": "Teas"
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [],
"x-tts-error-codes": [
{
"code": "12052109",
"message": "number of requests from merchants over limit"
},
{
"code": "12052261",
"message": "product name is empty"
},
{
"code": "12052704",
"message": "seller id not exist"
},
{
"code": "12052910",
"message": "Invalid input parameters. Refer to the API documentation for details."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/suggest-brands-202609"
}
},
"/product/202609/products/package/predict": {
"post": {
"operationId": "predictProductPackageDimensionsAndWeight",
"summary": "Predict Product Package Dimensions and Weight",
"description": "Predicts the package dimensions and weight for one candidate product based on its leaf category. The result is generated synchronously and can be used to prepare the package information in a create or edit product request. When no prediction is available, `data` is an empty object.",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PredictProductPackageDimensionsAndWeightRequest"
},
"example": {
"category_id": "600001"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PredictProductPackageDimensionsAndWeightResponse"
},
"example": {
"code": 0,
"data": {
"package_dimensions": {
"height": 10,
"length": 30,
"unit": "CENTIMETER",
"width": 20
},
"package_weight": {
"unit": "GRAM",
"value": "500"
}
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [],
"x-tts-error-codes": [],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/predict-product-package-dimensions-and-weight-202609"
}
},
"/product/202609/products/properties/recommend": {
"post": {
"operationId": "recommendRequiredProductProperties",
"summary": "Recommend Required Product Properties",
"description": "Predicts the required product properties and their recommended values from the product category and content. The result is generated synchronously for one product and can be used to prepare a create or edit product request.\n\nDo not include personal data, such as names, phone numbers, email addresses, or postal addresses, in the product title, description, or images. The response does not return the submitted product content.",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecommendRequiredProductPropertiesRequest"
},
"example": {
"category_id": "600001",
"description": "Lightweight cotton ankle socks designed for everyday wear.",
"images": [
{
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
}
],
"product_title": "Short Boat Invisible Socks",
"sales_properties": [
{
"id": "100000",
"values": [
{
"id": "100001"
}
]
}
],
"target_property_ids": [
"100392"
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecommendRequiredProductPropertiesResponse"
},
"example": {
"code": 0,
"data": {
"recommended_properties": [
{
"id": "100392",
"is_customizable": false,
"is_multiple_selection": false,
"is_required": true,
"name": "Occasion",
"type": "PRODUCT_PROPERTY",
"values": [
{
"id": "1001533",
"name": "Birthday"
}
]
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [],
"x-tts-error-codes": [],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/recommend-required-product-properties-202609"
}
},
"/product/202609/products/{product_id}/strikethrough_price/submit": {
"post": {
"operationId": "submitStrikethroughPrice",
"summary": "Submit Strikethrough Price",
"description": "Submit external pricing information for a product's SKUs so that TikTok Shop can verify the product's list price for use as a strikethrough price. If the submitted information is approved, the verified list price may be displayed as the strikethrough price when a discount applies.\n\nSubmitted pricing information expires 90 days after submission and must be resubmitted to continue supporting strikethrough price display.",
"tags": [
"Products"
],
"parameters": [
{
"name": "product_id",
"in": "path",
"required": true,
"description": "The product ID in TikTok Shop.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubmitStrikethroughPriceRequest"
},
"example": {
"external_product_id": "000059296971220002",
"skus": [
{
"external_retail_price": {
"amount": "10.00",
"currency": "USD"
},
"external_sku_id": "0000592969712207012",
"external_transaction_price": {
"amount": "12.00",
"currency": "USD",
"image": {
"uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
},
"transaction_time": "2026-09-15T08:30:00Z"
},
"id": "1729592969712207111"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubmitStrikethroughPriceResponse"
},
"example": {
"code": 0,
"data": {
"errors": []
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [],
"x-tts-error-codes": [],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/submit-strikethrough-price-202609"
}
},
"/product/202610/size_charts": {
"post": {
"operationId": "createSizeChartV2",
"summary": "Create Size Chart V2",
"description": "Create one size chart from structured table data. Use `REUSABLE_TEMPLATE` to create a seller template that can be reused across products, or `PRODUCT_SCOPED` to create a chart for a single product. The response returns the created size chart ID. The request must identify one authorized shop using shop_cipher.",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateSizeChartV2Request"
},
"example": {
"category_id": "601739",
"size_chart_data": {
"description": "Use body measurements.",
"is_one_size": false,
"measurement_type": "BODY_MEASUREMENTS",
"size_types": [
"size_chart_size_type_regular"
],
"table": {
"headers": [
{
"id": "size_chart_size_system_size",
"name": "Size"
},
{
"id": "size_chart_option_bust",
"name": "Bust"
}
],
"rows": [
{
"cells": [
{
"value": "M"
},
{
"value": "90"
}
]
}
]
},
"unit_system": "METRIC"
},
"size_chart_mode": "REUSABLE_TEMPLATE",
"template_name": "Women's Tops Size Chart"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateSizeChartV2Response"
},
"example": {
"code": 0,
"data": {
"size_chart_id": "7612345678901234567"
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [],
"x-tts-error-codes": [],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/create-size-chart-v2-202610"
}
},
"/product/202610/size_charts/edit": {
"post": {
"operationId": "editSizeChartV2",
"summary": "Edit Size Chart V2",
"description": "Edit an existing seller-owned size chart by replacing its structured table and editable metadata. Omit `template_name` to keep the current template name. The request must identify one authorized shop using shop_cipher.",
"tags": [
"Products"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EditSizeChartV2Request"
},
"example": {
"size_chart_data": {
"description": "Use body measurements.",
"is_one_size": false,
"measurement_type": "BODY_MEASUREMENTS",
"size_types": [
"size_chart_size_type_regular"
],
"table": {
"headers": [
{
"id": "size_chart_size_system_size",
"name": "Size"
},
{
"id": "size_chart_option_bust",
"name": "Bust"
}
],
"rows": [
{
"cells": [
{
"value": "M"
},
{
"value": "90"
}
]
}
]
},
"unit_system": "METRIC"
},
"size_chart_id": "7612345678901234567",
"template_name": "Women's Tops"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EditSizeChartV2Response"
},
"example": {
"code": 0,
"data": {
"size_chart_id": "12345"
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [],
"x-tts-error-codes": [],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/edit-size-chart-v2-202610"
}
},
"/promotion/202309/activities": {
"post": {
"operationId": "createPromotionActivity",
"summary": "Create Promotion Activity",
"description": "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](https://partner.tiktokshop.com/docv2/page/650d32c42aaa3602b86ccb5c).",
"tags": [
"Promotion"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatePromotionActivityRequest"
},
"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": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatePromotionActivityResponse"
},
"example": {
"code": 0,
"data": {
"activity_id": "7136104329798256386",
"create_time": 1661756811,
"update_time": 1661756811,
"status": "ONGOING"
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Promotion Modify"
],
"x-tts-error-codes": [
{
"code": "17003203",
"message": "A storewide free shipping promotion activity is already active. Only one can be created at a time."
},
{
"code": "17029001",
"message": "Invalid parameters"
},
{
"code": "17029002",
"message": "Title Length Too Long"
},
{
"code": "17029004",
"message": "Duplicate activity title."
},
{
"code": "17029005",
"message": "Begin Time Earlier Than Now"
},
{
"code": "17029006",
"message": "The activity period is too short."
},
{
"code": "17029007",
"message": "The activity period is too long."
},
{
"code": "17029008",
"message": "FlashSale Period Too Long"
},
{
"code": "17029026",
"message": "Invalid SellerID"
},
{
"code": "17029027",
"message": "Empty RequestSerialNo"
},
{
"code": "17029035",
"message": "ShopRisk Check Failed"
},
{
"code": "17029036",
"message": "ActivityType is not supported."
},
{
"code": "17029049",
"message": "ActivityVersion is not supported."
},
{
"code": "17029052",
"message": "ProductType is not supported"
},
{
"code": "17029068",
"message": "Selected `inventory_type` is not supported in your region."
},
{
"code": "17029070",
"message": "Empty gift sku info."
},
{
"code": "17029071",
"message": "Gift sku id is invalid, not an integer."
},
{
"code": "17029072",
"message": "Gift sku repeated"
},
{
"code": "17029073",
"message": "Price of the gift exceeds the upper limit"
},
{
"code": "17029074",
"message": "Eligible products and the gift products must not be the same product."
},
{
"code": "17029075",
"message": "Number of gifts per tier does not meet the limit"
},
{
"code": "17029076",
"message": "Gift sku is out of stock."
},
{
"code": "17029077",
"message": "Gifts across different tiers are repeated"
},
{
"code": "17029078",
"message": "Number of gift tiers does not meet the requirement"
},
{
"code": "17029082",
"message": "Specified time is outside of the defined range for this activity. Please check the time range for the activity and try again."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/create-promotion-activity-202309"
}
},
"/promotion/202309/activities/search": {
"post": {
"operationId": "searchPromotionActivities",
"summary": "Search Promotion Activities",
"description": "Search product discount, flash sale, shipping discount, Buy More Save More, Gift With Purchase, and Buy X Get Y promotion activities. For coupon activities, use [Search Coupons](https://partner.tiktokshop.com/docv2/page/6699dcdf115ebe02f841e4cd).",
"tags": [
"Promotion"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchPromotionActivitiesRequest"
},
"example": {
"status": "ONGOING",
"activity_title": "Discount",
"page_size": 20,
"page_token": "21",
"activity_type": "FLASHSALE"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchPromotionActivitiesResponse"
},
"example": {
"code": 0,
"data": {
"total_count": 120,
"next_page_token": "1661756811000",
"activities": [
{
"id": "7136104329798256386",
"title": "FlashSale 20230707",
"activity_type": "FIXED_PRICE",
"duration_type": "INDEFINITE",
"begin_time": 1661756811,
"end_time": 1661756811,
"status": "ONGOING",
"create_time": 1788301318971,
"update_time": 1788301318971,
"product_level": "PRODUCT",
"activity_commands": [
"IMMUTABLE"
],
"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"
}
},
"auction_support_type": "ALL"
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Promotion Information"
],
"x-tts-error-codes": [
{
"code": "17029001",
"message": "Invalid parameters"
},
{
"code": "17029055",
"message": "Request Timeout"
},
{
"code": "17029059",
"message": "`page_token + page_size` must be less than `10000`."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-promotion-activities-202309"
}
},
"/promotion/202309/activities/{activity_id}": {
"get": {
"operationId": "getActivity",
"summary": "Get Activity",
"description": "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](6699dce0de15e502ed219e37).",
"tags": [
"Promotion"
],
"parameters": [
{
"name": "activity_id",
"in": "path",
"required": true,
"description": "Activity ID",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetActivityResponse"
},
"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"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Promotion Information"
],
"x-tts-error-codes": [
{
"code": "17029001",
"message": "Invalid parameters"
},
{
"code": "17029009",
"message": "Activity does not exist"
},
{
"code": "17029028",
"message": "You are specifying activities not in your shop."
},
{
"code": "17029036",
"message": "ActivityType is not supported."
},
{
"code": "17029052",
"message": "ProductType is not supported"
},
{
"code": "17029055",
"message": "Request Timeout"
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-activity-202309"
},
"put": {
"operationId": "updatePromotionActivity",
"summary": "Update Promotion Activity",
"description": "Update an existing promotion activity. The stored activity type determines which request fields are processed:\n- 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.\n- For a shipping-discount activity, provide discount.shipping_discount; use duration_type to choose a scheduled or indefinite activity.\n- 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.\n- 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.\nFixed-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.",
"tags": [
"Promotion"
],
"parameters": [
{
"name": "activity_id",
"in": "path",
"required": true,
"description": "The unique identifier of the promotion activity.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdatePromotionActivityRequest"
},
"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": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdatePromotionActivityResponse"
},
"example": {
"code": 0,
"data": {
"activity_id": "7136104329798256386",
"title": "BlackFridayDiscount",
"update_time": 1661756811
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Promotion Modify"
],
"x-tts-error-codes": [
{
"code": "17003203",
"message": "A storewide free shipping promotion activity is already active. Only one can be created at a time."
},
{
"code": "17029001",
"message": "Invalid parameters"
},
{
"code": "17029002",
"message": "Title Length Too Long"
},
{
"code": "17029003",
"message": "The activity title is empty."
},
{
"code": "17029004",
"message": "Duplicate activity title."
},
{
"code": "17029005",
"message": "Begin Time Earlier Than Now"
},
{
"code": "17029006",
"message": "The activity period is too short."
},
{
"code": "17029007",
"message": "The activity period is too long."
},
{
"code": "17029008",
"message": "FlashSale Period Too Long"
},
{
"code": "17029009",
"message": "Activity does not exist"
},
{
"code": "17029010",
"message": "Activity is deactivated"
},
{
"code": "17029011",
"message": "Not allowed to update the beginning time of activity"
},
{
"code": "17029012",
"message": "Not allowed to update expired activities"
},
{
"code": "17029022",
"message": "The product or SKU cannot be in two `ONGOING` or `NOT_START` activities at the same time."
},
{
"code": "17029026",
"message": "Invalid SellerID"
},
{
"code": "17029028",
"message": "You are specifying activities not in your shop."
},
{
"code": "17029052",
"message": "ProductType is not supported"
},
{
"code": "17029070",
"message": "Empty gift sku info."
},
{
"code": "17029071",
"message": "Gift sku id is invalid, not an integer."
},
{
"code": "17029072",
"message": "Gift sku repeated"
},
{
"code": "17029073",
"message": "Price of the gift exceeds the upper limit"
},
{
"code": "17029074",
"message": "Eligible products and the gift products must not be the same product."
},
{
"code": "17029075",
"message": "Number of gifts per tier does not meet the limit"
},
{
"code": "17029076",
"message": "Gift sku is out of stock."
},
{
"code": "17029077",
"message": "Gifts across different tiers are repeated"
},
{
"code": "17029078",
"message": "Number of gift tiers does not meet the requirement"
},
{
"code": "17029082",
"message": "Specified time is outside of the defined range for this activity. Please check the time range for the activity and try again."
},
{
"code": "17029083",
"message": "The claim limit quantity of gift can not be decreased"
},
{
"code": "17029084",
"message": "The threshold type of gift can not be modified"
},
{
"code": "17029085",
"message": "The number of gift tiers can not be changed"
},
{
"code": "17029102",
"message": "Product level and shop level are not interchangeable"
},
{
"code": "17029103",
"message": "Partial of products have already been applied to another conflict promotion during the selected period."
},
{
"code": "17029104",
"message": "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."
},
{
"code": "17029105",
"message": "The threshold type and discount type can not be modified."
},
{
"code": "17029106",
"message": "Participation Limit info cannot change or modify."
},
{
"code": "17029107",
"message": "Due to overlapping with other activities, sellers cannot create shop-scope BMSM activity."
},
{
"code": "17029109",
"message": "The promotion exceeds the threshold."
},
{
"code": "17029110",
"message": "The discount value is below the minimum threshold."
},
{
"code": "17029111",
"message": "The threshold value is invalid."
},
{
"code": "17029112",
"message": "The discount value is invalid."
},
{
"code": "17029113",
"message": "The number of products will exceed the maximum number of the promotion."
},
{
"code": "17029114",
"message": "The promotion type is not supported."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/update-promotion-activity-202309"
}
},
"/promotion/202309/activities/{activity_id}/deactivate": {
"post": {
"operationId": "deactivateActivity",
"summary": "Deactivate Activity",
"description": "Deactivate an ongoing or upcoming activity.",
"tags": [
"Promotion"
],
"parameters": [
{
"name": "activity_id",
"in": "path",
"required": true,
"description": "A unique ID that identifies different activities.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeactivateActivityRequest"
},
"example": {}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeactivateActivityResponse"
},
"example": {
"code": 0,
"data": {
"activity_id": "7136104329798256386",
"title": "FlashSale 20230707",
"status": "DEACTIVATED",
"update_time": 1661756811
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Promotion Modify"
],
"x-tts-error-codes": [
{
"code": "17029001",
"message": "Invalid parameters"
},
{
"code": "17029009",
"message": "Activity does not exist"
},
{
"code": "17029010",
"message": "Activity is deactivated"
},
{
"code": "17029011",
"message": "Not allowed to update the beginning time of activity"
},
{
"code": "17029012",
"message": "Not allowed to update expired activities"
},
{
"code": "17029028",
"message": "You are specifying activities not in your shop."
},
{
"code": "17029036",
"message": "ActivityType is not supported."
},
{
"code": "17029052",
"message": "ProductType is not supported"
},
{
"code": "17029055",
"message": "Request Timeout"
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/deactivate-activity-202309"
}
},
"/promotion/202309/activities/{activity_id}/products": {
"put": {
"operationId": "updatePromotionActivityProducts",
"summary": "Update Promotion Activity Products",
"description": "Use this API as follows:\n- 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.\n- 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.\n- 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.\n- 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.\nFor 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](https://partner.tiktokshop.com/docv2/page/650acfd84a0bb702c072b4eb).",
"tags": [
"Promotion"
],
"parameters": [
{
"name": "activity_id",
"in": "path",
"required": true,
"description": "The unique identifier of the promotion activity.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdatePromotionActivityProductsRequest"
},
"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": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdatePromotionActivityProductsResponse"
},
"example": {
"code": 0,
"data": {
"activity_id": "7136104329798256386",
"title": "DiscountPromotion",
"update_time": 1661756811,
"status": "DRAFT",
"total_count": 1
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Promotion Modify"
],
"x-tts-error-codes": [
{
"code": "17011102",
"message": "Promotion title cannot be a duplicate."
},
{
"code": "17027107",
"message": "Internal system error, please try again later."
},
{
"code": "17029001",
"message": "Invalid parameters"
},
{
"code": "17029009",
"message": "Activity does not exist"
},
{
"code": "17029010",
"message": "Activity is deactivated"
},
{
"code": "17029012",
"message": "Not allowed to update expired activities"
},
{
"code": "17029013",
"message": "`sku` must be `[]` for activities of which `product_level==PRODUCT`."
},
{
"code": "17029014",
"message": "The value of `quantity_per_user` is out of range."
},
{
"code": "17029015",
"message": "When `product_level==VARIATION`, the value of `quantity_limit` must be `-1`."
},
{
"code": "17029016",
"message": "Invalid SKU ID."
},
{
"code": "17029017",
"message": "You are specifying products not in your shop."
},
{
"code": "17029018",
"message": "The provided SKU quantity is greater than the available stock."
},
{
"code": "17029019",
"message": "The provided product quantity is greater than the available stock."
},
{
"code": "17029020",
"message": "Product discount exceeds limit. The limit varies based on products and regions."
},
{
"code": "17029021",
"message": "SKU discount exceeds limit. The limit varies based on products and regions."
},
{
"code": "17029022",
"message": "The product or SKU cannot be in two `ONGOING` or `NOT_START` activities at the same time."
},
{
"code": "17029025",
"message": "The quantity of the products or the SKUs included in the activity exceeds `10000`."
},
{
"code": "17029026",
"message": "Invalid SellerID"
},
{
"code": "17029028",
"message": "You are specifying activities not in your shop."
},
{
"code": "17029029",
"message": "You are incorrectly specifying `activity_price_amount` instead of `discount` when `activity_type==DIRECT_DISCOUNT` and `product_level==PRODUCT`."
},
{
"code": "17029030",
"message": "You are incorrectly specifying `discount` instead of `activity_price_amount` when `activity_type==FIXED_PRICE / FLASHSALE` and `product_level==PRODUCT`."
},
{
"code": "17029031",
"message": "You are incorrectly specifying `activity_price_amount` instead of `discount` when `activity_type==DIRECT_DISCOUNT` and `product_level==VARIATION`."
},
{
"code": "17029032",
"message": "You are incorrectly specifying `discount` instead of `activity_price_amount` when `activity_type==FIXED_PRICE / FLASHSALE` and `product_level==VARIATION`."
},
{
"code": "17029033",
"message": "`products` is empty."
},
{
"code": "17029034",
"message": "`activity_price_amount` is invalid."
},
{
"code": "17029037",
"message": "`skus` is empty when `product_level==VARIATION`."
},
{
"code": "17029038",
"message": "When `product_level==VARIATION`, you must not specify `product.activity_price_amount` and `product.discount`."
},
{
"code": "17029039",
"message": "Duplicate product ID."
},
{
"code": "17029040",
"message": "Duplicate SKU ID."
},
{
"code": "17029041",
"message": "You must specify `product.discount` when `activity_type==DIRECT_DISCOUNT` and `product_level==PRODUCT`."
},
{
"code": "17029042",
"message": "You must specify `product.activity_price_amount` when `activity_type==FIXED_PRICE / FLASHSALE` and `product_level==PRODUCT`."
},
{
"code": "17029043",
"message": "You must specify `sku.discount` when `activity_type==DIRECT_DISCOUNT` and `product_level==VARIATION`."
},
{
"code": "17029044",
"message": "You must specify `sku.activity_price_amount` when `activity_type==FIXED_PRICE / FLASHSALE` and `product_level==VARIATION`."
},
{
"code": "17029045",
"message": "Duplicated RequestSerialNo."
},
{
"code": "17029046",
"message": "Number of items per request exceeds the limit."
},
{
"code": "17029047",
"message": "An `ONGOING` flash sale product cannot be updated."
},
{
"code": "17029048",
"message": "An `ONGOING` flash sale SKU cannot be updated."
},
{
"code": "17029049",
"message": "ActivityVersion is not supported."
},
{
"code": "17029050",
"message": "The value of `quantity_limit` and `quantity_per_user` must be `-1` or in the range of `[1, 99]`."
},
{
"code": "17029051",
"message": "Product ID not found."
},
{
"code": "17029053",
"message": "The SKU ID does not match the product ID."
},
{
"code": "17029054",
"message": "Please limit the request frequency."
},
{
"code": "17029055",
"message": "Request Timeout"
},
{
"code": "17029056",
"message": "Invalid product status."
},
{
"code": "17029058",
"message": "Unable to decrease buyer/num PurchaseLimit."
},
{
"code": "17029060",
"message": "The Categories of products is invalid"
},
{
"code": "17029062",
"message": "Discount is below the limit, please confirm."
},
{
"code": "17029063",
"message": "SKU discount is below the limit, please confirm."
},
{
"code": "17029064",
"message": "Product is non-sellable."
},
{
"code": "17029065",
"message": "Target quota is less than the initial quota."
},
{
"code": "17029066",
"message": "Limit info cannot be changed or modified."
},
{
"code": "17029067",
"message": "Auction products are not eligible for promotions."
},
{
"code": "17029069",
"message": "Access denied. This activity does not belong to this shop and therefore cannot be modified."
},
{
"code": "17029074",
"message": "Eligible products and the gift products must not be the same product."
},
{
"code": "17029079",
"message": "Product is already assigned in another conflicting promotion."
},
{
"code": "17029103",
"message": "Partial of products have already been applied to another conflict promotion during the selected period."
},
{
"code": "17029104",
"message": "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."
},
{
"code": "17029113",
"message": "The number of products will exceed the maximum number of the promotion."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/update-promotion-activity-products-202309"
},
"delete": {
"operationId": "removePromotionActivityProducts",
"summary": "Remove Promotion Activity Products",
"description": "Use this API for `FIXED_PRICE`, `DIRECT_DISCOUNT`, `FLASHSALE`, `BUY_MORE_SAVE_MORE`, `BUY_X_GET_Y`, `GIFT_WITH_PURCHASE`, and `SHIPPING_DISCOUNT` activities. Provide at least one non-empty removal list; omitting the body, sending an empty object, or sending only empty lists does not request an item removal.\n- When removing ordinary activity products from a PRODUCT-scoped activity, use `product_ids` and do not provide `sku_ids`.\n- When removing ordinary activity products or SKUs from a VARIATION-scoped activity, use `product_ids`, `sku_ids`, or both.\n- For `GIFT_WITH_PURCHASE`, provide a non-empty `product_ids` list; the other removal lists are not processed by its branch.\n- For `BUY_MORE_SAVE_MORE` or `BUY_X_GET_Y`, `benefit_product_ids` removes benefit-product relations without requiring `product_ids`.\n- For a SHOP-scoped `BUY_MORE_SAVE_MORE`, `BUY_X_GET_Y`, or `SHIPPING_DISCOUNT` activity, `exclude_product_ids` removes excluded-product relations.\nYou can provide multiple applicable non-empty lists in one ordinary non-GWP request. You cannot remove items from a `DEACTIVATED` or `EXPIRED` activity.",
"tags": [
"Promotion"
],
"parameters": [
{
"name": "activity_id",
"in": "path",
"required": true,
"description": "The unique identifier of the promotion activity.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RemovePromotionActivityProductsRequest"
},
"example": {
"product_ids": [
"7493989962827597361"
],
"sku_ids": [
"7135657830438176513"
],
"benefit_product_ids": [
"7493989962827597361"
],
"exclude_product_ids": [
"7493989962827597361"
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RemovePromotionActivityProductsResponse"
},
"example": {
"code": 0,
"data": {
"activity_id": "7136104329798256386",
"status": "ONGOING",
"update_time": 1661765135
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Promotion Modify"
],
"x-tts-error-codes": [
{
"code": "17027802",
"message": "Internal error, promotion purchase limit deletion failed, please try again"
},
{
"code": "17029001",
"message": "Invalid parameters"
},
{
"code": "17029009",
"message": "Activity does not exist"
},
{
"code": "17029010",
"message": "Activity is deactivated"
},
{
"code": "17029011",
"message": "Not allowed to update the beginning time of activity"
},
{
"code": "17029012",
"message": "Not allowed to update expired activities"
},
{
"code": "17029016",
"message": "Invalid SKU ID."
},
{
"code": "17029023",
"message": "Products Not In Promotion"
},
{
"code": "17029024",
"message": "SKU(s) not found in this promotion."
},
{
"code": "17029028",
"message": "You are specifying activities not in your shop."
},
{
"code": "17029036",
"message": "ActivityType is not supported."
},
{
"code": "17029046",
"message": "Number of items per request exceeds the limit."
},
{
"code": "17029047",
"message": "An `ONGOING` flash sale product cannot be updated."
},
{
"code": "17029048",
"message": "An `ONGOING` flash sale SKU cannot be updated."
},
{
"code": "17029052",
"message": "ProductType is not supported"
},
{
"code": "17029055",
"message": "Request Timeout"
},
{
"code": "17029069",
"message": "Access denied. This activity does not belong to this shop and therefore cannot be modified."
},
{
"code": "17029074",
"message": "Eligible products and the gift products must not be the same product."
},
{
"code": "17029079",
"message": "Product is already assigned in another conflicting promotion."
},
{
"code": "17029102",
"message": "Product level and shop level are not interchangeable"
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/remove-promotion-activity-products-202309"
}
},
"/promotion/202406/coupons/search": {
"post": {
"operationId": "searchCouponList",
"summary": "Search Coupon List",
"description": "Use this API to search coupons. Supported coupon creation sources include TikTok Shop Seller Center, the TikTok Seller App, and TikTok Shop CRM. Different supplied filters are combined with AND. Within status or display_type, multiple values are combined with OR. title_keyword performs phrase-prefix matching against the coupon title. For full details about a specific coupon, use the Get Coupon API.",
"tags": [
"Promotion"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "page_token",
"in": "query",
"required": false,
"description": "Page cursor. Omitting this parameter will return the first page of results.",
"schema": {
"type": "string"
}
},
{
"name": "page_size",
"in": "query",
"required": false,
"description": "The number of coupons returned in one page of results. The range is `[1, 100]`, with a default value of `50`.",
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchCouponListRequest"
},
"example": {
"status": [
"ONGOING"
],
"title_keyword": "Coupon123",
"display_type": [
"CHAT"
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchCouponListResponse"
},
"example": {
"code": 0,
"data": {
"total_count": 20,
"next_page_token": "1661756811000",
"coupons": [
{
"id": "7342461823095965461",
"title": "Coupon202407",
"display_type": "CHAT\n\n\n",
"status": "NOT_START\n\n\n\n",
"create_time": 1661756811000,
"update_time": 1661756811000,
"claim_duration": {
"start_time": 1709568000,
"end_time": 1709654340
},
"redemption_duration": {
"type": "ABSOLUTE",
"start_time": 1709654340,
"end_time": 1709754340,
"relative_time": 4
},
"promo_code": "TTS12345",
"target_buyer_segment": "NEW",
"usage_limits": {
"single_buyer_claim_limit": 30,
"total_claim_limit": 1000,
"redemption_limit": 1000
},
"discount": {
"type": "AMOUNT_OFF",
"reduction_amount": {
"amount": "30.5",
"currency": "USD"
},
"percentage": "30",
"max_discount": {
"amount": "40",
"currency": "USD"
}
},
"threshold": {
"type": "MIN_SPEND",
"min_spend": {
"amount": "30",
"currency": "USD"
}
},
"product_scope": "FULL_SHOP",
"creation_source": "SELLER_CENTER"
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Customer Service",
"Promotion Information"
],
"x-tts-error-codes": [
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-coupon-list-202406"
}
},
"/promotion/202406/coupons/{coupon_id}": {
"get": {
"operationId": "getCoupon",
"summary": "Get Coupon",
"description": "Use this API to get the full details of a coupon matching the {coupon_id}.",
"tags": [
"Promotion"
],
"parameters": [
{
"name": "coupon_id",
"in": "path",
"required": true,
"description": "The unique identifier of the coupon.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetCouponResponse"
},
"example": {
"code": 0,
"data": {
"coupon": {
"id": "7342461823095965461",
"title": "Coupon202407",
"display_type": "CHAT\n\n\n",
"status": "NOT_START\n\n\n\n",
"create_time": 1661756811000,
"update_time": 1661756811000,
"claim_duration": {
"start_time": 1709568000,
"end_time": 1709654340
},
"redemption_duration": {
"type": "ABSOLUTE",
"start_time": 1709754340,
"end_time": 1709768000,
"relative_time": 4
},
"display_channels": [
"SHOPPING_CENTER"
],
"promo_code": "TTS12345",
"target_buyer_segment": "NEW",
"usage_limits": {
"single_buyer_claim_limit": 30,
"total_claim_limit": 1000,
"redemption_limit": 1000
},
"usage_stats": {
"claimed_count": 5,
"redeemed_count": 0
},
"discount": {
"type": "AMOUNT_OFF",
"reduction_amount": {
"amount": "30.5",
"currency": "USD"
},
"percentage": "30",
"max_discount": {
"amount": "40",
"currency": "USD"
}
},
"threshold": {
"type": "MIN_SPEND",
"min_spend": {
"amount": "30",
"currency": "USD"
}
},
"product_scope": "FULL_SHOP",
"product_ids": [
"1729581162206365900"
],
"seller_tnc": "terms & conditions: xxx",
"creation_source": "SELLER_CENTER",
"live_tasks": [
{
"type": "FOLLOW_HOST",
"min_watch_time": "60"
}
]
}
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Customer Service",
"Promotion Information"
],
"x-tts-error-codes": [
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-coupon-202406"
}
},
"/promotion/202607/activities/{activity_id}/republish": {
"post": {
"operationId": "republishActivity",
"summary": "Republish Activity",
"description": "Use this API to republish a product discount activity or a flash deal activity that expired or was deactivated within the last 7 days. This API only supports FIXED_PRICE, FLASHSALE, and DIRECT_DISCOUNT activities. You must provide a new effective period by passing the new begin_time and end_time. Products and SKUs already associated with the activity do not need to be added again. After the activity is republished, you can edit the activity and modify its products or SKUs as usual. We recommend using this API instead of recreating the activity to reduce requests to the API for adding products.",
"tags": [
"Promotion"
],
"parameters": [
{
"name": "activity_id",
"in": "path",
"required": true,
"description": "A unique ID that identifies different activities.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RepublishActivityRequest"
},
"example": {
"end_time": 1782895064,
"begin_time": 1782875064
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RepublishActivityResponse"
},
"example": {
"code": 0,
"data": {
"activity_id": "7136104329798256386"
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Promotion Modify"
],
"x-tts-error-codes": [
{
"code": "17003243",
"message": "This activity don't allow republishing"
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/republish-activity-202607"
}
},
"/return_refund/202309/cancellations/{cancel_id}/approve": {
"post": {
"operationId": "approveCancellation",
"summary": "Approve Cancellation",
"description": "Use this API to approve a buyer-initiated cancellation request identified by cancel_id. Call this API only when the cancellation request is still waiting for seller action.",
"tags": [
"Return and refund"
],
"parameters": [
{
"name": "cancel_id",
"in": "path",
"required": true,
"description": "The cancellation request ID to approve. Use the `cancel_id` returned by Search Cancellations. Do not pass the order ID here.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "idempotency_key",
"in": "query",
"required": false,
"description": "The idempotency key is a unique value generated by the client which the server uses to recognize a request.\n\nIf you retry the same cancellation approval request, use the same key. If this parameter is omitted, the server generates an idempotency key for the request.\n\nYou may choose your own method of creating unique keys. We suggest using UUIDs, or another random string with enough entropy, to avoid collisions.\n\nIdempotency keys can be up to 255 characters long.",
"schema": {
"type": "string",
"maxLength": 255
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApproveCancellationRequest"
},
"example": {}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApproveCancellationResponse"
},
"example": {
"code": 0,
"data": {},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Return & Refund Basic"
],
"x-tts-error-codes": [
{
"code": "11050001",
"message": "invalid param"
},
{
"code": "25001001",
"message": "An invalid request parameter was passed. Please check that you have the correct parameter type(s) and format."
},
{
"code": "25001003",
"message": "Invalid order status."
},
{
"code": "25001028",
"message": "reverse lock failed"
},
{
"code": "25001045",
"message": "The order has already been shipped and we are unable to cancel shipment with the courier."
},
{
"code": "25001058",
"message": "reverse downstream data load error"
},
{
"code": "25007002",
"message": "db access error"
},
{
"code": "25007006",
"message": "Order not found."
},
{
"code": "25011012",
"message": "reverse status cannot approve application"
},
{
"code": "25020003",
"message": "decision not match reverse status"
},
{
"code": "25020004",
"message": "decision not match reverse type"
},
{
"code": "25020005",
"message": "No permission to process this order"
},
{
"code": "25020009",
"message": "reverse already cancelled"
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/approve-cancellation-202309"
}
},
"/return_refund/202309/cancellations/{cancel_id}/reject": {
"post": {
"operationId": "rejectCancellation",
"summary": "Reject Cancellation",
"description": "Use this API to reject a buyer's cancellation request for the specified cancel_id. Before calling this API, make sure the request is still in a state where seller rejection is currently allowed.",
"tags": [
"Return and refund"
],
"parameters": [
{
"name": "cancel_id",
"in": "path",
"required": true,
"description": "The cancellation request ID to reject. Use the `cancel_id` returned by Search Cancellations. Do not pass the order ID here.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "idempotency_key",
"in": "query",
"required": false,
"description": "The idempotency key is a unique value generated by the client that the server uses to recognize the same request. Reuse the same key for every retry of that request. If you omit this parameter, the server generates a key for the individual request. You may choose your own method of creating unique keys. We suggest using UUIDs, or another random string with enough entropy, to avoid collisions. Idempotency keys can be up to 255 characters long.",
"schema": {
"type": "string",
"maxLength": 255
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RejectCancellationRequest"
},
"example": {
"reject_reason": "seller_reject_apply_product_has_been_packed",
"comment": "I have packed the products before cancellation request",
"images": [
{
"image_id": "tos-maliva-i-o3syd03w52-us/57a1c8908fe74572861ea5e50887d8d1",
"mime_type": "image/png",
"height": 200,
"width": 200
}
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RejectCancellationResponse"
},
"example": {
"code": 0,
"data": {},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Return & Refund Basic"
],
"x-tts-error-codes": [
{
"code": "11050001",
"message": "invalid param"
},
{
"code": "25001001",
"message": "An invalid request parameter was passed. Please check that you have the correct parameter type(s) and format."
},
{
"code": "25001003",
"message": "Invalid order status."
},
{
"code": "25001014",
"message": "Unknown return reason. Please ensure you are passing a valid return reason."
},
{
"code": "25001016",
"message": "reverse reason not match action type"
},
{
"code": "25001020",
"message": "The provided return reason is currently offline. Please select a different return reason."
},
{
"code": "25001028",
"message": "reverse lock failed"
},
{
"code": "25001057",
"message": "reverse reason not match reason type"
},
{
"code": "25001058",
"message": "reverse downstream data load error"
},
{
"code": "25007006",
"message": "Order not found."
},
{
"code": "25011011",
"message": "reverse status cannot reject application"
},
{
"code": "25020003",
"message": "decision not match reverse status"
},
{
"code": "25020004",
"message": "decision not match reverse type"
},
{
"code": "25020005",
"message": "No permission to process this order"
},
{
"code": "25020010",
"message": "Aftersales has been approved and cannot be rejected."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/reject-cancellation-202309"
}
},
"/return_refund/202309/reject_reasons": {
"get": {
"operationId": "getRejectReasons",
"summary": "Get Reject Reasons",
"description": "Use this API to retrieve the seller reject-reason options currently applicable to the specified aftersales request. Use the returned name value as the reject reason key when calling the corresponding seller reject API.",
"tags": [
"Return and refund"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "locale",
"in": "query",
"required": false,
"description": "The BCP-47 locale codes for displaying the rejection reason, delimited by commas. Default: en-US\nRefer to [Locale codes](678e3a47bae28f030a8c7523) for the list of supported locale codes.",
"schema": {
"type": "string"
}
},
{
"name": "return_or_cancel_id",
"in": "query",
"required": true,
"description": "The unique identifier for an order return or cancellation.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetRejectReasonsResponse"
},
"example": {
"code": 0,
"data": {
"reasons": [
{
"name": "seller_reject_apply_you_have_reached_an_agreement_with_the_buyer",
"text": "You have reached an agreement with the buyer"
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Return & Refund Basic"
],
"x-tts-error-codes": [],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-reject-reasons-202309"
}
},
"/return_refund/202309/returns/{return_id}/approve": {
"post": {
"operationId": "approveReturn",
"summary": "Approve Return",
"description": "Use this API to approve a buyer's return request. The exact effect depends on the return type and return status. Before calling this API, make sure the return is still awaiting a seller action that matches the decision you are sending.",
"tags": [
"Return and refund"
],
"parameters": [
{
"name": "return_id",
"in": "path",
"required": true,
"description": "The unique identifier of the return request to be approved by the seller.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "idempotency_key",
"in": "query",
"required": false,
"description": "A unique value generated by the client that the server uses to recognize repeated requests. Reuse the same key when retrying the same request. If omitted, the server generates a key for that call. You may use a UUID or another random string with enough entropy to avoid collisions. Maximum length: 255 characters.",
"schema": {
"type": "string",
"maxLength": 255
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApproveReturnRequest"
},
"example": {
"decision": "APPROVE_REFUND",
"buyer_keep_item": true,
"partial_refund": {
"currency": "IDR",
"amount": "10"
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApproveReturnResponse"
},
"example": {
"code": 0,
"data": {},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Return & Refund Basic"
],
"x-tts-error-codes": [
{
"code": "11050001",
"message": "invalid param"
},
{
"code": "25001001",
"message": "An invalid request parameter was passed. Please check that you have the correct parameter type(s) and format."
},
{
"code": "25001003",
"message": "Invalid order status."
},
{
"code": "25001028",
"message": "reverse lock failed"
},
{
"code": "25001044",
"message": "ConfirmReceive fulfillment order failed"
},
{
"code": "25001058",
"message": "reverse downstream data load error"
},
{
"code": "25007006",
"message": "Order not found."
},
{
"code": "25007007",
"message": "ReverseOrderExistNegotiate"
},
{
"code": "25011010",
"message": "request has been transferred to platform operator"
},
{
"code": "25011012",
"message": "reverse status cannot approve application"
},
{
"code": "25011013",
"message": "reverse status cannot approve receive"
},
{
"code": "25011023",
"message": "forbid process authentic guarantee order"
},
{
"code": "25011026",
"message": "forbid process receive for FBT order"
},
{
"code": "25011032",
"message": "ReverseInvalidStatusPartialRefund"
},
{
"code": "25020004",
"message": "decision not match reverse type"
},
{
"code": "25020005",
"message": "No permission to process this order"
},
{
"code": "25020008",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
},
{
"code": "25020009",
"message": "reverse already cancelled"
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/approve-return-202309"
}
},
"/return_refund/202309/returns/{return_id}/records": {
"get": {
"operationId": "getReturnRecords",
"summary": "Get Return Records",
"description": "Use this API to retrieve the record entries for a specific return request. Each item in data.records represents an action or lifecycle event for the specified return_id.",
"tags": [
"Return and refund"
],
"parameters": [
{
"name": "return_id",
"in": "path",
"required": true,
"description": "A unique identifier for a TikTok Shop return request.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "locale",
"in": "query",
"required": false,
"description": "The BCP-47 locale codes for displaying the return reason, delimited by commas. Default: en-US\nRefer to [Locale codes](678e3a47bae28f030a8c7523) for the list of supported locale codes.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetReturnRecordsResponse"
},
"example": {
"code": 0,
"data": {
"records": [
{
"event": "ORDER_RETURN",
"role": "BUYER",
"description": "Customer submitted a return request",
"reason_text": "Wrong product was sent",
"note": "Reach an agreement with the buyer",
"images": [
{
"url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/004797ebfd8c4d3da2df1cc4bfdb0614~tplv-o3syd03w52-origin-jpeg.jpeg?from=4246405447",
"width": 200,
"height": 200
}
],
"videos": [
{
"url": "https://v16m-default.akamaized.net/1e26046c3df91cd008d2ababba9445e2/65005d33/video/tos/maliva/tos-maliva-v-d8ca36-us/oQVCbIQemDpQxI9lHsg9IXQAb7mwgBabababab",
"cover": "https://p16-oec-va.ibyteimg.com/musically-maliva-obj/998d0381960bda1ef272f4a7724cf5ed~tplv-o3syd03w52-origin-jpeg.jpeg?from=4246405489",
"width": 200,
"height": 200,
"duration_millis": 3000
}
],
"create_time": 1690532213
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Return & Refund Basic"
],
"x-tts-error-codes": [],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-return-records-202309"
}
},
"/return_refund/202405/returns/shipping_documents": {
"post": {
"operationId": "uploadReturnShippingInformation",
"summary": "Upload Return Shipping Information",
"description": "Use this API to upload return shipping documents, tracking numbers, and carriers for buyers.",
"tags": [
"Return and refund"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "return_ids",
"in": "query",
"required": true,
"description": "The identifier of a specific return.",
"explode": false,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
{
"name": "return_id_type",
"in": "query",
"required": false,
"description": "Specifies what kind of ID type was passed in the related return_ids field. (If the id type is not specified, the default value will be SKU_RETURN_ORDER.)\nPossible values:\n- RMA\n- SKU_RETURN_ORDER",
"schema": {
"type": "string",
"enum": [
"RMA",
"SKU_RETURN_ORDER"
]
}
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/UploadReturnShippingInformationRequest"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadReturnShippingInformationResponse"
},
"example": {
"code": 0,
"data": {},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Return & Refund Basic"
],
"x-tts-error-codes": [
{
"code": "25021022",
"message": "The return order has already uploaded the shipping document. Please do not upload it again."
},
{
"code": "25021023",
"message": "Return document formatting error. Please check the document format, only PDFs can be uploaded."
},
{
"code": "25023001",
"message": "Invalid return IDs."
},
{
"code": "25023002",
"message": "Return ID does not belong to this seller. Please do not upload it again."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/upload-return-shipping-information-202405"
}
},
"/return_refund/202601/decision_eligibility": {
"get": {
"operationId": "getDecisionEligibility",
"summary": "Get Decision Eligibility",
"description": "Use this API to evaluate which seller decisions are currently allowed for the specified aftersales request. The API returns one result per requested decision, including whether the decision is currently eligible and any rejection reasons that are applicable for an eligible reject decision.",
"tags": [
"Return and refund"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "return_or_cancel_id",
"in": "query",
"required": true,
"description": "The TikTok Shop return or cancellation request ID to evaluate. Pass the request identifier for the target cancellation, refund, return, or other supported aftersales flow. Do not pass an order ID or order line ID in this field.",
"schema": {
"type": "string"
}
},
{
"name": "check_decisions",
"in": "query",
"required": false,
"description": "The seller decisions to evaluate for the specified aftersales request. Possible Values:\n- `APPROVE_REQUEST_CANCEL`\n- `APPROVE_REFUND`\n- `APPROVE_RETURN`\n- `APPROVE_RECEIVED_PACKAGE`\n- `APPROVE_REPLACEMENT`\n- `ISSUE_REPLACEMENT_REFUND`\n- `DIRECT_REFUND`\n- `REJECT_REQUEST_CANCEL`\n- `REJECT_REFUND`\n- `REJECT_RETURN`\n- `REJECT_RECEIVED_PACKAGE`\n- `REJECT_REPLACEMENT`\n-`ISSUE_EXCHANGE_REFUND`\n**Note:** When omitted, the API evaluates all supported seller decisions for the request and returns one result per decision.",
"explode": false,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"APPROVE_REQUEST_CANCEL",
"APPROVE_REFUND",
"APPROVE_RETURN",
"APPROVE_RECEIVED_PACKAGE",
"APPROVE_REPLACEMENT",
"ISSUE_REPLACEMENT_REFUND",
"DIRECT_REFUND",
"REJECT_REQUEST_CANCEL",
"REJECT_REFUND",
"REJECT_RETURN",
"REJECT_RECEIVED_PACKAGE",
"REJECT_REPLACEMENT",
"ISSUE_EXCHANGE_REFUND"
]
}
}
},
{
"name": "locale",
"in": "query",
"required": false,
"description": "The BCP-47 locale codes for displaying the return reason, delimited by commas. Default: en-US\nRefer to [Locale codes](678e3a47bae28f030a8c7523) for the list of supported locale codes.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetDecisionEligibilityResponse"
},
"example": {
"code": 0,
"data": {
"decisions": [
{
"decision": "APPROVE_REFUND",
"eligible": true,
"ineligible_code": 25001001,
"ineligible_reason": "the return is already completed, you can't approve again.",
"available_reject_reasons": [
{
"name": "seller_reject_apply_product_has_been_packed",
"text": "Product shipped. Tracking updates will be available soon."
}
]
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Return & Refund Basic"
],
"x-tts-error-codes": [],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-decision-eligibility-202601"
}
},
"/return_refund/202602/cancellations": {
"post": {
"operationId": "cancelOrder",
"summary": "Cancel Order",
"description": "Use this API to cancel an order on behalf of a seller. In the US and UK markets, when an item is out of stock, partial cancellation on the single item level is supported by this API.",
"tags": [
"Return and refund"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CancelOrderRequest"
},
"example": {
"order_id": "577087614418520388",
"skus": [
{
"sku_id": "1729386416015578024",
"quantity": 1
}
],
"order_line_item_ids": [
"577087614418716996"
],
"cancel_reason": "ecom_order_delivered_refund_and_return_reason_wrong_product_seller",
"order_line_list": [
{
"order_line_item_id": "576469648086306986",
"sub_order_line_item_id": "576469648086306987"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CancelOrderResponse"
},
"example": {
"code": 0,
"data": {
"cancel_id": "4035319218955782461",
"cancel_status": "CANCELLATION_REQUEST_SUCCESS"
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Return & Refund Basic"
],
"x-tts-error-codes": [
{
"code": "25001001",
"message": "An invalid request parameter was passed. Please check that you have the correct parameter type(s) and format."
},
{
"code": "25001011",
"message": "A return request is already in process, or the order has already been cancelled."
},
{
"code": "25001014",
"message": "Unknown return reason. Please ensure you are passing a valid return reason."
},
{
"code": "25001015",
"message": "The provided return reason cannot be used by the seller. Please select a valid return reason and try again."
},
{
"code": "25001020",
"message": "The provided return reason is currently offline. Please select a different return reason."
},
{
"code": "25001021",
"message": "Reason not match order status"
},
{
"code": "25001028",
"message": "reverse lock failed"
},
{
"code": "25001045",
"message": "The order has already been shipped and we are unable to cancel shipment with the courier."
},
{
"code": "25001046",
"message": "Return request has failed due to an interception by TikTok risk control."
},
{
"code": "25001051",
"message": "Not allowed to return or cancel since order is completed or cancelled"
},
{
"code": "25005010",
"message": "Unable to cancel individual line items within this request."
},
{
"code": "25005011",
"message": "The requested line item(s) for return or refund exceeds the allowable limit."
},
{
"code": "25020005",
"message": "No permission to process this order"
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/cancel-order-202602"
}
},
"/return_refund/202602/cancellations/search": {
"post": {
"operationId": "searchCancellations",
"summary": "Search Cancellations",
"description": "Use this API to search and retrieve one or more order cancellations.",
"tags": [
"Return and refund"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "sort_field",
"in": "query",
"required": false,
"description": "The returned results will be sorted by the specified field. \n**Default:** `create_time`\nPossible values:\n- `create_time`\n- `update_time`\n\nSpecify the order for sorting the returned results by using the sort_order parameter.",
"schema": {
"type": "string",
"enum": [
"create_time",
"update_time"
]
}
},
{
"name": "sort_order",
"in": "query",
"required": false,
"description": "The sort order for the sort_field parameter. \n**Default:** `ASC`\nPossible values:\n- `ASC`: Ascending order\n- `DESC`: Descending order",
"schema": {
"type": "string",
"enum": [
"ASC",
"DESC"
],
"x-enum-descriptions": [
"Ascending order",
"Descending order"
]
}
},
{
"name": "page_size",
"in": "query",
"required": false,
"description": "The number of results to be returned per page. \n**Default:** 10. \nValid range: [1-50].",
"schema": {
"type": "string"
}
},
{
"name": "page_token",
"in": "query",
"required": false,
"description": "An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the next_page_token from a previous response. It is not needed for the first page.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchCancellationsRequest"
},
"example": {
"cancel_ids": [
"577087614418520388"
],
"order_ids": [
"577087614418520388"
],
"buyer_user_ids": [
"7494845267308415300"
],
"cancel_types": [
"CANCEL"
],
"cancel_status": [
"CANCELLATION_REQUEST_PENDING"
],
"create_time_ge": 1690340825,
"create_time_lt": 1690340825,
"update_time_ge": 1690340825,
"update_time_lt": 1690340825,
"locale": "en-US"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchCancellationsResponse"
},
"example": {
"code": 0,
"data": {
"cancellations": [
{
"order_id": "577087614418520388",
"cancel_type": "CANCEL",
"cancel_status": "CANCELLATION_REQUEST_PENDING",
"role": "BUYER",
"cancel_reason": "ecom_order_to_ship_canceled_reason_created_by_mistakes",
"cancel_reason_text": "Order created by mistake",
"create_time": 1690451136,
"update_time": 1690451136,
"seller_next_action_response": [
{
"action": "SELLER_RESPOND_BUYER_CANCEL",
"deadline": 1690554680
}
],
"refund_amount": {
"currency": "USD",
"refund_total": "1.23",
"refund_subtotal": "1",
"refund_shipping_fee": "0.2",
"refund_tax": "0.03",
"retail_delivery_fee": "0.1",
"buyer_service_fee": "1000"
},
"cancel_line_items": [
{
"cancel_line_item_id": "4035227913481196964",
"order_line_item_id": "576468844534141348",
"sku_id": "2729382476852921560",
"sku_name": "1#, Standard",
"product_image": {
"url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/004797ebfd8c4d3da2df1cc4bfdb0614~tplv-o3syd03w52-origin-jpeg.jpeg?from=4246405447",
"width": 200,
"height": 200
},
"product_name": "bundle No Heel Flat Heel Summer Winter Round Toe",
"seller_sku": "YYAPC23078TRT30",
"refund_amount": {
"currency": "USD",
"refund_total": "1.23",
"refund_subtotal": "1",
"refund_shipping_fee": "0.2",
"refund_tax": "0.03",
"retail_delivery_fee": "0.1",
"buyer_service_fee": "1000"
},
"cancel_sub_line_items": [
{
"cancel_sub_line_item_id": "4035227657962164812",
"cancel_line_item_id": "4035227657962164811",
"sub_order_line_item_id": "576473917261451852",
"order_line_item_id": "576473917261451851",
"sku_id": "2729382476852921560",
"sku_name": "1#, Standard",
"product_image": {
"url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/004797ebfd8c4d3da2df1cc4bfdb0614~tplv-o3syd03w52-origin-jpeg.jpeg?from=4246405447",
"width": 200,
"height": 200
},
"product_name": "bundle No Heel Flat Heel Summer Winter Round Toe",
"seller_sku": "YYAPC23078TRT30",
"refund_amount": {
"currency": "USD",
"refund_total": "1.23",
"refund_subtotal": "1",
"refund_shipping_fee": "0.2",
"refund_tax": "0.03",
"retail_delivery_fee": "0.1",
"buyer_service_fee": "1000"
}
}
]
}
],
"cancel_id": "4035318504086604100",
"should_replenish_stock": false
}
],
"total_count": 100,
"next_page_token": "aDU2dHIzMlFhME5CUzJKUDhDdVJhTDM1WmJkeFVTVW9LTkRaSnNaZCtuWjJXVU5CSDhlaA=="
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Return & Refund Basic"
],
"x-tts-error-codes": [
{
"code": "25001001",
"message": "An invalid request parameter was passed. Please check that you have the correct parameter type(s) and format."
},
{
"code": "25020005",
"message": "No permission to process this order"
},
{
"code": "25020008",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-cancellations-202602"
}
},
"/return_refund/202602/orders/{order_id}/aftersale_eligibility": {
"get": {
"operationId": "getAftersaleEligibility",
"summary": "Get Aftersale Eligibility",
"description": "Use this API to check whether a seller or buyer can initiate refund-only, return-and-refund, or cancellation requests for an order. The response groups eligibility by SKU, order line item, and aftersale request type.",
"tags": [
"Return and refund"
],
"parameters": [
{
"name": "order_id",
"in": "path",
"required": true,
"description": "The unique identifier for a TikTok Shop order.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "initiate_aftersale_user",
"in": "query",
"required": false,
"description": "The type of user you would like to check aftersale options for.\nDefault: SELLER\nPossible values:\n- SELLER\n- BUYER",
"schema": {
"type": "string",
"enum": [
"SELLER",
"BUYER"
]
}
},
{
"name": "request_types",
"in": "query",
"required": false,
"description": "**Optional.** Specifies which request types to query. If omitted, the API returns all request types currently available for the specified initiator. Possible values:\n-`CANCEL`\n-`REFUND`\n-`RETURN_AND_REFUND`",
"explode": false,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"CANCEL",
"REFUND",
"RETURN_AND_REFUND"
]
}
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetAftersaleEligibilityResponse"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Return & Refund Basic"
],
"x-tts-error-codes": [],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-aftersale-eligibility-202602"
}
},
"/return_refund/202602/refunds/calculate": {
"post": {
"operationId": "calculateRefund",
"summary": "Calculate Refund",
"description": "Use this API to estimate the refundable amount for a cancellation, refund, or return-and-refund request. The estimate depends on the selected request_type, reason_name, and targeted items. If skus, order_line_item_ids, and order_line_list are all omitted, all order lines in the order are selected as inputs to the refund calculation. For return-and-refund scenarios, the estimate can also depend on the selected return shipping method.",
"tags": [
"Return and refund"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CalculateRefundRequest"
},
"example": {
"order_id": "576469648086175911",
"request_type": "REFUND",
"shipment_type": "PLATFORM",
"handover_method": "DROP_OFF",
"reason_name": "ecom_order_delivered_refund_reason_missing_product_seller",
"order_line_item_ids": [
"576469648086306986"
],
"skus": [
{
"sku_id": "1729386416015578024",
"quantity": 1
}
],
"order_line_list": [
{
"order_line_item_id": "576469648086306986",
"sub_order_line_item_id": "576469648086306987"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CalculateRefundResponse"
},
"example": {
"code": 0,
"data": {
"order_refund_amount": {
"currency": "USD",
"refund_total": "1.23",
"refund_subtotal": "1",
"refund_shipping_fee": "0.2",
"refund_tax": "0.03",
"retail_delivery_fee": "0.1"
}
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Return & Refund Basic"
],
"x-tts-error-codes": [
{
"code": "25001001",
"message": "An invalid request parameter was passed. Please check that you have the correct parameter type(s) and format."
},
{
"code": "25007006",
"message": "Order not found."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/calculate-refund-202602"
}
},
"/return_refund/202602/returns": {
"post": {
"operationId": "createReturn",
"summary": "Create Return",
"description": "Use this API to create a seller-initiated aftersales request for an order on behalf of the buyer. Supported request types are `REFUND` and `RETURN_AND_REFUND`. Before submitting the request, confirm that the order is eligible for the selected aftersales type and return method. After the request is created, use the relevant search, status, or review API to continue the aftersales workflow.",
"tags": [
"Return and refund"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "idempotency_key",
"in": "query",
"required": false,
"description": "Idempotency Key",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateReturnRequest"
},
"example": {
"order_id": "576473917261320779",
"skus": [
{
"sku_id": "1729386416015578024",
"quantity": 1
}
],
"order_line_item_ids": [
"455764739172614518516"
],
"return_reason": "ecom_order_delivered_refund_reason_missing_product_seller",
"return_type": "REFUND",
"refund_total": "10.5",
"currency": "USD",
"shipment_type": "PLATFORM",
"handover_method": "DROP_OFF",
"order_line_list": [
{
"order_line_item_id": "576469648086306986",
"sub_order_line_item_id": "576469648086306987"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateReturnResponse"
},
"example": {
"code": 0,
"data": {
"return_id": "4035319218955782461",
"return_status": "RETURN_OR_REFUND_REQUEST_PENDING"
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Fulfillment Basic",
"Return & Refund Basic"
],
"x-tts-error-codes": [
{
"code": "25001001",
"message": "An invalid request parameter was passed. Please check that you have the correct parameter type(s) and format."
},
{
"code": "25001003",
"message": "Invalid order status."
},
{
"code": "25001010",
"message": "A return request has already been completed, or the order has already been cancelled."
},
{
"code": "25001011",
"message": "A return request is already in process, or the order has already been cancelled."
},
{
"code": "25001014",
"message": "Unknown return reason. Please ensure you are passing a valid return reason."
},
{
"code": "25001015",
"message": "The provided return reason cannot be used by the seller. Please select a valid return reason and try again."
},
{
"code": "25001020",
"message": "The provided return reason is currently offline. Please select a different return reason."
},
{
"code": "25001021",
"message": "Reason not match order status"
},
{
"code": "25001028",
"message": "reverse lock failed"
},
{
"code": "25001042",
"message": "Return package creation has failed due to internal error."
},
{
"code": "25001046",
"message": "Return request has failed due to an interception by TikTok risk control."
},
{
"code": "25001051",
"message": "Not allowed to return or cancel since order is completed or cancelled"
},
{
"code": "25005005",
"message": "Refund total amount is larger than the refundable amount."
},
{
"code": "25005010",
"message": "Unable to cancel individual line items within this request."
},
{
"code": "25005011",
"message": "The requested line item(s) for return or refund exceeds the allowable limit."
},
{
"code": "25020005",
"message": "No permission to process this order"
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/create-return-202602"
}
},
"/return_refund/202602/returns/search": {
"post": {
"operationId": "searchReturns",
"summary": "Search Returns",
"description": "Use this API to search returns by return ID, order ID, buyer, return type, return status, arbitration status, or create/update time window. The response is paginated. To retrieve the next page, pass the previous `next_page_token` as `page_token` and keep all other filters and sorting unchanged.",
"tags": [
"Return and refund"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "sort_field",
"in": "query",
"required": false,
"description": "The returned results will be sorted by the specified field. \n**Default**: `create_time`\nPossible values:\n- `create_time`\n- `update_time`\n\nSpecify the order for sorting the returned results by using the `sort_order` parameter.",
"schema": {
"type": "string",
"enum": [
"create_time",
"update_time"
]
}
},
{
"name": "sort_order",
"in": "query",
"required": false,
"description": "The sort order for the `sort_field` parameter. **Default**: `ASC`\nPossible values:\n- `ASC`: Ascending order\n- `DESC`: Descending order",
"schema": {
"type": "string",
"enum": [
"ASC",
"DESC"
],
"x-enum-descriptions": [
"Ascending order",
"Descending order"
]
}
},
{
"name": "page_size",
"in": "query",
"required": false,
"description": "The number of results to be returned per page. **Default**: 10. Valid range: [10-50].",
"schema": {
"type": "string"
}
},
{
"name": "page_token",
"in": "query",
"required": false,
"description": "An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the `next_page_token` from a previous response. It is not needed for the first page.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchReturnsRequest"
},
"example": {
"return_ids": [
"4035318504086604100"
],
"order_ids": [
"577686530908261117"
],
"buyer_user_ids": [
"7493996903972308733"
],
"return_types": [
"REFUND"
],
"return_status": [
"RETURN_OR_REFUND_REQUEST_PENDING"
],
"seller_proposed_return_type": [
"PARTIAL_REFUND"
],
"create_time_ge": 1690340825,
"arbitration_status": [
"IN_PROGRESS"
],
"update_time_ge": 1690340825,
"update_time_lt": 1690340825,
"locale": "en-US",
"create_time_lt": 1690340825
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchReturnsResponse"
},
"example": {
"code": 0,
"data": {
"return_orders": [
{
"order_id": "577686530908261117",
"return_id": "4035318504086604100",
"return_type": "REFUND",
"return_status": "RETURN_OR_REFUND_REQUEST_PENDING",
"arbitration_status": "IN_PROGRESS",
"role": "BUYER",
"return_reason": "ecom_order_to_ship_canceled_reason_created_by_mistakes",
"return_reason_text": "Order created by mistake",
"shipment_type": "PLATFORM",
"handover_method": "DROP_OFF",
"return_tracking_number": "213456789098765433456",
"return_provider_name": "J&T Express",
"return_provider_id": "TH27014E9R5Q4G",
"pre_return_id": "4035310341095393452",
"next_return_id": "4035310341095393463",
"can_buyer_keep_item": true,
"update_time": 1690453136,
"seller_next_action_response": [
{
"action": "SELLER_RESPOND_REFUND",
"deadline": 1690554680
}
],
"create_time": 1690451136,
"return_line_items": [
{
"return_line_item_id": "4035227657962164811",
"order_line_item_id": "576473917261451851",
"sku_id": "2729382476852921560",
"sku_name": "1#, Standard",
"product_name": "(SP) [PROMO BUNDLING] NICE Tissue Facial 180s x 5 pcs",
"seller_sku": "PUTIH 1 TALI",
"product_image": {
"url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/004797ebfd8c4d3da2df1cc4bfdb0614~tplv-o3syd03w52-origin-jpeg.jpeg?from=4246405447",
"width": 200,
"height": 200
},
"refund_amount": {
"currency": "USD",
"refund_total": "1.23",
"refund_subtotal": "1",
"refund_shipping_fee": "0.2",
"refund_tax": "0.03",
"retail_delivery_fee": "0.1",
"buyer_service_fee": "0.1"
},
"return_sub_line_items": [
{
"return_sub_line_item_id": "4035227657962164812",
"return_line_item_id": "4035227657962164811",
"sub_order_line_item_id": "576473917261451852",
"order_line_item_id": "576473917261451851",
"sku_id": "2729382476852921560",
"sku_name": "1#, Standard",
"product_image": {
"url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/004797ebfd8c4d3da2df1cc4bfdb0614~tplv-o3syd03w52-origin-jpeg.jpeg?from=4246405447",
"width": 200,
"height": 200
},
"product_name": "(SP) [PROMO BUNDLING] NICE Tissue Facial 180s x 5 pcs",
"seller_sku": "PUTIH 1 TALI",
"refund_amount": {
"currency": "USD",
"refund_total": "1.23",
"refund_subtotal": "1",
"refund_shipping_fee": "0.2",
"refund_tax": "0.03",
"retail_delivery_fee": "0.1",
"buyer_service_fee": "0.1"
}
}
]
}
],
"discount_amount": [
{
"currency": "USD",
"product_seller_discount": "0.1",
"shipping_fee_platform_discount": "0.1",
"shipping_fee_seller_discount": "0.1",
"product_platform_discount": "0.1"
}
],
"shipping_fee_amount": [
{
"currency": "USD",
"seller_paid_return_shipping_fee": "0.1",
"platform_paid_return_shipping_fee": "0.1",
"buyer_paid_return_shipping_fee": "0.1"
}
],
"refund_amount": {
"currency": "USD",
"refund_total": "1.23",
"refund_subtotal": "1",
"refund_shipping_fee": "0.2",
"refund_tax": "0.03",
"retail_delivery_fee": "0.1",
"buyer_service_fee": "0.1"
},
"return_shipping_document_type": "SHIPPING_LABEL",
"return_method": "PLATFORM_SHIPPED",
"is_combined_return": true,
"combined_return_id": "4035309948547073951",
"seller_proposed_return_type": "PARTIAL_REFUND",
"partial_refund": {
"currency": "IDR",
"amount": "10"
},
"buyer_rejected_partial_refund": true,
"return_warehouse_address": {
"full_address": "1199 Coleman Ave San Jose, CA 95110"
},
"is_quick_refund": false
}
],
"total_count": 100,
"next_page_token": "aDU2dHIzMlFhME5CUzJKUDhDdVJhTDM1WmJkeFVTVW9LTkRaSnNaZCtuWjJXVU5CSDhlaA=="
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Return & Refund Basic"
],
"x-tts-error-codes": [
{
"code": "25001001",
"message": "An invalid request parameter was passed. Please check that you have the correct parameter type(s) and format."
},
{
"code": "25020005",
"message": "No permission to process this order"
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-returns-202602"
}
},
"/return_refund/202603/aftersales/search": {
"post": {
"operationId": "searchAftersalesRequests",
"summary": "Search Aftersales Requests",
"description": "Searches aftersales requests for the authorized shop. You can filter by aftersales request, buyer, or main order IDs, aftersales request status, return type, and creation or update time. Use `whitelisted_data_fields` to include line items, SKU return requests, or return merchandise authorizations in each result.",
"tags": [
"Return and refund"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "locale",
"in": "query",
"required": false,
"description": "The BCP-47 locale codes for displaying purposes. Default: `en`\nRefer to [Locale codes](https://partner.tiktokshop.com/docv2/page/678e3a47bae28f030a8c7523) for the list of supported locale codes.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchAftersalesRequestsRequest"
},
"example": {
"whitelisted_data_fields": [
"LINE_ITEMS",
"SKU_RETURN_REQUESTS",
"RETURN_MERCHANDISE_AUTHORIZATIONS"
],
"filters": {
"aftersales_request_ids": [
"4035318504086604101"
],
"aftersales_request_statuses": [
"PENDING_REQUEST_REVIEW"
],
"return_types": [
"REFUND",
"RETURN_AND_REFUND"
],
"main_order_ids": [
"577686530908261117"
],
"buyer_ids": [
"7493996903972308733"
],
"time": {
"create_time": {
"min_unix_time_inclusive": 1774486592,
"max_unix_time_exclusive": 1774572992
},
"update_time": {
"min_unix_time_inclusive": 1774486592,
"max_unix_time_exclusive": 1774572992
}
}
},
"sort": {
"sort_field": "CREATE_TIME",
"sort_order": "ASC"
},
"pagination": {
"page_size": 100,
"page_token": "aDU2dHIzMlFhME5CUzJKUDhDdVJhTDM1WmJkeFVTVW9LTkRaSnNaZCtuWjJXVU5CSDhlaA=="
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchAftersalesRequestsResponse"
},
"example": {
"code": 0,
"data": {
"aftersales_requests": [
{
"id": "4035318504086604101",
"line_items": [
{
"return_line_item_id": "4035227657962164811",
"sub_return_line_item_id": "4035227657962164815",
"sku_id": "2729382476852921560",
"main_order_id": "577686530908261117",
"sku_return_request_id": "4035318504086604100"
}
],
"status": "PENDING_REQUEST_REVIEW",
"sku_return_requests": [
{
"order_id": "577686530908261117",
"return_id": "4035318504086604100",
"return_type": "REFUND",
"return_status": "RETURN_OR_REFUND_REQUEST_PENDING",
"arbitration_status": "IN_PROGRESS",
"role": "BUYER",
"return_reason": "ecom_order_to_ship_canceled_reason_created_by_mistakes",
"return_reason_text": "Order created by mistake",
"seller_next_action_response": [
{
"action": "SELLER_RESPOND_REFUND",
"deadline": 1690554680
}
],
"shipment_type": "PLATFORM",
"handover_method": "DROP_OFF",
"return_tracking_number": "213456789098765433456",
"return_provider_name": "J&T Express",
"return_provider_id": "TH27014E9R5Q4G",
"pre_return_id": "4035310341095393452",
"next_return_id": "4035310341095393463",
"refund_amount": {
"currency": "USD",
"refund_total": "1.23",
"refund_subtotal": "1",
"refund_shipping_fee": "0.2",
"refund_tax": "0.03",
"retail_delivery_fee": "0.1",
"buyer_service_fee": "0.1"
},
"return_line_items": [
{
"return_line_item_id": "4035227657962164811",
"order_line_item_id": "576473917261451851",
"sku_id": "2729382476852921560",
"sku_name": "1#, Standard",
"product_image": {
"url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/004797ebfd8c4d3da2df1cc4bfdb0614~tplv-o3syd03w52-origin-jpeg.jpeg?from=4246405447",
"width": 200,
"height": 200
},
"product_name": "(SP) [PROMO BUNDLING] NICE Tissue Facial 180s x 5 pcs",
"seller_sku": "PUTIH 1 TALI",
"refund_amount": {
"currency": "USD",
"refund_total": "1.23",
"refund_subtotal": "1",
"refund_shipping_fee": "0.2",
"refund_tax": "0.03",
"retail_delivery_fee": "0.1",
"buyer_service_fee": "0.1"
},
"return_sub_line_items": [
{
"return_sub_line_item_id": "4035227657962164812",
"return_line_item_id": "4035227657962164811",
"sub_order_line_item_id": "576473917261451852",
"order_line_item_id": "576473917261451851",
"sku_id": "2729382476852921560",
"sku_name": "1#, Standard",
"product_image": {
"url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/004797ebfd8c4d3da2df1cc4bfdb0614~tplv-o3syd03w52-origin-jpeg.jpeg?from=4246405447",
"width": 200,
"height": 200
},
"product_name": "(SP) [PROMO BUNDLING] NICE Tissue Facial 180s x 5 pcs",
"seller_sku": "PUTIH 1 TALI",
"refund_amount": {
"currency": "USD",
"refund_total": "1.23",
"refund_subtotal": "1",
"refund_shipping_fee": "0.2",
"refund_tax": "0.03",
"retail_delivery_fee": "0.1",
"buyer_service_fee": "0.1"
}
}
]
}
],
"create_time": 1690451136,
"update_time": 1690453136,
"discount": {
"product_platform_discount": "0.1",
"product_seller_discount": "0.1",
"shipping_fee_platform_discount": "0.1",
"shipping_fee_seller_discount": "0.1"
},
"shipping_fee": {
"seller_paid_return_shipping_fee_amount": "0.1",
"buyer_paid_return_shipping_fee_amount": "0.1",
"platform_paid_return_shipping_fee_amount": "0.1"
},
"buyer_keep_item": true,
"return_shipping_document_type": "SHIPPING_LABEL",
"return_method": "PLATFORM_SHIPPED",
"is_combined_return": false,
"combined_return_id": "4035309948547073951",
"seller_proposed_return_type": "PARTIAL_REFUND",
"partial_refund_amount": {
"partial_refund_total": "10",
"currency": "IDR"
},
"buyer_rejected_partial_refund": true,
"return_warehouse_address": {
"full_address": "1199 Coleman Ave San Jose, CA 95110"
},
"exchange_order_lines": [
{
"order_line_id": "0",
"sku_id": "0",
"sku_name": "0",
"product_name": "0",
"seller_sku_name": "0",
"product_image": {
"url": "0",
"width": 0,
"height": 0
},
"price_detail": {
"currency": "0",
"refund_total": "0",
"refund_subtotal": "0",
"refund_shipping_fee": "0",
"refund_tax": "0"
}
}
],
"reshipment_order_id": "0",
"is_quick_refund": false,
"return_sub_line_items": [
{
"return_sub_line_item_id": "4035227657962164812",
"return_line_item_id": "4035227657962164811",
"sub_order_line_item_id": "576473917261451852",
"order_line_item_id": "576473917261451851",
"sku_id": "2729382476852921560",
"sku_name": "1#, Standard",
"product_image": {
"url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/004797ebfd8c4d3da2df1cc4bfdb0614~tplv-o3syd03w52-origin-jpeg.jpeg?from=4246405447",
"width": 200,
"height": 200
},
"product_name": "(SP) [PROMO BUNDLING] NICE Tissue Facial 180s x 5 pcs",
"seller_sku": "PUTIH 1 TALI",
"refund_amount": {
"currency": "USD",
"refund_total": "1.23",
"refund_subtotal": "1",
"refund_shipping_fee": "0.2",
"refund_tax": "0.03",
"retail_delivery_fee": "0.1",
"buyer_service_fee": "0.1"
}
}
]
}
],
"return_merchandise_authorizations": [
{
"id": "2894521704838895640",
"package_id": "2894521704838895645",
"aftersales_request_id": "4035318504086604101",
"status": "AWAITING_BUYER_RETURN",
"line_items": [
{
"return_line_item_id": "4035227657962164811",
"sub_return_line_item_id": "4035227657962164815",
"sku_id": "2729382476852921560",
"main_order_id": "577686530908261117",
"sku_return_request_id": "4035318504086604100"
}
]
}
]
}
],
"total_count": 12345,
"next_page_token": "aDU2dHIzMlFhME5CUzJKUDhDdVJhTDM1WmJkeFVTVW9LTkRaSnNaZCtuWjJXVU5CSDhlaA=="
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Return & Refund Basic"
],
"x-tts-error-codes": [
{
"code": "25001001",
"message": "An invalid request parameter was passed. Please check that you have the correct parameter type(s) and format."
},
{
"code": "25020005",
"message": "No permission to process this order"
},
{
"code": "25020008",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-aftersales-requests-202603"
}
},
"/return_refund/202604/rma/search": {
"post": {
"operationId": "searchReturnMerchandiseAuthorizations",
"summary": "Search Return Merchandise Authorizations",
"description": "Searches return merchandise authorizations (RMAs) for the authorized shop. You can filter by identifiers, RMA status, and creation or update time. Use `whitelisted_data_fields` to include line items or SKU return requests for each RMA.",
"tags": [
"Return and refund"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "locale",
"in": "query",
"required": false,
"description": "The BCP-47 locale codes for displaying purposes. Default: `en`\nRefer to [Locale codes](https://partner.tiktokshop.com/docv2/page/678e3a47bae28f030a8c7523) for the list of supported locale codes.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchReturnMerchandiseAuthorizationsRequest"
},
"example": {
"whitelisted_data_fields": [
"LINE_ITEMS",
"SKU_RETURN_REQUESTS"
],
"filters": {
"rma_ids": [
"2894521704838895640"
],
"package_ids": [
"2894521704838895645"
],
"statuses": [
"PENDING_PACKAGE_REVIEW"
],
"aftersales_request_ids": [
"4035319218955782461"
],
"main_order_ids": [
"577686530908261117"
],
"time": {
"create_time": {
"min_unix_time_inclusive": 1774486592,
"max_unix_time_exclusive": 1774572992
},
"update_time": {
"min_unix_time_inclusive": 1774486592,
"max_unix_time_exclusive": 1774572992
}
}
},
"sort": {
"sort_field": "CREATE_TIME",
"sort_order": "ASC"
},
"pagination": {
"page_size": 100,
"page_token": "aDU2dHIzMlFhME5CUzJKUDhDdVJhTDM1WmJkeFVTVW9LTkRaSnNaZCtuWjJXVU5CSDhlaA=="
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchReturnMerchandiseAuthorizationsResponse"
},
"example": {
"code": 0,
"data": {
"return_merchandise_authorizations": [
{
"id": "2894521704838895640",
"package_id": "2894521704838895645",
"aftersales_request_id": "4035318504086604101",
"status": "AWAITING_BUYER_RETURN",
"line_items": [
{
"return_line_item_id": "4035227657962164811",
"sub_return_line_item_id": "4035227657962164815",
"sku_id": "2729382476852921560",
"main_order_id": "577686530908261117",
"sku_return_request_id": "4035318504086604100"
}
],
"sku_return_requests": [
{
"order_id": "577686530908261117",
"return_id": "4035318504086604100",
"return_type": "REFUND",
"return_status": "RETURN_OR_REFUND_REQUEST_PENDING",
"arbitration_status": "IN_PROGRESS",
"role": "BUYER",
"return_reason": "ecom_order_to_ship_canceled_reason_created_by_mistakes",
"return_reason_text": "Order created by mistake",
"seller_next_action_response": [
{
"action": "SELLER_RESPOND_REFUND",
"deadline": 1690554680
}
],
"shipment_type": "PLATFORM",
"handover_method": "DROP_OFF",
"return_tracking_number": "213456789098765433456",
"return_provider_name": "J&T Express",
"return_provider_id": "TH27014E9R5Q4G",
"pre_return_id": "4035310341095393452",
"next_return_id": "4035310341095393463",
"refund_amount": {
"currency": "USD",
"refund_total": "1.23",
"refund_subtotal": "1",
"refund_shipping_fee": "0.2",
"refund_tax": "0.03",
"retail_delivery_fee": "0.1",
"buyer_service_fee": "0.1"
},
"return_line_items": [
{
"return_line_item_id": "4035227657962164811",
"order_line_item_id": "576473917261451851",
"sku_id": "2729382476852921560",
"sku_name": "1#, Standard",
"product_image": {
"url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/004797ebfd8c4d3da2df1cc4bfdb0614~tplv-o3syd03w52-origin-jpeg.jpeg?from=4246405447",
"width": 200,
"height": 200
},
"product_name": "(SP) [PROMO BUNDLING] NICE Tissue Facial 180s x 5 pcs",
"seller_sku": "PUTIH 1 TALI",
"refund_amount": {
"currency": "USD",
"refund_total": "1.23",
"refund_subtotal": "1",
"refund_shipping_fee": "0.2",
"refund_tax": "0.03",
"retail_delivery_fee": "0.1",
"buyer_service_fee": "0.1"
},
"return_sub_line_items": [
{
"return_sub_line_item_id": "4035227657962164812",
"return_line_item_id": "4035227657962164811",
"sub_order_line_item_id": "576473917261451852",
"order_line_item_id": "576473917261451851",
"sku_id": "2729382476852921560",
"sku_name": "1#, Standard",
"product_image": {
"url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/004797ebfd8c4d3da2df1cc4bfdb0614~tplv-o3syd03w52-origin-jpeg.jpeg?from=4246405447",
"width": 200,
"height": 200
},
"product_name": "(SP) [PROMO BUNDLING] NICE Tissue Facial 180s x 5 pcs",
"seller_sku": "PUTIH 1 TALI",
"refund_amount": {
"currency": "USD",
"refund_total": "1.23",
"refund_subtotal": "1",
"refund_shipping_fee": "0.2",
"refund_tax": "0.03",
"retail_delivery_fee": "0.1",
"buyer_service_fee": "0.1"
}
}
]
}
],
"create_time": 1690451136,
"update_time": 1690453136,
"discount": {
"product_platform_discount": "0.1",
"product_seller_discount": "0.1",
"shipping_fee_platform_discount": "0.1",
"shipping_fee_seller_discount": "0.1"
},
"shipping_fee": {
"seller_paid_return_shipping_fee_amount": "0.1",
"buyer_paid_return_shipping_fee_amount": "0.1",
"platform_paid_return_shipping_fee_amount": "0.1"
},
"buyer_keep_item": true,
"return_shipping_document_type": "SHIPPING_LABEL",
"return_method": "PLATFORM_SHIPPED",
"is_combined_return": false,
"combined_return_id": "4035309948547073951",
"seller_proposed_return_type": "PARTIAL_REFUND",
"partial_refund_amount": {
"partial_refund_total": "10",
"currency": "IDR"
},
"buyer_rejected_partial_refund": false,
"return_warehouse_address": {
"full_address": "1199 Coleman Ave San Jose, CA 95110"
},
"exchange_order_lines": [
{
"order_line_id": "0",
"sku_id": "0",
"sku_name": "0",
"product_name": "0",
"seller_sku_name": "0",
"product_image": {
"url": "0",
"width": 0,
"height": 0
},
"price_detail": {
"currency": "0",
"refund_total": "0",
"refund_subtotal": "0",
"refund_shipping_fee": "0",
"refund_tax": "0"
}
}
],
"reshipment_order_id": "0",
"is_quick_refund": false,
"return_sub_line_items": [
{
"return_sub_line_item_id": "4035227657962164812",
"return_line_item_id": "4035227657962164811",
"sub_order_line_item_id": "576473917261451852",
"order_line_item_id": "576473917261451851",
"sku_id": "2729382476852921560",
"sku_name": "1#, Standard",
"product_image": {
"url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/004797ebfd8c4d3da2df1cc4bfdb0614~tplv-o3syd03w52-origin-jpeg.jpeg?from=4246405447",
"width": 200,
"height": 200
},
"product_name": "(SP) [PROMO BUNDLING] NICE Tissue Facial 180s x 5 pcs",
"seller_sku": "PUTIH 1 TALI",
"refund_amount": {
"currency": "USD",
"refund_total": "1.23",
"refund_subtotal": "1",
"refund_shipping_fee": "0.2",
"refund_tax": "0.03",
"retail_delivery_fee": "0.1",
"buyer_service_fee": "0.1"
}
}
]
}
]
}
],
"total_count": 12345,
"next_page_token": "aDU2dHIzMlFhME5CUzJKUDhDdVJhTDM1WmJkeFVTVW9LTkRaSnNaZCtuWjJXVU5CSDhlaA=="
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Return & Refund Basic"
],
"x-tts-error-codes": [
{
"code": "25001001",
"message": "An invalid request parameter was passed. Please check that you have the correct parameter type(s) and format."
},
{
"code": "25020005",
"message": "No permission to process this order"
},
{
"code": "25020008",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
},
{
"code": "36009003",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/search-return-merchandise-authorizations-202604"
}
},
"/return_refund/202606/returns/{return_id}/reject": {
"post": {
"operationId": "rejectReturn",
"summary": "Reject Return",
"description": "Use this API to reject a buyer's refund-only, return-and-refund, or replacement request, or to offer a partial refund after the package is received. The valid decision depends on the current request type and status. Before calling this API, make sure the request is still awaiting the seller action that matches the decision you send.",
"tags": [
"Return and refund"
],
"parameters": [
{
"name": "return_id",
"in": "path",
"required": true,
"description": "The unique identifier of the return request to be rejected by the seller.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "idempotency_key",
"in": "query",
"required": false,
"description": "A unique value generated by the client that the server uses to recognize repeated requests. Generate a collision-resistant value, such as a UUID, and reuse the same value when retrying the same request. If omitted, the server generates a key for the request; callers that need idempotent retries should provide and reuse their own key. Maximum length: 255 characters.",
"schema": {
"type": "string",
"maxLength": 255
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RejectReturnRequest"
},
"example": {
"decision": "REJECT_RECEIVED_PACKAGE",
"reject_reason": "seller_reject_apply_package_has_not_exceeded_estimated_delivery_time",
"comment": "I have reached an agreement with the buyer",
"images": [
{
"image_id": "tos-maliva-i-o3syd03w52-us/57a1c8908fe74572861ea5e50887d8d1",
"mime_type": "image/png",
"height": 200,
"width": 200
}
],
"partial_refund_amount": {
"partial_refund_total": "4.66",
"currency": "USD"
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RejectReturnResponse"
},
"example": {
"code": 0,
"data": {},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Return & Refund Basic"
],
"x-tts-error-codes": [
{
"code": "11050001",
"message": "invalid param"
},
{
"code": "25001001",
"message": "An invalid request parameter was passed. Please check that you have the correct parameter type(s) and format."
},
{
"code": "25001003",
"message": "Invalid order status."
},
{
"code": "25001014",
"message": "Unknown return reason. Please ensure you are passing a valid return reason."
},
{
"code": "25001016",
"message": "reverse reason not match action type"
},
{
"code": "25001020",
"message": "The provided return reason is currently offline. Please select a different return reason."
},
{
"code": "25001028",
"message": "reverse lock failed"
},
{
"code": "25001057",
"message": "reverse reason not match reason type"
},
{
"code": "25001058",
"message": "reverse downstream data load error"
},
{
"code": "25007002",
"message": "db access error"
},
{
"code": "25007006",
"message": "Order not found."
},
{
"code": "25011010",
"message": "request has been transferred to platform operator"
},
{
"code": "25011023",
"message": "forbid process authentic guarantee order"
},
{
"code": "25011025",
"message": "Quick refund forbid reject receive."
},
{
"code": "25011026",
"message": "forbid process receive for FBT order"
},
{
"code": "25011035",
"message": "could not reject parcel now"
},
{
"code": "25020004",
"message": "decision not match reverse type"
},
{
"code": "25020005",
"message": "No permission to process this order"
},
{
"code": "25020008",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
},
{
"code": "25020010",
"message": "Aftersales has been approved and cannot be rejected."
},
{
"code": "25020011",
"message": "return already received"
},
{
"code": "25020012",
"message": "status can't reject receive"
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/reject-return-202606"
}
},
"/return_refund/202606/review_decision": {
"get": {
"operationId": "getAvailableReviewDecisions",
"summary": "Get Available Review Decisions",
"description": "Description of [GET]/return_refund/:version/Get_Review_Decision",
"tags": [
"Return and refund"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
},
{
"name": "seller_id",
"in": "query",
"required": true,
"description": "The unique identifier of the seller/shop",
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "return_or_cancel_id",
"in": "query",
"required": true,
"description": "The identifier of the aftersales request to evaluate. Pass a reverse main order ID, aftersales request ID, or return merchandise authorization (RMA) ID; the API detects which type was provided. Do not pass an order ID or order line ID.",
"schema": {
"type": "string"
}
},
{
"name": "locale",
"in": "query",
"required": false,
"description": "The BCP-47 locale codes for displaying the return reason, delimited by commas. Default: en-US\nRefer to [Locale codes](678e3a47bae28f030a8c7523) for the list of supported locale codes.",
"schema": {
"type": "string"
}
},
{
"name": "check_decisions",
"in": "query",
"required": false,
"description": "The seller decisions to evaluate for the specified aftersales request. Possible values:\n- `APPROVE_REQUEST_CANCEL`\n- `APPROVE_REFUND`\n- `APPROVE_RETURN`\n- `APPROVE_RECEIVED_PACKAGE`\n- `APPROVE_REPLACEMENT`\n- `ISSUE_REPLACEMENT_REFUND`\n- `DIRECT_REFUND`\n- `REJECT_REQUEST_CANCEL`\n- `REJECT_REFUND`\n- `REJECT_RETURN`\n- `REJECT_RECEIVED_PACKAGE`\n- `REJECT_REPLACEMENT`\n- `ISSUE_EXCHANGE_REFUND`\n- `OFFER_PARTIAL_REFUND`\n- `OFFER_PARTIAL_REFUND_AFTER_RECEIVING_PKG`\n**Note:** When omitted, the API evaluates all supported seller decisions for the request and returns one result per decision.",
"explode": false,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"APPROVE_REQUEST_CANCEL",
"APPROVE_REFUND",
"APPROVE_RETURN",
"APPROVE_RECEIVED_PACKAGE",
"APPROVE_REPLACEMENT",
"ISSUE_REPLACEMENT_REFUND",
"DIRECT_REFUND",
"REJECT_REQUEST_CANCEL",
"REJECT_REFUND",
"REJECT_RETURN",
"REJECT_RECEIVED_PACKAGE",
"REJECT_REPLACEMENT",
"ISSUE_EXCHANGE_REFUND",
"OFFER_PARTIAL_REFUND",
"OFFER_PARTIAL_REFUND_AFTER_RECEIVING_PKG"
]
}
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetAvailableReviewDecisionsResponse"
},
"example": {
"code": 0,
"data": {
"line_items": [
{
"return_line_item_id": "4035319218955782461",
"sub_return_line_item_id": "4035227657962164815",
"decisions": [
{
"decision": "OFFER_PARTIAL_REFUND_AFTER_RECEIVING_PKG",
"eligible": false,
"ineligible_code": 25005020,
"ineligible_reason": "the return is already completed, you can't approve again.",
"available_reject_reasons": [
{
"name": "seller_reject_apply_product_has_been_packed",
"text": "The display text for the reject reason."
}
],
"partial_refund_amount_range": {
"min_amount": "2.34",
"max_amount": "3.33",
"currency": "USD"
}
}
]
}
],
"request_log_id": "20260713225708FB…",
"errors": [
{
"code": "98001004",
"message": "Invalid parameters. Please verify your input before retrying"
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Return & Refund Basic"
],
"x-tts-error-codes": [
{
"code": "25001003",
"message": "Invalid order status."
},
{
"code": "25005020",
"message": "reverse amount not support partial refund"
},
{
"code": "25005021",
"message": "partial refund only support single sku"
},
{
"code": "25011010",
"message": "request has been transferred to platform operator"
},
{
"code": "25011011",
"message": "reverse status cannot reject application"
},
{
"code": "25011012",
"message": "reverse status cannot approve application"
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-available-review-decisions-202606"
}
},
"/return_refund/202609/aftersales/review": {
"post": {
"operationId": "reviewAftersalesRequests",
"summary": "Review Aftersales Requests",
"description": "API used to review (approve, reject, or offer alternatives to) a buyer's return request.",
"tags": [
"Return and refund"
],
"parameters": [
{
"$ref": "#/components/parameters/ShopCipher"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReviewAftersalesRequestsRequest"
},
"example": {
"aftersales_request_decisions": [
{
"request_id": "4035319218955782461",
"request_id_type": "AFTERSALES",
"line_item_decisions": [
{
"line_items": [
{
"return_line_item_id": "4035227657962164811",
"sub_return_line_item_id": "4035227657962164815"
}
],
"action": "APPROVE_REQUEST",
"alternative_solution_details": {
"partial_refund_amount": "12.34",
"currency": "USD"
},
"reason": {
"reason_id": "seller_reject_apply_package_has_not_exceeded_estimated_delivery_time",
"text": "I have reached an agreement with the buyer",
"media": {
"uri": "tos-maliva-i-o3syd03w52-us/57a1c8908fe74572861ea5e50887d8d1",
"mime_type": "image/png"
}
}
}
],
"action_unix_time": 1774486592,
"idempotency_key": "40b456b1-78e7-412d-9fe6-82181496e1bd&app_key=38abcd"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReviewAftersalesRequestsResponse"
},
"example": {
"code": 0,
"data": {
"errors": [
{
"code": "98001004",
"message": "Invalid parameters. Please verify your input before retrying"
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-requires-shop-cipher": true,
"x-tts-scenario": 1,
"x-tts-scopes": [
"Return & Refund Basic"
],
"x-tts-error-codes": [
{
"code": "11050001",
"message": "invalid param"
},
{
"code": "25001001",
"message": "An invalid request parameter was passed. Please check that you have the correct parameter type(s) and format."
},
{
"code": "25001003",
"message": "Invalid order status."
},
{
"code": "25001028",
"message": "reverse lock failed"
},
{
"code": "25001044",
"message": "ConfirmReceive fulfillment order failed"
},
{
"code": "25001058",
"message": "reverse downstream data load error"
},
{
"code": "25007006",
"message": "Order not found."
},
{
"code": "25007007",
"message": "ReverseOrderExistNegotiate"
},
{
"code": "25011010",
"message": "request has been transferred to platform operator"
},
{
"code": "25011012",
"message": "reverse status cannot approve application"
},
{
"code": "25011013",
"message": "reverse status cannot approve receive"
},
{
"code": "25011023",
"message": "forbid process authentic guarantee order"
},
{
"code": "25011026",
"message": "forbid process receive for FBT order"
},
{
"code": "25011032",
"message": "ReverseInvalidStatusPartialRefund"
},
{
"code": "25020004",
"message": "decision not match reverse type"
},
{
"code": "25020005",
"message": "No permission to process this order"
},
{
"code": "25020008",
"message": "Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support."
},
{
"code": "25020009",
"message": "reverse already cancelled"
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/review-aftersales-requests-202609"
}
},
"/seller/202309/permissions": {
"get": {
"operationId": "getGlobalProductPermission",
"summary": "Get Global Product Permission",
"description": "Retrieves whether a cross-border seller is permitted to manage global products.\nYou can use this API before listing global products to check this permission.",
"tags": [
"Seller"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetGlobalProductPermissionResponse"
},
"example": {
"code": 0,
"data": {
"permissions": [
"MANAGE_GLOBAL_PRODUCT"
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-scenario": 2,
"x-tts-scopes": [
"Global Shop Information"
],
"x-tts-error-codes": [],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-global-product-permission-202309"
}
},
"/seller/202309/shops": {
"get": {
"operationId": "getActiveShops",
"summary": "Get Active Shops",
"description": "Retrieves all active shops associated with the authenticated seller account. The response includes each active shop's ID and region.\n\nTarget seller: All",
"tags": [
"Seller"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetActiveShopsResponse"
},
"example": {
"code": 0,
"data": {
"shops": [
{
"id": "36123502970007",
"region": "GB"
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-scenario": 2,
"x-tts-scopes": [
"Global Shop Information"
],
"x-tts-error-codes": [],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-active-shops-202309"
}
},
"/seller/202601/shop_groups": {
"get": {
"operationId": "getShopGroupAndRelatedShops",
"summary": "Get Shop Group and Related Shops",
"description": "Retrieves the product interoperability group and related shops for the authenticated shop. For example, a group can include a U.S. shop and a Mexico shop.",
"tags": [
"Seller"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetShopGroupAndRelatedShopsResponse"
},
"example": {
"code": 0,
"data": {
"shop_group_data": {
"shop_group": {
"source": "1",
"shop_group_name": "shop group name A"
},
"shops": [
{
"shop_id": "36123502970007",
"seller_id": "74901234567890",
"shop_name": "shop name A",
"shop_region": "US"
}
]
}
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-scenario": 2,
"x-tts-scopes": [
"Shop Authorized Information"
],
"x-tts-error-codes": [
{
"code": "98001004",
"message": "Parameter {param_name} is invalid. Reason: {reason}. Expected: {expected_value}"
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/get-shop-group-and-related-shops-202601"
}
},
"/supply_chain/202309/packages/sync": {
"post": {
"operationId": "confirmPackageShipment",
"summary": "Confirm Package Shipment",
"description": "Use this API to submit package shipment information. Only warehouse service providers certified by TikTok Shop can access this API. Packages are processed independently, so a request can partially succeed. Review both `success_packages` and `errors` when handling the response.",
"tags": [
"Supply chain"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConfirmPackageShipmentRequest"
},
"example": {
"warehouse_provider_id": "7342984797904049750",
"packages": [
{
"id": "28427944530283",
"wms_order_id": "324246554745",
"provider_warehouse_code": "7475973290484254255",
"shipping_origin_city": "CityA",
"time_zone": "UTC+8",
"ship_time_millis": 1694176625765,
"create_time_millis": 1694176625765,
"handover_time_millis": 1694176625765,
"shipping_provider_id": "2435653524354624",
"shipping_provider_name": "ProviderA",
"tracking_number": "WB53452356",
"dimension": {
"length": 34,
"width": 425,
"height": 42,
"unit": "METER"
},
"weight": {
"value": 342,
"unit": "KILOGRAM"
},
"skus": [
{
"id": "4235346547",
"quantity": 13
}
],
"provider_warehouse_name": "Central Warehouse",
"tcw_warehouse_type": "STANDARD"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConfirmPackageShipmentResponse"
},
"example": {
"code": 0,
"data": {
"success_packages": [
"5345241234",
"42365346"
],
"errors": [
{
"code": "39003015",
"message": "Provider is not supported by TikTok Shop",
"detail": {
"package_id": "4645645645"
}
}
]
},
"message": "Success",
"request_id": "202203070749000101890810281E8C70B7"
}
}
}
}
},
"x-tts-scenario": 3,
"x-tts-scopes": [
"Fulfillment Basic"
],
"x-tts-error-codes": [
{
"code": "39003015",
"message": "provider is not in package information send-back white list"
},
{
"code": "39003016",
"message": "package param invalid, please check detail fail reason"
},
{
"code": "39003017",
"message": "save warehouse package info err"
},
{
"code": "39003018",
"message": "the package list is empty in the request"
},
{
"code": "39003019",
"message": "warehouse provider id is invalid"
},
{
"code": "39003020",
"message": "the provider id in your request is not match your app_key"
}
],
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/confirm-package-shipment-202309"
}
}
},
"webhooks": {
"activity_change": {
"post": {
"operationId": "activityChangeWebhook",
"summary": "(63) Activity change",
"description": "The Activity change webhook is designed to notify partners about modifications related to activities and the products associated with them. This allows applications to stay synchronized with changes in activity details or product inclusion/exclusion lists.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ActivityChangeWebhook"
},
"example": {
"type": 63,
"timestamp": 1678886400,
"shop_id": "789123456789123456",
"tts_notification_id": "000000000000000001",
"data": {
"activity_id": "act_123456789012345678",
"update_time": 1678886400,
"change_type": "product_update",
"product_update_list": {
"product_ids": [
"11111111",
"22222222"
],
"exclude_product_ids": [
"33333333"
],
"benefit_product_ids": [
"44444444"
]
},
"product_remove_list": {
"product_ids": [
"55555555"
],
"sku_ids": [
"66666666"
],
"benefit_product_ids": [],
"exclude_product_ids": []
}
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 63,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/x6legjl9"
}
},
"activity_status_change": {
"post": {
"operationId": "activityStatusChangeWebhook",
"summary": "(39) Activity status change",
"description": "When a promotion activity of the specified type starts, expires, or is deactivated, you'll receive this webhook.\nThis webhook will only be triggered when all the following conditions are met:\n\n* Your App has been authorized the` Promotion Information` scope.\n* The activities are of the following types:\n * `FIXED_PRICE`\n * `DIRECT_DISCOUNT`\n * `SHIPPING_DISCOUNT`\n * `BUY_MORE_SAVE_MORE`\n * `FLASHSALE` (Only available in SEA markets: SG, TH, ID, MY, PH, VN)\n* One of the following status changes happens:\n * The activity starts: the status changes from `NOT_START` to `ONGOING`.\n * The activity expires: the status changes from `ONGOING` to `EXPIRED`.\n * The activity is deactivated: the status changes to `DEACTIVATED`.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ActivityStatusChangeWebhook"
},
"example": {
"type": 39,
"shop_id": "7494049642642441621",
"tts_notification_id": "7327112393057371910",
"timestamp": 1644412885,
"data": {
"activity_id": "7136104329798256386",
"update_time": 1644412885,
"activity_type": "FIXED_PRICE",
"product_level": "PRODUCT",
"status": "ONGOING"
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 39,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/39-activity-status-change"
}
},
"aftersales_request_status_update": {
"post": {
"operationId": "aftersalesRequestStatusUpdateWebhook",
"summary": "(64) Aftersales Request Status Update",
"description": "The **Aftersales Request Status Update** webhook is triggered in two scenarios:\n\n1. Buyer submits a return request in their TikTok user app.\n2. A seller makes a decision on whether to approve or reject the request.\n\n\n> **Note:** This is considered the **first-review** stage of the return journey. If the Afterales request is approved, it will enter the **second-review** stage, which is waiting for the seller to make a decision to approve or reject the returned items.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AftersalesRequestStatusUpdateWebhook"
},
"example": {
"type": 64,
"tts_notification_id": "1111111111",
"shop_id": "1234567890",
"timestamp": 1644412885,
"data": {
"aftersales_request_id": "576486316948490001",
"return_role": "BUYER",
"aftersales_request_status": "PENDING_REQUEST_REVIEW",
"aftersales_request_create_time": 1627587600,
"aftersales_request_update_time": 1644412885
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 64,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/h4cxaxub"
}
},
"appeal_completed": {
"post": {
"operationId": "appealCompletedWebhook",
"summary": "(66) Appeal Completed",
"description": "This webhook is triggered when a size chart verification appeal is approved or rejected.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppealCompletedWebhook"
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 66,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/ohw7toic"
}
},
"cancellation_status_change": {
"post": {
"operationId": "cancellationStatusChangeWebhook",
"summary": "(11) Cancellation status change",
"description": "The **cancellation status change** webhook is triggered when the `cancel_status` of an order changes:\n\n* An order cancellation is initiated: `CANCELLATION_REQUEST_PENDING`\n* An order cancellation is accepted by the `SELLER` or `SYSTEM`: `CANCELLATION_REQUEST_SUCCESS`\n* An order cancellation is closed by the `BUYER` or `SYSTEM`: `CANCELLATION_REQUEST_CANCELLED`\n* An order cancellation is successful and a refund is issued: `CANCELLATION_REQUEST_COMPLETE`",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CancellationStatusChangeWebhook"
},
"example": {
"type": 11,
"tts_notification_id": "7327112393057371910",
"shop_id": "7494049642642441621",
"timestamp": 1644412885,
"data": {
"order_id": "576486316948490001",
"cancellations_role": "BUYER",
"cancel_status": "CANCELLATION_REQUEST_PENDING",
"cancel_id": "4035318504086604100",
"create_time": 1627587600
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 11,
"x-tts-event-type": "CANCELLATION_STATUS_CHANGE",
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/11-cancellation-status-change"
}
},
"combined_listing_change": {
"post": {
"operationId": "combinedListingChangeWebhook",
"summary": "(42) Combined listing change",
"description": "This webhook is triggered when a combined listing is created, updated (the list of products in the combined listing changes), or deleted.\n**Prerequisite**: The \"Product Basic\" API scope is enabled in Partner Center. For more information, refer to [Access Scope](access-scope).",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CombinedListingChangeWebhook"
},
"example": {
"type": 42,
"tts_notification_id": "7327112393057371910",
"shop_id": "7494049642642441621",
"timestamp": 1644412885,
"data": {
"combined_listing_id": "123456789",
"products": [
{
"id": "987654321"
},
{
"id": "987654322"
}
],
"status": "LIVE",
"change_type": "UPDATE",
"added_product_ids": [
"987654321"
],
"removed_product_ids": [
"987654333"
]
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 42,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/42-combined-listing-change"
}
},
"creator_deauthorization": {
"post": {
"operationId": "creatorDeauthorizationWebhook",
"summary": "(20) Creator deauthorization",
"description": "When a creator completely removes the App's access to his/her data.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatorDeauthorizationWebhook"
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 20,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/20-creator-deauthorization"
}
},
"fbt_inventory_update": {
"post": {
"operationId": "fbtInventoryUpdateWebhook",
"summary": "(24) FBT inventory update",
"description": "This webhook is triggered when the FBT inventory updates.\n> Prerequisite: The **Fulfilled by TikTok(FBT) Info** API scope is enabled in Partner Center. For more information, refer to [Access Scope](access-scope).",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FBTInventoryUpdateWebhook"
},
"example": {
"type": 24,
"seller_open_id": "VIyStQAAAADCBQ40s4TzOSSOEIW-bM5O9cod3vK8OytW8m-bnBYlXw",
"tts_notification_id": "7327112393057371910",
"timestamp": 1644412885,
"data": {
"goods_id": "732357708734418520388",
"sku_id": "123513234",
"fbt_warehouse_inventory": [
{
"fbt_warehouse_id": "73823232239293999999",
"on_hand_detail": {
"total_quantity": 7,
"reserved_quantity": 5,
"available_quantity": 2
}
}
],
"update_time": 1644412845
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 24,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/24-fbt-inventory-update"
}
},
"fbt_merchant_onboarding": {
"post": {
"operationId": "fbtMerchantOnboardingWebhook",
"summary": "(22) FBT merchant onboarding",
"description": "This webhook is triggered when the TikTok Shop seller onboards FBT platform to enable FBT service.\n> Prerequisite: The **Fulfilled by TikTok(FBT) Info** API scope is enabled in Partner Center. For more information, refer to [Access Scope](access-scope).",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FBTMerchantOnboardingWebhook"
},
"example": {
"type": 22,
"seller_open_id": "VIyStQAAAADCBQ40s4TzOSSOEIW-bM5O9cod3vK8OytW8m-bnBYlXw",
"tts_notification_id": "7327112393057371910",
"timestamp": 1644412885,
"data": {
"onboarded_regions": [
{
"region_code": "GB"
}
],
"update_time": 1644412845
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 22,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/22-fbt-merchant-onboarding"
}
},
"get_fbt_mcf_order_status": {
"post": {
"operationId": "getFBTMCFOrderStatusWebhook",
"summary": "(58) Get FBT MCF Order Status",
"description": "This webhook is triggered when the FBT multi-channel-fulfillment order status has changed/updated.\n> Prerequisite: The **Fulfilled by TikTok(FBT) Info** API scope is enabled in Partner Center. For more information, refer to [Access Scope](access-scope).",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetFBTMCFOrderStatusWebhook"
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 58,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/gqh1f39k"
}
},
"global_listing_method_change": {
"post": {
"operationId": "globalListingMethodChangeWebhook",
"summary": "(52) Global listing method change",
"description": "This webhook is triggered when the global listing method for a shop changes.\n**Applicable only for global sellers.**\n**Prerequisite**: The \"Product Basic\" API scope is enabled in Partner Center. For more information, refer to [Access Scope](https://partner.tiktokshop.com/docv2/page/access-scope).",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GlobalListingMethodChangeWebhook"
},
"example": {
"type": 52,
"tts_notification_id": "7327112393057371910",
"timestamp": 1644412885,
"seller_open_id": "VIyStQAAAADCBQ40s4TzOSSOEIW-bM5O9cod3vK8OytW8m-bnBYlXw",
"data": {
"global_product_id": "1729715829872102020",
"local_product_id": [
"1731711955927208538"
],
"listing_method": "GLOBAL_PUBLISHING"
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 52,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/g2wnrb57"
}
},
"global_replication_status_change": {
"post": {
"operationId": "globalReplicationStatusChangeWebhook",
"summary": "(51) Global replication status change",
"description": "This webhook is triggered when a product replication operation in another market is completed, regardless of success or failure. If the replication fails, the failure reason(s) will be included in the response.\n**Applicable only for global sellers.**\n**Prerequisite**: The \"Product Basic\" API scope is enabled in Partner Center. For more information, refer to [Access Scope](https://partner.tiktokshop.com/docv2/page/access-scope).",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GlobalReplicationStatusChangeWebhook"
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 51,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/7nzxgima"
}
},
"goods_match": {
"post": {
"operationId": "goodsMatchWebhook",
"summary": "(23) Goods match",
"description": "This webhook is triggered when the seller matches / unmatches the TikTok Shop product to the FBT Goods.\n> Prerequisite: The **Fulfilled by TikTok(FBT) Info** API scope is enabled in Partner Center. For more information, refer to [Access Scope](access-scope).",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GoodsMatchWebhook"
},
"example": {
"type": 23,
"seller_open_id": "VIyStQAAAADCBQ40s4TzOSSOEIW-bM5O9cod3vK8OytW8m-bnBYlXw",
"tts_notification_id": "7327112393057371910",
"timestamp": 1644412885,
"data": {
"match_type": "MATCH",
"product_type": "LOCAL",
"goods_id": "732357708734418520388",
"product_id": "123513234",
"sku_id": "123563781",
"update_time": 1644412845
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 23,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/23-goods-match"
}
},
"image_translation_completed": {
"post": {
"operationId": "imageTranslationCompletedWebhook",
"summary": "(46) Image translation completed",
"description": "This webhook is triggered when an image translation is completed or failed.\n\n\nApplicable only for sellers that sell across EU.\n**Prerequisite**: The \"Product Basic\" API scope is enabled in Partner Center. For more information, refer to [Access Scope](access-scope).",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImageTranslationCompletedWebhook"
},
"example": {
"type": 46,
"shop_id": "7494049642642441621",
"tts_notification_id": "7327112393057371910",
"timestamp": 1644412885,
"data": {
"translation_task": {
"id": "764c6e87eedcea90399a0dafcd572b71",
"status": "COMPLETED",
"fail_reason": "",
"target_lang": "it-IT",
"original_image": {
"uri": "tos-useast2a-i-tulkllf4y5-euttp/748e39ecff38453ab8396a36a53dbb92",
"url": "https://p16-oec-sg.ibyteimg.com/tos-alisg-i-aphluv4xyz-sg/sample.jpeg"
},
"translated_image": {
"uri": "tos-maliva-i-o3syd03w52-us/53b55d6e8cdf1f315affa7e70b45707d",
"url": "https://p16-oec-sg.ibyteimg.com/tos-alisg-i-aphluv4xwc-sg/sample.jpeg"
}
}
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 46,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/46-image-translation-completed"
}
},
"inbound_fbt_order_status_change": {
"post": {
"operationId": "inboundFBTOrderStatusChangeWebhook",
"summary": "(21) Inbound FBT order status change",
"description": "This webhook is triggered when the status of an FBT inbound order changes.\n> Prerequisite: The **Fulfilled by TikTok(FBT) Info** API scope is enabled in Partner Center. For more information, refer to [Access Scope](access-scope).",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InboundFBTOrderStatusChangeWebhook"
},
"example": {
"type": 21,
"seller_open_id": "VIyStQAAAADCBQ40s4TzOSSOEIW-bM5O9cod3vK8OytW8m-bnBYlXw",
"tts_notification_id": "7327112393057371910",
"timestamp": 1644412885,
"data": {
"inbound_order_id": "IBR577087614418520388",
"order_status": "CANCELLED",
"update_time": 1644412845
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 21,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/21-inbound-fbt-order-status-change"
}
},
"inventory_changed_by_shop": {
"post": {
"operationId": "inventoryChangedByShopWebhook",
"summary": "(71) Inventory Changed By Shop",
"description": "This webhook is triggered when a SKU's inventory quantity changes in a shop. Each notification identifies the affected shop, product, and SKU, and includes an inventory snapshot after the change together with the individual change details.\n**Prerequisite**: The \"Product Basic\" API scope is enabled in Partner Center. For more information, refer to [Access Scope](https://partner.tiktokshop.com/docv2/page/access-scope).\nThe following events trigger this webhook when they cause an inventory quantity change:\n| Trigger source | Description |\n| --- | --- |\n| `order_created` | An order is successfully placed, and inventory is committed to the order. |\n| `order_canceled` | A buyer or seller cancels an order, and the committed inventory is released back to available stock. |\n| `order_shipped` | An order is shipped, and the committed inventory is deducted. |\n| `manual_adjustment` | A seller manually adjusts inventory in Seller Center. |\n| `api_sync` | A developer updates inventory through an inventory-related OpenAPI. |\n| `campaign_lock` | A seller joins a platform marketing campaign, and inventory is locked for the campaign. |\n| `campaign_unlock` | A marketing campaign ends or a seller withdraws, and the locked inventory is released. |\n| `creator_lock` | A seller allocates exclusive inventory to a creator collaboration. |\n| `creator_unlock` | A creator collaboration ends, and the locked inventory is released. |\n| `system_auto_replenish` | The system automatically replenishes inventory, such as after an order fails due to an exception. |",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InventoryChangedByShopWebhook"
},
"example": {
"type": 71,
"tts_notification_id": "7327112393057371910",
"shop_id": "7494049642642441621",
"timestamp": 1775122114,
"data": {
"event_id": "inventory_event_001",
"occurred_at": "2026-04-02T09:28:34Z",
"shop_id": 7494049642642441621,
"product_id": 1891234567890123456,
"sku_id": 1729507467923261408,
"quantity_snapshot_after_change": {
"total_quantity": 100,
"total_available_quantity": 80,
"total_committed_quantity": 20,
"in_shop_quantity": 65,
"campaign_locked_quantity": 10,
"creator_locked_quantity": 5
},
"change_detail": [
{
"idempotency_key": "inventory_change_001",
"trigger_source": "manual_adjustment",
"occurred_at": "2026-04-02T09:28:34Z",
"total_quantity_delta": 4,
"available_quantity_delta": 4,
"committed_quantity_delta": 0,
"in_shop_quantity_delta": 4,
"campaign_locked_quantity_delta": 0,
"creator_locked_quantity_delta": 0
}
]
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 71,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/qk9yta93"
}
},
"inventory_status_change": {
"post": {
"operationId": "inventoryStatusChangeWebhook",
"summary": "(27) Inventory status change",
"description": "This webhook will be triggered in either of the following situations:\n\n* The `current_inventory_status` has dropped to LOW_STOCK / OUT_OF_STOCK.\n* TikTok Shop predicts the `available_quantity` will drop to `0` in X days.\n\n> Note: The value of X can be system-configured or manually set by the seller.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InventoryStatusChangeWebhook"
},
"example": {
"type": 27,
"tts_notification_id": "7327112393057371910",
"shop_id": "7494049642642441621",
"timestamp": 1644412885,
"data": {
"product_id": "732357708734418520388",
"sku_id": "73235770873441823254",
"trigger_reason": {
"alert_type": "PREDICTION",
"lead_days": 21
},
"current_inventory_status": "LOW_STOCK",
"inventory_distribution": {
"total_quantity": 100,
"available_quantity": 50,
"creator_reserved_quantity": 20,
"campaign_reserved_quantity": 20,
"committed_quantity": 10
},
"update_time": 1627587600
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 27,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/27-inventory-status-change"
}
},
"invoice_status_change": {
"post": {
"operationId": "invoiceStatusChangeWebhook",
"summary": "(36) Invoice status change",
"description": "This webhook is triggered when the status of an invoice upload changes after using the [POST Upload Invoice](upload-invoice) endpoint.\n**Note**: The [POST Upload Invoice](upload-invoice) API is currently only applicable to the Brazil market.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InvoiceStatusChangeWebhook"
},
"example": {
"type": 36,
"tts_notification_id": "7327112393057371910",
"shop_id": "7494049642642441621",
"timestamp": 1644412885,
"data": {
"package_id": "123456",
"order_ids": [
"152523",
"532123"
],
"invoice_status": "INVALID",
"invalid_reason": "NOT_FOUND"
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 36,
"x-tts-event-type": "INVOICE_STATUS_CHANGE",
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/36-invoice-status-change"
}
},
"new_conversation": {
"post": {
"operationId": "newConversationWebhook",
"summary": "(13) New conversation",
"description": "This **new conversation** webhook is triggered when a customer service agent joins or leaves a conversation.\nWe recommend refreshing the conversation list when receiving this event.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NewConversationWebhook"
},
"example": {
"type": 13,
"tts_notification_id": "7327112393057371910",
"shop_id": "7494049642642441621",
"timestamp": 1644412885,
"data": {
"conversation_id": "576486316948490001",
"create_time": 1627587506
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 13,
"x-tts-event-type": "NEW_CONVERSATION",
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/13-new-conversation"
}
},
"new_message": {
"post": {
"operationId": "newMessageWebhook",
"summary": "(14) New message",
"description": "The **new message** webhook is triggered when a new message is sent in a customer service conversation.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NewMessageWebhook"
},
"example": {
"type": 14,
"tts_notification_id": "7327112393057371910",
"shop_id": "7494049642642441621",
"timestamp": 1644412885,
"data": {
"content": "{\"content\":\"444\"}",
"conversation_id": "710688832392260838",
"create_time": 1681790246,
"is_visible": true,
"message_id": "722323407926368819",
"index": "7494560109732334274",
"type": "TEXT",
"sender": {
"im_user_id": "707885565181165594",
"role": "BUYER"
}
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 14,
"x-tts-event-type": "NEW_MESSAGE",
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/14-new-message"
}
},
"new_message_listener": {
"post": {
"operationId": "newMessageListenerWebhook",
"summary": "(33) New message listener",
"description": "When a creator sends a message to the seller.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NewMessageListenerWebhook"
},
"example": {
"type": 33,
"shop_id": "7494049642642441621",
"tts_notification_id": "7327112393057371910",
"timestamp": 1644412885,
"data": {
"index": "1735032460678899",
"message_id": "7451907556216407553",
"conversation_id": "7451873679308620048",
"msg_type": "TEXT",
"content": "Hello",
"create_time": "1691411573",
"sender": {
"sender_im_user_id": "2368694990397660924"
}
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 33,
"x-tts-event-type": "NEW_MESSAGE_LISTENER",
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/33-new-message-listener"
}
},
"opportunity_matching_status_change": {
"post": {
"operationId": "opportunityMatchingStatusChangeWebhook",
"summary": "(25) Opportunity matching status change",
"description": "This webhook is triggered when the status of opportunity matching for a candidate product changes.\n**Prerequisite**: The \"Product Opportunities\" API scope is enabled in Partner Center. For more information, refer to [Access Scope](access-scope).\n📌 This webhook is currently available only to a limited set of developers.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OpportunityMatchingStatusChangeWebhook"
},
"example": {
"type": 25,
"tts_notification_id": "7327112393057371910",
"shop_id": "7494049642642441621",
"timestamp": 1730458800,
"data": {
"external_product_id": "576486316948490000",
"opportunity_matching_status": "PENDING",
"opportunity_ids": [
"213231",
"213233"
],
"opportunity_matching_end_time": 1735603200,
"update_time": 1730458800
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 25,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/25-opportunity-matching-status-change"
}
},
"order_status_change": {
"post": {
"operationId": "orderStatusChangeWebhook",
"summary": "(1) Order status change",
"description": "The **order status change** webhook is triggered when the `order_status` of an order changes.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrderStatusChangeWebhook"
},
"example": {
"type": 1,
"tts_notification_id": "7327112393057371910",
"shop_id": "7494049642642441621",
"timestamp": 1644412885,
"data": {
"order_id": "576486316948490001",
"order_status": "UNPAID",
"is_on_hold_order": false,
"update_time": 1644412885
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 1,
"x-tts-event-type": "ORDER_STATUS_CHANGE",
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/1-order-status-change"
}
},
"package_update": {
"post": {
"operationId": "packageUpdateWebhook",
"summary": "(4) Package update",
"description": "The **package update** webhook is triggered when package updates such as combine, split, cancel the combine package operation, etc. occur.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PackageUpdateWebhook"
},
"example": {
"type": 4,
"tts_notification_id": "7327112393057371910",
"shop_id": "7494049642642441621",
"timestamp": 1644412885,
"data": {
"sc_type": "COMBINE",
"role_type": "ROLE_USER",
"package_list": [
{
"package_id": "123456",
"order_id_list": [
"152523",
"532123"
]
}
],
"update_time": 1644412885
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 4,
"x-tts-event-type": "PACKAGE_UPDATE",
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/4-package-update"
}
},
"product_audit_status_change": {
"post": {
"operationId": "productAuditStatusChangeWebhook",
"summary": "(37) Product audit status change",
"description": "When the product audit status changes, you'll receive this webhook.\nWith this webhook, you can easily get the audit status information of a product instead of calling [Get Product](get-product) API.\nTo receive this webhook, you must ensure the `Product Basic` API scope is enabled in Partner Center.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProductAuditStatusChangeWebhook"
},
"example": {
"type": 37,
"shop_id": "7494049642642441621",
"tts_notification_id": "7327112393057371910",
"timestamp": 1644412885,
"data": {
"product_id": 789078671231,
"audit": {
"status": "PRE_APPROVED",
"pre_approved_reason": "KYC_PENDING"
},
"integrated_platform_statuses": {
"platform": "TOKOPEDIA",
"status": "AUDITING"
},
"update_time": 1644412885
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 37,
"x-tts-event-type": "PRODUCT_AUDIT_STATUS_CHANGE",
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/37-product-audit-status-change"
}
},
"product_category_change": {
"post": {
"operationId": "productCategoryChangeWebhook",
"summary": "(18) Product category change",
"description": "When the category of a product is changed, all apps authorized by the shop (using `shop_id`) receive this webhook. When you receive the webhook, you can get more detailed product information by using the [Get Product](get-product) API.\nThis webhook is triggered regardless of how a product category is changed. Categories can be changed by the seller, developer, or TikTok Shop.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProductCategoryChangeWebhook"
},
"example": {
"type": 18,
"shop_id": "7494049642642441621",
"tts_notification_id": "7327112393057371910",
"timestamp": 1644412885,
"data": {
"product_id": "789078671231",
"previous_category_id": "600001",
"current_category_id": "600002",
"update_time": 1644412845
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 18,
"x-tts-event-type": "PRODUCT_CATEGORY_CHANGE",
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/18-product-category-change"
}
},
"product_creation": {
"post": {
"operationId": "productCreationWebhook",
"summary": "(16) Product creation",
"description": "Triggers a webhook message when a product is created",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProductCreationWebhook"
},
"example": {
"type": 16,
"tts_notification_id": "7327112393057371910",
"shop_id": "7494049642642441621",
"timestamp": 1644412885,
"data": {
"product_id": 576486316948490000,
"product_types": [
"GPR_PRODUCT"
],
"update_time": 1644412885
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 16,
"x-tts-event-type": "PRODUCT_CREATION",
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/16-product-creation"
}
},
"product_information_change": {
"post": {
"operationId": "productInformationChangeWebhook",
"summary": "(15) Product information change",
"description": "This webhook is triggered when changes to a **live** product's properties take effect online.\n**Prerequisite**: The product is **live** and the \"Product Basic\" API scope is enabled in Partner Center. For more information, refer to [Access Scope](access-scope).",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProductInformationChangeWebhook"
},
"example": {
"type": 15,
"tts_notification_id": "7327112393057371910",
"shop_id": "7494049642642441621",
"timestamp": 1644412885,
"data": {
"product_id": "123456789",
"change_source": "SELLER_CENTER",
"changed_fields": [
"title",
"description",
"main_images",
"product_attributes",
"size_chart_image",
"size_chart_template",
"others"
],
"update_time": 1627587600
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 15,
"x-tts-event-type": "PRODUCT_INFORMATION_CHANGE",
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/15-product-information-change"
}
},
"product_package_recommended": {
"post": {
"operationId": "productPackageRecommendedWebhook",
"summary": "(62) Product Package Recommended",
"description": "This webhook is triggered when a product package recommendation is generated.\n**Note:** Applicable only for Brazil (**BR**) and Mexico (**MX**) markets.\n**Prerequisite**: The \"Product Basic\" API scope is enabled in Partner Center. For more information, please refer to [Access Scope](https://partner.tiktokshop.com/docv2/page/access-scope).",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProductPackageRecommendedWebhook"
},
"example": {
"type": 62,
"tts_notification_id": "7611238471432161025",
"shop_id": "1111111",
"timestamp": 1772129552,
"data": {
"abnormality_types": [
"Weight",
"Dimension"
],
"dimension_recommendation": {
"height": {
"max_value": "3",
"min_value": "3"
},
"length": {
"max_value": "1234",
"min_value": "123"
},
"unit": "CENTIMETER",
"width": {
"max_value": "666",
"min_value": "555"
}
},
"product_id": "1733529220361062152",
"weight_recommendation": {
"unit": "GRAM",
"weight": {
"max_value": "12000",
"min_value": "12000"
}
}
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 62,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/ve4gakno"
}
},
"product_status_change": {
"post": {
"operationId": "productStatusChangeWebhook",
"summary": "(5) Product status change",
"description": "The **product status change** webhook triggers when a product audit status changes or is completed:\n\n* Product passes the first audit: `PRODUCT_FIRST_PASS_REVIEW`\n* Product status changes by platform: `PRODUCT_STATUS_CHANGED`\n* Product audit fails: `PRODUCT_AUDIT_FAILURE`",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProductStatusChangeWebhook"
},
"example": {
"type": 5,
"tts_notification_id": "7327112393057371910",
"shop_id": "7494049642642441621",
"timestamp": 1644412885,
"data": {
"product_id": 576486316948490000,
"status": "PRODUCT_FIRST_PASS_REVIEW",
"suspended_reason": "",
"update_time": 1644412885
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 5,
"x-tts-event-type": "PRODUCT_STATUS_CHANGE",
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/5-product-status-change"
}
},
"recipient_address_update": {
"post": {
"operationId": "recipientAddressUpdateWebhook",
"summary": "(3) Recipient address update",
"description": "The **recipient address update** webhook triggers when an order recipient's address is updated.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecipientAddressUpdateWebhook"
},
"example": {
"type": 3,
"shop_id": "7494049642642441621",
"timestamp": 1644412885,
"data": {
"order_id": "576486316948490001",
"update_time": 1644412885
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 3,
"x-tts-event-type": "RECIPIENT_ADDRESS_UPDATE",
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/3-recipient-address-update"
}
},
"refund_success": {
"post": {
"operationId": "refundSuccessWebhook",
"summary": "(67) Refund Success",
"description": "Once a refund of an RMA is successfully completed.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RefundSuccessWebhook"
},
"example": {
"type": 67,
"tts_notification_id": "7628321701399676688",
"shop_id": "123456",
"timestamp": 1776107052,
"data": {
"aftersales_request_id": "111111111",
"line_items": [
{
"main_order_id": "789456123",
"return_line_item_id": "999999",
"sku_id": "147852",
"sku_return_request_id": "321654987",
"sub_return_line_item_id": "888888"
},
{
"main_order_id": "789456123",
"return_line_item_id": "999999",
"sku_id": "147853",
"sku_return_request_id": "321654987",
"sub_return_line_item_id": "777777"
},
{
"main_order_id": "789456123",
"return_line_item_id": "666666",
"sku_id": "147853",
"sku_return_request_id": "321654987"
}
],
"refund_currency": "USD",
"refund_status": "REFUND_SUCCESS",
"refund_timestamp": 1776102211,
"refund_total": "1.25",
"rma_id": "222222222"
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 67,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/8y10pibm"
}
},
"return_status_change": {
"post": {
"operationId": "returnStatusChangeWebhook",
"summary": "(12) Return status change",
"description": "The **return status change** webhook is triggered when the `return_status` of an order changes:\n\n* The `BUYER` initiates a return or refund request and is pending `SELLER` review: `RETURN_OR_REFUND_REQUEST_PENDING`\n* The `SELLER` declines the `BUYER`'s return or refund request: `REFUND_OR_RETURN_REQUEST_REJECT`\n* The return request is approved and the `SELLER` is waiting for the `BUYER` to return the approved items: `AWAITING_BUYER_SHIP`. If the `BUYER` doesn't ship the items to the `SELLER` before the deadline, the request will be closed automatically.\n* To return the items to the `SELLER`, the `BUYER` drops off the package successfully or the `BUYER` ships the package and uploads the tracking number: `BUYER_SHIPPED_ITEM`\n* The `SELLER` declines the refund request for the return: `REJECT_RECEIVE_PACKAGE`\n* The `SELLER` accepts the refund request or issues a refund for the return: `RETURN_OR_REFUND_REQUEST_SUCCESS`\n* The `BUYER` or `SYSTEM` closes the return or refund request: `RETURN_OR_REFUND__REQUEST_CANCELLED`\n* The return or refund is successful: `RETURN_OR_REFUND_REQUEST_COMPLETE`\n\nAdditionally, a `BUYER` may request an identical replacement item instead of a refund:\n\n* The `BUYER` initiates a replacement request and is pending `SELLER` review: `REPLACEMENT_REQUEST_PENDING`\n* The `SELLER` declines the `BUYER`'s replacement request: `REPLACEMENT_REQUEST_REJECT`\n* The `SELLER` decides to issue a refund to the `BUYER` without replacement: `REPLACEMENT_REQUEST_REFUND_SUCCESS`\n* The `BUYER` cancels the replacement request: `REPLACEMENT_REQUEST_CANCEL`\n* The `SELLER` approves the replacement request: `REPLACEMENT_REQUEST_COMPLETE`",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReturnStatusChangeWebhook"
},
"example": {
"type": 12,
"tts_notification_id": "7327112393057371910",
"shop_id": "7494049642642441621",
"timestamp": 1644412885,
"data": {
"order_id": "576486316948490001",
"return_role": "BUYER",
"return_type": "REFUND",
"return_status": "RETURN_OR_REFUND_REQUEST_PENDING",
"return_id": "576486316948490001",
"create_time": 1627587600,
"update_time": 1644412885
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 12,
"x-tts-event-type": "RETURN_STATUS_CHANGE",
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/12-return-status-change"
}
},
"rma_status_update": {
"post": {
"operationId": "rmaStatusUpdateWebhook",
"summary": "(65) RMA Status Update",
"description": "The **RMA Status Update** webhook is triggered in the following scenarios:\n\n1. RMA is created\n2. The RMA package is delivered and is pending the seller to review items to make a refund **decision.**\n3. The RMA items review and refund decision is completed.\n\n\n> **Note:** The RMA is automatically created once the Aftersales Request has been approved. The RMA decision is considered the second-review stage of the Aftersales journey.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RMAStatusUpdateWebhook"
},
"example": {
"type": 65,
"tts_notification_id": "1111111113",
"shop_id": "1234567890",
"timestamp": 1644412889,
"data": {
"rma_id": "576486316948490002",
"aftersales_request_id": "576486316948490001",
"return_role": "BUYER",
"rma_status": "INIT",
"rma_create_time": 1627587601,
"rma_update_time": 1644412889
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 65,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/2f0jrrxc"
}
},
"sample_application_status_change": {
"post": {
"operationId": "sampleApplicationStatusChangeWebhook",
"summary": "(56) Sample Application Status Change",
"description": "This webhook will trigger when the creator's sample application status changes.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SampleApplicationStatusChangeWebhook"
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 56,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/urzvzank"
}
},
"seller_deauthorization": {
"post": {
"operationId": "sellerDeauthorizationWebhook",
"summary": "(6) Seller deauthorization",
"description": "The **seller deauthorization** webhook is triggered after a seller is deauthorized. This is important to prevent developers from assuming there is an issue with the platform authorization function.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SellerDeauthorizationWebhook"
},
"example": {
"type": 6,
"tts_notification_id": "7327112393057371910",
"shop_id": "7494049642642441621",
"timestamp": 1644412885,
"data": {
"message": "Shop_id {xxx} is deauthorized from your APP by merchant."
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 6,
"x-tts-event-type": "SELLER_DEAUTHORIZATION",
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/6-seller-deauthorization"
}
},
"shoppable_content_posting": {
"post": {
"operationId": "shoppableContentPostingWebhook",
"summary": "(17) Shoppable content posting",
"description": "The shoppable content posting webhook is triggered when the creator adds, updates, or removes a product link in a video or livestream.\n> This webhook will only be triggered after the creator has authorized the `Read Creator Affiliate Collaborations` scope.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ShoppableContentPostingWebhook"
},
"example": {
"type": 17,
"creator_open_id": "VIyStQAAAADCBQ40s4TzOSSOEIW-bM5O9cod3vK8OytW8m-bnBYlXw",
"tts_notification_id": "7327112393057371910",
"timestamp": 1644412885,
"data": {
"product_id": "789078671231",
"event": {
"type": "ADD",
"scene": "VIDEO",
"content_id": "789078671231"
}
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 17,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/17-shoppable-content-posting"
}
},
"shoppable_video_precheck_tasks_result": {
"post": {
"operationId": "shoppableVideoPrecheckTasksResultWebhook",
"summary": "(59) Shoppable Video Precheck Tasks Result",
"description": "The Video Precheck Result webhook is triggered when the Precheck Video Content API is called, and provides the results of the video’s quality assessment and violation checks.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ShoppableVideoPrecheckTasksResultWebhook"
},
"example": {
"type": 59,
"creator_open_id": "VIyStQAAAADCBQ40s4TzOSSOEIW-bM5O9cod3vK8OytW8m-bnBYlXw",
"tts_notification_id": "7327112393057371910",
"timestamp": 1644412885,
"data": {
"task_id": "task_202402011200001234",
"violation_check_result": {
"status": "FAIL",
"issues": [
{
"risk": "HIGH",
"suggestions": "Remove prohibited visual elements and resubmit the video."
}
]
},
"good_quality_check_result": {
"status": "SUCCESS",
"issues": [
{
"code": "LOW_RESOLUTION",
"suggestions": "Consider uploading a higher-resolution video for better viewing experience."
}
]
}
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 59,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/arpnre1g"
}
},
"size_chart_change": {
"post": {
"operationId": "sizeChartChangeWebhook",
"summary": "(19) Size chart change",
"description": "This webhook is triggered when a product size chart is created, edited, or deleted.\n**Prerequisite**: The \"Product Basic\" API scope is enabled in Partner Center. For more information, refer to [Access Scope](access-scope).",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SizeChartChangeWebhook"
},
"example": {
"type": 19,
"seller_open_id": "VIyStQAAAADCBQ40s4TzOSSOEIW-bM5O9cod3vK8OytW8m-bnBYlXw",
"tts_notification_id": "7327112393057371910",
"timestamp": 1644412885,
"data": {
"size_chart_template_id": "789078671231",
"size_chart_template_name": "600001",
"event_type": "EDIT",
"update_time": 1644412845
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 19,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/19-size-chart-change"
}
},
"sku_status_change": {
"post": {
"operationId": "skuStatusChangeWebhook",
"summary": "(50) SKU status change",
"description": "This webhook is triggered when the SKU status of an existing product changes.\nTypical scenarios include:\n\n* A new SKU is added under an existing product.\n* An existing SKU is deleted from an existing product.\n* An existing SKU is activated.\n* An existing SKU is deactivated.\n\n**Prerequisite:** The merchant has subscribed to the corresponding webhook topic and the related product change event is successfully consumed by the webhook delivery pipeline.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SKUStatusChangeWebhook"
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 50,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/u94ho74u"
}
},
"strikethrough_price_expired": {
"post": {
"operationId": "strikethroughPriceExpiredWebhook",
"summary": "(38) Strikethrough price expired",
"description": "This webhook will be triggered when the strikethrough pricing verification information expires, 90 days after submission.\nPrerequisite: The \"Strikethrough Price\" API scope is enabled in Partner Center. For more information, refer to [Access Scope](access-scope).",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StrikethroughPriceExpiredWebhook"
},
"example": {
"type": 38,
"tts_notification_id": "7327112393057371910",
"shop_id": "7494049642642441621",
"timestamp": 1644412885,
"data": {
"product_id": "732357708734418520388",
"sku_id": "73235770873441823254"
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 38,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/38-strikethrough-price-expired"
}
},
"tokopedia_mirror_status_change": {
"post": {
"operationId": "tokopediaMirrorStatusChangeWebhook",
"summary": "(35) Tokopedia mirror status change",
"description": "This webhook is triggered when the TikTok Shop to Tokopedia mirroring process is completed or rolled back. Applicable only for the **Indonesia** market.\n\n**Prerequisite**: The shop is [active](get-active-shops), and the \"**Shop Authorized Information**\" API scope is enabled in Partner Center. For more information, refer to [Access Scope](access-scope).",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TokopediaMirrorStatusChangeWebhook"
},
"example": {
"type": 35,
"tts_notification_id": "7327112393057371910",
"seller_open_id": "VIyStQAAAADCBQ40s4TzOSSOEIW-bM5O9cod3vK8OytW8m-bnBYlXw",
"timestamp": 1644412885,
"data": {
"tts_shop_id": "7494049642642441621",
"mirror_status": "MIRRORED",
"update_time": 1627587600
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 35,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/35-tokopedia-mirror-status-change"
}
},
"upcoming_authorization_expiration": {
"post": {
"operationId": "upcomingAuthorizationExpirationWebhook",
"summary": "(7) Upcoming authorization expiration",
"description": "The **upcoming authorization expiration** webhook is triggered 30 days before authorization automatically expires. This webhook continues to notify the seller once a day at 0:00 until re-authorization is completed.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpcomingAuthorizationExpirationWebhook"
},
"example": {
"type": 7,
"tts_notification_id": "7327112393057371910",
"shop_id": "7494049642642441621",
"timestamp": 1644412885,
"data": {
"message": "Authorization of shop_id {xxx} is expiring in {x} days. Please direct the merchant to re-authorize.",
"expiration_time": "1627587506"
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 7,
"x-tts-event-type": "UPCOMING_AUTHORIZATION_EXPIRATION",
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/7-upcoming-authorization-expiration"
}
},
"video_precheck_result": {
"post": {
"operationId": "videoPrecheckResultWebhook",
"summary": "(55) Video Precheck Result",
"description": "The Video Precheck Result webhook is triggered when the Precheck Video Content API is called, and the results are surfaced to know if the video has any violations, or if it has passed inspection.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VideoPrecheckResultWebhook"
},
"example": {
"type": 55,
"creator_open_id": "VIyStQAAAADCBQ40s4TzOSSOEIW-bM5O9cod3vK8OytW8m-bnBYlXw",
"tts_notification_id": "7327112393057371910",
"timestamp": 1644412885,
"data": {
"precheck_task_id": "7493990579714164574",
"result": "FAIL",
"issues": [
{
"risk": "Pirated Content",
"suggestion": "Your video may include unoriginal content. Creating original content is essential for standing out from the crowd."
}
]
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"responses": {
"200": {
"description": "Return HTTP 200 to acknowledge receipt."
}
},
"x-tts-webhook-type": 55,
"x-tts-docs-url": "https://partner.tiktokshop.com/docv2/page/iygh3ycz"
}
}
},
"components": {
"schemas": {
"ActivateProductsRequest": {
"type": "object",
"properties": {
"product_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "The product IDs to activate.\nMax number of IDs: 20"
},
"listing_platforms": {
"type": "array",
"items": {
"type": "string",
"enum": [
"TOKOPEDIA",
"TIKTOK_SHOP"
]
},
"description": "The listing platforms where the product will be activated. \nPossible values:\n- TOKOPEDIA\n- TIKTOK_SHOP\nDefault: TIKTOK_SHOP\n\nApplicable only for sellers that migrated from Tokopedia."
}
},
"required": [
"product_ids"
]
},
"ActivateProductsResponse": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int64",
"description": "Status code; 0 means success."
},
"message": {
"type": "string",
"description": "Success or failure message."
},
"request_id": {
"type": "string",
"description": "Request log ID."
},
"data": {
"$ref": "#/components/schemas/ActivateProductsResponseData"
}
}
},
"ActivateProductsResponseData": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ActivateProductsResponseDataError"
},
"description": "The errors for individual products that could not be activated. Check this list even when the top-level `code` is `0`."
}
}
},
"ActivateProductsResponseDataError": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int64",
"description": "The main error code."
},
"message": {
"type": "string",
"description": "The main error message."
},
"detail": {
"$ref": "#/components/schemas/ActivateProductsResponseDataErrorDetail",
"description": "The details of the main error."
}
}
},
"ActivateProductsResponseDataErrorDetail": {
"type": "object",
"properties": {
"product_id": {
"type": "string",
"description": "The ID of the product that could not be activated."
},
"extra_errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ActivateProductsResponseDataErrorDetailExtraError"
},
"description": "A list of further nested errors or issues related to the main error."
}
}
},
"ActivateProductsResponseDataErrorDetailExtraError": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int64",
"description": "The secondary error code."
},
"message": {
"type": "string",
"description": "The secondary error message."
}
}
},
"ActivityChangeWebhook": {
"type": "object",
"properties": {
"shop_id": {
"type": "string",
"description": "The ID of the shop."
},
"timestamp": {
"type": "integer",
"format": "int64",
"description": "The time when this webhook was triggered, represented by Unix timestamp."
},
"tts_notification_id": {
"type": "string",
"description": "The ID of the notification."
},
"type": {
"type": "integer",
"const": 63,
"description": "The ID of the webhook type."
},
"data": {
"$ref": "#/components/schemas/ActivityChangeWebhookData"
}
},
"required": [
"type"
]
},
"ActivityChangeWebhookData": {
"type": "object",
"properties": {
"activity_id": {
"type": "string",
"description": "The ID of the promotion activity."
},
"update_time": {
"type": "integer",
"format": "int64",
"description": "The time when the status changed, represented as a Unix timestamp (seconds)."
},
"change_type": {
"type": "string",
"description": "The type of activity changes. \n \n * CREATE \n * UPDATE \n * DEACTIVATE"
},
"product_update_list": {
"$ref": "#/components/schemas/ActivityChangeWebhookDataProductUpdateList",
"description": "Products included in an updated scope."
},
"product_remove_list": {
"$ref": "#/components/schemas/ActivityChangeWebhookDataProductRemoveList",
"description": "Products removed from the activity."
}
}
},
"ActivityChangeWebhookDataProductRemoveList": {
"type": "object",
"properties": {
"product_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Removed product IDs."
},
"sku_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Removed SKU IDs."
},
"benefit_product_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "TikTokShop product ID list."
},
"exclude_product_ids": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 100,
"description": "IDs of the BXGY exclude products to remove. \n Max count: 100."
}
}
},
"ActivityChangeWebhookDataProductUpdateList": {
"type": "object",
"properties": {
"product_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Included product IDs."
},
"exclude_product_ids": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 100,
"description": "IDs of the BXGY exclude products to remove. \n Max count: 100."
},
"benefit_product_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "TikTokShop product ID list."
}
}
},
"ActivityPrice": {
"type": "object",
"properties": {
"amount": {
"type": "string",
"description": "Activity price amount."
},
"currency": {
"type": "string",
"description": "Currency unit of an activity price."
}
}
},
"ActivityStatusChangeWebhook": {
"type": "object",
"properties": {
"type": {
"type": "integer",
"const": 39,
"description": "The ID of the webhook type."
},
"tts_notification_id": {
"type": "string",
"description": "The ID of the notification."
},
"shop_id": {
"type": "string",
"description": "The ID of the shop."
},
"timestamp": {
"type": "integer",
"format": "int64",
"description": "The time when this webhook was triggered, represented by Unix timestamp."
},
"data": {
"$ref": "#/components/schemas/ActivityStatusChangeWebhookData"
}
},
"required": [
"type"
]
},
"ActivityStatusChangeWebhookData": {
"type": "object",
"properties": {
"activity_id": {
"type": "string",
"description": "The ID of the promotion activity."
},
"update_time": {
"type": "integer",
"format": "int64",
"description": "The time when the status changed, represented as a Unix timestamp (seconds)."
},
"activity_type": {
"type": "string",
"enum": [
"FIXED_PRICE",
"DIRECT_DISCOUNT",
"SHIPPING_DISCOUNT",
"BUY_MORE_SAVE_MORE",
"FLASHSALE"
],
"x-enum-descriptions": [
"",
"",
"",
"",
"Only available in SEA markets: SG, TH, ID, MY, PH, VN"
],
"description": "The type of the promotion activity. Possible values are: \n \n * `FIXED_PRICE` \n * `DIRECT_DISCOUNT` \n * `SHIPPING_DISCOUNT` \n * `BUY_MORE_SAVE_MORE` \n * `FLASHSALE` (Only available in SEA markets: SG, TH, ID, MY, PH, VN)"
},
"product_level": {
"type": "string",
"enum": [
"PRODUCT",
"VARIATION",
"SHOP"
],
"description": "Activity product dimension, values are: \n \n * `PRODUCT` \n * `VARIATION` \n * `SHOP`"
},
"status": {
"type": "string",
"enum": [
"ONGOING",
"EXPIRED",
"DEACTIVATED"
],
"description": "The current status of the promotion activity. Possible values are: \n \n * `ONGOING` \n * `EXPIRED` \n * `DEACTIVATED`"
}
}
},
"ActualBonusCommission": {
"type": "object",
"properties": {
"amount": {
"type": "string",
"description": "The actual bonus commission amount as a localized display string. It may include a currency symbol or code and region-specific decimal and grouping separators; see the sibling `currency` field for the currency code."
},
"currency": {
"type": "string",
"description": "The currency code."
}
}
},
"ActualCommission": {
"type": "object",
"properties": {
"amount": {
"type": "string",
"description": "The actual commission amount as a localized display string. It may include a currency symbol or code and region-specific decimal and grouping separators; see the sibling `currency` field for the currency code. An empty string means that no actual commission value is available."
},
"currency": {
"type": "string",
"description": "The currency code."
}
}
},
"ActualCommissionBase": {
"type": "object",
"properties": {
"amount": {
"type": "string",
"description": "The actual commission base as a localized display string. It may include a currency symbol or code and region-specific decimal and grouping separators; see the sibling `currency` field for the currency code. For `SETTLED` orders, this contains the actual base when available; for `REFUNDED` orders, it is a localized zero value; for other statuses, it is an empty string."
},
"currency": {
"type": "string",
"description": "The currency code."
}
}
},
"ActualCreatorCommissionRewardFee": {
"type": "object",
"properties": {
"amount": {
"type": "string",
"description": "When available, the actual creator commission reward fee as a localized display string. It may include a currency symbol or code and region-specific decimal and grouping separators; see the sibling `currency` field for the currency code."
},
"currency": {
"type": "string",
"description": "The currency code."
}
}
},
"ActualShopAdsCommission": {
"type": "object",
"properties": {
"amount": {
"type": "string",
"description": "When available, the actual shop ads commission amount as a localized display string. It may include a currency symbol or code and region-specific decimal and grouping separators; see the sibling `currency` field for the currency code."
},
"currency": {
"type": "string",
"description": "The currency code."
}
}
},
"ActualStandardCommission": {
"type": "object",
"properties": {
"amount": {
"type": "string",
"description": "Commission amount without a currency symbol. Use the sibling `currency` field to identify the currency."
},
"currency": {
"type": "string",
"description": "Type of currency use"
}
}
},
"AddExternalOrderReferencesRequest": {
"type": "object",
"properties": {
"orders": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AddExternalOrderReferencesRequestOrder"
},
"maxItems": 100,
"description": "Orders for which to add or update external OMS references. Min count: 1. Max count: 100."
}
},
"required": [
"orders"
]
},
"AddExternalOrderReferencesRequestOrder": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The unique identifier for a TikTok Shop order."
},
"external_order": {
"$ref": "#/components/schemas/AddExternalOrderReferencesRequestOrderExternalOrder",
"description": "Order information in your external order management system (OMS)."
}
},
"required": [
"id",
"external_order"
]
},
"AddExternalOrderReferencesRequestOrderExternalOrder": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The corresponding order ID in your OMS."
},
"platform": {
"type": "string",
"enum": [
"SHOPIFY",
"WOOCOMMERCE",
"BIGCOMMERCE",
"MAGENTO",
"SALESFORCE_COMMERCE_CLOUD",
"CHANNEL_ADVISOR",
"AMAZON",
"ORDER_MANAGEMENT_SYSTEM",
"WAREHOUSE_MANAGEMENT_SYSTEM",
"ERP_SYSTEM"
],
"description": "The alias of your OMS.\nPossible values:\n- SHOPIFY\n- WOOCOMMERCE\n- BIGCOMMERCE\n- MAGENTO\n- SALESFORCE_COMMERCE_CLOUD\n- CHANNEL_ADVISOR\n- AMAZON\n- ORDER_MANAGEMENT_SYSTEM\n- WAREHOUSE_MANAGEMENT_SYSTEM\n- ERP_SYSTEM\n\nNotes:\n- To attach information from multiple OMSs to the same order in TikTok Shop, call this API multiple times, each with the same TikTok Shop order and a different OMS.\n- To edit the attached information for a TikTok Shop order, call the API with the same OMS."
},
"line_items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AddExternalOrderReferencesRequestOrderExternalOrderLineItem"
},
"maxItems": 100,
"description": "Max count: 100."
}
},
"required": [
"id",
"platform",
"line_items"
]
},
"AddExternalOrderReferencesRequestOrderExternalOrderLineItem": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Line item ID in your OMS."
},
"origin_id": {
"type": "string",
"description": "Line item ID in TikTok Shop."
}
},
"required": [
"id",
"origin_id"
]
},
"AddExternalOrderReferencesResponse": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int64",
"description": "Status code; 0 means success."
},
"message": {
"type": "string",
"description": "Success or failure message."
},
"request_id": {
"type": "string",
"description": "Request log ID."
},
"data": {
"$ref": "#/components/schemas/AddExternalOrderReferencesResponseData"
}
}
},
"AddExternalOrderReferencesResponseData": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AddExternalOrderReferencesResponseDataError"
},
"description": "Per-order errors. Each item identifies a TikTok Shop order and its external OMS reference that could not be processed. On a successful API response, references for orders not listed here are saved even when this list is non-empty."
}
}
},
"AddExternalOrderReferencesResponseDataError": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "The machine-readable code for this per-order error."
},
"message": {
"type": "string",
"description": "A human-readable message describing this per-order error."
},
"detail": {
"$ref": "#/components/schemas/AddExternalOrderReferencesResponseDataErrorDetail",
"description": "The TikTok Shop order and external OMS reference associated with this per-order error."
}
}
},
"AddExternalOrderReferencesResponseDataErrorDetail": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "The unique identifier for a TikTok Shop order."
},
"external_order": {
"$ref": "#/components/schemas/AddExternalOrderReferencesResponseDataErrorDetailExternalOrder",
"description": "The order information in your OMS."
}
}
},
"AddExternalOrderReferencesResponseDataErrorDetailExternalOrder": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The corresponding order ID in your OMS."
},
"platform": {
"type": "string",
"description": "The alias of your OMS."
}
}
},
"AddShowcaseProductsRequest": {
"type": "object",
"properties": {
"add_type": {
"type": "string",
"description": "Specifies how products are added to the showcase. This an enumerated type with values:\n- PRODUCT_ID\n- PRODUCT_LINK"
},
"product_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "A list of product identifiers included if `add_type` is set to `PRODUCT_ID`. The products associated with the identifiers are added to the showcase. Maximum length of the list is 20 product identifiers."
},
"product_link": {
"type": "string",
"description": "A product URL to use when `add_type` is set to `PRODUCT_LINK`. The product associated with the URL is added to the showcase."
}
},
"required": [
"add_type"
]
},
"AddShowcaseProductsResponse": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int64",
"description": "Status code; 0 means success."
},
"message": {
"type": "string",
"description": "Success or failure message."
},
"request_id": {
"type": "string",
"description": "Request log ID."
},
"data": {
"$ref": "#/components/schemas/AddShowcaseProductsResponseData"
}
}
},
"AddShowcaseProductsResponseData": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Error"
},
"description": "A list of product showcase addition errors."
}
}
},
"Address": {
"type": "object",
"properties": {
"street_address_line1": {
"type": "string",
"maxLength": 500,
"description": "The detailed street address of the location, including the building number, street name, district, city, province, and any relevant details.\nMax length: 500 characters"
},
"street_address_line2": {
"type": "string",
"maxLength": 500,
"description": "(**Deprecated**: This field is deprecated and will be removed in a future API version. If provided, its value will be merged into `street_address_line1`. It is recommended to specify `street_address_line1` directly.)\nAn optional secondary line for additional address details, if necessary.\nMax length: 500 characters",
"deprecated": true
},
"district": {
"type": "string",
"maxLength": 500,
"description": "(**Deprecated**: This field is deprecated and will be removed in a future API version. If provided, its value will be merged into `street_address_line1`. It is recommended to specify `street_address_line1` directly.)\n\nThe district name.\nMax length: 500 characters",
"deprecated": true
},
"city": {
"type": "string",
"maxLength": 500,
"description": "(**Deprecated**: This field is deprecated and will be removed in a future API version. If provided, its value will be merged into `street_address_line1`. It is recommended to specify `street_address_line1` directly.)\n\nThe city name.\nMax length: 500 characters",
"deprecated": true
},
"postal_code": {
"type": "string",
"maxLength": 500,
"description": "The postal code.\nMax length: 500 characters"
},
"province": {
"type": "string",
"maxLength": 500,
"description": "(**Deprecated**: This field is deprecated and will be removed in a future API version. If provided, its value will be merged into `street_address_line1`. It is recommended to specify `street_address_line1` directly.)\n\nThe province, state, or region name.\nMax length: 500 characters",
"deprecated": true
},
"country": {
"type": "string",
"description": "The two letter ISO 3166 country code representing the country of the address. It must be an EU country."
}
},
"required": [
"street_address_line1",
"postal_code",
"country"
]
},
"AerosolExtraInfo": {
"type": "object",
"properties": {
"volume": {
"type": "string",
"description": "Aerosol volume. Required when `hazmat_type` is `AEROSOLS`. The value must be a numeric string greater than 0."
},
"volume_unit": {
"type": "string",
"description": "aeroslo volume unit"
}
}
},
"AftersalesRequestStatusUpdateWebhook": {
"type": "object",
"properties": {
"shop_id": {
"type": "string",
"description": "TikTok Shop identifier associated with the event."
},
"timestamp": {
"type": "integer",
"format": "int64",
"description": "The time when this webhook was triggered, represented by Unix timestamp."
},
"tts_notification_id": {
"type": "string",
"description": "Unique notification identifier for deduplication and tracing."
},
"type": {
"type": "integer",
"const": 64,
"description": "The ID of the webhook type."
},
"data": {
"$ref": "#/components/schemas/AftersalesRequestStatusUpdateWebhookData"
}
},
"required": [
"type"
]
},
"AftersalesRequestStatusUpdateWebhookData": {
"type": "object",
"properties": {
"aftersales_request_id": {
"type": "string",
"description": "Unique identifier of the aftersales request."
},
"return_role": {
"type": "string",
"enum": [
"BUYER",
"SELLER"
],
"description": "Role that initiated the return flow. Possible enumerations: \n \n * `BUYER` \n * `SELLER`"
},
"aftersales_request_status": {
"type": "string",
"enum": [
"PENDING_REQUEST_REVIEW",
"REQUEST_REVIEW_COMPLETED"
],
"description": "Current aftersales request status. Possible enumerations: \n \n * `PENDING_REQUEST_REVIEW` \n * `REQUEST_REVIEW_COMPLETED`"
},
"aftersales_request_create_time": {
"type": "integer",
"format": "int64",
"description": "Creation time of the aftersales request in Unix seconds."
},
"aftersales_request_update_time": {
"type": "integer",
"format": "int64",
"description": "Last update time of the aftersales request in Unix seconds."
}
}
},
"AgeDistribution": {
"type": "object",
"properties": {
"age": {
"type": "string",
"description": "Possible values:\n- 18-24\n- 25-34\n- 35-44\n- 45-54\n- 55+"
},
"percentage": {
"type": "string",
"description": "Proportion for the corresponding age group within this viewer profile, expressed as a decimal fraction."
}
}
},
"Aov": {
"type": "object",
"properties": {
"amount": {
"type": "string",
"description": "Amount in the corresponding currency."
},
"currency": {
"type": "string",
"description": "Currency code (ISO 4217 standard)."
}
}
},
"AppealCompletedWebhook": {
"type": "object",
"properties": {
"shop_id": {
"type": "string"
},
"type": {
"type": "integer",
"const": 66,
"description": "The ID of the webhook type."
},
"tts_notification_id": {
"type": "string"
},
"timestamp": {
"type": "integer",
"format": "int64"
},
"data": {
"$ref": "#/components/schemas/AppealCompletedWebhookData"
}
},
"required": [
"type",
"shop_id",
"tts_notification_id",
"timestamp",
"data"
]
},
"AppealCompletedWebhookData": {
"type": "object",
"properties": {
"appeal_task": {
"$ref": "#/components/schemas/AppealCompletedWebhookDataAppealTask"
},
"product_id": {
"type": "integer",
"format": "int64"
}
},
"required": [
"appeal_task",
"product_id"
]
},
"AppealCompletedWebhookDataAppealTask": {
"type": "object",
"properties": {
"size_chart_id": {
"type": "integer",
"format": "int64"
},
"size_chart_image_uri": {
"type": "string"
},
"appeal_audit_result": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AppealCompletedWebhookDataAppealTaskAppealAuditResult"
}
}
},
"required": [
"appeal_audit_result"
]
},
"AppealCompletedWebhookDataAppealTaskAppealAuditResult": {
"type": "object",
"properties": {
"indicator_type": {
"type": "string"
},
"status": {
"type": "string"
},
"reject_reason": {
"type": "string"
}
},
"required": [
"indicator_type",
"status"
]
},
"ApproveCancellationRequest": {
"type": "object",
"properties": {}
},
"ApproveCancellationResponse": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int64",
"description": "Status code; 0 means success."
},
"message": {
"type": "string",
"description": "Success or failure message."
},
"request_id": {
"type": "string",
"description": "Request log ID."
},
"data": {
"$ref": "#/components/schemas/ApproveCancellationResponseData"
}
}
},
"ApproveCancellationResponseData": {
"type": "object",
"properties": {}
},
"ApproveReturnRequest": {
"type": "object",
"properties": {
"decision": {
"type": "string",
"enum": [
"APPROVE_REFUND",
"APPROVE_RETURN",
"APPROVE_RECEIVED_PACKAGE",
"APPROVE_REPLACEMENT",
"ISSUE_REPLACEMENT_REFUND",
"OFFER_PARTIAL_REFUND",
"DIRECT_REFUND"
],
"x-enum-descriptions": [
"seller approve a refund-only request",
"seller approve the initial return-and-refund request",
"seller approve return-and-refund request after the buyer has already shipped or handed over the item.",
"seller approve replacement request",
"seller decline the replacement request and directly refund the buyer instead.",
"seller offers a partial refund amount to the buyer without requiring the item(s) to be returned.",
"seller issues a returnless refund, meaning the buyer receives a full refund and keeps the item"
],
"description": "Seller's decision for the return request, available values:\n- `APPROVE_REFUND`: seller approve a refund-only request\n- `APPROVE_RETURN`: seller approve the initial return-and-refund request\n- `APPROVE_RECEIVED_PACKAGE`: seller approve return-and-refund request after the buyer has already shipped or handed over the item.\n- `APPROVE_REPLACEMENT`: seller approve replacement request\n- `ISSUE_REPLACEMENT_REFUND`: seller decline the replacement request and directly refund the buyer instead.\n- `OFFER_PARTIAL_REFUND`: seller offers a partial refund amount to the buyer without requiring the item(s) to be returned.\n- `DIRECT_REFUND`: seller issues a returnless refund, meaning the buyer receives a full refund and keeps the item"
},
"buyer_keep_item": {
"type": "boolean",
"description": "**Optional**. Use this field only when decision is set to `APPROVE_RETURN`. If set to `true`, the seller issues a returnless refund, which means the buyer receives a full refund and keeps the item. If set to `false` or omitted, the seller approves the return-and-refund flow and the buyer returns the item."
},
"partial_refund": {
"$ref": "#/components/schemas/PartialRefund",
"description": "**Required** when `decision` is set to `OFFER_PARTIAL_REFUND`. When `partial_refund` is provided, both `amount` and `currency` are required. Omit this field for all other decisions."
}
},
"required": [
"decision"
]
},
"ApproveReturnResponse": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int64",
"description": "Status code; 0 means success."
},
"message": {
"type": "string",
"description": "Success or failure message."
},
"request_id": {
"type": "string",
"description": "Request log ID."
},
"data": {
"$ref": "#/components/schemas/ApproveReturnResponseData"
}
}
},
"ApproveReturnResponseData": {
"type": "object",
"properties": {}
},
"AreaPlacement": {
"type": "object",
"properties": {
"height": {
"type": "string",
"description": "The height of the customizable area.\nSupports two decimal places."
},
"rotate_degree": {
"type": "string",
"description": "The rotation angle of the customizable area, in degrees.\nSupports two decimal places."
},
"width": {
"type": "string",
"description": "The width of the customizable area.\nSupports two decimal places."
},
"x_coordinate": {
"type": "string",
"description": "The X-coordinate of the customizable area's starting point on the surface.\nSupports two decimal places."
},
"y_coordinate": {
"type": "string",
"description": "The Y-coordinate of the customizable area's starting point on the surface.\nSupports two decimal places."
}
}
},
"AreaScope": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The (buyer's) geographical area to which the promotion activity applies.\n- `WHOLE`: Promotion activity applies to all areas to which the seller offers fulfillment. \n- `SPECIFIC_AREAS`: Only applies to specific fulfillment areas, as defined in `area_scope.specific_areas`"
},
"specific_areas": {
"type": "array",
"items": {
"type": "string"
},
"description": "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](https://partner.tiktokshop.com/docv2/page/67e3b059e7dc4f04a4ff9e09)"
}
},
"required": [
"type"
]
},
"AttributedGmv": {
"type": "object",
"properties": {
"amount": {
"type": "string",
"description": "Attributed GMV amount."
},
"currency": {
"type": "string",
"description": "Attributed GMV currency code."
}
}
},
"AvailableRejectReason": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The machine-readable name of the rejection reason to pass as the rejection-reason identifier in the applicable review or reject request."
},
"text": {
"type": "string",
"description": "The display text for the rejection reason."
}
}
},
"Avatar": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "The URL for the creator's TikTok profile avatar."
}
}
},
"AvgLiveAuctionPrice": {
"type": "object",
"properties": {
"amount": {
"type": "string",
"description": "Amount in the corresponding currency."
},
"currency": {
"type": "string",
"description": "Currency code (ISO 4217 standard)."
}
}
},
"AvgOrderValue": {
"type": "object",
"properties": {
"amount": {
"type": "string",
"description": "Amount in the corresponding currency."
},
"currency": {
"type": "string",
"description": "Currency code (ISO 4217 standard)."
}
}
},
"AvgPrice": {
"type": "object",
"properties": {
"amount": {
"type": "string",
"description": "GMV amount in the corresponding currency."
},
"currency": {
"type": "string",
"description": "GMV currency code (ISO 4217 standard). If LOCAL currency is requested, the value will be the local currency code of where the shop is registered (e.g. GBP)."
}
}
},
"AvgSkuOrderValue": {
"type": "object",
"properties": {
"amount": {
"type": "string",
"description": "Amount in the corresponding currency."
},
"currency": {
"type": "string",
"description": "Currency code (ISO 4217 standard)."
}
}
},
"BarcodeInfo": {
"type": "object",
"properties": {
"barcode_type": {
"type": "string",
"description": "Type of barcode provided for the goods, such as UPC."
},
"barcode_value": {
"type": "string",
"description": "Barcode value. UPC must contain 8 or 12 digits; EAN must contain 8 or 13 digits; and GTIN must contain 8, 12, 13, or 14 digits. UPC, EAN, and GTIN values must have a valid checksum. ASIN_OR_FNSKU must contain 10 uppercase letters or digits and start with B or X. MERCHANT_SKU_ID must contain 1 to 32 printable ASCII characters with no whitespace."
}
}
},
"BatchShipPackagesRequest": {
"type": "object",
"properties": {
"packages": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BatchShipPackagesRequestPackage"
},
"description": "Input list of packages you would like to batch ship."
}
},
"required": [
"packages"
]
},
"BatchShipPackagesRequestPackage": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Package ID."
},
"handover_method": {
"type": "string",
"enum": [
"PICKUP",
"DROP_OFF"
],
"x-enum-descriptions": [
"A shipping provider will pickup the package(s) from the seller's pickup address.",
"The seller will need to drop off the package(s) at a designated location."
],
"description": "Possible values:\n- `PICKUP`: A shipping provider will pickup the package(s) from the seller's pickup address.\n- `DROP_OFF`: The seller will need to drop off the package(s) at a designated location."
},
"pickup_slot": {
"$ref": "#/components/schemas/PickupSlot",
"description": "Package pickup time slot."
},
"self_shipment": {
"$ref": "#/components/schemas/SelfShipment",
"description": "Only needed for seller shipping packages. Check the `delivery_option `field in [Get Package Detail](https://partner.tiktokshop.com/docv2/page/650aa39fbace3e02b75d8617?external_id=650aa39fbace3e02b75d8617) to see how to differentiate between TikTok shipping and seller shipping. Use the `shipping_provider_id` retrieved from the [Get Shipping Providers](https://partner.tiktokshop.com/docv2/page/650aa48d4a0bb702c06d85cd?external_id=650aa48d4a0bb702c06d85cd#Back%20To%20Top) API and upload the corresponding tracking number."
}
},
"required": [
"id"
]
},
"BatchShipPackagesResponse": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int64",
"description": "Status code; 0 means success."
},
"message": {
"type": "string",
"description": "Success or failure message."
},
"request_id": {
"type": "string",
"description": "Request log ID."
},
"data": {
"$ref": "#/components/schemas/BatchShipPackagesResponseData"
}
}
},
"BatchShipPackagesResponseData": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BatchShipPackagesResponseDataError"
},
"description": "Package-specific errors for packages that could not be shipped. Check this list even when the top-level response `code` is `0`."
}
}
},
"BatchShipPackagesResponseDataError": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int64",
"description": "The failure reason code."
},
"message": {
"type": "string",
"description": "The failure reason message."
},
"detail": {
"$ref": "#/components/schemas/BatchShipPackagesResponseDataErrorDetail",
"description": "Error detail."
}
}
},
"BatchShipPackagesResponseDataErrorDetail": {
"type": "object",
"properties": {
"package_id": {
"type": "string",
"description": "Package ID."
}
}
},
"BatteryExtraInfo": {
"type": "object",
"properties": {
"battery_type": {
"type": "string",
"description": "Battery type\nPossible values:\nLITHIUM_ION\nLITHIUM_METAL\nOTHER"
},
"battery_packaging_type": {
"type": "string",
"enum": [
"STANDALONE",
"IN_EQUIPMENT",
"WITH_EQUIPMENT",
"OTHER"
],
"description": "Battery packaging type.\nPossible values:\n- STANDALONE\n- IN_EQUIPMENT\n- WITH_EQUIPMENT\n- OTHER"
},
"total_battery_weight": {
"type": "string",
"description": "Total battery weight in the unit specified by total_battery_weight_unit."
},
"total_battery_weight_unit": {
"type": "string",
"description": "Unit for total_battery_weight. Possible value: GRAM."
},
"total_battery_capacity": {
"type": "string",
"description": "Total battery capacity in the unit specified by total_battery_capacity_unit."
},
"total_battery_capacity_unit": {
"type": "string",
"description": "Unit for total_battery_capacity, such as WATTHOUR."
},
"is_need_un_38_3_test": {
"type": "boolean",
"description": "UN38.3 testing ensures that batteries meet specific safety criteria. Please send the report in the field if it's not included in the MSDS."
},
"un_38_3_test_file_url": {
"type": "string",
"description": "UN38.3 testing file URL"
},
"battery_count_per_package": {
"type": "string",
"description": "per package battery count"
}
},
"required": [
"battery_type",
"battery_packaging_type",
"total_battery_weight",
"total_battery_weight_unit",
"total_battery_capacity",
"total_battery_capacity_unit",
"is_need_un_38_3_test"
]
},
"Benchmark": {
"type": "object",
"properties": {
"excellent_threshold": {
"type": "string",
"description": "Excellent tier threshold."
},
"poor_threshold": {
"type": "string",
"description": "Poor tier threshold."
}
}
},
"BoxMeasurement": {
"type": "object",
"properties": {
"weight": {
"type": "string",
"description": "Carton weight."
},
"weight_unit": {
"type": "string",
"enum": [
"KILOGRAM",
"GRAM",
"MILLIGRAM",
"POUNDS",
"OUNCE"
],
"x-enum-descriptions": [
"kg",
"g",
"mg",
"lbs",
"oz"
],
"description": "The unit used for the carton's `weight` value.\n\n**Possible values:**\n* `KILOGRAM` (kg)\n* `GRAM` (g)\n* `MILLIGRAM` (mg)\n* `POUNDS` (lbs)\n* `OUNCE` (oz)"
},
"width": {
"type": "string",
"description": "Carton width."
},
"height": {
"type": "string",
"description": "Carton height."
},
"length": {
"type": "string",
"description": "Carton length."
},
"length_unit": {
"type": "string",
"enum": [
"METER",
"CENTIMETER",
"MILLIMETER",
"FOOT",
"MICRON",
"INCH"
],
"x-enum-descriptions": [
"m",
"cm",
"mm",
"ft",
"μm",
"in"
],
"description": "The unit used for the carton's `length`, `width`, and `height` values.\n\n**Possible values:**\n* `METER` (m)\n* `CENTIMETER` (cm)\n* `MILLIMETER` (mm)\n* `FOOT` (ft)\n* `MICRON` (μm)\n* `INCH` (in)"
}
},
"required": [
"weight",
"weight_unit",
"width",
"height",
"length",
"length_unit"
]
},
"Brand": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the brand of this product."
},
"name": {
"type": "string",
"description": "The brand name of this product."
}
}
},
"BxgyDiscount": {
"type": "object",
"properties": {
"threshold_type": {
"type": "string",
"enum": [
"MINIMAL_ITEM_QUANTITY",
"MINIMAL_ORDER_AMOUNT"
],
"x-enum-descriptions": [
"The buyer must purchase at least the configured quantity of eligible products.",
"The eligible-product subtotal must reach the configured amount."
],
"description": "The purchase criterion.\nPossible values:\n- `MINIMAL_ITEM_QUANTITY`: The buyer must purchase at least the configured quantity of eligible products.\n- `MINIMAL_ORDER_AMOUNT`: The eligible-product subtotal must reach the configured amount."
},
"threshold_value": {
"type": "string",
"description": "The purchase threshold determined by `threshold_type`.\n- When `threshold_type==MINIMAL_ITEM_QUANTITY`, enter a positive integer no greater than `10`.\n- When `threshold_type==MINIMAL_ORDER_AMOUNT`, enter a positive eligible-product subtotal in local currency, with at most two decimal places."
},
"discount_type": {
"type": "string",
"enum": [
"PERCENTAGE_OFF",
"FREE",
"AMOUNT_OFF_EACH"
],
"x-enum-descriptions": [
"Apply the percentage specified by discount_value to eligible products.",
"Provide the configured quantity of eligible products for free.",
"Deduct the local-currency amount specified by discount_value from each eligible product."
],
"description": "The type of benefit.\nPossible values:\n- PERCENTAGE_OFF: Apply the percentage specified by discount_value to eligible products.\n- FREE: Provide the configured quantity of eligible products for free.\n- AMOUNT_OFF_EACH: Deduct the local-currency amount specified by discount_value from each eligible product."
},
"discount_value": {
"type": "string",
"description": "Value of the discount.\n- 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.\n- `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."
},
"benefit_max_applicable_quantity": {
"type": "string",
"description": "The quantity of item Y awarded each time the Buy X Get Y benefit applies. Enter a positive integer no greater than `20`."
},
"benefit_max_applicable_times": {
"type": "string",
"description": "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`."
}
},
"required": [
"threshold_type",
"threshold_value",
"discount_type",
"discount_value",
"benefit_max_applicable_quantity"
]
},
"CalculateRefundRequest": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "TikTok Shop order id."
},
"request_type": {
"type": "string",
"description": "Request type\n- CANCEL\n- REFUND\n- RETURN_AND_REFUND\nNote: different request types are used for different aftersales scenarios. Also, different request types might have different refund amounts, because the refund amount calculation policy is different."
},
"shipment_type": {
"type": "string",
"description": "How buyer ships items to seller when in a return request, could be:\n- `PLATFORM`\n- `BUYER_ARRANGE`"
},
"handover_method": {
"type": "string",
"description": "Which handover method buyer chooses to use when returning goods to seller by platform\n- `DROP_OFF`: buyer drops off the parcel in logistics service collect point.\n- `PICKUP`: logistics service picks up the buyer package."
},
"reason_name": {
"type": "string",
"description": "Seller's reason for the selected cancellation, refund, or return-and-refund request. Use the [Get Aftersale Eligibility](https://partner.tiktokshop.com/docv2/page/69c3070c66dee40493fdfe2e) endpoint to retrieve the currently available reasons, and submit the returned reason name in this field."
},
"order_line_item_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "TikTok Shop order line item IDs to include in the refund calculation. Do not provide non-empty values in both `order_line_item_ids` and `order_line_list` in the same request."
},
"skus": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Sku"
},
"description": "skus"
},
"order_line_list": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OrderLineList"
},
"description": "Order lines to include in the refund calculation. Use this field when you need to identify individual sub-items in a bundle product. **Note:** This field is completely backward compatible with the previous `order_line_item_ids` field. Do not provide non-empty values in both `order_line_list` and `order_line_item_ids` in the same request."
}
},
"required": [
"order_id",
"request_type",
"reason_name"
]
},
"CalculateRefundResponse": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int64",
"description": "Status code; 0 means success."
},
"message": {
"type": "string",
"description": "Success or failure message."
},
"request_id": {
"type": "string",
"description": "Request log ID."
},
"data": {
"$ref": "#/components/schemas/CalculateRefundResponseData"
}
}
},
"CalculateRefundResponseData": {
"type": "object",
"properties": {
"order_refund_amount": {
"$ref": "#/components/schemas/CalculateRefundResponseDataOrderRefundAmount",
"description": "Refund amount to buyer."
}
}
},
"CalculateRefundResponseDataOrderRefundAmount": {
"type": "object",
"properties": {
"currency": {
"type": "string",
"description": "Currency for payment."
},
"refund_total": {
"type": "string",
"description": "Total amount refund to buyer."
},
"refund_subtotal": {
"type": "string",
"description": "Subtotal amount included in the calculated refund."
},
"refund_shipping_fee": {
"type": "string",
"description": "Shipping fee refund to buyer."
},
"refund_tax": {
"type": "string",
"description": "Tax returned to buyer."
},
"retail_delivery_fee": {
"type": "string",
"description": "Retail delivery fee takes effect once platform GMV exceeds 500,000 USD, according to US Colorado states' compliance rules."
}
}
},
"CancelFBTMCFOrderRequest": {
"type": "object",
"properties": {
"mcf_order_id": {
"type": "string",
"description": "The MCF order ID as a numeric string."
},
"consign_orders": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CancelFBTMCFOrderRequestConsignOrder"
},
"description": "The consign orders to cancel. Omit this field to cancel all consign orders in the specified MCF order."
}
},
"required": [
"mcf_order_id"
]
},
"CancelFBTMCFOrderRequestConsignOrder": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The consign order ID as a numeric string without the `OBF` prefix."
}
}
},
"CancelFBTMCFOrderResponse": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int64",
"description": "Status code; 0 means success."
},
"message": {
"type": "string",
"description": "Success or failure message."
},
"request_id": {
"type": "string",
"description": "Request log ID."
},
"data": {
"$ref": "#/components/schemas/CancelFBTMCFOrderResponseData"
}
}
},
"CancelFBTMCFOrderResponseData": {
"type": "object",
"properties": {
"mcf_order": {
"$ref": "#/components/schemas/CancelFBTMCFOrderResponseDataMcfOrder",
"description": "The mcf order information and related consign order status."
}
}
},
"CancelFBTMCFOrderResponseDataMcfOrder": {
"type": "object",
"properties": {
"external_order_id": {
"type": "string",
"description": "The corresponding order ID in your OMS."
},
"mcf_order_id": {
"type": "string",
"description": "A unique ID that identifies different MCF orders"
},
"consign_orders": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CancelFBTMCFOrderResponseDataMcfOrderConsignOrder"
},
"description": "All consign orders in the MCF order and their current statuses after the cancellation request. Match the requested consign order IDs to the returned items; a status of `CLOSED` means that the consign order has been canceled."
}
}
},
"CancelFBTMCFOrderResponseDataMcfOrderConsignOrder": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The consign order ID, returned as a numeric string without the `OBF` prefix."
},
"status": {
"type": "string",
"enum": [
"PENDING",
"HANDLE_BY_WAREHOUSE",
"SHIPPED",
"HANDOVER",
"CLOSED",
"LOST",
"DAMAGE",
"COMPLETED",
"ABNORMAL",
"RETURNED",
"SCRAP",
"UNKNOWN"
],
"x-enum-descriptions": [
"Order is pending warehouse processing",
"Order is being processed by the warehouse",
"Order has been shipped out from the warehouse",
"Order has been received by the logistics carrier and is in transit",
"Order has been canceled",
"Order is lost",
"Order is damaged",
"Order has been completed",
"There is an issue related to this order and cannot be fulfilled",
"Order has been returned",
"Order has been scrapped",
"Order status is unknown"
],
"description": "The current status of this consign order. In a cancellation response, `CLOSED` means that the consign order has been canceled.\n\nPossible Status Enumerations\n1. **PENDING** - Order is pending warehouse processing\n2. **HANDLE_BY_WAREHOUSE** - Order is being processed by the warehouse\n3. **SHIPPED** - Order has been shipped out from the warehouse\n4. **HANDOVER** - Order has been received by the logistics carrier and is in transit\n5. **CLOSED** - Order has been canceled\n6. **LOST** - Order is lost\n7. **DAMAGE** - Order is damaged\n8. **COMPLETED** - Order has been completed\n9. **ABNORMAL** - There is an issue related to this order and cannot be fulfilled\n10. **RETURNED** - Order has been returned\n11. **SCRAP** - Order has been scrapped\n12. **UNKNOWN** - Order status is unknown"
}
}
},
"CancelInboundOrderRequest": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "The positive numeric identifier of the inbound order to cancel.\n\n**Note:** Provide the numeric sequence only; do not include the \"IBR\" prefix (for example, use `123456` instead of `IBR123456`)."
},
"cancel_reason": {
"type": "string",
"description": "Reason for cancelling the inbound order. The value must not be empty or contain only whitespace."
}
},
"required": [
"order_id",
"cancel_reason"
]
},
"CancelInboundOrderResponse": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int64",
"description": "Status code; 0 means success."
},
"message": {
"type": "string",
"description": "Success or failure message."
},
"request_id": {
"type": "string",
"description": "Request log ID."
},
"data": {
"$ref": "#/components/schemas/CancelInboundOrderResponseData"
}
}
},
"CancelInboundOrderResponseData": {
"type": "object",
"properties": {}
},
"CancelOrderRequest": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "TikTok Shop order id"
},
"skus": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Sku"
},
"description": "List of SKU to cancel"
},
"order_line_item_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of order line item IDs to cancel. In the US and UK markets, when an item is out of stock, partial cancellation at the individual item level is supported. To initiate a partial cancellation, specify the item's order line ID. **Note:** This is a legacy field. For new integrations, use `order_line_list` instead. Do not provide non-empty values in both `order_line_item_ids` and `order_line_list` in the same request."
},
"cancel_reason": {
"type": "string",
"description": "Reason for canceling the order. To obtain a reason for this order, call `GET /return_refund/202602/orders/{order_id}/aftersale_eligibility` with the same `order_id`, `initiate_aftersale_user=SELLER`, and `request_types=CANCEL`. From the corresponding `data.sku_eligibility[].line_item_eligibility[]` result, pass an exact value from `available_reason_names` as `cancel_reason`. See \"Return API Overview\" for additional guidance on seller cancellation reasons."
},
"order_line_list": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OrderLineList"
},
"description": "List of order lines or sub-order lines to cancel. In the US and UK markets, when an item is out of stock, partial cancellation at the individual item level is supported. **Note:** This field is completely backward compatible with the previous `order_line_item_ids` field. Do not provide non-empty values in both `order_line_list` and `order_line_item_ids` in the same request."
}
},
"required": [
"order_id",
"cancel_reason"
]
},
"CancelOrderResponse": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int64",
"description": "Status code; 0 means success."
},
"message": {
"type": "string",
"description": "Success or failure message."
},
"request_id": {
"type": "string",
"description": "Request log ID."
},
"data": {
"$ref": "#/components/schemas/CancelOrderResponseData"
}
}
},
"CancelOrderResponseData": {
"type": "object",
"properties": {
"cancel_id": {
"type": "string",
"description": "The identifier of a specific order cancellation."
},
"cancel_status": {
"type": "string",
"enum": [
"CANCELLATION_REQUEST_PENDING",
"CANCELLATION_REQUEST_SUCCESS",
"CANCELLATION_REQUEST_CANCEL",
"CANCELLATION_REQUEST_COMPLETE"
],
"description": "The status of an order cancellation request. \nAvailable values:\n- `CANCELLATION_REQUEST_PENDING`\n- `CANCELLATION_REQUEST_SUCCESS`\n- `CANCELLATION_REQUEST_CANCEL`\n- `CANCELLATION_REQUEST_COMPLETE`"
}
}
},
"CancellationStatusChangeWebhook": {
"type": "object",
"properties": {
"type": {
"type": "integer",
"const": 11,
"description": "The ID of the webhook type."
},
"tts_notification_id": {
"type": "string",
"description": "The ID of the notification."
},
"shop_id": {
"type": "string",
"description": "The shop ID."
},
"timestamp": {
"type": "integer",
"format": "int64",
"description": "The Unix timestamp when the webhook was triggered."
},
"data": {
"$ref": "#/components/schemas/CancellationStatusChangeWebhookData"
}
},
"required": [
"type"
]
},
"CancellationStatusChangeWebhookData": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "The identification of a TikTok Shop order"
},
"cancellations_role": {
"type": "string",
"enum": [
"BUYER",
"SELLER",
"SYSTEM"
],
"description": "The user who initiated a cancellation, with possible values: \n \n * BUYER \n * SELLER \n * SYSTEM"
},
"cancel_status": {
"type": "string",
"enum": [
"CANCELLATION_REQUEST_PENDING",
"CANCELLATION_REQUEST_SUCCESS",
"CANCELLATION_REQUEST_CANCELLED",
"CANCELLATION_REQUEST_COMPLETE"
],
"description": "Order cancellation status, with possible values: \n \n * CANCELLATION_REQUEST_PENDING \n * CANCELLATION_REQUEST_SUCCESS \n * CANCELLATION_REQUEST_CANCELLED \n * CANCELLATION_REQUEST_COMPLETE"
},
"cancel_id": {
"type": "string",
"description": "The identifier of a specific order cancellation"
},
"create_time": {
"type": "integer",
"format": "int64",
"description": "The time when the buyer initiated the cancellation request, represented as a Unix timestamp (seconds)."
}
}
},
"Carton": {
"type": "object",
"properties": {
"carton_type": {
"type": "string",
"enum": [
"SINGLE_SKU",
"MULTI_SKU"
],
"x-enum-descriptions": [
"`items` must contain exactly one item.",
"`items` must contain two or more items."
],
"description": "Indicates whether the carton is configured as single-SKU or multi-SKU.\n\n**Possible values:**\n* `SINGLE_SKU`: `items` must contain exactly one item.\n* `MULTI_SKU`: `items` must contain two or more items."
},
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Item"
},
"description": "Goods item list of a carton."
},
"quantity": {
"type": "integer",
"format": "int64",
"description": "Number of cartons that use this carton configuration."
},
"carton_nums": {
"type": "array",
"items": {
"type": "string"
},
"description": "Identifiers assigned to the cartons represented by this configuration. Either every carton configuration in the request must provide a non-empty `carton_nums` array, or no configuration may provide any carton identifiers. When provided, the number of identifiers must equal this configuration's `quantity`; each identifier must use the format `C` followed by four digits and must be unique across the request. If none are provided, carton identifiers are generated automatically."
},
"box_measurements": {
"$ref": "#/components/schemas/BoxMeasurement",
"description": "Carton measurement."
}
},
"required": [
"carton_type",
"items",
"quantity",
"box_measurements"
]
},
"Category": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The category ID."
}
}
},
"CategoryChain": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The current category id of this product."
},
"local_name": {
"type": "string",
"description": "The current level category name of this product."
},
"is_leaf": {
"type": "boolean",
"description": "Indicate whether current node is leaf node"
},
"parent_id": {
"type": "string",
"description": "The category id of its parent category"
}
}
},
"Certification": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID to identify the type of certification required for the product category.\nRetrieve this value from the [Get Category Rules API](https://partner.tiktokshop.com/docv2/page/6509c0febace3e02b74594a9)."
},
"images": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Image"
},
"description": "A list of certification related images."
},
"files": {
"type": "array",
"items": {
"$ref": "#/components/schemas/File"
},
"description": "A list of certification related files."
},
"expiration_date": {
"type": "integer",
"format": "int64",
"description": "The expiration date of this certification expressed in unix timestamp (seconds) UTC+0. \nThis field may be required for certain certifications. Use the [Get Category Rules API](https://partner.tiktokshop.com/docv2/page/6509c0febace3e02b74594a9) to find out the requirements."
}
},
"required": [
"id"
]
},
"CheckCreatorOutreachEligibilityRequest": {
"type": "object",
"properties": {
"creator_infos": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CheckCreatorOutreachEligibilityRequestCreatorInfo"
},
"description": "Creator information to evaluate for the shop's outreach eligibility. Provide one to 100 entries with unique Creator Open IDs."
}
},
"required": [
"creator_infos"
]
},
"CheckCreatorOutreachEligibilityRequestCreatorInfo": {
"type": "object",
"properties": {
"creator_open_id": {
"type": "string",
"description": "Creator Open ID."
}
},
"required": [
"creator_open_id"
]
},
"CheckCreatorOutreachEligibilityResponse": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int64",
"description": "Status code; 0 means success."
},
"message": {
"type": "string",
"description": "Success or failure message."
},
"request_id": {
"type": "string",
"description": "Request log ID."
},
"data": {
"$ref": "#/components/schemas/CheckCreatorOutreachEligibilityResponseData"
}
}
},
"CheckCreatorOutreachEligibilityResponseData": {
"type": "object",
"properties": {
"creator_eligibility_results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CheckCreatorOutreachEligibilityResponseDataCreatorEligibilityResult"
},
"description": "Per-creator raw connection and quota eligibility facts."
},
"ineligible_creator_levels": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
},
"description": "Creator levels that prevent quota consumption for the full requested batch. This is an empty array when no creator level prevents quota consumption."
},
"is_batch_quota_consumable": {
"type": "boolean",
"description": "Whether quota can be consumed for the full requested creator batch."
}
}
},
"CheckCreatorOutreachEligibilityResponseDataCreatorEligibilityResult": {
"type": "object",
"properties": {
"creator_level": {
"type": "integer",
"format": "int64",
"description": "Creator level evaluated by the quota rules."
},
"creator_open_id": {
"type": "string",
"description": "Creator Open ID from the request."
},
"is_blocked": {
"type": "boolean",
"description": "Whether a blocking relationship prevents the shop and creator from connecting."
},
"is_connected": {
"type": "boolean",
"description": "Whether the shop is already connected with the creator."
},
"is_creator_follower_count_threshold_met": {
"type": "boolean",
"description": "Whether the creator meets the follower count threshold required for the shop to initiate creator outreach."
},
"is_creator_level_quota_available": {
"type": "boolean",
"description": "Whether outreach quota is available for the creator's level."
},
"is_paired": {
"type": "boolean",
"description": "Whether the shop is paired with the creator."
}
}
},
"CheckCreatorSampleEligibilityResponse": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int64",
"description": "Status code; 0 means success."
},
"message": {
"type": "string",
"description": "Success or failure message."
},
"request_id": {
"type": "string",
"description": "Request log ID."
},
"data": {
"$ref": "#/components/schemas/CheckCreatorSampleEligibilityResponseData"
}
}
},
"CheckCreatorSampleEligibilityResponseData": {
"type": "object",
"properties": {
"label": {
"$ref": "#/components/schemas/CheckCreatorSampleEligibilityResponseDataLabel",
"description": "Creator applicable sample label information."
}
}
},
"CheckCreatorSampleEligibilityResponseDataLabel": {
"type": "object",
"properties": {
"can_apply": {
"type": "boolean",
"description": "Whether the authenticated creator can apply for a sample of the specified product."
},
"status": {
"type": "string",
"description": "Status indicating whether the creator has applied for a free sample of the specified product.\n- UNKNOWN: The application status is unknown.\n- TO_APPLY: The creator has not applied for a free sample of the product.\n- ONGOING: The creator has applied for a free sample but has not completed sample fulfillment.\n- COMPLETE: The creator has applied for a free sample and completed sample fulfillment."
},
"application_id": {
"type": "string",
"description": "Sample Application ID. only appear when the creator has already applied this product."
},
"reach_limit": {
"type": "boolean",
"description": "If the creator has reached the sample application upper limit."
},
"sample_product": {
"$ref": "#/components/schemas/CheckCreatorSampleEligibilityResponseDataLabelSampleProduct",
"description": "The sample product information."
}
}
},
"CheckCreatorSampleEligibilityResponseDataLabelSampleProduct": {
"type": "object",
"properties": {
"sample_sku_list": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CheckCreatorSampleEligibilityResponseDataLabelSampleProductSampleSkuList"
},
"description": "The sample product SKU information."
}
}
},
"CheckCreatorSampleEligibilityResponseDataLabelSampleProductSampleSkuList": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The SKU identifier."
},
"sale_property_value_ids": {
"type": "string",
"description": "The SKU property value identifiers joined with underscores (`_`) in the same order as the entries in `sale_properties`."
},
"price": {
"$ref": "#/components/schemas/Price",
"description": "SKU price information."
},
"sale_properties": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CheckCreatorSampleEligibilityResponseDataLabelSampleProductSampleSkuListSaleProperty"
},
"description": "The SKU property information."
},
"is_available": {
"type": "boolean",
"description": "Whether this SKU is available for the creator to apply for as a sample."
},
"unavailable_reason": {
"type": "string",
"enum": [
"IS_PREORDER",
"IS_GIFT",
"OUT_OF_STOCK",
"EXCEED_CB_PRICE_THRESHOLD",
"ALREADY_APPLYED",
"UNKNOWN"
],
"x-enum-descriptions": [
"The product is a preorder product and does not support free samples.",
"The product is a gift and does not support free samples.",
"The product is out of stock.",
"The SKU price exceeds the applicable cross-border price threshold.",
"The creator has already applied for this SKU.",
"No mapped unavailability reason is available."
],
"description": "The reason code associated with SKU sample availability. Interpret a specific unavailability reason only when `is_available` is `false`. `UNKNOWN` can also be returned when `is_available` is `true` because no unavailability reason applies.\nPossible values:\n- IS_PREORDER: The product is a preorder product and does not support free samples.\n- IS_GIFT: The product is a gift and does not support free samples.\n- OUT_OF_STOCK: The product is out of stock.\n- EXCEED_CB_PRICE_THRESHOLD: The SKU price exceeds the applicable cross-border price threshold.\n- ALREADY_APPLYED: The creator has already applied for this SKU.\n- UNKNOWN: No mapped unavailability reason is available."
}
}
},
"CheckCreatorSampleEligibilityResponseDataLabelSampleProductSampleSkuListSaleProperty": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "A SKU property identifier, short for \"Stock Keeping Unit Property ID\", is a specific identification code assigned to a particular property or characteristic of a SKU.(i.e: \"100000\" means \"color\")"
},
"name": {
"type": "string",
"description": "The SKU property name."
},
"value_id": {
"type": "string",
"description": "The SKU property value identifier is an identification code related to the specific values of the properties of a Stock Keeping Unit (SKU).\nWhen a SKU has certain properties like color, size, etc., each possible value for those properties has its own unique SKU property value identifier. For instance, if the property is \"color\" and the possible values are \"red\", \"blue\", \"green\", then \"red\" would have its own SKU property vvalue identifier, \"blue\" would have another one, and so on."
},
"value_name": {
"type": "string",
"description": "The SKU property value name."
}
}
},
"CheckListingPrerequisitesResponse": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int64",
"description": "Status code; 0 means success."
},
"message": {
"type": "string",
"description": "Success or failure message."
},
"request_id": {
"type": "string",
"description": "Request log ID."
},
"data": {
"$ref": "#/components/schemas/CheckListingPrerequisitesResponseData"
}
}
},
"CheckListingPrerequisitesResponseData": {
"type": "object",
"properties": {
"check_results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CheckListingPrerequisitesResponseDataCheckResult"
},
"description": "A list of results from checking whether a shop satisfies TikTok Shop requirements."
}
}
},
"CheckListingPrerequisitesResponseDataCheckResult": {
"type": "object",
"properties": {
"check_item": {
"type": "string",
"enum": [
"SHOP_STATUS",
"SHOP_TAX",
"PICKUP_WAREHOUSE",
"RETURN_WAREHOUSE",
"DELIVERY_OPTION",
"SHIPPING_TEMPLATE",
"PRODUCT_QUANTITY_LIMIT",
"EXTENDED_PRODUCER_RESPONSIBILITY",
"BANk_ACCOUNT",
"CONTACT_INFO"
],
"description": "A requirement that the shop needs to satisfy.\nPossible values:\n- SHOP_STATUS\n- SHOP_TAX\n- PICKUP_WAREHOUSE\n- RETURN_WAREHOUSE\n- DELIVERY_OPTION\n- SHIPPING_TEMPLATE\n- PRODUCT_QUANTITY_LIMIT\n- EXTENDED_PRODUCER_RESPONSIBILITY\n- BANk_ACCOUNT\n- CONTACT_INFO"
},
"is_failed": {
"type": "boolean",
"description": "A flag indicating whether the shop has failed a `check_item`."
},
"fail_reasons": {
"type": "array",
"items": {
"type": "string"
},
"description": "The specific reasons for failing a certain `check_item`."
}
}
},
"CheckProductListingRequest": {
"type": "object",
"properties": {
"description": {
"type": "string",
"maxLength": 10000,
"description": "The product description in HTML format.\n\n**Note**:\n- The content must conform to the [HTML syntax](https://html.spec.whatwg.org/). All HTML tags are accepted but to optimize display on the TikTok Shop product detail page, the system will automatically convert certain tags into alternative formats, such as rendering `