openapi: 3.1.0 info: title: TikTok Shop Partner API version: 2026.10.19 description: Generated from the TikTok Shop Partner Center documentation (https://partner.tiktokshop.com/docv2). Do not edit by hand. externalDocs: url: https://partner.tiktokshop.com/docv2 servers: - url: https://open-api.tiktokglobalshop.com security: - accessToken: [] tags: - name: Affiliate creator - name: Affiliate partner - name: Affiliate seller - name: Analytics - name: Authorization - name: Customer engagement - name: Customer service - name: Event - name: Finance - name: Fulfilled by TikTok (FBT) - name: Fulfillment - name: Logistics - name: Orders - name: Products - name: Promotion - name: Return and refund - name: Seller - name: Supply chain - name: Tools paths: /affiliate_creator/202405/open_collaborations/products/search: post: operationId: searchOpenCollaborationProducts summary: Search Open Collaboration Products description: |- This API is used to search the information of products with open collaboration by category, commission rate, and keywords. It will return all products on the TikTok Shop Affiliate Product Marketplace that are in an open collaboration. Creators can only search for open collaboration within the regions they are registered in the affiliate. tags: - Affiliate creator parameters: - name: page_token in: query required: false description: Pagination token. Leave this parameter empty in the first request. To retrieve the next page, pass the `next_page_token` returned by the previous response and reuse the same `category`, `commission_rate_range`, `sales_price_range`, `title_keywords`, `sort_field`, `sort_order`, and `page_size` values. An empty `next_page_token` means there are no more pages. 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 20. schema: type: integer format: int64 minimum: 1 maximum: 20 - name: sort_field in: query required: false description: |- The returned results are sorted by the specified field. Possible values: - commission_rate - product_sales_price - commission - units_sold Specify the sort order using the `sort_order` parameter. schema: type: string enum: - commission_rate - product_sales_price - commission - units_sold - name: sort_order in: query required: false description: |- The sort order for the objects in the response. Default: ASC Possible values: - ASC: Ascending order - DESC: Descending order schema: type: string enum: - ASC - DESC x-enum-descriptions: - Ascending order - Descending order requestBody: content: application/json: schema: $ref: "#/components/schemas/SearchOpenCollaborationProductsRequest" example: title_keywords: - Men - Fashion - " Sports Short" sales_price_range: amount_ge: "12.44" amount_lt: "100" category: id: "341234" commission_rate_range: rate_ge: 100 rate_lt: 8000 responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/SearchOpenCollaborationProductsResponse" 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: "341182" 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-scenario: 4 x-tts-scopes: - Read Creator Affiliate Collaborations x-tts-error-codes: [] x-tts-docs-url: https://partner.tiktokshop.com/docv2/page/search-open-collaboration-products-202405 /affiliate_creator/202405/showcases/products: get: operationId: getShowcaseProducts summary: Get Showcase Products description: This API lists the products in the creator's showcase, paginated by specified page size and iterated through pages by page token for up to 2000 products in the showcase. This API is generally used when a creator would like to view the products in the showcase. The platform will return the product details in the showcase, as well as the products in the livebag if the creator is live streaming. tags: - Affiliate creator parameters: - 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 - 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: origin in: query required: true description: Set to `LIVE` to indicate the request originates from a Live room. Set to `SHOWCASE` to indicate that the request originates from the Showcase. schema: type: string responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/GetShowcaseProductsResponse" example: code: 0 data: products: - id: "53219092314" shop: name: Gift store addition: customized_main_images: - width: 100 heigth: 100 url: https://p16-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/d76b8cc1b598de90ad5048df46e672b3~c5_100x100.webp?x-expires=1691895600&x-signature=oAT9KOL7aCN3Did9U%2FoKEsbBDj0%3D price: original_price: minimum_amount: "12.21" maximum_amount: "100.00" currency: USD seller_discount_price: minimum_amount: "12.21" maximum_amount: "100.00" currency: USD platform_discount_price: minimum_amount: "12.21" maximum_amount: "100.00" currency: USD title: Chirstmas Gift main_images: - width: 100 heigth: 100 url: https://p16-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/d76b8cc1b598de90ad5048df46e672b3~c5_100x100.webp?x-expires=1691895600&x-signature=oAT9KOL7aCN3Did9U%2FoKEsbBDj0%3D status: inventory_status: IN_STOCK review_status: APPROVED is_hidden: false added_status: ADDED source: AFFILIATE detail_link: https://shop.tiktok.com/view/product/248901892031?region=US&local=en third_party_link: https://storename.myshopify.com/products/gold-bracelet-engraved-with-diamonds sale_regions: - US commission: rate: 3000 reward_rate: 500 collaboration: id: "7495383576027499219" type: "1" partner: id: "123456789" name: Partner Name next_page_token: V231as2V0PTAK total_count: 15 message: Success request_id: 202203070749000101890810281E8C70B7 x-tts-scenario: 4 x-tts-scopes: - Content Posting - Read Showcase Products x-tts-error-codes: - code: "18001405" message: This creator account has no selection region. - 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-showcase-products-202405 /affiliate_creator/202405/showcases/products/add: post: operationId: addShowcaseProducts summary: Add Showcase Products description: This API adds products to the authenticated creator's showcase. Global Shop users must have at least one selected region before calling this API. A successful API response can still contain `errors` for products that were not added; when there are no product-level addition errors, `errors` is omitted. tags: - Affiliate creator requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AddShowcaseProductsRequest" example: add_type: PRODUCT_ID product_ids: - "12390753231" - "7102893481290" product_link: https://www.example.com/api/v1/share/AImHx6DlXqP1 responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/AddShowcaseProductsResponse" example: code: 0 data: errors: - code: 16001001 message: Encounter network error, please try again. detail: product_id: "12390753231" message: Success request_id: 202203070749000101890810281E8C70B7 x-tts-scenario: 4 x-tts-scopes: - Content Posting - Manage Showcase Products x-tts-error-codes: [] x-tts-docs-url: https://partner.tiktokshop.com/docv2/page/add-showcase-products-202405 /affiliate_creator/202405/target_collaborations/search: post: operationId: searchCreatorTargetCollaborations summary: Search Creator Target Collaborations description: Searches for the authenticated creator's target collaborations and the products within them for the TikTok Shop specified by `shop_id`. tags: - Affiliate creator parameters: - name: page_token in: query required: false description: An opaque token used to retrieve the next page of a paginated result set. It is not needed for the first page. For each subsequent page, pass the previous response's `next_page_token` unchanged as `page_token` and reuse the same `page_size`, `shop_id`, `keyword`, and `keyword_type` values, including whether optional `keyword` and `keyword_type` were omitted or provided. schema: type: string - name: page_size in: query required: true description: "The number of results to be returned per page. Valid range: [0-100]." schema: type: integer format: int64 minimum: 0 maximum: 100 requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SearchCreatorTargetCollaborationsRequest" example: shop_id: "789078671231" keyword_type: TARGET_COLLABORATIONS_ID keyword: "12312312" responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/SearchCreatorTargetCollaborationsResponse" example: code: 0 data: total_count: 100 next_page_token: b2Zmc2V0PTIw target_collaborations: - id: "789078671231123124" name: target_collaboration status: LIVE products: - 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 commission: rate: 1000 amount: "121.23" currency: USD message: Success request_id: 202203070749000101890810281E8C70B7 x-tts-scenario: 4 x-tts-scopes: - Read Creator Affiliate Collaborations x-tts-error-codes: [] x-tts-docs-url: https://partner.tiktokshop.com/docv2/page/search-creator-target-collaborations-202405 /affiliate_creator/202409/sample_applications/fulfillments/search: post: operationId: creatorSearchSampleApplicationFulfillments summary: Creator Search Sample Application Fulfillments description: You, the creator, can use this API to query the fulfillment status for the received sample applications. tags: - Affiliate creator parameters: - name: sort_order in: query required: false description: |- The sort order for the field specified in the sort_field parameter. Default: ASC Possible values: ASC: Ascending order DESC: Descending order schema: type: string - name: sort_field in: query required: false description: |- Possible values: - expired_time: Sort by the remaining time to fulfill. - create_time: Sort by the fulfillment record creation time. Default: expired_time. schema: type: string enum: - expired_time - create_time x-enum-descriptions: - Sort by the remaining time to fulfill. - Sort by the fulfillment record creation time. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreatorSearchSampleApplicationFulfillmentsRequest" example: fulfillment_statuses: - PENDING - ONGOING responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/CreatorSearchSampleApplicationFulfillmentsResponse" example: code: 0 data: fulfillments: - id: "123456" shop_id: "123456" application_id: "123456" sample_application_type: FREE_SAMPLE product_id: "123456" expiration_time: 1728542813 total_suspend_duration: 100020 status: ONGOING bound_product_status: LIVE message: Success request_id: 202203070749000101890810281E8C70B7 x-tts-scenario: 4 x-tts-scopes: - Read Creator Affiliate Collaborations x-tts-error-codes: [] x-tts-docs-url: https://partner.tiktokshop.com/docv2/page/creator-search-sample-application-fulfillments-202409 /affiliate_creator/202409/showcases/products: delete: operationId: removeShowcaseProducts summary: Remove Showcase Products description: |- This API removes the products in the creator's showcase. The platform will return error code and error message if the deletion fails. tags: - Affiliate creator requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/RemoveShowcaseProductsRequest" example: product_ids: - "12390753231" - "7102893481290" responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/RemoveShowcaseProductsResponse" example: code: 0 data: code: 0 message: Success request_id: 202203070749000101890810281E8C70B7 message: Success request_id: 202203070749000101890810281E8C70B7 x-tts-scenario: 4 x-tts-scopes: - Manage Showcase Products 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: "16015027" message: System error x-tts-docs-url: https://partner.tiktokshop.com/docv2/page/remove-showcase-products-202409 /affiliate_creator/202409/showcases/products/top: post: operationId: moveShowcaseProductsToTheTop summary: Move Showcase Products to the Top description: |- Use this API to move products to the top of the authenticated creator's showcase. The platform will return the error code and error message if the pinning operation fails. tags: - Affiliate creator requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/MoveShowcaseProductsToTheTopRequest" example: product_ids: - "12390753231" - "7102893481290" responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/MoveShowcaseProductsToTheTopResponse" example: code: 0 data: code: 0 message: Success request_id: 202203070749000101890810281E8C70B7 message: Success request_id: 202203070749000101890810281E8C70B7 x-tts-scenario: 4 x-tts-scopes: - Manage Showcase Products 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: "16015027" message: System error x-tts-docs-url: https://partner.tiktokshop.com/docv2/page/move-showcase-products-to-the-top-202409 /affiliate_creator/202410/orders/search: post: operationId: searchCreatorAffiliateOrders summary: Search Creator Affiliate Orders description: Search affiliate orders attributed to the authenticated creator. The response includes order and SKU details, order status, content attribution, commission rates, and estimated or actual commission amounts for tracking affiliate conversions. tags: - Affiliate creator parameters: - 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 Valid Range: [1-100] schema: type: integer format: int64 minimum: 1 maximum: 100 requestBody: content: application/json: schema: $ref: "#/components/schemas/SearchCreatorAffiliateOrdersRequest" example: create_time_ge: 1719807456 create_time_lt: 1728443155 responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/SearchCreatorAffiliateOrdersResponse" example: code: 0 data: orders: - id: "789078671231123124" create_time: 1685548800 delivery_time: 1685548800 status: SETTLED skus: - id: "1729793769377925388" campaign_id: "73661290629" open_collaboration_id: "73661290629" target_collaboration_id: "73661290629" product_name: black_suit product_id: "1729793769377859852" price: amount: Rp9.900 currency: IDR shop_name: TestCase idl2l content_type: LIVE content_id: "7493990579714164574" quantity: 2 commission_rate: 1000 commission_tier_setting: 3.0 OR 5.0 commission_model: Tiered commission commission_bonus_rate: 1000 estimated_commission_base: amount: Rp9.900 currency: IDR standard_commission_rate: 5000 shop_ads_commission_rate: 5000 estimated_bonus_commission: amount: Rp1.00 currency: IDR estimated_standard_commission: amount: Rp8.000 currency: IDR estimated_shop_ads_commission: amount: Rp8.000 currency: IDR estimated_commission: amount: Rp1.980 currency: IDR actual_commission: amount: Rp1.900 currency: IDR actual_bonus_commission: amount: Rp2.000 currency: IDR actual_commission_base: amount: Rp9.900 currency: IDR actual_standard_commission: amount: Rp5.000 currency: IDR actual_shop_ads_commission: amount: Rp5.000 currency: IDR returned_quantity: 1 refunded_quantity: 0 tag: test-01 creator_commission_reward_rate: 1000 estimated_creator_commission_reward_fee: amount: "250" currency: IDR actual_creator_commission_reward_fee: amount: "100" currency: IDR isr: amount: "100" currency: MXN iva: amount: "100" currency: MXN pit: amount: "100" currency: IDR shared_with_partner: amount: "100" currency: IDR trace_info: id: "15678763" type: SPECIFIC last_update_time: 1685548800 is_carousel: false next_page_token: b2Zmc2V0PTEw total_count: 10 message: Success request_id: 202203070749000101890810281E8C70B7 x-tts-scenario: 4 x-tts-scopes: - Read Creator Affiliate Collaborations x-tts-error-codes: [] x-tts-docs-url: https://partner.tiktokshop.com/docv2/page/search-creator-affiliate-orders-202410 /affiliate_creator/202412/sample_applications/search: post: operationId: searchCreatorSampleApplications summary: Search Creator Sample Applications description: Search sample applications for the authenticated creator. tags: - Affiliate creator parameters: - name: page_token in: query required: false description: The page token returned in `next_page_token` by the previous response. Omit this parameter for the first request. For subsequent pages, pass the returned token and reuse the same `application_statuses` value. 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. Default 20 schema: type: integer format: int64 minimum: 1 maximum: 50 requestBody: content: application/json: schema: $ref: "#/components/schemas/SearchCreatorSampleApplicationsRequest" example: application_statuses: - PENDING - AWAITING_SHIPMENT responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/SearchCreatorSampleApplicationsResponse" example: code: 0 data: next_page_token: "20" sample_applications: - id: "8070590921506065183" sample_product: id: "1729432087292775344" sku_id: "1729480364147774364" sku_sale_property_value_names: - red - large size main_order_id: "13444222" activity_id: "13456677" status: PENDING creator_fulfillment: id: "123456" expiration_time: 1726301400 total_suspend_duration: 123 status: PENDING bound_product_status: LIVE message: Success request_id: 202203070749000101890810281E8C70B7 x-tts-scenario: 4 x-tts-scopes: - Read Creator Affiliate Collaborations x-tts-error-codes: [] x-tts-docs-url: https://partner.tiktokshop.com/docv2/page/search-creator-sample-applications-202412 /affiliate_creator/202412/sample_applications/single_query: post: operationId: getCreatorSampleApplicationDetail summary: Get Creator Sample Application Detail description: Get the sample detail of specified sample application. tags: - Affiliate creator requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/GetCreatorSampleApplicationDetailRequest" example: product_id: "1729480364147774364" application_id: "8070590921506065183" application_type: FREE_SAMPLE main_order_id: "579622078763731743" responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/GetCreatorSampleApplicationDetailResponse" example: code: 0 data: sample_application: id: "8070590921506065183" create_time: 1731298837 sample_product: id: "1729863469568985219" sku_id: "1729480364147774364" sku_sale_property_value_names: - red - large size main_order_id: "57871819384716917" activity_id: "74378918272345199" type: FREE_SAMPLE status: PENDING creator_fulfillment: id: "87147319238415178" expiration_time: 1726301400 total_suspend_duration: 7641234 status: PENDING message: Success request_id: 202203070749000101890810281E8C70B7 x-tts-scenario: 4 x-tts-scopes: - Read Creator Affiliate Collaborations 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-sample-application-detail-202412 /affiliate_creator/202412/samples/labels: get: operationId: checkCreatorSampleEligibility summary: Check Creator Sample Eligibility description: Check if a creator can apply for a sample of a specific product. tags: - Affiliate creator parameters: - name: product_id in: query required: true description: The TikTok Shop product identifier. schema: type: string responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/CheckCreatorSampleEligibilityResponse" example: code: 0 data: label: can_apply: true status: ONGOING application_id: "86427198341982134" reach_limit: true sample_product: sample_sku_list: - id: "1731055098570377347" sale_property_value_ids: "7068196393634072325" price: amount: "7588986" currency: USD sale_properties: - id: "100000" name: color value_id: "7425668826861520646" value_name: Default is_available: true unavailable_reason: IS_PREORDER message: Success request_id: 202203070749000101890810281E8C70B7 x-tts-scenario: 4 x-tts-scopes: - Read Creator Affiliate Collaborations 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/check-creator-sample-eligibility-202412 /affiliate_creator/202504/affiliate_sharing_links/publisher/{publisher_id}/generate_batch: post: operationId: generatePublisherSharingLinksInBatch summary: Generate Publisher Sharing Links in Batch description: |- You can use this API to generate material sharing links for a specific publisher. After that, you can share the link with the publisher. Right now, the material type must be `PRODUCT`. Please ensure that the material is included in the campaign by using [Generate Multi Affiliate Partner Campaign Product Links](generate-multi-affiliate-partner-campaign-product-links). tags: - Affiliate creator parameters: - name: publisher_id in: path required: true description: The publisher id in partner's system schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/GeneratePublisherSharingLinksInBatchRequest" example: material: ids: - "7362840009596339971" - "7362840009596339923" type: PRODUCT promotion_campaign_schema: https://www.tiktok.com/t/ZSxRC4FEL/ campaign_id: "7432840009596339923" link_type: "TOKO " responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/GeneratePublisherSharingLinksInBatchResponse" example: code: 0 data: sharing_links: - material_id: 7362840009596339971 sharing_link: https://www.tiktok.com/t/AIxvOHlaJoKO deep_link: snssdk1180://ec/pdp?biz_type=0&enter_method=web&gd_label=click_wap_p_product_detail_t_launch_pop_up_s__e__f__fp__fps_affiliate_links_rf_&h5_start_ts=1768977752558&is_commerce=1&jump_time=1768977752558&mall_extra_info=%7B%22mall_out_source%22%3A%22seo.web_product_detail.out_of_app%22%2C%22mall_landing_page%22%3A%22product_detail%22%2C%22mall_homepage_visited_type%22%3A2%7D&media_source=channelshareh5&need_mall=1&needlaunchlog=1&o_app_code=abcsadaadada&page_name=reflow_pdp&page_name=product_detail¶ms_url=https%3A%2F%2Fshop-id.tokopedia.com%2Fview%2Fproduct%2F1730831248044885504%3Fchain_key%3D%257B%2522event_id%2522%253A%2522o_event_id%2522%252C%2522k%2522%253A%2522000000000000000007596668298679682828%2522%252C%2522sc%2522%253A%2522OPEN_API%2522%252C%2522t%2522%253A1%257D%26div_media_source%3Daffiliate%26event_id%3Do_event_id%26landing_page_name%3Dproduct_detail%26landpage_form%3Dhalf%26page_name%3Dproduct_detail%26scene%3Dpdp%26share_app_id%3D1180%26sticky_diversion_config%3D%257B%2522merge_action%2522%253A%2522merge%2522%252C%2522data%2522%253A%257B%2522channel%2522%253A%255B%2522benefit_hub%2522%255D%257D%252C%2522is_sticky%2522%253A1%257D%26touch_point_product_id%3D1730831248044885504%26trackParams%3D%257B%2522enter_from_info%2522%253A%2522product_share_outside%2522%252C%2522source_page_type%2522%253A%2522product_share%2522%252C%2522enable_shop_tab_popup%2522%253A1%257D%26utm_source%3Dopen_api&previous_page=deeplink_ug_seo_outside_gg_product_detail_link_web&refer=web&requestParams=%7B%22product_id%22%3A%5B%221730831248044885504%22%5D%7D&scene=pdp&trackParams=%7B%22enter_from_info%22%3A%22product_share_outside%22%2C%22source_page_type%22%3A%22product_share%22%2C%22enable_shop_tab_popup%22%3A1%7D&traffic_diversion_info=%7B%22traffic_out_source%22%3A%22affiliate_links%22%2C%22page_name%22%3A%22product_detail%22%7D&ug_media_source=deeplink_ug_seo_outside_gg_product_detail_link_web&ug_medium=fe_component&utm_source=open_api&wid=7506871187759580673 one_link: | https://snssdk1180.onelink.me/BAuo?params_url=https%3A%2F%2Fshop-id.tokopedia.com%2Fview%2Fproduct%2F1730831248044885504%3Fchain_key%3D%257B%2522event_id%2522%253A%2522o_event_id%2522%252C%2522k%2522%253A%2522000000000000000007596668298679682828%2522%252C%2522sc%2522%253A%2522OPEN_API%2522%252C%2522t%2522%253A1%257D%26div_media_source%3Daffiliate%26event_id%3Do_event_id%26landing_page_name%3Dproduct_detail%26landpage_form%3Dhalf%26page_name%3Dproduct_detail%26scene%3Dpdp%26share_app_id%3D1180%26sticky_diversion_config%3D%257B%2522merge_action%2522%253A%2522merge%2522%252C%2522data%2522%253A%257B%2522channel%2522%253A%255B%2522benefit_hub%2522%255D%257D%252C%2522is_sticky%2522%253A1%257D%26touch_point_product_id%3D1730831248044885504%26trackParams%3D%257B%2522enter_from_info%2522%253A%2522product_share_outside%2522%252C%2522source_page_type%2522%253A%2522product_share%2522%252C%2522enable_shop_tab_popup%2522%253A1%257D%26utm_source%3Dopen_api failed_materials: - material_id: "7362840009596339923" fail_reason: The product was sold out message: Success request_id: 202203070749000101890810281E8C70B7 x-tts-scenario: 4 x-tts-scopes: - Read Affiliate Share Link x-tts-error-codes: [] x-tts-docs-url: https://partner.tiktokshop.com/docv2/page/generate-publisher-sharing-links-in-batch-202504 /affiliate_creator/202505/affiliate_sharing_links/general_publishers/generate_batch: post: operationId: generateGeneralSharingLinks summary: Generate General Sharing Links description: |- You can use this API to generate material sharing links for your publishers. After that, you can encapsulate the sharing link with additional information like publisher ID. Right now, the material type must be `PRODUCT`. Please ensure that the material is included in the campaign by using [Generate Multi Affiliate Partner Campaign Product Links]. tags: - Affiliate creator requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/GenerateGeneralSharingLinksRequest" example: material: ids: - "7362840009596339971" - "7362840009596339923" type: PRODUCT promotion_campaign_schema: https://www.tiktok.com/t/ZSxRC4FEL/ campaign_id: "7332840009596339923" link_type: TOKO responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/GenerateGeneralSharingLinksResponse" example: code: 0 data: sharing_links: - material_id: "7362840009596339971" sharing_link: https://www.tiktok.com/view/product/1730958349688804006?chain_key=%7B%22t%22%3A1%2C%22k%22%3A%22000000000000000007518161308526446350%22%2C%22sc%22%3A%22OPEN_API%22%7D&scene=pdp&utm_source=open_api&trackParams=%7B%22enter_from_info%22%3A%22product_share_outside%22%2C%22source_page_type%22%3A%22product_share%22%2C%22enable_shop_tab_popup%22%3A1%7D&share_app_id=1233 deep_link: | snssdk1180://ec/pdp?biz_type=0&enter_method=web&gd_label=click_wap_p_product_detail_t_launch_pop_up_s__e__f__fp__fps_affiliate_links_rf_&h5_start_ts=1768977752558&is_commerce=1&jump_time=1768977752558&need_mall=1&needlaunchlog=1&o_app_code=abcsadaadada&page_name=reflow_pdp&page_name=product_detail¶ms_url=https%3A%2F%2Fshop-id.tokopedia.com%2Fview%2Fproduct%2F1730831248044885504%3Fchain_key%3D%257B%2522event_id%2522%253A%2522o_event_id%2522%252C%2522k%2522%253A%2522000000000000000007596668298679682828%2522%252C%2522sc%2522%253A%2522OPEN_API%2522%252C%2522t%2522%253A1%257D%26div_media_source%3Daffiliate%26event_id%3Do_event_id%26landing_page_name%3Dproduct_detail%26landpage_form%3Dhalf%26page_name%3Dproduct_detail%26scene%3Dpdp%26share_app_id%3D1180%26sticky_diversion_config%3D%257B%2522merge_action%2522%253A%2522 one_link: | https://snssdk1180.onelink.me/BAuo?params_url=https%3A%2F%2Fshop-id.tokopedia.com%2Fview%2Fproduct%2F1730831248044885504%3Fchain_key%3D%257B%2522event_id%2522%253A%2522o_event_id%2522%252C%2522k%2522%253A%2522000000000000000007596668298679682828%2522%252C%2522sc%2522%253A%2522OPEN_API%2522%252C%2522t%2522%253A1%257D%26div_media_source%3Daffiliate%26event_id%3Do_event_id%26landing_page_name%3Dproduct_detail%26landpage_form%3Dhalf%26page_name%3Dproduct_detail%26scene%3Dpdp%26share_app_id%3D1180%26sticky_diversion_config%3D%257B%2522merge_action%2522%253A%2522merge%2522%252C%2522data%2522%253A%257B%2522channel%2522%253A%255B%2522benefit_hub%2522%255D%257D%252C%2522is_sticky%2522%253A1%257D%26touch_point_product_id%3D1730831248044885504%26trackParams%3D%257B%2522enter_from_info%2522%253A%2522product_share_outside%2522%252C%2522source_page_type%2522%253A%2522product_share%2522%252C%2522enable_shop_tab_popup%2522%253A1%257D%26utm_source%3Dopen_api failed_materials: - material_id: "7362840009596339972" fail_reason: Product was sold out message: Success request_id: 202203070749000101890810281E8C70B7 x-tts-scenario: 4 x-tts-scopes: - Read Affiliate Share Link x-tts-error-codes: [] x-tts-docs-url: https://partner.tiktokshop.com/docv2/page/generate-general-sharing-links-202505 /affiliate_creator/202505/orders/trace/search: post: operationId: searchAffiliateOrdersByCreator summary: Search Affiliate Orders by Creator description: Retrieves affiliate orders attributed to the creator represented by the current access token. Results can provide order status and timestamps, together with SKU-level product, shop, content, trace, quantity, price, and estimated or actual commission details. tags: - Affiliate creator parameters: - 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 return per page. Valid range: 1 to 100. schema: type: integer format: int64 minimum: 1 maximum: 100 requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SearchAffiliateOrdersByCreatorRequest" example: time_ge: 1719807456000 time_lt: 1728443155000 time_type: PAY_TIME responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/SearchAffiliateOrdersByCreatorResponse" example: code: 0 data: orders: - id: 789078671231123124 status: SETTLED skus: - id: "1729793769377925388" product_id: "1729793769377859852" price: amount: Rp9.900 currency: IDR quantity: 2 commission_rate: 1000 estimated_commission_base: amount: Rp9.900 currency: IDR actual_commission: amount: Rp1.900 currency: IDR shop_ads_commission_rate: 5000 commission_bonus_rate: 1000 product_name: black suit shop_name: TestCase idl2l returned_quantity: 1 refunded_quantity: 0 campaign_id: "73661290629" actual_commission_base: amount: Rp9.900 currency: IDR actual_shop_ads_commission: amount: Rp5.000 currency: IDR estimated_shop_ads_commission: amount: Rp8.000 currency: IDR estimated_bonus_commission: amount: Rp1.00 currency: IDR delivery_time: 1685548800 creator_commission_reward_rate: 1000 estimated_creator_commission_reward_fee: amount: "250" currency: IDR actual_creator_commission_reward_fee: amount: "100" currency: IDR content_type: LIVE content_id: "7493990579714164574" trace: id: "15678763" type: SPECIFIC estimated_commission: amount: "1" currency: USD actual_bonus_commission: amount: "1" currency: USD create_time: 1685548800 delivery_time: 1685548800 next_page_token: b2Zmc2V0PTEw total_count: 10 message: Success request_id: 202203070749000101890810281E8C70B7 x-tts-scenario: 4 x-tts-scopes: - Read Affiliate Share Link 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-affiliate-orders-by-creator-202505 /affiliate_creator/202505/videos/video_files: post: operationId: uploadShoppableVideoFile summary: Upload Shoppable Video File description: Upload a video file before posting a shoppable video to TikTok. After the upload succeeds, call `POST /affiliate_creator/202505/videos` and pass the returned `video_file.id` as `video_info.file_id`. tags: - Affiliate creator requestBody: required: true content: multipart/form-data: schema: $ref: "#/components/schemas/UploadShoppableVideoFileRequest" responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/UploadShoppableVideoFileResponse" example: code: 0 data: video_file: id: "123123123123" md5: D41D8CD98F00B204E9800998ECF8427E 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/upload-shoppable-video-file-202505 /affiliate_creator/202508/profiles: get: operationId: getCreatorProfile summary: Get Creator Profile description: Retrieves profile information for the creator associated with the access token. The creator must have a configured sales region; otherwise, the request fails with a precondition error. tags: - Affiliate creator responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/GetCreatorProfileResponse" example: code: 0 data: avatar: width: 100 height: 100 url: https://p16-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/d76b8cc1b598de90ad5048df46e672b3~c5_100x100.webp?x-expires=1691895600&x-signature=oAT9KOL7aCN3Did9U%2FoKEsbBDj0%3D username: abc123 selection_region: US register_region: US seller_type: LOCAL permissions: - LIVE_STREAM_PERMISSION - SELF_SALE_PERMISSION - ADD_AFFILIATE_PERMISSION user_type: TIKTOK_SHOP_OFFICIAL_ACCOUNT creator_user_open_id: uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg message: Success request_id: 202203070749000101890810281E8C70B7 x-tts-scenario: 4 x-tts-scopes: - Affiliate Information - Content Posting x-tts-error-codes: - code: "16015006" message: There is no selection region in this creator now. please contact the creator and ensure he has ec permission now. - code: "16015007" message: "no sale region error; detail: creator has no sale region." - code: "16501011" message: user has no permission to access this api. please check the creator auth info. - code: "16504002" message: query creator info failed.Please check creator ec permission is avaliable now - code: "36009002" message: Too many requests. You've made too many requests in a short period of time. x-tts-docs-url: https://partner.tiktokshop.com/docv2/page/get-creator-profile-202508 /affiliate_creator/202509/open_collaborations/products: post: operationId: getOpenCollaborationProductListByProductIds summary: Get Open Collaboration Product List By Product Ids description: Retrieves open collaboration product information for the specified product IDs. tags: - Affiliate creator parameters: - name: product_ids in: query required: false description: "A comma-separated list of numeric product IDs. Maximum: 50 IDs per request." explode: false schema: type: array items: type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/GetOpenCollaborationProductListByProductIdsRequest" example: {} responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/GetOpenCollaborationProductListByProductIdsResponse" example: code: 0 data: products: - shop: name: Test shop id: "1729432087292775344" has_inventory: false units_sold: 12 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: "3435545" local_name: COMPUTER is_leaf: false parent_id: "12345" commission: rate: 100 currency: USD amount: "0" sales_price: currency: USD minimum_amount: "34.3" maximum_amount: "55.7" shop_ads_commission: rate: 100 message: Success request_id: 202203070749000101890810281E8C70B7 x-tts-scenario: 4 x-tts-scopes: - Read Creator Affiliate Collaborations x-tts-error-codes: [] x-tts-docs-url: https://partner.tiktokshop.com/docv2/page/get-open-collaboration-product-list-by-product-ids-202509 /affiliate_creator/202509/shop_products: get: operationId: getShopProducts summary: Get Shop Products description: Searches for products in the shop bound to the authenticated creator. Optionally use `title_keyword` to filter products by title. The creator must have a bound shop before calling this API. tags: - Affiliate creator parameters: - name: title_keyword in: query required: false description: The title keyword of the product you wish to search by. schema: type: string - name: sort_field in: query required: false description: |- Sort field. Possible values: - PRODUCT_ID - PRICE - SALE If omitted or empty, defaults to PRODUCT_ID. Any other value is rejected. schema: type: string enum: - PRODUCT_ID - PRICE - SALE - name: sort_order in: query required: false description: |- Sort order. Possible values: - DESC - ASC If omitted or empty, defaults to DESC. Any other value is rejected. schema: type: string enum: - DESC - ASC - name: page_size in: query required: true description: |- Pagination count determines how many products you'll get after sending the request. 20 is a recommended number. Valid 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. 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 `title_keyword`, `sort_field`, `sort_order`, and `page_size` values. schema: type: string responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/GetShopProductsResponse" example: code: 0 data: products: - id: "1729592969712207012" title: testcase autotest Live Product price: amount: "56.00" currency: USD added_status: ADDABLE brand_name: Apple images: - url: https://p19-pu-sign-useast8.tiktokcdn-us.com/tos-useast5-avt-0068-tx/982dd6b4e46a6a24203b00611a474cca~c5_1080x1080.webp width: 200 height: 200 sales_count: 33 total_count: 300 next_page_token: b2Zmc2V0PTIw 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-shop-products-202509 /affiliate_creator/202509/videos/{video_id}/status: get: operationId: getShoppableVideoStatus summary: Get Shoppable Video Status description: Use this API to get shoppable video posting results. tags: - Affiliate creator parameters: - name: video_id in: path required: true description: The video id from [Publish Shoppable Video] schema: type: string responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/GetShoppableVideoStatusResponse" example: code: 0 data: video: id: "7493990579714164574" post_status: FAIL post_time: 1685548800 message: Success request_id: 202203070749000101890810281E8C70B7 x-tts-scenario: 4 x-tts-scopes: - Content Posting x-tts-error-codes: - code: "170001016" message: The video does not belong to the creator or the video is not photo post. Please check valid video status. - code: "38007001" message: System Error x-tts-docs-url: https://partner.tiktokshop.com/docv2/page/get-shoppable-video-status-202509 /affiliate_creator/202511/photos/photo_files: post: operationId: uploadShoppablePhotoFile summary: Upload Shoppable Photo File description: Use this API to upload the photos before photo posting. It returns the photo_file_uri for each uploaded image tags: - Affiliate creator requestBody: required: true content: multipart/form-data: schema: $ref: "#/components/schemas/UploadShoppablePhotoFileRequest" responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/UploadShoppablePhotoFileResponse" example: code: 0 data: photo_file: photo_uri: skldjfskdlfjlskdfs000023423s message: Success request_id: 202203070749000101890810281E8C70B7 x-tts-scenario: 4 x-tts-scopes: - Content Posting 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-shoppable-photo-file-202511 /affiliate_creator/202511/videos/precheck_task: post: operationId: createVideoPrecheckTask summary: Create Video Precheck Task description: Use this API to create a task that checks a video and its shoppable content anchor for violations. If the task is created successfully, the response returns a task ID. tags: - Affiliate creator requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateVideoPrecheckTaskRequest" example: video_info: file_id: v12d00gd0024d3nfqr7og65 product_link_info: product_id: "17294069642063424" title: Sample product anchor title responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/CreateVideoPrecheckTaskResponse" example: code: 0 data: precheck: task_id: "1123123123" message: Success request_id: 202203070749000101890810281E8C70B7 x-tts-scenario: 4 x-tts-scopes: - Content Posting x-tts-error-codes: - code: "16011007" message: Product link title should be no longer than 30 characters. - code: "16011009" message: Product link title contains offensive language. - code: "16011069" message: Product link title contains punctuation or emoji. - code: "170001002" message: Creator TikTok Shop permission check failed. - code: "170001005" message: Creator terms of service not signed. Please contact TikTok for more details. - code: "170001006" message: GKA terms not signed. Please try again after signing GKA term. - code: "170001007" message: Creator did not sign the EU data share agreement. - code: "170001008" message: Creator Age verification failed. Please verify age first. - code: "170001009" message: The product belongs to unsupported category. - code: "170001010" message: The commission plan gets failed or rejected. - code: "170001011" message: The product doesn't exist. - code: "170001012" message: The product is not available. - code: "170001013" message: Showcase SPU exceeds limit. - code: "170001014" message: Blocked by spam check. - code: "170001015" message: Blocked by TikTok Shop risk control. - code: "170001018" message: Get creator pay account error. Please verify the pay account first. - code: "170001019" message: The user has exceeded allocated daily quota for precheck resource - 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-video-precheck-task-202511 /affiliate_creator/202601/videos/precheck_tasks/{task_id}: get: operationId: getShoppableVideoPrecheckResult summary: Get Shoppable Video Precheck Result description: Retrieve the violation and, when enabled, good-quality check results for a video precheck task. If a returned check status is `PROCESSING`, call this API again later. If a check status is `FAIL`, review its `issues` field for the detected issues and suggested improvements. tags: - Affiliate creator parameters: - name: task_id in: path required: true description: task id from [Precheck Video Content](https://partner.tiktokshop.com/docv2/page/precheck-video-content-202511) schema: type: string responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/GetShoppableVideoPrecheckResultResponse" example: code: 0 data: precheck_task: id: "7493990579714164574" violation_check_result: status: FAIL issues: - risk: Pirated Content suggestions: Your video may include unoriginal content. Creating original content is essential for standing out from the crowd. good_quality_check_result: status: FAIL issues: - code: LOW_CONTENT_PROMOTIO suggestions: You can try to showcase the product from multiple perspectives. message: Success request_id: 202203070749000101890810281E8C70B7 x-tts-scenario: 4 x-tts-scopes: - Content Posting 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-shoppable-video-precheck-result-202601 /affiliate_creator/202603/videos: post: operationId: postShoppableVideo summary: Post Shoppable Video description: "Use this API to submit a shoppable video for publishing. When the submission succeeds, pass the returned video ID as the `video_id` path parameter to Get Shoppable Video Status (`GET /affiliate_creator/202509/videos/{video_id}/status`) to retrieve the posting status: `PROCESSING`, `SUCCESS`, or `FAIL`. If the status is `PROCESSING`, call the status API again later to check for a terminal status." tags: - Affiliate creator requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PostShoppableVideoRequest" example: video_info: file_id: v12d00gd0024d3nfqr7og65 title: Sample video title cover_uri: v12d00gd0024d3nfqr7og65oooiuuyy cover_timestamp_ms: 1000 music_id: "717294069642063456" product_link_info: product_id: "17294069642063424" title: Sample product anchor title responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/PostShoppableVideoResponse" example: code: 0 data: video: id: "7548431509997292816" message: Success request_id: 202203070749000101890810281E8C70B7 x-tts-scenario: 4 x-tts-scopes: - Content Posting x-tts-error-codes: - code: "16011007" message: Product link title should be no longer than 30 characters. - code: "16011009" message: Product link title contains offensive language. - code: "16011069" message: Product link title contains punctuation or emoji. - code: "170001002" message: Creator TikTok Shop permission check failed. - code: "170001003" message: Creator Tiktok Shop permission temporarily banned. - code: "170001004" message: Creator TikTok Shop permission is permanently banned. - code: "170001005" message: Creator terms of service not signed. Please contact TikTok for more details. - code: "170001006" message: GKA terms not signed. Please try again after signing GKA term. - code: "170001007" message: Creator did not sign the EU data share agreement. - code: "170001008" message: Creator Age verification failed. Please verify age first. - code: "170001009" message: The product belongs to unsupported category. - code: "170001010" message: The commission plan gets failed or rejected. - code: "170001011" message: The product doesn't exist. - code: "170001012" message: The product is not available. - code: "170001013" message: Showcase SPU exceeds limit. - code: "170001014" message: Blocked by spam check. - code: "170001015" message: Blocked by TikTok Shop risk control. - code: "170001018" message: Get creator pay account error. Please verify the pay account first. - code: "170001020" message: You have exceeded the frequency to post EC short videos. Please take a rest. - code: "170001024" message: cover_timestamp_ms must be a non-negative integer within the video duration. - code: "170001025" message: cover_timestamp_ms exceeds the video duration. - code: "170001030" message: Creator account banned. Please contact TikTok agent for your account. - code: "170001031" message: Creator forbidden to post content. - code: "170001040" message: Please use valid video file id to post TikTok Shop short video. - code: "170001050" message: Getting errors during video posting workflow. Please try again or contact TikTok. - code: "170001060" message: "Posting quota exceeded: the creator is under violation control, resulting in a reduced posting limit." - code: "170001061" message: "Posting quota exceeded: creator is in the newbie period." - code: "170001062" message: "Posting quota exceeded: platform-level posting limit reached." - code: "170001063" message: The product you added only supports auction sales and cannot be used in shoppable videos or Carousels. - code: "36009003" message: Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support. - code: "38007001" message: System Error x-tts-docs-url: https://partner.tiktokshop.com/docv2/page/post-shoppable-video-202603 /affiliate_creator/202606/toko_product_mappers: get: operationId: mapTokopediaToTikTokShopProductIDs summary: Map Tokopedia to TikTok Shop Product IDs description: Returns mappings from the specified Tokopedia product IDs to the corresponding TikTok Shop product IDs. tags: - Affiliate creator requestBody: content: application/json: schema: $ref: "#/components/schemas/MapTokopediaToTikTokShopProductIDsRequest" responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/MapTokopediaToTikTokShopProductIDsResponse" example: code: 0 data: error: code: 1 message: empty_product_id product: - toko_pid: 2177906740 tts_pid: 1735209287836402920 message: Success request_id: 202203070749000101890810281E8C70B7 x-tts-scenario: 4 x-tts-scopes: - Read Creator Affiliate Collaborations x-tts-error-codes: [] x-tts-docs-url: https://partner.tiktokshop.com/docv2/page/map-tokopedia-to-tiktok-shop-product-ids-202606 /affiliate_creator/202607/map_toko_product: post: operationId: getTokopediaAndTikTokShopProductIDMappings summary: Get Tokopedia and TikTok Shop Product ID Mappings description: Returns mappings from the specified Tokopedia product IDs to the corresponding TikTok Shop product IDs. tags: - Affiliate creator requestBody: content: application/json: schema: $ref: "#/components/schemas/GetTokopediaAndTikTokShopProductIDMappingsRequest" example: toko_pids: - 123456 responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/GetTokopediaAndTikTokShopProductIDMappingsResponse" example: code: 0 data: error: code: 1 message: empty_product_id product: - toko_pid: 2177906740 tts_pid: 1735209287836402920 message: Success request_id: 202203070749000101890810281E8C70B7 x-tts-scenario: 4 x-tts-scopes: - Read Affiliate Share Link x-tts-error-codes: [] x-tts-docs-url: https://partner.tiktokshop.com/docv2/page/get-tokopedia-and-tiktok-shop-product-id-mappings-202607 /affiliate_creator/202610/photos: post: operationId: postShoppablePhotos summary: Post Shoppable Photos description: Use this API to post the shoppable photos with uris and metadata. tags: - Affiliate creator requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PostShoppablePhotosRequest" example: photos_info: - photo_file_uris: tos-useast5-i-photomode-tx/owBwaPnAIiaYg4Ck6aNcAmLkBA14n8QQQGEgi music_id: "7577090708998212365" title: Post title link_info: post_type: "1" shop_info: shop_id: "7494831143334152261" group_type: "1" group_id: "6" links: - product_id: "74998589993939330" link_title: product A is_ai_generated: false responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/PostShoppablePhotosResponse" example: code: 0 data: photo: photo_post_id: "34234234234324342" quota: 3/day message: Success request_id: 202203070749000101890810281E8C70B7 x-tts-scenario: 4 x-tts-scopes: - Content Posting x-tts-error-codes: - code: "16011007" message: Product link title should be no longer than 30 characters. - code: "16011009" message: Product link title contains offensive language. - code: "16011069" message: Product link title contains punctuation or emoji. - code: "170001002" message: Creator TikTok Shop permission check failed. - code: "170001003" message: Creator Tiktok Shop permission temporarily banned. - code: "170001004" message: Creator TikTok Shop permission is permanently banned. - code: "170001005" message: Creator terms of service not signed. Please contact TikTok for more details. - code: "170001006" message: GKA terms not signed. Please try again after signing GKA term. - code: "170001007" message: Creator did not sign the EU data share agreement. - code: "170001008" message: Creator Age verification failed. Please verify age first. - code: "170001009" message: The product belongs to unsupported category. - code: "170001010" message: The commission plan gets failed or rejected. - code: "170001011" message: The product doesn't exist. - code: "170001012" message: The product is not available. - code: "170001013" message: Showcase SPU exceeds limit. - code: "170001014" message: Blocked by spam check. - code: "170001015" message: Blocked by TikTok Shop risk control. - code: "170001018" message: Get creator pay account error. Please verify the pay account first. - code: "170001020" message: You have exceeded the frequency to post EC short videos. Please take a rest. - code: "170001030" message: Creator account banned. Please contact TikTok agent for your account. - code: "170001031" message: Creator forbidden to post content. - code: "170001040" message: Please use valid video file id to post TikTok Shop short video. - code: "170001050" message: Getting errors during video posting workflow. Please try again or contact TikTok. - code: "170001060" message: "Posting quota exceeded: the creator is under violation control, resulting in a reduced posting limit." - code: "170001061" message: "Posting quota exceeded: creator is in the newbie period." - code: "170001062" message: "Posting quota exceeded: platform-level posting limit reached." - code: "170001063" message: The product you added only supports auction sales and cannot be used in shoppable videos or Carousels. - code: "36009003" message: Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support. - code: "38007001" message: System Error x-tts-docs-url: https://partner.tiktokshop.com/docv2/page/post-shoppable-photos-202610 /affiliate_partner/202405/campaigns: get: operationId: getAffiliatePartnerCampaignList summary: Get Affiliate Partner Campaign List description: Lists campaigns for an affiliate partner, filtered by campaign category, participation state, and campaign status. tags: - Affiliate partner parameters: - 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 - name: page_size in: query required: true description: "The number of campaigns to return per page. Valid 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. Maximum page size is `100` items. schema: type: string - name: status in: query required: false description: |- This parameter is required. The campaign status. The status is an enumerated type with values: - `READY` - `UPCOMING` - `ONGOING` - `CLOSED` - `UNSPECIFIED` schema: type: string - name: type in: query required: false description: |- The campaign type. This is an enumerated type with values: - MY_CAMPAIGNS - GS_SELLING_CAMPAIGNS - SELLER_CAMPAIGNS - EXCLUSIVE_TIKTOK_SHOP Default value is MY_CAMPAIGNS. schema: type: string - name: query_type_filter in: query required: false description: |- An additional filter whose valid values depend on `type`: - `SELLER_CAMPAIGNS`: `query_type_filter` is required. Set it to `MARKETPLACE` to include campaigns that the partner has not joined, or `JOINED` to include only campaigns that the partner has joined. When using `MARKETPLACE`, set `status` to `UNSPECIFIED`. - `EXCLUSIVE_TIKTOK_SHOP`: `query_type_filter` is required. Set it to `AVAILABLE` to include campaigns that the partner is permitted to join, or `JOINED` to include only campaigns that the partner has joined. For either value, set `status` to `UNSPECIFIED`. - `MY_CAMPAIGNS` or `GS_SELLING_CAMPAIGNS`: omit `query_type_filter` or set it to `DEFAULT`. schema: type: string responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/GetAffiliatePartnerCampaignListResponse" example: code: 0 data: campaigns: - id: "7360590375814268715" name: test status: READY registration_start_time: 1712941200 registration_end_time: 1713891599 campaign_start_time: 1712941200 campaign_end_time: 1715878799 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: "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-list-202405 post: operationId: createAffiliatePartnerCampaign summary: Create Affiliate Partner Campaign description: Creates an affiliate partner campaign for either specific sellers identified by shop code or eligible seller types. Configure the campaign period, seller registration period, commission rate, and contact information. When the campaign is created successfully, the operation returns the new `campaign_id` synchronously. The campaign is not displayed to sellers after creation. To publish a successfully created campaign, call `POST /affiliate_partner/202405/campaigns/{campaign_id}/publish` with the returned campaign ID. tags: - Affiliate partner parameters: - 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/CreateAffiliatePartnerCampaignRequest" example: name: my first campaign description: campaign for test campaign_start_time: 1712941200 campaign_end_time: 1715878799 registration_start_time: 1712941200 registration_end_time: 1713891599 commission_rate: 1000 contact_info: whatsapp: "+14255550100" email: 123456@gmail.com phone: "+14255550100" zalo: "+14255550100" viber: "+14255550100" line: "+14255550100" target_shop_codes: - THCBELNL4Y target_seller_types: - CROSS_BORDER responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/CreateAffiliatePartnerCampaignResponse" example: code: 0 data: campaign_id: "7356411663443183367" 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: "16032002" message: Invalid campaign period - code: "16032003" message: Invalid registration period - code: "16032004" message: Invalid campaign seller scope - code: "16032013" message: Payment account not yet activated x-tts-docs-url: https://partner.tiktokshop.com/docv2/page/create-affiliate-partner-campaign-202405 /affiliate_partner/202405/campaigns/{campaign_id}: get: operationId: getAffiliatePartnerCampaignDetail summary: Get Affiliate Partner Campaign Detail description: This API offers the ability to get affiliate campaign details. tags: - Affiliate partner parameters: - name: campaign_id in: path required: true description: The campaign ID in decimal integer format. 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/GetAffiliatePartnerCampaignDetailResponse" example: code: 0 data: id: "7356876895365105455" name: test_campaign description: Campaign for api test. status: READY region: US registration_start_time: 1712941200 registration_end_time: 1713891599 campaign_start_time: 1712941200 campaign_end_time: 1715878799 commission_rate: 1000 contact_info: whatsapp: "+14255550100" email: 123456@gmail.com phone: "+14255550100" zalo: "+14255550100" viber: "+14255550100" line: "+14255550100" target_shops: - code: THCBELNL4Y name: my_shop target_seller_types: - LOCAL 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-detail-202405 /affiliate_partner/202405/campaigns/{campaign_id}/partial_edit: post: operationId: editAffiliatePartnerCampaign summary: Edit Affiliate Partner Campaign description: Partially updates an Affiliate Partner campaign. Fields omitted from the request retain their current values, including omitted fields within `contact_info`. `target_seller_types` and `target_shop_codes` are mutually exclusive. To switch targeting modes, send the previously used field as an empty array and the new field with its values. Campaigns cannot be edited after they are closed. tags: - Affiliate partner parameters: - name: campaign_id in: path required: true description: The campaign ID in decimal integer format. 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/EditAffiliatePartnerCampaignRequest" example: name: test campaign description: campaign for api test. campaign_start_time: 1712941200 campaign_end_time: 1715878799 registration_start_time: 1712941200 registration_end_time: 1713891599 commission_rate: 1000 contact_info: whatsapp: "+14255550100" email: 123456@gmail.com phone: "+14255550100" zalo: "+14255550100" viber: "+14255550100" line: "+14255550100" target_shop_codes: - THCBELNL4Y target_seller_types: - CROSS_BORDER responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/EditAffiliatePartnerCampaignResponse" 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: "16032002" message: Invalid campaign period - code: "16032003" message: Invalid registration period - code: "16032004" message: Invalid campaign seller scope - code: "16032005" message: Campaign not found - code: "16032007" message: Permission denied - code: "16032008" message: Operation denied x-tts-docs-url: https://partner.tiktokshop.com/docv2/page/edit-affiliate-partner-campaign-202405 /affiliate_partner/202405/campaigns/{campaign_id}/products: get: operationId: getAffiliatePartnerCampaignProductList summary: Get Affiliate Partner Campaign Product List description: This API offers the ability to list products submitted by sellers in an Affiliate Partner campaign. tags: - Affiliate partner parameters: - name: campaign_id in: path required: true description: The numeric ID of an existing Affiliate Partner campaign. 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 - name: page_size in: query required: true description: The number of results to return per page. The value must be between 1 and 100. schema: type: integer format: int64 - 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: review_status in: query required: false description: |- The product review status. This an enumerated type with values: - PENDING - APPROVED - REJECTED - PENDING_CLOSED - CLOSED schema: type: string - name: product_name in: query required: false description: Filter the product list by product name. If value of `product_name` is contained in `product.name`, the product will be included in the response. schema: type: string - name: product_id in: query required: false description: Filter the product list by product ID. The value must be a numeric string. A product is included when this value matches `product.id`. schema: type: string - name: shop_name in: query required: false description: Filter the product list by shop name. If value of `shop_name` is contained in `product.shop_name`, the product will be included in the response. schema: type: string - name: category_id in: query required: false description: Filter the product list by category ID. If value of `category_id` matches `product.category.id`, or the product falls into the leaf category of the specified category, the product will be included in the response. schema: type: string responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/GetAffiliatePartnerCampaignProductListResponse" example: code: 0 data: products: - id: "1729442777527587334" review_status: PENDING name: test case number 4 test case number 4 main_image_url: https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/fa0387fa5a204dcfa44d5be75877a163~tplv-o3syd03w52-origin-webp.webp?from=3478900499 lowest_price: currency: USD amount: "1.1" highest_price: currency: USD amount: "12.21" inventory: 89 shop_name: my_shop total_commission_rate: 6600 creator_commission_rate: 1000 partner_commission_rate: 5600 open_collaboration_commission_rate: 1000 is_available: true product_sales: 10 category: id: "12222" name: COMPUTER sample_quota: 12 sku_information_list: - sku_name: factory product sku_id: "1729666531097281876" inventory: available_quantity: "80" base_price: region_code: MY currency: MYR list_price: "162.34" sale_price: "162.34" localized_dutiable_price: "141.58" region_prices: - region_code: MY currency: MYR list_price: "162.34" sale_price: "162.34" localized_dutiable_price: "141.58" properties: - name: Spesifikasi value_name: lalai product_description:

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 Possible values: - ASC: Ascending order - 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. Default: commission_rate Possible values: - commission_rate - product_sales_price - commission - 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. The 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 Valid 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. - If `false`, all fields in conversation` are returned. `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. Possible values: - `ALL`: Retrieve all conversations regardless of status. - `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. - `UNREPLIED`: Retrieve conversations in which the seller is not the last message sender. - `STARRED`: Retrieve conversations the seller starred. - `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. You 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. Enum: - ASC：means to sort data in ascending order - 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: - product_original_price: sort by products' original price. By 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. A 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 whatsapp: | (+62) 1234567890 telegram: | (+62) 1234567890 line: | (+62) 1234567890 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. - 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`. Supported campaign types: - `MY_CAMPAIGNS` - `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. 14 days maximum. 1 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. - CREATOR: Selects creator-list export tasks. - 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. Available values: - BASIC_CREATOR_INFORMATION: Basic creator profile information. - CONTENT_PERFORMANCE: Content performance metrics, Promotion Performance Score (PPS), fulfillment score, and promoted product count. - FOLLOWER_INFORMATION: Follower location, age, and gender distributions. - COLLABORATION: Collaborated brands and commission information. - 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. For 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. In 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. Available values: ALL, 1D Default value: ALL * ALL: aggregate * 1D: daily schema: type: string enum: - ALL - 1D - name: currency in: query required: false description: |- Currency. Available values: USD, LOCAL Default value: LOCAL * USD: US dollars * 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: - gmv (default) - sku_orders - 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: - DESC (default) - 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: - LIVE - INACTIVE - 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: - USD: U.S. dollars - 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. Available values: ALL, 1D Default value: ALL * ALL: aggregate * 1D: daily schema: type: string enum: - ALL - 1D - name: currency in: query required: false description: |- Currency: - USD: US dollars - 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. In the parameter name, "ge" refers to "greater than or equal to" (inclusive) The 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. In the parameter name, "lt" refers to "less than" (exclusive) The 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. Available values: ALL, 1D Default value: ALL * ALL: aggregate * 1D: daily schema: type: string enum: - ALL - 1D - name: currency in: query required: false description: |- Currently, only local currency is supported in the response. Available values: USD, LOCAL Default value: LOCAL * USD: US dollars * 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. In 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. Min value: 1 Max value: 100 Default value: 10 schema: type: integer format: int64 minimum: 1 maximum: 100 - name: sort_field in: query required: false description: |- Sort on. Available values: gmv, units_sold, daily_avg_buyers Default value: gmv schema: type: string enum: - gmv - units_sold - daily_avg_buyers - name: sort_order in: query required: false description: |- Sort direction. Available values: ASC, DESC Default value: DESC * ASC: ascending * DESC: descending schema: type: string enum: - ASC - DESC - name: currency in: query required: false description: |- Currency. Available values: USD, LOCAL Default value: LOCAL * USD: US dollars * 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. Leave 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. In 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. Available values: USD, LOCAL Default value: LOCAL * USD: US dollars * 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: - 1D — 1 day - 7D — 7 days - 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: - ALL — include all creator types - OFFICIAL — include official creators - CHANNEL — include channel creators - 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: - USD — US dollars - LOCAL — the local currency where the shop is registered If 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: - 1D: query data for 1 day - 7D: query data for 7 days - 30D: query data for 30 days This 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: - 1D — 1 day - 7D — 7 days - 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: - 1D: 1 day - 7D: 7 days - 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. Available values: ASC, DESC Default value: DESC * ASC: ascending * DESC: descending schema: type: string enum: - ASC - DESC - name: sort_field in: query required: false description: |- Field to sort on. Available values: - gmv - items_sold - customers - created_sku_orders - sku_orders - main_orders - product_impressions - product_clicks Default 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 WAHIDA KNITWEAR CARDIGAN (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. In 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. Max value: 100 Default 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. Leave this field empty for first time queries. schema: type: string - name: sort_field in: query required: false description: |- Field to sort on. Default: gmv Available values: - gmv - items_sold - orders schema: type: string enum: - gmv - items_sold - orders - name: sort_order in: query required: false description: |- Sort direction. Available values: ASC, DESC Default value: DESC * ASC: ascending * DESC: descending schema: type: string enum: - ASC - DESC - name: currency in: query required: false description: |- Currency. Available values: USD, LOCAL Default value: LOCAL * USD: US dollars * 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. Available values: - LIVE: live products - INACTIVE: inactive products - 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. In the parameter name, "ge" refers to "greater than or equal to" (inclusive) The 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. In the parameter name, "lt" refers to "less than" (exclusive). The 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. Minimum value: 1 Maximum value: 100 Default 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. Default value: gmv Available values: - gmv: sort by overall Gross Merchandise Value (GMV). - gpm: sort by average GMV generated from 1,000 views. - avg_customers: sort by daily average customers. - sku_orders: sort by paid SKU orders. - items_sold: sort by units sold. - views: sort by video views. - click_through_rate: sort by the ratio of product clicks to video views. - 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. Available values: ASC, DESC Default value: DESC * ASC: ascending * DESC: descending schema: type: string enum: - ASC - DESC - name: currency in: query required: false description: |- Currently, only local currency is supported in the response. Available values: USD, LOCAL Default value: LOCAL * USD: US dollars * 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. Leave 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. Available values: ALL, OFFICIAL_ACCOUNTS, MARKETING_ACCOUNTS, AFFILIATE_ACCOUNTS Default value: ALL - ALL: all account types - OFFICIAL_ACCOUNTS: official accounts - MARKETING_ACCOUNTS: marketing accounts - 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. Shop 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. Use 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. Shop 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. Use 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. Shop 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. Use 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. Shop 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. Use 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: - NRR: products with negative reviews (`nrr_top_product_items`). - NBFR: products with returns or refunds (`nbfr_top_product_items`). - OTDR: logistics providers and their on-time delivery performance (`otdr_logistics_items`). - 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. Shop 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. Use 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. In 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. In 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. Available values: ALL, 1D Default value: ALL * ALL: aggregate * 1D: daily schema: type: string enum: - ALL - 1D - name: currency in: query required: false description: |- Currently, only local currency is supported in the response. Available values: USD, LOCAL Default value: LOCAL * USD: US dollars * 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. In 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. In 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. The response will contain real-time metrics of today (local time) schema: type: boolean - name: granularity in: query required: false description: |- Granularity of the data. Available values: - ALL: Aggregate data for the full requested time range. - 1D: Daily data. Default 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. Available values: - USD: US dollars. - LOCAL: Local currency where the shop is located. Default 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. Available values: - ALL: All account types. - LINKED_ACCOUNTS: Linked accounts. - AFFILIATE_ACCOUNTS: Affiliate accounts. Default 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. In 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. In 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. Available values: - OFFICIAL_ACCOUNTS: Official accounts. - MARKETING_ACCOUNTS: Marketing accounts. - 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. Max value: 100 Default value: 10 schema: type: integer format: int64 maximum: 100 - name: sort_field in: query required: false description: |- Field to sort on. Default: live_attributed_gmv Available values: - live_attributed_gmv - products_added - products_sold - live_attributed_sku_orders - live_attributed_items_sold - 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. Available values: - ASC: Ascending order. - DESC: Descending order. Default value: DESC schema: type: string enum: - ASC - DESC x-enum-descriptions: - Ascending order. - Descending order. - name: currency in: query required: false description: |- Currency. Available values: - USD: US dollars. - LOCAL: Local currency where the shop is located. Default 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. Leave 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. In the parameter name, "ge" refers to "greater than or equal to" (inclusive) The 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. In the parameter name, "lt" refers to "less than" (exclusive) The 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. Available values: ALL, 1D Default value: ALL * ALL: aggregate * 1D: daily schema: type: string enum: - ALL - 1D - name: currency in: query required: false description: |- Currently, only local currency is supported in the response. Available values: USD, LOCAL Default value: LOCAL * USD: US dollars * 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. In 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. In 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. The response will contain real-time metrics of today (local time) schema: type: boolean - name: granularity in: query required: false description: |- Granularity of the data. Available values: ALL, 1D Default value: ALL * ALL: aggregate * 1D: daily schema: type: string enum: - ALL - 1D - name: currency in: query required: false description: |- Currently, only local currency is supported in the response. Currency. Available values: USD, LOCAL Default value: LOCAL * USD: US dollars * 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. Available values: - ALL: All account types. - OFFICIAL_ACCOUNTS: Official accounts. - MARKETING_ACCOUNTS: Marketing accounts. - AFFILIATE_ACCOUNTS: Affiliate accounts. Default 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. Seller 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. For more information about seller authorization, refer to [Seller authorization guide](https://partner.tiktokshop.com/docv2/page/678e3a344ddec3030b238fa0). Target 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. Partner 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. For more information about partner authorization, refer to [Partner authorization guide](678e3a3978f4c20311b8b555). Target 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. Note 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. **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. Refer 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. Note 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. 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/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. For 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). Possible enumerations: - de-DE (German, Germany) - en (English) - en-GB (English, United Kingdom) - es-ES (Spanish, Spain) - es-MX (Spanish, Latin America) - fr-FR (French, France) - id-ID (Indonesian, Indonesia) - it-IT (Italian, Italy) - ja-JP (Japanese) - ms-MY (Malay, Malaysia) - th-TH (Thai, Thailand) - vi-VN (Vietnamese, Vietnam) - pt-BR (Portuguese, Brazil) - 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. Calling 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. For 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). Possible enumerations: - de-DE (German, Germany) - en (English) - en-GB (English, United Kingdom) - es-ES (Spanish, Spain) - es-MX (Spanish, Latin America) - fr-FR (French, France) - id-ID (Indonesian, Indonesia) - it-IT (Italian, Italy) - ja-JP (Japanese) - ms-MY (Malay, Malaysia) - th-TH (Thai, Thailand) - vi-VN (Vietnamese, Vietnam) - pt-BR (Portuguese, Brazil) - 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. Possible enumerations: - DESC(default) - 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: - `create_time` (default) - `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. 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: - Product ID: 1732529206731441911; - 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; - Product price: ; - Strike-through price: - Sold: 40013. View 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. Valid 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 Refer 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. Valid 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. Valid range: [1-100]. Pagination 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. Cancellation is rejected for target consign orders that have reached `SHIPPED`, `HANDOVER`, `COMPLETED`, or a shipping-exception state such as `LOST`, `DAMAGE`, `RETURNED`, or `SCRAP`. After 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. For 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. **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. Only 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. You 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. **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. **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. **Format applicability** * `carton_label_format` controls the carton or pallet label layout only when `print_items` includes `CARTON_PALLET_LABEL`. * `barcode_format` controls the goods-barcode label layout only when `print_items` includes `FBT_BARCODE`. The selected `print_items` and both resolved format values are part of the print task identifier, so keep the same selections in every polling request. **Workflow** 1. **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. 2. **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. 3. **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. The 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. Valid 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). Applicable 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. Refer 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. Possible values: - PAID: Payment has been transferred to the seller. - FAILED: Payment transfer failed. - PROCESSING: Payment is currently being processed. Default: 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. Default: 20 Valid 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. Default: ASC Possible values: - ASC: Ascending order - 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. **Note:** `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. - If `statement_time_ge` is provided but `statement_time_lt` is omitted, `statement_time_lt` defaults to the current time. - If `statement_time_lt` is provided but `statement_time_ge` is omitted, `statement_time_ge` defaults to the earliest shop time. **Example:** Statements 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)`: - Set `statement_time_ge` to `1777420800` (inclusive). - 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. Possible values: - WITHDRAW: The seller withdraws the settlement amount to a bank card. - SETTLE: The platform settles the amount to the seller. - TRANSFER: A platform subsidy or deduction due to platform policies. - REVERSE: A withdrawal failure caused by incorrect bank card information. - PAYMENT: A payment transaction. - 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. Applicable 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). Applicable 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. Default: ASC Possible values: - ASC: Ascending order - 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: 20 Valid 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. For 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. **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. Default: 20 Valid 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. Default: ASC Possible values: - ASC: Ascending order - 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 specified 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.** Retrieves records of automated payments for a shop based on a specified date range. Use 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. Refer 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. Default: 20 Valid 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. Default: ASC Possible values: - ASC: Ascending order - 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. **Note:** `create_time_ge` and `create_time_lt` together constitute the creation time filter condition. - If `create_time_ge` is filled but `create_time_lt` is empty, `create_time_lt` will default to the current time. - 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. The 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. The supplier identity and associated seller identity are resolved from the authorization context. The caller cannot specify seller_id. Only 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). This API only supports uploading qualification files in `PDF` format. The file size can not exceed 10MB. Note: 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. Usage requirements: - The image format must be `JPEG`, `PNG`, or `JPG`. - 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. - 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. - 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). Please 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: - Some regions support item-level splits (splitting individual units of the same SKU). - Others only support all-units splits (splitting different SKUs into separate packages). Here are two examples of supported splits: - **Case 1: all-units split**, applicable for orders in BR, SEA, MX (local sellers) Split a buyer order of SKU A of quantity 2 and SKU B of quantity 1 into two separate packages: - **Package 1**: all units of SKU A - **Package 2**: all units of SKU B - **Case 2: item-level split**, applicable for orders in EU, JP, MX (global sellers), UK, US Split the same order contents into three individual packages: - **Package 1**: 1 unit of SKU A - **Package 2**: 1 unit of SKU A - **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! 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. Default: `create_time` Possible values: - `create_time` - `update_time` - `order_pay_time` Specify 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` Possible values: - `ASC`: Ascending order - `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. - `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. - `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). - `In-store Pickup`: Confirm shipment and notify the buyer that the order is ready for pickup. A 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 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 phone_number: | (+1)213-***-1234 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 sender_address: full_address: 1*** Coleman Ave San Jose, CA 95110 phone_number: | (+1)213-***-1234 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`. - `TikTok Shipping`: Schedule a package handover time for TikTok Shipping carriers to pickup a package from seller. - `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). - `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: - `SHIPPING_LABEL`: Returns the shipping label in PDF format by default. - `PACKING_SLIP`: Returns the packing slip in PDF format by default. - `SHIPPING_LABEL_AND_PACKING_SLIP`: Returns both the shipping label and the packing slip for the package, both in PDF format by default. - `SHIPPING_LABEL_PICTURE`: Returns the shipping label in PNG format. - `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`. - `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. If you specify `SHIPPING_LABEL_PICTURE` for the `document_type`, any value specified in the `document_size` will be ignored. Possible values: - `A6` (Default) - `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. Possible values: - PDF (Default) - ZPL (Only for BR and MX market) **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. Possible values: - DEFAULT (Default) - 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. ) 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. **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). Available 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. If 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.** This 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.** This 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. - `WAREHOUSE`: Returns the delivery options currently active for the warehouse. Orders use these options by default. - `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`. Default: `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. For 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. For 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. Get 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. 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/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 Possible values: - ASC: Ascending order - 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. Default: `create_time` Possible values: - `create_time` - `update_time` Specify 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). Possible values: - SHOPIFY - WOOCOMMERCE - BIGCOMMERCE - MAGENTO - SALESFORCE_COMMERCE_CLOUD - CHANNEL_ADVISOR - AMAZON - ORDER_MANAGEMENT_SYSTEM - WAREHOUSE_MANAGEMENT_SYSTEM - 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). Possible values: - SHOPIFY - WOOCOMMERCE - BIGCOMMERCE - MAGENTO - SALESFORCE_COMMERCE_CLOUD - CHANNEL_ADVISOR - AMAZON - ORDER_MANAGEMENT_SYSTEM - WAREHOUSE_MANAGEMENT_SYSTEM - 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. Max 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. - To check if a brand is fully authorized for use in a specific product category, specify the **category ID**. - 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. **Key concept** Whether 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). **- Brand selection rules**: You can only select the following types of brands during product creation/editing. - Authorized brands which contain the desired category (`authorized_status=AUTHORIZED` and `brand_status=AVAILABLE`) - Unauthorized non-T1 brands (`authorized_status=UNAUTHORIEZD` and `is_t1_brand=false`) **- 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. **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. **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. Possible values: - 1: Returns only authorized brands - 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. Valid 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: - US, EU and SEA: v2, represents the 7-level category tree. Important: For US, EU and SEA shops, you must pass v2 when using this API. - 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. Authorization 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. **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. Product 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. **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. Default: The default locale of your shop. Possible values: - `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` 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: - US, EU and SEA: v2, represents the 7-level category tree. Important: For US, EU and SEA shops, you must pass v2 when using this API. - 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. Possible values: - TIKTOK_SHOP - TOKOPEDIA Default: TIKTOK_SHOP Applicable 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. Applicable only for BR, MX, EU and SEA markets. schema: type: boolean - name: is_live_quick in: query required: false description: |- false — NORMAL products true — LIVE_QUICK products. Only seller with the required permissions can creat LIVE_QUICK products. Default: 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. If you are syncing product catalogs from an external system to TikTok Shop, use this API to facilitate product categorization. **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.

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. Products 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. - **Sales attributes** (e.g. size, color, length) define product variants and are optional if your product is straightforward and has no variants. - **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. Use this API to determine the mandatory and optional attributes before listing a product. **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. Default: The default locale of your shop. Possible values: - `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` 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: - US, EU and SEA: v2, represents the 7-level category tree. Important: For US, EU and SEA shops, you must pass v2 when using this API. - 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 true — LIVE_QUICK products. Only seller with the required permissions can creat LIVE_QUICK products. Default: 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. Products 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. - **Sales attributes** (e.g. size, color, length) define product variants and are optional if your product is straightforward and has no variants. - **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. Use this API to determine the mandatory and optional attributes, including market-specific requirements, before listing a global product. **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. Default: The default locale of your shop. Possible values: - `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` 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: - US, EU and SEA: v2, represents the 7-level category tree. Important: For US, EU and SEA shops, you must pass v2 when using this API. - 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. Use this API to determine the supporting information that you must prepare before listing a global product. **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: - US, EU and SEA: v2, represents the 7-level category tree. Important: For US, EU and SEA shops, you must pass v2 when using this API. - 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. Default: The default locale of your shop. Possible values: - `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` 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. Use this API to determine the supporting information that you must prepare before listing a product. **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: - US, EU and SEA: v2, represents the 7-level category tree. Important: For US, EU and SEA shops, you must pass v2 when using this API. - 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. Default: The default locale of your shop. Possible values: - `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` 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. Where 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. Use 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. **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 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. Product 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. Default: The default locale of your shop. Possible values: - `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` 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: - US, EU and SEA: v2, represents the 7-level category tree. Important: For US, EU and SEA shops, you must pass v2 when using this API. - 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. If you are syncing product catalogs from an external system to TikTok Shop, use this API to facilitate product classification. **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.

\ \ \ " 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. You 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. **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. **Note**: - 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. - 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. - 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 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 value_name: Red sku_img: uri: | tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe 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 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 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. **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. **Note**: - 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. - 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. - 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 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. **Note**: - 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 - Use the [Get Product API](6509d85b4a0bb702c057fdda) to obtain the converted local product information in the target market's language. - 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. **Note**: - 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. - 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 `` tag. tags: - Products requestBody: required: true content: multipart/form-data: schema: $ref: "#/components/schemas/UploadProductImageRequest" responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/UploadProductImageResponse" example: code: 0 data: uri: tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe url: | https://p-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe height: 720 width: 720 use_case: MAIN_IMAGE message: Success request_id: 202203070749000101890810281E8C70B7 x-tts-scenario: 2 x-tts-scopes: - Product Basic x-tts-error-codes: - code: "11050001" message: invalid param - code: "12019116" message: The image dimensions exceed the allowed limits. - 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: "12038014" message: "The image dimensions exceed the allowed limits. Allowed dimensions (width x height in pixels): {{min_width}} x {{min_height}} to {{max_width}} x {{max_height}}" - code: "12038015" message: "Failed to process the image. The format or content is not supported. Supported formats: {{formats}}" - 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-image-202309 /product/202309/inventory/search: post: operationId: inventorySearch summary: Inventory Search description: |- Retrieve inventory information for multiple products or SKUs. **Note**: - If both `sku_ids` and `product_ids` are passed, `sku_ids` takes precedence and `product_ids` is ignored. - Passing product IDs returns the inventory information of all SKUs under the specified products. - Passing SKU IDs returns the inventory information for the specified SKUs. tags: - Products parameters: - $ref: "#/components/parameters/ShopCipher" requestBody: content: application/json: schema: $ref: "#/components/schemas/InventorySearchRequest" example: product_ids: - "1729592969712207008" sku_ids: - "1729388324987897824" responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/InventorySearchResponse" example: code: 0 data: inventory: - product_id: "1729592969712207008" skus: - id: "1729388324987897824" seller_sku: Color-Red-XM01 total_available_quantity: 100 total_committed_quantity: 10 warehouse_inventory: - warehouse_id: "7054915283043174149" available_quantity: 100 committed_quantity: 10 total_available_inventory_distribution: campaign_inventory: - quantity: 30 campaign_name: Big Sale creator_inventory: - quantity: 20 creator_name: py001 in_shop_inventory: quantity: 50 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: "12019008" message: Product id is invalid - code: "12019015" message: The number of SKU exceed the limit - code: "12019022" message: SKU must contain a valid warehouse. - code: "12019112" message: seller id is invalid - code: "12019114" message: Seller has no permission - code: "12019120" message: The number of provided product IDs 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/inventory-search-202309 /product/202309/products: post: operationId: createProduct summary: Create Product description: |- Create and list products intended for sale exclusively in local shops. You can create products in `AVAILABLE` categories. (US sellers can also create products in INVITE_ONLY categories). After creation, it will be sent for audit review by TikTok Shop. Use the [Product status change](https://partner.tiktokshop.com/docv2/page/650956aff1fd3102b90b6261) webhook to keep track of the review status. **Note**: - This API is applicable for all sellers. - Global sellers who have migrated to use the local replication listing method can use this API to create products. Otherwise, they can continue to use the [Create Global Product API](6509de61bace3e02b7489cba) to create global products. - Before calling this API, we recommend that you prepare the necessary information by following the [usage flow for your region](650b23eef1fd3102b93d2326). - 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. Refer to TikTok Shop Academy for details on the limit. - 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" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateProductRequest" example: save_mode: LISTING description: |2-

Please check the measurements before purchase.

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. **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. After 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. In 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. Every 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. **Note**: - 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.) A 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. Default: 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.

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 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. - True: Retrieves the latest version of the product information that is currently under review. - False: Retrieves a snapshot of the product information that is live and online (before the edit). Default: 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. - True: Retrieves the draft version of the product information. - False: Retrieves the latest product information. Default: False **Note**: - Applicable only if the product is in the `DRAFT`, `ACTIVATE`, `SELLER_DEACTIVATED`, or `PLATFORM_DEACTIVATED` status. - 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. Default: The default locale of your shop. Possible values: - 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 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.

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: |- Botol & 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: - Inventory is automatically allocated and cannot be modified manually - Warehouse IDs provided are incorrect - 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. **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. Valid 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. Each 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. **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. This is especially useful for images displayed in the product image gallery as it enhances product visibility. **Note**: - 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. - Images that were previously optimized will not be processed again. - 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: - Listing quality information (available only for the US market). - Issues with the current product details and the overall recommendations - Auto-generated optimization suggestions targeted for specific product fields, including the title, description, and image. **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. **Note**: - Max number of IDs: 200 - 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. Applicable 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. - Max IDs: 20 - 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. - Max IDs: 20 - 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. The 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". **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. Valid 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. Default: The default locale of your shop. Possible values: - 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 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. - Use the [Search Manufacturers API](67066a580dcee902fa03ccf9) to obtain the translations. - Use the [Partial Edit Manufacturer API](67066a55c55b3a03044eea29) to edit the translations, if necessary. - When creating a product, pass the returned `manufacturer_id` to associate the product with the manufacturer. Target 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. Target seller: Local sellers operating in EU countries **Note**: - The manufacturer name, registered trade name, email address, local phone number, and the address field must not contain Chinese characters. - 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. `name`, `email`) 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. 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. - Use the [Search Responsible Persons API](67066a55f17b7d02f95d2fb1) to obtain the translations. - Use the [Partial Edit Responsible Person API](67066a5587019802fdce19b3) to edit the translations, if necessary. - When creating a product, pass the returned `responsible_person_id` to associate the product with the responsible person. Target 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. Target seller: Local sellers operating in EU countries **Note**: - 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. `name`, `email`) 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. 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: - Listing quality information (available only for the US market). - Issues with the current product details and the overall recommendations - Auto-generated optimization suggestions targeted for specific product fields, including the title, description, and image. This API enables you to diagnose both live products (status: `ACTIVATE`) and brand-new products not yet listed in TikTok Shop. - To diagnose a **live product**, provide the `product_id` and `category_id` and leave all other product details blank. - To diagnose a **brand-new product** not yet listed in TikTok Shop, omit the `product_id` and provide the product details as necessary. - 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. **Note**: - To diagnose multiple live products, use the [Product Information Issue Diagnosis API](665048f380b6b302e73917d9). - 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.

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 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. When 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`. Target 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. Valid 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. When 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`. Target 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. Valid 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. This 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. Valid 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. Applicable only for sellers that sell across EU. Use 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. **Note**: - Please wait 5 minutes after task creation before calling the Get endpoint, and retry at intervals over 10 seconds to avoid rate limiting. - Each task corresponds to the translation of 1 image into 1 target language. - 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. **Note**: Please wait 5 minutes after [task creation](684f8b2d6e0b37048b2448b4) before calling this API, and retry at intervals over 10 seconds to avoid rate limiting. Applicable 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. Max 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. **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. Applicable 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 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. After 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. **Note**: - This API is applicable only for **active sellers/shops** that have completed the KYC onboarding process. - 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. - 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. - 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). - 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. **For global sellers**: If you're using the local replication listing method, note the following sync rules: - To sync any changes to other markets, please provide the `seller_sku` and complete `replicated_products` data. - 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. **For Tokopedia sellers**: Note 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: - **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. - **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: |2-

Please compare above detailed size with your measurement before purchase.

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 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: - Inventory is automatically allocated and cannot be modified manually - Warehouse IDs provided are incorrect - 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. After 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. **Note**: - This API is applicable for all sellers. - 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. - If a draft or audit-review version exists, unedited fields will retain their values over those of the base (live) version. - **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. - If new mandatory product attributes were added by TikTok Shop after the creation of your product, ensure that you provide these attributes too. **For global sellers**: If you're using the local replication listing method, note the following sync rules: **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. **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. **General changes** are optional to sync to other markets. To sync, you only need to provide `replicated_products.region`. **For Tokopedia sellers**: Note 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: - **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. - **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: - 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. - 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. Get 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. Retrieve 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. Valid 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.

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. Valid 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 Initiates an appeal process for a product that was blocked during the listing phase due to a size chart verification failure. This 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: 1. Whether the size chart contains all mandatory dimensions. 2. Whether the size chart covers all Stock-Keeping Units (SKUs) for sale. 3. Whether the numerical values within the size chart are valid. If 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. Use 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. Note: - Please wait at least 5 minutes after submitting an appeal before checking its status via the API to ensure the data is synchronized. - 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. If 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. After 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. Default: The default locale of your shop. Possible values: - en - en-GB - zh-CN - de-DE - id-ID - it-IT - ja-JP - ms-MY - pt-BR - th-TH - 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. Default: The default locale of your shop. Possible values: - en - en-GB - zh-CN - de-DE - id-ID - it-IT - ja-JP - ms-MY - pt-BR - th-TH - 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. Do 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. Submitted 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: - For fixed-price, direct-discount, and flash-sale activities, update title, begin_time, and end_time; the other type-specific fields are not processed by this update path. - For a shipping-discount activity, provide discount.shipping_discount; use duration_type to choose a scheduled or indefinite activity. - For a Buy More Save More (BMSM) or Buy X Get Y (BXGY) activity, set duration_type to NORMAL, set product_level to PRODUCT or SHOP, provide exactly one participation_limit entry, and provide the matching discount object. - For a Gift With Purchase (GWP) activity, set duration_type to NORMAL, set product_level to PRODUCT, provide exactly one participation_limit entry, and provide discount.gift_discount. Fixed-price, direct-discount, flash-sale, BMSM, BXGY, and GWP activities cannot be updated after they are deactivated or expired. For those activity types, an upcoming activity with a normal schedule requires a future begin_time, while an ongoing activity must keep its existing begin_time. An ongoing BMSM or BXGY activity must also keep its existing first-tier threshold value, threshold type, discount type, product scope, participation limit, and target-user setting. 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: - For a `FIXED_PRICE`, `DIRECT_DISCOUNT`, or `FLASHSALE` activity with PRODUCT or VARIATION scope, provide a non-empty `products` array. For VARIATION scope, add or update SKUs in each product's `skus` array. - For a PRODUCT-scoped `SHIPPING_DISCOUNT` or `GIFT_WITH_PURCHASE` activity, provide a non-empty `products` array. A SHOP-scoped shipping-discount activity is not supported by this operation, and this operation does not document nested-SKU updates for shipping-discount or Gift With Purchase. - For a PRODUCT-scoped `BUY_MORE_SAVE_MORE` or `BUY_X_GET_Y` activity, `products` can be omitted or empty when the request updates only benefit-product relations. - For a SHOP-scoped `BUY_MORE_SAVE_MORE` or `BUY_X_GET_Y` activity, omit `products` or pass an empty array; use `benefit_product_ids` or `exclude_product_ids` for the applicable relation update. For an ongoing flash deal, you can add products or SKUs, but you cannot change the price or purchase limits of products or SKUs already in the activity. To remove products or SKUs, use [Remove Activity Product](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. - When removing ordinary activity products from a PRODUCT-scoped activity, use `product_ids` and do not provide `sku_ids`. - When removing ordinary activity products or SKUs from a VARIATION-scoped activity, use `product_ids`, `sku_ids`, or both. - For `GIFT_WITH_PURCHASE`, provide a non-empty `product_ids` list; the other removal lists are not processed by its branch. - For `BUY_MORE_SAVE_MORE` or `BUY_X_GET_Y`, `benefit_product_ids` removes benefit-product relations without requiring `product_ids`. - For a SHOP-scoped `BUY_MORE_SAVE_MORE`, `BUY_X_GET_Y`, or `SHIPPING_DISCOUNT` activity, `exclude_product_ids` removes excluded-product relations. You 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 status: |+ NOT_START 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 status: |+ NOT_START 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. If 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. 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: 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 Refer 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 Refer 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.) Possible values: - RMA - 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: - `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` **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 Refer 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. **Default:** `create_time` Possible values: - `create_time` - `update_time` Specify 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` Possible values: - `ASC`: Ascending order - `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: [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. Default: SELLER Possible values: - SELLER - 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: -`CANCEL` -`REFUND` -`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. **Default**: `create_time` Possible values: - `create_time` - `update_time` Specify 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` Possible values: - `ASC`: Ascending order - `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` Refer 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` Refer 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 Refer 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: - `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` **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. You 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. Target 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. This webhook will only be triggered when all the following conditions are met: * Your App has been authorized the` Promotion Information` scope. * The activities are of the following types: * `FIXED_PRICE` * `DIRECT_DISCOUNT` * `SHIPPING_DISCOUNT` * `BUY_MORE_SAVE_MORE` * `FLASHSALE` (Only available in SEA markets: SG, TH, ID, MY, PH, VN) * One of the following status changes happens: * The activity starts: the status changes from `NOT_START` to `ONGOING`. * The activity expires: the status changes from `ONGOING` to `EXPIRED`. * 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: 1. Buyer submits a return request in their TikTok user app. 2. A seller makes a decision on whether to approve or reject the request. > **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: * An order cancellation is initiated: `CANCELLATION_REQUEST_PENDING` * An order cancellation is accepted by the `SELLER` or `SYSTEM`: `CANCELLATION_REQUEST_SUCCESS` * An order cancellation is closed by the `BUYER` or `SYSTEM`: `CANCELLATION_REQUEST_CANCELLED` * 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. **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. > 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. > 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. > 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. **Applicable only for global sellers.** **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. **Applicable only for global sellers.** **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. > 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. Applicable only for sellers that sell across EU. **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. > 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. **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). The following events trigger this webhook when they cause an inventory quantity change: | Trigger source | Description | | --- | --- | | `order_created` | An order is successfully placed, and inventory is committed to the order. | | `order_canceled` | A buyer or seller cancels an order, and the committed inventory is released back to available stock. | | `order_shipped` | An order is shipped, and the committed inventory is deducted. | | `manual_adjustment` | A seller manually adjusts inventory in Seller Center. | | `api_sync` | A developer updates inventory through an inventory-related OpenAPI. | | `campaign_lock` | A seller joins a platform marketing campaign, and inventory is locked for the campaign. | | `campaign_unlock` | A marketing campaign ends or a seller withdraws, and the locked inventory is released. | | `creator_lock` | A seller allocates exclusive inventory to a creator collaboration. | | `creator_unlock` | A creator collaboration ends, and the locked inventory is released. | | `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: * The `current_inventory_status` has dropped to LOW_STOCK / OUT_OF_STOCK. * TikTok Shop predicts the `available_quantity` will drop to `0` in X days. > 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. **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. We 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. **Prerequisite**: The "Product Opportunities" API scope is enabled in Partner Center. For more information, refer to [Access Scope](access-scope). 📌 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. With this webhook, you can easily get the audit status information of a product instead of calling [Get Product](get-product) API. To 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. This 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. **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. **Note:** Applicable only for Brazil (**BR**) and Mexico (**MX**) markets. **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: * Product passes the first audit: `PRODUCT_FIRST_PASS_REVIEW` * Product status changes by platform: `PRODUCT_STATUS_CHANGED` * 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: * The `BUYER` initiates a return or refund request and is pending `SELLER` review: `RETURN_OR_REFUND_REQUEST_PENDING` * The `SELLER` declines the `BUYER`'s return or refund request: `REFUND_OR_RETURN_REQUEST_REJECT` * 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. * 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` * The `SELLER` declines the refund request for the return: `REJECT_RECEIVE_PACKAGE` * The `SELLER` accepts the refund request or issues a refund for the return: `RETURN_OR_REFUND_REQUEST_SUCCESS` * The `BUYER` or `SYSTEM` closes the return or refund request: `RETURN_OR_REFUND__REQUEST_CANCELLED` * The return or refund is successful: `RETURN_OR_REFUND_REQUEST_COMPLETE` Additionally, a `BUYER` may request an identical replacement item instead of a refund: * The `BUYER` initiates a replacement request and is pending `SELLER` review: `REPLACEMENT_REQUEST_PENDING` * The `SELLER` declines the `BUYER`'s replacement request: `REPLACEMENT_REQUEST_REJECT` * The `SELLER` decides to issue a refund to the `BUYER` without replacement: `REPLACEMENT_REQUEST_REFUND_SUCCESS` * The `BUYER` cancels the replacement request: `REPLACEMENT_REQUEST_CANCEL` * 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: 1. RMA is created 2. The RMA package is delivered and is pending the seller to review items to make a refund **decision.** 3. The RMA items review and refund decision is completed. > **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. > 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. **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. Typical scenarios include: * A new SKU is added under an existing product. * An existing SKU is deleted from an existing product. * An existing SKU is activated. * An existing SKU is deactivated. **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. Prerequisite: 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. **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. Max 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. Possible values: - TOKOPEDIA - TIKTOK_SHOP Default: TIKTOK_SHOP Applicable 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. * CREATE * UPDATE * 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. 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. 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: * `FIXED_PRICE` * `DIRECT_DISCOUNT` * `SHIPPING_DISCOUNT` * `BUY_MORE_SAVE_MORE` * `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: * `PRODUCT` * `VARIATION` * `SHOP` status: type: string enum: - ONGOING - EXPIRED - DEACTIVATED description: |- The current status of the promotion activity. Possible values are: * `ONGOING` * `EXPIRED` * `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. Possible values: - SHOPIFY - WOOCOMMERCE - BIGCOMMERCE - MAGENTO - SALESFORCE_COMMERCE_CLOUD - CHANNEL_ADVISOR - AMAZON - ORDER_MANAGEMENT_SYSTEM - WAREHOUSE_MANAGEMENT_SYSTEM - ERP_SYSTEM Notes: - 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. - 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: - PRODUCT_ID - 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. Max 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.) An optional secondary line for additional address details, if necessary. Max 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.) The district name. Max 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.) The city name. Max length: 500 characters deprecated: true postal_code: type: string maxLength: 500 description: |- The postal code. Max 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.) The province, state, or region name. Max 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: * `BUYER` * `SELLER` aftersales_request_status: type: string enum: - PENDING_REQUEST_REVIEW - REQUEST_REVIEW_COMPLETED description: |- Current aftersales request status. Possible enumerations: * `PENDING_REQUEST_REVIEW` * `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: - 18-24 - 25-34 - 35-44 - 45-54 - 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: - `APPROVE_REFUND`: seller approve a refund-only request - `APPROVE_RETURN`: seller approve the initial return-and-refund request - `APPROVE_RECEIVED_PACKAGE`: seller approve return-and-refund request after the buyer has already shipped or handed over the item. - `APPROVE_REPLACEMENT`: seller approve replacement request - `ISSUE_REPLACEMENT_REFUND`: seller decline the replacement request and directly refund the buyer instead. - `OFFER_PARTIAL_REFUND`: seller offers a partial refund amount to the buyer without requiring the item(s) to be returned. - `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. Supports two decimal places. rotate_degree: type: string description: |- The rotation angle of the customizable area, in degrees. Supports two decimal places. width: type: string description: |- The width of the customizable area. Supports two decimal places. x_coordinate: type: string description: |- The X-coordinate of the customizable area's starting point on the surface. Supports two decimal places. y_coordinate: type: string description: |- The Y-coordinate of the customizable area's starting point on the surface. Supports two decimal places. AreaScope: type: object properties: type: type: string description: |- The (buyer's) geographical area to which the promotion activity applies. ​- `WHOLE`: Promotion activity applies to all areas to which the seller offers fulfillment. - `SPECIFIC_AREAS`: Only applies to specific fulfillment areas, as defined in `area_scope.specific_areas` 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: - `PICKUP`: A shipping provider will pickup the package(s) from the seller's pickup address. - `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 Possible values: LITHIUM_ION LITHIUM_METAL OTHER battery_packaging_type: type: string enum: - STANDALONE - IN_EQUIPMENT - WITH_EQUIPMENT - OTHER description: |- Battery packaging type. Possible values: - STANDALONE - IN_EQUIPMENT - WITH_EQUIPMENT - 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. **Possible values:** * `KILOGRAM` (kg) * `GRAM` (g) * `MILLIGRAM` (mg) * `POUNDS` (lbs) * `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. **Possible values:** * `METER` (m) * `CENTIMETER` (cm) * `MILLIMETER` (mm) * `FOOT` (ft) * `MICRON` (μm) * `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. Possible values: - `MINIMAL_ITEM_QUANTITY`: The buyer must purchase at least the configured quantity of eligible products. - `MINIMAL_ORDER_AMOUNT`: The eligible-product subtotal must reach the configured amount. threshold_value: type: string description: |- The purchase threshold determined by `threshold_type`. - When `threshold_type==MINIMAL_ITEM_QUANTITY`, enter a positive integer no greater than `10`. - When `threshold_type==MINIMAL_ORDER_AMOUNT`, enter a positive eligible-product subtotal in local currency, with at most two decimal places. 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. Possible values: - PERCENTAGE_OFF: Apply the percentage specified by discount_value to eligible products. - FREE: Provide the configured quantity of eligible products for free. - AMOUNT_OFF_EACH: Deduct the local-currency amount specified by discount_value from each eligible product. discount_value: type: string description: |- Value of the discount. - When `type`==`PERCENTAGE_OFF`, the buyer will receive X% off the price of eligible products. If the value represents a percentage, it should be an integer. - `type`==`AMOUNT_OFF_EACH`, the buyer will receive X units of local currency off the price of each eligible products. If the value represents a monetary amount, it should be limited to two decimal places. 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 - CANCEL - REFUND - RETURN_AND_REFUND Note: 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: - `PLATFORM` - `BUYER_ARRANGE` handover_method: type: string description: |- Which handover method buyer chooses to use when returning goods to seller by platform - `DROP_OFF`: buyer drops off the parcel in logistics service collect point. - `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. Possible Status Enumerations 1. **PENDING** - Order is pending warehouse processing 2. **HANDLE_BY_WAREHOUSE** - Order is being processed by the warehouse 3. **SHIPPED** - Order has been shipped out from the warehouse 4. **HANDOVER** - Order has been received by the logistics carrier and is in transit 5. **CLOSED** - Order has been canceled 6. **LOST** - Order is lost 7. **DAMAGE** - Order is damaged 8. **COMPLETED** - Order has been completed 9. **ABNORMAL** - There is an issue related to this order and cannot be fulfilled 10. **RETURNED** - Order has been returned 11. **SCRAP** - Order has been scrapped 12. **UNKNOWN** - Order status is unknown CancelInboundOrderRequest: type: object properties: order_id: type: string description: |- The positive numeric identifier of the inbound order to cancel. **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. Available values: - `CANCELLATION_REQUEST_PENDING` - `CANCELLATION_REQUEST_SUCCESS` - `CANCELLATION_REQUEST_CANCEL` - `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: * BUYER * SELLER * 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: * CANCELLATION_REQUEST_PENDING * CANCELLATION_REQUEST_SUCCESS * CANCELLATION_REQUEST_CANCELLED * 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. **Possible values:** * `SINGLE_SKU`: `items` must contain exactly one item. * `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. Retrieve 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. This 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. - UNKNOWN: The application status is unknown. - TO_APPLY: The creator has not applied for a free sample of the product. - ONGOING: The creator has applied for a free sample but has not completed sample fulfillment. - 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. Possible values: - IS_PREORDER: The product is a preorder product and does not support free samples. - IS_GIFT: The product is a gift and does not support free samples. - OUT_OF_STOCK: The product is out of stock. - EXCEED_CB_PRICE_THRESHOLD: The SKU price exceeds the applicable cross-border price threshold. - ALREADY_APPLYED: The creator has already applied for this SKU. - 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). When 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. Possible values: - SHOP_STATUS - SHOP_TAX - PICKUP_WAREHOUSE - RETURN_WAREHOUSE - DELIVERY_OPTION - SHIPPING_TEMPLATE - PRODUCT_QUANTITY_LIMIT - EXTENDED_PRODUCER_RESPONSIBILITY - BANk_ACCOUNT - 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. **Note**: - 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 `` tags as images. - Max length: 10,000 characters. - Image guidelines: You must use [TikTok Shop image URLs](6509df95defece02be598a22). Max 30 `` tags, each under 4000px with `src`, `width`, and `height` attributes. **Recommendations**: - If you are syncing a pre-existing description from another platform, include the full HTML source description here. - Provide a detailed description, ideally over 300 characters. - Include 3-5 key selling points, each under 250 characters, with supporting images. - Use 1600x1600 px for the image dimensions. category_id: type: string description: |- The ID of a leaf category for this product. Use the [Get Categories API](https://partner.tiktokshop.com/docv2/page/6509c89d0fcef602bf1acd9b) to obtain the available categories. **Note**: - Refer to TikTok Shop Academy for information on product category restrictions. - For the US market, if you are creating products in `INVITE_ONLY` categories, you must submit a separate application through the Qualification Center on TikTok Shop Seller Center to gain access. Otherwise, even if the product audit is passed, the product will not be listed and made available to buyers. (The product status will be `PENDING` and the audit status will be `PRE_APPROVED`) - For the Indonesia market, to list a product on both TikTok Shop and Tokopedia, you must use only categories that are available on both platforms. brand_id: type: string description: |- The ID of the brand of this product. Use the [Get Brands API](https://partner.tiktokshop.com/docv2/page/6503075656e2bb0289dd5d01) to get the list of available brands for a shop. **Note**: Unauthorized brands won't be displayed on TikTok Shop. main_images: type: array items: $ref: "#/components/schemas/MainImage" maxItems: 9 description: |- A list of images to display in the product image gallery. - Max count: 9 - Arrange your image URIs in the sequence that they should appear on TikTok Shop. - Image dimensions: [300x300 px, 4000x4000 px] **Recommendations**: - Use a minimum of 5 images. - The first image should have a white background. Use the [Optimize Images API](https://partner.tiktokshop.com/docv2/page/665692b35d39dc02deb49a97) to change the background to white. skus: type: array items: $ref: "#/components/schemas/CheckProductListingRequestSku" description: |- A list of Stock Keeping Units (SKUs) used to identify distinct variants of the product. **Note**: - Max SKUs for BR, EU, JP, MX, UK, US: 300 - Max SKUs for other regions: 100 **Recommendations**: Place the most important variant at the beginning of the array. title: type: string description: |- The product title. Title length: - DE, ES, FR, IE, IT, JP, UK, US: [1, 255] - BR, MX: [1, 300] - Other regions: [25, 255] is_cod_allowed: type: boolean description: |- A flag indicating whether to show the Cash On Delivery (COD) payment option during checkout. Use the [Get Category Rules API](https://partner.tiktokshop.com/docv2/page/6509c0febace3e02b74594a9) to check if COD is supported for your product category. Applicable only for the following markets: - Global sellers: MY, PH, SA, TH, VN - Local sellers: ID, MY, PH, SA, TH, VN **Note**: If COD is not supported, the listing will fail if you set this to `true`. certifications: type: array items: $ref: "#/components/schemas/Certification" maxItems: 10 description: |- The list of certifications for your product. Max count: 10 As per TikTok Shop guidelines, certifications are required for certain restricted product categories. Retrieve the certification requirements for your product from the [Get Category Rules API](https://partner.tiktokshop.com/docv2/page/6509c0febace3e02b74594a9). Refer to [TikTok Shop Restricted Products Policy](https://seller-us.tiktok.com/university/essay?identity=1&role=1&knowledge_id=3238037484275457&from=policy) for information on product category restrictions. package_weight: $ref: "#/components/schemas/PackageWeight" description: |- The weight of the product package. **Note**: - All the products package weight is **mandatory by default**, except for products under **Virtual Products** categories. [Get Categories API](https://partner.tiktokshop.com/docv2/page/get-categories-202309) e.g **Digital Games**. - Provide the weight measured after packing the product. - This value impacts the shipping cost, so it is important to ensure that the weight is accurate. Any discrepancies in measurements may lead to additional shipping fees. - The package weight will take precedence over package dimensions in fee calculation if the fee based on weight is higher. product_attributes: type: array items: $ref: "#/components/schemas/ProductAttribute" description: |- A list of general attributes (e.g. manufacturer, country of origin, materials used) that describe the product as a whole, regardless of variant. **Important**: The attributes available for use are determined by the system based on the product's assigned category, with some being mandatory. You must provide the product attributes marked as `is_required` in the response of the [Get Attributes API](6509c5784a0bb702c0561cc8) to avoid listing failure. size_chart: $ref: "#/components/schemas/SizeChart" description: |- The measurement details of the product to help buyers find the right size. **Note**: - For certain product categories, size charts may be required or not supported. Use the [Get Category Rules API](https://partner.tiktokshop.com/docv2/page/6509c0febace3e02b74594a9) to check the requirements. - If size charts are not supported, even if you provide a size chart here, the size chart will not be saved. - Provide either a TikTok Shop size chart template ID or a size chart image; if both are provided, the ID takes priority. package_dimensions: $ref: "#/components/schemas/PackageDimension" description: |- The dimensions of the product package. **Note**: - Provide the dimensions measured after packing the product. - These values impact the shipping cost, so it is important to ensure that dimensions are accurate. Any discrepancies in measurements may lead to additional shipping fees. - Optional for ID, TH, VN regions. external_product_id: type: string maxLength: 999 description: |- An external identifier used in an external ecommerce platform. This is used to associate the product between TikTok Shop and the external ecommerce platform. Max length: 999 characters delivery_option_ids: type: array items: type: string description: |- This field is supported for seller accounts in the following regions only: - ID - MX - MY - PH - SG - TH - VN The custom delivery option IDs to apply to this product if you want to override the default warehouse delivery options. To retrieve the available option IDs, call [Get Warehouse Delivery Options](650aa46ebace3e02b75d9afa) with `scope=PRODUCT`. **Note**: Leave this field blank to inherit the default delivery options configured for the warehouse. video: $ref: "#/components/schemas/Video" description: |- A product introduction or promotion video to display for your product. **Recommendations**: - Aspect ratio: 1:1 - Resolution: HD 720p or higher - Duration: 20 - 60 seconds primary_combined_product_id: type: string description: |- If this product is associated with a virtual bundle, this value is the ID of the primary product in the bundle. **Note**: Required only for virtual bundle products. manufacturer_ids: type: array items: type: string description: |- A list of manufacturer IDs. Retrieve the IDs from the [Search Manufacturers API](67066a580dcee902fa03ccf9). **Note**: Applicable only for the EU market in certain categories. Use the [Get Category Rules API](6509c0febace3e02b74594a9) to check the requirements. responsible_person_ids: type: array items: type: string description: |- A list of responsible person IDs. Retrieve the IDs from the [Search Responsible Persons API](67066a55f17b7d02f95d2fb1). **Note**: Applicable only for the EU market in certain categories. Use the [Get Category Rules API](6509c0febace3e02b74594a9) to check the requirements. listing_platforms: type: array items: type: string enum: - TOKOPEDIA - TIKTOK_SHOP description: |- The platforms for listing the product. Possible values: - TOKOPEDIA - TIKTOK_SHOP Default: TIKTOK_SHOP Applicable only for sellers that migrated from Tokopedia. shipping_insurance_requirement: type: string enum: - REQUIRED - OPTIONAL - NOT_SUPPORTED x-enum-descriptions: - Shipping insurance is mandatory and buyers can't opt out. - Buyers can choose to purchase shipping insurance through the platform. - Shipping insurance is not supported for the product. description: |- The shipping insurance purchase requirement imposed on buyers for the product. Possible values: - REQUIRED: Shipping insurance is mandatory and buyers can't opt out. - OPTIONAL: Buyers can choose to purchase shipping insurance through the platform. - NOT_SUPPORTED: Shipping insurance is not supported for the product. Default: OPTIONAL Applicable only if the listing platforms include TOKOPEDIA. is_pre_owned: type: boolean description: |- A flag to indicate if the product is pre-owned. Applicable only if TOKOPEDIA is the sole listing platform. **Note**: To list pre-owned products on the TikTok Shop platform, please specify the ID of one of the designated pre-owned product categories (e.g. pre-owned luxury bags, luggage, and accessories) in `category_id`. minimum_order_quantity: type: integer format: int64 minimum: 1 maximum: 20 description: |- The minimum order quantity for the product. Valid range: [1, 20] Applicable only for the Indonesia market and selected sellers in other SEA markets. Contact your account manager for more information about gaining access to this field. shipping_template_id: type: string description: Identifier of the shipping template that will be bound to the product option: $ref: "#/components/schemas/CheckProductListingRequestOption" description: Options for asynchronous product information verification. scheduled_sale: $ref: "#/components/schemas/ScheduledSale" description: Scheduled listing configuration for the product, including whether scheduled listing is enabled and the scheduled listing time. search_terms: type: array items: type: string description: Search terms (ST words). ST words will not be displayed to consumers; they are only used in search engines to increase your search weight and gain more traffic. Please ensure that ST words are consistent with the product description, with a maximum of 15 terms and a total of no more than 250 characters. key_product_features: type: array items: type: string maxItems: 5 description: Key Product Features. They will be displayed in the Product highlight module on the product detail page and will be used by search engines to increase your search weight for more traffic. The total number of items should not exceed 5, and the total character count should not exceed 1500. product_tag_operations: type: array items: $ref: "#/components/schemas/ProductTagOperation" description: Legacy operations for enabling or disabling the `AUCTION` product tag. If `selling_format` is provided, it takes precedence over this field. locale: 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 description: |- The BCP-47 locale codes for displaying category information. Default: The default locale of your shop. Possible values: - 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 selling_format: type: string enum: - FIXED_PRICE - FIXED_PRICE_AND_LIVE_AUCTION description: "Choose either Fixed price or Fixed price and LIVE auction. Fixed price is selected by default. LIVE auction require a starting bid price. Possible values: FIXED_PRICE, FIXED_PRICE_AND_LIVE_AUCTION." is_live_quick: type: boolean description: |- false — NORMAL products true — LIVE_QUICK products. Only seller with the required permissions can creat LIVE_QUICK products. Default: false required: - description - category_id - main_images - skus - title CheckProductListingRequestOption: type: object properties: need_trigger_gne_async_check: type: boolean description: |- Whether to trigger asynchronous product information verification. This asynchronous workflow is available only to enabled sellers in the US. Set this field to `true` together with a nonempty `gne_async_check_session_id` to start new asynchronous checks. To retry retrieval with the same session ID without creating new asynchronous tasks, set this field to `false`; any completed findings are returned in `pre_check_results`. gne_async_check_session_id: type: string description: |- A caller-provided session ID for asynchronous product information verification. This asynchronous workflow is available only to enabled sellers in the US. Provide a nonempty session ID when you trigger asynchronous verification, then reuse the same session ID on later calls to this API with the same product information to retrieve any completed findings in `pre_check_results`. This API does not generate or return a new session ID for you. CheckProductListingRequestSku: type: object properties: sales_attributes: type: array items: $ref: "#/components/schemas/CheckProductListingRequestSkuSalesAttribute" description: |- A list of attributes (e.g. size, color, length) that define each variant of a product. **Note**: - You can omit this object if there is only 1 SKU. Otherwise, this is **required**. - You can only have up to 3 types of sales attributes per product. - Each SKU must include the same number and type of sales attributes. For example, you cannot have one SKU that has only a Color attribute, while another SKU has both Color and Size attributes. - Provide either a built-in ID or a custom name; if both are provided, the ID takes priority. - The `id/name` and `value_id/value_name` pairs must be unique in each SKU. For example, you cannot repeat `"name": "Color"`, `"value_name": "Red"` in different SKUs. seller_sku: type: string description: |- An internal code/name for managing SKUs, not visible to buyers. Valid length: - DE, ES, FR, IT, PL, NL, BE, CZ, AT, GR, PT, HU: 6-50 characters - Other regions: 1-50 characters Format: - DE, ES, FR, IT, PL, NL, BE, CZ, AT, GR, PT, HU: Use alphabets, numbers, hyphens (-), or underscores (_) only - Other regions: Text without spaces price: $ref: "#/components/schemas/CheckProductListingRequestSkuPrice" description: SKU pricing information. external_sku_id: type: string maxLength: 999 description: |- An external identifier used in an external ecommerce platform. This is used to associate the SKU between TikTok Shop and the external ecommerce platform. Max length: 999 characters identifier_code: $ref: "#/components/schemas/IdentifierCode" description: A regulated identifier code assigned to a product based on international standardized regulations (e.g. GTIN) to ensure the product is universally identifiable across various platforms and systems. inventory: type: array items: $ref: "#/components/schemas/Inventory" description: SKU inventory information. combined_skus: type: array items: $ref: "#/components/schemas/CombinedSku" description: If this SKU belongs to a virtual bundle, this object contains the list of individual SKUs that form the bundle (e.g. gift basket, starter pack). sku_unit_count: type: string description: |- The total quantity/volume of the product represented by the SKU. For example, if the SKU represents 500ml of water, this value would be 500 if the unit type is defined as ml. Valid range: [0.01, 99,999.9999] Applicable only for the EU market. **Note**: - This is mainly used to calculate the unit price of the SKU, and is required only if you wish to display the unit price to facilitate easier price comparisons across different products and packaging sizes. - Unit price = Selling price/(SKU unit count/base unit count). Therefore if you want to obtain the unit price, you would also need to define the "base unit count" and the "unit type" product attributes. Retrieve the relevant information for these product attributes by using the [Get Attributes API](https://partner.tiktokshop.com/docv2/page/6509c5784a0bb702c0561cc8). The unit price would then be returned in the [Get Product API](https://partner.tiktokshop.com/docv2/page/6509d85b4a0bb702c057fdda). external_urls: type: array items: type: string description: |- A list of URLs for third-party product listing pages where consumers can place orders. Add this property if you have products listed on third-party sites other than TikTok Shop and would like to map them. Provide this field as a JSON array of URL strings. Max string length: 500 extra_identifier_codes: type: array items: type: string description: |- If the SKU belongs to a virtual bundle (containing multiple individual SKUs), you can add up to 10 additional identifier codes here for the SKUs included in the bundle. **Format**: GTIN: 14 digits EAN: 8, 13, or 14 digits UPC: 12 digits ISBN: 13 digits, or 9 digits ending in capital `X` **Note**: - Applicable only for the EU market. - The identifier code must be unique for each SKU, with no repetition allowed. pre_sale: $ref: "#/components/schemas/PreSale" description: |- SKU presale information, used to tag a product as a presale product based on its presale type. Omit this object if the product is a regular item. Applicable only if `allowed_special_product_types` from [Get Category Rules](6509c0febace3e02b74594a9) is not empty. **Rules for the US market**: - Regular / Preorder product: Once the product goes live, you cannot change the product type. - Made-to-order product: You can change it to a regular product at any time. list_price: $ref: "#/components/schemas/ListPrice" description: |- The SKU's list price information. This is equivalent to the manufacturer's suggested retail price (MSRP), or the recommended retail price (RRP). Applicable only for US local sellers. **Note**: This value may appear as the strikethrough price on the product page. However, whether the strikethrough price is shown and the amount shown are subject to the audit team's review and decision based on various pricing information. external_list_prices: type: array items: $ref: "#/components/schemas/ExternalListPrice" description: |- The SKU list price (e.g. MSRP, RRP) or original price information on external ecommerce platforms. Applicable only for selected local sellers in the US market. **Note**: This value may appear as the strikethrough price on the product page. However, whether the strikethrough price is shown and the amount shown are subject to the audit team's review and decision based on various pricing information. fees: type: array items: $ref: "#/components/schemas/Fee" description: The fees required for this product based on TikTok Shop policies. Fees are required only for certain product categories, retrieve the requirements from the [Get Category Rules API](https://partner.tiktokshop.com/docv2/page/6509c0febace3e02b74594a9). sku_dimensions: $ref: "#/components/schemas/SkuDimension" description: |- The dimensions of the sku. Note: - Provide the dimensions measured after packing the product. - These values impact the shipping cost, so it is important to ensure that dimensions are accurate. Any discrepancies in measurements may lead to additional shipping fees. - Optional for ID, TH, VN regions. sku_weight: $ref: "#/components/schemas/SkuWeight" description: |- The packaged weight of the SKU. Note: - Provide the weight measured after packing the SKU. - Use the same measurement system for `sku_weight` and `sku_dimensions`; for example, use `KILOGRAM` with `CENTIMETER`. - Weight and dimensions can affect shipping costs, so ensure both are accurate. Shipping fees may use the higher of the actual weight and the volumetric weight calculated from the dimensions. required: - price - inventory CheckProductListingRequestSkuPrice: type: object properties: amount: type: string description: |- **Local sellers/Intra-EU sellers** The SKU's **local display price** shown on the product page before any discounts. Refer to [Product Pricing](https://partner.tiktokshop.com/docv2/page/67e1288d76cfee049d9af858) for the allowed price ranges in each market. currency: type: string enum: - BRL - CZK - EUR - GBP - HUF - IDR - JPY - MXN - MYR - PHP - PLN - SGD - THB - USD - VND x-enum-descriptions: - Brazil - Czech Republic - France, Germany, Ireland, Italy, Spain, Netherlands, Belgium, Austria, Greece, Portugal - United Kingdom - Hungary - Indonesia - Japan - Mexico - Malaysia - Philippines - Poland - Singapore - Thailand - United States - Vietnam description: |- The currency.Possible values based on the region: - BRL: Brazil - CZK: Czech Republic - EUR: France, Germany, Ireland, Italy, Spain, Netherlands, Belgium, Austria, Greece, Portugal - GBP: United Kingdom - HUF: Hungary - IDR: Indonesia - JPY: Japan - MXN: Mexico - MYR: Malaysia - PHP: Philippines - PLN: Poland - SGD: Singapore - THB: Thailand - USD: United States - VND: Vietnam sale_price: type: string description: |- **Global sellers** The SKU's **local display price** shown on the product page before any discounts. Refer to [Product Pricing](https://partner.tiktokshop.com/docv2/page/67e1288d76cfee049d9af858) for the allowed price ranges in each market. **Note**: - Applicable only for global sellers. - Required for JP and US shops using China warehouses, optional for others. - This is the definitive final price shown on the product page, all other prices will be ignored. starting_bid_price: type: string description: starting bid price for auction product required: - currency CheckProductListingRequestSkuSalesAttribute: type: object properties: id: type: string description: The ID of a built-in sales attribute, retrieved from [Get Attributes API](https://partner.tiktokshop.com/docv2/page/6509c5784a0bb702c0561cc8). name: type: string maxLength: 20 description: |- A self-defined custom sales attribute name to validate when the built-in attributes do not satisfy your needs. **Note**: - Do not include sensitive characters. - Max length: 20 characters value_id: type: string description: The ID of a built-in sales attribute value, retrieved from the [Get Attributes API](https://partner.tiktokshop.com/docv2/page/6509c5784a0bb702c0561cc8). value_name: type: string maxLength: 50 description: |- A self-defined custom sales attribute value to validate when the built-in values do not satisfy your needs. **Note**: - No duplicates allowed under the same attribute. - Max length: 50 characters. sku_img: $ref: "#/components/schemas/SkuImg" description: |- The default/main image for each value (e.g. red) of the primary sales attribute (e.g. color). This appears in the product options gallery on TikTok Shop. You can attach images to only 1 type of sales attribute, which will serve as the primary attribute for display. An image must be provided for each value of the primary attribute. For example, if a product has 2 colors and 3 sizes, you can choose to attach images for either the color sales attribute or the size sales attribute. If you choose to attach images for color, you must attach 2 images, one for each color. If you want to add more images, use `supplementary_sku_images`. supplementary_sku_images: type: array items: $ref: "#/components/schemas/SupplementarySkuImage" description: |- A list of supplementary images for each value (e.g. red) of the primary sales attribute (e.g. color) to provide multiple views or details of the product for that attribute value. These appear in the product options gallery on TikTok Shop. **Note**: - Max number of image URIs: 8. - Arrange your image URIs in the sequence that they should appear on TikTok Shop. - Applicable only for the US market. CheckProductListingResponse: 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/CheckProductListingResponseData" CheckProductListingResponseData: type: object properties: check_result: type: string description: The result of the product diagnosis (PASS, FAILED). fail_reasons: type: array items: $ref: "#/components/schemas/CheckProductListingResponseDataFailReason" description: A list of failure reasons if `check_result` is FAILED. warnings: $ref: "#/components/schemas/Warning" description: Warning information that the API caller needs to pay special attention to. listing_quality: $ref: "#/components/schemas/CheckProductListingResponseDataListingQuality" description: |- (**Deprecated**: This field is deprecated and will be removed in a future API version. Use the [Diagnose and Optimize Product](677c9523f7765c0308b3d68d) API instead to get listing quality related information.） Product listing quality information. deprecated: true diagnoses: type: array items: $ref: "#/components/schemas/CheckProductListingResponseDataDiagnosis" 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 product diagnosis related information.) Product optimization diagnosis information. deprecated: true pre_check_results: type: array items: $ref: "#/components/schemas/CheckProductListingResponseDataPreCheckResult" description: Contains any completed product information verification findings available for the supplied `gne_async_check_session_id`. The response does not expose a separate pending or completed status. If this field is missing or empty, you cannot determine from the response whether the asynchronous checks have completed or passed. CheckProductListingResponseDataDiagnosis: type: object properties: field: type: string enum: - TITLE - DESCRIPTION - IMAGE - ATTRIBUTE - SIZE_CHART x-enum-descriptions: - Product title - Product description - Product image displayed in the image gallery - Product attribute - Product size chart description: |- The product field being diagnosed. Possible values: - TITLE: Product title - DESCRIPTION: Product description - IMAGE: Product image displayed in the image gallery - ATTRIBUTE: Product attribute - SIZE_CHART: Product size chart diagnosis_results: type: array items: $ref: "#/components/schemas/DiagnosisResult" description: The diagnosis results. suggestions: $ref: "#/components/schemas/CheckProductListingResponseDataDiagnosisSuggestion" description: Improvement suggestions. CheckProductListingResponseDataDiagnosisSuggestion: type: object properties: seo_words: type: array items: $ref: "#/components/schemas/SeoWord" description: The SEO keyword suggestions if `diagnoses.field` is "TITLE". smart_texts: type: array items: $ref: "#/components/schemas/SmartText" description: The intelligent text suggestions for titles and descriptions. images: type: array items: $ref: "#/components/schemas/CheckProductListingResponseDataDiagnosisSuggestionImage" description: The optimized main image. Only the first image in the main image set will be optimized. CheckProductListingResponseDataDiagnosisSuggestionImage: type: object properties: uri: type: string description: The original URI of the image. url: type: string description: The original URL of the image. optimized_uri: type: string description: The URI of the image after optimization. optimized_url: type: string description: The URL of the image after optimization. height: type: integer format: int64 description: The image height after optimization. width: type: integer format: int64 description: The image width after optimization. CheckProductListingResponseDataFailReason: type: object properties: code: type: integer format: int64 description: A machine-readable code that represents the failure reason. This is equivalent to the error codes shown when creating a product. For the full list of codes, refer to [Create Product > Error Code](https://partner.tiktokshop.com/docv2/page/6502fc8da57708028b42b18a?#Error_Code). message: type: string description: A detailed reason for the failure. CheckProductListingResponseDataListingQuality: type: object properties: current_tier: type: string enum: - POOR - FAIR - GOOD - EXCELLENT description: |- The current quality tier of this product listing. The quality tier of a product listing depends on the quality of the content in its product fields such as the title, image, attributes etc. Possible values: - POOR - FAIR - GOOD - EXCELLENT **Note**: Available only for the US market. remaining_recommendations: type: integer format: int64 description: |- The remaining number of recommendations (see `diagnosis_results`) that must be implemented for the product to reach the highest tier. **Note**: - To reach the highest tier, you must implement all recommendations listed in `diagnosis_results`. - Available only for the US market. CheckProductListingResponseDataPreCheckResult: type: object properties: pre_check_item: type: string description: "Product information verification type: The types of issues returned by product information verification." pre_check_details: type: array items: $ref: "#/components/schemas/CheckProductListingResponseDataPreCheckResultPreCheckDetail" description: Information Verification Details. CheckProductListingResponseDataPreCheckResultPreCheckDetail: type: object properties: short_reason: type: string description: "Reason for streamlining: Simple problem description of product verification results" long_reason: type: string description: "Detailed reason: Detailed problem description of product verification results" related_fields: type: array items: type: string description: "Problem Module: From which module does the problem originate, e.g., PRE_CHECK_FIELD_TITLE, PRE_CHECK_FIELD_IMAGES" CheckShippingTemplateExistenceResponse: 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/CheckShippingTemplateExistenceResponseData" CheckShippingTemplateExistenceResponseData: type: object properties: template_exist: type: boolean description: if template exists, return true CheckTargetCollaborationConflictsRequest: type: object properties: creator_open_id_list: type: array items: type: string description: Creator Open ID List. [More details](https://partner.tiktokshop.com/docv2/page/3obfokj6) product_id_list: type: array items: type: string description: product id list required: - creator_open_id_list - product_id_list CheckTargetCollaborationConflictsResponse: 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/CheckTargetCollaborationConflictsResponseData" CheckTargetCollaborationConflictsResponseData: type: object properties: has_conflict: type: boolean description: Indicates whether a conflict exists between the creator and the product. (Returns `true` if a conflict is detected.) conflict_items: type: array items: $ref: "#/components/schemas/CheckTargetCollaborationConflictsResponseDataConflictItem" description: A list of creator-product combinations whose conflicts caused the target collaboration to fail. Each item identifies the creator, product, and existing target collaboration involved. CheckTargetCollaborationConflictsResponseDataConflictItem: type: object properties: creator_open_id: type: string description: Creator Open ID. [More details](https://partner.tiktokshop.com/docv2/page/3obfokj6) product_id: type: string description: The product identifier. existing_collaboration_id: type: string description: The confict target collaboration id CheckTikTokShippingAndCollectionByTikTokCoverageResponse: 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/CheckTikTokShippingAndCollectionByTikTokCoverageResponseData" CheckTikTokShippingAndCollectionByTikTokCoverageResponseData: type: object properties: is_tiktok_shipping: type: boolean description: Indicates whether the tracking number is covered by TikTok Shipping (TTS). is_tiktok_collection: type: boolean description: Indicates whether the tracking number is covered by Collection by TikTok (CBT). ClaimDuration: type: object properties: start_time: type: integer format: int64 description: The UNIX timestamp, in seconds, from which a shopper can claim the coupon. end_time: type: integer format: int64 description: The UNIX timestamp, in seconds, after which a shopper can no longer claim the coupon. ClickToOrderRate: type: object properties: sku_order_ctor: type: string description: The percentage of times viewers clicked product links in LIVE streams and placed a direct order. main_order_ctor: type: string description: Percentage of times viewers who clicked LIVE product links also placed a main order. CombinePackageRequest: type: object properties: combinable_packages: type: array items: $ref: "#/components/schemas/CombinePackageRequestCombinablePackage" description: The packages to combine. Provide at least one package. Each item identifies a package and can specify the order IDs to include. required: - combinable_packages CombinePackageRequestCombinablePackage: type: object properties: id: type: string description: The package ID. order_ids: type: array items: type: string description: The order IDs to include when combining the package identified by `id`. required: - id CombinePackageResponse: 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/CombinePackageResponseData" CombinePackageResponseData: type: object properties: packages: type: array items: $ref: "#/components/schemas/Package" description: Return list of successfully combined packages. errors: type: array items: $ref: "#/components/schemas/BatchShipPackagesResponseDataError" description: The errors returned for packages that could not be combined. CombinedListingChangeWebhook: type: object properties: type: type: integer const: 42 description: The ID of the webhook type. tts_notification_id: type: string description: The ID of this webhook notification. shop_id: type: string description: The shop ID. timestamp: type: integer format: int64 description: The time when this webhook is triggered. Unix timestamp. data: $ref: "#/components/schemas/CombinedListingChangeWebhookData" required: - type CombinedListingChangeWebhookData: type: object properties: combined_listing_id: type: string description: The combined listing ID. products: type: array items: $ref: "#/components/schemas/CombinedListingChangeWebhookDataProduct" description: The current list of products in this combined listing after the change. status: type: string enum: - LIVE - SYSTEM_DEACTIVATED - SELLER_DEACTIVATED - DELETED description: |- The status of the combined listing. Possible values: * LIVE * SYSTEM_DEACTIVATED * SELLER_DEACTIVATED * DELETED Note: Only products in LIVE combined listings will appear on the product display page. change_type: type: string enum: - CREATE - UPDATE - DELETE x-enum-descriptions: - The combined listing was created. - The combined listing was updated to add or remove products. - The combined listing was deleted. description: |- The type of change made to this combined listing. Possible values: * CREATE: The combined listing was created. * UPDATE: The combined listing was updated to add or remove products. * DELETE: The combined listing was deleted. added_product_ids: type: array items: type: string description: The list of products that were newly added to the combined listing. removed_product_ids: type: array items: type: string description: The list of products that were removed from the combined listing. CombinedListingChangeWebhookDataProduct: type: object properties: id: type: string description: The product id. CombinedListingSku: type: object properties: sku_id: type: string description: The original `sku_id` related to the virtual bundle SKU. sku_count: type: integer format: int64 description: The quantity of original SKU that compose the virtual bundle SKU. product_id: type: string description: The original `product_id` related to the virtual bundle SKU. seller_sku: type: string description: The original `seller_sku` (which is defined by sellers) related to the virtual bundle SKU. CombinedSku: type: object properties: product_id: type: string description: The ID of the source product included in the virtual bundle. sku_id: type: string description: The ID of the source SKU included in the virtual bundle. sku_count: type: integer format: int64 description: The quantity of the source SKU included in the virtual bundle. required: - product_id - sku_id - sku_count Commission: type: object properties: rate: type: integer format: int64 description: |- - The commission rate for this product is set by merchants for creators public promotion. - The range of this value is [100, 8000]. - This value equals actual commission rate multi 10000. For example: 3000 means the actual commission rate is 30.00%, and 3555 means 35.55% currency: type: string description: Currency code for the commission amount. amount: type: string description: The commission amount calculated from the product's promotional price and commission rate. When both minimum and maximum promotional prices are available, the value is formatted as ` - `; otherwise, it contains the available commission amount. If neither price is available, the value is `0`. The currency is specified by `commission.currency`. ConfirmInboundMethodRequest: type: object properties: plan_id: type: string description: Identifier of the FBT inbound plan whose warehouse placement option is being confirmed. placement_option_id: type: string description: Placement option id. A placement option represents the shipment splits and destinations. inbound_method: type: string enum: - D2FC - ONE_HUB x-enum-descriptions: - Direct to fulfillment center, may be split into multiple shipments - Single destination, includes fee description: |- **Possible values:** * `D2FC` (Direct to fulfillment center, may be split into multiple shipments) * `ONE_HUB` (Single destination, includes fee) estimate_arrival_time: $ref: "#/components/schemas/EstimateArrivalTime" description: Estimated arrival time. Value should be retrieved from the `available_time_window_list` from `ListAvailableInboundMethod` API response required: - plan_id - placement_option_id - inbound_method - estimate_arrival_time ConfirmInboundMethodResponse: 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/ConfirmInboundMethodResponseData" ConfirmInboundMethodResponseData: type: object properties: inbound_order_ids: type: array items: type: string description: List of child inbound order IDs generated for the confirmed FBT inbound plan. ConfirmOrderSplitRequest: type: object properties: splittable_groups: type: array items: $ref: "#/components/schemas/ConfirmOrderSplitRequestSplittableGroup" description: Groups of order line items to split. Each successfully split group is returned as a separate package. splittable_groups_v2: type: array items: $ref: "#/components/schemas/ConfirmOrderSplitRequestSplittableGroupsV2" description: This new parameter is completely backward compatible with the previous splittable groups field and in addition this supports bundle order splitting, use the sub items accordingly required: - splittable_groups ConfirmOrderSplitRequestSplittableGroup: type: object properties: id: type: string description: A developer-defined identifier for this split group. The response returns the same value in `splittable_group_id` to correlate the group with its newly created package. order_line_item_ids: type: array items: type: string description: The order line item IDs that need to be split into this group. required: - id - order_line_item_ids ConfirmOrderSplitRequestSplittableGroupsV2: type: object properties: id: type: string description: A developer-defined identifier for this split group. The response returns the same value in `splittable_group_id` to correlate the group with its newly created package. order_line_list: type: array items: $ref: "#/components/schemas/ConfirmOrderSplitRequestSplittableGroupsV2OrderLineList" description: This new parameter is completely backward compatible with the previous oder_line_items_ids field and in addition this supports bundle order splitting, use the sub items accordingly ConfirmOrderSplitRequestSplittableGroupsV2OrderLineList: type: object properties: order_line_id: type: string description: The corresponding order line ID. sub_item_id: type: string description: |- The sub-order-line ID inside a bundle product. - Required for bundle products. - Not required for non-bundle products. ConfirmOrderSplitResponse: 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/ConfirmOrderSplitResponseData" ConfirmOrderSplitResponseData: type: object properties: packages: type: array items: $ref: "#/components/schemas/ConfirmOrderSplitResponseDataPackage" description: Packages created by the split. Each returned package includes the request group identifier in `splittable_group_id` and its new package ID in `id`. ConfirmOrderSplitResponseDataPackage: type: object properties: splittable_group_id: type: string description: The developer-defined `id` of the corresponding group from `splittable_groups` or `splittable_groups_v2` in the request. id: type: string description: Package ID after success split. Use this new package ID to call [Ship Package API](https://partner.tiktokshop.com/docv2/page/650aa4f1defece02be6e7cb1?external_id=650aa4f1defece02be6e7cb1) to ship the package. ConfirmPackageShipmentRequest: type: object properties: warehouse_provider_id: type: string description: The unique warehouse provider ID assigned by TikTok Shop. The value must represent a positive base-10 integer. packages: type: array items: $ref: "#/components/schemas/ConfirmPackageShipmentRequestPackage" description: List of packages to confirm. Provide at least one package. required: - warehouse_provider_id - packages ConfirmPackageShipmentRequestPackage: type: object properties: id: type: string description: Package ID. The value must be a non-zero base-10 integer string no longer than 40 UTF-8 bytes. wms_order_id: type: string description: Warehouse Management System order number provider_warehouse_code: type: string description: "Warehouse code. Maximum: 40 UTF-8 bytes." shipping_origin_city: type: string description: Origin city name for the shipment time_zone: type: string description: The warehouse time zone ship_time_millis: type: integer format: int64 description: Time when the order is shipped out of the warehouse (Unix timestamp in milliseconds) create_time_millis: type: integer format: int64 description: Time when warehouse receives the order (Unix timestamp in milliseconds) handover_time_millis: type: integer format: int64 description: Time when the order is handed over to the shipping provider (Unix timestamp in milliseconds) shipping_provider_id: type: string description: Shipping service provider ID shipping_provider_name: type: string description: Shipping service provider name tracking_number: type: string description: Tracking number dimension: $ref: "#/components/schemas/ConfirmPackageShipmentRequestPackageDimension" description: Package dimension information weight: $ref: "#/components/schemas/ConfirmPackageShipmentRequestPackageWeight" description: Package weight information skus: type: array items: $ref: "#/components/schemas/ConfirmPackageShipmentRequestPackageSku" description: List of order SKUs in the package. Provide at least one SKU. provider_warehouse_name: type: string description: Warehouse name tcw_warehouse_type: type: string enum: - STANDARD - TIKTOK_CERTIFIED_WAREHOUSE_FULFILLMENT x-enum-descriptions: - Standard warehouse that has not been specifically certified by TikTok - TikTok certified warehouse usually offering better service levels. Certified warehouses are required to meet fulfillment timeline standards set by TikTok description: |- TikTok warehouse type Possible values: - STANDARD: Standard warehouse that has not been specifically certified by TikTok - TIKTOK_CERTIFIED_WAREHOUSE_FULFILLMENT: TikTok certified warehouse usually offering better service levels. Certified warehouses are required to meet fulfillment timeline standards set by TikTok required: - id - wms_order_id - time_zone - ship_time_millis - create_time_millis - handover_time_millis - shipping_provider_id - shipping_provider_name - tracking_number - dimension - skus ConfirmPackageShipmentRequestPackageDimension: type: object properties: length: type: integer format: int64 description: Package length. Must be greater than or equal to `0`. width: type: integer format: int64 description: Package width. Must be greater than or equal to `0`. height: type: integer format: int64 description: Package height. Must be greater than or equal to `0`. unit: type: string enum: - METER - CENTIMETER - MILLIMETER - MICRON - FOOT - INCH description: |- Package dimension unit Possible values: - METER - CENTIMETER - MILLIMETER - MICRON - FOOT - INCH ConfirmPackageShipmentRequestPackageSku: type: object properties: id: type: string description: The TikTok Shop SKU ID. The value must represent a positive base-10 integer. quantity: type: integer format: int64 description: Quantity of this SKU in the package. Must be greater than `0`. required: - id - quantity ConfirmPackageShipmentRequestPackageWeight: type: object properties: value: type: integer format: int64 description: Package weight. Must be greater than or equal to `0`. unit: type: string enum: - KILOGRAM - GRAM - MILLIGRAM - POUND - OUNCE description: |- Package weight unit Possible values: - KILOGRAM - GRAM - MILLIGRAM - POUND - OUNCE ConfirmPackageShipmentResponse: 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/ConfirmPackageShipmentResponseData" ConfirmPackageShipmentResponseData: type: object properties: success_packages: type: array items: type: string description: List of packages that have been successfully confirmed errors: type: array items: $ref: "#/components/schemas/ConfirmPackageShipmentResponseDataError" description: List of packages that were not confirmed, with failure information for each package. This field is omitted when every package is confirmed. ConfirmPackageShipmentResponseDataError: type: object properties: code: type: string description: Error code message: type: string description: Error message detail: $ref: "#/components/schemas/BatchShipPackagesResponseDataErrorDetail" description: Failed package details ContactInfo: type: object properties: whatsapp: type: string description: The partner's phone number registered in WhatsApp, in E.164 international format. Applicable if the target market is MY, SG, GB, ID, or US. email: type: string description: The partner's email address. phone: type: string description: The partner's phone number in E.164 international format. zalo: type: string description: The partner's phone number registered in Zalo, in E.164 international format. Applicable if the target market is VN. viber: type: string description: The partner's phone number registered in Viber, in E.164 international format. Applicable if the target market is PH. line: type: string description: The partner's phone number registered in LINE, in E.164 international format. Applicable if the target market is TH. CountryDistribution: type: object properties: country_code: type: string description: The region of the viewer's TikTok account. percentage: type: string description: Proportion for the corresponding country within this viewer profile, expressed as a decimal fraction. CreateAffiliatePartnerCampaignRequest: type: object properties: name: type: string minLength: 1 maxLength: 50 description: The campaign name. Must contain 1 to 50 characters, inclusive, and must not start with a space. description: type: string minLength: 1 maxLength: 1000 description: The campaign description. Must contain 1 to 1000 characters, inclusive, and must not start with a space. campaign_start_time: type: integer format: int64 description: The scheduled campaign start time as a Unix timestamp in seconds. It must not be earlier than the current time. In subsequent edits, this value can be changed only when the campaign status is `READY` or `UPCOMING`. campaign_end_time: type: integer format: int64 description: The scheduled campaign end time as a Unix timestamp in seconds. It must be later than `campaign_start_time`, and the campaign period must be between 1 and 360 days, inclusive. In subsequent edits, this value cannot be changed when the campaign status is `CLOSED`. registration_start_time: type: integer format: int64 description: The scheduled start time for seller product registration as a Unix timestamp in seconds. It must be equal to `campaign_start_time`. In subsequent edits, this value can be changed only when the campaign status is `READY` or `UPCOMING`. registration_end_time: type: integer format: int64 description: The scheduled end time for seller product registration as a Unix timestamp in seconds. It must be later than `registration_start_time`; the registration period must be at least 1 day and must not extend beyond `campaign_end_time`. In subsequent edits, this value cannot be changed when the campaign status is `CLOSED`. commission_rate: type: integer format: int64 description: The total commission rate, in hundredths of a percent (0.01%) units, proposed by the affiliate partner for display to sellers. The value must be between 100 and 8000, inclusive. contact_info: $ref: "#/components/schemas/CreateAffiliatePartnerCampaignRequestContactInfo" description: The partner's contact information. target_shop_codes: type: array items: type: string description: A list of TikTok Shop seller shop codes that may register for the campaign. Find a seller's shop code in TikTok Shop Seller Central by selecting the Seller Profile icon in the top-right corner of the user interface. Specify exactly one of `target_shop_codes` and `target_seller_types`. The list must contain fewer than 100 items. target_seller_types: type: array items: type: string enum: - LOCAL - CROSS_BORDER description: |- A list of eligible seller types that may register for the campaign. Use this field to target seller types instead of specific sellers in `target_shop_codes`. Specify exactly one of `target_seller_types` and `target_shop_codes`. Possible values: - `LOCAL` - `CROSS_BORDER` required: - name - description - campaign_start_time - campaign_end_time - registration_start_time - registration_end_time - commission_rate - contact_info CreateAffiliatePartnerCampaignRequestContactInfo: type: object properties: whatsapp: type: string description: The partner's phone number registered in WhatsApp, in E.164 international format. Required if the target market is MY, SG, GB, or ID; optional if the target market is US; otherwise, not applicable. email: type: string description: The partner's email address. phone: type: string description: The partner's phone number in E.164 international format. zalo: type: string description: The partner's phone number registered in Zalo, in E.164 international format. Required if the target market is VN; otherwise, not applicable. viber: type: string description: The partner's phone number registered in Viber, in E.164 international format. Required if the target market is PH; otherwise, not applicable. line: type: string description: The partner's phone number registered in LINE, in E.164 international format. Required if the target market is TH; otherwise, not applicable. required: - email CreateAffiliatePartnerCampaignResponse: 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/CreateAffiliatePartnerCampaignResponseData" CreateAffiliatePartnerCampaignResponseData: type: object properties: campaign_id: type: string description: The campaign identifier. CreateCategoryUpgradeTaskRequest: type: object properties: {} CreateCategoryUpgradeTaskResponse: 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/CreateCategoryUpgradeTaskResponseData" CreateCategoryUpgradeTaskResponseData: type: object properties: {} CreateCompassOfflineExportTaskRequest: type: object properties: module_type: type: string enum: - CREATOR - BASE x-enum-descriptions: - Creator list data. - Core performance data. description: |- Type of Compass data to export. Allowed values: - CREATOR: Creator list data. - BASE: Core performance data. window_type: type: string enum: - PAST_24H - PAST_7_DAYS - PAST_30_DAYS description: "Time window included in the export, ending on end_day. Allowed values: PAST_24H, PAST_7_DAYS, PAST_30_DAYS." end_day: type: integer format: int64 description: |- End date in the local timezone of the specified region, formatted as YYYYMMDD. - id：UTC+7 - my：UTC+8 - sg：UTC+8 - vn：UTC+7 - th：UTC+7 - ph：UTC+8 - sa：UTC+3 - us：UTC-8 - mx：UTC-6 - br：UTC-3 - jp：UTC+9 - gb：UTC+0 - ie：UTC+0 - es：UTC+1 - de：UTC+1 - fr：UTC+1 - it：UTC+1 - pl：UTC+1 - nl：UTC+1 - be：UTC+1 - cz：UTC+1 - at：UTC+1 - gr：UTC+2 - pt：UTC+0 - hu：UTC+1 plan_type: type: string enum: - ALL - TARGET - OPEN - PARTNER description: "Plan type. Allowed values: ALL, TARGET, OPEN, PARTNER." CreateCompassOfflineExportTaskResponse: 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/CreateCompassOfflineExportTaskResponseData" CreateCompassOfflineExportTaskResponseData: type: object properties: task: $ref: "#/components/schemas/CreateCompassOfflineExportTaskResponseDataTask" description: The task for creating downloadable files CreateCompassOfflineExportTaskResponseDataTask: type: object properties: id: type: string description: the id of the task. CreateConversationRequest: type: object properties: buyer_user_id: type: string description: |- Buyer's user ID The value is the same as `data.orders.user_id` in the response data of [Get Order Detail](650aa8ccc16ffe02b8f167a0). required: - buyer_user_id CreateConversationResponse: 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/CreateConversationResponseData" CreateConversationResponseData: type: object properties: conversation_id: type: string description: |- Converstaion ID. The unique identifier for a conversation between the buyer and a shop. CreateCustomBrandsRequest: type: object properties: name: type: string description: |- The brand name. **Note**: - Length: [2, 30] - No language restrictions, but do not use Chinese. - Do not use a name that already exists. - Do not include special fonts or emoticons. - Do not include 5 or more consecutive numbers. - The name will not be translated into multiple languages. required: - name CreateCustomBrandsResponse: 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/CreateCustomBrandsResponseData" CreateCustomBrandsResponseData: type: object properties: id: type: string description: A unique ID that identifies the brand in TikTok Shop. CreateCustomEngagementTaskRequest: type: object properties: task_name: type: string description: "The name of the task. Length: 1–256 bytes when UTF-8 encoded." end_time: type: integer format: int64 description: The time at which the task ends, and messages will no longer be sent. Unix timestamp (seconds). channel: type: string description: The engagement channel. Only `TIKTOK_IM` is supported. product_ids: type: array items: type: string maxItems: 4 description: |- The product IDs that you want to include as interactive cards in the message. Retrieve this value from the [Search Products API](https://partner.tiktokshop.com/docv2/page/65854ffb8f559302d8a6acda). Max count: 4 coupon_ids: type: array items: type: string maxItems: 1 description: |- The coupon IDs that you want to include as interactive cards in the message. Max count: 1 You can only add coupons that have one of these sets of property: - `coupons.display_type=REGULAR` and `coupons.target_buyer_segment=ALL` - `coupons.display_type=REGULAR` and `coupons.target_buyer_segment=REPEAT_CUSTOMERS`. Find out the coupon ID and properties from the [Search Coupons API](https://partner.tiktokshop.com/docv2/page/6699dcdf115ebe02f841e4cd). custom_message: $ref: "#/components/schemas/CreateCustomEngagementTaskRequestCustomMessage" description: The custom message to send to customers. required: - task_name - end_time - channel CreateCustomEngagementTaskRequestCustomMessage: type: object properties: title: type: string description: |- The message title. - Valid format: plain text, unicode emoji (UTF-8) - Valid length: 1–70 Unicode code points. body: type: string description: |- The message body. - Valid format: plain text, unicode emoji (UTF-8) - Valid length: 1–500 Unicode code points. CreateCustomEngagementTaskResponse: 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/CreateCustomEngagementTaskResponseData" CreateCustomEngagementTaskResponseData: type: object properties: task_id: type: string description: The unique identifier for the customer engagement task. Pass this value in the [Send Engagement Message API](67777e448e882e030d29676e) to associate the task with the message sending operation. CreateEngagementTaskRequest: type: object properties: template_id: type: string description: The ID of engagement message templates predefined by TikTok Shop. Retrieve the value from [Get Message Templates](67777e44223fde02fdfdc157). task_name: type: string description: "The name of the task. Length: 1–256 bytes." end_time: type: integer format: int64 description: The time at which the task ends, and messages will no longer be sent. Unix timestamp (seconds). channel: type: string description: The engagement channel. Only `TIKTOK_IM` is supported. product_ids: type: array items: type: string description: The product ID. Retrieve this value from the [Search Products API](https://partner.tiktokshop.com/docv2/page/65854ffb8f559302d8a6acda). coupon_ids: type: array items: type: string description: |- The coupon ID. Retrieve this value and other coupon-related information from the [Search Coupons API](https://partner.tiktokshop.com/docv2/page/6699dcdf115ebe02f841e4cd). **Note**: The coupon properties must comply with the rules defined in `coupon_card_rules.coupon_type` of the [Get Message Templates API](67777e44223fde02fdfdc157). required: - template_id - task_name - end_time - channel CreateEngagementTaskResponse: 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/CreateEngagementTaskResponseData" CreateEngagementTaskResponseData: type: object properties: task_id: type: string description: The unique identifier for the customer engagement task. Pass this value in the [Send Engagement Message API](67777e448e882e030d29676e) to associate the task with the message sending operation. CreateFBTGoodsRequest: type: object properties: create_goods_dto_list: type: array items: $ref: "#/components/schemas/CreateFBTGoodsRequestCreateGoodsDtoList" description: List of goods records to create. required: - create_goods_dto_list CreateFBTGoodsRequestCreateGoodsDtoList: type: object properties: tts_sku_id: type: string description: Identifier for Stock Keeping Unit (SKU) generated by TikTok Shop system create_goods_type: type: string description: "Type of create-goods operation. Current supported value: CREATE_AND_BIND." goods_name: type: string maxLength: 255 description: "Name of the goods. Maximum length: 255 characters." goods_image_url: type: string description: Image URL for the goods. reference_code: type: string maxLength: 50 description: "Reference code for the goods. Maximum length: 50 characters." barcode_infos: type: array items: $ref: "#/components/schemas/BarcodeInfo" description: Barcodes for the goods. For each goods record, provide at most one UPC, EAN, or GTIN in total, at most five ASIN_OR_FNSKU values, and at most five MERCHANT_SKU_ID values. return_handling_method: type: string enum: - COLLECT_RETURN_UNITS - RESTOCK_SELLABLE_COLLECT_UNSELLABLE - RESTOCK_SELLABLE_DISPOSE_UNSELLABLE - DISPOSAL_WITHOUT_INSPECTION - RETURN_WITHOUT_INSPECTION - RESTOCK_SELLABLE_RETURN_UNSELLABLE description: |- Return handling method for the FBT customer return service. The default value will be Restock sellable, Dispose unsellable. Possible values: - COLLECT_RETURN_UNITS - RESTOCK_SELLABLE_COLLECT_UNSELLABLE - RESTOCK_SELLABLE_DISPOSE_UNSELLABLE - DISPOSAL_WITHOUT_INSPECTION - RETURN_WITHOUT_INSPECTION - RESTOCK_SELLABLE_RETURN_UNSELLABLE dimension_and_weight_base_info: $ref: "#/components/schemas/CreateFBTGoodsRequestCreateGoodsDtoListDimensionAndWeightBaseInfo" description: Dimensions and weight for the goods. weight_value, length_value, width_value, and height_value must each be a numeric string greater than 0. is_hazmat: type: boolean description: whether is hazmat goods hazmat_info: $ref: "#/components/schemas/HazmatInfo" description: Hazardous-material details. Required when is_hazmat is true. For hazmat_type BATTERY, FLAMMABLE_LIQUID, or AEROSOLS, provide battery_extra_info, flammable_liquids_extra_info, or aerosol_extra_info, respectively. is_lot_code: type: boolean description: Whether lot-code management is enabled for the goods. is_expiration_management: type: boolean description: Whether shelf-life management is enabled for the goods. When true, shelf_life_attribute_info is required. shelf_life_attribute_info: $ref: "#/components/schemas/ShelfLifeAttributeInfo" description: Shelf-life attributes for the goods. The cutoff values must be nonnegative and satisfy sales_cutoff_days < expiration_alert_days < inbound_cutoff_days. If provided, shelf_life must be less than 3650 days. is_sioc: type: boolean description: A flag indicating whether the goods is under sioc sioc_attribute: $ref: "#/components/schemas/SiocAttribute" description: sioc info bulky_item_attribute: $ref: "#/components/schemas/CreateFBTGoodsRequestCreateGoodsDtoListBulkyItemAttribute" description: bulky item info goods_safety_attributes: $ref: "#/components/schemas/GoodsSafetyAttribute" description: safety attribute info required: - tts_sku_id - create_goods_type - goods_name - goods_image_url - return_handling_method - dimension_and_weight_base_info - is_hazmat - is_lot_code - is_expiration_management CreateFBTGoodsRequestCreateGoodsDtoListBulkyItemAttribute: type: object properties: is_bulky_item_accessories: type: boolean description: whether the goods is bulky accessories CreateFBTGoodsRequestCreateGoodsDtoListDimensionAndWeightBaseInfo: type: object properties: weight_value: type: string description: Weight of the goods in the specified weight_unit. length_value: type: string description: Length of the goods in the specified dimension_unit. width_value: type: string description: Width of the goods in the specified dimension_unit. height_value: type: string description: Height of the goods in the specified dimension_unit. weight_unit: type: string description: "Weight unit. Possible values: MILLIGRAM (mg), GRAM (g), KILOGRAM (kg), POUND (lb), OUNCE (oz)." dimension_unit: type: string description: "Dimension unit. Possible values: MILLIMETER (mm), CENTIMETER (cm), METER (m), FOOT (ft), INCH (in)." required: - weight_value - length_value - width_value - height_value - weight_unit - dimension_unit CreateFBTGoodsResponse: 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/CreateFBTGoodsResponseData" CreateFBTGoodsResponseData: type: object properties: create_result_info: $ref: "#/components/schemas/CreateFBTGoodsResponseDataCreateResultInfo" description: Goods creation result information. CreateFBTGoodsResponseDataCreateResultInfo: type: object properties: create_result_list: type: array items: $ref: "#/components/schemas/CreateFBTGoodsResponseDataCreateResultInfoCreateResultList" description: List of goods creation results. CreateFBTGoodsResponseDataCreateResultInfoCreateResultList: type: object properties: tts_sku_id: type: string description: Identifier for the SKU generated by TikTok Shop system. is_success: type: boolean description: Whether the goods creation succeeded. tts_goods_id: type: string description: Identifier of the FBT goods record. Returned when is_success is true. fail_reason: type: string description: Reason the goods record was not created. Returned when is_success is false. CreateFBTMCFOrderRequest: type: object properties: external_order_id: type: string description: "The corresponding order ID in your OMS. Maximum UTF-8 length: 127 bytes. It must be unique among active MCF orders for the same merchant. Reusing an `external_order_id` from an active order is rejected as a duplicate and is not an idempotent retry." goods: type: array items: $ref: "#/components/schemas/CreateFBTMCFOrderRequestGood" description: The item IDs and quantities included in the order. The array must contain at least one item, and each item must be managed in the FBT system. The sum of `quantity` across all entries in `goods` must not exceed 50. consignee: $ref: "#/components/schemas/CreateFBTMCFOrderRequestConsignee" description: The consignee contact info required: - external_order_id - goods - consignee CreateFBTMCFOrderRequestConsignee: type: object properties: name: type: string description: The consignee name. Must not exceed 128 UTF-8 bytes. phone_number: type: string description: The phone number of consignee email: type: string description: The email of consignee address: $ref: "#/components/schemas/CreateFBTMCFOrderRequestConsigneeAddress" description: The consignee address must be a valid address; if the address verification fails, no order will be created. required: - name - phone_number - email - address CreateFBTMCFOrderRequestConsigneeAddress: type: object properties: country_code: type: string description: The consignee address country code in two-character ISO 3166-1 alpha-2 format. Only `US` is accepted. state_or_region: type: string description: Consignee address state or region district_or_county: type: string description: Consignee address district or county city: type: string description: Consignee address city address_line_1: type: string description: The detail address line 1 address_line_2: type: string description: The detail address line 2 postal_code: type: string description: The 5-digit US ZIP code for the consignee address. required: - country_code - state_or_region - city - address_line_1 CreateFBTMCFOrderRequestGood: type: object properties: id: type: string description: The goods ID generated by the Fulfilled by TikTok system. The value must be a positive base-10 integer string. quantity: type: integer format: int64 description: The quantity of this item. Must be greater than 0. required: - id - quantity CreateFBTMCFOrderResponse: 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/CreateFBTMCFOrderResponseData" CreateFBTMCFOrderResponseData: type: object properties: mcf_order: $ref: "#/components/schemas/CreateFBTMCFOrderResponseDataMcfOrder" description: Information about the successfully created MCF order. On a successful response, this object contains `mcf_order_id`, `external_order_id`, and `create_time`. CreateFBTMCFOrderResponseDataMcfOrder: 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 create_time: type: integer format: int64 description: The Unix timestamp, in seconds, when the MCF order was created. CreateFirstMileBundleRequest: type: object properties: order_ids: type: array items: type: string description: |- The IDs of all the orders sent in a single first-mile bundle. Maximum: 9,999 order IDs per request. The orders must follow the restrictions: - Each of the orders must exist and be RTS and shipping label printed. - The orders are sent by the same seller. - The orders belong to a single group of TikTok Shop service districts. The groups are: - Group 1: PH, SG, MY, VN, TH, and JP. - Group 2: DE, FR, IT, ES. You can not create first mile bundles for US/UK orders using this API. handover_method: type: string enum: - PICKUP - DROP_OFF x-enum-descriptions: - You use the logistic service provided by TikTok Shop to send the bundle. - You contact the logistic provider and send the bundle. The logistic provider must be registered at TikTok Shop. description: |- The way you send the first-mile bundle. Possible enumerations are: - `PICKUP`: You use the logistic service provided by TikTok Shop to send the bundle. - `DROP_OFF`: You contact the logistic provider and send the bundle. The logistic provider must be registered at TikTok Shop. shipping_provider_id: type: string description: The logistic provider ID in TikTok Shop. Required when `handover_method == DROP_OFF`. tracking_number: type: string description: The logistic tracking number of the bundle. Required when `handover_method == DROP_OFF`. phone_tail_number: type: string description: Last 4 digits of the sender's phone number. Required when `handover_method == DROP_OFF`. required: - order_ids - handover_method CreateFirstMileBundleResponse: 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/CreateFirstMileBundleResponseData" CreateFirstMileBundleResponseData: type: object properties: first_mile_bundle_id: type: string description: The ID of the first-mile bundle. url: type: string description: The returned waybill link. errors: type: array items: $ref: "#/components/schemas/CreateFirstMileBundleResponseDataError" description: Errors associated with requested orders. An entry can indicate that the requested order could not be resolved, or that a package associated with the order could not be included in the bundle. Check this array and `first_mile_bundle_id` even when the top-level response code is `0`. A present `first_mile_bundle_id` identifies the created bundle; if it is absent, this response does not identify a created bundle. CreateFirstMileBundleResponseDataError: type: object properties: code: type: integer format: int64 description: The code for the error associated with the requested order identified by `detail.order_id`. message: type: string description: The message that explains the error associated with the requested order identified by `detail.order_id`. detail: $ref: "#/components/schemas/CreateFirstMileBundleResponseDataErrorDetail" description: Error detail CreateFirstMileBundleResponseDataErrorDetail: type: object properties: order_id: type: string description: TikTok Shop order ID CreateFirstMileBundleV2Request: type: object properties: order_ids: type: array items: type: string description: |- The IDs of all the orders sent in a single first-mile bundle. Maximum: 9,999 order IDs per request. The orders must follow the restrictions: - Each of the orders must exist and be RTS and shipping label printed. - The orders are sent by the same seller. - The orders belong to a single group of TikTok Shop service districts. The groups are: - Group 1: PH, SG, MY, VN, TH, and JP. - Group 2: DE, FR, IT, ES. You can not create first mile bundles for US/UK orders using this API. handover_method: type: string enum: - PICKUP - DROP_OFF x-enum-descriptions: - You use the logistic service provided by TikTok Shop to send the bundle. - You contact the logistic provider and send the bundle. The logistic provider must be registered at TikTok Shop. description: |- The way you send the first-mile bundle. Possible enumerations are: - `PICKUP`: You use the logistic service provided by TikTok Shop to send the bundle. - `DROP_OFF`: You contact the logistic provider and send the bundle. The logistic provider must be registered at TikTok Shop. shipping_provider_id: type: string description: The logistic provider ID in TikTok Shop. Required when `handover_method == DROP_OFF`. tracking_number: type: string description: The logistic tracking number of the bundle. Required when `handover_method == DROP_OFF`. phone_tail_number: type: string description: Last 4 digits of the sender's phone number. Required when `handover_method == DROP_OFF`. required: - order_ids - handover_method CreateFirstMileBundleV2Response: 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/CreateFirstMileBundleV2ResponseData" CreateFirstMileBundleV2ResponseData: type: object properties: first_mile_bundle_id: type: string description: The ID of the first-mile bundle. url: type: string description: The returned waybill link. errors: type: array items: $ref: "#/components/schemas/CreateFirstMileBundleResponseDataError" description: Errors associated with requested orders. An entry can indicate that the requested order could not be resolved, or that a package associated with the order could not be included in the bundle. Multiple errors may be returned, including when the top-level `code` is `0`. CreateGPAUpgradeTaskRequest: type: object properties: {} CreateGPAUpgradeTaskResponse: 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/CreateGPAUpgradeTaskResponseData" CreateGPAUpgradeTaskResponseData: type: object properties: {} CreateGlobalProductRequest: type: object properties: title: type: string description: |- The product title. Title length: - DE, ES, FR, IE, IT, JP, UK, US: [1, 255] - MX:[1,300] - Other regions: [25, 255] description: type: string maxLength: 10000 description: |- The product description in HTML format. **Note**: - 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 `
` tags as images. - Max length: 10,000 characters. - Image guidelines: You must use [TikTok Shop image URLs](6509df95defece02be598a22). Max 30 `` tags, each under 4000px with `src`, `width`, and `height` attributes. **Recommendations**: - If you are syncing a pre-existing description from another platform, include the full HTML source description here. - Provide a detailed description, ideally over 300 characters. - Include 3-5 key selling points, each under 250 characters, with supporting images. - Use 1600x1600 px for the image dimensions. category_id: type: string description: |- The ID of the category of this product. - It must be a leaf category that corresponds to the category tree type specified in the `category_version` property. - It must be a main category (`categories.permission_statuses=AVAILABLE` in [Get Global Categories API](650a03f8f1fd3102b91b338a)). **Note**: Refer to TikTok Shop Academy for information on product category restrictions. brand_id: type: string description: |- The ID of the brand of this product. **Note**: Unauthorized brands won't be displayed on TikTok Shop. main_images: type: array items: $ref: "#/components/schemas/MainImage" maxItems: 9 description: |- A list of images to display in the product image gallery. - Max count: 9 - Arrange your image URIs in the sequence that they should appear on TikTok Shop. - Image dimensions: [300x300 px, 4000x4000 px] **Recommendations**: - Use a minimum of 5 images. - The first image should have a white background. Use the [Optimize Images API](https://partner.tiktokshop.com/docv2/page/665692b35d39dc02deb49a97) to change the background to white. skus: type: array items: $ref: "#/components/schemas/CreateGlobalProductRequestSku" description: |- A list of global Stock Keeping Units (SKUs) used to identify distinct variants of the product. **Note**: - Max SKUs for EU, JP, UK, US: 300 - Max SKUs for other regions: 100 **Recommendations**: Place the most important variant at the beginning of the array. package_weight: $ref: "#/components/schemas/PackageWeight" description: |- The weight of the product package. **Note**: - Provide the weight measured after packing the product. - This value impacts the shipping cost, so it is important to ensure that the measurements are accurate. Any discrepancies may lead to additional shipping fees. - The package weight will take precedence over package dimensions in fee calculation if the fee based on weight is higher. certifications: type: array items: $ref: "#/components/schemas/CreateGlobalProductRequestCertification" maxItems: 10 description: |- The list of certifications for your product. Max count: 10 As per TikTok Shop guidelines, certifications are required for certain restricted product categories. Retrieve the certification requirements for your product from the [Get Global Category Rules API](https://partner.tiktokshop.com/docv2/page/650a056df1fd3102b91b5b8e). Refer to [TikTok Shop Restricted Products Policy](https://seller-us.tiktok.com/university/essay?identity=1&role=1&knowledge_id=3238037484275457&from=policy) for information on product category restrictions. package_dimensions: $ref: "#/components/schemas/PackageDimension" description: |- The dimensions of the product package. **Note**: - Provide the dimensions measured after packing the product. - These values impact the shipping cost, so it is important to ensure that dimensions are accurate. Any discrepancies may lead to additional shipping fees. product_attributes: type: array items: $ref: "#/components/schemas/ProductAttribute" description: |- A list of general attributes (e.g. manufacturer, country of origin, materials used) that describe the product as a whole, regardless of variant. **Important**: The attributes available for use are determined by the system based on the product's assigned category, with some being mandatory. You must provide the product attributes marked as `is_required` in the response of the [Get Global Attributes API](https://partner.tiktokshop.com/docv2/page/650a0483c16ffe02b8dfc80a). size_chart: $ref: "#/components/schemas/SizeChart" description: |- The measurement details of the product to help buyers find the right size. **Note**: - For certain product categories, size charts may be required or not supported. Use the [Get Global Category Rules API](https://partner.tiktokshop.com/docv2/page/650a056df1fd3102b91b5b8e) to check the requirements. - If size charts are not supported, even if you provide a size chart here, the size chart will not be saved. - Provide either a TikTok Shop size chart template ID or a size chart image; if both are provided, the ID takes priority. video: $ref: "#/components/schemas/Video" description: |- A product introduction or promotion video to display for your product. **Recommendations**: - Aspect ratio: 1:1 - Resolution: HD 720p or higher - Duration: 20 - 60 seconds manufacturer: $ref: "#/components/schemas/Manufacturer" description: |- (**Deprecated**: This field is deprecated and will be removed in a future API version. Use `manufacturer_ids` instead.) The product manufacturer's details. **Note**: You must fill in all the nested properties for the manufacturer's information to be valid. deprecated: true category_version: type: string description: |- Filter categories by the category tree version.Possible values based on region: - US, EU and SEA: v2, represents the 7-level category tree. Important: For US, EU and SEA shops, you must pass v2 when using this API. - Other regions: v1, represents the 3-level category tree.Default: v1 responsible_person_ids: type: array items: type: string description: |- A list of responsible person IDs. Retrieve the IDs from the [Search Responsible Persons API](67066a55f17b7d02f95d2fb1). **Note**: Applicable only for the EU market in certain categories. Use the [Get Global Category Rules API](650a056df1fd3102b91b5b8e) to check the requirements. manufacturer_ids: type: array items: type: string description: |- A list of manufacturer IDs. Retrieve the IDs from the [Search Manufacturers API](67066a580dcee902fa03ccf9). **Note**: Applicable only for the EU market in certain categories. Use the [Get Global Category Rules API](650a056df1fd3102b91b5b8e) to check the requirements. source_locale: 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 description: |- The BCP-47 locale codes for displaying category information. Default: The default locale of your shop. Possible values: - `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` external_global_product_id: type: string maxLength: 999 description: |- An external identifier used in an external ecommerce platform. This is used to associate the global product between TikTok Shop and the external ecommerce platform. Max length: 999 characters required: - title - description - category_id - main_images - skus - package_weight CreateGlobalProductRequestCertification: type: object properties: id: type: string description: |- The ID to identify the type of certification required for the product category. Retrieve this value from the [Get Global Category Rules API](https://partner.tiktokshop.com/docv2/page/650a056df1fd3102b91b5b8e). 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. required: - id CreateGlobalProductRequestSku: type: object properties: global_quantity: type: integer format: int64 description: |- The total SKU inventory quantity across all shops globally. The inventory for each local shop is automatically calculated when a product is first published. After publishing, this global quantity cannot be manually changed. You can only modify the inventory quantity in each local shop. sales_attributes: type: array items: $ref: "#/components/schemas/CreateGlobalProductRequestSkuSalesAttribute" description: |- A list of attributes (e.g. size, color, length) that define each variant of a product. **Note**: - You can omit this object if there is only 1 SKU. Otherwise, this is **required**. - You can only have up to 3 types of sales attributes per product. - Each SKU must include the same number and type of sales attributes. For example, you cannot have one SKU that has only a Color attribute, while another SKU has both Color and Size attributes. - Provide either a built-in ID or a custom name; if both are provided, the ID takes priority. - The `id/name` and `value_id/value_name` pairs must be unique in each SKU. For example, you cannot repeat `"name": "Color"`, `"value_name": "Red"` in different SKUs. seller_sku: type: string minLength: 1 maxLength: 50 description: |- An internal code/name for managing SKUs, not visible to buyers. - Valid length: 1-50 characters - Format: Text without spaces price: $ref: "#/components/schemas/CreateGlobalProductRequestSkuPrice" description: |- The SKU's **global uniform pre-tax** price that serves as the baseline for calculating the local prices across different markets. **Note**: - Upon publishing, this price will be automatically converted to the local pre-tax price and local display price based on market-specific exchange rates and applicable charges such as shipping costs, taxes, and other fees. - The auto-conversion will exclude JP and US shops using China warehouses. identifier_code: $ref: "#/components/schemas/IdentifierCode" description: |- A regulated identifier code assigned to a product based on international standardized regulations (e.g. GTIN) to ensure the product is universally identifiable across various platforms and systems. **IMPORTANT**: This object and its values can only be modified when the product is in DRAFT status. Once submitted for review, changes are not allowed. Please define the values carefully. inventory: type: array items: $ref: "#/components/schemas/CreateGlobalProductRequestSkuInventory" maxItems: 50 description: |- SKU inventory information per warehouse. If multi-warehouse is enabled in Seller Center, you must provide the inventory details for each warehouse. Max count: 50 **Note**: `global_quantity` will not take effect if inventory details are provided for each warehouse. sku_unit_count: type: string description: |- The total quantity/volume of the product represented by the SKU. For example, if the SKU represents 500ml of water, this value would be 500 if the unit type is defined as ml. Valid range: [0.01, 99,999.9999] Applicable only for the EU market. **Note**: - This is mainly used to calculate the unit price of the SKU, and is required only if you wish to display the unit price to facilitate easier price comparisons across different products and packaging sizes. - Unit price = Selling price/(SKU unit count/base unit count). Therefore if you want to obtain the unit price, you would also need to define the "base unit count" and the "unit type" product attributes. Retrieve the relevant information for these product attributes by using the [Get Global Attributes API](650a0483c16ffe02b8dfc80a). The unit price would then be returned in the [Get Global Product API](6509e2b0bace3e02b7490c96). extra_identifier_codes: type: array items: type: string description: |- If the SKU belongs to a virtual bundle (containing multiple individual SKUs), you can add up to 10 additional identifier codes here for the SKUs included in the bundle. **Format**: GTIN: 14 digits EAN: 8, 13, or 14 digits UPC: 12 digits ISBN: 13 digits, or 9 digits ending in capital `X` **Note**: - Applicable only for the EU market. - The identifier code must be unique for each SKU, with no repetition allowed. external_global_sku_id: type: string maxLength: 999 description: |- An external identifier used in an external ecommerce platform. This is used to associate the global SKU between TikTok Shop and the external ecommerce platform. Max length: 999 characters required: - price CreateGlobalProductRequestSkuInventory: type: object properties: global_warehouse_id: type: string description: |- The ID of the global warehouse where the SKU is stored. Retrieve the list of global warehouses available for the seller from the [Get Global Seller Warehouse API](https://partner.tiktokshop.com/docv2/page/650aa3f0defece02be6e5ffb). quantity: type: integer format: int64 minimum: 1 maximum: 99999 description: |- The SKU quantity available in the warehouse. Valid range: [1, 99,999] required: - global_warehouse_id - quantity CreateGlobalProductRequestSkuPrice: type: object properties: amount: type: string description: |- The price amount. Max: 99,999,999.99 currency: type: string enum: - USD - EUR x-enum-descriptions: - Applicable for global sellers - Applicable for intra-EU sellers description: |- The currency. Possible values: - `USD`: Applicable for global sellers - `EUR`: Applicable for intra-EU sellers required: - amount - currency CreateGlobalProductRequestSkuSalesAttribute: type: object properties: id: type: string description: The ID of a built-in sales attribute, retrieved from [Get Global Attributes API](https://partner.tiktokshop.com/docv2/page/650a0483c16ffe02b8dfc80a). name: type: string maxLength: 20 description: |- A self-defined custom sales attribute name if the built-in attributes do not satisfy your needs. TikTok Shop generates an ID when the global product is created and returns it in `data.global_skus[].sales_attributes[].id`. **Note**: - Do not include sensitive characters. - Max length: 20 characters value_id: type: string description: The ID of a built-in sales attribute value, retrieved from the [Get Global Attributes API](https://partner.tiktokshop.com/docv2/page/650a0483c16ffe02b8dfc80a). value_name: type: string maxLength: 50 description: |- A self-defined custom sales attribute value if the built-in values do not satisfy your needs. TikTok Shop generates an ID when the global product is created and returns it in `data.global_skus[].sales_attributes[].value_id`. **Note**: - No duplicates allowed under the same attribute. - Max length: 50 characters. - Supports only alphabets and numbers. sku_img: $ref: "#/components/schemas/SkuImg" description: |- An image to display for the SKU. You can attach images to only 1 type of sales attribute, and you must attach an image for each value of the chosen attribute. For example, if a product has 2 colors and 3 sizes, you can choose to attach images for either the Color sales attribute or the Size sales attribute. If you choose to attach images for Color, you must attach 2 images, one for each color. CreateGlobalProductResponse: 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/CreateGlobalProductResponseData" CreateGlobalProductResponseData: type: object properties: global_product_id: type: string description: The global product ID generated by TikTok Shop. global_skus: type: array items: $ref: "#/components/schemas/GlobalSku" description: A list of global Stock Keeping Units (SKUs) used to identify distinct variants of the product. CreateImageTranslationTasksRequest: type: object properties: images: type: array items: $ref: "#/components/schemas/CreateImageTranslationTasksRequestImage" description: |- The list of images to translate. Use the [Upload Product Image API](https://partner.tiktokshop.com/docv2/page/6509df95defece02be598a22) to upload the images first and obtain the corresponding image URIs. **Note**: A request can contain at most 20 image URI and target language combinations in total. The recommendations to specify up to 5 images and up to 20 target languages are not independent limits that can be used together; the total number of combinations must remain 20 or fewer. For example, you can submit 10 images with 2 target languages each, but you can't submit 10 images with 5 target languages each. required: - images CreateImageTranslationTasksRequestImage: type: object properties: image_uri: type: string description: |- The URI of the image, retrieved from the [Upload Product Image API](https://partner.tiktokshop.com/docv2/page/6509df95defece02be598a22) **Recommendation**: Specify up to 5 images to avoid exceeding the task limit per call. target_languages: type: array items: type: string enum: - cs-CZ - da-DK - de-AT - de-BE - de-DE - el-GR - en-GB - en-IE - es-ES - fi-FI - fr-FR - fr-BE - hu-HU - it-IT - nl-NL - nl-BE - pl-PL - pt-PT - sv-SE description: |- The target languages to translate the image into. You can specify multiple target languages for each image. Possible values: - `cs-CZ` - `da-DK` - `de-AT` - `de-BE` - `de-DE` - `el-GR` - `en-GB` - `en-IE` - `es-ES` - `fi-FI` - `fr-FR` - `fr-BE` - `hu-HU` - `it-IT` - `nl-NL` - `nl-BE` - `pl-PL` - `pt-PT` - `sv-SE` Recommendation: Specify up to 20 languages to avoid exceeding the task limit per call. required: - image_uri - target_languages CreateImageTranslationTasksResponse: 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/CreateImageTranslationTasksResponseData" CreateImageTranslationTasksResponseData: type: object properties: translation_tasks: type: array items: $ref: "#/components/schemas/CreateImageTranslationTasksResponseDataTranslationTask" description: |- The list of translation tasks created for the requested images. Each task corresponds to the translation of 1 image into 1 target language. So if you specified 2 target languages for an image, 2 tasks will be created. CreateImageTranslationTasksResponseDataTranslationTask: type: object properties: image_uri: type: string description: The URI of the image to translate. target_language: type: string description: The target language for this translation task. This value corresponds to one of the `target_languages` submitted for the task's `image_uri`. id: type: string description: |- The ID to identify the image translation task. Pass this ID to the [Get Image Translation Tasks API](684f8b2d535a9d048f234564) to retrieve the task status and the translated image URIs. CreateManufacturerRequest: type: object properties: name: type: string maxLength: 255 description: |- The manufacturer name. Chinese characters are not supported. Max length: 255 characters registered_trade_name: type: string maxLength: 200 description: |- The registered trade name of the manufacturer. Chinese characters are not supported. Max length: 200 characters email: type: string description: The manufacturer's email address. Use a valid email format such as `name@example.com`. Chinese characters are not supported. phone_number: $ref: "#/components/schemas/PhoneNumber" description: The phone number of the manufacturer. address: type: string maxLength: 500 description: |- The postal address of the manufacturer. Chinese characters are not supported. Max length: 500 characters locale: type: string enum: - de-DE - en-IE - es-ES - fr-FR - it-IT description: |- The BCP-47 locale code representing the language used for specifying the manufacturer information. Possible values: - de-DE - en-IE - es-ES - fr-FR - it-IT Default: The locale of the seller's registered business address. **Note**: The information provided will be automatically translated into all EU languages supported by TikTok Shop. Ensure the locale matches the language used in field values to avoid inaccurate translations. required: - name - email - phone_number - address CreateManufacturerResponse: 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/CreateManufacturerResponseData" CreateManufacturerResponseData: type: object properties: manufacturer_id: type: string description: A unique ID that identifies the manufacturer in TikTok Shop. CreateOpenCollaborationRequest: type: object properties: product_id: type: string description: The product ID to add to the affiliate open collaboration. Submit one product per request. commission_rate: type: integer format: int64 description: The commission rate for the open collaboration, expressed in hundredths of a percent. For example, `3587` represents `35.87%`. The value must be from `100` to `8000`, inclusive. required: - product_id - commission_rate CreateOpenCollaborationResponse: 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/CreateOpenCollaborationResponseData" CreateOpenCollaborationResponseData: type: object properties: open_collaboration: $ref: "#/components/schemas/CreateOpenCollaborationResponseDataOpenCollaboration" description: The open collaboration. CreateOpenCollaborationResponseDataOpenCollaboration: type: object properties: id: type: string description: The open collaboration identifier. product_id: type: string description: The product identifier. effective_time: type: integer format: int64 description: The time from which the open collaboration commission is effective, expressed as a Unix timestamp in seconds. CreateOrUpdateInboundPlanRequest: type: object properties: plan_id: type: string description: Without plan id it is creating, with plan id it is updating. idempotent_key: type: string description: Idempotency key for creating an inbound plan. Required when `plan_id` is not provided. goods_items: type: array items: $ref: "#/components/schemas/CreateOrUpdateInboundPlanRequestGoodsItem" description: Goods item list. cartons: type: array items: $ref: "#/components/schemas/Carton" description: Carton List. CreateOrUpdateInboundPlanRequestGoodsItem: type: object properties: goods_id: type: string description: The Fulfilled by TikTok goods identifier for this inbound plan item. The goods must belong to the merchant associated with the authenticated seller, be approved for fulfillment, and be matched to an SKU. quantity: type: integer format: int64 description: Quantity of this goods item in the inbound plan. Must be greater than 0. required: - goods_id - quantity CreateOrUpdateInboundPlanResponse: 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/CreateOrUpdateInboundPlanResponseData" CreateOrUpdateInboundPlanResponseData: type: object properties: inbound_plan: $ref: "#/components/schemas/CreateOrUpdateInboundPlanResponseDataInboundPlan" description: Inbound plan. CreateOrUpdateInboundPlanResponseDataInboundPlan: type: object properties: plan_id: type: string description: Plan identifier. CreatePackagesRequest: type: object properties: ship_type: type: string description: |- 1:All the products in one order are shipped in one package with one tracking number 2:Partical products in one parent order are shipped in multiple packages with multiple tracking numbers 3:All the products in multiple orders are shipped in one package with one tracking number. order_id: type: string description: The TikTok Shop order ID. Required when `ship_type` is `1` or `2`; not used when `ship_type` is `3`. order_line_item: type: array items: $ref: "#/components/schemas/CreatePackagesRequestOrderLineItem" description: |- List of order line item IDs. If ship_type=2,This is a required field;If ship_type=1&3,we will not use this field order_list_ids: type: array items: type: string description: The TikTok Shop order IDs to combine into one package. Required when `ship_type` is `3`; provide at least two order IDs. dimension: $ref: "#/components/schemas/CreatePackagesRequestDimension" description: Package dimensions. For `ship_type` `1` and `2`, each dimension must be between 0.01 and 999999 and have no more than two decimal places. shipping_service_id: type: string description: |- Specify the shipping service used. If not specified, use the default service obtained from [Get Eligible Shipping Service](https://partner.tiktokshop.com/docv2/page/650aa6b2bace3e02b75dda4e). weight: $ref: "#/components/schemas/CreatePackagesRequestWeight" description: Package weight. For `ship_type` `1` and `2`, the value must be between 0.01 and 999999 and have no more than two decimal places. required: - ship_type CreatePackagesRequestDimension: type: object properties: length: type: string description: |- Package length. The length, width, and height must be passed together. width: type: string description: |- Package width. The length, width, and height must be passed together. height: type: string description: |- Package height. The length, width, and height must be passed together. unit: type: string enum: - CM - INCH description: |- The unit of measurement for the package dimensions. For packages in the US, use `INCH`. Available values: - `CM` - `INCH` required: - length - width - height - unit CreatePackagesRequestOrderLineItem: type: object properties: order_line_id: type: string description: The TikTok Shop order line item ID. sub_item_id: type: string description: |- Only for virtual bundle items,list of sub item ids. If ship_type=2,This is a required field;If ship_type=1&3,we will not use this field CreatePackagesRequestWeight: type: object properties: value: type: string description: The numerical value of the package weight. unit: type: string enum: - GRAM - POUND description: |- The unit of measurement for the package weight. Available values: - `GRAM` - `POUND` required: - value - unit CreatePackagesResponse: 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/CreatePackagesResponseData" CreatePackagesResponseData: type: object properties: dimension: $ref: "#/components/schemas/Dimension" description: Package dimensions. shipping_service_info: $ref: "#/components/schemas/CreatePackagesResponseDataShippingServiceInfo" description: Information about the shipping service selected for the package. package_id: type: string description: Package ID. weight: $ref: "#/components/schemas/Weight" description: Package weight. create_time: type: integer format: int64 description: |- The time when the product was created. Unix timestamp. CreatePackagesResponseDataShippingServiceInfo: type: object properties: id: type: string description: Shipping service ID. name: type: string description: Shipping service name. price: type: string description: Estimated price for this service. currency: type: string description: Currency of the price. earliest_delivery_days: type: integer format: int64 description: The minimum estimated duration required for package delivery.US only. latest_delivery_days: type: integer format: int64 description: The maximum estimated duration required for package delivery.US only. shipping_provider_id: type: string description: Shipping provider ID.US only. shipping_provider_name: type: string description: Shipping provider name.US only. CreateProductRequest: type: object properties: save_mode: type: string enum: - AS_DRAFT - LISTING x-enum-descriptions: - Save the product as a draft for future editing. - Immediately list the product in the shop. description: |- Indicates how the product should be saved. Possible values: - AS_DRAFT: Save the product as a draft for future editing. - LISTING: Immediately list the product in the shop. Default: LISTING description: type: string maxLength: 10000 description: |- The product description in HTML format. **Note**: - 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 `
` tags as images. - Max length: 10,000 characters. - Image guidelines: You must use [TikTok Shop image URLs](6509df95defece02be598a22). Max 30 `` tags, each under 4000px with `src`, `width`, and `height` attributes. **Recommendations**: - If you are syncing a pre-existing description from another platform, include the full HTML source description here. - Provide a detailed description, ideally over 300 characters. - Include 3-5 key selling points, each under 250 characters, with supporting images. - Use 1600x1600 px for the image dimensions. category_id: type: string description: |- The ID of the category of this product. It must be a leaf category that corresponds to the category tree type specified in the `category_version` property. Use the [Get Categories API](https://partner.tiktokshop.com/docv2/page/6509c89d0fcef602bf1acd9b) to obtain the available categories. **Note**: - Refer to TikTok Shop Academy for information on product category restrictions. - For the US market, if you are creating products in `INVITE_ONLY` categories, you must submit a separate application through the Qualification Center on TikTok Shop Seller Center to gain access. Otherwise, even if the product audit is passed, the product will not be listed and made available to buyers. (The product status will be `PENDING` and the audit status will be `PRE_APPROVED`) - For the Indonesia market, to list a product on both TikTok Shop and Tokopedia, you must use only categories that are available on both platforms. brand_id: type: string description: |- The ID of the brand of this product. Use the [Get Brands API](https://partner.tiktokshop.com/docv2/page/6503075656e2bb0289dd5d01) to get the list of available brands for a shop. **Note**: Unauthorized brands won't be displayed on TikTok Shop. main_images: type: array items: $ref: "#/components/schemas/MainImage" maxItems: 9 description: |- A list of images to display in the product image gallery. - Max count: 9 - Arrange your image URIs in the sequence that they should appear on TikTok Shop. - Image dimensions: [300x300 px, 4000x4000 px] **Recommendations**: - Use a minimum of 5 images. - The first image should have a white background. Use the [Optimize Images API](665692b35d39dc02deb49a97) to change the background to white. skus: type: array items: $ref: "#/components/schemas/CreateProductRequestSku" description: |- A list of Stock Keeping Units (SKUs) used to identify distinct variants of the product. **Note**: - Max SKUs for BR, EU, JP, MX, UK, US: 300 - Max SKUs for other regions: 100 **Recommendations**: Place the most important variant at the beginning of the array. title: type: string description: |- The product title. Title length: - DE, ES, FR, IE, IT, JP, UK, US: [1, 255] - BR, MX: [1, 300] - Other regions: [25, 255] is_cod_allowed: type: boolean description: |- A flag indicating whether to show the Cash On Delivery (COD) payment option during checkout. Use the [Get Category Rules API](https://partner.tiktokshop.com/docv2/page/6509c0febace3e02b74594a9) to check if COD is supported for your product category. Applicable only for the following markets: - Global sellers: MY, PH, SA, TH, VN - Local sellers: ID, MY, PH, SA, TH, VN **Note**: If COD is not supported, the listing will fail if you set this to `true`. certifications: type: array items: $ref: "#/components/schemas/Certification" maxItems: 10 description: |- The list of certifications for your product. Max count: 10 As per TikTok Shop guidelines, certifications are required for certain restricted product categories. Retrieve the certification requirements for your product from the [Get Category Rules API](https://partner.tiktokshop.com/docv2/page/6509c0febace3e02b74594a9). Refer to [TikTok Shop Restricted Products Policy](https://seller-us.tiktok.com/university/essay?identity=1&role=1&knowledge_id=3238037484275457&from=policy) for information on product category restrictions. package_dimensions: $ref: "#/components/schemas/PackageDimension" description: |- The dimensions of the product package. **Note**: - Provide the dimensions measured after packing the product. - These values impact the shipping cost, so it is important to ensure that dimensions are accurate. Any discrepancies in measurements may lead to additional shipping fees. - Optional for ID, TH, VN regions. product_attributes: type: array items: $ref: "#/components/schemas/CreateProductRequestProductAttribute" description: |- A list of general attributes (e.g. manufacturer, country of origin, materials used) that describe the product as a whole, regardless of variant. **Important**: The attributes available for use are determined by the system based on the product's assigned category, with some being mandatory. You must provide the product attributes marked as `is_required` in the response of the [Get Attributes API](6509c5784a0bb702c0561cc8) to avoid listing failure. package_weight: $ref: "#/components/schemas/PackageWeight" description: |- The weight of the product package. **Note**: - All the products package weight is **mandatory by default**, except for products under **Virtual Products** categories. [Get Categories API](https://partner.tiktokshop.com/docv2/page/get-categories-202309) e.g **Digital Games**. - Provide the weight measured after packing the product. - This value impacts the shipping cost, so it is important to ensure that the weight is accurate. Any discrepancies in measurements may lead to additional shipping fees. - The package weight will take precedence over package dimensions in fee calculation if the fee based on weight is higher. video: $ref: "#/components/schemas/Video" description: |- A product introduction or promotion video to display for your product. **Recommendations**: - Aspect ratio: 1:1 - Resolution: HD 720p or higher - Duration: 20 - 60 seconds external_product_id: type: string maxLength: 999 description: |- An external identifier used in an external ecommerce platform. This is used to associate the product between TikTok Shop and the external ecommerce platform. Max length: 999 characters delivery_option_ids: type: array items: type: string description: |- This field is supported for seller accounts in the following regions only: - ID - MX - MY - PH - SG - TH - VN For all other regions, this field is NOT used and will NOT be processed if passed for create, edit, or partial edit operations. The custom delivery option IDs to apply to this product if you want to override the default warehouse delivery options. To retrieve the available option IDs, call [Get Warehouse Delivery Options](650aa46ebace3e02b75d9afa) with `scope=PRODUCT`. **Note**: Leave this field blank to inherit the default delivery options configured for the warehouse. size_chart: $ref: "#/components/schemas/SizeChart" description: |- The measurement details of the product to help buyers find the right size. **Note**: - For certain product categories, size charts may be required or not supported. Use the [Get Category Rules API](https://partner.tiktokshop.com/docv2/page/6509c0febace3e02b74594a9) to check the requirements. - If size charts are not supported, even if you provide a size chart here, the size chart will not be saved. - Provide either a TikTok Shop size chart template ID or a size chart image; if both are provided, the ID takes priority. primary_combined_product_id: type: string description: |- If this product is associated with a virtual bundle, this value is the ID of the primary product in the bundle. **Note**: Required only for virtual bundle products. is_not_for_sale: type: boolean description: |- A flag indicating whether the product is not for sale and only available through Gift with Purchase (GWP) promotions. Such products won't appear in searches or recommendations True: Not for sale False: For sale category_version: type: string description: |- The category tree version to assign this product to. Possible values based on region: - US and SEA regions: `v2`, represents the 7-level category tree. **Important**: For US and SEA shops, you must pass `v2` when using this API. - Other regions: `v1`, represents the 3-level category tree. Default: `v1` manufacturer_ids: type: array items: type: string description: |- A list of manufacturer IDs. Retrieve the IDs from the [Search Manufacturers API](67066a580dcee902fa03ccf9). **Note**: Applicable only for the EU market in certain categories. Use the [Get Category Rules API](6509c0febace3e02b74594a9) to check the requirements. responsible_person_ids: type: array items: type: string description: |- A list of responsible person IDs. Retrieve the IDs from the [Search Responsible Persons API](67066a55f17b7d02f95d2fb1). **Note**: Applicable only for the EU market in certain categories. Use the [Get Category Rules API](6509c0febace3e02b74594a9) to check the requirements. listing_platforms: type: array items: type: string enum: - TOKOPEDIA - TIKTOK_SHOP description: |- The platforms for listing the product. Possible values: - TOKOPEDIA - TIKTOK_SHOP Default: TIKTOK_SHOP Applicable only for sellers that migrated from Tokopedia. shipping_insurance_requirement: type: string enum: - REQUIRED - OPTIONAL - NOT_SUPPORTED x-enum-descriptions: - Shipping insurance is mandatory and buyers can't opt out. - Buyers can choose to purchase shipping insurance through the platform. - Shipping insurance is not supported for the product. description: |- The shipping insurance purchase requirement imposed on buyers for the product. Possible values: - REQUIRED: Shipping insurance is mandatory and buyers can't opt out. - OPTIONAL: Buyers can choose to purchase shipping insurance through the platform. - NOT_SUPPORTED: Shipping insurance is not supported for the product. Default: OPTIONAL Applicable only if the listing platforms include TOKOPEDIA. minimum_order_quantity: type: integer format: int64 minimum: 1 maximum: 20 description: |- The minimum order quantity for the product. Valid range: [1, 20] Applicable only for the Indonesia market and selected sellers in other SEA markets. Contact your account manager for more information about gaining access to this field. is_pre_owned: type: boolean description: |- A flag to indicate if the product is pre-owned. Applicable only if TOKOPEDIA is the sole listing platform. **Note**: To list pre-owned products on the TikTok Shop platform, please specify the ID of one of the designated pre-owned product categories (e.g. pre-owned luxury bags, luggage, and accessories) in `category_id`. idempotency_key: type: string maxLength: 128 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 within the shop for each request to avoid accidental duplicates. It can be used to track requests across the shop. Max length: 128 characters **Note**: We recommend that you generate v4 UUIDs for use as keys. shipping_template_id: type: string description: Identifier of the shipping template that will be bound to the product scheduled_sale: $ref: "#/components/schemas/ScheduledSale" description: Scheduled listing configuration for the product, including whether scheduled listing is enabled and the scheduled listing time. locale: 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 description: |- The BCP-47 locale codes for displaying category information. Default: The default locale of your shop. Possible values: - `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` auto_translate_enabled: type: boolean description: The field works only if products need to list with more than one languages in determined country, otherwise it does not need to fill in. search_terms: type: array items: type: string description: Search terms (ST words). ST words will not be displayed to consumers; they are only used in search engines to increase your search weight and gain more traffic. Please ensure that ST words are consistent with the product description, with a maximum of 15 terms and a total of no more than 250 characters. key_product_features: type: array items: type: string maxItems: 5 description: Key Product Features. They will be displayed in the Product highlight module on the product detail page and will be used by search engines to increase your search weight for more traffic. The total number of items should not exceed 5, and the total character count should not exceed 1500. product_tag_operations: type: array items: $ref: "#/components/schemas/ProductTagOperation" description: "product tag to identity special type product.Possible values: AUCTION" purchase_order_quantity_limit: $ref: "#/components/schemas/PurchaseOrderQuantityLimit" description: Purchase quantity limits applied to each SKU of the product. Use the child fields to set the maximum quantity per order and the cumulative quantity across orders. selling_format: type: string enum: - FIXED_PRICE - FIXED_PRICE_AND_LIVE_AUCTION description: "Choose either Fixed price or Fixed price and LIVE auction. Fixed price is selected by default. LIVE auction requires a starting bid price. Possible values: FIXED_PRICE, FIXED_PRICE_AND_LIVE_AUCTION. If `selling_format` is provided, it takes priority over the legacy `product_tag_operations` field; `product_tag_operations` is used only when `selling_format` is not provided." is_live_quick: type: boolean description: |- false — NORMAL products true — LIVE_QUICK products. Only seller with the required permissions can creat LIVE_QUICK products. Default: false is_blind_box: type: boolean description: "Whether the product is a blind box of lucky bag. For example: PopMart" required: - description - category_id - main_images - skus - title CreateProductRequestProductAttribute: type: object properties: id: type: string description: The ID of the product attribute, retrieved from the [Get Attributes API](https://partner.tiktokshop.com/docv2/page/6509c5784a0bb702c0561cc8). values: type: array items: $ref: "#/components/schemas/CreateProductRequestProductAttributeValue" description: |- A list of selectable values for the product attribute. **Note**: Provide either a built-in ID or a custom name; if both are provided, the ID takes priority. required: - id - values CreateProductRequestProductAttributeValue: type: object properties: id: type: string description: The ID of a built-in product attribute value, retrieved from the [Get Attributes API](https://partner.tiktokshop.com/docv2/page/6509c5784a0bb702c0561cc8). name: type: string maxLength: 2000 description: |- A self-defined custom product attribute value if the built-in values do not satisfy your needs. The system will auto-generate an ID after listing. **Note**: - No duplicates allowed under the same attribute. - Max length: 2000 characters metric_standard_info: $ref: "#/components/schemas/MetricStandardInfo" description: Defines the measurement template information used to describe the measurement standards and metric values configured for the product. CreateProductRequestSku: type: object properties: sales_attributes: type: array items: $ref: "#/components/schemas/CreateProductRequestSkuSalesAttribute" description: |- A list of attributes (e.g. size, color, length) that define each variant of a product. **Note**: - You can omit this object if there is only 1 SKU. Otherwise, this is **required**. - You can only have up to 3 types of sales attributes per product. - Each SKU must include the same number and type of sales attributes. For example, you cannot have one SKU that has only a Color attribute, while another SKU has both Color and Size attributes. - Provide either a built-in ID or a custom name; if both are provided, the ID takes priority. - The `id/name` and `value_id/value_name` pairs must be unique in each SKU. For example, you cannot repeat `"name": "Color"`, `"value_name": "Red"` in different SKUs. inventory: type: array items: $ref: "#/components/schemas/Inventory" description: SKU inventory information. seller_sku: type: string description: |- An internal code/name for managing SKUs, not visible to buyers. Valid length: - DE, ES, FR, IT, PL, NL, BE, CZ, AT, GR, PT, HU: 6-50 characters - Other regions: 1-50 characters Format: - DE, ES, FR, IT, PL, NL, BE, CZ, AT, GR, PT, HU: Use alphabets, numbers, hyphens (-), or underscores (_) only - Other regions: Text without spaces price: $ref: "#/components/schemas/CreateProductRequestSkuPrice" description: SKU pricing information. external_sku_id: type: string maxLength: 999 description: |- An external identifier used in an external ecommerce platform. This is used to associate the SKU between TikTok Shop and the external ecommerce platform. Max length: 999 characters identifier_code: $ref: "#/components/schemas/IdentifierCode" description: |- A regulated identifier code assigned to a product based on international standardized regulations (e.g. GTIN) to ensure the product is universally identifiable across various platforms and systems. **IMPORTANT**: This object and its values can only be modified when the product is in DRAFT status. Once submitted for review, changes are not allowed. Please define the values carefully. combined_skus: type: array items: $ref: "#/components/schemas/CombinedSku" description: If this SKU belongs to a virtual bundle, this object contains the list of individual SKUs that form the bundle (e.g. gift basket, starter pack). sku_unit_count: type: string description: |- The total quantity/volume of the product represented by the SKU. For example, if the SKU represents 500ml of water, this value would be 500 if the unit type is defined as ml. Valid range: [0.01, 99,999.9999] Applicable only for the EU market. **Note**: - This is mainly used to calculate the unit price of the SKU, and is required only if you wish to display the unit price to facilitate easier price comparisons across different products and packaging sizes. - Unit price = Selling price/(SKU unit count/base unit count). Therefore if you want to obtain the unit price, you would also need to define the "base unit count" and the "unit type" product attributes. Retrieve the relevant information for these product attributes by using the [Get Attributes API](https://partner.tiktokshop.com/docv2/page/6509c5784a0bb702c0561cc8). The unit price would then be returned in the [Get Product API](https://partner.tiktokshop.com/docv2/page/6509d85b4a0bb702c057fdda). external_urls: type: array items: type: string description: |- A list of URLs for third-party product listing pages where consumers can place orders. Add this property if you have products listed on third-party sites other than TikTok Shop and would like to map them. Max string length: 500 extra_identifier_codes: type: array items: type: string description: |- If the SKU belongs to a virtual bundle (containing multiple individual SKUs), you can add up to 10 additional identifier codes here for the SKUs included in the bundle. **Format**: GTIN: 14 digits EAN: 8, 13, or 14 digits UPC: 12 digits ISBN: 13 digits, or 9 digits ending in capital `X` **Note**: - Applicable only for the EU market. - The identifier code must be unique for each SKU, with no repetition allowed. pre_sale: $ref: "#/components/schemas/PreSale" description: |- SKU presale information, used to tag a product as a presale product based on its presale type. Omit this object if the product is a regular item. Applicable only if `allowed_special_product_types` from [Get Category Rules](6509c0febace3e02b74594a9) is not empty. **Rules for the US market**: - Regular / Preorder product: Once the product goes live, you cannot change the product type. - Made-to-order product: You can change it to a regular product at any time. list_price: $ref: "#/components/schemas/ListPrice" description: |- The SKU's list price information. This is equivalent to the manufacturer's suggested retail price (MSRP), or the recommended retail price (RRP). Applicable only for the US market. **Note**: This value may appear as the strikethrough price on the product page. However, whether the strikethrough price is shown and the amount shown are subject to the audit team's review and decision based on various pricing information. external_list_prices: type: array items: $ref: "#/components/schemas/ExternalListPrice" description: |- The SKU list price (e.g. MSRP, RRP) or original price information on external ecommerce platforms. Applicable only for selected sellers in the US market. **Note**: This value may appear as the strikethrough price on the product page. However, whether the strikethrough price is shown and the amount shown are subject to the audit team's review and decision based on various pricing information. fees: type: array items: $ref: "#/components/schemas/Fee" description: The fees required for this product based on TikTok Shop policies. Fees are required only for certain product categories, retrieve the requirements from the [Get Category Rules API](https://partner.tiktokshop.com/docv2/page/6509c0febace3e02b74594a9). sku_dimensions: $ref: "#/components/schemas/SkuDimension" description: |- The dimensions of the sku. Note: - Provide the dimensions measured after packing the product. - These values impact the shipping cost, so it is important to ensure that dimensions are accurate. Any discrepancies in measurements may lead to additional shipping fees. - Optional for ID, TH, VN regions. sku_weight: $ref: "#/components/schemas/SkuWeight" description: |- The packaged weight of the SKU. Note: - Provide the weight measured after packing the SKU. - Use the same measurement system for `sku_weight` and `sku_dimensions`; for example, use `KILOGRAM` with `CENTIMETER`. - SKU weight and SKU dimensions can affect shipping costs, so ensure both are accurate. If the fee based on SKU weight is higher than the fee based on SKU dimensions, the weight-based fee takes precedence. required: - inventory - price CreateProductRequestSkuPrice: type: object properties: amount: type: string description: |- **Local sellers/Intra-EU sellers** The SKU's **local display price** shown on the product page before any discounts. Refer to [Product Pricing](https://partner.tiktokshop.com/docv2/page/67e1288d76cfee049d9af858) for the allowed price ranges in each market. currency: type: string enum: - BRL - EUR - GBP - IDR - JPY - MXN - MYR - PHP - SGD - THB - USD - VND x-enum-descriptions: - Brazil - France, Germany, Ireland, Italy, Spain - United Kingdom - Indonesia - Japan - Mexico - Malaysia - Philippines - Singapore - Thailand - United States - Vietnam description: |- The currency. Possible values based on the region: - BRL: Brazil - EUR: France, Germany, Ireland, Italy, Spain - GBP: United Kingdom - IDR: Indonesia - JPY: Japan - MXN: Mexico - MYR: Malaysia - PHP: Philippines - SGD: Singapore - THB: Thailand - USD: United States - VND: Vietnam sale_price: type: string description: |- **Global sellers** The SKU's **local display price** shown on the product page before any discounts. Refer to [Product Pricing](https://partner.tiktokshop.com/docv2/page/67e1288d76cfee049d9af858) for the allowed price ranges in each market. **Note**: - Applicable only for global sellers. - Required for JP and US shops using China warehouses, optional for others. - This is the definitive final price shown on the product page, all other prices will be ignored. starting_bid_price: type: string description: starting bit price for auction product required: - currency CreateProductRequestSkuSalesAttribute: type: object properties: id: type: string description: The ID of a built-in sales attribute, retrieved from [Get Attributes API](https://partner.tiktokshop.com/docv2/page/6509c5784a0bb702c0561cc8). value_id: type: string description: The ID of a built-in sales attribute value, retrieved from the [Get Attributes API](https://partner.tiktokshop.com/docv2/page/6509c5784a0bb702c0561cc8). value_name: type: string maxLength: 50 description: |- A self-defined custom sales attribute value if the built-in values do not satisfy your needs. The system will auto-generate an ID after listing. If you use `save_mode=AS_DRAFT`, the response may also contain a generated ID for this custom value in `data.skus[].sales_attributes[].value_id`. **Note**: - No duplicates allowed under the same attribute. - Max length: 50 characters. sku_img: $ref: "#/components/schemas/SkuImg" description: |- The default/main image for each value (e.g. red) of the primary sales attribute (e.g. color). This appears in the product options gallery on TikTok Shop. You can attach images to only 1 type of sales attribute, which will serve as the primary attribute for display. An image must be provided for each value of the primary attribute. For example, if a product has 2 colors and 3 sizes, you can choose to attach images for either the color sales attribute or the size sales attribute. If you choose to attach images for color, you must attach 2 images, one for each color. If you want to add more images, use `supplementary_sku_images`. name: type: string maxLength: 20 description: |- A self-defined custom sales attribute name if the built-in attributes do not satisfy your needs. The system will auto-generate an ID after listing. If you use `save_mode=AS_DRAFT`, the response may also contain a generated ID for this custom name in `data.skus[].sales_attributes[].id`. **Note**: - Do not include sensitive characters. - Max length: 20 characters supplementary_sku_images: type: array items: $ref: "#/components/schemas/SupplementarySkuImage" description: |- A list of supplementary images for each value (e.g. red) of the primary sales attribute (e.g. color) to provide multiple views or details of the product for that attribute value. These appear in the product options gallery on TikTok Shop. **Note**: - Max number of image URIs: 8. - Arrange your image URIs in the sequence that they should appear on TikTok Shop. - Applicable only for the US market. CreateProductResponse: 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/CreateProductResponseData" CreateProductResponseData: type: object properties: product_id: type: string description: The product ID generated by TikTok Shop. skus: type: array items: $ref: "#/components/schemas/CreateProductResponseDataSku" description: A list of Stock Keeping Units (SKUs) used to identify distinct variants of the product. warnings: type: array items: $ref: "#/components/schemas/Warning" description: Warning information that the API caller needs to pay special attention to. CreateProductResponseDataSku: type: object properties: id: type: string description: The SKU ID generated by TikTok Shop. One product can contain multiple SKU IDs. seller_sku: type: string description: |- An internal code/name for managing SKUs, not visible to buyers. Valid length: - DE, ES, FR, IT, PL, NL, BE, CZ, AT, GR, PT, HU: 6-50 characters - Other regions: 1-50 characters Format: - DE, ES, FR, IT, PL, NL, BE, CZ, AT, GR, PT, HU: Use alphabets, numbers, hyphens (-), or underscores (_) only - Other regions: Text without spaces sales_attributes: type: array items: $ref: "#/components/schemas/SalesAttribute" description: A list of attributes (e.g. size, color, length) that define each variant of a product. external_sku_id: type: string description: An external identifier used in an external ecommerce platform. This is used to associate the SKU between TikTok Shop and the external ecommerce platform. fees: type: array items: $ref: "#/components/schemas/Fee" description: The fees required for this product based on TikTok Shop policies. Fees are required only for certain product categories, retrieve the requirements from the [Get Category Rules API](https://partner.tiktokshop.com/docv2/page/6509c0febace3e02b74594a9). CreatePromotionActivityRequest: type: object properties: title: type: string description: "Unique name across all your activities. Maximum length: 50 characters for `FLASHSALE` and `SHIPPING_DISCOUNT`; 100 characters for `FIXED_PRICE`, `DIRECT_DISCOUNT`, `BUY_MORE_SAVE_MORE`, `BUY_X_GET_Y`, and `GIFT_WITH_PURCHASE`." activity_type: type: string enum: - FIXED_PRICE - DIRECT_DISCOUNT - FLASHSALE - SHIPPING_DISCOUNT - BUY_MORE_SAVE_MORE - GIFT_WITH_PURCHASE - BUY_X_GET_Y x-enum-descriptions: - A product discount activity with a fixed price. - A product discount activity with a percentage discount. - A flash sale activity. - A shipping fee discount activity. - A Buy More Save More promotion. - A Gift With Purchase promotion. - A Buy X Get Y promotion. description: |- The type of promotion activity. Possible values: - `FIXED_PRICE`: A product discount activity with a fixed price. - `DIRECT_DISCOUNT`: A product discount activity with a percentage discount. - `FLASHSALE`: A flash sale activity. - `SHIPPING_DISCOUNT`: A shipping fee discount activity. - `BUY_MORE_SAVE_MORE`: A Buy More Save More promotion. - `GIFT_WITH_PURCHASE`: A Gift With Purchase promotion. - `BUY_X_GET_Y`: A Buy X Get Y promotion. product_level: type: string enum: - PRODUCT - VARIATION - SHOP x-enum-descriptions: - Apply the promotion at the product (SPU) level to all SKUs in each selected product. - Apply the promotion only to selected SKUs. - Apply the promotion to all products in the shop. description: |- The product scope of the activity. Possible values: - `PRODUCT`: Apply the promotion at the product (SPU) level to all SKUs in each selected product. - `VARIATION`: Apply the promotion only to selected SKUs. - `SHOP`: Apply the promotion to all products in the shop. Activity-specific constraints: - `FIXED_PRICE`, `DIRECT_DISCOUNT`, and `FLASHSALE` support `PRODUCT` or `VARIATION`. - `SHIPPING_DISCOUNT` does not support `VARIATION`. - `BUY_MORE_SAVE_MORE` and `BUY_X_GET_Y` support `PRODUCT` or `SHOP`. - `GIFT_WITH_PURCHASE` requires `PRODUCT`. To set the products or SKUs covered by the activity, use [Update Activity Product](https://partner.tiktokshop.com/docv2/page/650d32c42aaa3602b86ccb5c). duration_type: type: string description: |- The effective time type of the current activity - NORMAL: `begin_time` and `end_time` must be filled - INDEFINITE: `begin_time` and `end_time` aren't required, and the promotion will be a long-term activity which runs indefinitely. 1. `INDEFINITE` is only valid when `activity_type` is `SHIPPING_DISCOUNT`, 2. If `duration_type` is `INDEFINITE`, `start_time` and `end_time` should be 0 Default: NORMAL begin_time: type: integer format: int64 description: Activity start time. UNIX timestamp. The value must be greater than the value of the current time. end_time: type: integer format: int64 description: Activity end time as a Unix timestamp in seconds. For `NORMAL` `FIXED_PRICE`, `DIRECT_DISCOUNT`, `FLASHSALE`, `BUY_MORE_SAVE_MORE`, `BUY_X_GET_Y`, and `GIFT_WITH_PURCHASE` activities, it must be at least 600 seconds after `begin_time`. For a `NORMAL` shipping-discount activity, provide a positive value. participation_limit: type: array items: $ref: "#/components/schemas/CreatePromotionActivityRequestParticipationLimit" description: Buyer participation-limit settings. For `BUY_MORE_SAVE_MORE`, `BUY_X_GET_Y`, and `GIFT_WITH_PURCHASE`, provide exactly one entry. discount: $ref: "#/components/schemas/Discount" description: Discount configuration. For `SHIPPING_DISCOUNT`, provide `shipping_discount`; for `BUY_MORE_SAVE_MORE`, provide `bmsm_discount`; for `GIFT_WITH_PURCHASE`, provide `gift_discount`; and for `BUY_X_GET_Y`, provide `bxgy_discount`. This field is not used for `FIXED_PRICE`, `DIRECT_DISCOUNT`, or `FLASHSALE`. target_user_info: $ref: "#/components/schemas/CreatePromotionActivityRequestTargetUserInfo" description: Target-audience configuration for `BUY_MORE_SAVE_MORE`, `BUY_X_GET_Y`, and `GIFT_WITH_PURCHASE` activities. If omitted, the activity targets `ALL_USER`. auction_support_type: type: string enum: - ALL - EXCLUDE_AUCTION x-enum-descriptions: - Support both regular and auction products. - Exclude auction products. description: |- For `SHIPPING_DISCOUNT` activities, determines whether auction products are supported. Possible values: - `ALL`: Support both regular and auction products. - `EXCLUDE_AUCTION`: Exclude auction products. Default: `ALL`. required: - title - activity_type - product_level - begin_time - end_time CreatePromotionActivityRequestDiscountBmsmDiscountDetail: type: object properties: tier: type: integer format: int64 description: "`tier` uses 1-based indexing: the first and second tiers are `1` and `2`, not `0` and `1`. For each subsequent tier, both `threshold_value` and `value` must be greater than those of the previous tier. For example, if tier `1` has `threshold_value` `20` and `value` `15`, tier `2` must have a `threshold_value` greater than `20` and a `value` greater than `15`." threshold_type: type: string enum: - MINIMAL_ITEM_QUANTITY - MINIMAL_ORDER_AMOUNT x-enum-descriptions: - Buyer must meet or exceed the minimum spend criteria with eligible products. - Buyer must meet or exceed the minimum spend criteria with eligible order. description: |- The type of purchase criteria. Possible enumerations are: - `MINIMAL_ITEM_QUANTITY`: Buyer must meet or exceed the minimum spend criteria with eligible products. - `MINIMAL_ORDER_AMOUNT`: Buyer must meet or exceed the minimum spend criteria with eligible order. threshold_value: type: string description: |- The purchase threshold for this tier. - When `threshold_type==MINIMAL_ITEM_QUANTITY`, enter a positive integer. - When `threshold_type==MINIMAL_ORDER_AMOUNT`, enter a positive amount in local currency, with at most two decimal places. type: type: string enum: - PERCENTAGE_OFF - AMOUNT_OFF x-enum-descriptions: - Buyer will receive X% off the price of the eligible products. - Buyer will receive X units of local currency off the price of eligible products. description: |- The type of discount awarded as a benefit. The value of the discount is determined by `value`. Possible enumerations are: - `PERCENTAGE_OFF`: Buyer will receive X% off the price of the eligible products. - `AMOUNT_OFF`: Buyer will receive X units of local currency off the price of eligible products. value: type: string description: |- The discount value. - When `type==PERCENTAGE_OFF`, enter a positive integer percentage. - When `type==AMOUNT_OFF`, enter a positive amount in local currency, with at most two decimal places. required: - tier - threshold_type - threshold_value - type - value CreatePromotionActivityRequestParticipationLimit: type: object properties: type: type: string enum: - BUYER_NO_LIMIT - BUYER_LIMIT_ONLY_ONE x-enum-descriptions: - A buyer can benefit from this activity across multiple orders. - A buyer can benefit from this activity for no more than one order. description: |- Determines whether each buyer can receive the activity benefit more than once. Possible values: - `BUYER_NO_LIMIT`: A buyer can benefit from this activity across multiple orders. - `BUYER_LIMIT_ONLY_ONE`: A buyer can benefit from this activity for no more than one order. required: - type CreatePromotionActivityRequestTargetUserInfo: type: object properties: user_type: type: string enum: - ALL_USER - SHOP_NEW_CUSTOMER - SHOP_EXISTING_CUSTOMER - SHOP_REPEAT_CUSTOMER description: |- Possible enumerations are: `ALL_USER` `SHOP_NEW_CUSTOMER` `SHOP_EXISTING_CUSTOMER` `SHOP_REPEAT_CUSTOMER` CreatePromotionActivityResponse: 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/CreatePromotionActivityResponseData" CreatePromotionActivityResponseData: type: object properties: activity_id: type: string description: On success, the ID of the created activity. Use it as `activity_id` when adding products or SKUs with [Update Activity Product](https://partner.tiktokshop.com/docv2/page/650d32c42aaa3602b86ccb5c). create_time: type: integer format: int64 description: The time when the activity was created. update_time: type: integer format: int64 description: The time when the activity was last updated. status: type: string enum: - DRAFT - NOT_START - ONGOING - EXPIRED - DEACTIVATED - NOT_EFFECTIVE x-enum-descriptions: - Promotion activities with this status are not available to TikTok users. - Promotion activities with this status are not available to TikTok users until the set activity start time. - Promotion activities with this status are available to TikTok users. - Promotion activities with this status are not available to TikTok users because it has expired. - The activity has been deactivated by the seller and is not available to TikTok users. - The activity is terminated by the platform and is not available to TikTok users. description: |- Possible values: - DRAFT: Promotion activities with this status are not available to TikTok users. - NOT_START: Promotion activities with this status are not available to TikTok users until the set activity start time. - ONGOING: Promotion activities with this status are available to TikTok users. - EXPIRED: Promotion activities with this status are not available to TikTok users because it has expired. - DEACTIVATED: The activity has been deactivated by the seller and is not available to TikTok users. - NOT_EFFECTIVE: The activity is terminated by the platform and is not available to TikTok users. CreateResponsiblePersonRequest: type: object properties: name: type: string maxLength: 200 description: |- The responsible person name. Chinese characters are not supported. Max length: 200 characters email: type: string description: The email address of the responsible person. Chinese characters are not supported. phone_number: $ref: "#/components/schemas/CreateResponsiblePersonRequestPhoneNumber" description: The phone number of the responsible person. Chinese characters are not supported in `local_number`. address: $ref: "#/components/schemas/Address" description: The residential address of the responsible person. Chinese characters are not supported in any address field. locale: type: string enum: - de-DE - en-IE - es-ES - fr-FR - it-IT description: |- The BCP-47 locale code representing the language used for specifying the responsible person information. Possible values: - de-DE - en-IE - es-ES - fr-FR - it-IT Default: The locale of the seller's registered business address. **Note**: The information provided will be automatically translated into all EU languages supported by TikTok Shop. Ensure the locale matches the language used in field values to avoid inaccurate translations. required: - name - email - phone_number - address CreateResponsiblePersonRequestPhoneNumber: type: object properties: country_code: type: string description: |- The country code of the phone number, prefixed by a plus `+` symbol. E.g. +353 for Ireland. Only EU country codes are allowed. Max digits: 4 local_number: type: string description: |- The local number. Length: 7 - 11 digits required: - country_code - local_number CreateResponsiblePersonResponse: 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/CreateResponsiblePersonResponseData" CreateResponsiblePersonResponseData: type: object properties: responsible_person_id: type: string description: A unique ID that identifies the responsible person in TikTok Shop. CreateReturnRequest: type: object properties: order_id: type: string description: Tiktok Shop order id skus: type: array items: $ref: "#/components/schemas/Sku" description: Skus order_line_item_ids: type: array items: type: string description: Specifies the order line IDs to include in the return request. Use this field to select order lines when an order is split into multiple packages. Do not provide non-empty values in both `order_line_item_ids` and `order_line_list` in the same request. If `order_line_item_ids`, `order_line_list`, and `skus` are all omitted, all order lines in the order are included. **Note:** This is a legacy field; new integrations should use `order_line_list` instead. return_reason: type: string description: Seller's reason to create a return return_type: type: string description: |- Which type to create: - REFUND - RETURN_AND_REFUND refund_total: type: string description: |- Total refund amount to the buyer. The total refund amount can not exceed the refundable amount currency: type: string description: Currency of the refund amount. It should be the same as the currency of the TikTok Shop order. Required when `refund_total` is provided. shipment_type: type: string description: |- Specifies the return shipping method the buyer uses to send items back to the seller in a return request. Supported values: - `PLATFORM` - `BUYER_ARRANGE` handover_method: type: string description: |- **Optional**. Only applicable when shipment_type is `PLATFORM`. Specifies the handover method the buyer uses to return the item through platform-supported shipping. Supported values: - `DROP_OFF` - `PICKUP` order_line_list: type: array items: $ref: "#/components/schemas/OrderLineList" description: Specifies the line items to include in the return request and supports bundle order splitting. Every entry must include `order_line_item_id`. For a bundle sub-item, also include `sub_order_line_item_id`; omit `sub_order_line_item_id` for a normal order line. Do not mix normal order lines and bundle sub-items in the same request. **Note:** This field is completely backward compatible with the legacy `order_line_item_ids` field. required: - order_id - return_reason - return_type CreateReturnResponse: 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/CreateReturnResponseData" CreateReturnResponseData: type: object properties: return_id: type: string description: The identifier of a specific return request. return_status: type: string enum: - RETURN_OR_REFUND_REQUEST_PENDING - REFUND_OR_RETURN_REQUEST_REJECT - AWAITING_BUYER_SHIP - BUYER_SHIPPED_ITEM - REJECT_RECEIVE_PACKAGE - RETURN_OR_REFUND_REQUEST_SUCCESS - RETURN_OR_REFUND_REQUEST_CANCEL - RETURN_OR_REFUND_REQUEST_COMPLETE x-enum-descriptions: - Request is pending, needs to be approved by seller or platform - Seller rejected the request - Waiting buyer to ship items to seller, if exceed the deadline, request will be closed by platform - Buyer has shipped items to seller. - Seller reject return package - The refund/return request is successful, buyer will be refunded. - The request has been cancelled by buyer or system - The request is successful, and the amount has been refunded. description: |- Return status, available values: - RETURN_OR_REFUND_REQUEST_PENDING: Request is pending, needs to be approved by seller or platform - REFUND_OR_RETURN_REQUEST_REJECT: Seller rejected the request - AWAITING_BUYER_SHIP: Waiting buyer to ship items to seller, if exceed the deadline, request will be closed by platform - BUYER_SHIPPED_ITEM: Buyer has shipped items to seller. - REJECT_RECEIVE_PACKAGE: Seller reject return package - RETURN_OR_REFUND_REQUEST_SUCCESS: The refund/return request is successful, buyer will be refunded. - RETURN_OR_REFUND_REQUEST_CANCEL: The request has been cancelled by buyer or system - RETURN_OR_REFUND_REQUEST_COMPLETE: The request is successful, and the amount has been refunded. CreateSizeChartV2Request: type: object properties: category_id: type: string description: The leaf category for which to create the size chart. The category must support size charts. size_chart_data: $ref: "#/components/schemas/SizeChartData" description: Structured size chart content. size_chart_mode: type: string description: |- Possible values: REUSABLE_TEMPLATE: A size chart template that can be reused across multiple products. PRODUCT_SCOPED: A size chart created for and used by a single product. template_name: type: string description: |- Template name. Required when size_chart_mode is REUSABLE_TEMPLATE. When size_chart_mode is PRODUCT_SCOPED, any value provided for this field is discarded and is not stored. required: - category_id - size_chart_data - size_chart_mode CreateSizeChartV2Response: 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/CreateSizeChartV2ResponseData" CreateSizeChartV2ResponseData: type: object properties: size_chart_id: type: string description: The ID of the created size chart. For REUSABLE_TEMPLATE mode, use this value as size_chart.template.id in subsequent product APIs. For PRODUCT_SCOPED mode, this ID identifies a size chart specific to a single product and cannot be reused as a template ID. CreateTargetCollaborationRequest: type: object properties: name: type: string description: The name of the target collaboration. message: type: string description: The message sent to creators associated with the target collaboration. end_time: type: string description: The date at which the target collaboration ends, in Unix epoch time. products: type: array items: $ref: "#/components/schemas/CreateTargetCollaborationRequestProduct" description: A list of metadata and data for the products provided by the seller for target collaboration. Maximum length of the list is `100` products. creator_user_open_ids: type: array items: type: string description: Maximum length of the list is `50` user open identifiers. Creator Open ID. [More details](https://partner.tiktokshop.com/docv2/page/3obfokj6) seller_contact_info: $ref: "#/components/schemas/SellerContactInfo" description: Metadata and data associated with the seller contact information. free_sample_rule: $ref: "#/components/schemas/FreeSampleRule" description: A set of properties that control the free sample behavior for the product. preferred_content_type: type: string description: preferred creator content type, "LIVE" or "VIDEO" required: - name - end_time - products - creator_user_open_ids - seller_contact_info - free_sample_rule CreateTargetCollaborationRequestProduct: type: object properties: id: type: string description: The product identifier. target_commission_rate: type: integer format: int64 description: The desired commission rate for the target collaboration. The desired commission rate is expressed in hundredths of a percent. For example, `3587` is a commission rate of `35.87%`. This value must a minimum of `100`. shop_ads_commission_rate: type: integer format: int64 description: |- The commission rate applies only to orders generated from ads. If a creator’s video is used as an ad without this rate being set, the resulting orders will instead earn either: - The Shop Ads commission you configured in open collaboration, or - The standard commission defined in this invitation. The commission rate is specified in increments of 1/10,000. For example, 1000 stands for 0.1 or 10%. required: - id - target_commission_rate CreateTargetCollaborationResponse: 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/CreateTargetCollaborationResponseData" CreateTargetCollaborationResponseData: type: object properties: target_collaboration: $ref: "#/components/schemas/CreateTargetCollaborationResponseDataTargetCollaboration" description: The target collaboration. target_collaboration_conflicts: type: array items: $ref: "#/components/schemas/TargetCollaborationConflict" description: A list of user and product identifiers with target collaboration conflicts that caused target collaboration failure. invalid_open_id_list: type: array items: type: string description: The list of open id that caused the create to fail. invalid_product_id_list: type: array items: type: string description: The list of product id that caused the create to fail. create_time: type: integer format: int64 description: The create time of the target collaboration. CreateTargetCollaborationResponseDataTargetCollaboration: type: object properties: id: type: string description: The target collaboration identifier. CreateTime: type: object properties: min_unix_time_inclusive: type: integer format: int64 description: Inclusive lower bound (Unix seconds). max_unix_time_exclusive: type: integer format: int64 description: Exclusive upper bound (Unix seconds). CreateVideoPrecheckTaskRequest: type: object properties: video_info: $ref: "#/components/schemas/CreateVideoPrecheckTaskRequestVideoInfo" description: Video information product_link_info: $ref: "#/components/schemas/ProductLinkInfo" description: Product link information required: - video_info - product_link_info CreateVideoPrecheckTaskRequestVideoInfo: type: object properties: file_id: type: string description: Video file_id from [Upload Shoppable Video File](https://api/affiliate_creator/202505/videos/video_files) required: - file_id CreateVideoPrecheckTaskResponse: 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/CreateVideoPrecheckTaskResponseData" CreateVideoPrecheckTaskResponseData: type: object properties: precheck: $ref: "#/components/schemas/CreateVideoPrecheckTaskResponseDataPrecheck" description: Information about the created video content pre-check task. CreateVideoPrecheckTaskResponseDataPrecheck: type: object properties: task_id: type: string description: The ID of the created video pre-check task. Pass this value as the `task_id` path parameter to `GET /affiliate_creator/202511/videos/precheck_tasks/{task_id}` to retrieve the result. CreatorDeauthorizationWebhook: type: object properties: type: type: integer const: 20 description: The ID of the webhook type. tts_notification_id: type: string description: The ID of the notification. creator_open_id: type: string description: The open_id of the creator. To get the value, see [Authorization overview](authorization-overview-202407). timestamp: type: integer format: int64 description: The UNIX timestamp when this webhook was triggered. data: $ref: "#/components/schemas/CreatorDeauthorizationWebhookData" required: - type CreatorDeauthorizationWebhookData: type: object properties: cancel_time: type: string description: The UNIX timestamp when this event happened. CreatorSearchSampleApplicationFulfillmentsRequest: type: object properties: fulfillment_statuses: type: array items: type: string enum: - PENDING - ONGOING - SUCCEED - FAILED - OVERDUE - SUSPEND - CANCELLED - EXEMPTED x-enum-descriptions: - The creator has not yet fulfilled the content creation obligation. - Fulfillment is in progress; content has been created and is being evaluated against criteria. - Fulfillment has been successfully completed; the content meets the required standards. - Fulfillment failed; the content did not meet the required standards. - Fulfillment is overdue; the creator did not meet the deadline. - Fulfillment has been suspended. - Fulfillment has been cancelled, either by the creator or due to operational reasons. - The creator is exempt from the fulfillment obligation. description: |- A list of fulfillment statuses. The response is filtered to include sample fulfillments with the `status` field set to one of the specified values. The possible values are: - PENDING: The creator has not yet fulfilled the content creation obligation. - ONGOING: Fulfillment is in progress; content has been created and is being evaluated against criteria. - SUCCEED: Fulfillment has been successfully completed; the content meets the required standards. - FAILED: Fulfillment failed; the content did not meet the required standards. - OVERDUE: Fulfillment is overdue; the creator did not meet the deadline. - SUSPEND: Fulfillment has been suspended. - CANCELLED: Fulfillment has been cancelled, either by the creator or due to operational reasons. - EXEMPTED: The creator is exempt from the fulfillment obligation. required: - fulfillment_statuses CreatorSearchSampleApplicationFulfillmentsResponse: 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/CreatorSearchSampleApplicationFulfillmentsResponseData" CreatorSearchSampleApplicationFulfillmentsResponseData: type: object properties: fulfillments: type: array items: $ref: "#/components/schemas/CreatorSearchSampleApplicationFulfillmentsResponseDataFulfillment" description: Creator fulfillment contents. CreatorSearchSampleApplicationFulfillmentsResponseDataFulfillment: type: object properties: id: type: string description: The fulfillment identifier. shop_id: type: string description: The TikTok Shop identifier. application_id: type: string description: The sample application identifier. sample_application_type: type: string enum: - FREE_SAMPLE - SAMPLE_COUPON - SAMPLE_CAMPAIGN - PLATFORM_FREE_SAMPLE - REFUNDABLE_SAMPLE - UNSPECIFIED description: |- The type of the sample application. Possible values: - FREE_SAMPLE - SAMPLE_COUPON - SAMPLE_CAMPAIGN - PLATFORM_FREE_SAMPLE - REFUNDABLE_SAMPLE - UNSPECIFIED product_id: type: string description: The product identifier. expiration_time: type: integer format: int64 description: |- Fulfillment deadline timestamp. Usually the value is `{you_receiving_sample_time} + 14Days`. But if you apply for fulfillment suspension, the value is `{you_receiving_sample_time} + 14Days + total_suspend_duration`. total_suspend_duration: type: integer format: int64 description: The duration you applied for fulfillment suspension in seconds. status: type: string description: |- The fulfillment status.This is an enumerated type with values: - PENDING: The creator has not yet fulfilled the content creation obligation. - ONGOING: Fulfillment is in progress; content has been created and is being evaluated against criteria. - SUCCEED: Fulfillment has been successfully completed; the content meets the required standards. - FAILED: Fulfillment failed; the content did not meet the required standards. - OVERDUE: Fulfillment is overdue; the creator did not meet the deadline.SUSPEND: Fulfillment has been suspended. - CANCELLED: Fulfillment has been cancelled, either by the creator or due to operational reasons. - EXEMPTED: The creator is exempt from the fulfillment obligation. bound_product_status: type: string enum: - UNKNOWN - LIVE - OUT_OF_STOCK - SELLER_DEACTIVATE - PLATFORM_DEACTIVATE - NO_PLAN - PERMANENT_DELETED x-enum-descriptions: - The product's promotion status is unknown. - The product is available for promotion. - The product is out of stock. - The product has been deactivated by the seller. - The product has been deactivated by the platform. - There is no valid plan available for the creator to promote the product. - The product has been permanently deleted and is no longer available. description: |- The promotion status of the product associated with the fulfillment. Possible values: - UNKNOWN: The product's promotion status is unknown. - LIVE: The product is available for promotion. - OUT_OF_STOCK: The product is out of stock. - SELLER_DEACTIVATE: The product has been deactivated by the seller. - PLATFORM_DEACTIVATE: The product has been deactivated by the platform. - NO_PLAN: There is no valid plan available for the creator to promote the product. - PERMANENT_DELETED: The product has been permanently deleted and is no longer available. CurSession: type: object properties: id: type: string description: Current session id. phase: type: string enum: - AUTO_REPLY - QUEUED - ASSIGNED x-enum-descriptions: - The session is being handled by automatic replies or chatbot responses. - The session is waiting to be assigned to an agent. - The session has been assigned to an agent. description: |- Current phase of the session. Possible enumerations: - `AUTO_REPLY` — The session is being handled by automatic replies or chatbot responses. - `QUEUED` — The session is waiting to be assigned to an agent. - `ASSIGNED` — The session has been assigned to an agent. DataPoint: type: object properties: value: type: string description: The value of the metric identified by `stats_type` at this data point. timestamp: type: integer format: int64 description: The time of the data points DeactivateActivityRequest: type: object properties: {} DeactivateActivityResponse: 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/DeactivateActivityResponseData" DeactivateActivityResponseData: type: object properties: activity_id: type: string description: A unique ID that identifies different activities. title: type: string description: Activity name (50 characters max.) The name must be unique. status: type: string description: |- Activity status after successful deactivation. Possible value: - DEACTIVATED: The activity has been deactivated by the seller and is not available to TikTok users. update_time: type: integer format: int64 description: The time when the deactivation response was created, as a Unix timestamp in seconds. DeactivateProductsRequest: type: object properties: product_ids: type: array items: type: string description: |- The product IDs to deactivate. Max number of IDs: 20. listing_platforms: type: array items: type: string enum: - TOKOPEDIA - TIKTOK_SHOP description: |- The listing platforms where the product will be deactivated. Possible values: - TOKOPEDIA - TIKTOK_SHOP Default: TIKTOK_SHOP Applicable only for sellers that migrated from Tokopedia. required: - product_ids DeactivateProductsResponse: 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/DeactivateProductsResponseData" DeactivateProductsResponseData: type: object properties: errors: type: array items: $ref: "#/components/schemas/Error" description: The errors for individual products that could not be deactivated. Check this list even when the top-level `code` is `0`. DeleteGlobalProductsRequest: type: object properties: global_product_ids: type: array items: type: string description: |- The global product IDs to delete. Max number of IDs: 20 required: - global_product_ids DeleteGlobalProductsResponse: 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/DeleteGlobalProductsResponseData" DeleteGlobalProductsResponseData: type: object properties: errors: type: array items: $ref: "#/components/schemas/DeleteGlobalProductsResponseDataError" description: The errors for individual global products that could not be deleted. Check this list even when the top-level `code` is `0`. DeleteGlobalProductsResponseDataError: type: object properties: message: type: string description: The error message. code: type: integer format: int64 description: The error code. detail: $ref: "#/components/schemas/DeleteGlobalProductsResponseDataErrorDetail" description: The details of the error. DeleteGlobalProductsResponseDataErrorDetail: type: object properties: global_product_id: type: string description: The ID of the global product that could not be deleted. DeleteProductsRequest: type: object properties: product_ids: type: array items: type: string description: |- The product IDs to delete. Max number of IDs: 20. required: - product_ids DeleteProductsResponse: 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/DeleteProductsResponseData" DeleteProductsResponseData: type: object properties: errors: type: array items: $ref: "#/components/schemas/Error" description: The errors for individual products that could not be deleted. Check this list even when the top-level `code` is `0`. DeleteWebhookForAnEventRequest: type: object properties: event_type: type: string enum: - ORDER_STATUS_CHANGE - RECIPIENT_ADDRESS_UPDATE - PACKAGE_UPDATE - PRODUCT_STATUS_CHANGE - SELLER_DEAUTHORIZATION - UPCOMING_AUTHORIZATION_EXPIRATION - CANCELLATION_STATUS_CHANGE - RETURN_STATUS_CHANGE - NEW_CONVERSATION - NEW_MESSAGE - PRODUCT_INFORMATION_CHANGE - PRODUCT_CREATION - PRODUCT_CATEGORY_CHANGE - NEW_MESSAGE_LISTENER - INVOICE_STATUS_CHANGE - PRODUCT_AUDIT_STATUS_CHANGE - REVERSE_STATUS_UPDATE x-enum-descriptions: - Triggers on each order status update, from new order placement through all subsequent status changes. See [Order Status change](650300b8a57708028b430b4a). - Triggers when the recipient's address is updated. See [Receipient address update](650301af5a12ff0294ea3bf9). - Triggers when a package is updated (e.g., combined, split, or address changed). See [Package update](650955cabace3e02b73cc886). - Triggers when product audit results are updated. See [Product status change](650956aff1fd3102b90b6261). - Triggers when a seller is deauthorized to inform developers and avoid misunderstandings about platform authorization issues. See [Seller deauthorization](65095746defece02be4d749d). - Triggers 30 days before authorization expiration, with daily notifications at 0:00 until re-authorization is completed. See [Upcoming authorization expiration](6509579c0fcef602bf11312c). - Triggers when an order's cancellation status changes. See [Cancellation status change](65030150746462028285f657). - Triggers when an order's return status changes. See [Return status change](65030162bb2a4d028d50cc51). - Triggers when a customer service agent joins or leaves a conversation. See [New conversation](6614330bfe9fdc02e002abfd). - Triggers when a new message is sent in a customer service conversation. See [New Message](66143486ef8a1202dc323258). - Triggers when changes to a product's title, description, main images, or attributes go live. See [Product information change](65d6f41411a60f02dc1cf8bf). - Triggers when a new product is created. See [Product creation](663c98b566828e02e4515580). - Triggers when the category of a product is changed. See [Product category change](668764a371f16d02eef1f393). - Triggers when a creator sends a message to the seller. See [New message listener](6790b76eb59cf9030997b783). - Triggers when the status of an invoice upload changes after using the [POST Upload Invoice](67b542559a140004b343984f) endpoint. See [Invoice Status Change](67b68ca185619104a6772e5d). - Triggers when the product audit status changes. See [Product audit status change](67b5c6cba42623049abe5062). - Triggers when buyer raises cancellation, refund only, or return & refund requests that need the seller to accept or reject. See [Reverse Status Update](https://partner.tiktokshop.com/doc/page/63fd7459715d622a338c5437). description: |- The topic of the webhook event. Possible values: - `ORDER_STATUS_CHANGE`: Triggers on each order status update, from new order placement through all subsequent status changes. See [Order Status change](650300b8a57708028b430b4a). - `RECIPIENT_ADDRESS_UPDATE`: Triggers when the recipient's address is updated. See [Receipient address update](650301af5a12ff0294ea3bf9). - `PACKAGE_UPDATE`: Triggers when a package is updated (e.g., combined, split, or address changed). See [Package update](650955cabace3e02b73cc886). - `PRODUCT_STATUS_CHANGE`: Triggers when product audit results are updated. See [Product status change](650956aff1fd3102b90b6261). - `SELLER_DEAUTHORIZATION`: Triggers when a seller is deauthorized to inform developers and avoid misunderstandings about platform authorization issues. See [Seller deauthorization](65095746defece02be4d749d). - `UPCOMING_AUTHORIZATION_EXPIRATION`: Triggers 30 days before authorization expiration, with daily notifications at 0:00 until re-authorization is completed. See [Upcoming authorization expiration](6509579c0fcef602bf11312c). - `CANCELLATION_STATUS_CHANGE`: Triggers when an order's cancellation status changes. See [Cancellation status change](65030150746462028285f657). - `RETURN_STATUS_CHANGE`: Triggers when an order's return status changes. See [Return status change](65030162bb2a4d028d50cc51). - `NEW_CONVERSATION`: Triggers when a customer service agent joins or leaves a conversation. See [New conversation](6614330bfe9fdc02e002abfd). - `NEW_MESSAGE`: Triggers when a new message is sent in a customer service conversation. See [New Message](66143486ef8a1202dc323258). - `PRODUCT_INFORMATION_CHANGE`: Triggers when changes to a product's title, description, main images, or attributes go live. See [Product information change](65d6f41411a60f02dc1cf8bf). - `PRODUCT_CREATION`: Triggers when a new product is created. See [Product creation](663c98b566828e02e4515580). - `PRODUCT_CATEGORY_CHANGE`: Triggers when the category of a product is changed. See [Product category change](668764a371f16d02eef1f393). - `NEW_MESSAGE_LISTENER`: Triggers when a creator sends a message to the seller. See [New message listener](6790b76eb59cf9030997b783). - `INVOICE_STATUS_CHANGE`: Triggers when the status of an invoice upload changes after using the [POST Upload Invoice](67b542559a140004b343984f) endpoint. See [Invoice Status Change](67b68ca185619104a6772e5d). - `PRODUCT_AUDIT_STATUS_CHANGE`: Triggers when the product audit status changes. See [Product audit status change](67b5c6cba42623049abe5062). - `REVERSE_STATUS_UPDATE`: Triggers when buyer raises cancellation, refund only, or return & refund requests that need the seller to accept or reject. See [Reverse Status Update](https://partner.tiktokshop.com/doc/page/63fd7459715d622a338c5437). required: - event_type DeleteWebhookForAnEventResponse: 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/DeleteWebhookForAnEventResponseData" DeleteWebhookForAnEventResponseData: type: object properties: {} Detail: type: object properties: product_id: type: string description: The product identifier. DiagnoseAndOptimizeProductRequest: type: object properties: product_id: type: string description: |- The product ID of an existing product in TikTok Shop. - Omit this if you are diagnosing a brand-new product not yet listed in TikTok Shop. - Provide this ID if the product is similar to an existing one, and you want the diagnosis to consider both the existing product's details and the new information in this request. category_id: type: string description: |- The ID of the category of this product. It must be a leaf category. Use the [Get Categories API](https://partner.tiktokshop.com/docv2/page/6509c89d0fcef602bf1acd9b) to find a leaf category. **Note**: - For the US market, refer to [TikTok Shop Restricted Products Policy](https://seller-us.tiktok.com/university/essay?identity=1&role=1&knowledge_id=3238037484275457&from=policy) for information on product category restrictions. - For the Indonesia market, to list a product on both TikTok Shop and Tokopedia, you must use only categories that are available on both platforms. description: type: string maxLength: 10000 description: |- The product description in HTML format. **Note**: - 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 `
` tags as images. - Max length: 10,000 characters. - Images must use TikTok Shop image URLs, not exceed 4000px, and include `src`, `width`, and `height` attributes. **Recommendations**: - If you are syncing a pre-existing description from another platform, include the full HTML source description here. - Provide a detailed description, ideally over 300 characters. - Include 3-5 key selling points, each under 250 characters, with supporting images. - Use 1600x1600 px for the image dimensions. brand_id: type: string description: |- The ID of the brand of this product. Use the [Get Brands API](https://partner.tiktokshop.com/docv2/page/6503075656e2bb0289dd5d01) to get the list of available brands for a shop. **Note**: Unauthorized brands won't be displayed on TikTok Shop. main_images: type: array items: $ref: "#/components/schemas/DiagnoseAndOptimizeProductRequestMainImage" description: |- A list of images to display in the product image gallery. Use the [Upload Product Image API](https://partner.tiktokshop.com/docv2/page/6509df95defece02be598a22) to upload the images first and obtain the corresponding image URI. **Note**: - Max number of image URIs: 9 - Arrange your image URIs in the sequence that they should appear on TikTok Shop. - Image dimensions: [300x300 px, 4000x4000 px] **Recommendations**: - Use a minimum of 5 images. - The first image should have a white background. Use the [Optimize Images API](https://partner.tiktokshop.com/docv2/page/665692b35d39dc02deb49a97) to change the background to white. title: type: string description: |- The product title. Title length: - DE, ES, FR, IE, IT, JP, UK, US: [1, 255] - BR, MX: [1, 300] - Other regions: [25, 255] product_attributes: type: array items: $ref: "#/components/schemas/DiagnoseAndOptimizeProductRequestProductAttribute" description: |- A list of general attributes (e.g. manufacturer, country of origin, materials used) that describe the product as a whole, regardless of variant. **Note**: The attributes available for use are determined by the system based on the product's assigned category, with some being mandatory. Retrieve the product attributes by using the [Get Attributes API](https://partner.tiktokshop.com/docv2/page/6509c5784a0bb702c0561cc8). size_chart: $ref: "#/components/schemas/DiagnoseAndOptimizeProductRequestSizeChart" description: |- The measurement details of the product to help buyers find the right size. **Note**: - For certain product categories, size charts may be required or not supported. Use the [Get Category Rules API](https://partner.tiktokshop.com/docv2/page/6509c0febace3e02b74594a9) to check the requirements. - Provide either a TikTok Shop size chart template ID or a size chart image; if both are provided, the ID takes priority. optimization_fields: type: array items: type: string enum: - TITLE - DESCRIPTION - IMAGE - ALL - NONE x-enum-descriptions: - Product title - Product description (suggestions for this may take more than 10 seconds to generate) - Product image displayed in the image gallery - Suggestions are generated for all the above fields - No suggestions will be provided. description: |- The fields for which you want to generate specific optimization suggestions. Possible values: - TITLE: Product title - DESCRIPTION: Product description (suggestions for this may take more than 10 seconds to generate) - IMAGE: Product image displayed in the image gallery - ALL: Suggestions are generated for all the above fields - NONE: No suggestions will be provided. Default: NONE required: - category_id DiagnoseAndOptimizeProductRequestMainImage: type: object properties: uri: type: string description: |- The URI of the image. Retrieve the URI from the [Upload Product Image API](https://partner.tiktokshop.com/docv2/page/6509df95defece02be598a22) or the [Optimize Images API](https://partner.tiktokshop.com/docv2/page/665692b35d39dc02deb49a97). DiagnoseAndOptimizeProductRequestProductAttribute: type: object properties: id: type: string description: The ID of the product attribute, retrieved from the [Get Attributes API](https://partner.tiktokshop.com/docv2/page/6509c5784a0bb702c0561cc8). values: type: array items: $ref: "#/components/schemas/DiagnoseAndOptimizeProductRequestProductAttributeValue" description: |- A list of selectable values for the product attribute. **Note**: Provide either a built-in ID or a custom name; if both are provided, the ID takes priority. DiagnoseAndOptimizeProductRequestProductAttributeValue: type: object properties: id: type: string description: The ID of a built-in product attribute value, retrieved from the [Get Attributes API](https://partner.tiktokshop.com/docv2/page/6509c5784a0bb702c0561cc8). name: type: string maxLength: 500 description: |- A self-defined custom product attribute value if the built-in values do not satisfy your needs. The system will auto-generate an ID after listing. **Note**: - No duplicates allowed under the same attribute. - Max length: 500 characters DiagnoseAndOptimizeProductRequestSizeChart: type: object properties: template: $ref: "#/components/schemas/DiagnoseAndOptimizeProductRequestSizeChartTemplate" description: A TikTok Shop size chart template generated by the size chart tool in Seller Center > Manage Products > Bulk action > Batch manage size charts. image: $ref: "#/components/schemas/DiagnoseAndOptimizeProductRequestSizeChartImage" description: An image of the size chart. DiagnoseAndOptimizeProductRequestSizeChartImage: type: object properties: uri: type: string description: |- The URI of the size chart image. Use the [Upload Product Image API](https://partner.tiktokshop.com/docv2/page/6509df95defece02be598a22) to upload the image first and obtain the corresponding image URI. DiagnoseAndOptimizeProductRequestSizeChartTemplate: type: object properties: id: type: string description: The size chart template ID. DiagnoseAndOptimizeProductResponse: 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/DiagnoseAndOptimizeProductResponseData" DiagnoseAndOptimizeProductResponseData: type: object properties: listing_quality: $ref: "#/components/schemas/ListingQuality" description: Product listing quality information. diagnoses: type: array items: $ref: "#/components/schemas/Diagnosis" description: Product diagnosis and optimization information. DiagnoseAndOptimizeProductResponseDataDiagnosisSuggestionImage: type: object properties: height: type: integer format: int64 description: The image height after optimization. width: type: integer format: int64 description: The image width after optimization. uri: type: string description: The original URI of the image. url: type: string description: The original URL of the image. optimized_uri: type: string description: The URI of the image after optimization. optimized_url: type: string description: The URL of the image after optimization. Diagnosis: type: object properties: field: type: string enum: - TITLE - DESCRIPTION - IMAGE - ATTRIBUTE - SIZE_CHART x-enum-descriptions: - Product title - Product description - Product image displayed in the image gallery - Product attribute - Product size chart description: |- The product field being diagnosed. Possible values: - TITLE: Product title - DESCRIPTION: Product description - IMAGE: Product image displayed in the image gallery - ATTRIBUTE: Product attribute - SIZE_CHART: Product size chart diagnosis_results: type: array items: $ref: "#/components/schemas/DiagnosisResult" description: The results of diagnosing the specified field. suggestion: $ref: "#/components/schemas/Suggestion" description: |- Optimization suggestions that are auto-generated by the system to improve the effectiveness of the specified field. **Note**: This will not be returned if the value for `optimization_fields` is blank or `NONE`. DiagnosisResult: type: object properties: code: type: string description: |- A machine-readable code that represents an identified issue. Refer to [Listing quality diagnosis](https://partner.tiktokshop.com/docv2/page/66eb8f5c6f2da702e96a49dd) for the full list of identified issues and the corresponding recommendations. how_to_solve: type: string description: |- The recommendation for resolving the identified issue, returned in the default locale language of the shop. Refer to [Listing quality diagnosis](https://partner.tiktokshop.com/docv2/page/66eb8f5c6f2da702e96a49dd) for the full list of recommendations. quality_tier: type: string enum: - FAIR - GOOD description: |- The listing quality tier you can reach by implementing the recommendation. Possible values: - FAIR - GOOD **Note**: - To reach a higher tier, you must implement all recommendations from the destination tier and all preceding tiers. For example, a product will reach the "GOOD" tier once all "FAIR" and "GOOD" recommendations are addressed or implemented. - Available only for the US market. Dimension: type: object properties: length: type: string description: Package length. width: type: string description: Package width. height: type: string description: Package height. unit: type: string enum: - CM - INCH description: |- The unit of measurement for the package dimensions. Available values: - `CM` - `INCH` Discount: type: object properties: shipping_discount: $ref: "#/components/schemas/ShippingDiscount" description: Configurations for the shipping discount, including purchase criteria, discount value, shipping method, inventory type, and area scope. bmsm_discount: $ref: "#/components/schemas/DiscountBmsmDiscount" description: Configurations related to Buy More Save More (BMSM) promotions gift_discount: $ref: "#/components/schemas/GiftDiscount" description: Configurations related to Gift With Purchase (GWP) promotions. Only needs to be configured for GWP promotions. bxgy_discount: $ref: "#/components/schemas/BxgyDiscount" description: Configurations related to Buy X Get Y (BXGY) promotions. Only needs to be configured for BXGY promotions. DiscountBmsmDiscount: type: object properties: details: type: array items: $ref: "#/components/schemas/CreatePromotionActivityRequestDiscountBmsmDiscountDetail" description: Configurations for Buy More Save More tiers. Provide one or two tiers. `threshold_type` and `type` must be the same across all tiers. DiscountDetail: type: object properties: discount_level: type: string description: |- An enum that communicated the type of discount: - REGULAR - FIRST_ORDER - RETENTION discount_value: type: integer format: int64 description: The value of the discount. A value of 10, would indicate a 10% discount. DistrictInfo: type: object properties: address_level_name: type: string description: The name of administrative division that can be used by seller for ship. e.g. state/county/city/district/town etc. address_name: type: string description: "Administrative area name. eg: London" address_level: type: string description: Administrative district level code. Value can be L0/L1/L2/L3/L4. eg. US is L0 iso_code: type: string description: ISO code of the administrative district level DownloadCompassTaskFileResponse: 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/DownloadCompassTaskFileResponseData" DownloadCompassTaskFileResponseData: type: object properties: file: $ref: "#/components/schemas/DownloadCompassTaskFileResponseDataFile" description: The downloadable file DownloadCompassTaskFileResponseDataFile: type: object properties: base64: type: string description: The Base64-encoded contents of the export result file. EditAffiliatePartnerCampaignRequest: type: object properties: name: type: string minLength: 1 maxLength: 50 description: The campaign name. It must contain 1 to 50 characters and must not start with a space. description: type: string minLength: 1 maxLength: 1000 description: The campaign description. It must contain 1 to 1000 characters and must not start with a space. campaign_start_time: type: integer format: int64 description: The scheduled campaign start time as a Unix timestamp in seconds. This field can be updated only when the campaign status is `READY` or `UPCOMING`. campaign_end_time: type: integer format: int64 description: The scheduled end time in Unix epoch time format for the campaign. Note that the end time must be less than 360 days from the start date. This field is no longer editable when the campaign status is set to `CLOSED`. registration_start_time: type: integer format: int64 description: The scheduled start time for seller product registration, as a Unix timestamp in seconds. This field can be updated only when the campaign status is `READY` or `UPCOMING`. registration_end_time: type: integer format: int64 description: The scheduled end time for seller product registration, as a Unix timestamp in seconds. This field is no longer editable when the campaign status is `CLOSED`. commission_rate: type: integer format: int64 description: The total commission rate, in units of 0.01%, proposed by the affiliate partner for display to sellers. The value must be between 100 and 8000, inclusive. contact_info: $ref: "#/components/schemas/ContactInfo" description: The partner's contact information. target_shop_codes: type: array items: type: string description: A list of TikTok Shop seller shop codes to allow to register for the campaign. The seller shop code in available in TikTok Shop Seller Central by clicking on the Seller Profile icon in the top right of the user interface. The list must be less than 100 items in length. target_seller_types: type: array items: type: string enum: - LOCAL - CROSS_BORDER description: |- A list of eligible seller types to allow to register for the campaign. Use this field to broadly target types of sellers instead of specific sellers in the `target_shop_codes` field. This is an enumerated type with possible values: - LOCAL - CROSS_BORDER EditAffiliatePartnerCampaignResponse: 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/EditAffiliatePartnerCampaignResponseData" EditAffiliatePartnerCampaignResponseData: type: object properties: {} EditGlobalProductRequest: type: object properties: title: type: string description: |- The product title. Title length: - DE, ES, FR, IE, IT, JP, UK, US: [1, 255] - MX:[1,300] - Other regions: [25, 255] description: type: string maxLength: 10000 description: |- The product description in HTML format. **Note**: - 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 `
` tags as images. - Max length: 10,000 characters. - Image guidelines: You must use [TikTok Shop image URLs](6509df95defece02be598a22). Max 30 `` tags, each under 4000px with `src`, `width`, and `height` attributes. **Recommendations**: - If you are syncing a pre-existing description from another platform, include the full HTML source description here. - Provide a detailed description, ideally over 300 characters. - Include 3-5 key selling points, each under 250 characters, with supporting images. - Use 1600x1600 px for the image dimensions. category_id: type: string description: |- The ID of the category of this product. - It must be a leaf category that corresponds to the category tree type specified in the `category_version` property. - It must be a main category (`categories.permission_statuses=AVAILABLE` in [Get Global Categories API](650a03f8f1fd3102b91b338a)). **Note**: Refer to TikTok Shop Academy for information on product category restrictions. brand_id: type: string description: |- The ID of the brand of this product. **Note**: Unauthorized brands won't be displayed on TikTok Shop. main_images: type: array items: $ref: "#/components/schemas/MainImage" maxItems: 9 description: |- A list of images to display in the product image gallery. - Max count: 9 - Arrange your image URIs in the sequence that they should appear on TikTok Shop. - Image dimensions: [300x300 px, 4000x4000 px] **Recommendations**: - Use a minimum of 5 images. - The first image should have a white background. Use the [Optimize Images API](https://partner.tiktokshop.com/docv2/page/665692b35d39dc02deb49a97) to change the background to white. skus: type: array items: $ref: "#/components/schemas/EditGlobalProductRequestSku" description: |- A list of global Stock Keeping Units (SKUs) used to identify distinct variants of the product. **Note**: - Max SKUs for EU, JP, UK, US: 300 - Max SKUs for other regions: 100 **Recommendations**: Place the most important variant at the beginning of the array. package_weight: $ref: "#/components/schemas/PackageWeight" description: |- The weight of the product package. **Note**: - Provide the weight measured after packing the product. - This value impacts the shipping cost, so it is important to ensure that the measurements are accurate. Any discrepancies may lead to additional shipping fees. - The package weight will take precedence over package dimensions in fee calculation if the fee based on weight is higher. certifications: type: array items: $ref: "#/components/schemas/CreateGlobalProductRequestCertification" maxItems: 10 description: |- The list of certifications for your product. Max count: 10 As per TikTok Shop guidelines, certifications are required for certain restricted product categories. Retrieve the certification requirements for your product from the [Get Global Category Rules API](https://partner.tiktokshop.com/docv2/page/650a056df1fd3102b91b5b8e). Refer to [TikTok Shop Restricted Products Policy](https://seller-us.tiktok.com/university/essay?identity=1&role=1&knowledge_id=3238037484275457&from=policy) for information on product category restrictions. package_dimensions: $ref: "#/components/schemas/PackageDimension" description: |- The dimensions of the product package. **Note**: - Provide the dimensions measured after packing the product. - These values impact the shipping cost, so it is important to ensure that dimensions are accurate. Any discrepancies may lead to additional shipping fees. product_attributes: type: array items: $ref: "#/components/schemas/ProductAttribute" description: |- A list of general attributes (e.g. manufacturer, country of origin, materials used) that describe the product as a whole, regardless of variant. **Important**: The attributes available for use are determined by the system based on the product's assigned category, with some being mandatory. You must provide the product attributes marked as `is_required` in the response of the [Get Global Attributes API](650a0483c16ffe02b8dfc80a). size_chart: $ref: "#/components/schemas/SizeChart" description: |- The measurement details of the product to help buyers find the right size. **Note**: - For certain product categories, size charts may be required or not supported. Use the [Get Global Category Rules API](https://partner.tiktokshop.com/docv2/page/650a056df1fd3102b91b5b8e) to check the requirements. - If size charts are not supported, even if you provide a size chart here, the size chart will not be saved. - Provide either a TikTok Shop size chart template ID or a size chart image; if both are provided, the ID takes priority. video: $ref: "#/components/schemas/Video" description: |- A product introduction or promotion video to display for your product. **Recommendations**: - Aspect ratio: 1:1 - Resolution: HD 720p or higher - Duration: 20 - 60 seconds manufacturer: $ref: "#/components/schemas/Manufacturer" description: |- (**Deprecated**: This field is deprecated and will be removed in a future API version. Use `manufacturer_ids` instead.) The product manufacturer's details. deprecated: true manufacturer_ids: type: array items: type: string description: |- A comma-delimited list of manufacturer IDs. Retrieve the IDs from the [Search Manufacturers API](67066a580dcee902fa03ccf9). Default: The IDs provided when the global product was created. **Note**: Applicable only for the EU market in certain categories. Use the [Get Global Category Rules API](650a056df1fd3102b91b5b8e) to check the requirements. responsible_person_ids: type: array items: type: string description: |- A comma-delimited list of responsible person IDs. Retrieve the IDs from the [Search Responsible Persons API](67066a55f17b7d02f95d2fb1). Default: The IDs provided when the global product was created. **Note**: Applicable only for the EU market in certain categories. Use the [Get Global Category Rules API](650a056df1fd3102b91b5b8e) to check the requirements. category_version: type: string description: |- Filter categories by the category tree version.Possible values based on region: - US, EU and SEA: v2, represents the 7-level category tree. Important: For US, EU and SEA shops, you must pass v2 when using this API. - Other regions: v1, represents the 3-level category tree.Default: v1 external_global_product_id: type: string maxLength: 999 description: |- An external identifier used in an external ecommerce platform. This is used to associate the global product between TikTok Shop and the external ecommerce platform. Max length: 999 characters required: - title - description - category_id - main_images - skus - package_weight EditGlobalProductRequestSku: type: object properties: id: type: string description: |- The global SKU ID in TikTok Shop. One product can contain multiple SKU IDs. **Note**: - To edit an existing SKU, include its SKU ID. - Any existing SKU IDs not listed here will result in the deletion of those SKUs. For example, if this product contains 5 SKUs and you only provide 2 SKU IDs, the remaining 3 will be deleted. - To create new SKUs, leave the SKU ID blank and complete the other fields. global_quantity: type: integer format: int64 description: |- The total SKU inventory quantity across all shops globally. The inventory for each local shop is automatically calculated when a product is first published. After publishing, this global quantity cannot be manually changed. You can only modify the inventory quantity in each local shop. seller_sku: type: string minLength: 1 maxLength: 50 description: |- An internal code/name for managing SKUs, not visible to buyers. - Valid length: 1-50 characters - Format: Text without spaces price: $ref: "#/components/schemas/CreateGlobalProductRequestSkuPrice" description: |- The SKU's **global uniform pre-tax** price that serves as the baseline for calculating the local prices across different markets. **Note**: - Upon publishing, this price will be automatically converted to the local pre-tax price and local display price based on market-specific exchange rates and applicable charges such as shipping costs, taxes, and other fees. - The auto-conversion will exclude JP and US shops using China warehouses. For these shops, please use `sale_prices` instead. sales_attributes: type: array items: $ref: "#/components/schemas/CreateGlobalProductRequestSkuSalesAttribute" description: |- A list of attributes (e.g. size, color, length) that define each variant of a product. **Note**: - You must retain at least 1 sales attribute, deleting all existing sales attributes is not allowed. - You can only have up to 3 types of sales attributes per product. - Each SKU must include the same number and type of sales attributes. For example, you cannot have one SKU that has only a Color attribute, while another SKU has both Color and Size attributes. - Provide either a built-in ID or a custom name; if both are provided, the ID takes priority. - The `id/name` and `value_id/value_name` pairs must be unique in each SKU. For example, you cannot repeat `"name": "Color"`, `"value_name": "Red"` in different SKUs. inventory: type: array items: $ref: "#/components/schemas/CreateGlobalProductRequestSkuInventory" maxItems: 50 description: |- SKU inventory information per warehouse. If multi-warehouse is enabled in Seller Center, you must provide the inventory details for each warehouse. Max count: 50 **Note**: `global_quantity` will not take effect if inventory details are provided for each warehouse. identifier_code: $ref: "#/components/schemas/IdentifierCode" description: |- A regulated identifier code assigned to a product based on international standardized regulations (e.g. GTIN) to ensure the product is universally identifiable across various platforms and systems. **Note**: Editable only if the product is in DRAFT state. Otherwise, changes are not allowed. sku_unit_count: type: string description: |- The total quantity/volume of the product represented by the SKU. For example, if the SKU represents 500ml of water, this value would be 500 if the unit type is defined as ml. Valid range: [0.01, 99,999.9999] Applicable only for the EU market. **Note**: - This is mainly used to calculate the unit price of the SKU, and is required only if you wish to display the unit price to facilitate easier price comparisons across different products and packaging sizes. - Unit price = Selling price/(SKU unit count/base unit count). Therefore if you want to obtain the unit price, you would also need to define the "base unit count" and the "unit type" product attributes. Retrieve the relevant information for these product attributes by using the [Get Global Attributes API](https://partner.tiktokshop.com/docv2/page/650a0483c16ffe02b8dfc80a). The unit price would then be returned in the [Get Global Product API](https://partner.tiktokshop.com/docv2/page/6509e2b0bace3e02b7490c96). extra_identifier_codes: type: array items: type: string description: |- If the SKU belongs to a virtual bundle (containing multiple individual SKUs), you can add up to 10 additional identifier codes here for the SKUs included in the bundle. **Format**: GTIN: 14 digits EAN: 8, 13, or 14 digits UPC: 12 digits ISBN: 13 digits, or 9 digits ending in capital `X` **Note**: - Applicable only for the EU market. - The identifier code must be unique for each SKU, with no repetition allowed. external_global_sku_id: type: string maxLength: 999 description: |- An external identifier used in an external ecommerce platform. This is used to associate the global SKU between TikTok Shop and the external ecommerce platform. Max length: 999 characters sale_prices: type: array items: $ref: "#/components/schemas/EditGlobalProductRequestSkuSalePrice" description: |- The SKU's **local display price** shown on the product page before any discounts. **Note**: - Required for JP and US shops using China warehouses, optional for others. - This is the definitive final price shown on the product page, all other prices will be ignored. required: - price EditGlobalProductRequestSkuSalePrice: type: object properties: region: type: string enum: - AT - BE - CZ - DE - ES - FR - GB - GR - HU - ID - IE - IT - JP - MY - NL - PH - PO - PT - SG - TH - US - VN - MX x-enum-descriptions: - Austria - Belgium - Czech Republic - Germany - Spain - France - United Kingdom - Greece - Hungary - Indonesia - Ireland - Italy - Japan - Malaysia - Netherlands (NL) - Philippines - Poland - Portugal - Singapore - Thailand - United States - Vietnam - Mexico description: |- The market for which this local display price applies. Possible values: - AT: Austria - BE: Belgium - CZ: Czech Republic - DE: Germany - ES: Spain - FR: France - GB: United Kingdom - GR: Greece - HU: Hungary - ID: Indonesia - IE: Ireland - IT: Italy - JP: Japan - MY: Malaysia - NL: Netherlands (NL) - PH: Philippines - PO: Poland - PT: Portugal - SG: Singapore - TH: Thailand - US: United States - VN: Vietnam - MX: Mexico amount: type: string description: |- The price amount. Refer to [Product Pricing](https://partner.tiktokshop.com/docv2/page/67e1288d76cfee049d9af858) for the allowed price ranges in each market. required: - region - amount EditGlobalProductResponse: 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/EditGlobalProductResponseData" EditGlobalProductResponseData: type: object properties: global_skus: type: array items: $ref: "#/components/schemas/GlobalSku" description: A list of global Stock Keeping Units (SKUs) used to identify distinct variants of the product. publish_results: type: array items: $ref: "#/components/schemas/PublishResult" description: Results of syncing the changes in the edited product to markets where it is published. EditOpenCollaborationSampleRuleRequest: type: object properties: product_id: type: string description: The product ID to which the sample rule applies. You can only assign one sample rule for one `product_id`. Only the most recent API call will take effect. sample_rule: $ref: "#/components/schemas/EditOpenCollaborationSampleRuleRequestSampleRule" description: The sample rule settings to apply to the specified product. Use `activate_status` to create, update, or deactivate the rule. required: - product_id EditOpenCollaborationSampleRuleRequestSampleRule: type: object properties: sample_quota: type: integer format: int64 description: The total quantity of the samples provided by the seller that the creators can apply for. is_sample_time_unlimited: type: boolean description: |- Whether the sample is always available for application: - If true, the sample can be requested at any time. - If false, the sample can only be requested during specified time periods. You must set start_time and end_time. start_time: type: integer format: int64 description: The start of the period during which a creator can apply for samples, as a Unix timestamp in seconds. You must specify `start_time` and `end_time` together. end_time: type: integer format: int64 description: The end of the period during which a creator can apply for samples, as a Unix timestamp in seconds. You must specify `start_time` and `end_time` together. thresholds: $ref: "#/components/schemas/Threshold" description: The threshold criteria that a creator must meet to be eligible to apply for the sample. activate_status: type: string description: |- To activate the sample rule, use `ACTIVATE`; to deactivate the sample rule, use `DEACTIVATE`. When using `ACTIVATE`, you must specify the details of the rule; when using `DEACTIVATE`, you just need to specify `product_id`. required: - activate_status EditOpenCollaborationSampleRuleResponse: 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/EditOpenCollaborationSampleRuleResponseData" EditOpenCollaborationSampleRuleResponseData: type: object properties: {} EditOpenCollaborationSettingsRequest: type: object properties: auto_add_product: $ref: "#/components/schemas/EditOpenCollaborationSettingsRequestAutoAddProduct" description: An object with properties to automatically add products to affiliate open collaboration plans. EditOpenCollaborationSettingsRequestAutoAddProduct: type: object properties: enable: type: boolean description: Set to `true` if products are automatically added to affiliate open collaboration plans. The seller can add existing non-affiliate products to open collaboration at one time, and future products are added automatically. Set to `false` if otherwise. commission_rate: type: integer format: int64 description: The commission rate in hundredths of a percent. For example, `3587` is a commission rate of `35.87%`. This value must a minimum of `100` and a maximum of `8000`. Not that setting the `enable` property to `false` overrides this property. required: - enable - commission_rate EditOpenCollaborationSettingsResponse: 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/EditOpenCollaborationSettingsResponseData" EditOpenCollaborationSettingsResponseData: type: object properties: {} EditProductRequest: type: object properties: save_mode: type: string enum: - AS_DRAFT - LISTING x-enum-descriptions: - Save the product as a draft for future editing. - Submit the edited product for listing. Changes that require review are published after approval; changes to the price or inventory fields are published immediately. description: |- Indicates how the product should be saved. Possible values: - AS_DRAFT: Save the product as a draft for future editing. - LISTING: Submit the edited product for listing. Changes that require review are published after approval; changes to the price or inventory fields are published immediately. Default: LISTING **Note**: - Saving as draft is not supported when the product status is `DELETED`, or when the product is `PENDING` or `FREEZE` on any listing platform. - When saving a post-live draft with `save_mode=AS_DRAFT`, `inventory` and `delivery_option_ids` are not supported and will not be saved. description: type: string maxLength: 10000 description: |- The product description in HTML format. **Note**: - 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 `
` tags as images. - Max length: 10,000 characters. - Image guidelines: You must use [TikTok Shop image URLs](6509df95defece02be598a22). Max 30 `` tags, each under 4000px with `src`, `width`, and `height` attributes. **Recommendations**: - If you are syncing a pre-existing description from another platform, include the full HTML source description here. - Provide a detailed description, ideally over 300 characters. - Include 3-5 key selling points, each under 250 characters, with supporting images. - Use 1600x1600 px for the image dimensions. category_id: type: string description: |- The ID of the category of this product. It must be a leaf category that corresponds to the category tree type specified in the `category_version` property. Use the [Get Categories API](https://partner.tiktokshop.com/docv2/page/6509c89d0fcef602bf1acd9b) to obtain the available categories. **Note**: - Refer to TikTok Shop Academy for information on product category restrictions. - For the US market, if you change a product's category to an `INVITE_ONLY` category, you must submit a separate application through the Qualification Center on TikTok Shop Seller Center to gain access. Otherwise, even if the product audit is passed, the product will not be listed and made available to buyers. (The product status will be `PENDING` and the audit status will be `PRE_APPROVED`) - For the Indonesia market, to list a product on both TikTok Shop and Tokopedia, you must use only categories that are available on both platforms. brand_id: type: string description: |- The ID of the brand of this product. Use the [Get Brands API](https://partner.tiktokshop.com/docv2/page/6503075656e2bb0289dd5d01) to get the list of available brands for a shop. **Note**: Unauthorized brands won't be displayed on TikTok Shop. main_images: type: array items: $ref: "#/components/schemas/MainImage" maxItems: 9 description: |- A list of images to display in the product image gallery. - Max count: 9 - Arrange your image URIs in the sequence that they should appear on TikTok Shop. - Image dimensions: [300x300 px, 4000x4000 px] **Recommendations**: - Use a minimum of 5 images. - The first image should have a white background. Use the [Optimize Images API](https://partner.tiktokshop.com/docv2/page/665692b35d39dc02deb49a97) to change the background to white skus: type: array items: $ref: "#/components/schemas/EditProductRequestSku" description: |- A list of Stock Keeping Units (SKUs) used to identify distinct variants of the product. **Note**: - Max SKUs for BR, EU, MX, JP, UK, US: 300 - Max SKUs for other regions: 100 **Recommendations**: Place the most important variant at the beginning of the array. title: type: string description: |- The product title. Title length: - DE, ES, FR, IE, IT, JP, UK, US: [1, 255] - BR, MX: [1, 300] - Other regions: [25, 255] is_cod_allowed: type: boolean description: |- A flag indicating whether to show the Cash On Delivery (COD) payment option during checkout. Use the [Get Category Rules API](https://partner.tiktokshop.com/docv2/page/6509c0febace3e02b74594a9) to check if COD is supported for your product category. Applicable only for the following markets: - Global sellers: MY, PH, SA, TH, VN - Local sellers: ID, MY, PH, SA, TH, VN **Note**: If COD is not supported, the listing will fail if you set this to `true`. certifications: type: array items: $ref: "#/components/schemas/Certification" maxItems: 10 description: |- The list of certifications for your product. Max count: 10 As per TikTok Shop guidelines, certifications are required for certain restricted product categories. Retrieve the certification requirements for your product from the [Get Category Rules API](https://partner.tiktokshop.com/docv2/page/6509c0febace3e02b74594a9). Refer to [TikTok Shop Restricted Products Policy](https://seller-us.tiktok.com/university/essay?identity=1&role=1&knowledge_id=3238037484275457&from=policy) for information on product category restrictions. package_weight: $ref: "#/components/schemas/PackageWeight" description: |- The weight of the product package. **Note**: - Product package weight is mandatory by default, except for products under **Virtual Products** categories. See the [Get Categories API](https://partner.tiktokshop.com/docv2/page/get-categories-202309), for example **Digital Games**. - Provide the weight measured after packing the product. - This value impacts the shipping cost, so ensure that the weight is accurate. Measurement discrepancies may lead to additional shipping fees. - The package weight takes precedence over package dimensions in fee calculation if the fee based on weight is higher. product_attributes: type: array items: $ref: "#/components/schemas/CreateProductRequestProductAttribute" description: |- A list of general attributes (e.g. manufacturer, country of origin, materials used) that describe the product as a whole, regardless of variant. **Important**: The attributes available for use are determined by the system based on the product's assigned category, with some being mandatory. You must provide the product attributes marked as `is_required` in the response of the [Get Attributes API](6509c5784a0bb702c0561cc8) to avoid listing failure. size_chart: $ref: "#/components/schemas/SizeChart" description: |- The measurement details of the product to help buyers find the right size. **Note**: - For certain product categories, size charts may be required or not supported. Use the [Get Category Rules API](https://partner.tiktokshop.com/docv2/page/6509c0febace3e02b74594a9) to check the requirements. - If size charts are not supported, even if you provide a size chart here, the size chart will not be saved. - Provide either a TikTok Shop size chart template ID or a size chart image; if both are provided, the ID takes priority. package_dimensions: $ref: "#/components/schemas/PackageDimension" description: |- The dimensions of the product package. **Note**: - Provide the dimensions measured after packing the product. - These values impact the shipping cost, so it is important to ensure that dimensions are accurate. Any discrepancies in measurements may lead to additional shipping fees. - Optional for ID, TH, VN regions. external_product_id: type: string maxLength: 999 description: |- An external identifier used in an external ecommerce platform. This is used to associate the product between TikTok Shop and the external ecommerce platform. Max length: 999 characters delivery_option_ids: type: array items: type: string description: |- This field is supported for seller accounts in the following regions only: - ID - MX - MY - PH - SG - TH - VN For all other regions, this field is NOT used and will NOT be processed if passed for create, edit, or partial edit operations. The custom delivery option IDs to apply to this product if you want to override the default warehouse delivery options. To retrieve the available option IDs, call [Get Warehouse Delivery Options](https://partner.tiktokshop.com/docv2/page/650aa46ebace3e02b75d9afa) with `scope=PRODUCT`. **Note**: - Leave this field blank to inherit the default delivery options configured for the warehouse. - If you are saving a post-live draft with `save_mode=AS_DRAFT`, this field is not supported and will not be saved. When using Get Product to retrieve the draft, the values will reflect those in the base version. video: $ref: "#/components/schemas/Video" description: |- A product introduction or promotion video to display for your product. **Recommendations**: - Aspect ratio: 1:1 - Resolution: HD 720p or higher - Duration: 20 - 60 seconds category_version: type: string description: |- The category tree version to assign this product to. Possible values based on region: - US and SEA regions: `v2`, represents the 7-level category tree. **Important**: For US and SEA shops, you must pass `v2` when using this API. - Other regions: `v1`, represents the 3-level category tree. Default: `v1` manufacturer_ids: type: array items: type: string description: |- A list of manufacturer IDs. Retrieve the IDs from the [Search Manufacturers API](67066a580dcee902fa03ccf9). **Note**: Applicable only for the EU market in certain categories. Use the [Get Category Rules API](6509c0febace3e02b74594a9) to check the requirements. responsible_person_ids: type: array items: type: string description: |- A list of responsible person IDs. Retrieve the IDs from the [Search Responsible Persons API](67066a55f17b7d02f95d2fb1). **Note**: Applicable only for the EU market in certain categories. Use the [Get Category Rules API](6509c0febace3e02b74594a9) to check the requirements. listing_platforms: type: array items: type: string enum: - TOKOPEDIA - TIKTOK_SHOP description: |- The platforms for listing the product. Possible values: - TOKOPEDIA - TIKTOK_SHOP Applicable only for sellers that migrated from Tokopedia. **IMPORTANT**: This field controls the product's visibility on the listing platforms. - If the product is live on both platforms but the request contains only 1 platform, the product will be deactivated and hidden from the omitted platform. - If the product is live on 1 platform but the request contains a different platform, the product will be deactivated and hidden from the omitted platform. - If you omit this array, the product will be sent for audit on the currently active platforms or on the platforms specified in the previous request. - If you want to deactivate the product on both platforms, use the Deactivate Product API. shipping_insurance_requirement: type: string enum: - REQUIRED - OPTIONAL - NOT_SUPPORTED x-enum-descriptions: - Shipping insurance is mandatory and buyers can't opt out. - Buyers can choose to purchase shipping insurance through the platform. - Shipping insurance is not supported for the product. description: |- The shipping insurance purchase requirement imposed on buyers for the product. Possible values: - REQUIRED: Shipping insurance is mandatory and buyers can't opt out. - OPTIONAL: Buyers can choose to purchase shipping insurance through the platform. - NOT_SUPPORTED: Shipping insurance is not supported for the product. Default: OPTIONAL Applicable only if the listing platforms include TOKOPEDIA. is_pre_owned: type: boolean description: |- A flag to indicate if the product is pre-owned. Applicable only if TOKOPEDIA is the sole listing platform. **Note**: To list pre-owned products on the TikTok Shop platform, please specify the ID of one of the designated pre-owned product categories (e.g. pre-owned luxury bags, luggage, and accessories) in `category_id`. minimum_order_quantity: type: integer format: int64 minimum: 1 maximum: 20 description: |- The minimum order quantity for the product. Valid range: [1, 20] Applicable only for the Indonesia market and selected sellers in other SEA markets. Contact your account manager for more information about gaining access to this field. replicated_products: type: array items: $ref: "#/components/schemas/EditProductRequestReplicatedProduct" description: |- The list of local market replicas to which updates should be synced. This is a full edit endpoint, so all fields will be synchronized. For each target market: - The market must already contain a replica. Use Get Global Replicated Products to check the available markets. - Submit the complete target-market SKU list. Existing target SKU IDs omitted from the list are deleted. - Provide a price for every target SKU. Inventory is also required except when syncing from the US to MX, where target inventory is optional. Category changes and sales-attribute ID or name changes must be synchronized to other markets. For these changes, provide the source `seller_sku` and complete the corresponding details in this object; otherwise, the API call fails. subscribe_info_edit: $ref: "#/components/schemas/EditProductRequestSubscribeInfoEdit" description: All the editable Save and Subscribe promotion info associated with the given product. shipping_template_id: type: string description: Identifier of the shipping template that will be bound to the product scheduled_sale: $ref: "#/components/schemas/ScheduledSale" description: Scheduled listing configuration for the product, including whether scheduled listing is enabled and the scheduled listing time. locale: 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 description: |- The BCP-47 locale codes for displaying category information. Default: The default locale of your shop. Possible values: - `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` auto_translate_enabled: type: boolean description: Whether to automatically translate the product content when listing the product in a market where multiple languages are needed. Omit this field when automatic translation is not needed. search_terms: type: array items: type: string description: Search terms (ST words). ST words will not be displayed to consumers; they are only used in search engines to increase your search weight and gain more traffic. Please ensure that ST words are consistent with the product description, with a maximum of 15 terms and a total of no more than 250 characters. key_product_features: type: array items: type: string maxItems: 5 description: Key Product Features. They will be displayed in the Product highlight module on the product detail page and will be used by search engines to increase your search weight for more traffic. The total number of items should not exceed 5, and the total character count should not exceed 1500. inventory_mode: type: string description: |- Defines the inventory mode for the duplicated source product. This parameter supports two modes: SHARED and EXCLUSIVE. - SHARED: In this mode, the inventory of all interconnected (shared) products must be strictly consistent; otherwise, an error will be returned. - EXCLUSIVE: In this mode, the inventory for each product can be set independently without affecting others. Applicability: This feature is applicable ONLY for the EU market. Default Value: If left empty, the system defaults to the EXCLUSIVE mode. product_tag_operations: type: array items: $ref: "#/components/schemas/ProductTagOperation" description: Legacy operations for enabling or disabling the `AUCTION` product tag. If `selling_format` is provided, it takes precedence over this field. purchase_order_quantity_limit: $ref: "#/components/schemas/PurchaseOrderQuantityLimit" description: Purchase quantity limits applied to each SKU of the product, including the maximum quantity per order and the cumulative quantity across orders. selling_format: type: string enum: - FIXED_PRICE - FIXED_PRICE_AND_LIVE_AUCTION description: "Choose either Fixed price or Fixed price and LIVE auction. Fixed price is selected by default. LIVE auction require a starting bid price. Possible values: FIXED_PRICE, FIXED_PRICE_AND_LIVE_AUCTION." is_live_quick: type: boolean description: |- false — NORMAL products true — LIVE_QUICK products. Only seller with the required permissions can creat LIVE_QUICK products. Default: false is_blind_box: type: boolean description: "Whether the product is a blind box of lucky bag. For example: PopMart" required: - description - category_id - main_images - skus - title EditProductRequestReplicatedProduct: type: object properties: region: type: string enum: - DE - ES - FR - GB - ID - IE - IT - JP - MY - PH - SG - TH - US - VN x-enum-descriptions: - Germany - Spain - France - United Kingdom - Indonesia - Ireland - Italy - Japan - Malaysia - Philippines - Singapore - Thailand - United States - Vietnam description: |- The market where you want to sync the changes to. The market must already contain a replica. Use the Get Global Replicated Products to check the markets that contain a replica. Possible values: - DE: Germany - ES: Spain - FR: France - GB: United Kingdom - ID: Indonesia - IE: Ireland - IT: Italy - JP: Japan - MY: Malaysia - PH: Philippines - SG: Singapore - TH: Thailand - US: United States - VN: Vietnam skus: type: array items: $ref: "#/components/schemas/EditProductRequestReplicatedProductSku" description: |- The SKUs to be synced to the specified market. **Note**: - You must pass in all existing SKUs. Any existing SKU IDs not listed here will result in the deletion of those SKUs. For example, if this product contains 5 SKUs and you only provide 2 SKU IDs, the remaining 3 will be deleted. - To create new SKUs, leave the SKU ID blank and provide the seller_sku. inventory_mode: type: string description: |- Defines the inventory mode for the duplicated target product. This parameter supports two modes: SHARED and EXCLUSIVE. - SHARED: In this mode, the inventory of all interconnected (shared) products must be strictly consistent; otherwise, an error will be returned. - EXCLUSIVE: In this mode, the inventory for each product can be set independently without affecting others. Applicability: This feature is applicable ONLY for the EU market. Default Value: If left empty, the system defaults to the EXCLUSIVE mode. required: - region EditProductRequestReplicatedProductSku: type: object properties: id: type: string description: The SKU ID generated by TikTok Shop. Provide this for existing SKUs. seller_sku: type: string description: |- An internal code/name for managing SKUs, not visible to buyers. Valid length: - DE, ES, FR, IT, PL, NL, BE, CZ, AT, GR, PT, HU: 6-50 characters - Other regions: 1-50 characters Format: - DE, ES, FR, IT, PL, NL, BE, CZ, AT, GR, PT, HU: Use alphabets, numbers, hyphens (-), or underscores (_) only - Other regions: Text without spaces price: $ref: "#/components/schemas/EditProductRequestReplicatedProductSkuPrice" description: The SKU's **local display price** shown on the product page before any discounts. inventory: type: array items: $ref: "#/components/schemas/EditProductRequestReplicatedProductSkuInventory" description: SKU inventory information per warehouse. This field is mandatory for other regions. But when syncing products from the US to MX, the MX product inventory field is optional. required: - price EditProductRequestReplicatedProductSkuInventory: type: object properties: warehouse_id: type: string description: The warehouse ID. Retrieve this value from the [Get Warehouse List API](650aa418defece02be6e66b6) or Get Inventory Rules API. This field is mandatory for other regions. But when syncing products from the US to MX, the MX product inventory field is optional. quantity: type: integer format: int64 minimum: 1 maximum: 999999 description: |- The SKU quantity available in the warehouse. Valid range: [1, 999,999]. This field is mandatory for other regions. But when syncing products from the US to MX, the MX product inventory field is optional. EditProductRequestReplicatedProductSkuPrice: type: object properties: currency: type: string enum: - EUR - GBP - IDR - JPY - MYR - PHP - SGD - THB - USD - VND x-enum-descriptions: - France, Germany, Ireland, Italy, Spain - United Kingdom - Indonesia - Japanese - Malaysia - Philippines - Singapore - Thailand - United States - Vietnam description: |- The currency. You must specify the local currency in the target market. Possible values: - EUR: France, Germany, Ireland, Italy, Spain - GBP: United Kingdom - IDR: Indonesia - JPY: Japanese - MYR: Malaysia - PHP: Philippines - SGD: Singapore - THB: Thailand - USD: United States - VND: Vietnam sale_price: type: string description: |- The SKU's local display price shown on the product page before any discounts. Refer to [Product Pricing](https://partner.tiktokshop.com/docv2/page/67e1288d76cfee049d9af858) for the allowed price ranges in each market. required: - currency - sale_price EditProductRequestSku: type: object properties: id: type: string description: |- The SKU ID generated by TikTok Shop. One product can contain multiple SKU IDs. **Note**: - To edit an existing SKU, include its SKU ID. - Any existing SKU IDs not listed here will result in the deletion of those SKUs. For example, if this product contains 5 SKUs and you only provide 2 SKU IDs, the remaining 3 will be deleted. - To create new SKUs, leave the SKU ID blank and complete the other fields. sales_attributes: type: array items: $ref: "#/components/schemas/CheckProductListingRequestSkuSalesAttribute" description: |- A list of attributes (e.g. size, color, length) that define each variant of a product. **Note**: - You must retain at least 1 sales attribute, deleting all existing sales attributes is not allowed. - You can only have up to 3 types of sales attributes per product. - Each SKU must include the same number and type of sales attributes. For example, you cannot have one SKU that has only a Color attribute, while another SKU has both Color and Size attributes. - Provide either a built-in ID or a custom name; if both are provided, the ID takes priority. - The `id/name` and `value_id/value_name` pairs must be unique in each SKU. For example, you cannot repeat `"name": "Color"`, `"value_name": "Red"` in different SKUs. seller_sku: type: string description: |- An internal code/name for managing SKUs, not visible to buyers. Valid length: - DE, ES, FR, IT, PL, NL, BE, CZ, AT, GR, PT, HU: 6-50 characters - Other regions: 1-50 characters Format: - DE, ES, FR, IT, PL, NL, BE, CZ, AT, GR, PT, HU: Use alphabets, numbers, hyphens (-), or underscores (_) only - Other regions: Text without spaces price: $ref: "#/components/schemas/CreateProductRequestSkuPrice" description: |- SKU pricing information. **Note**: If you omit this object in the API request, the existing information will remain unchanged. external_sku_id: type: string maxLength: 999 description: |- An external identifier used in an external ecommerce platform. This is used to associate the SKU between TikTok Shop and the external ecommerce platform. Max length: 999 characters identifier_code: $ref: "#/components/schemas/IdentifierCode" description: |- A regulated identifier code assigned to a product based on international standardized regulations (e.g. GTIN) to ensure the product is universally identifiable across various platforms and systems. **Note**: Editable only if the product is in DRAFT state. Otherwise, changes are not allowed. inventory: type: array items: $ref: "#/components/schemas/Inventory" description: |- SKU inventory information. **Note**: - If you omit this object array in the API request, the existing information will remain unchanged. - If you are saving a post-live draft with `save_mode=AS_DRAFT`, this field is not supported and will not be saved. When using Get Product to retrieve the draft, the values will reflect those in the base version. combined_skus: type: array items: $ref: "#/components/schemas/CombinedSku" description: If this SKU belongs to a virtual bundle, this object contains the list of individual SKUs that form the bundle (e.g. gift basket, starter pack). sku_unit_count: type: string description: |- The total quantity/volume of the product represented by the SKU. For example, if the SKU represents 500ml of water, this value would be 500 if the unit type is defined as ml. Valid range: [0.01, 99,999.9999] Applicable only for the EU market. **Note**: - This is mainly used to calculate the unit price of the SKU, and is required only if you wish to display the unit price to facilitate easier price comparisons across different products and packaging sizes. - Unit price = Selling price/(SKU unit count/base unit count). Therefore if you want to obtain the unit price, you would also need to define the "base unit count" and the "unit type" product attributes. Retrieve the relevant information for these product attributes by using the [Get Attributes API](https://partner.tiktokshop.com/docv2/page/6509c5784a0bb702c0561cc8). The unit price would then be returned in the [Get Product API](https://partner.tiktokshop.com/docv2/page/6509d85b4a0bb702c057fdda). external_urls: type: array items: type: string description: |- A list of URLs for third-party product listing pages where consumers can place orders. Add this property if you have products listed on third-party sites other than TikTok Shop and would like to map them. Max string length: 500 extra_identifier_codes: type: array items: type: string description: |- If the SKU belongs to a virtual bundle (containing multiple individual SKUs), you can add up to 10 additional identifier codes here for the SKUs included in the bundle. **Format**: GTIN: 14 digits EAN: 8, 13, or 14 digits UPC: 12 digits ISBN: 13 digits, or 9 digits ending in capital `X` **Note**: - Applicable only for the EU market. - The identifier code must be unique for each SKU, with no repetition allowed. pre_sale: $ref: "#/components/schemas/EditProductRequestSkuPreSale" description: |- SKU presale information, used to tag a product as a presale product based on its presale type. Applicable only if `allowed_special_product_types` from [Get Category Rules](6509c0febace3e02b74594a9) is not empty. **General usage rules**: - Omit this object to retain the current presale settings. **Rules for the US market**: - Regular / Preorder product: Once the product goes live, you cannot change the product type. - Made-to-order product: You can change it to a regular product at any time. list_price: $ref: "#/components/schemas/ListPrice" description: |- The SKU's list price information. This is equivalent to the manufacturer's suggested retail price (MSRP), or the recommended retail price (RRP). Applicable only for US local sellers. **Note**: This value may appear as the strikethrough price on the product page. However, whether the strikethrough price is shown and the amount shown are subject to the audit team's review and decision based on various pricing information. external_list_prices: type: array items: $ref: "#/components/schemas/ExternalListPrice" description: |- The SKU list price (e.g. MSRP, RRP) or original price information on external ecommerce platforms. Applicable only for selected local sellers in the US market. **Note**: This value may appear as the strikethrough price on the product page. However, whether the strikethrough price is shown and the amount shown are subject to the audit team's review and decision based on various pricing information. fees: type: array items: $ref: "#/components/schemas/Fee" description: The fees required for this product based on TikTok Shop policies. Fees are required only for certain product categories, retrieve the requirements from the [Get Category Rules API](https://partner.tiktokshop.com/docv2/page/6509c0febace3e02b74594a9). sku_dimensions: $ref: "#/components/schemas/SkuDimension" description: |- The dimensions of the sku. Note: - Provide the dimensions measured after packing the product. - These values impact the shipping cost, so it is important to ensure that dimensions are accurate. Any discrepancies in measurements may lead to additional shipping fees. - Optional for ID, TH, VN regions. sku_weight: $ref: "#/components/schemas/SkuWeight" description: |- The packaged weight of the SKU. **Note**: - Provide the weight measured after packing the SKU. - Use the same measurement system for `sku_weight` and `sku_dimensions`; for example, use `KILOGRAM` with `CENTIMETER`. - Weight and dimensions can affect shipping costs, so ensure both are accurate. Shipping fees may use the higher of the actual weight and the volumetric weight calculated from the dimensions. EditProductRequestSkuPreSale: type: object properties: type: type: string enum: - PRE_ORDER - MADE_TO_ORDER - CUSTOM - NONE x-enum-descriptions: - The product is not yet available or released. Fulfillment can be extended by specifying a release date. - The product is produced only after the order is received. Fulfillment can be extended by specifying a duration. - The product requires a fulfillment timeline that exceeds the standard due to other factors. Fulfillment can be extended by specifying a duration. - To convert the product to a regular (non-presale) product. description: |- The type of pre-sale. Possible values based on the region: **US** - `PRE_ORDER`: The product is not yet available or released. Fulfillment can be extended by specifying a **release date**. - `MADE_TO_ORDER`: The product is produced only after the order is received. Fulfillment can be extended by specifying a **duration**. - `CUSTOM`: The product requires a fulfillment timeline that exceeds the standard due to other factors. Fulfillment can be extended by specifying a **duration**. **UK, EU, SEA, JP, and LATAM** - `PRE_ORDER`: The product is not yet available or released. Fulfillment can be extended by specifying a **duration**. **ALL** - `NONE`: To convert the product to a regular (non-presale) product. fulfillment_type: $ref: "#/components/schemas/FulfillmentType" description: |- Information about the type of pre-sale order fulfillment and the corresponding timeframe. - `handling_duration_days` is for fulfillment with an extended duration. - `release_date` is for starting fulfillment on a fixed date. **Note**: Provide either the `handling_duration_days` or the `release_date`, depending on the value of `pre_sale.type` and your shop's region. EditProductRequestSubscribeInfoEdit: type: object properties: subscribe_status: type: string description: |- An enum outlining whether the given product has an active Subscribe and Save promotion: - ENABLED - NOT_ENABLED This field is required if the subscription is being created or modified. discount_details: type: array items: $ref: "#/components/schemas/DiscountDetail" description: All of the Save and Subscribe discount details. EditProductResponse: 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/EditProductResponseData" EditProductResponseData: type: object properties: product_id: type: string description: The product ID generated by TikTok Shop. skus: type: array items: $ref: "#/components/schemas/CreateProductResponseDataSku" description: A list of Stock Keeping Units (SKUs) used to identify distinct variants of the product. warnings: type: array items: $ref: "#/components/schemas/Warning" description: Warning information that the API caller needs to pay special attention to. audit: $ref: "#/components/schemas/EditProductResponseDataAudit" description: |- Product audit information. **Note**: Applicable only to products listed on TikTok Shop. Not applicable for products listed only on Tokopedia. EditProductResponseDataAudit: type: object properties: status: type: string enum: - NONE - AUDITING - APPROVED x-enum-descriptions: - The product is not applicable for audit because it has not been submitted for listing on this platform, or it is in a draft, frozen, or deactivated state. - The product is currently being audited. - If you only edited the `price` or `inventory` fields of an approved product, the product remains approved and the new information is immediately published on the platform. description: |- The product audit status. Possible values: - NONE: The product is not applicable for audit because it has not been submitted for listing on this platform, or it is in a draft, frozen, or deactivated state. - AUDITING: The product is currently being audited. - APPROVED: If you only edited the `price` or `inventory` fields of an approved product, the product remains approved and the new information is immediately published on the platform. EditSizeChartV2Request: type: object properties: size_chart_data: $ref: "#/components/schemas/SizeChartData" description: Complete replacement size-chart data, including the structured table, measurement type, unit system, and optional descriptive metadata. size_chart_id: type: string description: The ID of the seller-owned reusable size chart template to update. template_name: type: string description: The new name of the size chart template. If omitted, the current name remains unchanged. required: - size_chart_data - size_chart_id EditSizeChartV2Response: 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/EditSizeChartV2ResponseData" EditSizeChartV2ResponseData: type: object properties: size_chart_id: type: string description: The ID of the updated size chart. This is the same ID provided in `size_chart_id`. EndSessionRequest: type: object properties: {} EndSessionResponse: 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/EndSessionResponseData" EndSessionResponseData: type: object properties: {} Error: type: object properties: code: type: integer format: int64 description: The error code. message: type: string description: A human-readable error message. detail: $ref: "#/components/schemas/Detail" description: Additional detail about the product showcase addition error. EstimateArrivalTime: type: object properties: start_timestamp: type: string description: Start of the estimated arrival time window as a Unix timestamp in seconds. For example, `1774162800` corresponds to Sunday, 2026-03-22 at 00:00 PDT (`2026-03-22T07:00:00Z`). Use the exact `start_timestamp` returned in `available_time_window_list` by the `ListAvailableInboundMethod` API. end_timestamp: type: string description: End of the estimated arrival time window as a Unix timestamp in seconds. For example, `1774767600` corresponds to Sunday, 2026-03-29 at 00:00 PDT (`2026-03-29T07:00:00Z`). Use the exact `end_timestamp` returned in `available_time_window_list` by the `ListAvailableInboundMethod` API. required: - start_timestamp - end_timestamp EstimatedBonusCommission: type: object properties: amount: type: string description: When available, the estimated 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. EstimatedCommission: type: object properties: amount: type: string description: The estimated 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. EstimatedCommissionBase: type: object properties: amount: type: string description: The estimated 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. currency: type: string description: The currency code. EstimatedCreatorCommissionRewardFee: type: object properties: amount: type: string description: When available, the estimated 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. EstimatedShopAdsCommission: type: object properties: amount: type: string description: The estimated 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. EstimatedStandardCommission: 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 ExchangeOrderLine: type: object properties: order_line_id: type: string description: Ignore this field. It is not yet supported. sku_id: type: string description: Ignore this field. It is not yet supported. sku_name: type: string description: Ignore this field. It is not yet supported. product_name: type: string description: Ignore this field. It is not yet supported. seller_sku_name: type: string description: Ignore this field. It is not yet supported. product_image: $ref: "#/components/schemas/ProductImage" description: Ignore this field. It is not yet supported. price_detail: $ref: "#/components/schemas/PriceDetail" description: Ignore this field. It is not yet supported. ExternalListPrice: type: object properties: source: type: string enum: - SHOPIFY_COMPARE_AT_PRICE x-enum-descriptions: - The compare_at_price in Shopify. description: |- The external ecommerce platform from which the price is sourced. Possible values: - SHOPIFY_COMPARE_AT_PRICE: The compare_at_price in Shopify. amount: type: string description: |- The price amount. Valid range: [0.01, 7600] currency: type: string enum: - USD description: |- The currency. Possible values: USD required: - source - amount - currency ExternalOrder: type: object properties: id: type: string description: Order ID in your OMS. platform: type: string description: The alias of your OMS. line_items: type: array items: $ref: "#/components/schemas/GetExternalOrderReferencesResponseDataExternalOrderLineItem" description: Line item references between the external order and TikTok Shop. FBTInventoryUpdateWebhook: type: object properties: type: type: integer const: 24 description: The ID of the webhook type. tts_notification_id: type: string description: The ID of this webhook notification. seller_open_id: type: string description: The open_id of the seller. For more information, refer to [Authorization overview](authorization-overview-202407). timestamp: type: integer format: int64 description: The time when this webhook is triggered. Unix timestamp. data: $ref: "#/components/schemas/FBTInventoryUpdateWebhookData" required: - type FBTInventoryUpdateWebhookData: type: object properties: goods_id: type: string description: FBT goods ID. sku_id: type: string description: TikTok Shop SKU ID. fbt_warehouse_inventory: type: array items: $ref: "#/components/schemas/FBTInventoryUpdateWebhookDataFbtWarehouseInventory" description: Inventory in different FBT warehouses. update_time: type: integer format: int64 description: The time when the action occurred. Unix timestamp. FBTInventoryUpdateWebhookDataFbtWarehouseInventory: type: object properties: fbt_warehouse_id: type: string description: ID of the FBT warehouse. on_hand_detail: $ref: "#/components/schemas/FBTInventoryUpdateWebhookDataFbtWarehouseInventoryOnHandDetail" description: The number of units physically in the warehouse, excluding those in transit or damaged. FBTInventoryUpdateWebhookDataFbtWarehouseInventoryOnHandDetail: type: object properties: total_quantity: type: integer format: int64 description: The total number of units. reserved_quantity: type: integer format: int64 description: The number of units reserved for confirmed orders and yet to be outbound. available_quantity: type: integer format: int64 description: The number of units available for sale. This does not include reserved units. FBTMerchantOnboardingWebhook: type: object properties: type: type: integer const: 22 description: The ID of the webhook type. tts_notification_id: type: string description: The ID of this webhook notification. seller_open_id: type: string description: The open_id of the seller. For more information, refer to [Authorization overview](authorization-overview-202407). timestamp: type: integer format: int64 description: The UNIX timestamp when the FBT onboarding status is updated. data: $ref: "#/components/schemas/FBTMerchantOnboardingWebhookData" required: - type FBTMerchantOnboardingWebhookData: type: object properties: onboarded_regions: type: array items: $ref: "#/components/schemas/FBTMerchantOnboardingWebhookDataOnboardedRegion" description: All onboarded FBT regions. update_time: type: integer format: int64 description: The latest update time. Unix timestamp. FBTMerchantOnboardingWebhookDataOnboardedRegion: type: object properties: region_code: type: string description: Onboarded FBT region code. FailReason: type: object properties: message: type: string description: The error message. FailedMaterial: type: object properties: material_id: type: string description: Material ID. fail_reason: type: string description: Fail reason. Fee: type: object properties: type: type: string enum: - PFAND description: |- The type of fee. Possible values: PFAND amount: type: string description: |- The fee amount. Valid range: - PFAND: [0.00 - 6300.00] additional_attribute: type: string enum: - SINGLE_USE - REUSABLE - NOT_APPLICABLE description: |- An optional attribute that provides additional context for the fee. The accepted values may vary by fee type and market. Possible values for Pfand: - SINGLE_USE - REUSABLE - NOT_APPLICABLE File: type: object properties: id: type: string description: |- The ID of the certification file. Use the [Upload Product File API](https://partner.tiktokshop.com/docv2/page/6509dffdc16ffe02b8dc10c5) to upload the files first and obtain the corresponding file ID. name: type: string description: The name of the certification file, including the file extension. format: type: string description: The format of the certification file. Only PDF is supported. required: - id - name - format FlammableLiquidsExtraInfo: type: object properties: flammable_liquids_type: type: string enum: - PAINT - PERFUMERY - ALCOHOLIC - OTHER description: |- Flammable-liquid type. Possible values: - PAINT - PERFUMERY - ALCOHOLIC - OTHER flammable_liquids_volume: type: string description: Volume of flammable liquid in the unit specified by volume_unit. volume_unit: type: string description: Unit for flammable_liquids_volume, such as MILLILITERS. required: - flammable_liquids_type - flammable_liquids_volume FreeSampleRule: type: object properties: has_free_sample: type: boolean description: If set to `true`, free samples are provided to creators invited to the target collaboration group. If set to `false`, free samples are not provided. is_sample_approval_exempt: type: boolean description: If set to `true`, creators invited to the target collaboration are exempt from seller review and are automatically approved for a free product sample. Note that the `has_free_sample` property overrides the free sample behavior. required: - has_free_sample - is_sample_approval_exempt FulfillmentType: type: object properties: handling_duration_days: type: integer format: int64 description: |- The desired duration for handling a pre-sale order and handing it over to a shipping carrier. Applicable only for the following regions and pre-sale type: **US** - `MADE_TO_ORDER`: Business days, from 3 to 14 days. - `CUSTOM`: Business days, from 3 to 30 days. **UK, EU, SEA, JP, and LATAM** - `PRE_ORDER`: Calendar days, from 3 to 30 days. release_date: type: integer format: int64 description: |- The date on which the product gets converted into a regular product and becomes available for general purchase. On this date, order handling will also start, changing the status of the order to [`AWAITING_SHIPMENT`](https://partner.tiktokshop.com/docv2/page/650b1b4bbace3e02b76d1011). Applicable only for `PRE_ORDER` in the US. **Note**: - Valid range: The date must fall within 3 - 60 days from the current date. - This date is a unix timestamp (seconds) based on the seller-selected timezone in Seller Center. - This date cannot be modified once the product goes live. GenderDistribution: type: object properties: gender: type: string enum: - MALE - FEMALE x-enum-descriptions: - male viewers - female viewers description: |- Viewer gender. Possible values: - MALE: male viewers - FEMALE: female viewers percentage: type: string description: Proportion for the corresponding gender within this viewer profile, expressed as a decimal fraction. GenerateAffiliatePartnerCampaignProductLinkRequest: type: object properties: creator_commission_rate: type: integer format: int64 description: The commission rate paid to a creator, in hundredths of a percent (0.01%). The value must be at least 100 (1%) and no greater than the total commission rate set by the seller. required: - creator_commission_rate GenerateAffiliatePartnerCampaignProductLinkResponse: 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/GenerateAffiliatePartnerCampaignProductLinkResponseData" GenerateAffiliatePartnerCampaignProductLinkResponseData: type: object properties: product_promotion_link: type: string description: A URL for product promotion content. This URL is provided to agencies for sharing with colloborating creators. Creators share this link with followers via the TikTok App. Note that creators control whether or not to add products to their showcase in the pop-up window. GenerateAffiliateProductPromotionLinkRequest: type: object properties: {} GenerateAffiliateProductPromotionLinkResponse: 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/GenerateAffiliateProductPromotionLinkResponseData" GenerateAffiliateProductPromotionLinkResponseData: type: object properties: product_promotion_link: type: string description: The URL for a web page with information about the product promotion. GenerateCampaignProductPromotionLinksInBatchRequest: type: object properties: product_ids: type: array items: type: string description: The list of product IDs. The max length is 50. GenerateCampaignProductPromotionLinksInBatchResponse: 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/GenerateCampaignProductPromotionLinksInBatchResponseData" GenerateCampaignProductPromotionLinksInBatchResponseData: type: object properties: product_promotion_links: type: array items: $ref: "#/components/schemas/GenerateCampaignProductPromotionLinksInBatchResponseDataProductPromotionLink" description: The list of products for which the promotion links are generated successfully. failed_product_ids: type: array items: type: string description: The list of products for which the promotion links failed to be generated. GenerateCampaignProductPromotionLinksInBatchResponseDataProductPromotionLink: type: object properties: product_id: type: string description: The ID of the product to promote. link: type: string description: This is the product promotion link that agencies can share with collaborated creators. Creators can copy/paste this link into the web browser. Creators will be re-directed to the add-product-link page in the Tikotk app. Creators can decide whether to add products to their showcases in the pop-up window. GenerateGeneralSharingLinksRequest: type: object properties: material: $ref: "#/components/schemas/GenerateGeneralSharingLinksRequestMaterial" description: The entities for which the sharing links are generated. campaign_id: type: string description: If a creator adds products from a campaign, please include the campaign ID. The campaign ID can be found in the Affiliate Center or retrieved using the Get Affiliate Partner Campaign List API. link_type: type: string description: |- Optional. For Tokopedia agencies, set this field to `TOKO`. The response returns the Tokopedia product URL in `sharing_link` and omits `deep_link` and `one_link`. If this field is omitted or set to another value, the response returns the TikTok Shop product URL in `sharing_link`. For `PRODUCT` requests, `deep_link` and `one_link` are also returned. required: - material GenerateGeneralSharingLinksRequestMaterial: type: object properties: ids: type: array items: type: string description: The list of material IDs. For `PRODUCT` requests, provide 1 to 50 product IDs. type: type: string description: |- Right now, the only possible value is `PRODUCT`. When `type` is `PRODUCT`, use product IDs for `ids`. promotion_campaign_schema: type: string description: When type is set to CAMPAIGN, this field is required. This schema is associated with the Campaign page. required: - ids - type GenerateGeneralSharingLinksResponse: 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/GenerateGeneralSharingLinksResponseData" GenerateGeneralSharingLinksResponseData: type: object properties: sharing_links: type: array items: $ref: "#/components/schemas/GenerateGeneralSharingLinksResponseDataSharingLink" description: The successfully generated sharing links. failed_materials: type: array items: $ref: "#/components/schemas/FailedMaterial" description: The list of materials which failed to generate sharing links for. GenerateGeneralSharingLinksResponseDataSharingLink: type: object properties: material_id: type: string description: Material ID. sharing_link: type: string description: |- This is the product promotion link that agencies can share with collaborated creators. Creators can copy/paste this link into the web browser. After you have the links, add the following request parameters and their corresponding values to the end of the link URL. When a user places an order using this link, the resulting e-commerce order will carry these parameters as part of its information: - event_id: Unique event id for each click - publisher_id: The unique publish_id assigned by CJ Nice to have - publisher_name: From CJ publisher profile. - device_type: 1-mobile, 2-desktop. - device_id: The clicks from the same device id can be aggregated as UV. - referrer_src: The URL of the webpage that a user came from before landing on the current share link. deep_link: type: string description: |- A product promotion app deep link that opens the corresponding TikTok Shop product detail page. It is returned for `PRODUCT` requests that use the TikTok Shop link type and is omitted when `link_type` is `TOKO`. Agencies can share this link with collaborated creators, and creators can share it with users. Use `one_link` for the HTTPS link that can be opened in a web browser. To enable attribution, replace the `o_event_id` placeholder in the returned `deep_link` URL with a developer-generated unique ID for each click. Do not URL-encode or URL-decode the returned link. If a user places an order through this link, the resulting e-commerce order carries the event ID for tracking. one_link: type: string description: |- A product promotion one-link that opens the corresponding TikTok Shop product detail page. It is returned for `PRODUCT` requests that use the TikTok Shop link type and is omitted when `link_type` is `TOKO`. Agencies can share this link with collaborated creators, and creators can copy and paste it into a web browser or share it with users. To enable attribution, replace the `o_event_id` placeholder in the returned `one_link` URL with a developer-generated unique ID for each click. Do not URL-encode or URL-decode the returned link. If a user places an order through this link, the resulting e-commerce order carries the event ID for tracking. If the user does not have TikTok installed, the link redirects the user to the app store to install TikTok. GeneratePublisherSharingLinksInBatchRequest: type: object properties: material: $ref: "#/components/schemas/GeneratePublisherSharingLinksInBatchRequestMaterial" description: The entities for which the sharing links are generated. campaign_id: type: string description: If a creator adds products from a campaign, please include the campaign ID. The campaign ID can be found in the Affiliate Center or retrieved using the Get Affiliate Partner Campaign List API. link_type: type: string description: |- Controls the `sharing_link` returned when `material.type` is `PRODUCT`. - Set to `TOKO` for a Tokopedia product URL. This option is for Tokopedia agencies. - Omit this field for a TikTok Shop product URL. required: - material GeneratePublisherSharingLinksInBatchRequestMaterial: type: object properties: ids: type: array items: type: string description: The list of material IDs. The maximum length is 50. When `type` is `PRODUCT`, provide 1 to 50 product IDs. type: type: string enum: - PRODUCT - CAMPAIGN x-enum-descriptions: - Provide product IDs in `ids`. - Provide `promotion_campaign_schema`. description: |- The material type. Possible values: - `PRODUCT`: Provide product IDs in `ids`. - `CAMPAIGN`: Provide `promotion_campaign_schema`. promotion_campaign_schema: type: string description: When `type` is set to `CAMPAIGN`, this field is required. This schema is associated with the Campaign page. required: - ids - type GeneratePublisherSharingLinksInBatchResponse: 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/GeneratePublisherSharingLinksInBatchResponseData" GeneratePublisherSharingLinksInBatchResponseData: type: object properties: sharing_links: type: array items: $ref: "#/components/schemas/GeneratePublisherSharingLinksInBatchResponseDataSharingLink" description: Generated affiliate sharing links for successfully processed materials for the publisher specified in the path. failed_materials: type: array items: $ref: "#/components/schemas/FailedMaterial" description: The list of materials which failed to generate sharing links for. GeneratePublisherSharingLinksInBatchResponseDataSharingLink: type: object properties: material_id: type: integer format: int64 description: Material ID. sharing_link: type: string description: This is the product promotion link that agencies can share with collaborated publishers. The publishers can post this link at their will. deep_link: type: string description: |- A product promotion deep link that opens the corresponding TikTok Shop product detail page. Agencies can share this link with collaborated creators, and creators can copy/paste it into a web browser (or share it to users). If a user places an order via this link, the resulting e-commerce order will carry these parameter values for tracking. one_link: type: string description: |- A product promotion one-link that opens the corresponding TikTok Shop product detail page. Agencies can share this link with collaborated creators, and creators can copy/paste it into a web browser (or share it to users). If a user places an order via this link, the resulting e-commerce order will carry these parameter values for tracking. If the user does not have TikTok installed on their phone, they will be redirected to the app store to install TikTok. GenerateTargetCollaborationLinkRequest: type: object properties: {} GenerateTargetCollaborationLinkResponse: 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/GenerateTargetCollaborationLinkResponseData" GenerateTargetCollaborationLinkResponseData: type: object properties: link: type: string description: The link of the target invitation, the creator can jump to the page of adding products after clicking. GetActiveShopsResponse: 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/GetActiveShopsResponseData" GetActiveShopsResponseData: type: object properties: shops: type: array items: $ref: "#/components/schemas/GetActiveShopsResponseDataShop" description: |- The list of active shops that belong to the seller. Note: Local sellers only have 1 shop. GetActiveShopsResponseDataShop: type: object properties: id: type: string description: The ID of the shop. region: type: string description: The region of the shop. GetActivityResponse: 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/GetActivityResponseData" GetActivityResponseData: type: object properties: activity_id: type: string description: A unique ID that identifies different activities. title: type: string description: Activity name (50 characters max.) The name must be unique. activity_type: type: string enum: - FIXED_PRICE - DIRECT_DISCOUNT - FLASHSALE - SHIPPING_DISCOUNT - BUY_MORE_SAVE_MORE - GIFT_WITH_PURCHASE - BUY_X_GET_Y x-enum-descriptions: - A product discount activity with a fixed price. - A product discount activity with a percentage discount. - A flash sale activity. - A shipping fee discount activity. - A Buy More Save More promotion. - A Gift With Purchase promotion. - A Buy X Get Y promotion. description: |- The activity type. Possible values: - `FIXED_PRICE`: A product discount activity with a fixed price. - `DIRECT_DISCOUNT`: A product discount activity with a percentage discount. - `FLASHSALE`: A flash sale activity. - `SHIPPING_DISCOUNT`: A shipping fee discount activity. - `BUY_MORE_SAVE_MORE`: A Buy More Save More promotion. - `GIFT_WITH_PURCHASE`: A Gift With Purchase promotion. - `BUY_X_GET_Y`: A Buy X Get Y promotion. duration_type: type: string description: |- The effective time type of the current activity - NORMAL: `begin_time` and `end_time` must be filled - INDEFINITE: `begin_time` and `end_time` aren't required, and the promotion will be a long-term activity which runs indefinitely. 1. `INDEFINITE` is only valid when `activity_type` is `SHIPPING_DISCOUNT`, 2. If `duration_type` is `INDEFINITE`, `start_time` and `end_time` should be 0 Default: NORMAL begin_time: type: integer format: int64 description: Activity start time as a UNIX timestamp in seconds. end_time: type: integer format: int64 description: Activity end time as a UNIX timestamp in seconds. participation_limit: type: array items: $ref: "#/components/schemas/GetActivityResponseDataParticipationLimit" description: The number of times a buyer can participate in the promotion. products: type: array items: $ref: "#/components/schemas/GetActivityResponseDataProduct" description: |- Product List. Note:If `FIXED_PRICE`, `DIRECT_DISCOUNT` and `FLASHSALE` activity that ended more than 180 days,this field is empty. status: type: string enum: - DRAFT - NOT_START - ONGOING - EXPIRED - DEACTIVATED - NOT_EFFECTIVE x-enum-descriptions: - Promotion activities with this status are not available to TikTok users. - Promotion activities with this status are not available to TikTok users until the set activity start time. - Promotion activities with this status are available to TikTok users. - Promotion activities with this status are not available to TikTok users because it has expired. - The activity has been deactivated by the seller and is not available to TikTok users. - The activity is terminated by the platform and is not available to TikTok users. description: |- Activity status. Possible values: - DRAFT: Promotion activities with this status are not available to TikTok users. - NOT_START: Promotion activities with this status are not available to TikTok users until the set activity start time. - ONGOING: Promotion activities with this status are available to TikTok users. - EXPIRED: Promotion activities with this status are not available to TikTok users because it has expired. - DEACTIVATED: The activity has been deactivated by the seller and is not available to TikTok users. - NOT_EFFECTIVE: The activity is terminated by the platform and is not available to TikTok users. create_time: type: integer format: int64 description: Activity creation time as a UNIX timestamp in milliseconds. update_time: type: integer format: int64 description: Activity update time as a UNIX timestamp in milliseconds. product_level: type: string enum: - PRODUCT - VARIATION - SHOP x-enum-descriptions: - Product level promotion activity. - SKU level promotion activity. - Shop level promotion activity. description: |- Activity product dimension, values are: - PRODUCT: Product level promotion activity. - VARIATION: SKU level promotion activity. - SHOP: Shop level promotion activity. activity_commands: type: array items: type: string description: |- Applicable commands to the activity: - IMMUTABLE: The activity cann't be editable or deactivated discount: $ref: "#/components/schemas/GetActivityResponseDataDiscount" description: Type-specific discount information. This field is omitted for `FIXED_PRICE`, `DIRECT_DISCOUNT`, and `FLASHSALE` activities. For other supported activity types, use the corresponding nested discount object when it is returned. target_user_info: $ref: "#/components/schemas/GetActivityResponseDataTargetUserInfo" description: The targeted user type of the promotion. benefit_products: type: array items: $ref: "#/components/schemas/GetActivityResponseDataBenefitProduct" description: Benefit products in BXGY promotions auction_support_type: type: string enum: - ALL - EXCLUDE_AUCTION x-enum-descriptions: - The activity supports both normal products and auction products. - The activity does not support auction products. description: |- Whether a `SHIPPING_DISCOUNT` activity supports auction products. This field is omitted for other activity types and can also be omitted for a shipping-discount activity when auction-support data is unavailable. Possible values: - `ALL`: The activity supports both normal products and auction products. - `EXCLUDE_AUCTION`: The activity does not support auction products. GetActivityResponseDataBenefitProduct: type: object properties: id: type: string description: TikTokShop product ID GetActivityResponseDataDiscount: type: object properties: shipping_discount: $ref: "#/components/schemas/GetActivityResponseDataDiscountShippingDiscount" description: Shipping discount bmsm_discount: $ref: "#/components/schemas/GetActivityResponseDataDiscountBmsmDiscount" description: Configurations related to Buy More Save More (BMSM) promotions. gift_discount: $ref: "#/components/schemas/GetActivityResponseDataDiscountGiftDiscount" description: Configurations related to Gift With Purchase (GWP) promotions. Only needs to be configured for GWP promotions. bxgy_discount: $ref: "#/components/schemas/GetActivityResponseDataDiscountBxgyDiscount" description: Configurations related to Buy X Get Y (BXGY) promotions. Only needs to be configured for BXGY promotions. GetActivityResponseDataDiscountBmsmDiscount: type: object properties: details: type: array items: $ref: "#/components/schemas/GetActivityResponseDataDiscountBmsmDiscountDetail" description: |- Configurations for BMSM promotions. A maximum of two `tier`s are permitted. `details.threshold_type` and `details.type` must be the same across all `tier`s. GetActivityResponseDataDiscountBmsmDiscountDetail: type: object properties: tier: type: integer format: int64 description: |- `tier` uses 1-based indexing, i.e. the first and second tiers are counted "1, 2", not "0, 1". `threshold_value` and `value` for a given tier must be greater than that of the previous tier. E.g. If `tier`==1 has `threshold_value`==`20` and `value`== `15`, `tier`==2 must have `threshold_value` > `20` and `value`>`15`. threshold_type: type: string enum: - MINIMAL_ITEM_QUANTITY - MINIMAL_ORDER_AMOUNT x-enum-descriptions: - Buyer must meet or exceed the minimum spend criteria with eligible products. - Buyer must meet or exceed the minimum spend criteria with eligible order. description: |- The type of purchase criteria. Possible enumerations are: - `MINIMAL_ITEM_QUANTITY`: Buyer must meet or exceed the minimum spend criteria with eligible products. - `MINIMAL_ORDER_AMOUNT`: Buyer must meet or exceed the minimum spend criteria with eligible order. threshold_value: type: string description: |- The purchase threshold of the discount, based on the `threshold_type`, e.g., "3". Determined by user. - When `threshold_type==NO_THRESHOLD`, this value is not required. - When `threshold_type==MINIMAL_ITEM_QUANTITY`, buyer must purchase at least the specified number of eligible products (e.g. must purchase 3 or more eligible products to receive the benefit). If it represents a quantity, it must be an integer. - When `threshold_type==MINIMAL_ORDER_AMOUNT`, the eligible product subtotal for the buyer's order must meet or exceed the specified order value in local currency (e.g. buyer's order subtotal must be at least $3 to receive the benefit). If it represents an order value, it must be limited to two decimal places. type: type: string enum: - PERCENTAGE_OFF - AMOUNT_OFF x-enum-descriptions: - Buyer will receive X% off the price of the eligible products. - Buyer will receive X units of local currency off the price of eligible products. description: |- The type of discount awarded as a benefit. The value of the discount is determined by `value`. Possible enumerations are: - `PERCENTAGE_OFF`: Buyer will receive X% off the price of the eligible products. - `AMOUNT_OFF`: Buyer will receive X units of local currency off the price of eligible products. value: type: string description: |- Value of the discount. - When `type`==`PERCENTAGE_OFF`, the buyer will receive X% off the price of eligible products. If the value represents a percentage, it should be an integer. - `type`==`AMOUNT_OFF`, the buyer will receive X units of local currency off the price of eligible products. If the value represents a monetary amount, it should be limited to two decimal places. GetActivityResponseDataDiscountBxgyDiscount: type: object properties: threshold_type: type: string enum: - MINIMAL_ITEM_QUANTITY - MINIMAL_ORDER_AMOUNT x-enum-descriptions: - The buyer must purchase at least the specified quantity of eligible products. - The eligible-product subtotal must reach the specified amount. description: |- The purchase criterion returned for the activity. Possible values: - `MINIMAL_ITEM_QUANTITY`: The buyer must purchase at least the specified quantity of eligible products. - `MINIMAL_ORDER_AMOUNT`: The eligible-product subtotal must reach the specified amount. threshold_value: type: string description: |- The purchase threshold returned for the activity, based on `threshold_type`. - When `threshold_type==MINIMAL_ITEM_QUANTITY`, this is the number of eligible products the buyer must purchase and must be an integer. - When `threshold_type==MINIMAL_ORDER_AMOUNT`, this is the eligible-product subtotal the buyer must reach, in local currency. discount_type: type: string enum: - PERCENTAGE_OFF - FREE - AMOUNT_OFF_EACH x-enum-descriptions: - Buyer will receive X% off the price of the eligible products. - Buyer will receive X eligible products for free. - Buyer will receive X units of local currency off the price of each eligible product. description: |- The type of discount awarded as a benefit. For PERCENTAGE_OFF and AMOUNT_OFF_EACH, the discount amount is determined by `discount_value`. Possible enumerations are: - `PERCENTAGE_OFF`: Buyer will receive X% off the price of the eligible products. - `FREE`: Buyer will receive X eligible products for free. - `AMOUNT_OFF_EACH`: Buyer will receive X units of local currency off the price of each eligible product. discount_value: type: string description: |- Value of the discount. - When `type`==`PERCENTAGE_OFF`, the buyer will receive X% off the price of eligible products. If the value represents a percentage, it should be an integer. - `type`==`AMOUNT_OFF_EACH`, the buyer will receive X units of local currency off the price of each eligible products. If the value represents a monetary amount, it should be limited to two decimal places. benefit_max_applicable_quantity: type: string description: The quantity of item Y in a BXGY promotion. This value must be a positive integer. benefit_max_applicable_times: type: string description: Optional. The maximum number of times the BXGY benefit can be applied within a single order. This value must be a positive integer. GetActivityResponseDataDiscountGiftDiscount: type: object properties: gift_receiving_type: type: string description: "The receiving type of gift. Currently only supports one type: `ALL_RECEIVE`" gift_infos: type: array items: $ref: "#/components/schemas/GetActivityResponseDataDiscountGiftDiscountGiftInfo" description: |- Configurations regarding Gift With Purchase (GWP) promotions. A maximum of two `tier`s are permitted in SEA and UK. Only one `tier` is permitted in US. And `threshold_type` must be the same across all `tier`s. GetActivityResponseDataDiscountGiftDiscountGiftInfo: type: object properties: tier: type: integer format: int64 description: |- `tier` uses 1-based indexing, i.e. the first and second tiers are counted "1, 2", not "0, 1". `threshold_value` for a given tier must be greater than that of the previous tier. E.g. If `tier`==1 has `threshold_value`==`2`, `tier`==2 must have `threshold_value` > `2`. threshold_type: type: string enum: - MINIMAL_ITEM_QUANTITY - MINIMAL_ORDER_AMOUNT x-enum-descriptions: - Buyer must meet or exceed the minimum spend criteria with eligible products. - Buyer must meet or exceed the minimum spend criteria with eligible order. description: |- purchase threshold type of discount. Possible enumerations are: - `MINIMAL_ITEM_QUANTITY`: Buyer must meet or exceed the minimum spend criteria with eligible products. - `MINIMAL_ORDER_AMOUNT`: Buyer must meet or exceed the minimum spend criteria with eligible order. threshold_value: type: string description: |- The purchase threshold value of the gift, based on `threshold_type`. Determined by the user. - When `threshold_type==MINIMAL_ITEM_QUANTITY`, the buyer must purchase at least the specified number of eligible products (for example, 3 eligible products). If it represents a quantity, it must be an integer. - When `threshold_type==MINIMAL_ORDER_AMOUNT`, the eligible-product subtotal must meet or exceed the specified value in local currency (for example, 3 units of local currency). If it represents an order value, it must be limited to two decimal places. gift_details: type: array items: $ref: "#/components/schemas/GetActivityResponseDataDiscountGiftDiscountGiftInfoGiftDetail" description: Gift configurations related to Gift With Purchase (GWP) promotions. GetActivityResponseDataDiscountGiftDiscountGiftInfoGiftDetail: type: object properties: product_id: type: string description: TikTok Shop product id of gift. sku_id: type: string description: TikTok Shop sku ID of gift. total_claim_limit: type: string description: The quantity limit of the gift sku which is involved in the activity. The range is [1, 99999]. If you are updating the value of an existing sku, the value cannot be decreased. GetActivityResponseDataDiscountShippingDiscount: type: object properties: threshold_type: type: string enum: - NO_THRESHOLD - MINIMAL_ITEM_QUANTITY - MINIMAL_ORDER_AMOUNT x-enum-descriptions: - No minimum purchase criteria. - Buyer must meet or exceed the minimum spend criteria with eligible products. - Buyer must meet or exceed the minimum spend criteria with eligible order. description: |- The type of purchase criteria. Possible enumerations are: - `NO_THRESHOLD`: No minimum purchase criteria. - `MINIMAL_ITEM_QUANTITY`: Buyer must meet or exceed the minimum spend criteria with eligible products. - `MINIMAL_ORDER_AMOUNT`: Buyer must meet or exceed the minimum spend criteria with eligible order. `MINIMAL_ITEM_QUANTITY` and `MINIMAL_ORDER_AMOUNT` can only be set when `product_level==SHOP`. threshold_value: type: string description: |- The purchase threshold returned for the shipping discount, based on `threshold_type`. - When `threshold_type==NO_THRESHOLD`, this value is not required. - When `threshold_type==MINIMAL_ITEM_QUANTITY`, this is the number of eligible products the buyer must purchase and must be an integer. - When `threshold_type==MINIMAL_ORDER_AMOUNT`, this is the eligible-product subtotal the buyer must reach in local currency (for example, 3 units of local currency) and must have no more than two decimal places. type: type: string description: |- The type of shipping discount returned for the promotion activity. - FREE_SHIPPING: The buyer's shipping charge is fully covered. - DISCOUNT_SHIPPING_FEE: The buyer's shipping charge is reduced by up to the amount in value. value: type: string description: |- Value of the discount. - When `type==FREE_SHIPPING`, this value is not required. - `type==DISCOUNT_SHIPPING_FEE`, this value is the maximum amount deducted from the buyer's price of shipping in local currency. The value should be limited to two decimal places. shipping_method: type: string description: |- The shipping methods to which this promotion applies. - When `STANDARD_SHIPPING`: Only applies to Standard Shipping methods, including Economy. - `EXPRESS_SHIPPING`: Only applies to Express Shipping methods. - `ALL_SHIPPING_METHOD`: Applies to all shipping methods that the shop offers. Default: `STANDARD_SHIPPING` inventory_type: type: string description: |- The inventory types to which the promotion activity applies: - `SELF_FULFILLED`: Only applies to Inventory fulfilled from seller warehouses - `FULFILLED_BY_TIKTOK`: Only applies to Inventory fulfilled by TikTok from FBT (Fulfilled by TikTok) warehouses. - `ALL`: Applies to all inventory of eligible products. Default: `SELF_FULFILLED` `FULFILLED_BY_TIKTOK` and `ALL` can only be set when `product_level`==`SHOP` and `threshold_type=NO_THRESHOLD`. area_scope: $ref: "#/components/schemas/GetActivityResponseDataDiscountShippingDiscountAreaScope" description: The (buyer's) geographical areas to which the promotion activity applies. GetActivityResponseDataDiscountShippingDiscountAreaScope: type: object properties: type: type: string description: |- The (buyer's) geographical area to which the promotion activity applies. ​- `WHOLE`: Promotion activity applies to all areas to which the seller offers fulfillment. - `SPECIFIC_AREAS`: Only applies to specific fulfillment areas, as defined in `area_scope.specific_areas`. 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)" GetActivityResponseDataParticipationLimit: type: object properties: type: type: string description: |- Determines whether the promotion activity limits the number of times each buyer can receive its benefit. e.g.: - `BUYER_NO_LIMIT`: No limit for buyer​s. Buyers can benefit from this promotion across multiple orders. - `BUYER_LIMIT_ONLY_ONE`: Buyers can benefit from this promotion activity for no more than one order. ​Default: `BUYER_NO_LIMIT` GetActivityResponseDataProduct: type: object properties: id: type: string description: TikTok Shop Product ID. activity_price: $ref: "#/components/schemas/ActivityPrice" description: Activity price. quantity_limit: type: integer format: int64 description: The quantity limit of the products involved in the activity. The range is `[1, 99]`, or `-1` for unlimited. quantity_per_user: type: integer format: int64 description: Limit of product purchase per buyer. The range is `[1, 99]`, or `-1` for unlimited. discount: type: string description: Discount value. If the product is 10% off, the value is `10`. Available only if `activity_type==DIRECT_DISCOUNT` and `product_level==PRODUCT`. skus: type: array items: $ref: "#/components/schemas/GetActivityResponseDataProductSku" description: Available only if `product_level==VARIATION`. used_quantity: type: integer format: int64 description: The quantity of products that have already taken effect in the activity. GetActivityResponseDataProductSku: type: object properties: id: type: string description: TikTok Shop SKU ID. discount: type: string description: Discount value. If the SKU is 10% off, the value is `10`. Available only if `activity_type==DIRECT_DISCOUNT`. quantity_limit: type: integer format: int64 description: The quantity limit of the SKU involved in the activity. The range is `[1, 99]`, or `-1` for unlimited. quantity_per_user: type: integer format: int64 description: Limit of SKU purchase per buyer. The range is `[1, 99]`, or `-1` for unlimited. activity_price: $ref: "#/components/schemas/ActivityPrice" description: Activity price. Available only if `activity_type==FIXED_PRICE/FLASHSALE`. used_quantity: type: integer format: int64 description: The quantity of SKU that have already taken effect in the activity. GetActivityResponseDataTargetUserInfo: type: object properties: user_type: type: string enum: - ALL_USER - SHOP_NEW_CUSTOMER - SHOP_EXISTING_CUSTOMER - SHOP_REPEAT_CUSTOMER - SHOP_ABANDONED_CHECKOUTS_CUSTOMER description: |- The targeted user type. Possible values: - `ALL_USER` - `SHOP_NEW_CUSTOMER` - `SHOP_EXISTING_CUSTOMER` - `SHOP_REPEAT_CUSTOMER` - `SHOP_ABANDONED_CHECKOUTS_CUSTOMER` GetAffiliateCampaignCreatorProductContentStatisticsResponse: 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/GetAffiliateCampaignCreatorProductContentStatisticsResponseData" GetAffiliateCampaignCreatorProductContentStatisticsResponseData: type: object properties: creator_content_statistics: type: array items: $ref: "#/components/schemas/GetAffiliateCampaignCreatorProductContentStatisticsResponseDataCreatorContentStatistic" description: A list of objects that represent content statistics for the associated creator. GetAffiliateCampaignCreatorProductContentStatisticsResponseDataCreatorContentStatistic: type: object properties: content_type: type: string description: "Content type: `VIDEO` for video content or `LIVE_ROOM` for live-room content." cover_img_url: type: string description: A URL for the live room cover image in the TikTok CDN.The video content doesn't have this value. source_url: type: string description: The URL on the public TikTok website at which the live room video can be played back. When content_type == VIDEO, the value is the url of the source video; when content_type == LIVE_ROOM, the value is the url where you can play back the recording of the live. view_count: type: string description: The number of public views of the live room or video. like_count: type: string description: The number of TikTok user likes associated with the live room or video. comment_num: type: string description: The number of TikTok user comments associated with the live room or video. paid_order_num: type: string description: The total number of paid orders associated with the live room or video. paid_amount: type: string description: The aggregate value of product orders associated with the live room or video. linked_tiktok_video: type: string description: The friendly URL for the video on the TikTok website. published_date: type: string format: date description: When content_type == VIDEO, this is the date when the video was published; when content_type == LIVE_ROOM, this is the date when the live started. The value is in YYYY_MM_DD format. content_end_date: type: - string - "null" format: date description: When content_type == VIDEO, this field is None; when content_type == LIVE_ROOM, this is the date when the live ended. The value is in YYYY_MM_DD format. GetAffiliateCampaignCreatorProductSampleStatusResponse: 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/GetAffiliateCampaignCreatorProductSampleStatusResponseData" GetAffiliateCampaignCreatorProductSampleStatusResponseData: type: object properties: sample_status: $ref: "#/components/schemas/GetAffiliateCampaignCreatorProductSampleStatusResponseDataSampleStatus" description: The creator's sample status GetAffiliateCampaignCreatorProductSampleStatusResponseDataSampleStatus: type: object properties: shipping_provider_name: type: string description: The name of the shipping provider delivery_option: type: string description: |- The delivery option: - ECONOMY_SHIPPING - PREMIUM_SHIPPING estimated_earliest_delivery_date: type: string description: The earliest estimated delivery date in Unix epoch format. estimated_latest_delivery_date: type: string description: The latest estimated delivery date in Unix epoch format. quantity: type: integer format: int64 description: The quantity of products delivered. tracking_results: type: array items: $ref: "#/components/schemas/GetAffiliateCampaignCreatorProductSampleStatusResponseDataSampleStatusTrackingResult" description: A list of objects representing tracking events. GetAffiliateCampaignCreatorProductSampleStatusResponseDataSampleStatusTrackingResult: type: object properties: tracking_event_update_date: type: string description: The date at which the tracking event was last updated, in Unix epoch format. tracking_event_description: type: string description: |- The title of the tracking event. - THE_PACKAGE_HAS_BEEN_DELIVERED - OUT_FOR_DELIVERY - ORDER_PACKED_AND_READY_FOR_DROP_OFF_AT_CARRIERS_FACILITY - ORDER_PLACED tracking_event_description_extended: type: string description: More information about the tracking event GetAffiliatePartnerCampaignDetailResponse: 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/GetAffiliatePartnerCampaignDetailResponseData" GetAffiliatePartnerCampaignDetailResponseData: type: object properties: id: type: string description: The campaign identifier. name: type: string maxLength: 50 description: "The campaign name. Maximum length: 50 characters." description: type: string maxLength: 1000 description: "The campaign description. Maximum length: 1000 characters." status: type: string description: |- The campaign status. The status is an enumerated type with values: - READY - UPCOMING - ONGOING - CLOSED region: type: string description: The region to which the campaign is associated. registration_start_time: type: integer format: int64 description: The scheduled start time for seller product registration as a Unix timestamp in seconds. This field can be updated only when the campaign status is `READY` or `UPCOMING`. registration_end_time: type: integer format: int64 description: The scheduled end time for seller product registration as a Unix timestamp in seconds. This field is no longer editable when the campaign status is `CLOSED`. campaign_start_time: type: integer format: int64 description: The scheduled campaign start time as a Unix timestamp in seconds. This field can be updated only when the campaign status is `READY` or `UPCOMING`. campaign_end_time: type: integer format: int64 description: The scheduled end time in Unix epoch time format for the campaign. Note that the end time must be less than 360 days from the start date. This field is no longer editable when the campaign status is set to `CLOSED`. commission_rate: type: integer format: int64 description: The total commission rate in hundredths of a percent (0.01%) units proposed by the affiliate partner for display to sellers. Commission rate must be greater than 100 and less than 8000. contact_info: $ref: "#/components/schemas/ContactInfo" description: The campaign creator's contact information. target_shops: type: array items: $ref: "#/components/schemas/GetAffiliatePartnerCampaignDetailResponseDataTargetShop" description: A list of TikTok Shop seller shop codes and names with permission to register for the campaign. target_seller_types: type: array items: type: string enum: - LOCAL - CROSS_BORDER description: |- A list of seller types eligible to register for the campaign. Use this field to broadly target seller types instead of the specific shops listed in `target_shops`. Possible values: - LOCAL - CROSS_BORDER GetAffiliatePartnerCampaignDetailResponseDataTargetShop: type: object properties: code: type: string description: The seller shop code in available in TikTok Shop Seller Central by clicking on the Seller Profile icon in the top right of the user interface. name: type: string description: The TikTok Shop name. GetAffiliatePartnerCampaignListResponse: 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/GetAffiliatePartnerCampaignListResponseData" GetAffiliatePartnerCampaignListResponseData: type: object properties: campaigns: type: array items: $ref: "#/components/schemas/GetAffiliatePartnerCampaignListResponseDataCampaign" description: A list of campaigns. next_page_token: type: string description: An opaque token used to retrieve the next page of a paginated result set. For the first request, omit `page_token` or pass an empty value. For each subsequent request, pass the previous response's non-empty `next_page_token` as `page_token`, and keep the same `category_asset_cipher`, `page_size`, `status`, `type`, and `query_type_filter` values, including whether each optional parameter was omitted or provided. If `next_page_token` is empty, no more pages are available. total_count: type: integer format: int64 description: The total number of campaigns in the list. GetAffiliatePartnerCampaignListResponseDataCampaign: type: object properties: id: type: string description: The campaign identifier. name: type: string description: The campaign name. status: type: string description: |- The campaign status. The status is an enumerated type with values: - READY - UPCOMING - ONGOING - CLOSED registration_start_time: type: integer format: int64 description: The scheduled start time in Unix epoch format for seller product registration. Note that this field can be updated when the campaign status is set to `READY` or `UPCOMING` only. registration_end_time: type: integer format: int64 description: The scheduled end time in Unix epoch time format for seller product registration. This field is no longer editable when the campaign status is set to `CLOSED`. campaign_start_time: type: integer format: int64 description: The scheduled start time in Unix epoch time format for the campaign. Note that this field can be updated when the campaign status is set to `READY` or `UPCOMING` only. campaign_end_time: type: integer format: int64 description: The scheduled end time in Unix epoch time format for the campaign. Note that the end time must be less than 360 days from the start date. This field is no longer editable when the campaign status is set to `CLOSED`. GetAffiliatePartnerCampaignProductListResponse: 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/GetAffiliatePartnerCampaignProductListResponseData" GetAffiliatePartnerCampaignProductListResponseData: type: object properties: products: type: array items: $ref: "#/components/schemas/GetAffiliatePartnerCampaignProductListResponseDataProduct" description: The list of products. next_page_token: type: string description: An opaque token used to retrieve the next page of a paginated result set. When this value is non-empty, pass it as `page_token` in the next request and reuse the same `campaign_id`, `category_asset_cipher`, `page_size`, `review_status`, `product_name`, `product_id`, `shop_name`, and `category_id` values, including any omitted optional filters. An empty `next_page_token` means there are no more pages. total_count: type: integer format: int64 description: The total number of products in the list. GetAffiliatePartnerCampaignProductListResponseDataProduct: type: object properties: id: type: string description: The product identifier. review_status: type: string description: |- The product review status. This an enumerated type with values: - PENDING - APPROVED - REJECTED - PENDING_CLOSED - CLOSED name: type: string description: The product name. main_image_url: type: string description: The product image URL. lowest_price: $ref: "#/components/schemas/GetAffiliatePartnerCampaignProductListResponseDataProductLowestPrice" description: The lowest original price of all SKUs of this product. highest_price: $ref: "#/components/schemas/GetAffiliatePartnerCampaignProductListResponseDataProductHighestPrice" description: The highest original price of all SKUs of this product. inventory: type: integer format: int64 description: The number of in-stock units of all SKUs for this product. shop_name: type: string description: The TikTok Shop name. total_commission_rate: type: integer format: int64 description: The total commission rate in hundredths of a percent (0.01%) units. creator_commission_rate: type: integer format: int64 description: The creator commission rate in hundredths of a percent (0.01%) units. partner_commission_rate: type: integer format: int64 description: The partner commission rate in hundredths of a percent (0.01%) units. open_collaboration_commission_rate: type: integer format: int64 description: The product open collaboration commission rate in hundredths of a percent (0.01%) units. is_available: type: boolean description: Set to `true` if a product URL is available. Set to `false` if no product URL is available. product_sales: type: integer format: int64 description: The total number of units sold of this product for this campaign. category: $ref: "#/components/schemas/GetAffiliatePartnerCampaignProductListResponseDataProductCategory" description: The leaf category to which this product is associated. sample_quota: type: integer format: int64 description: The total amount of sample inventory available for allocation to creators by the seller. sku_information_list: type: array items: $ref: "#/components/schemas/GetAffiliatePartnerCampaignProductListResponseDataProductSkuInformationList" description: A list of Stock Keeping Units (SKUs) used to identify distinct variants of the product. product_description: type: string description: Return product description GetAffiliatePartnerCampaignProductListResponseDataProductCategory: type: object properties: id: type: string description: The category identifier. name: type: string description: The category name. GetAffiliatePartnerCampaignProductListResponseDataProductHighestPrice: type: object properties: currency: type: string description: The currency code for the region in which the product is sold. amount: type: string description: The highest price amount. GetAffiliatePartnerCampaignProductListResponseDataProductLowestPrice: type: object properties: currency: type: string description: The currency in the sales region. amount: type: string description: The lowest price amount. GetAffiliatePartnerCampaignProductListResponseDataProductSkuInformationList: type: object properties: sku_name: type: string description: The name of the sku sku_id: type: string description: The id of the sku inventory: $ref: "#/components/schemas/GetAffiliatePartnerCampaignProductListResponseDataProductSkuInformationListInventory" description: SKU inventory details. base_price: $ref: "#/components/schemas/GetAffiliatePartnerCampaignProductListResponseDataProductSkuInformationListBasePrice" description: the base price of the sku region_prices: type: array items: $ref: "#/components/schemas/GetAffiliatePartnerCampaignProductListResponseDataProductSkuInformationListRegionPrice" description: region prices properties: type: array items: $ref: "#/components/schemas/GetAffiliatePartnerCampaignProductListResponseDataProductSkuInformationListProperty" description: The properties of the sku GetAffiliatePartnerCampaignProductListResponseDataProductSkuInformationListBasePrice: type: object properties: region_code: type: string description: the region code of the sku currency: type: string enum: - BRL - EUR - GBP - IDR - JPY - MXN - MYR - PHP - SGD - THB - USD - VND x-enum-descriptions: - Brazil - France, Germany, Ireland, Italy, Spain - United Kingdom - Indonesia - Japan - Mexico - Malaysia - Philippines - Singapore - Thailand - United States - Vietnam description: |- The currency of the SKU price. Possible values based on the region: - BRL: Brazil - EUR: France, Germany, Ireland, Italy, Spain - GBP: United Kingdom - IDR: Indonesia - JPY: Japan - MXN: Mexico - MYR: Malaysia - PHP: Philippines - SGD: Singapore - THB: Thailand - USD: United States - VND: Vietnam list_price: type: string description: The SKU's list price information that has been verified to be legitimate by the audit team. This is equivalent to the manufacturer's suggested retail price (MSRP), or the recommended retail price (RRP). sale_price: type: string description: |- The SKU's selling price, inclusive of tax. Applicable only for cross-border sellers from China. localized_dutiable_price: type: string description: localized dutiable price GetAffiliatePartnerCampaignProductListResponseDataProductSkuInformationListInventory: type: object properties: available_quantity: type: string description: The total SKU quantity available in the warehouse. GetAffiliatePartnerCampaignProductListResponseDataProductSkuInformationListProperty: type: object properties: name: type: string description: the name of the property value_name: type: string description: the name of the value GetAffiliatePartnerCampaignProductListResponseDataProductSkuInformationListRegionPrice: type: object properties: region_code: type: string description: the region code of the sku currency: type: string enum: - BRL - EUR - GBP - IDR - JPY - MXN - MYR - PHP - SGD - THB - USD - VND x-enum-descriptions: - Brazil - France, Germany, Ireland, Italy, Spain - United Kingdom - Indonesia - Japan - Mexico - Malaysia - Philippines - Singapore - Thailand - United States - Vietnam description: |- The currency of the SKU price. Possible values based on the region: - BRL: Brazil - EUR: France, Germany, Ireland, Italy, Spain - GBP: United Kingdom - IDR: Indonesia - JPY: Japan - MXN: Mexico - MYR: Malaysia - PHP: Philippines - SGD: Singapore - THB: Thailand - USD: United States - VND: Vietnam list_price: type: string description: The SKU's list price information that has been verified to be legitimate by the audit team. This is equivalent to the manufacturer's suggested retail price (MSRP), or the recommended retail price (RRP). sale_price: type: string description: |- The SKU's selling price, inclusive of tax. Applicable only for cross-border sellers from China. localized_dutiable_price: type: string description: localized dutiable price GetAftersaleEligibilityResponse: 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/GetAftersaleEligibilityResponseData" GetAftersaleEligibilityResponseData: type: object properties: sku_eligibility: type: array items: $ref: "#/components/schemas/GetAftersaleEligibilityResponseDataSkuEligibility" description: The eligible aftersale options for a given SKU. GetAftersaleEligibilityResponseDataSkuEligibility: type: object properties: sku_id: type: string description: SKU ID. line_item_eligibility: type: array items: $ref: "#/components/schemas/GetAftersaleEligibilityResponseDataSkuEligibilityLineItemEligibility" description: Eligibility results for order line items in this SKU, grouped by aftersale request type. A request type can include separate entries for eligible and ineligible order line items. Eligible entries can include available_reason_names, while ineligible entries include ineligible_code and ineligible_reason. GetAftersaleEligibilityResponseDataSkuEligibilityLineItemEligibility: type: object properties: request_type: type: string enum: - CANCEL - REFUND - RETURN_AND_REFUND description: |- Aftersale request type. Possible values: - `CANCEL` - `REFUND` - `RETURN_AND_REFUND` order_line_items_ids: type: array items: type: string description: Specifies the order line IDs. **Note:** This is a legacy field for new integrations use `order_line_list` instead. eligible: type: boolean description: |- Indicates whether the order lines in this entry are eligible for the entry's aftersale request type: - `true`: The order lines are eligible for the request type. - `false`: The order lines are ineligible for the request type. ineligible_code: type: integer format: int64 description: The reason code for an ineligible aftersale request. ineligible_reason: type: string description: The reason for an ineligible aftersale request. available_reason_names: type: array items: type: string description: A list of reason names that can be used when creating a follow-up aftersale request. order_line_list: type: array items: $ref: "#/components/schemas/OrderLineList" description: Specifies the order line items. **Note:** This field is completely backward compatible with the previous `order_line_items_ids` field. GetAgentSettingsResponse: 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/GetAgentSettingsResponseData" GetAgentSettingsResponseData: type: object properties: can_accept_chat: type: boolean description: |- Whether the current agent can accept chat. If true, the agent will receive auto-assigned chats. The agent can manually select chats to respond. If false, the agent will receive manually assigned chats only. GetAuthorizedCategoryAssetsResponse: 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/GetAuthorizedCategoryAssetsResponseData" GetAuthorizedCategoryAssetsResponseData: type: object properties: category_assets: type: array items: $ref: "#/components/schemas/GetAuthorizedCategoryAssetsResponseDataCategoryAsset" description: The list of business category assets that a partner has authorized for the app. GetAuthorizedCategoryAssetsResponseDataCategoryAsset: type: object properties: cipher: type: string description: The encrypted category asset cipher for this authorized business category and target market. Use it as an input parameter in affiliate partner related APIs; you do not need to decrypt it. target_market: type: string description: The target market associated with this authorized business category and its category asset cipher. category: $ref: "#/components/schemas/GetAuthorizedCategoryAssetsResponseDataCategoryAssetCategory" description: The business category information. GetAuthorizedCategoryAssetsResponseDataCategoryAssetCategory: type: object properties: id: type: integer format: int64 description: The ID of the business category. Use this field to verify if the partner has authorized the correct category. Otherwise, request re-authorization from the partner by referring to the [Partner authorization guide](https://partner.tiktokshop.com/docv2/page/669a301bd92cd602fd403ff9). name: type: string description: The name of the business category. This name may change. GetAuthorizedShopsResponse: 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/GetAuthorizedShopsResponseData" GetAuthorizedShopsResponseData: type: object properties: shops: type: array items: $ref: "#/components/schemas/GetAuthorizedShopsResponseDataShop" description: The list of shops that a seller has authorized for the app. GetAuthorizedShopsResponseDataShop: type: object properties: id: type: string description: An internal identifier for the TikTok Shop. name: type: string description: The TikTok Shop name. region: type: string description: The region of the shop. seller_type: type: string enum: - CROSS_BORDER - LOCAL x-enum-descriptions: - Cross border sellers with multiple shops in different countries. - Local sellers with only 1 shop. description: |- The type of seller. Possible values: - CROSS_BORDER: Cross border sellers with multiple shops in different countries. - LOCAL: Local sellers with only 1 shop. cipher: type: string description: An encrypted token used to securely identify a shop in API requests. There is no need for decryption on the receiving end. code: type: string description: The TikTok Shop code, which is also displayed on Seller Center. GetAvailableReviewDecisionsResponse: 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/GetAvailableReviewDecisionsResponseData" GetAvailableReviewDecisionsResponseData: type: object properties: line_items: type: array items: $ref: "#/components/schemas/GetAvailableReviewDecisionsResponseDataLineItem" description: Line items to which the returned decisions apply. Decision details apply to each line item individually. For example, a partial refund amount of 1.00 for each of three line items results in a total of 3.00; use the `currency` returned with the amount range rather than assuming a currency. request_log_id: type: string description: The log id of this request, used for troubleshooting with TikTok Shop support. errors: type: array items: $ref: "#/components/schemas/GetAvailableReviewDecisionsResponseDataError" description: |- Lists errors for partially failed requests. For example, if a request reviews multiple orders or items and only some fail, individual error details are returned here. **IMPORTANT**: Partial failures still return a top-level success code (0), so clients must also check this field to detect partial errors. For complete failures (e.g. validation errors), the top-level response code and message will indicate a failure, but this field will remain empty. GetAvailableReviewDecisionsResponseDataError: type: object properties: code: type: string description: Error Code message: type: string description: Error Description GetAvailableReviewDecisionsResponseDataLineItem: type: object properties: return_line_item_id: type: string description: Unique identifier for this item in the return. In the case of virtual bundle, this corresponds to the id of the original parent item bundle. sub_return_line_item_id: type: string description: Unique identifier for this item in the return. In the case of virtual bundle, this corresponds to the id of the current child item being returned. decisions: type: array items: $ref: "#/components/schemas/GetAvailableReviewDecisionsResponseDataLineItemDecision" description: The list of candidate review decisions for this line item. GetAvailableReviewDecisionsResponseDataLineItemDecision: type: object properties: decision: 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 description: |- Seller review decision evaluated for this line item. Possible values: - `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` eligible: type: boolean description: Whether this decision is currently eligible for the line item. When `false`, `ineligible_code` and `ineligible_reason` explain why the decision is ineligible; these fields are omitted when `true`. ineligible_code: type: integer format: int64 description: The reason code for an ineligible decision. ineligible_reason: type: string description: The reason for an ineligible decision. available_reject_reasons: type: array items: $ref: "#/components/schemas/AvailableRejectReason" description: Rejection reasons, if available, for this eligible decision. Each item contains a machine-readable name and display text. partial_refund_amount_range: $ref: "#/components/schemas/GetAvailableReviewDecisionsResponseDataLineItemDecisionPartialRefundAmountRange" description: The allowed partial refund amount band. Returned for the `OFFER_PARTIAL_REFUND_AFTER_RECEIVING_PKG` decision when it is eligible; omitted for all other decisions. GetAvailableReviewDecisionsResponseDataLineItemDecisionPartialRefundAmountRange: type: object properties: min_amount: type: string description: The minimum partial refund amount the seller may offer. max_amount: type: string description: The maximum partial refund amount the seller may offer. currency: type: string description: The currency of the partial refund amount range, matching the currency of the current return request. GetBestsellingCreatorsResponse: 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/GetBestsellingCreatorsResponseData" GetBestsellingCreatorsResponseData: type: object properties: creators: type: array items: $ref: "#/components/schemas/GetBestsellingCreatorsResponseDataCreator" description: List of bestselling creator records for the target date range. GetBestsellingCreatorsResponseDataCreator: type: object properties: rank: type: integer format: int64 description: GMV rank of the creator. gmv_range: type: string description: The creator's GMV range for the selected reporting period, expressed in the currency selected by `currency`. open_id: type: string description: Creator's open id, use this open id to identify a creator. user_name: type: string description: The creator's account handle. nick_name: type: string description: The creator's display name. followers_count: type: integer format: int64 description: Number of followers likes_count: type: integer format: int64 description: Number of likes GetBestsellingLIVESessionsResponse: 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/GetBestsellingLIVESessionsResponseData" GetBestsellingLIVESessionsResponseData: type: object properties: lives: type: array items: $ref: "#/components/schemas/GetBestsellingLIVESessionsResponseDataLive" description: List of bestselling LIVE session records for the target date range. GetBestsellingLIVESessionsResponseDataLive: type: object properties: rank: type: integer format: int64 description: GMV rank of the LIVE session gmv_range: type: string description: GMV range of the LIVE session. id: type: string description: LIVE session id title: type: string description: LIVE session title start_time: type: integer format: int64 description: Start time of the LIVE session as a Unix timestamp in seconds (UTC+00:00). duration: type: integer format: int64 description: LIVE session duration, in seconds. creator_name: type: string description: The creator’s unique username used for system identification. open_id: type: string description: The creator’s unique ID, uniquely identifying the creator in the system. creator_nick_name: type: string description: The creator’s display nickname, visible externally. GetBestsellingProductsResponse: 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/GetBestsellingProductsResponseData" GetBestsellingProductsResponseData: type: object properties: products: type: array items: $ref: "#/components/schemas/GetBestsellingProductsResponseDataProduct" description: List of bestselling product records for the target date range. GetBestsellingProductsResponseDataProduct: type: object properties: rank: type: integer format: int64 description: GMV rank of the product. gmv_range: type: string description: GMV range of the product, in the currency specified by currency. id: type: string description: Product ID name: type: string description: Product name rating: type: string description: Product rating in history product_image: $ref: "#/components/schemas/GetBestsellingProductsResponseDataProductProductImage" description: Product image information, including URI, URLs, thumbnail URLs, height, and width. shop_name: type: string description: The TikTok Shop name. shop_id: type: string description: The ID of the TikTok Shop associated with the product. GetBestsellingProductsResponseDataProductProductImage: type: object properties: height: type: integer format: int64 description: |- The image height. Unit: px width: type: integer format: int64 description: |- The image width. Unit: px thumb_urls: type: array items: type: string description: The URLs to view the image thumbnails. uri: type: string description: The URI of the image. urls: type: array items: type: string description: The URLs to view the images. GetBestsellingVideosResponse: 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/GetBestsellingVideosResponseData" GetBestsellingVideosResponseData: type: object properties: videos: type: array items: $ref: "#/components/schemas/GetBestsellingVideosResponseDataVideo" description: List of bestselling video records for the target date range. GetBestsellingVideosResponseDataVideo: type: object properties: rank: type: integer format: int64 description: Gmv rank of the video id: type: string description: Video id nick_name: type: string description: Creator handle gmv_range: type: string description: Gmv range of the video views: type: integer format: int64 description: Accumulative number of video views since the video was published. likes: type: integer format: int64 description: Accumulative number of video likes since the video was published. comments: type: integer format: int64 description: Accumulative number of video comments since the video was published. shares: type: integer format: int64 description: Accumulative number of video shares since the video was published. product_infos: type: array items: $ref: "#/components/schemas/GetBestsellingVideosResponseDataVideoProductInfo" description: List of product anchors associated with the video, including product IDs and product names. Excludes deactivated and sold-out products. publish_time: type: integer format: int64 description: The time when the video was published, as a Unix timestamp in seconds (UTC). duration: type: integer format: int64 description: Duration of the video, in seconds. GetBestsellingVideosResponseDataVideoProductInfo: type: object properties: product_id: type: string description: Product ID in the product anchor. Excludes deactivated and sold-out products. product_name: type: string description: Product name in the product anchor. Deactivated and sold-out products are excluded. GetBrandsResponse: 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/GetBrandsResponseData" GetBrandsResponseData: type: object properties: brands: type: array items: $ref: "#/components/schemas/GetBrandsResponseDataBrand" description: The list of brands that meet the query conditions. total_count: type: integer format: int64 description: The total count of brands that meet the query conditions. next_page_token: type: string description: An opaque token used to retrieve the next page of a paginated result set. If this value is non-empty, pass it in the `page_token` parameter of the next request. An empty value means there are no more results. GetBrandsResponseDataBrand: type: object properties: id: type: string description: The brand ID. name: type: string description: The brand name. authorized_status: type: string enum: - UNAUTHORIEZD - AUTHORIZED description: |- A status to indicate whether the seller has obtained prior authorization to sell goods bearing the brand's trademark, name, or logo. Possible values: - UNAUTHORIEZD - AUTHORIZED **Note**: If the brand is unauthorized, check `is_t1_brand` to determine if you can use it during product creation. is_t1_brand: type: boolean description: |- A flag to indicate whether the brand is a T1 brand, which refers to internationally renowned brands that may have compliance risks and require sellers to obtain brand authorization. **Note**: - You cannot create products with unauthorized T1 brands. - You can create products with unauthorized non-T1 brands, **but** the brand information will not appear on the product display page. You can obtain authorization by submitting the required qualifications through TikTok Shop Seller Center > Qualification Center > Brand qualification. brand_status: type: string enum: - AVAILABLE - UNAVAILABLE description: |- The availability of an **authorized brand** in the requested category. Possible values: - AVAILABLE - UNAVAILABLE **Note**: Not applicable if you did not specify the category ID, or the brand is unauthorized. GetCampaignProductPerformanceListResponse: 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/GetCampaignProductPerformanceListResponseData" GetCampaignProductPerformanceListResponseData: type: object properties: total_count: type: integer format: int64 description: The total count of products included in the specified campaign. campaign_product_statistics: type: array items: $ref: "#/components/schemas/GetCampaignProductPerformanceListResponseDataCampaignProductStatistic" description: A list of objects representing campaign product statistics. next_page_token: type: string description: The token to use as `page_token` in the next request. Keep the same `campaign_id` and `page_size` on subsequent requests. An empty string indicates that there are no more results. GetCampaignProductPerformanceListResponseDataCampaignProductStatistic: type: object properties: data_update_time: type: string description: The time at which the product data was last updated, in Unix epoch format. creator_sales_num: type: integer format: int64 description: The number of creators credited with at least one product sale. collaborated_creators_num: type: integer format: int64 description: The total number of creators associated with the campaign. promoted_creator_num: type: integer format: int64 description: The number of the creators involved in the campaign. sample_requested_creator_num: type: integer format: int64 description: The total number of samples requested by all creators associated with the campaign. campaign_product_detail: $ref: "#/components/schemas/GetCampaignProductPerformanceListResponseDataCampaignProductStatisticCampaignProductDetail" description: An object representing the details for the product associated with the campaign. GetCampaignProductPerformanceListResponseDataCampaignProductStatisticCampaignProductDetail: type: object properties: product_id: type: string description: The product identifier. product_status: type: string description: |- The product status. This is an enumerated type with values: - PRODUCT_UNSPECIFIED - PRODUCT_PENDING - PRODUCT_APPROVED - PRODUCT_REJECTED - PRODUCT_PENDING_CLOSED - PRODUCT_CLOSED product_name: type: string description: The product name. product_stock_count: type: string description: The product's total available stock quantity across all SKUs. total_commission_percent: type: string description: The total commission rate for the partner plan. It is the sum of `creator_commission_percent` and `partner_commission_percent`. The value is in hundredths of a percent. For example, a value of 1000 means 10.00%. creator_commission_percent: type: string description: The commission rate for the creator in the partner plan. The value is in hundredths of a percent. For example, a value of 1000 means 10.00%. partner_commission_percent: type: string description: The commission rate for the partner in the partner plan. The value is in hundredths of a percent. For example, a value of 1000 means 10.00%. plan_commission_percent: type: string description: The commission rate for open collaboration. The value is in hundredths of a percent. For example, a value of 1000 means 10.00%. product_price: $ref: "#/components/schemas/GetCampaignProductPerformanceListResponseDataCampaignProductStatisticCampaignProductDetailProductPrice" description: The product price. product_thumbnail: $ref: "#/components/schemas/GetCampaignProductPerformanceListResponseDataCampaignProductStatisticCampaignProductDetailProductThumbnail" description: An object representing the product thumbnail. indicator_data: $ref: "#/components/schemas/GetCampaignProductPerformanceListResponseDataCampaignProductStatisticCampaignProductDetailIndicatorData" description: Key performance indicators for the product. GetCampaignProductPerformanceListResponseDataCampaignProductStatisticCampaignProductDetailIndicatorData: type: object properties: paid_order_num: type: string description: The total number of paid orders. `paid_order_num` = `actual_order_num` + {number of paid but returned orders} actual_order_num: type: string description: The actual number of paid orders. estimated_amount: type: string description: The total payment amount corresponding to `paid_order_num`. actual_amount: type: string description: GMV, the total payment amount corresponding to `actual_order_num`. estimated_partner_commission: type: string description: The partner commission amount corresponding to paid_order_num. actual_partner_commission: type: string description: The partner commission amount corresponding to actual_order_num. creator_sales_num: type: string description: The number of creators credited with at least one product sale. collaborated_creators_num: type: string description: The total number of creators collaborating on the campaign. promoted_creator_num: type: string description: The number of creators involved in the partner plan. sample_requested_creator_num: type: string description: The total number of creators that applied for a sample. GetCampaignProductPerformanceListResponseDataCampaignProductStatisticCampaignProductDetailProductPrice: type: object properties: min_price: type: string description: The minimum offered price of the product. max_price: type: string description: The maximum offered price of the product. currency: type: string description: The currency code for the maximum and minimum offered price for the product. GetCampaignProductPerformanceListResponseDataCampaignProductStatisticCampaignProductDetailProductThumbnail: type: object properties: uri: type: string description: The URI of the product thumbnail image. url_list: type: array items: type: string description: A list of URLs for the product thumbnail image. GetCategoriesResponse: 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/GetCategoriesResponseData" GetCategoriesResponseData: type: object properties: categories: type: array items: $ref: "#/components/schemas/GetCategoriesResponseDataCategory" description: The list of categories that meet the query conditions. GetCategoriesResponseDataCategory: type: object properties: id: type: string description: The category ID. parent_id: type: string description: |- The parent category ID. For the root category, the parent ID is `0`. local_name: type: string description: The category name in the requested locale. If `locale` is omitted, the default locale of your shop is used. is_leaf: type: boolean description: |- A flag to indicate if the category is a leaf category. **Note**: You can only create or edit products that belong to a leaf category. permission_statuses: type: array items: type: string enum: - AVAILABLE - INVITE_ONLY - NON_MAIN_CATEGORY - PROHIBITED x-enum-descriptions: - None of the category-permission restrictions listed below applies to this category. To create or edit a product in the category, `is_leaf` must be `true`. - This is a restricted category and you do not have permission to use it. Submit an application through the Qualification Center on TikTok Shop Seller Center to gain access. In Seller Center, `INVITE_ONLY` is also known as "restricted". - This category is out of scope for this shop, and you do not have permission to use it. Contact your account manager for assistance. - This category is prohibited on TikTok Shop. Do not attempt to list products in this category as they will be rejected during audit. Applicable only for BR, MX, EU and SEA markets. description: |- The shop's permission statuses for this category. Possible values: - `AVAILABLE`: None of the category-permission restrictions listed below applies to this category. To create or edit a product in the category, `is_leaf` must be `true`. - `INVITE_ONLY`: This is a restricted category and you do not have permission to use it. Submit an application through the Qualification Center on TikTok Shop Seller Center to gain access. In Seller Center, `INVITE_ONLY` is also known as "restricted". - `NON_MAIN_CATEGORY`: This category is out of scope for this shop, and you do not have permission to use it. Contact your account manager for assistance. - `PROHIBITED`: This category is prohibited on TikTok Shop. Do not attempt to list products in this category as they will be rejected during audit. Applicable only for BR, MX, EU and SEA markets. GetCategoryAttributesResponse: 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/GetCategoryAttributesResponseData" GetCategoryAttributesResponseData: type: object properties: attributes: type: array items: $ref: "#/components/schemas/GetCategoryAttributesResponseDataAttribute" description: The list of standard built-in product and sales attributes that are bound to the specified category, based on your shop's location. GetCategoryAttributesResponseDataAttribute: type: object properties: id: type: string description: The ID of the built-in attribute. name: type: string description: The name of the built-in attribute. type: type: string enum: - SALES_PROPERTY - PRODUCT_PROPERTY x-enum-descriptions: - Indicates sales attributes that define product variants. - Indicates product attributes that describe the product as a whole. description: |- The attribute type. Possible values: - SALES_PROPERTY: Indicates sales attributes that define product variants. - PRODUCT_PROPERTY: Indicates product attributes that describe the product as a whole. is_requried: type: boolean description: |- A flag to indicate if the product attribute is always required when creating or editing a product. - true: The attribute is always required. - false: The attribute is not required, or required only if certain conditions are met. Refer to `requirement_conditions` for the specific requirements. Applicable only if `type=PRODUCT_PROPERTY`. values: type: array items: $ref: "#/components/schemas/GetCategoryAttributesResponseDataAttributeValue" description: A list of selectable values for the attribute. value_data_format: type: string enum: - POSITIVE_INT_OR_DECIMAL x-enum-descriptions: - Positive integers or decimal numbers. description: |- The data format for a free-form attribute value. Returned for customizable numeric attributes. Possible values: - POSITIVE_INT_OR_DECIMAL: Positive integers or decimal numbers. is_customizable: type: boolean description: A flag indicating whether sellers can enter a custom value for the attribute when creating or editing a product. requirement_conditions: type: array items: $ref: "#/components/schemas/RequirementCondition" description: |- A list of conditions that determine if the product attribute is required based on the seller's inputs for other attributes. If any of the conditions is met, the attribute is required; otherwise, it is optional. For example, there's a condition that states that the "Battery type" attribute is required if the seller selects the value "Batteries" for the attribute "Contains Batteries or Cells?". For more scenario-based guidance on using this parameter, refer to the [Solution Guide - CAT-PRE-HAZMAT](https://partner.tiktokshop.com/openlearn/guide/usecase?parent_id=7256668359046153985). Applicable only if `type=PRODUCT_PROPERTY` and `is_requried=false`. is_multiple_selection: type: boolean description: A flag indicating whether sellers can select multiple values for the attribute when creating or editing a product. metric_standards: type: array items: $ref: "#/components/schemas/GetCategoryAttributesResponseDataAttributeMetricStandard" description: Defines the measurement template information used to describe the measurement standards and metric values configured for the product. GetCategoryAttributesResponseDataAttributeMetricStandard: type: object properties: id: type: string description: The unique ID of the measurement template. Use this ID to identify which measurement standard template applies to the product. name: type: string description: The name of the measurement template. metric_value_modules: type: array items: $ref: "#/components/schemas/GetCategoryAttributesResponseDataAttributeMetricStandardMetricValueModule" description: Metric value modules. GetCategoryAttributesResponseDataAttributeMetricStandardMetricValueModule: type: object properties: id: type: string description: The unique ID of a metric item within the measurement template. This ID identifies which metric the submitted value belongs to. name: type: string description: The seller-provided value for the specified metric item in the measurement template. input_type: type: string description: Metric value modules input type. data_types: type: array items: type: string description: Metric value modules data type. default_values: type: array items: $ref: "#/components/schemas/GetCategoryAttributesResponseDataAttributeMetricStandardMetricValueModuleDefaultValue" description: Metric value modules default values. units: type: array items: $ref: "#/components/schemas/GetCategoryAttributesResponseDataAttributeMetricStandardMetricValueModuleUnit" description: Metric value modules units. value_limit: $ref: "#/components/schemas/GetCategoryAttributesResponseDataAttributeMetricStandardMetricValueModuleValueLimit" description: Metric value value limit. prefix: type: string description: Metric value prefix. suffix: type: string description: Metric value suffix. shading_word: type: string description: Metric value shading word. GetCategoryAttributesResponseDataAttributeMetricStandardMetricValueModuleDefaultValue: type: object properties: id: type: string description: Metric value modules default value id. name: type: string description: Metric value modules default value name. GetCategoryAttributesResponseDataAttributeMetricStandardMetricValueModuleUnit: type: object properties: id: type: string description: Unit id. name: type: string description: Unit name. GetCategoryAttributesResponseDataAttributeMetricStandardMetricValueModuleValueLimit: type: object properties: num_limit: $ref: "#/components/schemas/GetCategoryAttributesResponseDataAttributeMetricStandardMetricValueModuleValueLimitNumLimit" description: Metric value num limit. length_limit: $ref: "#/components/schemas/GetCategoryAttributesResponseDataAttributeMetricStandardMetricValueModuleValueLimitLengthLimit" description: Metric value length limit. GetCategoryAttributesResponseDataAttributeMetricStandardMetricValueModuleValueLimitLengthLimit: type: object properties: min_length: type: integer format: int64 description: Metric value min length. max_length: type: integer format: int64 description: Metric value max length. GetCategoryAttributesResponseDataAttributeMetricStandardMetricValueModuleValueLimitNumLimit: type: object properties: min_value: type: integer format: int64 description: Metric value num limit min value. max_value: type: integer format: int64 description: Metric value num limit max value. GetCategoryAttributesResponseDataAttributeValue: type: object properties: id: type: string description: The ID of the built-in attribute value. name: type: string description: The name of the built-in attribute value. icon_url: type: string description: The icon url value of the built-in attribute value. GetCategoryRulesResponse: 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/GetCategoryRulesResponseData" GetCategoryRulesResponseData: type: object properties: product_certifications: type: array items: $ref: "#/components/schemas/GetCategoryRulesResponseDataProductCertification" description: |- Certification related rules. As per TikTok Shop guidelines, certifications are required for certain restricted product categories. Refer to [TikTok Shop Restricted Products Policy](https://seller-us.tiktok.com/university/essay?identity=1&role=1&knowledge_id=3238037484275457&from=policy) for information on product category restrictions. If this is empty, it means certifications are not required for this category. size_chart: $ref: "#/components/schemas/GetCategoryRulesResponseDataSizeChart" description: Size chart related rules. cod: $ref: "#/components/schemas/GetCategoryRulesResponseDataCod" description: |- Cash on Delivery (COD) related rules. Applicable only for the following markets: - Global sellers: MY, PH, SA, TH, VN - Local sellers: ID, MY, PH, SA, TH, VN package_dimension: $ref: "#/components/schemas/GetCategoryRulesResponseDataPackageDimension" description: Package dimension related rules. epr: $ref: "#/components/schemas/GetCategoryRulesResponseDataEpr" description: Extended Producer Responsibility (EPR) related rules. responsible_person: $ref: "#/components/schemas/GetCategoryRulesResponseDataResponsiblePerson" description: Responsible person (RP) related rules. Applicable only for the EU market. manufacturer: $ref: "#/components/schemas/GetCategoryRulesResponseDataManufacturer" description: Manufacturer related rules. Applicable only for the EU market. allowed_special_product_types: type: array items: type: string enum: - PRE_ORDER - MADE_TO_ORDER - CUSTOM x-enum-descriptions: - The product is not yet available or released. Fulfillment can be extended by specifying a release date. - The product is produced only after the order is received. Fulfillment can be extended by specifying a duration. - The product requires a fulfillment timeline that exceeds the standard due to other factors. Fulfillment can be extended by specifying a duration. description: |- The list of special product types, excluding regular products, that your shop is allowed to list in this category. Possible values based on the region: **US** - `PRE_ORDER`: The product is not yet available or released. Fulfillment can be extended by specifying a release date. - `MADE_TO_ORDER`: The product is produced only after the order is received. Fulfillment can be extended by specifying a duration. - `CUSTOM`: The product requires a fulfillment timeline that exceeds the standard due to other factors. Fulfillment can be extended by specifying a duration. **UK and SEA** - `PRE_ORDER`: The product is not yet available or released. Fulfillment can be extended by specifying a duration. **Note**: This field is omitted if you lack the permission to list special product types. Contact your account manager for assistance if you wish to list such products. fees: type: array items: $ref: "#/components/schemas/GetCategoryRulesResponseDataFee" description: Product fees related rules. seller_sku: $ref: "#/components/schemas/GetCategoryRulesResponseDataSellerSku" description: Seller SKU related rules. Applicable only for cross-border POP shops in EU markets. GetCategoryRulesResponseDataCod: type: object properties: is_supported: type: boolean description: |- A flag to indicate whether COD is supported. **Note**: If COD is not supported, but you set `is_cod_allowed=true` when creating or editing a product, the listing will fail. GetCategoryRulesResponseDataEpr: type: object properties: is_required: type: boolean description: A flag to indicate whether EPR is required. GetCategoryRulesResponseDataFee: type: object properties: type: type: string enum: - PFAND description: |- The type of fee. Possible values: PFAND is_required: type: boolean description: A flag to indicate whether information about the fee is required. GetCategoryRulesResponseDataManufacturer: type: object properties: is_required: type: boolean description: A flag to indicate whether the manufacturer information is required. GetCategoryRulesResponseDataPackageDimension: type: object properties: is_required: type: boolean description: A flag to indicate whether package dimensions are required. GetCategoryRulesResponseDataProductCertification: type: object properties: id: type: string description: The ID to identify the type of certification required. name: type: string description: The name of the certification type. is_required: type: boolean description: |- A flag to indicate if the certification is always required when creating or editing a product. - true: The certification is always required. - false: The certification is not required, or required only if certain conditions are met. Refer to `requirement_conditions` for the specific requirements. document_details: type: string description: Details about the certification documents that you must submit, including the content, format, and any other guidelines. sample_image_url: type: string description: The URL to view an image of the sample certification document. requirement_conditions: type: array items: $ref: "#/components/schemas/RequirementCondition" description: |- A list of conditions that determine if the certification is required based on the seller's inputs for a product attribute. If any of the conditions is met, the certification is required; otherwise, it is optional. For example, there's a condition that states that the "Safety Data Sheet (SDS) for flammable materials" certification is required if the seller selects the value "Yes" for the attribute "Flammable Liquid?". For more scenario-based guidance on using this parameter, refer to the [Solution Guide - CAT-PRE-HAZMAT](https://partner.tiktokshop.com/openlearn/guide/usecase?parent_id=7256668359046153985). Applicable only if `is_required=false`. expiration_date: $ref: "#/components/schemas/GetCategoryRulesResponseDataProductCertificationExpirationDate" description: Certification expiration date related rules. GetCategoryRulesResponseDataProductCertificationExpirationDate: type: object properties: is_required: type: boolean description: A flag to indicate whether an expiration date is required for this certification. GetCategoryRulesResponseDataResponsiblePerson: type: object properties: is_required: type: boolean description: A flag to indicate whether the responsible person information is required. GetCategoryRulesResponseDataSellerSku: type: object properties: is_required: type: boolean description: A flag to indicate whether a Seller SKU is required when creating or editing a product in this category. When required, the Seller SKU must be 6 to 50 characters long and can contain only letters, digits, hyphens (-) and underscores (_). GetCategoryRulesResponseDataSizeChart: type: object properties: is_supported: type: boolean description: |- A flag to indicate whether size charts are supported. **Note**: If size charts are not supported, even if you provide a size chart when creating or editing a product, the size chart will not be saved. is_required: type: boolean description: A flag to indicate whether a size chart is required. measurement_and_options: type: array items: $ref: "#/components/schemas/GetCategoryRulesResponseDataSizeChartMeasurementAndOption" description: Measurement rules grouped by measurement basis. size_types: type: array items: type: string description: "Available size types configured for this category. Use values returned in this list for size_chart_data.size_types when creating or editing a size chart. Possible values include: size_chart_common_size_type: Common; size_chart_size_type_regular: Regular; size_chart_size_type_juniors: Juniors; size_chart_size_type_plus: Plus; size_chart_size_type_big&tall: Big & Tall; size_chart_size_type_petite: Petite. This field is omitted when size types do not apply to the category." GetCategoryRulesResponseDataSizeChartMeasurementAndOption: type: object properties: measurement_type: type: string enum: - GENERIC_MEASUREMENTS - BODY_MEASUREMENTS - PRODUCT_MEASUREMENTS x-enum-descriptions: - generic measurements for categories that do not distinguish body and product measurements - shopper body measurements - finished-product or garment measurements. description: "Possible values: GENERIC_MEASUREMENTS: generic measurements for categories that do not distinguish body and product measurements; BODY_MEASUREMENTS: shopper body measurements; PRODUCT_MEASUREMENTS: finished-product or garment measurements." options: type: array items: $ref: "#/components/schemas/GetCategoryRulesResponseDataSizeChartMeasurementAndOptionOption" description: Online measurement options for this group. GetCategoryRulesResponseDataSizeChartMeasurementAndOptionOption: type: object properties: name: type: string description: Localized measurement name resolved using the request locale. id: type: string description: Platform-defined standard measurement ID, for example size_chart_option_bust. Use this ID as table.headers[].id for the corresponding standard measurement. role: type: string enum: - KEY - RECOMMEND x-enum-descriptions: - a key category measurement - a useful recommended measurement. description: "Possible values: KEY: a key category measurement; RECOMMEND: a useful recommended measurement." unit: type: string enum: - NONE - LENGTH - WEIGHT - HEIGHT x-enum-descriptions: - no unit conversion - length values such as cm or in - weight values such as kg or lb - person-height values such as cm or ft/in. description: "Possible values: NONE: no unit conversion; LENGTH: length values such as cm or in; WEIGHT: weight values such as kg or lb; HEIGHT: person-height values such as cm or ft/in." metric_value_range: type: array items: type: string description: Allowed metric range in [minimum, maximum] order. imperial_value_range: type: array items: type: string description: Allowed imperial range in [minimum, maximum] order. GetCompassTaskListResponse: 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/GetCompassTaskListResponseData" GetCompassTaskListResponseData: type: object properties: tasks: type: array items: $ref: "#/components/schemas/GetCompassTaskListResponseDataTask" description: The list of the task GetCompassTaskListResponseDataTask: type: object properties: module_type: type: string enum: - CREATOR - BASE description: "Allowed values: CREATOR, BASE." id: type: string description: The ID of the offline report task. When the task status is `SUCCEEDED`, use this value as the `task_id` path parameter in `GET /affiliate_seller/202603/compass/offline_tasks/{task_id}/file` to download the completed export task's result file. file_name: type: string description: the name of the final download file. status: type: string description: |- The status of the task. - RUNNING - SUCCEEDED - FAILED GetConversationListRequest: type: object properties: only_need_conversation_id: type: boolean description: |- - If `true`, only `conversation_id` in `data.conversation` is returned. - If `false`, all fields in `data.conversation` are returned. `true` by default. GetConversationListResponse: 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/GetConversationListResponseData" GetConversationListResponseData: type: object properties: has_more: type: boolean description: Whether there are more conversations. next_page_token: type: string description: Pagination cursor for the next page. When `has_more` is `true`, pass this value as `page_token` in the next request. conversations: type: array items: $ref: "#/components/schemas/GetConversationListResponseDataConversation" description: The conversation list. GetConversationListResponseDataConversation: type: object properties: id: type: string description: Conversation unique ID. unread_count: type: integer format: int64 description: Number of unread messages. username: type: string description: The TikTok user name. avatar: type: string description: The URL for the TikTok creator's avatar image file. creator_im_id: type: string description: Creators' IM User ID. GetConversationMessagesResponse: 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/GetConversationMessagesResponseData" GetConversationMessagesResponseData: type: object properties: next_page_token: type: string description: |- The index indicates where we should start on the next page. If there is no more record, this field will be ""(empty string). Put this value to request param "page_token" for the next page query. unsupported_msg_tips: type: string description: If your app encounters a message type it doesn't support, you can display the text to guide the user to check the message in TikTok Shop. The content of the message depends on the specific `locale`. messages: type: array items: $ref: "#/components/schemas/GetConversationMessagesResponseDataMessage" description: Messages in conversation. GetConversationMessagesResponseDataMessage: type: object properties: id: type: string description: Message ID. type: type: string enum: - TEXT - IMAGE - ALLOCATED_SERVICE - NOTIFICATION - BUYER_ENTER_FROM_TRANSFER - BUYER_ENTER_FROM_PRODUCT - BUYER_ENTER_FROM_ORDER - PRODUCT_CARD - EMOTICONS - ORDER_CARD - VIDEO - RETURN_REFUND_CARD - COUPON_CARD - LOGISTICS_CARD - OTHER x-enum-descriptions: - "" - "" - A customer service agent joins the conversation. - Notification from the system. - The conversation is transferred to another customer service agent. - The buyer is viewing a product before sending this message. - The buyer is viewing an order before sending this message. - "" - "" - "" - "" - Return/refund card. - "" - "" - Messages of types not supported in this API. description: |- Message type. Possible enumerations: - TEXT - IMAGE - ALLOCATED_SERVICE - A customer service agent joins the conversation. - NOTIFICATION - Notification from the system. - BUYER_ENTER_FROM_TRANSFER : The conversation is transferred to another customer service agent. - BUYER_ENTER_FROM_PRODUCT : The buyer is viewing a product before sending this message. - BUYER_ENTER_FROM_ORDER : The buyer is viewing an order before sending this message. - PRODUCT_CARD - EMOTICONS - ORDER_CARD - VIDEO - RETURN_REFUND_CARD: Return/refund card. - COUPON_CARD - LOGISTICS_CARD - OTHER: Messages of types not supported in this API. content: type: string description: |- Message content, in JSON serialized string. Examples of content for each type of message are listed below: - TEXT: ``` { "content": "simple text" } ``` - IMAGE: ``` { "height": "290", "url": "https://tosv.boei18n.byted.org/obj/temai-im/FszkJ53nSapYG6KDaJQmqR3jjoZGwww304-290", "width": "304" } ``` - PRODUCT_CARD, BUYER_ENTER_FROM_PRODUCT: ``` { "product_id": "12345" } ``` - ORDER_CARD, BUYER_ENTER_FROM_ORDER : ``` { "order_id": "12345" } ``` - LOGISTICS_CARD: ``` { "order_id": "12345", "package_id": "321" } ``` - RETURN_REFUND_CARD: ``` { "order_id": "12345", "sku_id": "45678" } ``` - VIDEO: ``` { "url": "https://video-boei18n.byted.org/storage/v1/tos-boei18n-v-c72c01/e8240f35244646428df9c3244d1a7408?x-tos-algorithm=v2&x-tos-authkey=5bf25627da095a5cba28ace592de46cc&x-tos-expires=1681980481&x-tos-signature=r_bRxtrvGhXAuZgMmNhlZ_Upqzg", "cover": "https://p-boei18n.byted.org/tos-boei18n-v-c72c01/o8keEOhzTcNCcJyAbkWZwpLIyTfkJxcGbRBvLP~tplv-jvtte31kaf-origin-jpeg.jpeg?", "width": 640, "height": 360, "duration": "20.504", "vid": "v0e30cg700f7cgcmu8jc77u9e2bdp95g", "expire_time": "1681980481", "format": "mp4", "size": 400000, "bit_rate": 156067, "quality": "original", "codec_type": "h264" } ``` - ALLOCATED_SERVICE, NOTIFICATION, BUYER_ENTER_FROM_TRANSFER, OTHER: ``` { "content": "simple text" } ``` - COUPON_CARD: ``` { "coupon_id": "7262992004278206762" } ``` Note: Use [Get Coupon](6699dce0de15e502ed219e37) for the details of the coupon. create_time: type: integer format: int64 description: Unix timestamp for creating the message in seconds. is_visible: type: boolean description: |- Whether this message should be displayed to customer service. For example, the buyer will receive a rating request message at the end of the conversation from the system. You should not present this type of message to the seller or the customer support agents. sender: $ref: "#/components/schemas/GetConversationMessagesResponseDataMessageSender" description: The message sender. For system and robot roles, shop is the sender. index: type: string description: |- Message index. This field can be used to sort messages. "index" means the order of the message in the conversation. This value is unique for every message in a conversation. This value is time-related, meaning a newer message will get a larger "index". But it is not strictly increasing. data: type: string description: |- Structured message data encoded as a JSON string. Request it with `need_data=true`. The field is available only for visible messages and message types for which structured data can be generated. For a `LOGISTICS_CARD` message, `predict_delivery_time_min`, `predict_delivery_time_max`, and `tracking[].update_time_millis` are Unix timestamps in milliseconds and remain raw numeric values in `data`. The `time_zone` request parameter affects the generated localized `plaintext`; it does not convert these structured-data timestamp values. Example for a `LOGISTICS_CARD` message: ```json { "packages": [ { "package_id": "456", "product_name": "Nutrition", "product_image": "https://cdn-us.com/us/123jpeg:1000:1000.jpeg?dr=123&t=555", "paid_price": "$0.01", "quantity": 1, "predict_delivery_time_min": 1763198750000, "predict_delivery_time_max": 1763457950000, "delivery_option": "Standard shipping", "tracking_number": "1Z789", "shipping_provider_name": "UPS", "tracking": [ { "description": "Package has been delivered!", "update_time_millis": 1763954669267 }, { "description": "Arrived at the carrier's facility.", "update_time_millis": 1763954598311 }, { "description": "Package picked up.", "update_time_millis": 1763954598024 }, { "description": "Order packed and ready for dropoff at carrier's facility.", "update_time_millis": 1763451813897 }, { "description": "Order placed.", "update_time_millis": 1763112346906 } ] } ] } ``` plaintext: type: string description: |- Human-readable message content. Request it with `need_plaintext=true`. The field is available only for visible messages and message types for which plaintext can be generated. Example for a `PRODUCT_CARD` message: Product card shared: - Product ID: 1732529206731441911; - 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; - Product price: ; - Strike-through price: - Sold: 40013. View full details at: https://seller-vn.tiktok.com/product/manage?search_content=1732529206731441911 GetConversationMessagesResponseDataMessageSender: type: object properties: im_user_id: type: string description: |- Sender's ID. These are IM IDs, and can not be used to query orders. role: type: string enum: - BUYER - SHOP - CUSTOMER_SERVICE - SYSTEM - ROBOT description: |- Sender's role. Possible enumerations: - `BUYER` - `SHOP` - `CUSTOMER_SERVICE` - `SYSTEM` - `ROBOT` For `SYSTEM` and `ROBOT` role, the value of `im_user_id`, `nickname`, and `avatar` are the same as those of the `SHOP` role. nickname: type: string description: |- Sender's nickname. - For shops, the nickname is the shop's name. - For customer service, the nickname is the customer service's name. - For buyers, the nickname is the buyer's nickname on TikTok. You can set the nicknames for shops and customer service agents on Seller Center. avatar: type: string description: Sender's avatar URL. GetConversationResponse: 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/GetConversationResponseData" GetConversationResponseData: type: object properties: conversation: $ref: "#/components/schemas/GetConversationResponseDataConversation" description: Conversation info. GetConversationResponseDataConversation: type: object properties: id: type: string description: Conversation ID participant_count: type: integer format: int64 description: |- Number of participants in the conversation. - If there has been no customer service agent in the conversation, the value is `2`: the shop and the buyer; - Otherwise, the value is `3`: the shop, the buyer, and the customer service agent. participants: type: array items: $ref: "#/components/schemas/GetConversationResponseDataConversationParticipant" description: Conversation participants. create_time: type: integer format: int64 description: Unix timestamp when the conversation was created. In seconds. unread_count: type: integer format: int64 description: Number of messages unread by the customer service agent. cur_session_id: type: string description: ID of the current open session. This field is returned when `need_session_id` or `need_session_info` is `true` and current open session information is available. cur_session: $ref: "#/components/schemas/CurSession" description: Information about the current open session. This field is returned when `need_session_info` is `true` and current open session information is available. GetConversationResponseDataConversationParticipant: type: object properties: im_user_id: type: string description: Participant's ID, in IM system. This ID is used in IM system and can not be used to query orders. To query orders, use `user_id` instead. role: type: string enum: - BUYER - SHOP - CUSTOMER_SERVICE description: |- Participant's role. Possible enumerations: - `BUYER` - `SHOP` - `CUSTOMER_SERVICE` nickname: type: string description: Participant's nickname. avatar: type: string description: Participant's avatar URL. user_id: type: string description: Participant's ID. platform: type: string enum: - TIKTOK_SHOP - TOKOPEDIA description: |- Platform the buyer is from. This field is returned only when the participant role is `BUYER` and the shop region is Indonesia. Possible values: - `TIKTOK_SHOP` - `TOKOPEDIA` You cannot send platform-specific content to a buyer from another platform. For example, when sending a product card to a Tokopedia buyer, ensure that the product is listed on Tokopedia. GetConversationsResponse: 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/GetConversationsResponseData" GetConversationsResponseData: type: object properties: next_page_token: type: string description: |- The index indicates where we should start on the next page. If there is no more record, this field will be ""(empty string). Put this value to request param "page_token" for the next page query. conversations: type: array items: $ref: "#/components/schemas/GetConversationsResponseDataConversation" description: Conversation info. GetConversationsResponseDataConversation: type: object properties: id: type: string description: Conversation ID participant_count: type: integer format: int64 description: |- Number of participants in the conversation. - If there has been no customer service agent in the conversation, the value is `2`: the shop and the buyer; - Otherwise, the value is `3`: the shop, the buyer, and the customer service agent. can_send_message: type: boolean description: |- Whether customer service agent can send message in this conversation. Under any of the following circumstances, the CS agent can send messages: 1. There has been a prior conversation between the buyer and the shop within the last 30 days. 2. The buyer placed an order at the shop within the past 60 days. 3. The buyer has a history of returns or refunds at the shop. unread_count: type: integer format: int64 description: Number of messages unread by the customer service agent. create_time: type: integer format: int64 description: Unix timestamp when the conversation was created. In seconds. participants: type: array items: $ref: "#/components/schemas/GetConversationsResponseDataConversationParticipant" description: Conversation participants. latest_message: $ref: "#/components/schemas/GetConversationsResponseDataConversationLatestMessage" description: The latest message in conversation. cur_session_id: type: string description: Current session id. cur_session: $ref: "#/components/schemas/CurSession" description: Current session. GetConversationsResponseDataConversationLatestMessage: type: object properties: id: type: string description: Message ID. type: type: string enum: - TEXT - IMAGE - ALLOCATED_SERVICE - NOTIFICATION - BUYER_ENTER_FROM_TRANSFER - BUYER_ENTER_FROM_PRODUCT - BUYER_ENTER_FROM_ORDER - PRODUCT_CARD - EMOTICONS - ORDER_CARD - VIDEO - RETURN_REFUND_CARD - COUPON_CARD - OTHER x-enum-descriptions: - "" - "" - A customer service agent joins the conversation. - Notification from the system. - The conversation is transferred to another customer service agent. - The buyer is viewing a product before sending this message. - The buyer is viewing an order before sending this message. - "" - "" - "" - "" - Return/refund card. - "" - Messages of types not supported in this API. description: |- Message type. Possible enumerations: - TEXT - IMAGE - ALLOCATED_SERVICE - A customer service agent joins the conversation. - NOTIFICATION - Notification from the system. - BUYER_ENTER_FROM_TRANSFER : The conversation is transferred to another customer service agent. - BUYER_ENTER_FROM_PRODUCT : The buyer is viewing a product before sending this message. - BUYER_ENTER_FROM_ORDER : The buyer is viewing an order before sending this message. - PRODUCT_CARD - EMOTICONS - ORDER_CARD - VIDEO - RETURN_REFUND_CARD: Return/refund card. - COUPON_CARD - OTHER: Messages of types not supported in this API. content: type: string description: |- Message content, in JSON serialized string. Examples of content for each type of message are listed below: - TEXT: ``` { "content": "simple text" } ``` - IMAGE: ``` { "height": "290", "url": "https://tosv.boei18n.byted.org/obj/temai-im/FszkJ53nSapYG6KDaJQmqR3jjoZGwww304-290", "width": "304" } ``` - PRODUCT_CARD, BUYER_ENTER_FROM_PRODUCT: ``` { "product_id": "12345" } ``` - ORDER_CARD, BUYER_ENTER_FROM_ORDER : ``` { "order_id": "12345" } ``` - RETURN_REFUND_CARD: ``` { "order_id": "12345", "sku_id": "45678" } ``` - VIDEO: ``` { "url": "https://video-boei18n.byted.org/storage/v1/tos-boei18n-v-c72c01/e8240f35244646428df9c3244d1a7408?x-tos-algorithm=v2&x-tos-authkey=5bf25627da095a5cba28ace592de46cc&x-tos-expires=1681980481&x-tos-signature=r_bRxtrvGhXAuZgMmNhlZ_Upqzg", "cover": "https://p-boei18n.byted.org/tos-boei18n-v-c72c01/o8keEOhzTcNCcJyAbkWZwpLIyTfkJxcGbRBvLP~tplv-jvtte31kaf-origin-jpeg.jpeg?", "width": 640, "height": 360, "duration": "20.504", "vid": "v0e30cg700f7cgcmu8jc77u9e2bdp95g", "expire_time": "1681980481", "format": "mp4", "size": 400000, "bit_rate": 156067, "quality": "original", "codec_type": "h264" } ``` - ALLOCATED_SERVICE, NOTIFICATION, BUYER_ENTER_FROM_TRANSFER, OTHER: ``` { "content": "simple text" } ``` - COUPON_CARD: ``` { "coupon_id": "7262992004278206762" } ``` Note: Use [Get Coupon](6699dce0de15e502ed219e37) for the details of the coupon. create_time: type: integer format: int64 description: Unix timestamp for creating the message in seconds. is_visible: type: boolean description: |- Whether this message should be displayed to customer service. For example, the buyer will receive a rating request message at the end of the conversation from the system. You should not present this type of message to the seller or the customer support agents. sender: $ref: "#/components/schemas/GetConversationsResponseDataConversationLatestMessageSender" description: Sender of the message. index: type: string description: |- Message index. This field can be used to sort messages. "index" means the order of the message in the conversation. This value is unique for every message in a conversation. This value is time-related, meaning a newer message will get a larger "index". But it is not strictly increasing. GetConversationsResponseDataConversationLatestMessageSender: type: object properties: im_user_id: type: string description: Sender's IM ID. Sender's unique identifier in TikTok Shop's IM system. avatar: type: string description: Sender's avatar URL. role: type: string enum: - BUYER - SHOP - CUSTOMER_SERVICE - SYSTEM - ROBOT description: |- Sender's role. Possible enumerations: - `BUYER` - `SHOP` - `CUSTOMER_SERVICE` - `SYSTEM` - `ROBOT` For `SYSTEM` and `ROBOT` role, the value of `im_user_id`, `nickname`, and `avatar` are the same as those of the `SHOP` role. nickname: type: string description: |- Sender's nickname. - For shops, the nickname is the shop's name. - For customer service, the nickname is the customer service's name. - For buyers, the nickname is the buyer's nickname on TikTok. You can set the nicknames for shops and customer service agents on Seller Center. GetConversationsResponseDataConversationParticipant: type: object properties: im_user_id: type: string description: Participant's ID, in IM system. This ID is used in IM system and can not be used to query orders. To query orders, use `user_id` instead. avatar: type: string description: Participant's avatar URL. user_id: type: string description: Participant's ID. role: type: string enum: - BUYER - SHOP - CUSTOMER_SERVICE description: |- Participant's role. Possible enumerations: - `BUYER` - `SHOP` - `CUSTOMER_SERVICE` nickname: type: string description: Participant's nickname. buyer_platform: type: string enum: - TIKTOK_SHOP - TOKOPEDIA description: |- Which platform is the buyer from. This field will only be returned when the participant's `role` is `BUYER` and the shop's region is Indonesia. Possible enumerations: - TIKTOK_SHOP - TOKOPEDIA You cannot send platform-specific content to the buyer from a different platform. For example, when you send a product card to the Tokopedia buyer, you must ensure the product is listed on Tokopedia. GetCouponResponse: 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/GetCouponResponseData" GetCouponResponseData: type: object properties: coupon: $ref: "#/components/schemas/GetCouponResponseDataCoupon" description: The coupon detail object, including identity, display settings, status, claim and redemption durations, discount, threshold, product scope, usage limits, usage stats, and live tasks. GetCouponResponseDataCoupon: type: object properties: id: type: string description: A unique ID that identifies different coupons. title: type: string description: Seller-specified title of the coupon. display_type: type: string description: |- The display type of coupons. Values: - `REGULAR`: Regular coupons which are displayed to TikTok users across all display locations available in TTS, including PLPs, PDPs, TikTok Videos, LIVE Rooms, Creator Showcases, and may be shared via TTS Customer Support instant messages. Includes coupons which target select customer segments. - `LIVE`: Coupons which are only displayed to TikTok users in LIVE Rooms. - `CREATOR_EXCLUSIVE`: Coupons that can be claimed through the display channels of the specified creator, such as their LIVE Rooms, and their Creator Showcase. - `CHAT`: Exclusive coupons that may be sent to customers via TTS customer support chat messages, but are not displayed in other display locations. - `PROMO_CODE`: Promo codes do not have dedicated display locations on TikTok, but may be shared with customers in LIVEs, in TikTok videos, or other social media platforms. They can be claimed by customers entering a claim code at checkout or by customers that use a custom promo code landing page URL. status: type: string description: |- Coupon's promotion status. Values: - `NOT_START`: Not available to TikTok users until the coupon's configured start time. - `ONGOING`: Available to TikTok users. - `EXPIRED`: Not available to TikTok users because it has expired. - `DEACTIVATED`: Deactivated by the seller and is not available to TikTok users. create_time: type: integer format: int64 description: The UNIX timestamp, in milliseconds, when the coupon was created. update_time: type: integer format: int64 description: The UNIX timestamp, in milliseconds, when the coupon was last updated. claim_duration: $ref: "#/components/schemas/ClaimDuration" description: Claimable period of the coupon. redemption_duration: $ref: "#/components/schemas/RedemptionDuration" description: Period during which the coupon can be redeemed (i.e. applied to an order). display_channels: type: array items: type: string description: |- The channels in which the coupons can be displayed or distributed: - `ALL`: All channels. - `SHOPPING_CENTER`: Only in TikTok Shop shopping center. - `CHAT`: Only in TT chat. - `LIVE`: Only in TT live. - `PRIVATE`: For promotion code. TikTok users won't know the codes until you show them. - `PRIVATE_WITH_ALLOW`: A private display-channel value returned for a regular coupon. - `VIDEO`: Only in short videos. - `SHOWCASE`: Only in showcases. promo_code: type: string description: Promotion code. Returned only when `display_type == 'PROMO_CODE'`. The string contains only Unicode letters or digits. The length of the string is in the range of `[6, 12]`. target_buyer_segment: type: string enum: - ALL - NEW - REPEAT_CUSTOMERS - RECENT_CUSTOMERS - FREQUENT_CUSTOMERS - LAPSED_CUSTOMERS - NEW_FOLLOWERS - EXISTING_ACTIVE_FOLLOWERS x-enum-descriptions: - May be discovered and claimed by all TTS buyers. - Customers who have never purchased from your shop. - People who have previously placed orders in your shop and made another purchase within certain days(30 days for non-US and 90 days for US). - People who have made their first purchase in your shop in the past certain days(30 days for non-US and 90 days for US). - Customers with more than 1 purchase within the last 90 days. - Customers with at least 1 purchase in the past 365 days but no purchases within the last certain days(90 days for non-US and 30 days for US). - People who started following the TikTok account of your shop in the past 30 days. - People who followed the TikTok account of your shop and engaged with your shop through LIVE, short videos or product cards in the past 30 days. description: |- The target buyer segment of the coupon. Possible enumerations are: - `ALL`: May be discovered and claimed by all TTS buyers. - `NEW`:Customers who have never purchased from your shop. - `REPEAT_CUSTOMERS`: People who have previously placed orders in your shop and made another purchase within certain days(30 days for non-US and 90 days for US). - `RECENT_CUSTOMERS`: People who have made their first purchase in your shop in the past certain days(30 days for non-US and 90 days for US). - `FREQUENT_CUSTOMERS`: Customers with more than 1 purchase within the last 90 days. - `LAPSED_CUSTOMERS`: Customers with at least 1 purchase in the past 365 days but no purchases within the last certain days(90 days for non-US and 30 days for US). - `NEW_FOLLOWERS`: People who started following the TikTok account of your shop in the past 30 days. - `EXISTING_ACTIVE_FOLLOWERS`: People who followed the TikTok account of your shop and engaged with your shop through LIVE, short videos or product cards in the past 30 days. usage_limits: $ref: "#/components/schemas/UsageLimit" description: Limitations for the use of the coupons. usage_stats: $ref: "#/components/schemas/GetCouponResponseDataCouponUsageStat" description: Usage statistics discount: $ref: "#/components/schemas/GetCouponResponseDataCouponDiscount" description: The coupon discount configuration, including type, reduction_amount, percentage, and max_discount. threshold: $ref: "#/components/schemas/GetCouponResponseDataCouponThreshold" description: Optional minimum purchase criteria that must be met in order to receive the coupon's discount. product_scope: type: string enum: - FULL_SHOP - SPECIFIC_PRODUCTS x-enum-descriptions: - All products sold in the shop are eligible for the coupon. - Only specified products are eligible for the coupon. The list of specified products are returned in the response of the `get_coupon` API. description: |- The range of the products which the coupon applies to. The possible enumerations are: - `FULL_SHOP`: All products sold in the shop are eligible for the coupon. - `SPECIFIC_PRODUCTS`: Only specified products are eligible for the coupon. The list of specified products are returned in the response of the `get_coupon` API. product_ids: type: array items: type: string description: The IDs of the eligible products when `product_scope == 'SPECIFIC_PRODUCTS'`. seller_tnc: type: string description: Custom terms & conditions optionally uploaded by the seller when configuring the coupon. creation_source: type: string description: |- The system where the coupon is created: - `SELLER_CENTER`: Created via the Promotions section of TikTok Seller Center. - `SELLER_APP`: Created via the TikTok Seller Mobile App. - `TTS_CRM`: Created via the TikTok Shop CRM. live_tasks: type: array items: $ref: "#/components/schemas/GetCouponResponseDataCouponLiveTask" description: The tasks which the shopper must fulfill before claiming the coupon distributed in TikTok live. Only exists for LIVE coupons in the US and the UK. GetCouponResponseDataCouponDiscount: type: object properties: type: type: string enum: - AMOUNT_OFF - PERCENT_OFF x-enum-descriptions: - Reduces the final price of the item by the specified `reduction_amount` - Reduces the final price by the specified `percentage`. description: |- The type of discount offered by the coupon. Possible enumerations are: - `AMOUNT_OFF`: Reduces the final price of the item by the specified `reduction_amount` - `PERCENT_OFF`: Reduces the final price by the specified `percentage`. reduction_amount: $ref: "#/components/schemas/ReductionAmount" description: Will appear when `type == 'AMOUNT_OFF'`. percentage: type: string description: The discount offered by the coupon, in percentage points. Will appear when `type == 'PERCENT_OFF'`. max_discount: $ref: "#/components/schemas/MaxDiscount" description: Optional monetary upper limit of the total discount amount when `type == "PERCENT_OFF"`. GetCouponResponseDataCouponLiveTask: type: object properties: type: type: string enum: - NONE - FOLLOW_HOST - WATCH_FOR_MIN_TIME x-enum-descriptions: - Any shopper in the LIVE room may claim the coupon. - Shoppers must follow the LIVE host before being able to claim the coupon. - Shoppers must watch the LIVE for the time specified by `min_watch_time` before being able to claim the coupon. description: |- Possible enumerations: - `NONE`: Any shopper in the LIVE room may claim the coupon. - `FOLLOW_HOST`: Shoppers must follow the LIVE host before being able to claim the coupon. - `WATCH_FOR_MIN_TIME`: Shoppers must watch the LIVE for the time specified by `min_watch_time` before being able to claim the coupon. min_watch_time: type: string description: Number of seconds for which the shopper must watch the LIVE in order to claim the coupon. GetCouponResponseDataCouponThreshold: type: object properties: type: type: string enum: - NONE - MIN_SPEND x-enum-descriptions: - No minimum purchase criteria. - Buyer must meet or exceed the minimum spend criteria with eligible products. description: |- The type of purchase criteria. Possible enumerations are: - `NONE`: No minimum purchase criteria. - `MIN_SPEND`: Buyer must meet or exceed the minimum spend criteria with eligible products. min_spend: $ref: "#/components/schemas/MinSpend" description: When `threshold.type == 'MIN_SPEND'`, a customer must purchase products from the range defined by `product_scope` with a monetary amount greater than or equal to this value, or the customer cannot use the coupon. GetCouponResponseDataCouponUsageStat: type: object properties: claimed_count: type: integer format: int64 description: The number of times that the coupon has been claimed. redeemed_count: type: integer format: int64 description: The number of times that a coupon has been redeemed (i.e. applied to an order). GetCreatorConversationMessagesResponse: 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/GetCreatorConversationMessagesResponseData" GetCreatorConversationMessagesResponseData: type: object properties: has_more: type: boolean description: Whether there are any more messages. next_page_token: type: string description: When `has_more` is `true`, pass this cursor as `page_token` in the next request. It is empty when `has_more` is `false`. messages: type: array items: $ref: "#/components/schemas/GetCreatorConversationMessagesResponseDataMessage" GetCreatorConversationMessagesResponseDataMessage: type: object properties: conversation_index: type: string description: Index of the message in the conversation. Higher index corresponds to newer message. message_body: $ref: "#/components/schemas/GetCreatorConversationMessagesResponseDataMessageMessageBody" description: Message's content GetCreatorConversationMessagesResponseDataMessageMessageBody: type: object properties: id: type: string description: Message ID. conversation_id: type: string description: Conversation ID to which the message belongs. type: type: string enum: - TEXT - PRODUCT_CARD - TARGET_COLLABORATION_CARD - FREE_SAMPLE_CARD - IMAGE - CRM_TEXT_WITH_IMAGE_CARD - CRM_TEXT_WITH_PRODUCTS_CARD - NOTIFICATION - EMOTICONS - SYSTEM description: |- Message type. Possible values: - TEXT - PRODUCT_CARD - TARGET_COLLABORATION_CARD - FREE_SAMPLE_CARD - IMAGE - CRM_TEXT_WITH_IMAGE_CARD - CRM_TEXT_WITH_PRODUCTS_CARD - NOTIFICATION - EMOTICONS - SYSTEM content: type: string description: |- Message content serialized as a JSON string. The JSON object depends on `type`: - `TEXT`: `{"content": "simple text"}` - `PRODUCT_CARD`: `{"product_id": "12345"}` - `TARGET_COLLABORATION_CARD`: `{"invitation_group_id": "1234"}` - `FREE_SAMPLE_CARD`: `{"apply_id": "1234"}` - `IMAGE`: `{"height": "290", "url": "", "width": "304"}` - `CRM_TEXT_WITH_IMAGE_CARD`: `{"title": "abc", "content": "efg", "url": ""}` - `CRM_TEXT_WITH_PRODUCTS_CARD`: `{"title": "abc", "content": "efg", "product_ids": [123, 456, 789, 222]}` - `NOTIFICATION` or `SYSTEM`: `{"content": "notification/system message"}` - `EMOTICONS`: `{"height": "110", "url": "", "width": "110"}` create_time: type: integer format: int64 description: Message creation time, represented as a Unix timestamp (seconds). sender_id: type: string description: The message sender im id GetCreatorMarketplaceAdvancedSearchFiltersRequest: type: object properties: options: type: array items: $ref: "#/components/schemas/GetCreatorMarketplaceAdvancedSearchFiltersRequestOption" description: The filter option types to retrieve. If this field is omitted or empty, both `option_list` and `sorters` are returned as empty arrays. GetCreatorMarketplaceAdvancedSearchFiltersRequestOption: type: object properties: option_type: type: string enum: - OPTION_VERTICAL_PRO - OPTION_LANGUAGE - OPTION_CREATOR_LEVEL - OPTION_SORTER - OPTION_BRAND x-enum-descriptions: - Category Pro, a label for creators who regularly post about one product category and generated most of their sales in that category during the past 60 days. - Creator language. - Creator level based on GMV. The definition varies by country and is maintained by the TikTok Shop Creator team. - Available creator-search sorting options, returned in `sorters`. - Creator brand information. This value is not supported in DE, FR, IT, ES, IE, or JP. description: |- Filter option type to retrieve. Possible values: - `OPTION_VERTICAL_PRO`: Category Pro, a label for creators who regularly post about one product category and generated most of their sales in that category during the past 60 days. - `OPTION_LANGUAGE`: Creator language. - `OPTION_CREATOR_LEVEL`: Creator level based on GMV. The definition varies by country and is maintained by the TikTok Shop Creator team. - `OPTION_SORTER`: Available creator-search sorting options, returned in `sorters`. - `OPTION_BRAND`: Creator brand information. This value is not supported in DE, FR, IT, ES, IE, or JP. GetCreatorMarketplaceAdvancedSearchFiltersResponse: 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/GetCreatorMarketplaceAdvancedSearchFiltersResponseData" GetCreatorMarketplaceAdvancedSearchFiltersResponseData: type: object properties: data: $ref: "#/components/schemas/GetCreatorMarketplaceAdvancedSearchFiltersResponseDataData" description: The available Creator Marketplace search-filter values and sorting options. GetCreatorMarketplaceAdvancedSearchFiltersResponseDataData: type: object properties: option_list: type: array items: $ref: "#/components/schemas/GetCreatorMarketplaceAdvancedSearchFiltersResponseDataDataOptionList" description: Creator Marketplace Advanced Filter Option List. If we return an empty object, it means this filter is not currently supported by your account or region. sorters: type: array items: $ref: "#/components/schemas/GetCreatorMarketplaceAdvancedSearchFiltersResponseDataDataSorter" description: The available sorting options for Creator Marketplace search results. GetCreatorMarketplaceAdvancedSearchFiltersResponseDataDataOptionList: type: object properties: option_type: type: string description: The requested filter option type represented by this entry. options: type: array items: $ref: "#/components/schemas/Option" description: The available values for this filter option type. GetCreatorMarketplaceAdvancedSearchFiltersResponseDataDataSorter: type: object properties: algorithm_id: type: string description: sort algorithm id name: type: string description: sort algorithm name GetCreatorPerformanceForCampaignProductResponse: 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/GetCreatorPerformanceForCampaignProductResponseData" GetCreatorPerformanceForCampaignProductResponseData: type: object properties: total_creator_count: type: integer format: int64 description: The total number of creators associated with the specified product in the campaign across all pages. promotion_creators: type: array items: $ref: "#/components/schemas/GetCreatorPerformanceForCampaignProductResponseDataPromotionCreator" description: A list of objects representing information about the Affiliate Creator associated with the product promotion. next_page_token: type: string description: Opaque token for retrieving the next page. When this value is non-empty, pass it as the `page_token` query parameter in the next request and reuse the same `campaign_id`, `product_id`, and `page_size`. An empty token means there are no more results. GetCreatorPerformanceForCampaignProductResponseDataPromotionCreator: type: object properties: paid_amount: $ref: "#/components/schemas/GetCreatorPerformanceForCampaignProductResponseDataPromotionCreatorPaidAmount" description: An object representing the total amount paid for this product. room_count: type: integer format: int64 description: The number of live broadcast rooms associated with this promotion. video_count: type: integer format: int64 description: The total number of videos associated with this promotion published by creators. free_sample_status: type: string description: |- Status of the Creator's sample application. - NOT_REQUESTED - PENDING - AWAITING_SHIPMENT - AWAITING_COLLECTION - SHIPPED - CONTENT_PENDING - REJECT_CANCELLED - OVERDUE_CANCELLED - UNFULFIL_CANCELLED - DEL_PLAN_CANCELLED - SELLER_NOT_SHIP_CANCELLED - WITHDRAW_CANCELLED - UNFULFILLABLE_CANCELLED - OPERATOR_MANUAL_CANCELLED - OPERATOR_MANUAL_FAILED - OPERATOR_MANUAL_COMPLETED - COMPLETED commission: type: string description: The commission rate in hundredths of a percent (0.01%). For example, a value of 1000 is 10.00%. effective_end_time: type: string description: The effective end time for the collaboration in Unix epoch time format. effective_start_time: type: string description: The effective start time for the collaboration in Unix epoch time format. creator: $ref: "#/components/schemas/GetCreatorPerformanceForCampaignProductResponseDataPromotionCreatorCreator" description: An object representing information about the creator associated with the promotion. affiliate_product_id: type: string description: The affiliate product identifier. GetCreatorPerformanceForCampaignProductResponseDataPromotionCreatorCreator: type: object properties: nick_name: type: string description: The TikTok nickname of the creator. avatar_url: type: string description: A URL for the creator's avatar image in the TikTok CDN. follower_num: type: integer format: int64 description: The total count of TikTok followers for the creator. user_name: type: string description: The TikTok username of the creator. creator_open_id: type: string description: Creator Open ID. More details:https://partner.tiktokshop.com/docv2/page/3obfokj6 GetCreatorPerformanceForCampaignProductResponseDataPromotionCreatorPaidAmount: type: object properties: currency: type: string description: The currency code for the amount field. amount: type: string description: The total amount paid for this product. GetCreatorProfileResponse: 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/GetCreatorProfileResponseData" GetCreatorProfileResponseData: type: object properties: avatar: $ref: "#/components/schemas/GetCreatorProfileResponseDataAvatar" description: Data associated with the TikTok creator's profile avatar. username: type: string description: The TikTok user name. selection_region: type: string description: The region in which the creator is eligible to promote products in showcases, videos, and live streams. register_region: type: string description: The region in which the creator's TikTok account is registered. seller_type: type: string description: |- If the creator is also also has a TikTok Shop seller account, the seller type of the creator. This is an enumerated type with values: - CROSS_BORDER - LOCAL permissions: type: array items: type: string description: |- A list of product promotion permissions for the creator. The list can include zero or more of the following permissions: - LIVE_STREAM_PERMISSION - SELF_SALE_PERMISSION - ADD_AFFILIATE_PERMISSION - PHOTO_SHOPPABLE_PERMISSION_PRODUCT - PHOTO_SHOPPABLE_PERMISSION_SHOP user_type: type: string description: |- The creator's user type. This is an enumerated type with values: - TIKTOK_SHOP_OFFICIAL_ACCOUNT - TIKTOK_MARKETING_ACCOUNT - TIKTOK_SHOP_CREATOR creator_user_open_id: type: string description: Creator Open ID. [More details](https://partner.tiktokshop.com/docv2/page/3obfokj6) GetCreatorProfileResponseDataAvatar: type: object properties: width: type: integer format: int64 description: The avatar image width in pixels. height: type: integer format: int64 description: The avatar image height in pixels. url: type: string description: The URL for the TikTok creator's avatar image file. GetCreatorSampleApplicationDetailRequest: type: object properties: product_id: type: string description: The product identifier. application_id: type: string description: Free sample application ID. When `application_type` is `FREE_SAMPLE`, provide `application_id`; if it is omitted, provide `main_order_id` in addition to the required `product_id`. application_type: type: string description: |- The type of creator sample application. - FREE_SAMPLE : free sample supplied by seller which creator can apply for by themselves from product detail page. - SAMPLE_COUPON: creator claimed sample coupon (a type of coupon) and used it to place orders at a discount price. - SAMPLE_CAMPAIGN: activity organized by the platform. Creators can participate in this activity to obtain sample products provided by the platform for free. main_order_id: type: string description: The real main order identifier, required when application is "SAMPLE_COUPON" or "SAMPLE_CAMPAIGN" or "REFUNDABLE_SAMPLE". required: - product_id - application_type GetCreatorSampleApplicationDetailResponse: 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/GetCreatorSampleApplicationDetailResponseData" GetCreatorSampleApplicationDetailResponseData: type: object properties: sample_application: $ref: "#/components/schemas/GetCreatorSampleApplicationDetailResponseDataSampleApplication" description: The sample application information. GetCreatorSampleApplicationDetailResponseDataSampleApplication: type: object properties: id: type: string description: Sample application identifier. create_time: type: integer format: int64 description: Sample application create time in seconds. sample_product: $ref: "#/components/schemas/SampleProduct" description: The sample product information. main_order_id: type: string description: The sample order is generated after the sample application is approved by seller. activity_id: type: string description: The sample activity identifier id( only for sample campaign). type: type: string description: |- The type of creator sample application. - FREE_SAMPLE : free sample supplied by seller which creator can apply by themselves from pdp page. - SAMPLE_COUPON: creator claimed sample coupon (a type of coupon) and used it to purchase orders at a discount price. - SAMPLE_CAMPAIGN: activity organized by the platform. Creators can participate in this activity to obtain sample products provided by the platform for free. status: type: string description: |- The status of sample applications. The possible enumerated values are: - PENDING: The sample application is waiting for the seller's review. - AWAITING_SHIPMENT: The application is approved, and the seller needs to ship the sample. - SHIPPED: The sample has been shipped by the seller and is waiting for the creator to receive the package. - CONTENT_PENDING: The creator has received the sample package and is expected to create content. - REJECT_CANCELLED: The sample application has been rejected by the seller. - OVERDUE_CANCELLED: The sample application has expired due to being overdue. - UNFULFILL_CANCELLED: The creator did not fulfill the commitment to create content within the agreed timeframe. - SELLER_NOT_SHIP_CANCELLED: The seller did not ship the sample within the required timeframe. - WITHDRAW_CANCELLED: The creator withdrew the sample application before the seller approved it. - UNFULFILLABLE_CANCELLED: The application was cancelled due to reasons beyond the creator's control, making it impossible to create content. - OPS_CANCELLED: The application was manually cancelled by operations staff. - OPS_FAILED: The application was marked as failed by operations staff. - OPS_ COMPLETED: The application was manually marked as completed by operations staff. - COMPLETED: The application is complete, and the creator has posted the content. This field allows for tracking the status of a sample application throughout its lifecycle, providing visibility into each stage of the process for sellers and creators. creator_fulfillment: $ref: "#/components/schemas/GetCreatorSampleApplicationDetailResponseDataSampleApplicationCreatorFulfillment" description: Fulfillment info for this sample application. GetCreatorSampleApplicationDetailResponseDataSampleApplicationCreatorFulfillment: type: object properties: id: type: string description: Fulfillment identifier. expiration_time: type: integer format: int64 description: Fulfillment deadline timestamp, in seconds. total_suspend_duration: type: integer format: int64 description: Total suspension duration for fulfillment, in seconds. status: type: string enum: - PENDING - ONGOING - SUCCEED - FAILED - OVERDUE - SUSPEND - CANCELLED - EXEMPTED - REPEATED x-enum-descriptions: - The creator is yet to fulfill the content creation obligation. - Fulfillment is in progress; content has been created and is being evaluated against criteria. - Fulfillment has been successfully completed; the content meets the required standards. - Fulfillment failed; the content did not meet the required standards. - Fulfillment is overdue; the creator did not meet the deadline. - Fulfillment has been suspended. - Fulfillment has been cancelled, either by the creator or due to operational reasons. - The creator has been exempted from the fulfillment obligation. - The creator repeated the fulfillment after initially completing it; repeated fulfillment is not treated as a failure. description: |- Fulfillment status, It indicates the current status of the fulfillment process. The possible values are: - PENDING: The creator is yet to fulfill the content creation obligation. - ONGOING: Fulfillment is in progress; content has been created and is being evaluated against criteria. - SUCCEED: Fulfillment has been successfully completed; the content meets the required standards. - FAILED: Fulfillment failed; the content did not meet the required standards. - OVERDUE: Fulfillment is overdue; the creator did not meet the deadline. - SUSPEND: Fulfillment has been suspended. - CANCELLED: Fulfillment has been cancelled, either by the creator or due to operational reasons. - EXEMPTED: The creator has been exempted from the fulfillment obligation. - REPEATED: The creator repeated the fulfillment after initially completing it; repeated fulfillment is not treated as a failure. GetCustomerServicePerformanceResponse: 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/GetCustomerServicePerformanceResponseData" GetCustomerServicePerformanceResponseData: type: object properties: performance: $ref: "#/components/schemas/GetCustomerServicePerformanceResponseDataPerformance" description: The customer service performance metrics for the shop based on chat support sessions within the selected evaluation period. GetCustomerServicePerformanceResponseDataPerformance: type: object properties: support_session_count: type: integer format: int64 description: The total number of chat support sessions initiated by customers. A session starts when a customer first clicks an FAQ card or sends a message (text, image, video, emoji, product card, order card, etc.) in chat. The sessions which started in the specified time slot are included in calculation. response_percentage: type: string description: |- The percentage of chat support sessions of which the first response happens within 24 hours. The sessions which started in the specified time slot are included in calculation. - Automated responses such as FAQ cards are regarded as responses within 24 hours. - Sessions initiated during vacation mode are excluded from this calculation. satisfaction_percentage: type: string description: The percentage of chat support sessions rated 'Satisfied' (4 or 5 stars). The sessions of which the rating occurred in the specified time slot are included in the calculation; the sessions without rate are not included in the calculation. response_time_mins: type: string description: The average first response time in minutes for chat support sessions. The sessions which started in the specified time slot are included in calculation. conversion_rate: type: string description: The percentage of successfully converted customers based on the total number of potential customers. cs_guided_gmv: type: string description: The revenue generated from orders placed by customers within 7 days of your response to their chat. currency: type: string description: The ISO 4217 three-letter currency code used for `cs_guided_gmv`. See [Currency Codes](https://www.iso.org/iso-4217-currency-codes.html). GetDecisionEligibilityResponse: 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/GetDecisionEligibilityResponseData" GetDecisionEligibilityResponseData: type: object properties: decisions: type: array items: $ref: "#/components/schemas/GetDecisionEligibilityResponseDataDecision" description: The seller-decision eligibility results for the specified aftersales request. GetDecisionEligibilityResponseDataDecision: type: object properties: decision: 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 description: |- One eligibility result for one evaluated seller decision. Possible Values: - `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` eligible: type: boolean description: Whether this seller decision is currently eligible for the specified aftersales request. `true` means eligible; `false` means ineligible. ineligible_code: type: integer format: int64 description: The reason code for an ineligible decision. This field is returned when eligible is false. ineligible_reason: type: string description: The reason for an ineligible decision. This field is returned when eligible is false. available_reject_reasons: type: array items: $ref: "#/components/schemas/AvailableRejectReason" description: The reject reasons available for an eligible reject decision. Each reason includes a name and localized display text. GetEligibleShippingServicesRequest: type: object properties: order_line_item_ids: type: array items: type: string description: Order line item ID list weight: $ref: "#/components/schemas/GetEligibleShippingServicesRequestWeight" description: The weight of the scheduled package. dimension: $ref: "#/components/schemas/GetEligibleShippingServicesRequestDimension" description: The dimensions of the scheduled package. order_line_list: type: array items: $ref: "#/components/schemas/ConfirmOrderSplitRequestSplittableGroupsV2OrderLineList" description: This new parameter is completely backward compatible with the previous oder_line_items_ids field and in addition this supports bundle order splitting, use the sub items accordingly GetEligibleShippingServicesRequestDimension: type: object properties: length: type: string description: The length of the package. The length, width, height must be passed together. width: type: string description: The width of the package. The length, width, height must be passed together. height: type: string description: The height of the package. The length, width, height must be passed together. unit: type: string description: |- The unit of measurement for the package dimensions. - CM - INCH required: - length - width - height - unit GetEligibleShippingServicesRequestWeight: type: object properties: value: type: string description: The weight of the scheduled package. unit: type: string description: |- The unit of measurement is used to measure the weight. - GRAM - POUND required: - value - unit GetEligibleShippingServicesResponse: 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/GetEligibleShippingServicesResponseData" GetEligibleShippingServicesResponseData: type: object properties: order_id: type: string description: TikTok Shop order ID order_line_id: type: array items: type: string description: Line item ID list weight: $ref: "#/components/schemas/GetEligibleShippingServicesResponseDataWeight" description: The weight of the scheduled package. shipping_services: type: array items: $ref: "#/components/schemas/GetEligibleShippingServicesResponseDataShippingService" description: The shipping services available for the order. dimension: $ref: "#/components/schemas/GetEligibleShippingServicesResponseDataDimension" description: The dimension of the scheduled package. GetEligibleShippingServicesResponseDataDimension: type: object properties: length: type: string description: The length of the package. width: type: string description: The width of the package. height: type: string description: The height of the package. unit: type: string description: |- The unit of measurement for the package dimensions. - CM - INCH GetEligibleShippingServicesResponseDataShippingService: type: object properties: id: type: string description: Shipping service ID name: type: string description: Shipping service Name price: type: string description: Estimated total price for this Shipping services currency: type: string description: Currency of the price earliest_delivery_days: type: integer format: int64 description: The minimum estimated duration required for parcel delivery.US only. latest_delivery_days: type: integer format: int64 description: The maximum estimated duration required for parcel delivery.US only. is_default: type: boolean description: Whether it is the default shipping service shipping_provider_name: type: string description: The name of shipping provider.US only. shipping_provider_id: type: string description: The ID of shipping provider.US only. shipping_fee: type: string description: Shipping fee shipping_app_service_fee: type: string description: Shipping surcharge paid to the ERPs signature_fee: type: string description: Signature service fee GetEligibleShippingServicesResponseDataWeight: type: object properties: value: type: string description: The weight of the scheduled package. unit: type: string description: |- The unit of measurement is used to measure the weight. - GRAM - POUND GetEngagementFeaturePermissionsResponse: 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/GetEngagementFeaturePermissionsResponseData" GetEngagementFeaturePermissionsResponseData: type: object properties: features: type: array items: $ref: "#/components/schemas/GetEngagementFeaturePermissionsResponseDataFeature" description: The list of customer engagement features that has access control. GetEngagementFeaturePermissionsResponseDataFeature: type: object properties: name: type: string enum: - FUNDAMENTAL - CUSTOM_MSG x-enum-descriptions: - The ability to use any customer engagement APIs or features. This is the prerequisite for all other customer engagement features. - The ability to define and send custom messages. description: |- The feature name. Possible values: - `FUNDAMENTAL`: The ability to use any customer engagement APIs or features. This is the prerequisite for all other customer engagement features. - `CUSTOM_MSG`: The ability to define and send custom messages. is_authorized: type: boolean description: |- A flag to indicate whether the shop has permission to use this feature. Possible values: - `true`: Authorized to use this feature. - `false`: Not authorized to use this feature. GetEngagementTaskPerformancesRequest: type: object properties: task_ids: type: array items: type: string description: The customer engagement task IDs for which to retrieve performance data. Provide 1 to 50 IDs; each ID must be a base-10 string that fits in a signed 64-bit integer. required: - task_ids GetEngagementTaskPerformancesResponse: 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/GetEngagementTaskPerformancesResponseData" GetEngagementTaskPerformancesResponseData: type: object properties: task_performances: type: array items: $ref: "#/components/schemas/GetEngagementTaskPerformancesResponseDataTaskPerformance" description: The requested list of task performance. GetEngagementTaskPerformancesResponseDataTaskPerformance: type: object properties: id: type: string description: The customer engagement task ID for this performance record. status: type: string enum: - UNKNOWN - DRAFT - WAITING - SENDING - FAILED - CANCELED - SUCCESS - DELETED x-enum-descriptions: - The task status is unknown. - The task is in draft status. - The task is waiting. - The task is sending messages. - The task failed to send messages. - The task was canceled. - The task completed successfully. - The task was deleted. description: |- The status of the task. Possible values: - `UNKNOWN`: The task status is unknown. - `DRAFT`: The task is in draft status. - `WAITING`: The task is waiting. - `SENDING`: The task is sending messages. - `FAILED`: The task failed to send messages. - `CANCELED`: The task was canceled. - `SUCCESS`: The task completed successfully. - `DELETED`: The task was deleted. sent_recipient_count: type: integer format: int64 description: The number of users that received the message. read_recipient_count: type: integer format: int64 description: The number of users that read the message. order_count: type: integer format: int64 description: The number of orders resulting from the message. gmv_amount: type: string description: The revenue from the converted orders. claimed_coupons_count: type: integer format: int64 description: The number of coupons claimed. GetExternalOrderReferencesResponse: 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/GetExternalOrderReferencesResponseData" GetExternalOrderReferencesResponseData: type: object properties: external_orders: type: array items: $ref: "#/components/schemas/ExternalOrder" description: |- A list of orders that have been synced between your OMS and TikTok Shop. Note: If you've synced order information between multiple OMSs to the same TikTok Shop order, you'll retrieve all external order information. GetExternalOrderReferencesResponseDataExternalOrderLineItem: type: object properties: id: type: string description: Line item ID in your OMS. origin_id: type: string description: Line item ID in TikTok Shop. GetFBTInboundOrderDetailsResponse: 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/GetFBTInboundOrderDetailsResponseData" GetFBTInboundOrderDetailsResponseData: type: object properties: inbound_orders: type: array items: $ref: "#/components/schemas/GetFBTInboundOrderDetailsResponseDataInboundOrder" description: A list of inbound order detail information. GetFBTInboundOrderDetailsResponseDataInboundOrder: type: object properties: order_id: type: string description: The numeric identifier for inbound order in Fulfilled by TikTok system. order_id_string: type: string description: The string identifier for inbound order in Fulfilled by TikTok system. order_plan_id: type: string description: Plan identifier for the inbound order. merchant: $ref: "#/components/schemas/GetFBTInboundOrderDetailsResponseDataInboundOrderMerchant" description: Information regarding the merchant who owns the order. create_time: type: integer format: int64 description: Unix seconds timestamp when the inbound order was created. ship_time: type: integer format: int64 description: Unix seconds timestamp when the inbound order was shipped. expected_arrival_time: type: integer format: int64 description: Unix seconds timestamp of the expected arrival time provided by merchant. actual_arrival_time: type: integer format: int64 description: Unix seconds timestamp of the actual arrival time of the inbound order. warehouse: $ref: "#/components/schemas/GetFBTInboundOrderDetailsResponseDataInboundOrderWarehouse" description: Warehouse information. status_logs: type: array items: $ref: "#/components/schemas/GetFBTInboundOrderDetailsResponseDataInboundOrderStatusLog" description: Inbound order operation-history entries derived from at most 200 source status records. This list may be incomplete, and this operation does not provide a cursor for retrieving additional status records. logistic_info_list: type: array items: $ref: "#/components/schemas/GetFBTInboundOrderDetailsResponseDataInboundOrderLogisticInfoList" description: List of logistics information tied to the order. Only populated for small-parcel inbound orders. carton_details: type: array items: $ref: "#/components/schemas/GetFBTInboundOrderDetailsResponseDataInboundOrderCartonDetail" description: Detailed carton information for the inbound order. Only populated if `include_carton_details` is passed as true in the request. inbound_goods_lot_receive_item_details: type: array items: $ref: "#/components/schemas/GetFBTInboundOrderDetailsResponseDataInboundOrderInboundGoodsLotReceiveItemDetail" description: A detailed breakdown of planned versus actual receiving information, segmented by item, lot number, and expiration date. GetFBTInboundOrderDetailsResponseDataInboundOrderCartonDetail: type: object properties: carton_no: type: string description: Carton number. carton_type: type: string enum: - SINGLE_SKU - MULTI_SKU description: |- Whether this carton is single-SKU or multi-SKU. **Possible values:** * `SINGLE_SKU` * `MULTI_SKU` box_measurements: $ref: "#/components/schemas/GetFBTInboundOrderDetailsResponseDataInboundOrderCartonDetailBoxMeasurement" description: Carton measurement. items: type: array items: $ref: "#/components/schemas/GetFBTInboundOrderDetailsResponseDataInboundOrderCartonDetailItem" description: List of items in this carton. GetFBTInboundOrderDetailsResponseDataInboundOrderCartonDetailBoxMeasurement: 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. **Possible values:** * `KILOGRAM` (kg) * `GRAM` (g) * `MILLIGRAM` (mg) * `POUNDS` (lbs) * `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. **Possible values:** * `METER` (m) * `CENTIMETER` (cm) * `MILLIMETER` (mm) * `FOOT` (ft) * `MICRON` (μm) * `INCH` (in) GetFBTInboundOrderDetailsResponseDataInboundOrderCartonDetailItem: type: object properties: goods_id: type: string description: Identifier for goods within the Fulfilled by TikTok system. quantity: type: integer format: int64 description: The number of units of the goods in this carton. GetFBTInboundOrderDetailsResponseDataInboundOrderInboundGoodsLotReceiveItemDetail: type: object properties: goods_id: type: string description: The unique numeric identifier of the goods within Fulfilled by TikTok. lot_code: type: string description: The batch or lot number assigned by the manufacturer for this group of items. This field is non-empty only for goods with lot code management. expiration_time: type: integer format: int64 description: The expiration date of the items in this lot, represented as a Unix timestamp in seconds. This value is non-zero only for goods with expiration-date management. planned_count: type: integer format: int64 description: The total quantity of this specific lot expected to be received as part of the inbound order. normal_received_count: type: integer format: int64 description: The quantity of items received at **fulfillment centers** in sellable (good) condition for this lot. If the inbound order is sent to a hub, this value will only be updated when the goods are subsequently transferred to the fulfillment center. defective_received_count: type: integer format: int64 description: The quantity of items received in a damaged or unsellable state. total_received_count: type: integer format: int64 description: The sum of both `normal_received_count` and `defective_received_count`. GetFBTInboundOrderDetailsResponseDataInboundOrderLogisticInfoList: type: object properties: provider_name: type: string enum: - FEDEX - UPS - DHL - USPS - OTHER x-enum-descriptions: - Federal Express - United Parcel Service - DHL Express - United States Postal Service - All other logistics providers description: |- Name of the logistics service provider Possible values: * `FEDEX` (Federal Express) * `UPS` (United Parcel Service) * `DHL` (DHL Express) * `USPS` (United States Postal Service) * `OTHER` (All other logistics providers) waybill_number: type: string description: The tracking number for the current inbound shipment with the carrier. related_number: type: string description: Carton number tied to the logistics information. GetFBTInboundOrderDetailsResponseDataInboundOrderMerchant: type: object properties: id: type: string description: The identifier of the merchant in Fulfilled by TikTok system. name: type: string description: Name of the Fulfilled by TikTok merchant. GetFBTInboundOrderDetailsResponseDataInboundOrderStatusLog: type: object properties: operate_time: type: integer format: int64 description: The time when the inbound order is processed by the merchant or warehouses, represented as a Unix timestamp in seconds. new_status: type: string enum: - WORKING - READY_TO_SHIP - TO_BE_RECEIVED - ARRIVED_HUB - INTERNAL_TRANSFER - RECEIVING - PARTIALLY_RECEIVED - RECEIVED - CANCELLED - DELIVERED description: |- The order status in **Fulfilled by TikTok (FBT)** warehouse after this operation. **Possible values:** * `WORKING` * `READY_TO_SHIP` * `TO_BE_RECEIVED` * `ARRIVED_HUB` * `INTERNAL_TRANSFER` * `RECEIVING` * `PARTIALLY_RECEIVED` * `RECEIVED` * `CANCELLED` * `DELIVERED` previous_status: type: string enum: - WORKING - READY_TO_SHIP - TO_BE_RECEIVED - ARRIVED_HUB - INTERNAL_TRANSFER - RECEIVING - PARTIALLY_RECEIVED - RECEIVED - CANCELLED - DELIVERED description: |- The order status in **Fulfilled by TikTok (FBT)** warehouse before this operation. **Possible values:** * `WORKING` * `READY_TO_SHIP` * `TO_BE_RECEIVED` * `ARRIVED_HUB` * `INTERNAL_TRANSFER` * `RECEIVING` * `PARTIALLY_RECEIVED` * `RECEIVED` * `CANCELLED` * `DELIVERED` operator: type: string description: The unique identifier or name of the user or system entity that performed the status change. GetFBTInboundOrderDetailsResponseDataInboundOrderWarehouse: type: object properties: fbt_warehouse_id: type: string description: The identifier for warehouse generated by Fulfilled by TikTok system. business_warehouse_ids: type: array items: type: string description: The business identifier for warehouse generated by TikTok Shop system, correlated with the `fbt_warehouse_id`. name: type: string description: The Fulfilled by TikTok warehouse name. type: type: string enum: - HUB - FC x-enum-descriptions: - "" - Fulfillment Center description: |- Type of warehouse associated with the inbound order. Possible values: * `HUB` * `FC` (Fulfillment Center) GetFBTMCFOrderStatusResponse: 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/GetFBTMCFOrderStatusResponseData" GetFBTMCFOrderStatusResponseData: type: object properties: mcf_order: $ref: "#/components/schemas/GetFBTMCFOrderStatusResponseDataMcfOrder" description: MCF order information GetFBTMCFOrderStatusResponseDataMcfOrder: 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/GetFBTMCFOrderStatusResponseDataMcfOrderConsignOrder" description: The consign orders created for the MCF order. If fulfillment is split across multiple packages, this array contains one entry for each package. create_time: type: integer format: int64 description: The Unix timestamp, in seconds, when the MCF order was created. GetFBTMCFOrderStatusResponseDataMcfOrderConsignOrder: type: object properties: id: type: string description: "`consign order` unique id" goods: type: array items: $ref: "#/components/schemas/GetFBTMCFOrderStatusResponseDataMcfOrderConsignOrderGood" description: The goods id and quantity in this consign order. tracking_number: type: - string - "null" description: The tracking number of this consign order. If the order has not yet been handed over to the logistics carrier, this field may be a null value. carrier: type: - string - "null" description: The shipping carrier of this consign order. If the order has not yet been handed over to the logistics carrier, this field may be a null value. status: type: string enum: - PENDING - HANDLE_BY_WAREHOUSE - SHIPPED - HANDOVER - CLOSED - LOST - DAMAGE - RETURNED - SCRAP - UNKNOWN - COMPLETED - ABNORMAL x-enum-descriptions: - The order is pending warehouse processing. - The order is being processed by the warehouse. - The order has shipped from the warehouse. - The logistics carrier has received the order and it is in transit. - The order is closed. - The order is lost. - The order is damaged. - The order was returned. - The order was scrapped. - The consign-order status or shipping-exception subtype is unknown. - The order is complete. - An issue prevents the order from being fulfilled. description: |- The status of the consign order. Possible values: - **PENDING** - The order is pending warehouse processing. - **HANDLE_BY_WAREHOUSE** - The order is being processed by the warehouse. - **SHIPPED** - The order has shipped from the warehouse. - **HANDOVER** - The logistics carrier has received the order and it is in transit. - **CLOSED** - The order is closed. - **LOST** - The order is lost. - **DAMAGE** - The order is damaged. - **RETURNED** - The order was returned. - **SCRAP** - The order was scrapped. - **UNKNOWN** - The consign-order status or shipping-exception subtype is unknown. - **COMPLETED** - The order is complete. - **ABNORMAL** - An issue prevents the order from being fulfilled. is_platform_closed: type: boolean description: Indicates who canceled the consign order when `status` is `CLOSED`. `true` means the FBT platform canceled the order; `false` means it was canceled through your OMS. issue: type: string description: This field displays the reason for order stalling. When a `consign order` is in an abnormal status (such as **ABNORMAL**, **LOST**, etc.), specific issue reasons will be shown here. shipping_provider: anyOf: - $ref: "#/components/schemas/ShippingProvider" - type: "null" description: The shipping carrier detailed informatioin of this consign order. If the order has not yet been handed over to the logistics carrier, this field may be a null value. GetFBTMCFOrderStatusResponseDataMcfOrderConsignOrderGood: type: object properties: id: type: string description: Identifier for goods generated by Fulfilled by TikTok systemgoods id quantity: type: integer format: int64 description: The goods quantity in this consign order GetFBTMCFOrderStatusWebhook: type: object properties: type: type: integer const: 58 description: The ID of the webhook type. tts_notification_id: type: string description: The ID of the notification. seller_open_id: type: string description: The open_id of the seller. For more information, refer to [Authorization overview](https://partner.tiktokshop.com/docv2/page/authorization-overview-202407). timestamp: type: integer format: int64 description: The UNIX timestamp when this webhook was triggered. data: $ref: "#/components/schemas/GetFBTMCFOrderStatusWebhookData" required: - type GetFBTMCFOrderStatusWebhookData: type: object properties: mcf_order: $ref: "#/components/schemas/GetFBTMCFOrderStatusWebhookDataMcfOrder" description: MCF order information GetFBTMCFOrderStatusWebhookDataMcfOrder: 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/GetFBTMCFOrderStatusWebhookDataMcfOrderConsignOrder" description: Once the order has been shipped, the `consign_orders` field will display the consignment details of the order. create_time: type: integer format: int64 description: The time when the mcf order is created GetFBTMCFOrderStatusWebhookDataMcfOrderConsignOrder: type: object properties: id: type: string description: "`consign order` unique id" tracking_number: type: - string - "null" description: The tracking number of this consign order. If the order has not yet been handed over to the logistics carrier, this field may be a null value. status: type: string description: |- The status of this consign order Possible Status Enumerations 1. **SHIPPED** - Order has been shipped out from the warehouse 2. **HANDOVER** - Order has been received by the logistics carrier and is in transit 3. **CLOSED** - Order has been closed 4. **LOST** - Order is lost 5. **DAMAGE** - Order is damaged 6. **COMPLETED** - Order has been completed 7. **ABNORMAL** - There is an issue related to this order and cannot be fulfilled. goods: type: array items: $ref: "#/components/schemas/GetFBTMCFOrderStatusWebhookDataMcfOrderConsignOrderGood" description: The goods id and quantity in this consign order. is_platform_closed: type: string description: This field indicates whether a consign order has been canceled by the FBT platform. If the value is true, it means the order has been canceled by the platform; if it is false, it means the order has been canceled by your OMS. issue: type: string description: This field displays the reason for order stalling. When a `consign order` is in an abnormal status (such as ABNORMAL, LOST, etc.), specific issue reasons will be shown here. shipping_provider: anyOf: - $ref: "#/components/schemas/GetFBTMCFOrderStatusWebhookDataMcfOrderConsignOrderShippingProvider" - type: "null" description: The shipping carrier detailed information of this consign order. If the order has not yet been handed over to the logistics carrier, this field may be a null value. GetFBTMCFOrderStatusWebhookDataMcfOrderConsignOrderGood: type: object properties: id: type: string description: Identifier for goods generated by Fulfilled by TikTok systemgoods id quantity: type: integer format: int64 description: The goods quantity in this consign order GetFBTMCFOrderStatusWebhookDataMcfOrderConsignOrderShippingProvider: type: object properties: id: type: string description: The shipping carrier unique id. name: type: string description: The shipping carrier name. GetFBTMerchantMCFStatusResponse: 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/GetFBTMerchantMCFStatusResponseData" GetFBTMerchantMCFStatusResponseData: type: object properties: mcf_status: $ref: "#/components/schemas/GetFBTMerchantMCFStatusResponseDataMcfStatus" description: seller multi channel fulfillment status GetFBTMerchantMCFStatusResponseDataMcfStatus: type: object properties: is_mcf: type: integer format: int64 description: Flag indicating whether the seller has participated in Multi Channel Fulfillment. 0 means inactive and 1 means active. GetFBTMerchantOnboardedRegionsResponse: 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/GetFBTMerchantOnboardedRegionsResponseData" GetFBTMerchantOnboardedRegionsResponseData: type: object properties: onboarded_regions: type: array items: $ref: "#/components/schemas/GetFBTMerchantOnboardedRegionsResponseDataOnboardedRegion" description: A list of countries or regions where the merchant is onboarded and can conduct business in the Fulfilled by TikTok system. If seller is not onboarded, `data` will be empty. GetFBTMerchantOnboardedRegionsResponseDataOnboardedRegion: type: object properties: region_code: type: string description: The country or region codes follow the two-character ISO 3166-1 alpha-2 format. GetFBTWarehouseListResponse: 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/GetFBTWarehouseListResponseData" GetFBTWarehouseListResponseData: type: object properties: warehouses: type: array items: $ref: "#/components/schemas/GetFBTWarehouseListResponseDataWarehouse" description: A list of Fulfilled by TikTok warehouses information. GetFBTWarehouseListResponseDataWarehouse: type: object properties: fbt_warehouse_id: type: string description: The identifier for warehouse generated by Fulfilled By TikTok system. warehouse_ids: type: array items: type: string description: The warehouse IDs generated by TikTok Shop that are associated with this Fulfilled by TikTok warehouse (`fbt_warehouse_id`). name: type: string description: The Fulfilled by TikTok warehouse name, e.g.TikTok_Eastvale(CA). type: type: string enum: - PLATFORM_WAREHOUSE - OTHER_WAREHOUSE x-enum-descriptions: - A warehouse operated by TikTok. - A warehouse that is not classified as a platform warehouse. description: |- The Fulfilled by TikTok warehouse type. Possible values: - `PLATFORM_WAREHOUSE`: A warehouse operated by TikTok. - `OTHER_WAREHOUSE`: A warehouse that is not classified as a platform warehouse. subscribed: type: boolean description: |- A flag indicating whether the warehouse is subscribed. True: Subscribed. False: Not subscribed. addresses: type: array items: $ref: "#/components/schemas/GetFBTWarehouseListResponseDataWarehouseAddress" description: A list of addresses used to receive inbound shipments at the Fulfilled by TikTok warehouse. logistics_services: type: array items: $ref: "#/components/schemas/GetFBTWarehouseListResponseDataWarehouseLogisticsService" description: A list of logistics service information related to the current warehouse. GetFBTWarehouseListResponseDataWarehouseAddress: type: object properties: postal_code: type: string description: Warehouse address postal code (also known as zip code). region_code: type: string description: Warehouse country or region code in two-character ISO 3166-1 alpha-2 format. state: type: string description: Warehouse address state or province. district: type: string description: Warehouse address district or county. city: type: string description: Warehouse address city. address_line_1: type: string description: The detail address line 1. address_line_2: type: string description: The detail address line 2, additional address information(optional). address_line_3: type: string description: The detail address line 3, additional address information(optional). GetFBTWarehouseListResponseDataWarehouseLogisticsService: type: object properties: id: type: string description: The identifier for logistics service in TikTok Shop system. name: type: string description: The logistics service name. subscribed: type: boolean description: |- A flag indicating whether the logistic service is subscribed. True: Subscribed. False: Not subscribed. GetGlobalAttributesResponse: 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/GetGlobalAttributesResponseData" GetGlobalAttributesResponseData: type: object properties: attributes: type: array items: $ref: "#/components/schemas/GetGlobalAttributesResponseDataAttribute" description: The list of standard built-in product and sales attributes that are bound to the specified category. GetGlobalAttributesResponseDataAttribute: type: object properties: id: type: string description: The ID of the built-in attribute. name: type: string description: The name of the built-in attribute. type: type: string enum: - SALES_PROPERTY - PRODUCT_PROPERTY x-enum-descriptions: - Indicates sales attributes that define product variants. - Indicates product attributes that describe the product as a whole. description: |- The attribute type. Possible values: - SALES_PROPERTY: Indicates sales attributes that define product variants. - PRODUCT_PROPERTY: Indicates product attributes that describe the product as a whole. is_requried: type: boolean description: |- A flag indicating whether the product attribute is required across all of the seller's markets when creating or editing a product. - true: The attribute is required in all of the seller's markets. - false: The attribute is not required in all of the seller's markets; it may be required in some markets, required only under certain conditions, or optional. Refer to `required_regions`, `optional_regions`, and `requirement_conditions` for the specific requirements. Applicable only if `type=PRODUCT_PROPERTY`. values: type: array items: $ref: "#/components/schemas/GetGlobalAttributesResponseDataAttributeValue" description: A list of selectable values for the attribute. is_multiple_selection: type: boolean description: A flag to indicate if multiple values can be provided for the attribute when creating or editing a product. is_customizable: type: boolean description: A flag to indicate if the attribute value can be customized by sellers when creating or editing a product. requirement_conditions: type: array items: $ref: "#/components/schemas/GetGlobalAttributesResponseDataAttributeRequirementCondition" description: |- A list of market-specific conditions that determine whether the product attribute is required based on the seller's inputs for other attributes. If any condition for a market is met, the attribute is required in that market; otherwise, it is optional in that market. This field is omitted when no conditions apply. For example, a condition can state that the "Battery type" attribute is required if the seller selects the value "Batteries" for the attribute "Contains Batteries or Cells?". For more scenario-based guidance on using this parameter, refer to the [Solution Guide](https://partner.tiktokshop.com/openlearn/guide/usecase?parent_id=7256668359046153985). Applicable only if `type=PRODUCT_PROPERTY` and `optional_regions` is not empty. optional_regions: type: array items: type: string enum: - AT - BE - CZ - DE - ES - FR - GB - GR - HU - ID - IT - IE - JP - MY - NL - PH - PL - PT - SG - TH - US - VN - MX x-enum-descriptions: - Austria - Belgium - Czech Republic - Germany - Spain - France - United Kingdom - Greece - Hungary - Indonesia - Italy - Ireland - Japan - Malaysia - Netherlands - Philippines - Poland - Portugal - Singapore - Thailand - United States - Vietnam - Mexico description: |- The markets where the attribute is purely optional, or required only under certain conditions. Refer to `requirement_conditions` for details on markets with conditional requirements. This field is omitted when there are no optional markets. Possible values: - AT: Austria - BE: Belgium - CZ: Czech Republic - DE: Germany - ES: Spain - FR: France - GB: United Kingdom - GR: Greece - HU: Hungary - ID: Indonesia - IT: Italy - IE: Ireland - JP: Japan - MY: Malaysia - NL: Netherlands - PH: Philippines - PL: Poland - PT: Portugal - SG: Singapore - TH: Thailand - US: United States - VN: Vietnam - MX: Mexico Applicable only if `is_requried=false`. required_regions: type: array items: type: string enum: - AT - BE - CZ - DE - ES - FR - GB - GR - HU - ID - IT - IE - JP - MY - NL - PH - PL - PT - SG - TH - US - VN - MX x-enum-descriptions: - Austria - Belgium - Czech Republic - Germany - Spain - France - United Kingdom - Greece - Hungary - Indonesia - Italy - Ireland - Japan - Malaysia - Netherlands - Philippines - Poland - Portugal - Singapore - Thailand - United States - Vietnam - Mexico description: |- The markets where the attribute is required without conditions. When `is_requried=true`, this list contains all of the seller's markets. When `is_requried=false`, it contains only the markets where the attribute is unconditionally required. This field is omitted when there are no unconditionally required markets. Possible values: - AT: Austria - BE: Belgium - CZ: Czech Republic - DE: Germany - ES: Spain - FR: France - GB: United Kingdom - GR: Greece - HU: Hungary - ID: Indonesia - IT: Italy - IE: Ireland - JP: Japan - MY: Malaysia - NL: Netherlands - PH: Philippines - PL: Poland - PT: Portugal - SG: Singapore - TH: Thailand - US: United States - VN: Vietnam - MX: Mexico GetGlobalAttributesResponseDataAttributeRequirementCondition: type: object properties: region: type: string enum: - AT - BE - CZ - DE - ES - FR - GB - GR - HU - ID - IT - IE - JP - MY - NL - PH - PL - PT - SG - TH - US - VN - MX x-enum-descriptions: - Austria - Belgium - Czech Republic - Germany - Spain - France - United Kingdom - Greece - Hungary - Indonesia - Italy - Ireland - Japan - Malaysia - Netherlands - Philippines - Poland - Portugal - Singapore - Thailand - United States - Vietnam - Mexico description: |- The market where the attribute is required when the conditions are met. Possible values: - AT: Austria - BE: Belgium - CZ: Czech Republic - DE: Germany - ES: Spain - FR: France - GB: United Kingdom - GR: Greece - HU: Hungary - ID: Indonesia - IT: Italy - IE: Ireland - JP: Japan - MY: Malaysia - NL: Netherlands - PH: Philippines - PL: Poland - PT: Portugal - SG: Singapore - TH: Thailand - US: United States - VN: Vietnam - MX: Mexico condition_type: type: string enum: - VALUE_ID_MATCH x-enum-descriptions: - The condition is true when the seller selects a value whose ID matches the one specified in this condition. description: |- The type of condition. Possible values: - VALUE_ID_MATCH: The condition is true when the seller selects a value whose ID matches the one specified in this condition. attribute_id: type: string description: The ID of the product attribute that is being evaluated by the condition. attribute_value_id: type: string description: The ID of the product attribute value that must match the seller's input for the condition to be true. GetGlobalAttributesResponseDataAttributeValue: type: object properties: id: type: string description: The ID of the built-in attribute value. name: type: string description: The name of the built-in attribute value. GetGlobalCategoriesResponse: 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/GetGlobalCategoriesResponseData" GetGlobalCategoriesResponseData: type: object properties: categories: type: array items: $ref: "#/components/schemas/GetGlobalCategoriesResponseDataCategory" description: The list of categories that meet the query conditions. GetGlobalCategoriesResponseDataCategory: type: object properties: id: type: string description: The category ID. parent_id: type: string description: |- The parent category ID. For the root category, the parent ID is `0`. local_name: type: string description: The name of the category. is_leaf: type: boolean description: |- A flag to indicate if the category is a leaf category. **Note**: You can only create or edit products that belong to a leaf category. permission_statuses: type: array items: type: string enum: - AVAILABLE - NON_MAIN_CATEGORY x-enum-descriptions: - You have the permission to create products in this category. - This category is out of scope for this seller, and you do not have permission to use it. Contact your account manager for assistance. description: |- The shop's permission status for this category. Possible values: - AVAILABLE: You have the permission to create products in this category. - NON_MAIN_CATEGORY: This category is out of scope for this seller, and you do not have permission to use it. Contact your account manager for assistance. GetGlobalCategoryRulesResponse: 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/GetGlobalCategoryRulesResponseData" GetGlobalCategoryRulesResponseData: type: object properties: product_certifications: type: array items: $ref: "#/components/schemas/GetGlobalCategoryRulesResponseDataProductCertification" description: |- Certification related rules. As per TikTok Shop guidelines, certifications are required for certain restricted product categories. Refer to [TikTok Shop Restricted Products Policy](https://seller-us.tiktok.com/university/essay?identity=1&role=1&knowledge_id=3238037484275457&from=policy) for information on product category restrictions. If this is empty, it means certifications are not required for this category. size_chart: $ref: "#/components/schemas/GetGlobalCategoryRulesResponseDataSizeChart" description: Size chart related rules. responsible_person: $ref: "#/components/schemas/GetGlobalCategoryRulesResponseDataResponsiblePerson" description: |- Responsible person rules. If this is empty, it means a responsible person is not required for this category. Applicable only for EU markets. manufacturer: $ref: "#/components/schemas/GetGlobalCategoryRulesResponseDataManufacturer" description: |- Manufacturer rules. If this is empty, it means a manufacturer is not required for this category. Applicable only for EU markets. GetGlobalCategoryRulesResponseDataManufacturer: type: object properties: is_required: type: boolean description: |- A flag to indicate whether the manufacturer is required for **all EU markets**. - true: The manufacturer is required in all EU markets. - false: The manufacturer is required only in some EU markets. Refer to `required_regions` and `optional_regions` for details. optional_regions: type: array items: type: string enum: - DE - ES - FR - IT - IE x-enum-descriptions: - Germany - Spain - France - Italy - Ireland description: |- The markets where the manufacturer is optional. Possible values: - DE: Germany - ES: Spain - FR: France - IT: Italy - IE: Ireland required_regions: type: array items: type: string enum: - AT - BE - CZ - DE - ES - FR - GR - HU - IE - IT - NL - PL - PT x-enum-descriptions: - Austria - Belgium - Czechia - Germany - Spain - France - Greece - Hungary - Ireland - Italy - Netherlands - Poland - Portugal description: |- The markets where the manufacturer is required. Possible values: - AT: Austria - BE: Belgium - CZ: Czechia - DE: Germany - ES: Spain - FR: France - GR: Greece - HU: Hungary - IE: Ireland - IT: Italy - NL: Netherlands - PL: Poland - PT: Portugal GetGlobalCategoryRulesResponseDataProductCertification: type: object properties: id: type: string description: The ID to identify the type of certification required. name: type: string description: The name of the certification type. is_required: type: boolean description: |- A flag to indicate if the certification is required **globally**. - true: The certification is required in all regions. - false: The certification is required only in some regions, or if certain conditions are met. Refer to `required_regions` and `requirement_conditions` for the specific requirements. sample_image_url: type: string description: The URL to view an image of the sample certification document. required_regions: type: array items: type: string enum: - DE - ES - FR - GB - ID - IT - IE - JP - MY - PH - SG - TH - US - VN - MX x-enum-descriptions: - Germany - Spain - France - United Kingdom - Indonesia - Italy - Ireland - Japan - Malaysia - Philippines - Singapore - Thailand - United States - Vietnam - Mexico description: |- The markets where the certification is required, without conditions. Possible values: - DE: Germany - ES: Spain - FR: France - GB: United Kingdom - ID: Indonesia - IT: Italy - IE: Ireland - JP: Japan - MY: Malaysia - PH: Philippines - SG: Singapore - TH: Thailand - US: United States - VN: Vietnam - MX: Mexico Applicable only if `is_required=false`. optional_regions: type: array items: type: string enum: - AT - BE - CZ - DE - ES - FR - GB - GR - HU - ID - IE - IT - JP - MX - MY - NL - PH - PL - PT - SG - TH - US - VN x-enum-descriptions: - Austria - Belgium - Czechia - Germany - Spain - France - United Kingdom - Greece - Hungary - Indonesia - Ireland - Italy - Japan - Mexico - Malaysia - Netherlands - Philippines - Poland - Portugal - Singapore - Thailand - United States - Vietnam description: |- The markets where the certification is purely optional, or required only under certain conditions. Refer to `requirement_conditions` for details on markets with conditional requirements. Possible values: - AT: Austria - BE: Belgium - CZ: Czechia - DE: Germany - ES: Spain - FR: France - GB: United Kingdom - GR: Greece - HU: Hungary - ID: Indonesia - IE: Ireland - IT: Italy - JP: Japan - MX: Mexico - MY: Malaysia - NL: Netherlands - PH: Philippines - PL: Poland - PT: Portugal - SG: Singapore - TH: Thailand - US: United States - VN: Vietnam Applicable only if `is_required=false`. requirement_conditions: type: array items: $ref: "#/components/schemas/GetGlobalCategoryRulesResponseDataProductCertificationRequirementCondition" description: |- A list of conditions that determine if the certification is required in a market based on the seller's inputs for a product attribute. If any of the conditions is met, the certification is required; otherwise, it is optional. For example, there's a condition that states that the "Safety Data Sheet (SDS) for flammable materials" certification is required if the seller selects the value "Yes" for the attribute "Flammable Liquid?". For more scenario-based guidance on using this parameter, refer to the [Solution Guide](https://partner.tiktokshop.com/openlearn/guide/usecase?parent_id=7256668359046153985). Applicable only if `optional_regions` is not empty. GetGlobalCategoryRulesResponseDataProductCertificationRequirementCondition: type: object properties: region: type: string enum: - AT - BE - CZ - DE - ES - FR - GB - GR - HU - ID - IE - IT - JP - MX - MY - NL - PH - PL - PT - SG - TH - US - VN x-enum-descriptions: - Austria - Belgium - Czechia - Germany - Spain - France - United Kingdom - Greece - Hungary - Indonesia - Ireland - Italy - Japan - Mexico - Malaysia - Netherlands - Philippines - Poland - Portugal - Singapore - Thailand - United States - Vietnam description: |- The market where the certification is required when the conditions are met. Possible values: - AT: Austria - BE: Belgium - CZ: Czechia - DE: Germany - ES: Spain - FR: France - GB: United Kingdom - GR: Greece - HU: Hungary - ID: Indonesia - IE: Ireland - IT: Italy - JP: Japan - MX: Mexico - MY: Malaysia - NL: Netherlands - PH: Philippines - PL: Poland - PT: Portugal - SG: Singapore - TH: Thailand - US: United States - VN: Vietnam condition_type: type: string enum: - VALUE_ID_MATCH x-enum-descriptions: - The condition is true when the seller selects a value whose ID matches the one specified in this condition. description: |- The type of condition. Possible values: - VALUE_ID_MATCH: The condition is true when the seller selects a value whose ID matches the one specified in this condition. attribute_id: type: string description: The ID of the product attribute that is being evaluated by the condition. attribute_value_id: type: string description: The ID of the product attribute value that must match the seller's input for the condition to be true. GetGlobalCategoryRulesResponseDataResponsiblePerson: type: object properties: is_required: type: boolean description: |- A flag to indicate whether the responsible person is required for **all EU markets**. - true: The manufacturer is required in all EU markets. - false: The manufacturer is required only in some EU markets. Refer to `required_regions` and `optional_regions` for details. optional_regions: type: array items: type: string enum: - DE - ES - FR - IT - IE x-enum-descriptions: - Germany - Spain - France - Italy - Ireland description: |- The markets where the responsible person is optional. Possible values: - DE: Germany - ES: Spain - FR: France - IT: Italy - IE: Ireland required_regions: type: array items: type: string enum: - AT - BE - CZ - DE - ES - FR - GR - HU - IE - IT - NL - PL - PT x-enum-descriptions: - Austria - Belgium - Czechia - Germany - Spain - France - Greece - Hungary - Ireland - Italy - Netherlands - Poland - Portugal description: |- The markets where the responsible person is required. Possible values: - AT: Austria - BE: Belgium - CZ: Czechia - DE: Germany - ES: Spain - FR: France - GR: Greece - HU: Hungary - IE: Ireland - IT: Italy - NL: Netherlands - PL: Poland - PT: Portugal GetGlobalCategoryRulesResponseDataSizeChart: type: object properties: is_supported: type: boolean description: |- A flag to indicate whether size charts are supported. **Note**: If size charts are not supported, even if you provide a size chart when creating or editing a product, the size chart will not be saved. is_required: type: boolean description: A flag to indicate whether a size chart is required. GetGlobalListingRulesResponse: 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/GetGlobalListingRulesResponseData" GetGlobalListingRulesResponseData: type: object properties: listing_methods: type: array items: type: string enum: - GLOBAL_PUBLISHING - LOCAL_REPLICATION x-enum-descriptions: - Create a global product, then publish it to target local markets. - Create local product, then replicate it to other target local markets. description: |- The methods at which sellers can list products in this shop. Possible values: - GLOBAL_PUBLISHING: Create a global product, then publish it to target local markets. - LOCAL_REPLICATION: Create local product, then replicate it to other target local markets. inventory_rules: type: array items: $ref: "#/components/schemas/GetGlobalListingRulesResponseDataInventoryRule" description: A list of inventory allocation rules for all warehouses linked to the shop. GetGlobalListingRulesResponseDataInventoryRule: type: object properties: local_warehouse_id: type: string description: The warehouse ID associated with the shop. allocation_mode: type: string description: |- The inventory allocation mode used for this warehouse in the local market. `SHARED` – Inventory is pooled across all covered markets. An inventory deduction in one market reflects across all. `DYNAMIC` – Inventory is divided proportionally among covered markets. An inventory deduction in one market affects only that market. `MANUAL` – Inventory is configured independently by sellers for each market. An inventory deduction in one market affects only that market. associated_warehouses: type: array items: $ref: "#/components/schemas/GetGlobalListingRulesResponseDataInventoryRuleAssociatedWarehouse" description: |- A list of associated warehouses whose inventory is shared with or dynamically allocated from this warehouse. Each item identifies a warehouse and its region. **Note**: Applicable only when `allocation_mode` is `SHARED` or `DYNAMIC`. GetGlobalListingRulesResponseDataInventoryRuleAssociatedWarehouse: type: object properties: warehouse_id: type: string description: The associated warehouse ID. region: type: string description: The country where the warehouse is located. GetGlobalProductPermissionResponse: 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/GetGlobalProductPermissionResponseData" GetGlobalProductPermissionResponseData: type: object properties: permissions: type: array items: type: string enum: - MANAGE_GLOBAL_PRODUCT x-enum-descriptions: - Indicates the seller is permitted to manage global products listed in TikTok Shops across multiple countries. description: |- The seller's global product permissions. Possible values: - MANAGE_GLOBAL_PRODUCT: Indicates the seller is permitted to manage global products listed in TikTok Shops across multiple countries. An empty array means the seller does not have the MANAGE_GLOBAL_PRODUCT permission. GetGlobalProductResponse: 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/GetGlobalProductResponseData" GetGlobalProductResponseData: type: object properties: id: type: string description: The global product ID in TikTok Shop. title: type: string description: The product title. main_images: type: array items: $ref: "#/components/schemas/GetGlobalProductResponseDataMainImage" description: A list of images to display in the product image gallery. video: $ref: "#/components/schemas/GetGlobalProductResponseDataVideo" description: Product video information. description: type: string description: The product description in HTML format. package_dimensions: $ref: "#/components/schemas/GetGlobalProductResponseDataPackageDimension" description: The dimensions of the product package. package_weight: $ref: "#/components/schemas/GetGlobalProductResponseDataPackageWeight" description: The weight of the product package. certifications: type: array items: $ref: "#/components/schemas/GetGlobalProductResponseDataCertification" description: The list of certifications for your product. skus: type: array items: $ref: "#/components/schemas/GetGlobalProductResponseDataSku" description: A list of global Stock Keeping Units (SKUs) used to identify distinct variants of the product. update_time: type: integer format: int64 description: |- The time when the product is last updated. Unix timestamp in seconds. create_time: type: integer format: int64 description: |- The time when the product is created. Unix timestamp in seconds. product_attributes: type: array items: $ref: "#/components/schemas/GetGlobalProductResponseDataProductAttribute" description: A list of general attributes (e.g. manufacturer, country of origin, materials used) that describe the product as a whole, regardless of variant. size_chart: $ref: "#/components/schemas/GetGlobalProductResponseDataSizeChart" description: The measurement details of the product to help buyers find the right size. products: type: array items: $ref: "#/components/schemas/GetGlobalProductResponseDataProduct" description: The local products associated through global product publishing or manual binding. global_seller_id: type: string description: The cross-border seller ID. brand: $ref: "#/components/schemas/GetGlobalProductResponseDataBrand" description: Product brand information. category: $ref: "#/components/schemas/Category" description: The category of the product. manufacturer: $ref: "#/components/schemas/Manufacturer" description: |- (**Deprecated**: This field is deprecated and will be removed in a future API version. Use `manufacturer_ids` instead.) The product manufacturer's details. If there are more than one manufacturer information, only the first-added manufacturer will be returned in this field. deprecated: true responsible_person_ids: type: array items: type: string description: |- A list of responsible person IDs. Retrieve the IDs from the [Search Responsible Persons API](67066a55f17b7d02f95d2fb1). **Note**: Applicable only for the EU market in certain categories. manufacturer_ids: type: array items: type: string description: |- A list of manufacturer IDs. Retrieve the IDs from the [Search Manufacturers API](67066a580dcee902fa03ccf9). **Note**: Applicable only for the EU market in certain categories. source_locale: 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 description: |- The BCP-47 locale codes for displaying category information. Default: The default locale of your shop. Possible values: - 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 external_global_product_id: type: string description: An external identifier used in an external ecommerce platform. This is used to associate the product between TikTok Shop and the external ecommerce platform. GetGlobalProductResponseDataBrand: type: object properties: id: type: string description: The ID of the brand of this product. GetGlobalProductResponseDataCertification: type: object properties: id: type: string description: The ID to identify the type of certification required for the product category. title: type: string description: The title of the certification type. files: type: array items: $ref: "#/components/schemas/GetGlobalProductResponseDataCertificationFile" description: A list of certification related files. images: type: array items: $ref: "#/components/schemas/GetGlobalProductResponseDataCertificationImage" description: A list of certification related images. GetGlobalProductResponseDataCertificationFile: type: object properties: id: type: string description: The ID of the certification file. urls: type: array items: type: string description: The URLs to view the certification files. name: type: string description: The name of the certification file format: type: string description: The format of the certification file. GetGlobalProductResponseDataCertificationImage: type: object properties: height: type: integer format: int64 description: |- The image height. Unit: px width: type: integer format: int64 description: |- The image width. Unit: px uri: type: string description: The URI of the image. GetGlobalProductResponseDataMainImage: type: object properties: height: type: integer format: int64 description: |- The image height. Unit: px width: type: integer format: int64 description: |- The image width. Unit: px uri: type: string description: The URI of the image. GetGlobalProductResponseDataPackageDimension: type: object properties: length: type: string description: The package length. width: type: string description: The package width. height: type: string description: The package height. unit: type: string description: The unit for the package dimensions. GetGlobalProductResponseDataPackageWeight: type: object properties: value: type: string description: The package weight. unit: type: string description: The unit for the package weight. GetGlobalProductResponseDataProduct: type: object properties: region: type: string description: The market where the local product is listed. id: type: string description: The local product ID. sku_mappings: type: array items: $ref: "#/components/schemas/GetGlobalProductResponseDataProductSkuMapping" description: The list of sku mappings between the global and local products. GetGlobalProductResponseDataProductAttribute: type: object properties: id: type: string description: The ID of the product attribute. name: type: string description: The product attribute name. values: type: array items: $ref: "#/components/schemas/GetGlobalAttributesResponseDataAttributeValue" description: A list of selectable values for the product attribute. GetGlobalProductResponseDataProductSkuMapping: type: object properties: global_sku_id: type: string description: The global SKU ID in TikTok Shop. local_sku_id: type: string description: The local SKU ID in TikTok Shop. sales_attribute_mappings: type: array items: $ref: "#/components/schemas/GetGlobalProductResponseDataProductSkuMappingSalesAttributeMapping" description: The list of sales attribute mappings between the global and local SKUs. GetGlobalProductResponseDataProductSkuMappingSalesAttributeMapping: type: object properties: global_attribute_id: type: string description: The global sales attribute ID. local_attribute_id: type: string description: The local sales attribute ID. global_value_id: type: string description: The global sales attribute value ID. local_value_id: type: string description: The local sales attribute value ID. GetGlobalProductResponseDataSizeChart: type: object properties: image: $ref: "#/components/schemas/GetGlobalProductResponseDataCertificationImage" description: An image of the size chart. template: $ref: "#/components/schemas/DiagnoseAndOptimizeProductRequestSizeChartTemplate" description: A TikTok Shop size chart template generated by the size chart tool in Seller Center > Manage Products > Bulk action > Batch manage size charts. GetGlobalProductResponseDataSku: type: object properties: id: type: string description: The global SKU ID in TikTok Shop. seller_sku: type: string description: An internal code/name for managing SKUs, not visible to buyers. price: $ref: "#/components/schemas/GetGlobalProductResponseDataSkuPrice" description: |- The SKU's **global uniform pre-tax** price that serves as the baseline for calculating the local prices across different markets. **Note**: - Upon publishing, this price will be automatically converted to the local pre-tax price and local display price based on market-specific exchange rates and applicable charges such as shipping costs, taxes, and other fees. - The auto-conversion will exclude JP and US shops using China warehouses. global_quantity: type: integer format: int64 description: |- The total SKU inventory quantity across all shops globally. The inventory for each local shop is automatically calculated when a product is first published. After publishing, this global quantity cannot be manually changed. You can only modify the inventory quantity in each local shop. identifier_code: $ref: "#/components/schemas/IdentifierCode" description: A regulated identifier code assigned to a product based on international standardized regulations (e.g. GTIN) to ensure the product is universally identifiable across various platforms and systems. sales_attributes: type: array items: $ref: "#/components/schemas/GetGlobalProductResponseDataSkuSalesAttribute" description: A list of attributes (e.g. size, color, length) that define each variant of a product. inventory: type: array items: $ref: "#/components/schemas/GetGlobalProductResponseDataSkuInventory" description: SKU inventory information per warehouse. sku_unit_count: type: string description: |- The total quantity/volume of the product represented by the SKU. For example, if the SKU represents 500ml of water, this value would be 500 if the unit type is defined as ml. Applicable only for the EU market. **Note**: - This is mainly used to calculate the unit price of the SKU, and is required only if you wish to display the unit price to facilitate easier price comparisons across different products and packaging sizes. - Unit price = Selling price/(SKU unit count/base unit count). Therefore if you want to obtain the unit price, you would also need to define the "base unit count" and the "unit type" product attributes. Retrieve the relevant information for these product attributes by using the [Get Global Attributes API](650a0483c16ffe02b8dfc80a). extra_identifier_codes: type: array items: type: string description: |- A list of up to 10 additional identifier codes if the SKU belongs to a virtual bundle (containing multiple individual SKUs). **Note**: Applicable only for the EU market. external_global_sku_id: type: string description: An external identifier used in an external ecommerce platform. This is used to associate the SKU between TikTok Shop and the external ecommerce platform. GetGlobalProductResponseDataSkuInventory: type: object properties: global_warehouse_id: type: string description: The ID of the global warehouse where the SKU is stored. quantity: type: integer format: int64 description: The SKU quantity available in the warehouse. GetGlobalProductResponseDataSkuPrice: type: object properties: amount: type: string description: The price amount. currency: type: string enum: - USD - EUR x-enum-descriptions: - Applicable for global sellers - Applicable for intra-EU sellers description: |- The currency. Possible values: - `USD`: Applicable for global sellers - `EUR`: Applicable for intra-EU sellers unit_price: type: string description: |- The unit price of the SKU. You can display the unit price to facilitate easier price comparisons across different products and packaging sizes. Applicable only for the EU market. **Note**: - This value is available only if you have defined the elements used to calculate this price when creating the product. - Unit price = Selling price/(SKU unit count/base unit count) GetGlobalProductResponseDataSkuSalesAttribute: type: object properties: id: type: string description: The sales attribute ID. name: type: string description: The sales attribute name. value_id: type: string description: The sales attribute value ID. value_name: type: string description: The sales attribute value name. sku_img: $ref: "#/components/schemas/GetGlobalProductResponseDataSkuSalesAttributeSkuImg" description: An image to display for the SKU. GetGlobalProductResponseDataSkuSalesAttributeSkuImg: type: object properties: height: type: integer format: int64 description: |- The image height. Unit: px width: type: integer format: int64 description: |- The image width. Unit: px thumb_urls: type: array items: type: string description: The URLs to view the image thumbnails. uri: type: string description: The URI of the image. urls: type: array items: type: string description: The URLs to view the images. GetGlobalProductResponseDataVideo: type: object properties: id: type: string description: The video ID. GetGlobalReplicatedProductsResponse: 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/GetGlobalReplicatedProductsResponseData" GetGlobalReplicatedProductsResponseData: type: object properties: replicated_products: type: array items: $ref: "#/components/schemas/GetGlobalReplicatedProductsResponseDataReplicatedProduct" description: The product replicas associated with the requested product in other markets. The requested source product is excluded. Returns an empty array when no other associated replica is found. GetGlobalReplicatedProductsResponseDataReplicatedProduct: type: object properties: region: type: string enum: - AT - BE - CZ - DE - ES - FR - GB - GR - HU - ID - IE - IT - JP - MY - NL - PH - PO - PT - SG - TH - US - VN - MX x-enum-descriptions: - Austria - Belgium - Czech Republic - Germany - Spain - France - United Kingdom - Greece - Hungary - Indonesia - Ireland - Italy - Japan - Malaysia - Netherlands(NL) - Philippines - Poland - Portugal - Singapore - Thailand - United States - Vietnam - Mexico description: |- The market associated with the replicated product. Possible values: - AT: Austria - BE:Belgium - CZ:Czech Republic - DE: Germany - ES: Spain - FR: France - GB: United Kingdom - GR: Greece - HU:Hungary - ID: Indonesia - IE: Ireland - IT: Italy - JP: Japan - MY: Malaysia - NL: Netherlands(NL) - PH: Philippines - PO: Poland - PT:Portugal - SG: Singapore - TH: Thailand - US: United States - VN: Vietnam - MX: Mexico shop_id: type: string description: The TikTok Shop ID. product_id: type: string description: The ID of the product. product_status: type: string enum: - UNKNOWN - DRAFT - PENDING - FAILED - ACTIVATE - SELLER_DEACTIVATED - PLATFORM_DEACTIVATED - FREEZE - DELETED description: |- The status of the replicated product. Possible values: - UNKNOWN - DRAFT - PENDING - FAILED - ACTIVATE - SELLER_DEACTIVATED - PLATFORM_DEACTIVATED - FREEZE - DELETED GetGlobalSellerWarehousesResponse: 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/GetGlobalSellerWarehousesResponseData" GetGlobalSellerWarehousesResponseData: type: object properties: global_warehouses: type: array items: $ref: "#/components/schemas/GetGlobalSellerWarehousesResponseDataGlobalWarehouse" description: A list of global warehouses associated with the seller. GetGlobalSellerWarehousesResponseDataGlobalWarehouse: type: object properties: id: type: string description: Global warehouse ID, a unique and immutable primary key, used for all global warehouse logistics. name: type: string description: Global warehouse name. This name is not unique across the TikTok Shop system. ownership: type: string enum: - SELLER - PLATFORM_COOPERATION x-enum-descriptions: - Warehouse owned by the seller. - Warehouse owned by TikTok Shop. description: |- Possible values: - SELLER: Warehouse owned by the seller. - PLATFORM_COOPERATION: Warehouse owned by TikTok Shop. GetImageTranslationTasksResponse: 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/GetImageTranslationTasksResponseData" GetImageTranslationTasksResponseData: type: object properties: translation_tasks: type: array items: $ref: "#/components/schemas/GetImageTranslationTasksResponseDataTranslationTask" description: The requested translation tasks and the corresponding results. Each task corresponds to the translation of 1 image into 1 target language. GetImageTranslationTasksResponseDataTranslationTask: type: object properties: original_image: $ref: "#/components/schemas/GetImageTranslationTasksResponseDataTranslationTaskOriginalImage" description: The original image to be translated. id: type: string description: The ID to identify the image translation task. target_language: type: string enum: - de-DE - en-IE - es-ES - fr-FR - it-IT description: |- The target language to translate the image into. Possible values: - de-DE - en-IE - es-ES - fr-FR - it-IT status: type: string enum: - PROCESSING - COMPLETED - FAILED x-enum-descriptions: - Translation is underway and has not yet completed. - Translation has completed and results are ready. - Translation did not complete due to an error. description: |- The translation result. Possible values: - PROCESSING: Translation is underway and has not yet completed. - COMPLETED: Translation has completed and results are ready. - FAILED: Translation did not complete due to an error. fail_reason: type: string description: |- The reason why the translation task failed. Possible values: - Invalid image URI. - Internal processing error, please try calling this endpoint again. - This image can't be translated. Try a different image. translated_image: $ref: "#/components/schemas/GetImageTranslationTasksResponseDataTranslationTaskTranslatedImage" description: The translated image. GetImageTranslationTasksResponseDataTranslationTaskOriginalImage: type: object properties: uri: type: string description: The URI of the original image. url: type: string description: The URL of the original image. GetImageTranslationTasksResponseDataTranslationTaskTranslatedImage: type: object properties: uri: type: string description: The URI of the translated image. url: type: string description: The URL of the translated image. GetInboundMethodDetailRequest: type: object properties: plan_id: type: string description: Inbound plan identifier inbound_method: type: string enum: - D2FC - ONE_HUB x-enum-descriptions: - Direct to fulfillment center, may be split into multiple shipments - Single destination; can include an estimated placement fee description: |- **Possible values:** * `D2FC` (Direct to fulfillment center, may be split into multiple shipments) * `ONE_HUB` (Single destination; can include an estimated placement fee) estimate_arrival_time: $ref: "#/components/schemas/EstimateArrivalTime" description: Estimated arrival window for the selected `inbound_method`. Use the `start_timestamp` and `end_timestamp` from the same entry in the `available_time_window_list` returned by the List Available Inbound Methods API for this plan. required: - plan_id - inbound_method - estimate_arrival_time GetInboundMethodDetailResponse: 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/GetInboundMethodDetailResponseData" GetInboundMethodDetailResponseData: type: object properties: info: type: array items: $ref: "#/components/schemas/GetInboundMethodDetailResponseDataInfo" description: Placement options for the current placement task. If `placement_task_status` is `Executing`, repeat this request with the same `plan_id`, `inbound_method`, and estimated arrival window to retrieve the latest status. When the status is `Succeed`, select an option from `info` and pass its `placement_option_id` to the Confirm Inbound Method API. Do not confirm an option when the status is `Failed`. After `expiration_timestamp`, call this API again with the same selection inputs to obtain a new placement option or task. placement_task_status: type: string enum: - Executing - Succeed - Failed description: |- **Possible values:** * `Executing` * `Succeed` * `Failed` expiration_timestamp: type: string description: Unix timestamp in seconds when the placement result expires. For `ONE_HUB`, the expiration is set to 24 hours after this API processes the request. For other methods, it is 24 hours after the placement task's trigger time. After expiration, call this API again to generate a new placement task. GetInboundMethodDetailResponseDataInfo: type: object properties: allocation_shipments: type: array items: $ref: "#/components/schemas/GetInboundMethodDetailResponseDataInfoAllocationShipment" description: List of shipments for this placement option. placement_option_id: type: string description: Placement option id. A placement option represents the shipment splits and destinations. placement_fee_estimate: $ref: "#/components/schemas/GetInboundMethodDetailResponseDataInfoPlacementFeeEstimate" description: Estimated placement fee for a `ONE_HUB` placement option. GetInboundMethodDetailResponseDataInfoAllocationShipment: type: object properties: warehouse_id: type: string description: Warehouse identifier. goods_items: type: array items: $ref: "#/components/schemas/GetInboundMethodDetailResponseDataInfoAllocationShipmentGoodsItem" description: Goods item list. cartons: type: array items: $ref: "#/components/schemas/GetInboundMethodDetailResponseDataInfoAllocationShipmentCarton" description: Carton List. shipment_options: type: array items: $ref: "#/components/schemas/GetInboundMethodDetailResponseDataInfoAllocationShipmentShipmentOption" description: Shipment options. GetInboundMethodDetailResponseDataInfoAllocationShipmentCarton: type: object properties: carton_type: type: string enum: - SINGLE_SKU - MULTI_SKU description: |- Indicates if this is a single SKU carton or multi SKU carton. **Possible values:** * `SINGLE_SKU` * `MULTI_SKU` items: type: array items: $ref: "#/components/schemas/GetInboundMethodDetailResponseDataInfoAllocationShipmentCartonItem" description: Goods item list of a carton. quantity: type: integer format: int64 description: Carton quantity. carton_nums: type: array items: type: string description: Carton numbers. box_measurements: $ref: "#/components/schemas/GetFBTInboundOrderDetailsResponseDataInboundOrderCartonDetailBoxMeasurement" description: Carton measurement. GetInboundMethodDetailResponseDataInfoAllocationShipmentCartonItem: type: object properties: goods_id: type: string description: Goods identifier. quantity: type: integer format: int64 description: Quantity of this goods. lot_code: type: string description: Lot code of this goods. expiration_timestamp: type: string description: The expiration date for this item, Unix timestamp in seconds. GetInboundMethodDetailResponseDataInfoAllocationShipmentGoodsItem: type: object properties: goods_id: type: string description: Goods identifier. quantity: type: integer format: int64 description: Quantity of this goods. GetInboundMethodDetailResponseDataInfoAllocationShipmentShipmentOption: type: object properties: shipping_method: type: string description: "Shipping method for this shipment option. Possible values: SMALL_PARCEL, a parcel shipment method; FREIGHT, a freight shipment method." GetInboundMethodDetailResponseDataInfoPlacementFeeEstimate: type: object properties: amount: type: string description: Placement fee amount. currency: type: string enum: - USD - CNY - EUR - GBP - SAR description: |- The currency of the placement fee amount. **Possible values:** * `USD` * `CNY` * `EUR` * `GBP` * `SAR` GetInboxCategoryCountsResponse: 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/GetInboxCategoryCountsResponseData" GetInboxCategoryCountsResponseData: type: object properties: data: $ref: "#/components/schemas/GetInboxCategoryCountsResponseDataData" description: Conversation count data grouped by inbox category. GetInboxCategoryCountsResponseDataData: type: object properties: group_counts: type: array items: $ref: "#/components/schemas/GetInboxCategoryCountsResponseDataDataGroupCount" description: Conversation counts for each inbox category. GetInboxCategoryCountsResponseDataDataGroupCount: type: object properties: group_type: type: string description: |- Group type name, e.g. - UNREAD -UNREPLIED -STARRED -ARCHIVED count: type: integer format: int64 description: Conversation count in this group GetLatestUnreadMessagesResponse: 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/GetLatestUnreadMessagesResponseData" GetLatestUnreadMessagesResponseData: type: object properties: newest_message_list: type: array items: $ref: "#/components/schemas/GetLatestUnreadMessagesResponseDataNewestMessageList" description: The list of unread messages from the last minute. GetLatestUnreadMessagesResponseDataNewestMessageList: type: object properties: conversation_id: type: string description: The converastion id to which the message belongs content: type: string description: |- Message content as a JSON-serialized string. Parse the string as a JSON object; its shape depends on `type`: - `TEXT`: `{"content": "simple text"}` - `PRODUCT_CARD`: `{"product_id": "12345"}` - `TARGET_COLLABORATION_CARD`: `{"invitation_group_id": "1234"}` - `FREE_SAMPLE_CARD`: `{"apply_id": "1234"}` - `IMAGE`: `{"height": "290", "url": "", "width": "304"}` - `CRM_TEXT_WITH_IMAGE_CARD`: `{"title": "abc", "content": "efg", "url": ""}` - `CRM_TEXT_WITH_PRODUCTS_CARD`: `{"title": "abc", "content": "efg", "product_ids": [123, 456, 789, 222]}` - `NOTIFICATION` or `SYSTEM`: `{"content": "notification or system message"}` - `EMOTICONS`: `{"height": "110", "url": "", "width": "110"}` type: type: string enum: - TEXT - PRODUCT_CARD - TARGET_COLLABORATION_CARD - FREE_SAMPLE_CARD - IMAGE - CRM_TEXT_WITH_IMAGE_CARD - CRM_TEXT_WITH_PRODUCTS_CARD - NOTIFICATION - EMOTICONS - SYSTEM description: |- Message type. Possible values: - TEXT - PRODUCT_CARD - TARGET_COLLABORATION_CARD - FREE_SAMPLE_CARD - IMAGE - CRM_TEXT_WITH_IMAGE_CARD - CRM_TEXT_WITH_PRODUCTS_CARD - NOTIFICATION - EMOTICONS - SYSTEM sender_id: type: string description: sender's IM id unread_message_count: type: integer format: int64 description: The number of unread messages of the sender in the conversation. GetLiveRoomCoreStatsResponse: 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/GetLiveRoomCoreStatsResponseData" GetLiveRoomCoreStatsResponseData: type: object properties: stats: $ref: "#/components/schemas/GetLiveRoomCoreStatsResponseDataStat" description: The stats of the live room GetLiveRoomCoreStatsResponseDataStat: type: object properties: sales: type: integer format: int64 description: The number of product units sold from the livestream local_gmv: $ref: "#/components/schemas/LocalGmv" description: The gross merchandise value (GMV) generated from the livestream, expressed in the local currency. created_order_count: type: integer format: int64 description: The number of SKU orders created by users from the livestream current_visitor_count: type: integer format: int64 description: The number of viewers currently watching the livestream. paid_order_count: type: integer format: int64 description: The number of SKU orders created and paid by users from the livestream local_unit_price: $ref: "#/components/schemas/LocalUnitPrice" description: The average price of the units sold product_reach_count: type: integer format: int64 description: The number of product clicks from the livestream, including product list and product card clicks watch_pv: type: integer format: int64 description: The number of views of the livestream click_through_rate: type: string description: Click through rate，product clicks / views accumulated_new_follower_count: type: integer format: int64 description: The number of times users clicked to follow the creator buyer_count: type: integer format: int64 description: The number of unique users who paid for orders made from livestream, including returned/refunded orders accumulated_comment_count: type: integer format: int64 description: The cumulative number of times users left comments on the livestream product_view_count: type: integer format: int64 description: The number of impressions of all livestream products, including product list and product card impressions click_order_rate: type: string description: Click to order，paid sku orders/ product clicks avg_watching_duration: type: integer format: int64 description: The average length of time each unique viewer watches the livestream. accumulated_sharing_count: type: integer format: int64 description: The cumulative number of times users shared the livestream peak_concurrent_user_count: type: integer format: int64 description: The peak number of concurrent viewers of the livestream GetLiveRoomGMVAndOrderTrendsResponse: 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/GetLiveRoomGMVAndOrderTrendsResponseData" GetLiveRoomGMVAndOrderTrendsResponseData: type: object properties: gmv_trend_performances: type: array items: $ref: "#/components/schemas/GetLiveRoomGMVAndOrderTrendsResponseDataGmvTrendPerformance" description: GMV and created-order trend series for the live room. Each item identifies one metric through `stats_type`. GetLiveRoomGMVAndOrderTrendsResponseDataGmvTrendPerformance: type: object properties: stats_type: type: string description: "The stats_type describes the type of trend value. Possible values: TREND_GMV (GMV of the live streaming room), TREND_CREATED_ORDER (created orders in the live streaming room)." data_points: type: array items: $ref: "#/components/schemas/GetLiveRoomGMVAndOrderTrendsResponseDataGmvTrendPerformanceDataPoint" description: Data points for the metric identified by `stats_type`. GetLiveRoomGMVAndOrderTrendsResponseDataGmvTrendPerformanceDataPoint: type: object properties: order_count: type: integer format: int64 description: Number of created orders for this data point. Returned when `stats_type` is `TREND_CREATED_ORDER`. timestamp: type: integer format: int64 description: timestamp gmv: $ref: "#/components/schemas/GetLiveRoomGMVAndOrderTrendsResponseDataGmvTrendPerformanceDataPointGmv" description: GMV for this data point. Returned when `stats_type` is `TREND_GMV`. GetLiveRoomGMVAndOrderTrendsResponseDataGmvTrendPerformanceDataPointGmv: type: object properties: currency: type: string description: The ISO 4217 currency code for the GMV amount. amount: type: string description: The amount of GMV GetLiveRoomInteractiveTrendsResponse: 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/GetLiveRoomInteractiveTrendsResponseData" GetLiveRoomInteractiveTrendsResponseData: type: object properties: interactive_trend_performances: type: array items: $ref: "#/components/schemas/GetLiveRoomInteractiveTrendsResponseDataInteractiveTrendPerformance" description: The trend data of living room GetLiveRoomInteractiveTrendsResponseDataInteractiveTrendPerformance: type: object properties: stats_type: type: string enum: - TREND_WATCH_PV - TREND_COMMENT_PV - TREND_SHARE_PV x-enum-descriptions: - Watch count for the live room. - Comment count for the live room. - Share count for the live room. description: |- The type of interactive trend metric. Possible values: - `TREND_WATCH_PV`: Watch count for the live room. - `TREND_COMMENT_PV`: Comment count for the live room. - `TREND_SHARE_PV`: Share count for the live room. data_points: type: array items: $ref: "#/components/schemas/DataPoint" description: The data point of interactive trend GetLiveRoomProductStatsResponse: 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/GetLiveRoomProductStatsResponseData" GetLiveRoomProductStatsResponseData: type: object properties: product_stats: type: array items: $ref: "#/components/schemas/GetLiveRoomProductStatsResponseDataProductStat" description: Statistics for each product in the specified live room. GetLiveRoomProductStatsResponseDataProductStat: type: object properties: main_image_url: type: string description: The main image of product URL product_id: type: string description: Unique ID for each product is_live: type: boolean description: If the item is currently on sale in the livestream room click_through_rate: type: string description: The ratio of product clicks to product impressions sellable_region: type: string description: The region where products sells created_order_count: type: integer format: int64 description: The number of orders created for this product by users from the livestream exposure_count: type: integer format: int64 description: The number of impressions of this product, including in the product list and product cards total_click_count: type: integer format: int64 description: The total number of times the product was clicked from this livestream, including from the product list and product card local_gmv: $ref: "#/components/schemas/LocalGmv" description: The revenue of products using local currency product_name: type: string description: The display name of the product in the live room product stats list. local_unit_price: $ref: "#/components/schemas/LocalUnitPrice" description: The average price of the units sold using local currency paid_order_count: type: integer format: int64 description: The number of SKU orders created and paid by users for this product from the livestream room inventory_left_count: type: integer format: int64 description: The remaining inventory of the product inventory_consumption_count: type: integer format: int64 description: The number of product units sold created_order_user_count: type: integer format: int64 description: Number of unique users who created orders for this product paid_user_count: type: integer format: int64 description: Number of unique users who paid orders for this product click_order_rate: type: string description: Product paid SKU orders/Product clicks GetLiveRoomTrafficPerformanceResponse: 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/GetLiveRoomTrafficPerformanceResponseData" GetLiveRoomTrafficPerformanceResponseData: type: object properties: traffic_performances: type: array items: $ref: "#/components/schemas/GetLiveRoomTrafficPerformanceResponseDataTrafficPerformance" description: Traffic performance grouped by primary traffic source, including any available sub-source breakdowns. GetLiveRoomTrafficPerformanceResponseDataTrafficPerformance: type: object properties: source: $ref: "#/components/schemas/GetLiveRoomTrafficPerformanceResponseDataTrafficPerformanceSource" description: The source of traffic performances within the live room sub_sources: type: array items: $ref: "#/components/schemas/GetLiveRoomTrafficPerformanceResponseDataTrafficPerformanceSubSource" description: Traffic sub-sources associated with the primary traffic source, when available. GetLiveRoomTrafficPerformanceResponseDataTrafficPerformanceSource: type: object properties: name: type: string description: The name of the live source watch_pv: type: integer format: int64 description: The live room watch count attributed to the primary traffic source. GetLiveRoomTrafficPerformanceResponseDataTrafficPerformanceSubSource: type: object properties: name: type: string description: The name of the live sub source watch_pv: type: integer format: int64 description: The live room watch count attributed to the traffic sub-source. GetLiveRoomUserPortraitsResponse: 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/GetLiveRoomUserPortraitsResponseData" GetLiveRoomUserPortraitsResponseData: type: object properties: all_ads_gender_indicators: type: array items: $ref: "#/components/schemas/GetLiveRoomUserPortraitsResponseDataAllAdsGenderIndicator" description: Gender indicators for advertisement all_fan_indicators: type: array items: $ref: "#/components/schemas/GetLiveRoomUserPortraitsResponseDataAllFanIndicator" description: Fans indicators all_ads_age_indicators: type: array items: $ref: "#/components/schemas/GetLiveRoomUserPortraitsResponseDataAllAdsAgeIndicator" description: Age indicators for advertisement region_indicators: type: array items: $ref: "#/components/schemas/GetLiveRoomUserPortraitsResponseDataRegionIndicator" description: Country-level user portrait indicators for the live room. paid_ads_age_indicators: type: array items: $ref: "#/components/schemas/GetLiveRoomUserPortraitsResponseDataPaidAdsAgeIndicator" description: Paid advertisement age indicators for advertisement paid_ads_gender_indicators: type: array items: $ref: "#/components/schemas/GetLiveRoomUserPortraitsResponseDataPaidAdsGenderIndicator" description: Paid advertisement gender indicators for advertisement paid_fan_indicators: type: array items: $ref: "#/components/schemas/GetLiveRoomUserPortraitsResponseDataPaidFanIndicator" description: Paid fans indicators GetLiveRoomUserPortraitsResponseDataAllAdsAgeIndicator: type: object properties: type: type: string description: |- The type of age indicator. USER_PORTRAIT_AGE_LESS_THAN_15: Users whose age is less than 15. USER_PORTRAIT_AGE_MORE_THAN_34: Users whose age is more than 34. USER_PORTRAIT_AGE_MORE_THAN_55: Users whose age is more than 55. USER_PORTRAIT_AGE_13_TO_17: Users whose age is between 13 and 17. USER_PORTRAIT_AGE_15_TO_17: Users whose age is between 15 and 17. USER_PORTRAIT_AGE_18_TO_24: Users whose age is between 18 and 24. USER_PORTRAIT_AGE_25_TO_34: Users whose age is between 25 and 34. USER_PORTRAIT_AGE_35_TO_44: Users whose age is between 35 and 44. USER_PORTRAIT_AGE_45_TO_54: Users whose age is between 45 and 54. value: type: string description: The count for the corresponding age indicator. GetLiveRoomUserPortraitsResponseDataAllAdsGenderIndicator: type: object properties: type: type: string enum: - USER_PORTRAIT_GENDER_UNKNOWN - USER_PORTRAIT_GENDER_M - USER_PORTRAIT_GENDER_F x-enum-descriptions: - Unknown gender. - Male. - Female. description: |- The gender category represented by this indicator. Possible values: - USER_PORTRAIT_GENDER_UNKNOWN: Unknown gender. - USER_PORTRAIT_GENDER_M: Male. - USER_PORTRAIT_GENDER_F: Female. value: type: string description: The count for the corresponding gender indicator. GetLiveRoomUserPortraitsResponseDataAllFanIndicator: type: object properties: type: type: string description: |- The stats_type describes the type of value below. USER_PORTRAIT_FOLLOWER: The user portrait of the follower USER_PORTRAIT_NON_FOLLOWER: The user portrait of the non follower value: type: string description: The count for the corresponding follower-status indicator. GetLiveRoomUserPortraitsResponseDataPaidAdsAgeIndicator: type: object properties: type: type: string description: |- The type of paid advertisement age indicator. USER_PORTRAIT_AGE_LESS_THAN_15: Users whose age is less than 15. USER_PORTRAIT_AGE_MORE_THAN_34: Users whose age is more than 34. USER_PORTRAIT_AGE_MORE_THAN_55: Users whose age is more than 55. USER_PORTRAIT_AGE_13_TO_17: Users whose age is between 13 and 17. USER_PORTRAIT_AGE_15_TO_17: Users whose age is between 15 and 17. USER_PORTRAIT_AGE_18_TO_24: Users whose age is between 18 and 24. USER_PORTRAIT_AGE_25_TO_34: Users whose age is between 25 and 34. USER_PORTRAIT_AGE_35_TO_44: Users whose age is between 35 and 44. USER_PORTRAIT_AGE_45_TO_54: Users whose age is between 45 and 54. value: type: string description: The count for the corresponding paid-advertising age indicator. GetLiveRoomUserPortraitsResponseDataPaidAdsGenderIndicator: type: object properties: type: type: string enum: - USER_PORTRAIT_GENDER_UNKNOWN - USER_PORTRAIT_GENDER_M - USER_PORTRAIT_GENDER_F x-enum-descriptions: - Unknown gender. - Male. - Female. description: |- The gender category represented by this indicator. Possible values: - USER_PORTRAIT_GENDER_UNKNOWN: Unknown gender. - USER_PORTRAIT_GENDER_M: Male. - USER_PORTRAIT_GENDER_F: Female. value: type: string description: The count for the corresponding paid-advertising gender indicator. GetLiveRoomUserPortraitsResponseDataPaidFanIndicator: type: object properties: type: type: string description: |- The stats_type describes the type of value below. USER_PORTRAIT_FOLLOWER: The user portrait of the follower USER_PORTRAIT_NON_FOLLOWER: The user portrait of the non follower value: type: string description: The count for the corresponding paid follower-status indicator. GetLiveRoomUserPortraitsResponseDataRegionIndicator: type: object properties: value: type: string description: The share for the corresponding indicator, scaled by 10,000. Divide by 10,000 to obtain the underlying proportion. type: type: string description: The country of indicators GetLiveRoomViewTrendsResponse: 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/GetLiveRoomViewTrendsResponseData" GetLiveRoomViewTrendsResponseData: type: object properties: view_trend_performances: type: array items: $ref: "#/components/schemas/GetLiveRoomViewTrendsResponseDataViewTrendPerformance" description: Viewer count trends of the live streaming room GetLiveRoomViewTrendsResponseDataViewTrendPerformance: type: object properties: stats_type: type: string description: |- The viewer trend category. TREND_ONLINE_VIEWER: Viewers who are watching the live streaming room. TREND_ENTER_VIEWER: Viewers who enter the live streaming room. TREND_LEFT_VIEWER: Viewers who left the live streaming room. data_points: type: array items: $ref: "#/components/schemas/DataPoint" description: Viewer count data points for the corresponding trend category. GetLogisticsTrackingResponse: 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/GetLogisticsTrackingResponseData" GetLogisticsTrackingResponseData: type: object properties: order_id: type: string description: TikTok Shop order ID. logistics_details: type: array items: $ref: "#/components/schemas/GetLogisticsTrackingResponseDataLogisticsDetail" description: A list of parcels in the order. Each item describes one parcel and can include its carrier, latest tracking number, and tracking-event history. GetLogisticsTrackingResponseDataLogisticsDetail: type: object properties: newest_tracking_no: type: string description: The latest logistics tracking number for this parcel. carrier_name: type: string description: The carrier name. track_list: type: array items: $ref: "#/components/schemas/GetLogisticsTrackingResponseDataLogisticsDetailTrackList" description: A list of logistics tracking events for this parcel. GetLogisticsTrackingResponseDataLogisticsDetailTrackList: type: object properties: description: type: string description: Description of this tracking event. tracking_no: type: string description: The logistics tracking number associated with this tracking event. update_time_millis: type: integer format: int64 description: Unix timestamp in milliseconds (GMT/UTC+00:00) when this tracking event was updated. action_code: type: integer format: int64 description: |- Action code of this tracking event. It is an enumerated status value; the full enumeration list is maintained by the business side. Refer: action_code/action_code_name mapping details https://partner.tiktokshop.com/docv2/page/37tihrdq action_code_name: type: string description: Machine-readable status name corresponding to `action_code`. For action code and name mapping details, see https://partner.tiktokshop.com/docv2/page/37tihrdq. GetMarketplaceCreatorPerformanceResponse: 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/GetMarketplaceCreatorPerformanceResponseData" GetMarketplaceCreatorPerformanceResponseData: type: object properties: creator: $ref: "#/components/schemas/GetMarketplaceCreatorPerformanceResponseDataCreator" description: Data associated with the creator's TikTok profile. GetMarketplaceCreatorPerformanceResponseDataCreator: type: object properties: username: type: string description: TikTok user name. nickname: type: string description: TikTok nickname. avatar: $ref: "#/components/schemas/Avatar" description: Metadata and data associated with the creator's TikTok profile avatar. selection_region: type: string description: The region where the creator selects products to promote. bio_description: type: string description: The biography description associated with the creator. follower_count: type: integer format: int64 description: The creator's follower count. profile_tt_uri: type: string description: The deep-link URI for the creator's TikTok profile. category_ids: type: array items: type: string description: A list of category identifiers associated with the products for which the creator has created posts. top_collaborated_brand_ids: type: array items: type: string description: A list of the top 10 brands with which the creator has previously collaborated. brand_collaboration_count: type: integer format: int64 description: The total number of brands with which the creator has previously collaborated. units_sold: type: integer format: int64 description: The total number of units sold. Units are indexed to SKU. Note that if the creator has not given permission for precise data sharing, this property will not be present. units_sold_range: $ref: "#/components/schemas/UnitsSoldRange" description: The range of minimum number of units sold to maximum number of units sold over the lifetime of the creator account. Note that this property is included if the target market is `US` only. Note that if the creator has not given permission for precise data sharing, these properties will not be present. gmv: $ref: "#/components/schemas/GetLiveRoomGMVAndOrderTrendsResponseDataGmvTrendPerformanceDataPointGmv" description: Gross merchandise value (GMV) metadata and data associated with the creator. Note that if the creator has not given permission for precise data sharing, these properties will not be present. video_gmv: $ref: "#/components/schemas/VideoGmv" description: The video GMV metadata and data associated with the creator. Note that if the creator has not given permission for precise data sharing, these properties will not be present. live_gmv: $ref: "#/components/schemas/GetMarketplaceCreatorPerformanceResponseDataCreatorLiveGmv" description: Livestream GMV metadata and data associated with the creator. Note that if the creator has not given permission for precise data sharing, these properties will not be present. gmv_range: $ref: "#/components/schemas/GmvRange" description: The range of GMV values associated with this creator. Note that this property is included if the target market is `US` only. Note that if the creator has not given permission for precise data sharing, these properties will not be present. ec_live_engagement_rate: type: string description: E-commerce live stream engagement rate in hundredths of a percent. For example, `6000` is 60%. category_gmv_distribution: type: array items: $ref: "#/components/schemas/GetMarketplaceCreatorPerformanceResponseDataCreatorCategoryGmvDistribution" description: GMV distribution by category. content_gmv_distribution: type: array items: $ref: "#/components/schemas/GetMarketplaceCreatorPerformanceResponseDataCreatorContentGmvDistribution" description: GMV associated with creator content by content type. product_original_price_range: $ref: "#/components/schemas/GetMarketplaceCreatorPerformanceResponseDataCreatorProductOriginalPriceRange" description: The range of original prices for products promoted by the creator in the last 30 days. gpm: $ref: "#/components/schemas/GetMarketplaceCreatorPerformanceResponseDataCreatorGpm" description: GMV per mille (GPM) metadata and data associated with the creator. Note that if the creator has not given permission for precise data sharing, these properties will not be present. live_gpm: $ref: "#/components/schemas/GetMarketplaceCreatorPerformanceResponseDataCreatorLiveGpm" description: Livestream GMV per mille (GPM) metadata and data associated with the creator. Note that if the creator has not given permission for precise data sharing, these properties will not be present. video_gpm: $ref: "#/components/schemas/GetMarketplaceCreatorPerformanceResponseDataCreatorVideoGpm" description: Video GMV per mille (GPM) metadata and data associated with the creator. Note that if the creator has not given permission for precise data sharing, these properties will not be present. gpm_range: $ref: "#/components/schemas/GetMarketplaceCreatorPerformanceResponseDataCreatorGpmRange" description: The range of GPM values associated with the creator. Note that this property is included if the target market is `US`. Note that if the creator has not given permission for precise data sharing, these properties will not be present. video_gpm_range: $ref: "#/components/schemas/GetMarketplaceCreatorPerformanceResponseDataCreatorVideoGpmRange" description: The range of video GPM values associted with the creator. Note that this property is included if the target market is `US`. Note that if the creator has not given permission for precise data sharing, these properties will not be present. live_gpm_range: $ref: "#/components/schemas/GetMarketplaceCreatorPerformanceResponseDataCreatorLiveGpmRange" description: The range of livestream GPM values associted with the creator. Note that this property is included if the target market is `US` only. Note that if the creator has not given permission for precise data sharing, these properties will not be present. promoted_product_num: type: integer format: int64 description: The number of products promoted by the creator in the last 30 days. ec_live_count: type: integer format: int64 description: The number of e-commerce livestreams associated with the creator in the last 30 days. ec_video_count: type: integer format: int64 description: The number of e-commerce video posts associated with the creator in the last 30 days. avg_ec_video_play_count: type: integer format: int64 description: The average number of number of e-commerce video plays. avg_commission_rate: type: integer format: int64 description: The average commission rate in hundredths of a percent. Note that if the creator has not given permission for precise data sharing, these properties will not be present. avg_commission_rate_range: $ref: "#/components/schemas/GetMarketplaceCreatorPerformanceResponseDataCreatorAvgCommissionRateRange" description: The range of average commission rates associated with the creator. Note that if the creator has not given permission for precise data sharing, these properties will not be present. avg_gmv_per_buyer: $ref: "#/components/schemas/GetMarketplaceCreatorPerformanceResponseDataCreatorAvgGmvPerBuyer" description: Average GMV per buyer metadata and data associated with the creator. Note that this property is included if the target market is `US` only. Note that if the creator has not given permission for precise data sharing, these properties will not be present. avg_gmv_per_buyer_range: $ref: "#/components/schemas/GetMarketplaceCreatorPerformanceResponseDataCreatorAvgGmvPerBuyerRange" description: The range of average GMV per buyer associated with the creator. Note that this property is included if the target market is `US` only. Note that if the creator has not given permission for precise data sharing, these properties will not be present. avg_ec_live_view_count: type: integer format: int64 description: Average live stream views with promoted products. avg_ec_live_like_count: type: integer format: int64 description: Average e-commerce live stream likes. avg_ec_live_comment_count: type: integer format: int64 description: Average e-commerce live stream comments. avg_ec_live_share_count: type: integer format: int64 description: Average e-commerce live stream shares. avg_ec_video_like_count: type: integer format: int64 description: Average e-commerce video likes. avg_ec_video_comment_count: type: integer format: int64 description: Average e-commerce video comments. avg_ec_video_share_count: type: integer format: int64 description: Average e-commerce video shares. follower_location: type: array items: $ref: "#/components/schemas/GetMarketplaceCreatorPerformanceResponseDataCreatorFollowerLocation" description: A list of key–value pairs representing the distribution of followers by location. follower_age: type: array items: $ref: "#/components/schemas/GetMarketplaceCreatorPerformanceResponseDataCreatorFollowerAge" description: A list of key–value pairs representing the distribution of followers by age range. follower_gender: type: array items: $ref: "#/components/schemas/GetMarketplaceCreatorPerformanceResponseDataCreatorFollowerGender" description: A list of key–value pairs representing the distribution of followers by gender. pps: type: string description: |- Promotion Performance Score (PPS) The score reflects the quality of a creator's shoppable content and product selection over the past 90 days. A high score may indicate a better shopping experience, with fewer potential refunds or negative reviews. rating: type: string description: Rating from sellers who worked with this creator ec_video_engagement_rate: type: string description: |- The number of post engagements (likes, shares, and comments) divided by the total video views averaged across the videos in the last 30 days. For example, 3000 stands for 0.3 or 30% post_rate: type: string description: |- The projected rate at which a creator is likely to post a shoppable video or LIVE after receiving a sample. For example, 3000 stands for 0.3 or 30% creator_profile: $ref: "#/components/schemas/GetMarketplaceCreatorPerformanceResponseDataCreatorCreatorProfile" description: Advanced creator profile information. An empty object means this information is not available for the caller's account or region. GetMarketplaceCreatorPerformanceResponseDataCreatorAvgCommissionRateRange: type: object properties: minimum_amount: type: integer format: int64 description: The smallest average commission rate in hundredths of a percent. maximum_amount: type: integer format: int64 description: The largest average commission rate in hundredths of a percent. GetMarketplaceCreatorPerformanceResponseDataCreatorAvgGmvPerBuyer: type: object properties: currency: type: string description: The currency code. amount: type: string description: The average GMV per buyer amount. GetMarketplaceCreatorPerformanceResponseDataCreatorAvgGmvPerBuyerRange: type: object properties: currency: type: string description: The currency code. minimum_amount: type: string description: The smallest average GMV per buyer. maximum_amount: type: string description: The largest average GMV per buyer. formatted_range: type: string description: The formatted range of average GMV per buyer associated with the creator. GetMarketplaceCreatorPerformanceResponseDataCreatorCategoryGmvDistribution: type: object properties: category_id: type: string description: The top-level category identifier. A value of `-1` represents all other categories. value: type: string description: The proportion of the creator's GMV attributed to this category, expressed as a decimal from `0` to `1` (for example, `0.3035` = 30.35%). GetMarketplaceCreatorPerformanceResponseDataCreatorContentGmvDistribution: type: object properties: content_type: type: string description: |- The content type. This an enumerated type with values: - VIDEO - LIVE - SHOWCASE value: type: string description: The proportion of the creator's GMV attributed to this content type, expressed as a decimal from `0` to `1` (for example, `0.3035` = 30.35%). GetMarketplaceCreatorPerformanceResponseDataCreatorCreatorProfile: type: object properties: is_official_recommend: type: boolean description: Creaor has official recommend tag or not contact_info_available: type: boolean description: Is creator contact infomation available creator_bind_mcn_name: type: string description: Creator bind MCN name live_engagement_rate_30d: type: integer format: int64 description: Creator engagement rate last 30 days video_play_cnt_30d_med: type: integer format: int64 description: Creator average VIDEO play count last 30 days live_view_cnt_30d_med: type: integer format: int64 description: Creator average LIVE view count last 30 days live_like_cnt_30d: type: integer format: int64 description: Creator LIVE like count last 30 days live_comment_cnt_30d_med: type: integer format: int64 description: Creator average LIVE comment count last 30 days live_share_cnt_30d_med: type: integer format: int64 description: Creator average LIVE share count last 30 days video_publish_cnt_30d_med: type: integer format: int64 description: Creator average VIDEO publish count last 30 days has_invited_90d: type: boolean description: Has invited before 90 days is_creator_blocked: type: boolean description: Is creator blocked by shop creator_level: type: integer format: int64 description: Creator level creator_fulfillment_reviews: type: integer format: int64 description: The number of fulfillment reviews submitted by sellers for the creator in the last 90 days. is_eligible_flat_fee: type: boolean description: Creator is eligible for flat fee invitation is_rising_star: type: boolean description: Creator has rising star tag or not creator_fulfillment_score_90d: type: string description: Creator fulfillment score during last 90 days sample_score: type: integer format: int64 description: Creator credit total score. e.g. 75 means creator' sample scole is 75/100. creator_connect_info: $ref: "#/components/schemas/GetMarketplaceCreatorPerformanceResponseDataCreatorCreatorProfileCreatorConnectInfo" description: Creator connect infomation creator_trend_profile: type: array items: $ref: "#/components/schemas/GetMarketplaceCreatorPerformanceResponseDataCreatorCreatorProfileCreatorTrendProfile" description: Creator trend infomation GetMarketplaceCreatorPerformanceResponseDataCreatorCreatorProfileCreatorConnectInfo: type: object properties: is_paired: type: boolean description: Creator is paired or not is_connect: type: boolean description: Creator is connect or not is_blocked: type: boolean description: Creator is blocked or not GetMarketplaceCreatorPerformanceResponseDataCreatorCreatorProfileCreatorTrendProfile: type: object properties: start_timestamp: type: integer format: int64 description: Trend start timestamp end_timestamp: type: integer format: int64 description: Trend end timestamp gmv: $ref: "#/components/schemas/GetMarketplaceCreatorPerformanceResponseDataCreatorCreatorProfileCreatorTrendProfileGmv" description: Trend GMV infomation units_sold: type: integer format: int64 description: Trend units sold follower: type: integer format: int64 description: Trend follower engagement_rate: type: integer format: int64 description: Trend engagement rate e.g. 558 means creator's engagement rate is 5.58% GetMarketplaceCreatorPerformanceResponseDataCreatorCreatorProfileCreatorTrendProfileGmv: type: object properties: amount: type: string description: GMV amount symbol: type: string description: GMV symbol GetMarketplaceCreatorPerformanceResponseDataCreatorFollowerAge: type: object properties: key: type: string description: The age range (e.g., "18–23"). value: type: string description: The proportion of followers in this age range, expressed as a decimal (e.g., 0.2500 = 25.00%). GetMarketplaceCreatorPerformanceResponseDataCreatorFollowerGender: type: object properties: key: type: string description: The gender (e.g., "Male", "Female"). value: type: string description: The proportion of followers of this gender, expressed as a decimal (e.g., 0.5000 = 50.00%). GetMarketplaceCreatorPerformanceResponseDataCreatorFollowerLocation: type: object properties: key: type: string description: The country code for the follower location (for example, ID). value: type: string description: The proportion of followers from this location, expressed as a decimal (e.g., 0.3705 = 37.05%). GetMarketplaceCreatorPerformanceResponseDataCreatorGpm: type: object properties: currency: type: string description: The currency code. amount: type: string description: The GPM amount. GetMarketplaceCreatorPerformanceResponseDataCreatorGpmRange: type: object properties: currency: type: string description: The currency code. minimum_amount: type: string description: The lowest GPM value. maximum_amount: type: string description: The highest GPM value. formatted_range: type: string description: The formatted range of GPM values associated with the creator. GetMarketplaceCreatorPerformanceResponseDataCreatorLiveGmv: type: object properties: currency: type: string description: The currency code. amount: type: string description: Total livestream GMV associated with the creator. GetMarketplaceCreatorPerformanceResponseDataCreatorLiveGpm: type: object properties: currency: type: string description: The currency code. amount: type: string description: The livestream GPM amount. GetMarketplaceCreatorPerformanceResponseDataCreatorLiveGpmRange: type: object properties: currency: type: string description: The currency code. minimum_amount: type: string description: The lowest livestream GPM value. maximum_amount: type: string description: The highest livestream GPM value. formatted_range: type: string description: The formatted range of livestream GPM values associted with the creator. GetMarketplaceCreatorPerformanceResponseDataCreatorProductOriginalPriceRange: type: object properties: currency: type: string description: The currency code. minimum_amount: type: string description: The lowest original promoted product price. maximum_amount: type: string description: The higest original promoted product price. GetMarketplaceCreatorPerformanceResponseDataCreatorVideoGpm: type: object properties: currency: type: string description: The currency code. amount: type: string description: The video GPM amount. GetMarketplaceCreatorPerformanceResponseDataCreatorVideoGpmRange: type: object properties: currency: type: string description: The currency code. minimum_amount: type: string description: The lowest video GPM value. maximum_amount: type: string description: The highest video GPM value. formatted_range: type: string description: The formatted range of video GPM values associted with the creator. GetMessageTemplatesResponse: 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/GetMessageTemplatesResponseData" GetMessageTemplatesResponseData: type: object properties: message_templates: type: array items: $ref: "#/components/schemas/GetMessageTemplatesResponseDataMessageTemplate" description: Customer engagement message templates predefined by TikTok Shop. GetMessageTemplatesResponseDataMessageTemplate: type: object properties: id: type: string description: The template ID. message_title: type: string description: The message title. message_body: type: string description: The message body. product_card_rules: $ref: "#/components/schemas/GetMessageTemplatesResponseDataMessageTemplateProductCardRule" description: Rules on the number and type of interactive product cards that can be included in a message. coupon_card_rules: $ref: "#/components/schemas/GetMessageTemplatesResponseDataMessageTemplateCouponCardRule" description: Rules on the number and type of interactive coupon cards that can be included in a message. GetMessageTemplatesResponseDataMessageTemplateCouponCardRule: type: object properties: min_count: type: integer format: int64 description: The minimum number of coupon cards that must be included. max_count: type: integer format: int64 description: The maximum number of coupon cards that can be included. coupon_type: type: array items: type: string enum: - REGULAR_ALL - REGULAR_REPEAT x-enum-descriptions: - Regular coupons that target all buyers. - Regular coupons that target only repeat buyers. description: |- The types of coupon that can be included in the message. Possible values: - REGULAR_ALL: Regular coupons that target all buyers. Required coupon properties: `coupons.display_type=REGULAR` and `coupons.target_buyer_segment=ALL` in the [Search Coupons API](https://partner.tiktokshop.com/docv2/page/6699dcdf115ebe02f841e4cd). - REGULAR_REPEAT: Regular coupons that target only repeat buyers. Required coupon properties: `coupons.display_type=REGULAR` and `coupons.target_buyer_segment=REPEAT_CUSTOMERS` in the [Search Coupons API](https://partner.tiktokshop.com/docv2/page/6699dcdf115ebe02f841e4cd). GetMessageTemplatesResponseDataMessageTemplateProductCardRule: type: object properties: min_count: type: integer format: int64 description: The minimum number of product cards that must be included. max_count: type: integer format: int64 description: The maximum number of product cards that can be included. GetOpenCollaborationCreatorContentDetailsResponse: 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/GetOpenCollaborationCreatorContentDetailsResponseData" GetOpenCollaborationCreatorContentDetailsResponseData: type: object properties: next_page_token: type: string description: Pagination token for the next page. Pass this value as `page_token` in the next request. An empty token means there are no more results. total_count: type: integer format: int64 description: Total count of creators that satisfy all the input search conditions. creator_content_details: type: array items: $ref: "#/components/schemas/GetOpenCollaborationCreatorContentDetailsResponseDataCreatorContentDetail" description: Creator profiles, content counts, and promotion details for the specified product. product: $ref: "#/components/schemas/GetOpenCollaborationCreatorContentDetailsResponseDataProduct" description: Product details. GetOpenCollaborationCreatorContentDetailsResponseDataCreatorContentDetail: type: object properties: creator_profile: $ref: "#/components/schemas/GetOpenCollaborationCreatorContentDetailsResponseDataCreatorContentDetailCreatorProfile" description: Creator's profile details. video_count: type: integer format: int64 description: This field indicates the number of videos posted by the creator. live_count: type: integer format: int64 description: This field indicates the number of lives posted by the creator. promotion_status: type: string description: |- Promotion status of the creator. Field values: - NORMAL: When the creator is promoting normally, it returns to NORMAL status - TERMINATING:When the creator is asked by the merchant to terminate the promotion, the status will return to TERMINATING, indicating that the creator's promotion rights will expire soon. promotion_end_time: type: integer format: int64 description: End time of creator promotion. GetOpenCollaborationCreatorContentDetailsResponseDataCreatorContentDetailCreatorProfile: type: object properties: username: type: string description: The creator's username. nickname: type: string description: The creator's nickname. follower_count: type: integer format: int64 description: Number of followers of the creator. avatar: $ref: "#/components/schemas/Avatar" description: The creator's avatar details. creator_open_id: type: string description: Creator Open ID. [More details](https://partner.tiktokshop.com/docv2/page/3obfokj6) GetOpenCollaborationCreatorContentDetailsResponseDataProduct: type: object properties: id: type: string description: Product's unique id. image_url: type: string description: The product image url. GetOpenCollaborationProductListByProductIdsRequest: type: object properties: {} GetOpenCollaborationProductListByProductIdsResponse: 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/GetOpenCollaborationProductListByProductIdsResponseData" GetOpenCollaborationProductListByProductIdsResponseData: type: object properties: products: type: array items: $ref: "#/components/schemas/GetOpenCollaborationProductListByProductIdsResponseDataProduct" description: Products found for the requested product IDs. The response may contain fewer products than requested. GetOpenCollaborationProductListByProductIdsResponseDataProduct: type: object properties: shop: $ref: "#/components/schemas/Shop" description: The product's shop information. id: type: string description: Product's unique id. has_inventory: type: boolean description: Whether this product has inventory. units_sold: type: integer format: int64 description: The total number of units sold for this product. title: type: string description: Product's name. sale_region: type: string description: The region represents the areas where the product can be sold. main_image_url: type: string description: The product image url. detail_link: type: string description: Product's detail link which is used to get product details on mobile clients. original_price: $ref: "#/components/schemas/OriginalPrice" description: The product's original price category_chains: type: array items: $ref: "#/components/schemas/CategoryChain" description: |- The categories of this product. Return to the top three categories at most commission: $ref: "#/components/schemas/Commission" description: The commission of this product. sales_price: $ref: "#/components/schemas/SalesPrice" description: Sales price information of the product shop_ads_commission: $ref: "#/components/schemas/GetOpenCollaborationProductListByProductIdsResponseDataProductShopAdsCommission" description: |- The ads commission rate applies only to orders generated from ads. If a creator’s video is used as an ad without this rate being set, the resulting orders will instead earn either: - The Shop Ads commission you configured in open collaboration, or - The standard commission defined in this invitation. GetOpenCollaborationProductListByProductIdsResponseDataProductShopAdsCommission: type: object properties: rate: type: integer format: int64 description: The Shop Ads commission rate for this product, multiplied by 10,000. The range is 100 to 8,000. For example, 3,000 represents 30.00% and 3,555 represents 35.55%. GetOpenCollaborationSampleRulesResponse: 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/GetOpenCollaborationSampleRulesResponseData" GetOpenCollaborationSampleRulesResponseData: type: object properties: sample_rules: type: array items: $ref: "#/components/schemas/GetOpenCollaborationSampleRulesResponseDataSampleRule" description: The sample rules for the requested products. Products whose sample rules have never been created or have been deleted are omitted. GetOpenCollaborationSampleRulesResponseDataSampleRule: type: object properties: product_id: type: string description: The unique id of product. sample_quota: type: integer format: int64 description: The sample total quantity provided by seller which creators can apply for. is_sample_time_unlimited: type: boolean description: |- Whether samples are timely unlimited for request: - If true, it means available all the time - If false, it means sample only available from `begin_time` to `end_time`. status: type: string description: |- Free sample rule status: - NOT_STARTED. Not yet reached the specified `begin_time`. - ONGOING. The sample rule is effective and the collaboration is ongoing. - `NO_LEFT_COUNT`. `sample_quantity_available` is `0`. - PLAN_EXCEPTION. The product commission collaboration status is abnormal - EXPIRED. Exceeded the `end_time`. available_quantity: type: integer format: int64 description: The quantity of remaining samples available for application. start_time: type: integer format: int64 description: When present, the start of the sample application period, expressed as a Unix timestamp in seconds (UTC). end_time: type: integer format: int64 description: When present, the end of the sample application period, expressed as a Unix timestamp in seconds (UTC). thresholds: $ref: "#/components/schemas/Threshold" description: The threshold criteria that a creator must meet to be eligible to apply for the sample. GetOpenCollaborationSettingsResponse: 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/GetOpenCollaborationSettingsResponseData" GetOpenCollaborationSettingsResponseData: type: object properties: open_collaboration_settings: $ref: "#/components/schemas/GetOpenCollaborationSettingsResponseDataOpenCollaborationSetting" description: Open collaboration settings for the shop. GetOpenCollaborationSettingsResponseDataOpenCollaborationSetting: type: object properties: auto_add_product: $ref: "#/components/schemas/GetOpenCollaborationSettingsResponseDataOpenCollaborationSettingAutoAddProduct" description: Settings for automatically adding products to open collaboration. GetOpenCollaborationSettingsResponseDataOpenCollaborationSettingAutoAddProduct: type: object properties: enable: type: boolean description: |- - true: The seller can add existing non-affiliate products to open collaboration at one time, and future products will also be added automatically. - false: Future products will not be added to open collaboration automatically, but existing products' open collaboration will not be reverted. commission_rate: type: integer format: int64 description: |- The default commission rate of open collaboration created for the auto-added products. The unit is 0.01%. For example, to set the default commission rate to 10%, set the value to `1000`. If so, if the price of a product is $50 USD, the creator would receive $5 USD for every piece of product sold. The range is `[100, 8000]`. When enable=false, this field will not be returned. GetOpportunityDetailResponse: 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/GetOpportunityDetailResponseData" GetOpportunityDetailResponseData: type: object properties: opportunity: $ref: "#/components/schemas/GetOpportunityDetailResponseDataOpportunity" description: Detailed opportunity information, including basic details, market and content data, listing criteria, and the recommended action. GetOpportunityDetailResponseDataOpportunity: type: object properties: id: type: string description: Unique ID of the opportunity action_type: type: string enum: - LIST_SAME - LIST_SIMILAR x-enum-descriptions: - List the same product. - List a similar product. description: |- The recommended action. Possible values: - LIST_SAME: List the same product. - LIST_SIMILAR: List a similar product. listing_criteria: $ref: "#/components/schemas/GetOpportunityDetailResponseDataOpportunityListingCriteria" description: The criteria for products that match the opportunity lead. content_data: $ref: "#/components/schemas/GetOpportunityDetailResponseDataOpportunityContentData" description: The relevant data for the past 30 days. market_data: $ref: "#/components/schemas/GetOpportunityDetailResponseDataOpportunityMarketData" description: The relevant data for the past 30 days. basic_info: $ref: "#/components/schemas/GetOpportunityDetailResponseDataOpportunityBasicInfo" description: The detailed information of the opportunity. GetOpportunityDetailResponseDataOpportunityBasicInfo: type: object properties: opportunity_type: type: string enum: - PRODUCT - KEYWORD - CATEGORY x-enum-descriptions: - A product opportunity. - A keyword opportunity. - A category opportunity. description: |- The opportunity type. Possible values: - PRODUCT: A product opportunity. - KEYWORD: A keyword opportunity. - CATEGORY: A category opportunity. status: type: string description: "Opportunity status: ACTIVE / EXPIRED / FULFILLED(已提报)" create_time: type: integer format: int64 description: The opportunity creation time as a Unix timestamp in seconds (UTC). expire_time: type: integer format: int64 description: Opportunity expiry date, second-level timestamp title: type: string description: Opportunity title. category_id_level_1: type: string description: TikTok Shop L1 category ID. category_id_level_2: type: string description: TikTok Shop L2 category ID. category_id_level_3: type: string description: TikTok Shop L3 category ID. category_name_level_1: type: string description: Category name of 1st level category. category_name_level_2: type: string description: Category name of 2nd level category. category_name_level_3: type: string description: Category name of 3rd level category. reference_price: type: string description: The reference price for the product to list, formatted with the applicable currency symbol and three decimal places. If both price boundaries are available, the value is returned as a range; if one is available, a single price is returned; if neither is available, an empty string is returned. reference_images: type: array items: type: string description: Reference product images of the product to list. brand_info: type: string description: Brand requirements for products specified by the opportunity. reward_info: type: string description: Comma-separated descriptions of rewards that sellers can gain by listing products as required. Values are localized when a translation is available; otherwise, the configured reward description is returned. recom_info: type: string description: Recommendation reason why this is an opportunity. tags: type: string description: Comma-separated display values for the opportunity tags. Each value is localized when a translation is available; otherwise, the configured tag description or tag code is returned. tag_codes: type: array items: type: string description: Tag codes for the opportunity. The available codes depend on seller and market configuration. Examples for Latam include `core_product` and `top_product`. external_product_id: type: string description: Product ID on the reference source. reference_source: type: string enum: - "1" - "2" - "3" - "4" - "5" - "6" - "7" - "8" - "9" - "10" - "11" - "12" - "13" - "14" - "15" - "16" - "17" - "18" - "19" - "20" - "21" - "22" x-enum-descriptions: - SHOPEE - AMAZON - LOOKFANTASTIC - WALMART - TTS - ASOS - UNIVERSAL_PRODUCT - DTCNEXUS - TEMU - SHOPIFY - NEXUS_SHOPIFY - SHEIN - PIXEL - SHOPIFY_NON_1P - MIRAVIA - RAKUTEN - EBAY - ONBUY - MERCADO_LIBRE - ALLEGRO - BOL - DTC description: |- The reference platform code, returned only when `external_product_id` is present. Possible values: - `1`: SHOPEE - `2`: AMAZON - `3`: LOOKFANTASTIC - `4`: WALMART - `5`: TTS - `6`: ASOS - `7`: UNIVERSAL_PRODUCT - `8`: DTCNEXUS - `9`: TEMU - `10`: SHOPIFY - `11`: NEXUS_SHOPIFY - `12`: SHEIN - `13`: PIXEL - `14`: SHOPIFY_NON_1P - `15`: MIRAVIA - `16`: RAKUTEN - `17`: EBAY - `18`: ONBUY - `19`: MERCADO_LIBRE - `20`: ALLEGRO - `21`: BOL - `22`: DTC GetOpportunityDetailResponseDataOpportunityContentData: type: object properties: video_view_pv: type: string description: The cumulative short video view count of all videos associated with this product opportunity. shoppable_video_search_pv: type: string description: "The search page-view count for shoppable short videos associated with this product opportunity over the previous 30 days, returned as an approximate bucket: `<100`, a rounded-down hundreds value such as `300+`, a rounded-down thousands value such as `12k+`, a rounded-down millions value such as `1M+`, or `100M+`." trending_hashtag: type: string description: The top 1 video hashtag of the product-related videos, sorted by view count. top_shoppable_video_links: type: array items: type: string description: Links to the top 10 shoppable short videos related to the product, sorted by view count. GetOpportunityDetailResponseDataOpportunityListingCriteria: type: object properties: product_brand: type: string description: Requirement for product brand. product_category: type: string description: Requirement for product category. product_status: type: string description: "Requirement for product status : LIVE / DRAFT" keywords: type: string description: A comma-separated list of keywords that must be included in the product's title, attributes, description, or other applicable content. GetOpportunityDetailResponseDataOpportunityMarketData: type: object properties: est_market_sales_volume: type: string description: "Estimated market sales volume for the last 30 days, returned as an approximate bucket: `<100`, a value rounded down to a hundreds bucket ending in `00+`, a `k+` or `M+` value, or `100M+`." est_market_gmv: type: string description: "Estimated market sales GMV in USD for the last 30 days, returned as an approximate bucket: `<100`, a value rounded down to a hundreds bucket ending in `00+`, a `k+` or `M+` value, or `100M+`." market_buzz: type: string description: "Popularity level of the product: HOT / HIGH / MEDIUM" search_volume: type: string description: TikTok Shop in-site search volume, rounded to the nearest whole number and returned as a decimal string. search_keyword: type: string description: Comma-separated TikTok Shop in-site search keywords associated with the opportunity. competitor_product_count: type: string description: Approximate number of competing products listed in the last 30 days, returned as one of `< 10`, `< 50`, `< 100`, or `100+`. competitor_seller_count: type: string description: Number of competing sellers with the products currently listed. GetOrCreateCreatorConversationRequest: type: object properties: creator_open_id: type: string description: The creator's Open ID. Use the Open ID returned by the relevant API, not a user ID, creator ID, or seller ID. [More details](https://partner.tiktokshop.com/docv2/page/3obfokj6) only_need_conversation_id: type: boolean description: |- - If `true`, only `conversation_id` in `data.conversation` is returned. - If `false`, all fields in `data.conversation` are returned. `true` by default. required: - creator_open_id GetOrCreateCreatorConversationResponse: 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/GetOrCreateCreatorConversationResponseData" GetOrCreateCreatorConversationResponseData: type: object properties: conversation_id: type: string description: The unique ID of the conversation. is_new: type: boolean description: Whether this is a new conversation. username: type: string description: The TikTok creator's username. avatar: type: string description: The URL for the TikTok creator's avatar image file. unread_count: type: integer format: int64 description: Number of messages unread by the shop. creator_im_id: type: string description: Creators' IM User ID. GetOrderCustomsRequirementsRequest: type: object properties: order_ids: type: array items: type: string description: TikTok Shop order IDs to query. When providing a request body, include 1 to 50 order IDs. required: - order_ids GetOrderCustomsRequirementsResponse: 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/GetOrderCustomsRequirementsResponseData" GetOrderCustomsRequirementsResponseData: type: object properties: order_clearance_list: type: array items: $ref: "#/components/schemas/GetOrderCustomsRequirementsResponseDataOrderClearanceList" description: clearance info of this order GetOrderCustomsRequirementsResponseDataOrderClearanceList: type: object properties: order_id: type: string description: TikTok Shop order ID need_fill_clearance: type: boolean description: |- Whether an order needs to fill customs infomation: - true: The order needs to fill in customs information. - false: The order does not need to fill in custom information. already_filled_clearance: type: boolean description: When `need_fill_clearance` is `true`, whether customs clearance information has been submitted for every order line that requires it. This value is `false` when `need_fill_clearance` is `false`. target_country: type: string description: Country Alpha-2 Code biz_type: type: integer format: int64 description: |- enum CustomsBusinessType { CustomsBusinessTypeFS = 1; CustomsBusinessTypePOP = 2; } shipment_type: type: integer format: int64 description: |- enum ShipmentType{ CROSS_BORDER = 1, LOCAL = 2, } item_list: type: array items: $ref: "#/components/schemas/GetOrderCustomsRequirementsResponseDataOrderClearanceListItemList" description: Order-line details for the order. GetOrderCustomsRequirementsResponseDataOrderClearanceListItemList: type: object properties: order_line_id: type: string description: Sub order ID product_id: type: string description: Product ID. sku_id: type: string description: SKU ID. is_virtual_unboxing: type: boolean description: Whether this sub order is virtual_unboxing is_temporary_listing: type: boolean description: Whether this sub order is temporary_listing related_item_detail: type: array items: $ref: "#/components/schemas/GetOrderCustomsRequirementsResponseDataOrderClearanceListItemListRelatedItemDetail" description: Submitted customs clearance item details for this order line, aggregated by SKU. GetOrderCustomsRequirementsResponseDataOrderClearanceListItemListRelatedItemDetail: type: object properties: product_id: type: string description: Product ID. sku_id: type: string description: SKU ID. qty: type: integer format: int64 description: The amount of this sku price_percent: type: integer format: int64 description: "unit: %, price_percent=10 means 10%" GetOrderDetailResponse: 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/GetOrderDetailResponseData" GetOrderDetailResponseData: type: object properties: orders: type: array items: $ref: "#/components/schemas/GetOrderDetailResponseDataOrder" description: Order information. GetOrderDetailResponseDataOrder: type: object properties: id: type: string description: A unique identifier for a TikTok Shop order. cancellation_initiator: type: string enum: - SELLER - BUYER - SYSTEM description: |- The initiator of a cancellation request. Possible values: - `SELLER` - `BUYER` - `SYSTEM` shipping_provider: type: string description: The name of the current shipping provider. shipping_provider_id: type: string description: The ID of the current shipping provider. user_id: type: string description: The buyer's user ID. status: type: string enum: - UNPAID - ON_HOLD - AWAITING_SHIPMENT - PARTIALLY_SHIPPING - AWAITING_COLLECTION - IN_TRANSIT - DELIVERED - COMPLETED - CANCELLED x-enum-descriptions: - The order is placed, but payment is not yet completed. - The order is accepted and is waiting for fulfillment so the buyer may still cancel without the seller’s approval. If `order_type=PRE_ORDER`, it also means the product is still awaiting release so payment will only be authorized 1 day before the release, but the seller should start preparing for the release. - The order is ready for shipment, but no items are shipped yet. - Some items in the order are shipped, but not all. - The shipment is arranged, but the package is waiting to be collected by the carrier. - The package is collected by the carrier and delivery is in progress. - The package is delivered to buyer. - The order is completed, and no further returns or refunds are allowed. - The order is cancelled. description: |- The order status. Possible values: - `UNPAID`: The order is placed, but payment is not yet completed. - `ON_HOLD`: The order is accepted and is waiting for fulfillment so the buyer may still cancel without the seller’s approval. If `order_type=PRE_ORDER`, it also means the product is still awaiting release so payment will only be authorized 1 day before the release, but the seller should start preparing for the release. - `AWAITING_SHIPMENT`: The order is ready for shipment, but no items are shipped yet. - `PARTIALLY_SHIPPING`: Some items in the order are shipped, but not all. - `AWAITING_COLLECTION`: The shipment is arranged, but the package is waiting to be collected by the carrier. - `IN_TRANSIT`: The package is collected by the carrier and delivery is in progress. - `DELIVERED`: The package is delivered to buyer. - `COMPLETED`: The order is completed, and no further returns or refunds are allowed. - `CANCELLED`: The order is cancelled. rts_time: type: integer format: int64 description: |- The time seller shipped the order (call Ship Order endpoint successfully). Unix timestamp. payment: $ref: "#/components/schemas/Payment" description: Payment info about a TikTok Shop order. recipient_address: $ref: "#/components/schemas/GetOrderDetailResponseDataOrderRecipientAddress" description: "`recipient_address` is not available under `UNPAID` and `ON_HOLD` status." buyer_message: type: string description: The note from buyer. create_time: type: integer format: int64 description: The date and time that the order was created. Unix timestamp. tracking_number: type: string description: Tracking number. Available after ship package. cancel_reason: type: string description: |- The order level cancellation reason. **Note**: A multi-line order may have different `cancel_reason` across the multiple items. If this occurs, the order-level `cancel_reason` will surface the `cancel_reason` from the first line item. [See here](https://partner.tiktokshop.com/docv2/page/cancel-reasons) for more details on cancellation reasons. rts_sla_time: type: integer format: int64 description: The latest shipping time specified by the platform. Unix timestamp. paid_time: type: integer format: int64 description: The date and time that the order was paid. Unix timestamp. fulfillment_type: type: string enum: - FULFILLMENT_BY_SELLER - FULFILLMENT_BY_TIKTOK - FULFILLMENT_BY_DILAYANI_TOKOPEDIA x-enum-descriptions: - a method where sellers fulfill orders directly from their own inventory, without using TikTok's fulfillment centers. In this model, the seller is responsible for storing, packaging, and shipping the product to customers. - a service offered by TikTok that enables sellers to send their products to TikTok's fulfillment centers. TikTok then takes care of storing, picking, packing, and shipping the products to customers. - a method where Tokopedia GoTo Logistics provides warehousing and logistics services to sellers and charges a fee for the service. description: |- Fulfillment type. Only orders with fulfillment type can be shipped by sellers. Possible values: - `FULFILLMENT_BY_SELLER`: a method where sellers fulfill orders directly from their own inventory, without using TikTok's fulfillment centers. In this model, the seller is responsible for storing, packaging, and shipping the product to customers. - `FULFILLMENT_BY_TIKTOK`: a service offered by TikTok that enables sellers to send their products to TikTok's fulfillment centers. TikTok then takes care of storing, picking, packing, and shipping the products to customers. - `FULFILLMENT_BY_DILAYANI_TOKOPEDIA`: a method where Tokopedia GoTo Logistics provides warehousing and logistics services to sellers and charges a fee for the service. seller_note: type: string description: This field return the note, which seller notes in TikTok Seller Center. tts_sla_time: type: integer format: int64 description: |- The latest collection time specified by the platform. Unix timestamp. cancel_order_sla_time: type: integer format: int64 description: |- The automatic cancellation time for orders specified by the platform. Unix timestamp. update_time: type: integer format: int64 description: |- Time of order status changes. Unix timestamp. packages: type: array items: $ref: "#/components/schemas/GetOrderDetailResponseDataOrderPackage" description: List of packages included in this order delivery_type: type: string description: |- Indicates whether it is a PickUp DropOff (PUDO) location. The PUDO location is selected by the buyer when placing orders. - `HOME_DELIVERY`: not a PUDO location - `COLLECTION_POINT`: a PUDO location is_sample_order: type: boolean description: Use this field to determine whether the order is a sample order. warehouse_id: type: string description: seller warehouse ID. split_or_combine_tag: type: string description: |- Indicate whether the order is combined or split. - `COMBINED` - `SPLIT` This field will be used in future fulfillment apis. has_updated_recipient_address: type: boolean description: |- Whether the recipient address has been updated. - `false`: no update - `true`: updated cpf: type: string description: CPF (invoice number), used to issue an invoice. Exclusive for the Brazil market. delivery_option_id: type: string description: Order delivery option ID. delivery_sla_time: type: integer format: int64 description: Order should arrive by this date to be considered on-time and to avoid late delivery penalties. payment_method_name: type: string description: Payment method name, only for display payment_card_type: type: string enum: - Debit - Credit - Prepaid description: "Code to distinguish different payment method. Only assigned when the payment method is using bank card. Possible values are: Debit, Credit, Prepaid" channel_entity_national_registry_id: type: string description: The national channel entity registration ID of payment institution/creditor. In Brazil, it is the CNPJ of payment instituion. payment_method_code: type: string description: Payment method code identifying current transaction. It will contains payment method and card brand if it is card transaction. payment_auth_code: type: string description: |- Authorization code of current transaction (only for the Brazilian market). For card transactions (credit/debit card), this field will be transaction authorization code. For PIX transactions, this field will be E2E ID. shipping_due_time: type: integer format: int64 description: If the order hasn't updated its status to `AWAITING_COLLECTION` before this time, the order will be automatically canceled by TikTok Shop. line_items: type: array items: $ref: "#/components/schemas/GetOrderDetailResponseDataOrderLineItem" description: Line item info list. shipping_type: type: string description: |- The method of delivery. - `TIKTOK`: shipping service provided by TikTok. The seller should obtain shipping label from TikTok. - `SELLER`: seller provides shipping, including through 3rd party fulfillment providers on behalf of the seller. - `TIKTOK_DIGITAL`: Tiktok delivers virtual goods directly to buyers. There is no action needed. buyer_email: type: string description: The anonymized email address of the buyer. It is not recommended to send messages directly to this email address. If you need to contact the buyer, please go to Seller Center - Buyer Messages page. delivery_time: type: integer format: int64 description: The timestamp of the order's status update to `DELIVERED`. need_upload_invoice: type: string description: |- Whether an invoice needs to be uploaded and uploaded status (only for Brazil market). - UNKNOWN: Currently unable to confirm whether an invoice is needed - NEED_INVOICE: This order requires an invoice and the invoice has not been uploaded yet - NO_NEED：This order does not require an invoice - INVOICE_UPLOADED: The invoice for this order has been uploaded and verified. If the order is split, it will be marked as "uploaded" once any sub-order's invoice is uploaded. - INVOICE_PROCESSING: The invoice for this order is currently being uploaded/cancelled. Please wait for the final result and do not repeat the operation is_cod: type: boolean description: This option is for sellers that accept cash payment on delivery which is rare. Buyers will pay in cash upon receipt of package. Default value is `FALSE`. Only applicable to countries where Cash on Delivery (COD) is supported. request_cancel_time: type: integer format: int64 description: Buyer request cancel time. delivery_option_required_delivery_time: type: integer format: int64 description: Order should be delivered before this time. delivery_option_name: type: string description: Delivery option name. For display purposes only. is_buyer_request_cancel: type: boolean description: True when the buyer has a pending cancellation request delivery_due_time: type: integer format: int64 description: If the order hasn't updated its status to `DELIVERED` before this time, the order will be automatically canceled by TikTok Shop. collection_time: type: integer format: int64 description: The timestamp of the order's status update to `IN_TRANSIT`. is_on_hold_order: type: boolean description: Indicates whether the order experienced or will be experienced `ON_HOLD` status. cancel_time: type: integer format: int64 description: The timestamp of the order's status update to `CANCELLED`. is_replacement_order: type: boolean description: When true, this is a replacement order. replaced_order_id: type: string description: The order ID for the order that is being replaced. Returned only if `is_replacement_order` = `true` collection_due_time: type: integer format: int64 description: If the order hasn't updated its status to `IN_TRANSIT` before this time, the order will be automatically canceled by TikTok Shop pick_up_cut_off_time: type: integer format: int64 description: To avoid LDR, you must ensure the package is picked up by this time. Only applicable in Southeast Asia regions. fast_dispatch_sla_time: type: integer format: int64 description: |- The latest collection time to gain incentives of NDD (Next Day Delivery) project. Unix timestamp Only available in Thailand and Philippines. commerce_platform: type: string enum: - TIKTOK_SHOP - TOKOPEDIA description: |- The platform where the order was placed. Possible values: - TIKTOK_SHOP - TOKOPEDIA **Note**: Available only in the Indonesia market. order_type: type: string enum: - NORMAL - ZERO_LOTTERY - AUCTION - PRE_ORDER - MADE_TO_ORDER - BACK_ORDER - VIRTUAL_ORDER x-enum-descriptions: - An item that is in stock and available for immediate purchase and fulfillment. - An order placed during a lottery event in TikTok LIVE. - An order placed during auction, where the price of the product is not fixed. - An advance order for items that are not yet available or released. Fulfillment starts on a specific date in the future. - An order for items that are produced only after the order is received. Fulfillment starts after the product is produced. - An order for items that are out of stock but expected to be restocked. Fulfillment starts after the product is restocked. - An order for items that are digital goods, requiring no physical delivery. Fulfillment is immediate or automated upon payment confirmation. description: |- The order type. Possible values based on region: **All regions** - `NORMAL`: An item that is in stock and available for immediate purchase and fulfillment. - `ZERO_LOTTERY`: An order placed during a lottery event in TikTok LIVE. - `AUCTION`: An order placed during auction, where the price of the product is not fixed. **US** - `PRE_ORDER`: An advance order for items that are not yet available or released. Fulfillment starts on a specific date in the future. - `MADE_TO_ORDER`: An order for items that are produced only after the order is received. Fulfillment starts after the product is produced. - `BACK_ORDER`: An order for items that are out of stock but expected to be restocked. Fulfillment starts after the product is restocked. - `VIRTUAL_ORDER`: An order for items that are digital goods, requiring no physical delivery. Fulfillment is immediate or automated upon payment confirmation. Returns an empty value for standard orders or other types that don't fall into the above categories. release_date: type: integer format: int64 description: |- The date on which order handling starts and the status of the order changes to [`AWAITING_SHIPMENT`](https://partner.tiktokshop.com/docv2/page/650b1b4bbace3e02b76d1011). Applicable only if the `order_type` is `PRE_ORDER`. handling_duration: $ref: "#/components/schemas/HandlingDuration" description: |- The duration for the seller to process the order and hand it over to a shipping carrier after the order is placed. Applicable only if the `order_type` is `MADE_TO_ORDER` or `BACK_ORDER`. auto_combine_group_id: type: string description: An identifier assigned to orders from the same customer during a LIVE session to facilitate combined order shipping when "auto-combination" is activated in Seller Center. cpf_name: type: string description: Name belonging to the CPF number for the Brazil market. is_exchange_order: type: boolean description: |- When TRUE, this is an exchange order. Note: Only available in US and UK. exchange_source_order_id: type: string description: |- If the order is an exchange order, this field returns the original order's order ID, from which the exchange order was generated. Returned only if is_exchange_order = true. Note: Only available in US and UK. is_subscription_order: type: boolean description: Subscription orders are recurring orders set up by customers. If TRUE, this order is generated from a subscription order is_refundable_sample: type: boolean description: This indicates if an order is a refundable sample. Refundable samples lets sellers collaborate with creators by refunding product costs only when creators meet sales thresholds. authentication_required: type: boolean description: If true, order requires authentication. Use an approved in-house authentication service after an order has been placed for verification. This must be completed before shipment. consultation_id: type: string description: |- An ID to identify the corresponding ePharmacy consultation. Applicable only if an ePharmacy consultation was initiated. Not applicable if the prescription was provided by the customer through an image upload. fast_delivery_program: type: string enum: - 3_DAY_DELIVERY - 3_DAY_POTENTIAL_SHIPPING - 3_DAY_POTENTIAL_TRANSIT description: |- A badge presented on the merchandise to tell the buyer that the seller participates in the fast delivery program, such that the order should arrive in a promised time period. Possible values: - `3_DAY_DELIVERY` - `3_DAY_POTENTIAL_SHIPPING` - `3_DAY_POTENTIAL_TRANSIT` Not returned if order did not meet fast delivery program requirements. Note: Applicable only for the US market. buyer_nickname: type: string description: The nickname of the TikTok buyer, which is defined by the TikTok user. The buyer_nickname can be used to identify the buyer when displaying the unboxing results within the TikTok Live Session. buyer_avatar: type: string description: The avatar of the TikTok buyer, which is defined by the TikTok user. The buyer_avatar can be used in conjunction with the buyer_nickname when displaying the unboxing results within the TikTok Live Session. order_rights: type: array items: type: integer format: int64 description: |- Order tag identifier if has certain rights within the order based on the program subscribed by sellers. 1 = Shipping Fee Reimbursement Program 2 = Horizon+ Program Applicable for SEA market only fulfillment_priority_level: type: integer format: int64 description: |- Fulfillment priority value that can be used to prioritize shipping (only available in SEA) 100 = Instant 200 = Sameday 8 Hours 300 = Sameday 400 = Next Day Delivery 500 = Express 600 = Standard 700 = Economy 800 = Cargo recommended_shipping_time: type: integer format: int64 description: Recommended time to ship based on the each LSP service type (only available in SEA) instore_pickup_sla_time: type: integer format: int64 description: The latest buyer pickup time for instore pickup method specified by the platform. Currently applicable for SEA market. Unix timestamp. fast_rts_sla_time: type: integer format: int64 description: Indicate fast fulfillment SLA for shipping action. Applicable for SEA market only. Unix timestamp fast_collection_sla_time: type: integer format: int64 description: Indicate fast fulfillment SLA for collection action. Applicable for SEA market only. Unix timestamp GetOrderDetailResponseDataOrderLineItem: type: object properties: id: type: string description: Line item ID. sku_id: type: string description: SKU ID. combined_listing_skus: type: array items: $ref: "#/components/schemas/CombinedListingSku" description: For a virtual bundle SKU, returns an array of related product SKUs that compose the virtual bundle SKU. product_id: type: string description: Product ID. product_name: type: string description: Product name. sku_name: type: string description: The name of the SKU, combined by product SKU attribute like size or color. For example, "Black, 26." sku_image: type: string description: SKU image. original_price: type: string description: Item original price, please refer to the currency of `payment_info`. sale_price: type: string description: Item sale price, please refer to the currency of `payment_info`. pfand_fee: type: string description: |- Deposit fee that is applied to certain products, typically beverage containers such as bottles or cans. **Note** Only available in Germany market platform_discount: type: string description: Platform discount amount, please refer to the currency of `payment_info`. display_status: type: string description: |- - `UNPAID`: The order is placed, but payment is not yet completed. - `AWAITING_SHIPMENT`: The order is ready for shipment, but no items are shipped yet. - `AWAITING_COLLECTION`: The shipment is arranged, but the package is waiting to be collected by the carrier. - `IN_TRANSIT`: The package is collected by the carrier and delivery is in progress. - `DELIVERED`: The package is delivered to buyer. - `COMPLETED`: The order is completed, and no further returns or refunds are allowed. - `CANCELLED`: The order is canceled. cancel_user: type: string description: |- The initiator of a cancellation request: - `BUYER` - `SELLER` - `OPERATOR` - `SYSTEM` sku_type: type: string enum: - NORMAL - ZERO_LOTTERY - SHOP_PARTNER - PRE_ORDER - MADE_TO_ORDER x-enum-descriptions: - An item that is in stock and available for immediate purchase and fulfillment. - "` An item purchased during a lottery event in TikTok LIVE." - An item purchased from a TikTok Shop partner store. - An item that is not yet available or released. Fulfillment starts on a specific date in the future. - An item that is produced only after the order is received. Fulfillment starts after the product is produced. description: |- [**Deprecated**: This field is deprecated and will be removed in a future API version. Use `order_type` instead.] The order line type: Possible values based on region: **All regions** - `NORMAL`: An item that is in stock and available for immediate purchase and fulfillment. - `ZERO_LOTTERY:` An item purchased during a lottery event in TikTok LIVE. - `SHOP_PARTNER`: An item purchased from a TikTok Shop partner store. **US** - `PRE_ORDER`: An item that is not yet available or released. Fulfillment starts on a specific date in the future. - `MADE_TO_ORDER`: An item that is produced only after the order is received. Fulfillment starts after the product is produced. deprecated: true seller_sku: type: string description: The seller stock keeping unit (SKU) of the item. shipping_provider_id: type: string description: The shipping provider ID of the item. seller_discount: type: string description: Seller discount amount. Please refer to the currency of `payment_info`. currency: type: string description: Currency for payment. package_id: type: string description: An order can contain one or more packages based on how the seller chooses to ship. Each package has a unique `package_id` (and also a `tracking_id`, which is used to track the progress of the package as it is shipped). For local sellers in the US and UK markets, the `package_id` and `package_status` property will not be returned before the package is shipped rts_time: type: integer format: int64 description: |- The time seller shipped line order (call Ship Order endpoint successfully). Unix timestamp. item_tax: type: array items: $ref: "#/components/schemas/GetOrderDetailResponseDataOrderLineItemItemTax" description: Item tax detail. package_status: type: string description: |- The package status of the item: - `TO_FULFILL`: package waiting seller to arrange shipment. - `PROCESSING`: package shipment has been arranged by seller. Waiting carrier to collect the parcel. - `FULFILLING`: package has been collected by carrier and in transit. - `COMPLETED`: package has been delivered. - `CANCELLED`: package has been canceled. Normally, the package is canceled due to the package being lost or damaged. shipping_provider_name: type: string description: The shipping provider name of the item. is_gift: type: boolean description: Indicates whether the current order line is a gift. cancel_reason: type: string description: Item cancellation reason. small_order_fee: type: string description: Small order fee for TH. retail_delivery_fee: type: string description: RDF (retail delivery fee). Available only in the US market. tracking_number: type: string description: Tracking number. Available after package has been shipped. buyer_service_fee: type: string description: A service fee is charged on every transaction made. The charge is applied from the fifth order onwards and collected directly from customers during checkout. Only available in Indonesia market. handling_duration_days: type: string description: |- [**Deprecated**: This field is deprecated and will be removed in a future API version. Use `handling_duration` instead.] The number of business days required for the seller to process the order and hand it over to a shipping carrier after the order is placed. Applicable only if the value for `sku_type` is `MADE_TO_ORDER`. deprecated: true is_dangerous_good: type: boolean description: Whether the SKU is a hazmat item. When creating the label for a hazmat item, you must follow the platform rules to put certain items into one package. Please refer to the relationship between `sku_id` and `package_id` to determine how to follow platform rules. needs_prescription: type: boolean description: A flag to indicate whether the included product requires a prescription. gift_retail_price: type: string description: |- Retail price of the free item in orders Live giveaway, free sample and gift with purchase. For other orders, this field always returns 0. This amount can be used for free samples and live giveaway order invoice in Brazil is_unboxing_item: type: boolean description: |- If `true`, indicates the sku is a blind box item that will need be unboxed to reveal the actual product to the buyer. The actual product sku name and picture can also be updated to TikTok after the unboxing is completed. Note: This is currently only available in the US market. unboxing_sku_code: type: string description: |- A seller's third party sku code for the actual unboxed item, which warehouse fulfillment operations can reference to identify the accurate product they are shipping. Note: This is currently only available in the US market. unboxing_case_list: type: array items: $ref: "#/components/schemas/UnboxingCaseList" description: |- A seller's third party sku code for the case unboxed item, which warehouse fulfillment operations can reference to identify the accurate product they are shipping. Note: This is currently only available in the US market. sub_item_info: type: array items: $ref: "#/components/schemas/SubItemInfo" description: |- Sub items represent skus that belong to a "virtual bundle" that has been defined by a seller. The sub_item_info will include all relevant information about each item that is required to be fulfilled as part of the virtual bundle. Note: Each quantity of any sku has a unique sub_item_info "id", which allows the seller to perform line-level fulfillments, in the event the items are split across different warehouse locations. distance_shipping_fee: type: string description: |- Distance shipping fee is fee that charged charged by our logistics partner and covers the separate distance-based cost for deliveries outside Java island as a part of Horizon+ Program. Only applicable in ID Market. distance_fee: type: string description: Total distance fee for Horizon+ Program. Only applicable for ID market shipping_vat_amount: type: string description: |- Shipping vat amount Available in EU market shipping_vat_rate: type: string description: |- Shipping vat rate Available in EU market is_pod_customized: type: boolean description: Identifies if this SKU contains print on demand customization pod_info_id: type: string description: ID of the print on demand customization details. This ID can be used to query for the exact details of the customization room_id: type: string description: The unique ID of the LIVE session where the order line item was created. If the order line item was not created from a LIVE session, this field returns an empty string. product_listing_type: type: string enum: - TEMPORARY_LISTING description: |- This describes the product listing type of the SKU. Possible values: - `TEMPORARY_LISTING` GetOrderDetailResponseDataOrderLineItemItemTax: type: object properties: tax_type: type: string description: |- Tax type. - `SALES_TAX` (US market sales tax) Currently only sales tax is available. tax_amount: type: string description: Tax amount. tax_rate: type: string description: Tax rate. GetOrderDetailResponseDataOrderPackage: type: object properties: id: type: string description: Package ID GetOrderDetailResponseDataOrderRecipientAddress: type: object properties: full_address: type: string description: The complete recipient addresses information. phone_number: type: string description: The telephone number of the buyer. Please notice, if this order uses platform logistics, phone number will be desensitized. name: type: string description: The name of the recipient. Please note, if this order uses platform logistics, recipient name will be desensitized first_name: type: string description: The first name of the recipient. If the buyer does not provide their first and last name separately, this parameter will have the same value as the "name" parameter. last_name: type: string description: The last name of the recipient. If the buyer does not provide their first and last name separately, this parameter will be empty. first_name_local_script: type: string description: |- Recipient first name in katakana. **Note**: Applicable only for the JP market. last_name_local_script: type: string description: |- Recipient last name in katakana. **Note**: Applicable only for the JP market. region_code: type: string description: Region code. postal_code: type: string description: The postal code that can be used by seller for shipping (in the U.S, this is the ZIP code). post_town: type: string description: |- Post town of the address Note: Available only in UK market address_line1: type: string description: The first line of the street address. address_line2: type: string description: The second line of the street address address_line3: type: string description: The third line of the street address. address_line4: type: string description: The fourth line of the street address. district_info: type: array items: $ref: "#/components/schemas/DistrictInfo" description: District information list. delivery_preferences: $ref: "#/components/schemas/GetOrderDetailResponseDataOrderRecipientAddressDeliveryPreference" description: Contains all of the delivery instructions provided by the buyer for the shipping address. Currently, only available in the US market. address_detail: type: string description: Full buyer detail address. GetOrderDetailResponseDataOrderRecipientAddressDeliveryPreference: type: object properties: drop_off_location: type: string description: Drop-off location selected by the buyer. GetOrderListRequest: type: object properties: order_status: type: string enum: - UNPAID - ON_HOLD - AWAITING_SHIPMENT - PARTIALLY_SHIPPING - AWAITING_COLLECTION - IN_TRANSIT - DELIVERED - COMPLETED - CANCELLED x-enum-descriptions: - The order has been placed, but payment has not been completed. - The order has been accepted and is awaiting fulfillment. The buyer may still cancel without the seller’s approval. If `order_type=PRE_ORDER`, the product is still awaiting release so payment will only be authorized 1 day before the release, but the seller should start preparing for the release. - The order is ready to be shipped, but no items have been shipped yet. - Some items in the order have been shipped, but not all. - Shipping has been arranged, but the package is waiting to be collected by the carrier. - The package has been collected by the carrier and delivery is in progress. - The package has been delivered to the buyer. - The order has been completed, and no further returns or refunds are allowed. - The order has been cancelled. description: |- Specific order status. Available values: - `UNPAID`: The order has been placed, but payment has not been completed. - `ON_HOLD`: The order has been accepted and is awaiting fulfillment. The buyer may still cancel without the seller’s approval. If `order_type=PRE_ORDER`, the product is still awaiting release so payment will only be authorized 1 day before the release, but the seller should start preparing for the release. - `AWAITING_SHIPMENT`: The order is ready to be shipped, but no items have been shipped yet. - `PARTIALLY_SHIPPING`: Some items in the order have been shipped, but not all. - `AWAITING_COLLECTION`: Shipping has been arranged, but the package is waiting to be collected by the carrier. - `IN_TRANSIT`: The package has been collected by the carrier and delivery is in progress. - `DELIVERED`: The package has been delivered to the buyer. - `COMPLETED`: The order has been completed, and no further returns or refunds are allowed. - `CANCELLED`: The order has been cancelled. create_time_ge: type: integer format: int64 description: |- Filter orders to show only those that are created on or after the specified date and time. Unix timestamp. Note: `create_time_ge` and `create_time_lt` together constitute the creation time filter condition. - If `create_time_ge` is filled but `create_time_lt` is empty, `create_time_lt` will default to the current time. - If `create_time_lt` is filled but `create_time_ge` is empty, `create_time_ge` will default to the earliest shop time. create_time_lt: type: integer format: int64 description: |- Filter orders to show only those that are created before the specified date and time. Unix timestamp. Refer to notes in `create_time_ge` for more usage information. update_time_ge: type: integer format: int64 description: |- Filter orders to show only those that are updated on or after the specified date and time. Unix timestamp. Note: `update_time_ge` and `update_time_lt` together define the update time filter condition. - If `update_time_ge` is filled but `update_time_lt` is empty, `update_time_lt` will default to the current time. - If `update_time_lt` is filled but `update_time_ge` is empty, `update_time_ge` will default to the earliest shop time. Update times may exceed the selected search range due to ongoing data refreshes during the search process. update_time_lt: type: integer format: int64 description: |- Filter orders to show only those that are updated before the specified date and time. Unix timestamp. Refer to notes in `update_time_ge` for more usage information. Update times may exceed the selected search range due to ongoing data refreshes during the search process. shipping_type: type: string description: |- The delivery method. - `TIKTOK`: Shipping service provided by TikTok. The seller should obtain a shipping label from TikTok. - `SELLER`: Seller provides shipping, including through 3rd party fulfillment providers on behalf of the seller. - `TIKTOK_DIGITAL`: Tiktok delivers virtual goods directly to buyers. There is no action needed. - `IN-STORE PICKUP` : Buyer pickup the goods directly at seller location. Available for SEA market only. buyer_user_id: type: string description: Buyer user ID. is_buyer_request_cancel: type: boolean description: Whether the buyer has initiated an order cancellation request. warehouse_ids: type: array items: type: string maxItems: 100 description: |- Filter orders by pickup/sales warehouse IDs. Applicable only if the multi-warehouse feature is enabled. Max count: 100 GetOrderListResponse: 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/GetOrderListResponseData" GetOrderListResponseData: type: object properties: next_page_token: type: string description: An opaque token used to retrieve the next page of a paginated result set. Provide this value in the `page_token` parameter of your request if the current response does not return all the results. total_count: type: integer format: int64 description: Total number of orders in the search result. orders: type: array items: $ref: "#/components/schemas/GetOrderListResponseDataOrder" description: Order information. GetOrderListResponseDataOrder: type: object properties: id: type: string description: TikTok Shop order ID. buyer_message: type: string description: The note from the buyer. cancellation_initiator: type: string enum: - SELLER - BUYER - SYSTEM description: |- Cancellation request initiator. Available values: - `SELLER` - `BUYER` - `SYSTEM` shipping_provider_id: type: string description: The ID of the current shipping provider. create_time: type: integer format: int64 description: The date and time that the order was created. Unix timestamp. shipping_provider: type: string description: The name of the current shipping provider. packages: type: array items: $ref: "#/components/schemas/GetOrderListResponseDataOrderPackage" description: List of packages included in this order. payment: $ref: "#/components/schemas/Payment" description: Payment info about this order. recipient_address: $ref: "#/components/schemas/GetOrderListResponseDataOrderRecipientAddress" description: "`recipient_address` is not available under `UNPAID` and `ON_HOLD` statuses." status: type: string enum: - UNPAID - ON_HOLD - AWAITING_SHIPMENT - PARTIALLY_SHIPPING - AWAITING_COLLECTION - IN_TRANSIT - DELIVERED - COMPLETED - CANCELLED x-enum-descriptions: - The order has been placed, but payment has not been completed. - The order has been accepted and is awaiting fulfillment. The buyer may still cancel without the seller’s approval. If `order_type=PRE_ORDER`, the product is still awaiting release so payment will only be authorized 1 day before the release, but the seller should start preparing for the release. - The order is ready to be shipped, but no items have been shipped yet. - Some items in the order have been shipped, but not all. - Shipping has been arranged, but the package is waiting to be collected by the carrier. - The package has been collected by the carrier and delivery is in progress. - The package has been delivered to the buyer. - The order has been completed, and no further returns or refunds are allowed. - The order has been cancelled. description: |- Specific order status. Available values: - `UNPAID`: The order has been placed, but payment has not been completed. - `ON_HOLD`: The order has been accepted and is awaiting fulfillment. The buyer may still cancel without the seller’s approval. If `order_type=PRE_ORDER`, the product is still awaiting release so payment will only be authorized 1 day before the release, but the seller should start preparing for the release. - `AWAITING_SHIPMENT`: The order is ready to be shipped, but no items have been shipped yet. - `PARTIALLY_SHIPPING`: Some items in the order have been shipped, but not all. - `AWAITING_COLLECTION`: Shipping has been arranged, but the package is waiting to be collected by the carrier. - `IN_TRANSIT`: The package has been collected by the carrier and delivery is in progress. - `DELIVERED`: The package has been delivered to the buyer. - `COMPLETED`: The order has been completed, and no further returns or refunds are allowed. - `CANCELLED`: The order has been cancelled. fulfillment_type: type: string enum: - FULFILLMENT_BY_SELLER - FULFILLMENT_BY_TIKTOK - FULFILLMENT_BY_DILAYANI_TOKOPEDIA x-enum-descriptions: - a method where sellers fulfill orders directly from their own inventory, without using TikTok's fulfillment centers. In this model, the seller is responsible for storing, packaging, and shipping the products to customers. - a service offered by TikTok where sellers can send their products to TikTok's fulfillment centers. TikTok then takes care of storing, picking, packing, and shipping the products to customers. - a method where Tokopedia GoTo Logistics provides warehousing and logistics services to sellers and charges a fee for the service. description: |- Fulfillment type. Only orders with fulfillment type can be shipped by sellers. Available values: - `FULFILLMENT_BY_SELLER`: a method where sellers fulfill orders directly from their own inventory, without using TikTok's fulfillment centers. In this model, the seller is responsible for storing, packaging, and shipping the products to customers. - `FULFILLMENT_BY_TIKTOK`: a service offered by TikTok where sellers can send their products to TikTok's fulfillment centers. TikTok then takes care of storing, picking, packing, and shipping the products to customers. - `FULFILLMENT_BY_DILAYANI_TOKOPEDIA`: a method where Tokopedia GoTo Logistics provides warehousing and logistics services to sellers and charges a fee for the service. delivery_type: type: string enum: - HOME_DELIVERY - COLLECTION_POINT x-enum-descriptions: - not a PUDO location - a PUDO location description: |- Indicates whether it is a Pick-Up Drop-Off (PUDO) location. The PUDO location is selected by the buyer when placing orders. Available values: - `HOME_DELIVERY`: not a PUDO location - `COLLECTION_POINT`: a PUDO location paid_time: type: integer format: int64 description: The date and time that the order was paid. Unix timestamp. rts_sla_time: type: integer format: int64 description: The latest shipping time specified by the platform. Unix timestamp. tts_sla_time: type: integer format: int64 description: The latest collection time specified by the platform. Unix timestamp. cancel_reason: type: string description: The cancellation reason. Please visit [our list of cancel reasons](https://partner.tiktokshop.com/docv2/page/67e61eee427345048595487d) for more information. update_time: type: integer format: int64 description: Time of order status change. Unix timestamp. payment_method_name: type: string description: Payment method name, for display purposes. rts_time: type: integer format: int64 description: The time sellers shipped the order (called [Ship Package API](https://partner.tiktokshop.com/docv2/page/650aa4f1defece02be6e7cb1) successfully). Unix timestamp. tracking_number: type: string description: Tracking number. Available after the package has been shipped. split_or_combine_tag: type: string description: |- Indicates whether the order is combined or split: - `COMBINED` - `SPLIT` This field will be used in future fulfillment APIs. has_updated_recipient_address: type: boolean description: Whether the recipient address has been updated or changed. cancel_order_sla_time: type: integer format: int64 description: |- The automatic cancellation time for orders specified by the platform. Unix timestamp. warehouse_id: type: string description: Seller warehouse ID. request_cancel_time: type: integer format: int64 description: Buyer request cancellation time. Unix timestamp. shipping_type: type: string enum: - TIKTOK - SELLER - TIKTOK_DIGITAL x-enum-descriptions: - Shipping service provided by TikTok. The seller should obtain shipping label from TikTok. - Seller provides shipping, including through 3rd party fulfillment providers on behalf of the seller. - Tiktok delivers virtual goods directly to buyers. There is no action needed. description: |- Delivery method. Available values: - `TIKTOK`: Shipping service provided by TikTok. The seller should obtain shipping label from TikTok. - `SELLER`: Seller provides shipping, including through 3rd party fulfillment providers on behalf of the seller. - `TIKTOK_DIGITAL`: Tiktok delivers virtual goods directly to buyers. There is no action needed. user_id: type: string description: Buyer user ID. seller_note: type: string description: The seller note from TikTok Shop Seller Center. delivery_sla_time: type: integer format: int64 description: Order should arrive by this date to be considered on-time and to avoid late delivery penalties. is_cod: type: boolean description: |- This option is for sellers that accept cash payment on delivery (COD). Buyers will pay in cash upon receiving the package. Default: FALSE Only applicable to countries where COD is supported. delivery_option_id: type: string description: Delivery option ID is mapped to seller configured logistics templates ID. cancel_time: type: integer format: int64 description: The time an order's status was updated to `CANCELLED`. Unix timestamp. need_upload_invoice: type: string description: |- Whether an invoice needs to be uploaded and uploaded status (only for Brazil market). - UNKNOWN: Currently unable to confirm whether an invoice is needed - NEED_INVOICE: This order requires an invoice and the invoice has not been uploaded yet - NO_NEED：This order does not require an invoice - INVOICE_UPLOADED: The invoice for this order has been uploaded and verified. If the order is split, it will be marked as "uploaded" once any sub-order's invoice is uploaded. - INVOICE_PROCESSING: The invoice for this order is currently being uploaded/cancelled. Please wait for the final result and do not repeat the operation delivery_option_name: type: string description: |- Delivery option name. For display purposes only. Available values: - `Economy Shipping` - `Standard Shipping` - `Express Shipping` cpf: type: string description: |- CPF (invoice number), used to issue an invoice. **Note**: Only available in the Brazil market. line_items: type: array items: $ref: "#/components/schemas/GetOrderListResponseDataOrderLineItem" description: Line item info list. buyer_email: type: string description: The anonymized email address of the buyer. It is not recommended to send messages directly to this email address. If you need to contact the buyer, please go to the TikTok Shop Seller Center - Buyer Messages page. delivery_due_time: type: integer format: int64 description: If the order hasn't updated its status to `DELIVERED` before this time, the order will be automatically canceled by TikTok Shop. Unix timestamp. is_sample_order: type: boolean description: Use this field to determine whether the order is a sample order. shipping_due_time: type: integer format: int64 description: If the order hasn't updated its status to `AWAITING_COLLECTION` before this time, the order will be automatically canceled by TikTok Shop. Unix timestamp. collection_due_time: type: integer format: int64 description: If the order hasn't updated its status to `IN_TRANSIT` before this time, the order will be canceled by TikTok Shop. Unix timestamp. delivery_option_required_delivery_time: type: integer format: int64 description: Order should be delivered before this time. Unix timestamp. is_on_hold_order: type: boolean description: Indicates whether the order has been changed to or will be updated to `ON_HOLD` status. delivery_time: type: integer format: int64 description: The time an order's status changed to `DELIVERED`. Unix timestamp. is_replacement_order: type: boolean description: Whether this is a replacement order. is_subscription_order: type: boolean description: Subscription orders are recurring orders set up by customers. If TRUE, this order is generated from a subscription order is_refundable_sample: type: boolean description: This indicates if an order is a refundable sample. Refundable samples lets sellers collaborate with creators by refunding product costs only when creators meet sales thresholds. authentication_required: type: boolean description: If true, order requires authentication. Use an approved in-house authentication service after an order has been placed for verification. This must be completed before shipment. collection_time: type: integer format: int64 description: The time an order's status has been updated to `IN_TRANSIT`. Unix timestamp. replaced_order_id: type: string description: |- The order Id for the order that is being replaced. Returned only if `is_replacement_order = true`. is_buyer_request_cancel: type: boolean description: Whether the buyer has a pending cancellation request. pick_up_cut_off_time: type: integer format: int64 description: To avoid LDR, you must ensure the package is picked up by this time. Only applicable in South East Asia regions. fast_dispatch_sla_time: type: integer format: int64 description: |- The latest collection time to gain incentives of NDD (Next Day Delivery) project. Unix timestamp. **Note**: Only available in Thailand and the Philippines. commerce_platform: type: string enum: - TIKTOK_SHOP - TOKOPEDIA description: |- The platform where the order was placed. Possible values: - `TIKTOK_SHOP` - `TOKOPEDIA` **Note**: Available only in the Indonesia market. order_type: type: string enum: - NORMAL - ZERO_LOTTERY - AUCTION - PRE_ORDER - MADE_TO_ORDER - BACK_ORDER - VIRTUAL_ORDER x-enum-descriptions: - An item that is in stock and available for immediate purchase and fulfillment. - An order placed during a lottery event in TikTok LIVE. - An order placed during auction, where the price of the product is not fixed. - An advance order for items that are not yet available or released. Fulfillment starts on a specific date in the future. - An order for items that are produced only after the order is received. Fulfillment starts after the product is produced. - An order for items that are out of stock but expected to be restocked. Fulfillment starts after the product is restocked. - An order for items that are digital goods, requiring no physical delivery. Fulfillment is immediate or automated upon payment confirmation. description: |- The order type. Possible values based on region: **All regions** - `NORMAL`: An item that is in stock and available for immediate purchase and fulfillment. - `ZERO_LOTTERY`: An order placed during a lottery event in TikTok LIVE. - `AUCTION`: An order placed during auction, where the price of the product is not fixed. **US** - `PRE_ORDER`: An advance order for items that are not yet available or released. Fulfillment starts on a specific date in the future. - `MADE_TO_ORDER`: An order for items that are produced only after the order is received. Fulfillment starts after the product is produced. - `BACK_ORDER`: An order for items that are out of stock but expected to be restocked. Fulfillment starts after the product is restocked. - `VIRTUAL_ORDER`: An order for items that are digital goods, requiring no physical delivery. Fulfillment is immediate or automated upon payment confirmation. Returns an empty value for standard orders or other types that don't fall into the above categories. release_date: type: integer format: int64 description: |- The date on which order handling starts and the status of the order changes to [`AWAITING_SHIPMENT`](https://partner.tiktokshop.com/docv2/page/650b1b4bbace3e02b76d1011). Applicable only if the `order_type` is `PRE_ORDER`. handling_duration: $ref: "#/components/schemas/HandlingDuration" description: |- The duration for the seller to process the order and hand it over to a shipping carrier after the order is placed. Applicable only if the `order_type` is `MADE_TO_ORDER` or `BACK_ORDER`. auto_combine_group_id: type: string description: An identifier assigned to orders from the same customer during a LIVE session to facilitate combined order shipping when "auto-combination" is activated in Seller Center. cpf_name: type: string description: Name belonging to the CPF number for the Brazil market. is_exchange_order: type: boolean description: |- When TRUE, this is an exchange order. Note: Only available in US and UK. exchange_source_order_id: type: string description: |- If the order is an exchange order, this field returns the original order's order ID, from which the exchange order was generated. Returned only if is_exchange_order = true. Note: Only available in US and UK. consultation_id: type: string description: |- An ID to identify the corresponding ePharmacy consultation. Applicable only if an ePharmacy consultation was initiated. Not applicable if the prescription was provided by the customer through an image upload. fast_delivery_program: type: string enum: - 3_DAY_DELIVERY - 3_DAY_POTENTIAL_SHIPPING - 3_DAY_POTENTIAL_TRANSIT description: |- A badge presented on the merchandise to tell the buyer that the seller participates in the fast delivery program, such that the order should arrive in a promised time period. Possible values: - `3_DAY_DELIVERY` - `3_DAY_POTENTIAL_SHIPPING` - `3_DAY_POTENTIAL_TRANSIT` Not returned if order did not meet fast delivery program requirements. Note: Applicable only for the US market. fulfillment_priority_level: type: integer format: int64 description: |- Fulfillment priority value that can be used to prioritize shipping (only available in SEA) 100 = Instant 200 = Sameday 8 Hours 300 = Sameday 400 = Next Day Delivery 500 = Express 600 = Standard 700 = Economy 800 = Cargo recommended_shipping_time: type: integer format: int64 description: Recommended time to ship based on the each LSP service type (only available in SEA) buyer_nickname: type: string description: The nickname of the TikTok buyer, which is defined by the TikTok user. The buyer_nickname can be used to identify the buyer when displaying the unboxing results within the TikTok Live Session. buyer_avatar: type: string description: The avatar of the TikTok buyer, which is defined by the TikTok user. The buyer_avatar can be used in conjunction with the buyer_nickname when displaying the unboxing results within the TikTok Live Session. order_rights: type: array items: type: integer format: int64 description: |- Order tag identifier if has certain rights within the order based on the program subscribed by sellers. 1 = Shipping Fee Reimbursement Program 2 = Horizon+ Program Applicable for SEA market only instore_pickup_sla_time: type: integer format: int64 description: The latest buyer pickup time for instore pickup method specified by the platform. Currently applicable for SEA market. Unix timestamp. fast_rts_sla_time: type: integer format: int64 description: Indicate fast fulfillment SLA for shipping action. Applicable for SEA market only. Unix timestamp fast_collection_sla_time: type: integer format: int64 description: Indicate fast fulfillment SLA for collection action. Applicable for SEA market only. Unix timestamp GetOrderListResponseDataOrderLineItem: type: object properties: id: type: string description: Line item ID. sku_id: type: string description: SKU ID. combined_listing_skus: type: array items: $ref: "#/components/schemas/CombinedListingSku" description: For a virtual bundle SKU, returns an array of related product SKUs that compose the virtual bundle. display_status: type: string enum: - UNPAID - AWAITING_SHIPMENT - AWAITING_COLLECTION - IN_TRANSIT - DELIVERED - COMPLETED - CANCELLED x-enum-descriptions: - The order has been placed, but payment has not yet completed. - The order is ready for shipment, but no items have been shipped yet. - Shipping has been arranged, but the package is waiting to be collected by the carrier. - The package has been collected by the carrier and delivery is in progress. - The package has been delivered to the buyer. - The order has been completed, and no further returns or refunds are allowed. - The order has been cancelled. description: |- Available values: - `UNPAID`: The order has been placed, but payment has not yet completed. - `AWAITING_SHIPMENT`: The order is ready for shipment, but no items have been shipped yet. - `AWAITING_COLLECTION`: Shipping has been arranged, but the package is waiting to be collected by the carrier. - `IN_TRANSIT`: The package has been collected by the carrier and delivery is in progress. - `DELIVERED`: The package has been delivered to the buyer. - `COMPLETED`: The order has been completed, and no further returns or refunds are allowed. - `CANCELLED`: The order has been cancelled. product_name: type: string description: Product name. seller_sku: type: string description: The seller stock keeping unit (SKU) of the item. sku_image: type: string description: SKU image. sku_name: type: string description: The name of the SKU, combined by product SKU attribute like size or color. e.g. "Black, 26" product_id: type: string description: Product ID. sale_price: type: string description: Item sale price. Please refer to the currency of `payment_info`. pfand_fee: type: string description: |- Deposit fee that is applied to certain products, typically beverage containers such as bottles or cans. **Note** Only available in Germany market platform_discount: type: string description: Platform discount amount. Please refer to the currency of `payment_info`. seller_discount: type: string description: Seller discount amount. Please refer to the currency of `payment_info`. sku_type: type: string enum: - NORMAL - ZERO_LOTTERY - SHOP_PARTNER - PRE_ORDER - MADE_TO_ORDER x-enum-descriptions: - An item that is in stock and available for immediate purchase and fulfillment. - An item purchased during a lottery event in TikTok LIVE. - An item purchased from a TikTok Shop partner store. - An item that is not yet available or released. Fulfillment starts on a specific date in the future. - An item that is produced only after the order is received. Fulfillment starts after the product is produced. description: |- [**Deprecated**: This field is deprecated and will be removed in a future API version. Use `order_type` instead.] The order line type. Possible values based on region: **All regions** - `NORMAL`: An item that is in stock and available for immediate purchase and fulfillment. - `ZERO_LOTTERY`: An item purchased during a lottery event in TikTok LIVE. - `SHOP_PARTNER`: An item purchased from a TikTok Shop partner store. **US** - `PRE_ORDER`: An item that is not yet available or released. Fulfillment starts on a specific date in the future. - `MADE_TO_ORDER`: An item that is produced only after the order is received. Fulfillment starts after the product is produced. deprecated: true cancel_reason: type: string description: The cancellation reason. Please visit [our list of cancel reasons](https://partner.tiktokshop.com/docv2/page/67e61eee427345048595487d) for more information. original_price: type: string description: Item original price. Please refer to the currency of `payment_info`. rts_time: type: integer format: int64 description: The time sellers shipped the order (called [Ship Package API](https://partner.tiktokshop.com/docv2/page/650aa4f1defece02be6e7cb1) successfully). Unix timestamp. package_status: type: string enum: - TO_FULFILL - PROCESSING - FULFILLING - COMPLETED - CANCELLED x-enum-descriptions: - Package awaiting seller to arrange shipment. - Shipping has been arranged by the seller. Awaiting carrier collection. - Package has been collected by carrier and is in transit. - Package has been delivered. - Package has been canceled. Normally, the package is canceled due to the package being lost or damaged. description: |- The package status of the item. Available values: - `TO_FULFILL`: Package awaiting seller to arrange shipment. - `PROCESSING`: Shipping has been arranged by the seller. Awaiting carrier collection. - `FULFILLING`: Package has been collected by carrier and is in transit. - `COMPLETED`: Package has been delivered. - `CANCELLED`: Package has been canceled. Normally, the package is canceled due to the package being lost or damaged. currency: type: string description: Currency for payment. shipping_provider_name: type: string description: The shipping provider name. cancel_user: type: string enum: - BUYER - SELLER - OPERATOR - SYSTEM description: |- Cancellation request initiator. Available values: - `BUYER` - `SELLER` - `OPERATOR` - `SYSTEM` shipping_provider_id: type: string description: The shipping provider ID of the item. is_gift: type: boolean description: Indicates whether the current order line item is a gift. item_tax: type: array items: $ref: "#/components/schemas/ItemTax" description: Item tax detail. tracking_number: type: string description: Tracking number. Available after package has been shipped. package_id: type: string description: An order can contain one or more packages based on how the seller chooses to ship. Each package has a unique `package_id` and `tracking_id`. retail_delivery_fee: type: string description: |- Retail delivery fee (RDF). **Note**: Only available in the US market. buyer_service_fee: type: string description: |- A service fee is charged on every transaction made. The charge is applied from the fifth order onwards and collected directly from customers during checkout. **Note**: Only available in the Indonesia market. small_order_fee: type: string description: Small order fee for Thailand (TH). handling_duration_days: type: string description: |- [**Deprecated**: This field is deprecated and will be removed in a future API version. Use `handling_duration` instead.] The number of business days required for the seller to process the order and hand it over to a shipping carrier after the order is placed. Applicable only if the value for `sku_type` is `MADE_TO_ORDER`. deprecated: true is_dangerous_good: type: boolean description: Whether the SKU is a hazmat item. When creating the label for a hazmat item, you must follow the platform rules to put certain items into one package. Please refer to the relationship between `sku_id` and `package_id` to determine how to follow platform rules. needs_prescription: type: boolean description: A flag to indicate whether the included product requires a prescription. gift_retail_price: type: string description: |- Retail price of the free item in orders Live giveaway, free sample and gift with purchase. For other orders, this field always returns 0. This amount can be used for free samples and live giveaway order invoice in Brazil is_unboxing_item: type: boolean description: |- If `true`, indicates the sku is a blind box item that will need be unboxed to reveal the actual product to the buyer. The actual product sku name and picture can also be updated to TikTok after the unboxing is completed. Note: This is currently only available in the US market. unboxing_sku_code: type: string description: |- A seller's third party sku code for the actual unboxed item, which warehouse fulfillment operations can reference to identify the accurate product they are shipping. Note: This is currently only available in the US market. unboxing_case_list: type: array items: $ref: "#/components/schemas/UnboxingCaseList" description: |- A seller's third party sku code for the case unboxed item, which warehouse fulfillment operations can reference to identify the accurate product they are shipping. Note: This is currently only available in the US market. room_id: type: string description: The unique ID of the LIVE session where the order line item was created. If the order line item was not created from a LIVE session, this field returns an empty string. sub_item_info: type: array items: $ref: "#/components/schemas/SubItemInfo" description: |- Sub items represent skus that belong to a "virtual bundle" that has been defined by a seller. The sub_item_info will include all relevant information about each item that is required to be fulfilled as part of the virtual bundle. Note: Each quantity of any sku has a unique sub_item_info "id", which allows the seller to perform line-level fulfillments, in the event the items are split across different warehouse locations. distance_shipping_fee: type: string description: |- Distance shipping fee is fee that charged charged by our logistics partner and covers the separate distance-based cost for deliveries outside Java island as a part of Horizon+ Program. Only applicable in ID Market. distance_fee: type: string description: Total distance fee for Horizon+ Program. Only applicable for ID market shipping_vat_amount: type: string description: |- Shipping vat amount Available in EU market shipping_vat_rate: type: string description: |- Shipping vat rate Available in EU market is_pod_customized: type: boolean description: Identifies if this SKU contains print on demand customization pod_info_id: type: string description: ID of the print on demand customization details. This ID can be used to query for the exact details of the customization product_listing_type: type: string description: |- This describes the product listing type of the SKU. Possible values: - `TEMPORARY LISTING` GetOrderListResponseDataOrderPackage: type: object properties: id: type: string description: Package ID. GetOrderListResponseDataOrderRecipientAddress: type: object properties: full_address: type: string description: Complete recipient address information. phone_number: type: string description: |- Recipient telephone number. **Note**: If this order uses platform logistics, the phone number will be desensitized. name: type: string description: |- Recipient name. **Note**: If this order uses platform logistics, the recipient name will be desensitized. first_name: type: string description: |- Recipient first name. If the recipient first and last names are not provided separately, this parameter will have the same value as the `name` parameter. last_name: type: string description: |- Recipient last name. If the recipient first and last names are not provided separately, this parameter will be empty. first_name_local_script: type: string description: |- Recipient first name in katakana. **Note**: Applicable only for the JP market. last_name_local_script: type: string description: |- Recipient last name in katakana. **Note**: Applicable only for the JP market. address_detail: type: string description: Full recipient detailed address. address_line1: type: string description: The first line of the street address. address_line2: type: string description: The second line of the street address. address_line3: type: string description: The third line of the street address. address_line4: type: string description: The fourth line of the street address. district_info: type: array items: $ref: "#/components/schemas/DistrictInfo" description: "`district_info` is unavailable under `UNPAID` and `ON_HOLD` statuses." delivery_preferences: $ref: "#/components/schemas/GetOrderListResponseDataOrderRecipientAddressDeliveryPreference" description: Contains all of the delivery instructions provided by the recipient for the shipping address. Currently, only available in the US market. postal_code: type: string description: The postal code that can be used by seller for shipping. For the US market, this refers to the ZIP Code. region_code: type: string description: Region code. post_town: type: string description: |- Post town of the address Note: Available only in UK market GetOrderListResponseDataOrderRecipientAddressDeliveryPreference: type: object properties: drop_off_location: type: string description: Drop-off location selected by the recipient. GetOrderPriceDetailsResponse: 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/GetOrderPriceDetailsResponseData" GetOrderPriceDetailsResponseData: type: object properties: currency: type: string description: Currency Type. Three-letter code, see [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html). total: type: string description: "Total original price of the order. Calculation: `sku_list_price` + `shipping_list_price`" payment: type: string description: Amount paid by the buyer for the order. sku_list_price: type: string description: Total MSRP price of the products. sku_sale_price: type: string description: "Total promotional sale price of the products. Calculation: `sku_list_price` - `subtotal_deduction_seller` - `subtotal_deduction_platform`" subtotal: type: string description: Total promotional sale price of the products in the order, including tax. subtotal_deduction_seller: type: string description: Seller provided price discount on the product subtotal_deduction_platform: type: string description: Platform provided price discount on the product subtotal_tax_amount: type: string description: Total tax amount on the product voucher_deduction_platform: type: string description: Total product-price deduction from platform-funded vouchers for the order. voucher_deduction_seller: type: string description: Total product-price deduction from seller-funded vouchers for the order. shipping_list_price: type: string description: Original shipping price shipping_sale_price: type: string description: "Promotional shipping price. Calculation: `shipping_list_price` - `shipping_fee_deduction_seller` - `shipping_fee_deduction_platform`" shipping_fee_deduction_seller: type: string description: Shipping discount covered by the seller. shipping_fee_deduction_platform: type: string description: Shipping discount covered by the platform shipping_fee_deduction_platform_voucher: type: string description: Shipping-fee deduction from platform-funded vouchers for the order. tax_amount: type: string description: Total tax amount for the order. tax_rate: type: string description: Tax rate net_price_amount: type: string description: Order price excluding tax. cod_fee: type: string description: COD fee charged by shipping aggregators. For regions outside of Saudi Arabia, the value is `0.00`. cod_fee_net_amount: type: string description: COD fee charged by shipping aggregators including tax. For regions outside of Saudi Arabia, the value is `0.00`. sku_gift_original_price: type: string description: Original sku list price of the gift product from the seller. sku_gift_net_price: type: string description: Original sku list price of the gift product from the seller including tax. distance_shipping_fee: type: string description: |- Distance shipping fee is fee that charged charged by our logistics partner and covers the separate distance-based cost for deliveries outside Java island as a part of Horizon+ Program. Only applicable in ID Market. distance_fee: type: string description: Total distance fee for Horizon+ Program. Only applicable for ID market line_items: type: array items: $ref: "#/components/schemas/GetOrderPriceDetailsResponseDataLineItem" description: Price details for each line item in the order. GetOrderPriceDetailsResponseDataLineItem: type: object properties: id: type: string description: corresponding line_item id currency: type: string description: Currency Type. Three-letter code, see [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html). total: type: string description: "Total original price of the line item. Calculation: `sku_list_price` + `shipping_list_price`" payment: type: string description: Amount paid by the buyer for the line item. sku_list_price: type: string description: Total MSRP price of the products. sku_sale_price: type: string description: "Total promotional sale price of the products. Calculation: `sku_list_price` - `subtotal_deduction_seller` - `subtotal_deduction_platform`" subtotal: type: string description: Total promotional sale price for the line item, including tax. subtotal_deduction_seller: type: string description: Seller provided price discount on the product subtotal_deduction_platform: type: string description: Platform provided price discount on the product subtotal_tax_amount: type: string description: Total tax amount on the product voucher_deduction_platform: type: string description: Product-price deduction from platform-funded vouchers for the line item. voucher_deduction_seller: type: string description: Product-price deduction from seller-funded vouchers for the line item. shipping_list_price: type: string description: Original shipping price shipping_sale_price: type: string description: "Promotional shipping price. Calculation: `shipping_list_price` - `shipping_fee_deduction_seller` - `shipping_fee_deduction_platform`" shipping_fee_deduction_seller: type: string description: Shipping discount covered by the seller. shipping_fee_deduction_platform: type: string description: Shipping discount covered by the platform shipping_fee_deduction_platform_voucher: type: string description: Shipping-fee deduction from platform-funded vouchers for the line item. tax_amount: type: string description: Total tax amount for the line item. tax_rate: type: string description: Tax rate net_price_amount: type: string description: Line item price excluding tax. cod_fee: type: string description: COD fee charged by shipping aggregators. For regions outside of Saudi Arabia, the value is `0.00`. cod_fee_amount: type: string description: COD fee charged by shipping aggregators including tax. For regions outside of Saudi Arabia, the value is `0.00`. sku_gift_original_price: type: string description: Original sku list price of the gift product from the seller. sku_gift_net_price: type: string description: Original sku list price of the gift product from the seller including tax. distance_shipping_fee: type: string description: |- Distance shipping fee is fee that charged charged by our logistics partner and covers the separate distance-based cost for deliveries outside Java island as a part of Horizon+ Program. Only applicable in ID Market. distance_fee: type: string description: Total distance fee for Horizon+ Program. Only applicable for ID market seller_funded_product_promotions: type: array items: $ref: "#/components/schemas/GetOrderPriceDetailsResponseDataLineItemSellerFundedProductPromotion" description: Seller-funded product promotions associated with the line item. seller_funded_shipping_promotions: type: array items: $ref: "#/components/schemas/GetOrderPriceDetailsResponseDataLineItemSellerFundedShippingPromotion" description: Seller-funded shipping promotions associated with the line item. GetOrderPriceDetailsResponseDataLineItemSellerFundedProductPromotion: type: object properties: activity_id: type: string description: A unique ID that identifies different promotion activities. discount_amount: type: string description: Discount amount of this activity discount_type: type: string enum: - COUPON - ACTIVITY description: |- Discount type of this activity. Enumerations: - COUPON - ACTIVITY GetOrderPriceDetailsResponseDataLineItemSellerFundedShippingPromotion: type: object properties: activity_id: type: string description: A unique ID that identifies different promotion activities. discount_amount: type: string description: Discount amount of this activity discount_type: type: string enum: - COUPON - ACTIVITY description: |- Discount type of this activity. Enumerations: - COUPON - ACTIVITY GetOrderSplitAttributesResponse: 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/GetOrderSplitAttributesResponseData" GetOrderSplitAttributesResponseData: type: object properties: split_attributes: type: array items: $ref: "#/components/schemas/GetOrderSplitAttributesResponseDataSplitAttribute" description: Split-eligibility results for the evaluated TikTok Shop orders. Each result identifies an order and indicates whether it can be split; it may also include a reason when splitting is not allowed and mandatory package-splitting limits when applicable. GetOrderSplitAttributesResponseDataSplitAttribute: type: object properties: order_id: type: string description: TikTok Shop order ID. can_split: type: boolean description: |- Whether an order can be split: - `true`: The order can be split into multiple packages. - `false`: The order cannot be split into multiple packages. reason: type: string description: The reason why the order cannot be split. Only return this field when `can_split = false`. must_split: type: boolean description: |- Whether an order must be split: - true: The order must be split into multiple packages. - false: The order does not have to be split into multiple packages. must_split_reasons: type: array items: $ref: "#/components/schemas/GetOrderSplitAttributesResponseDataSplitAttributeMustSplitReason" description: The reason why the order must be split. Only return this field when must_split = true. GetOrderSplitAttributesResponseDataSplitAttributeMustSplitReason: type: object properties: type: type: string description: "It will return which type of verification is hit. There are two types of verification: CATEGORY_ITEM_LIMITATION means category verification and TOTAL_COUNT_LIMITATION means total product quantity verification." category_id: type: string description: The category ID associated with this split limitation. A value is returned when `type` is `CATEGORY_ITEM_LIMITATION`; no value is returned when `type` is `TOTAL_COUNT_LIMITATION`. max_count: type: string description: For category verification, return the maximum quantity of goods allowed for this category in a single package; for total product quantity verification within the package, return the total quantity limit of goods in a single package. GetOrderTrackingResponse: 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/GetOrderTrackingResponseData" GetOrderTrackingResponseData: type: object properties: tracking: type: array items: $ref: "#/components/schemas/GetOrderTrackingResponseDataTracking" description: The return list of tracking information. GetOrderTrackingResponseDataTracking: type: object properties: description: type: string description: Tracking status description. update_time_millis: type: integer format: int64 description: Tracking status update time. Unix timestamp in milliseconds. action_code: type: integer format: int64 description: Code that identifies the tracking event type. Use `description` for the human-readable event message. GetPODCustomizationDetailsRequest: type: object properties: main_order_id: type: string description: TikTok Shop order ID. query_order_lines: type: array items: $ref: "#/components/schemas/QueryOrderLine" description: A non-empty list of order lines for which to retrieve POD customization details. required: - main_order_id - query_order_lines GetPODCustomizationDetailsResponse: 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/GetPODCustomizationDetailsResponseData" GetPODCustomizationDetailsResponseData: type: object properties: pod_details: type: array items: $ref: "#/components/schemas/GetPODCustomizationDetailsResponseDataPodDetail" description: The POD customization details returned for the requested order lines. status_code: type: integer format: int64 description: response status GetPODCustomizationDetailsResponseDataPodDetail: type: object properties: pod_info_json: type: string description: A JSON-encoded string containing the POD customization template for the order line. order_line_id: type: string description: The unique identifier of the order line item. GetPackageDetailResponse: 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/GetPackageDetailResponseData" GetPackageDetailResponseData: type: object properties: package_id: type: string description: TikTok Shop package ID. orders: type: array items: $ref: "#/components/schemas/Order" description: The response list of TikTok Shop orders. package_status: type: string enum: - TO_FULFILL - PROCESSING - FULFILLING - COMPLETED - CANCELLED x-enum-descriptions: - Waiting for the merchant or warehouse to ship the package. - Package has been arranged by seller. Waiting for carrier to collect the parcel. - Package has been collected by carrier and in transit. - Package has been delivered. - Package has been canceled. Normally, the package is canceled due to the package being lost or damaged. description: |- Possible values: - `TO_FULFILL`：Waiting for the merchant or warehouse to ship the package. - `PROCESSING`: Package has been arranged by seller. Waiting for carrier to collect the parcel. - `FULFILLING`: Package has been collected by carrier and in transit. - `COMPLETED`: Package has been delivered. - `CANCELLED`: Package has been canceled. Normally, the package is canceled due to the package being lost or damaged. package_sub_status: type: string enum: - CREATED - ISSUE - STOCKING - RTSING - HBW - HBWING - TSP_PENDING - RTS - TTS - DELIVERED - SHIP_EXCEPTION - PART_DELIVERED_AND_EXCEPTION - CANCELLED x-enum-descriptions: - The package has been created. - Package allocation failed; contact platform support. - Platform verification is complete and the package is waiting for the seller to ship it. - The shipping label is being purchased and the carrier result is pending. - For FBT orders only; the package has been created in the warehouse. - For FBT orders only; the package is being created in the warehouse. - Authorization for third-party service-provider fulfillment is pending. - The shipping label has been purchased and the seller can print it. - The carrier has picked up the package. - The package has been delivered to the buyer. - The package cannot be delivered, for example because it is damaged or lost. See `ship_exception_reason` for the detailed reason. - Part of the package delivery completed and another part encountered a shipping exception. - The package has been canceled. description: |- Package sub-status. Possible values: - `CREATED`: The package has been created. - `ISSUE`: Package allocation failed; contact platform support. - `STOCKING`: Platform verification is complete and the package is waiting for the seller to ship it. - `RTSING`: The shipping label is being purchased and the carrier result is pending. - `HBW`: For FBT orders only; the package has been created in the warehouse. - `HBWING`: For FBT orders only; the package is being created in the warehouse. - `TSP_PENDING`: Authorization for third-party service-provider fulfillment is pending. - `RTS`: The shipping label has been purchased and the seller can print it. - `TTS`: The carrier has picked up the package. - `DELIVERED`: The package has been delivered to the buyer. - `SHIP_EXCEPTION`: The package cannot be delivered, for example because it is damaged or lost. See `ship_exception_reason` for the detailed reason. - `PART_DELIVERED_AND_EXCEPTION`: Part of the package delivery completed and another part encountered a shipping exception. - `CANCELLED`: The package has been canceled. ship_exception_reason: type: string description: |- -PACKAGE_DAMAGAED -PACKAGE_LOST -RETURNED_TO_SHIPPER -PACKAGE_SCRAP split_and_combine_tag: type: string enum: - DEFAULT - COMBINE - SPLIT x-enum-descriptions: - The package has not undergone any combine or split operation. - The package has been consolidated with another order. - The order has been split into multiple orders. description: |- Possible values: - `DEFAULT`: The package has not undergone any combine or split operation. - `COMBINE`: The package has been consolidated with another order. - `SPLIT`: The order has been split into multiple orders. has_multi_skus: type: boolean description: Whether there are multiple SKU IDs in a package. note_tag: type: string enum: - BUYER_UNNOTED - BUYER_NOTED x-enum-descriptions: - The order has not been noted by buyer. - The order has been noted by buyer. description: |- Possible values: - `BUYER_UNNOTED`: The order has not been noted by buyer. - `BUYER_NOTED`: The order has been noted by buyer. shipping_provider_name: type: string description: Package shipping provider name. shipping_provider_id: type: string description: Package shipping provider ID. shipping_type: type: string enum: - TIKTOK - SELLER x-enum-descriptions: - Shipping service provided by TikTok. The seller should obtain a shipping label from TikTok. - Seller provides shipping, including through a third-party fulfillment provider acting on the seller's behalf. description: |- Indicates who provides the shipping service. Possible values: - `TIKTOK`: Shipping service provided by TikTok. The seller should obtain a shipping label from TikTok. - `SELLER`: Seller provides shipping, including through a third-party fulfillment provider acting on the seller's behalf. delivery_option_name: type: string description: Delivery option name. For display purposes only. delivery_option_id: type: string description: Order delivery option ID. Delivery option ID is mapped to seller configured logistics templates ID. tracking_number: type: string description: Package tracking number. last_mile_tracking_number: type: string description: For cross-border order only. Cross-border order last mile tracking number. pickup_slot: $ref: "#/components/schemas/PickupSlot" description: The carrier pickup time slot scheduled for the package. create_time: type: integer format: int64 description: Package creation time. Unix timestamp, in seconds. handover_method: type: string enum: - PICKUP - DROP_OFF x-enum-descriptions: - A Logistics carrier will pickup the package(s) from the seller's pickup address. - Seller will need to drop off the package(s) to a designated location. description: |- Whether the package is delivered by pick up or drop off. Possible values: - `PICKUP`: A Logistics carrier will pickup the package(s) from the seller's pickup address. - `DROP_OFF`: Seller will need to drop off the package(s) to a designated location. order_line_item_ids: type: array items: type: string description: The order line item ID contained in the package. recipient_address: $ref: "#/components/schemas/GetPackageDetailResponseDataRecipientAddress" description: Recipient address and contact information. Returned personal information may be masked to protect the recipient's privacy. sender_address: $ref: "#/components/schemas/GetPackageDetailResponseDataSenderAddress" description: The sender's address and contact information. Sensitive fields may be masked. weight: $ref: "#/components/schemas/Weight" description: The weight of the scheduled package. dimension: $ref: "#/components/schemas/Dimension" description: The dimensions of the scheduled package. update_time: type: integer format: int64 description: The time when the package was last updated, as a Unix timestamp in seconds. insurance: $ref: "#/components/schemas/GetPackageDetailResponseDataInsurance" description: US only. Provides details of shipping insurance auto-enrolled during label purchase. biz_extension_tags: type: array items: type: string description: |- Special tags for current package if any. - `NON_MCF`: whether this package was shipped as a MCF order while in fact it is not. warehouse_id: type: string description: Seller Warehouse id for this package GetPackageDetailResponseDataInsurance: type: object properties: is_purchased: type: boolean description: Whether insurance has been purchased for the package. coverage_amount: type: string description: "The insurance coverage amount for the package. Units: USD." is_claim_eligible: type: boolean description: Whether the package is eligible for an insurance claim, based on eligible refund reasons. claim_status: type: string enum: - NOT_STARTED - CLAIM_PENDING - APPROVED - DECLINED x-enum-descriptions: - Claim has not been initiated for this package. - Claim is currently under review. - Claim has been approved. - Claim has been declined. description: |- The insurance claim status. Available values: - `NOT_STARTED`: Claim has not been initiated for this package. - `CLAIM_PENDING`: Claim is currently under review. - `APPROVED`: Claim has been approved. - `DECLINED`: Claim has been declined. GetPackageDetailResponseDataOrderSku: type: object properties: id: type: string description: "[Deprecated]SKU ID." deprecated: true name: type: string description: "[Deprecated]SKU name." deprecated: true image_url: type: string description: "[Deprecated]SKU image in order snapshot." deprecated: true quantity: type: integer format: int64 description: "[Deprecated]SKU quantity." deprecated: true GetPackageDetailResponseDataRecipientAddress: type: object properties: full_address: type: string description: The recipient's complete address, including geographic and detailed street-address information. phone_number: type: string description: The telephone number of the buyer. Please note, if this order use platform logistics, phone number will be desensitized. name: type: string description: The name of the recipient. Please note, if this order uses platform logistics, recipient name will be desensitized postal_code: type: string description: The postal code that can be used by seller for shipping (in the U.S, this refers to the ZIP code). address_detail: type: string description: The detailed street-address portion of the recipient's address. region_code: type: string description: The country or region code of the recipient address. address_line1: type: string description: The first line of the street address address_line2: type: string description: The second line of the street address. address_line3: type: string description: The third line of the street address. Usually only for the Brazilian market. address_line4: type: string description: The fourth line of the street address. Usually only for the Brazilian market. GetPackageDetailResponseDataSenderAddress: type: object properties: full_address: type: string description: The complete sender address, including geographic address components and address details. phone_number: type: string description: The telephone number of the sender. name: type: string description: The name of the sender. postal_code: type: string description: The postal code of the sender. address_detail: type: string description: The detailed street-address portion of the sender's address. region_code: type: string description: Region code of the sender. address_line1: type: string description: The first line of the sender's street address. address_line2: type: string description: The second line of the sender's street address. address_line3: type: string description: The third line of the sender's street address. Usually only for the Brazilian market. address_line4: type: string description: The fourth line of the sender's street address. Usually only for the Brazilian market. GetPackageHandoverTimeSlotsResponse: 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/GetPackageHandoverTimeSlotsResponseData" GetPackageHandoverTimeSlotsResponseData: type: object properties: can_pickup: type: boolean description: Whether this package supports door-to-door collection. can_drop_off: type: boolean description: Whether this package be dropped off at a drop-off location can_van_collection: type: boolean description: Specific to UK. Use this field to determine whether van collection is available. drop_off_point_url: type: string description: View package drop-off locations via provided URL. pickup_slots: type: array items: $ref: "#/components/schemas/GetPackageHandoverTimeSlotsResponseDataPickupSlot" description: Door-to-door collection time slots. Check `avaliable` to determine whether each time slot can be scheduled. GetPackageHandoverTimeSlotsResponseDataPickupSlot: type: object properties: start_time: type: integer format: int64 description: The start of the package pickup time slot, as a Unix timestamp in seconds. end_time: type: integer format: int64 description: The end of the package pickup time slot, as a Unix timestamp in seconds. avaliable: type: boolean description: Whether an appointment be made for this time slot. GetPackageShippingDocumentResponse: 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/GetPackageShippingDocumentResponseData" GetPackageShippingDocumentResponseData: type: object properties: doc_url: type: string description: The URL of the shipping document generated for the specified package according to the requested `document_type`. The URL is valid for 24 hours. tracking_number: type: string description: The package tracking number from the shipping carrier. GetPaymentsResponse: 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/GetPaymentsResponseData" GetPaymentsResponseData: type: object properties: next_page_token: type: string description: An opaque token used to retrieve the next page of a paginated result set. Provide this value in the `page_token` parameter of your request if the current response does not return all the results. An empty string means there is no next page. payments: type: array items: $ref: "#/components/schemas/GetPaymentsResponseDataPayment" description: The list of payments that meet the query conditions. GetPaymentsResponseDataPayment: type: object properties: create_time: type: integer format: int64 description: The time when the payment was initiated in TikTok Shop, as a Unix timestamp in seconds. id: type: string description: The payment ID. status: type: string enum: - PAID - FAILED - PROCESSING x-enum-descriptions: - Payment has been transferred to the seller. - Payment transfer failed. - Payment is currently being processed. description: |- The payment status, indicating whether payment has been transferred to the seller's bank account. Possible values: - PAID: Payment has been transferred to the seller. - FAILED: Payment transfer failed. - PROCESSING: Payment is currently being processed. amount: $ref: "#/components/schemas/GetPaymentsResponseDataPaymentAmount" description: The final payment amount after currency exchange. settlement_amount: $ref: "#/components/schemas/GetPaymentsResponseDataPaymentSettlementAmount" description: The settlement amount before currency exchange. payment_amount_before_exchange: $ref: "#/components/schemas/GetPaymentsResponseDataPaymentPaymentAmountBeforeExchange" description: The original payment amount before currency exchange. exchange_rate: type: string description: The exchange rate, displayed with six decimal places. paid_time: type: integer format: int64 description: The time when payment processing finished in TikTok Shop, as a Unix timestamp in seconds. Returns `0` when no finish time is available. bank_account: type: string description: The seller's bank account number masked, revealing only the last 4 digits for privacy. GetPaymentsResponseDataPaymentAmount: type: object properties: value: type: string description: The final payment amount. currency: type: string description: The exchange currency code in ISO 4217 format. GetPaymentsResponseDataPaymentPaymentAmountBeforeExchange: type: object properties: value: type: string description: The original payment amount. currency: type: string description: The original currency code in ISO 4217 format. GetPaymentsResponseDataPaymentSettlementAmount: type: object properties: value: type: string description: The settlement amount. currency: type: string description: The original currency code in ISO 4217 format. GetProductDiagnosesResponse: 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/GetProductDiagnosesResponseData" GetProductDiagnosesResponseData: type: object properties: products: type: array items: $ref: "#/components/schemas/GetProductDiagnosesResponseDataProduct" description: The list of requested products and the corresponding diagnosis results. GetProductDiagnosesResponseDataProduct: type: object properties: id: type: string description: The product ID. listing_quality: $ref: "#/components/schemas/ListingQuality" description: Product listing quality information. diagnoses: type: array items: $ref: "#/components/schemas/Diagnosis" description: Product diagnosis and optimization information. GetProductPackageRecommendationsRequest: type: object properties: product_ids: type: array items: type: string description: A JSON array of product IDs for which to retrieve package recommendations. GetProductPackageRecommendationsResponse: 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/GetProductPackageRecommendationsResponseData" GetProductPackageRecommendationsResponseData: type: object properties: next_page_token: type: string description: An opaque token used to retrieve the next page of a paginated result set. Provide this value in the `page_token` parameter of your request if the current response does not return all the results. total_count: type: integer format: int64 description: The total number of products that meet the query conditions. products: type: array items: $ref: "#/components/schemas/GetProductPackageRecommendationsResponseDataProduct" description: The product package recommendations that meet the query conditions. Each item identifies a product and provides detected anomaly types with any available weight or dimension correction range. GetProductPackageRecommendationsResponseDataProduct: type: object properties: product_id: type: string description: The product ID generated by TikTok Shop. abnormality_types: type: array items: type: string enum: - None - Dimension - Weight x-enum-descriptions: - No weight or dimension anomaly was detected. - A dimension correction is recommended. - A weight correction is recommended. description: |- The detected package anomaly types. Possible values: - `None`: No weight or dimension anomaly was detected. - `Dimension`: A dimension correction is recommended. - `Weight`: A weight correction is recommended. weight_recommendation: $ref: "#/components/schemas/GetProductPackageRecommendationsResponseDataProductWeightRecommendation" description: Weight correction recommendation (Returned only when the weight of product has been recommended ). dimension_recommendation: $ref: "#/components/schemas/GetProductPackageRecommendationsResponseDataProductDimensionRecommendation" description: Dimension correction recommendation (Returned only when the dimensions of product has been recommended). GetProductPackageRecommendationsResponseDataProductDimensionRecommendation: type: object properties: unit: type: string description: Unit of dimension, fixed as centimeter. length: $ref: "#/components/schemas/GetProductPackageRecommendationsResponseDataProductDimensionRecommendationLength" description: Recommended values for length. height: $ref: "#/components/schemas/GetProductPackageRecommendationsResponseDataProductDimensionRecommendationHeight" description: Recommended values for height (structure same as length). width: $ref: "#/components/schemas/GetProductPackageRecommendationsResponseDataProductDimensionRecommendationWidth" description: Recommended values for width (structure same as length). GetProductPackageRecommendationsResponseDataProductDimensionRecommendationHeight: type: object properties: min_value: type: string description: "Recommended range minimum; unit: cm" max_value: type: string description: "Recommended range maximum; unit: cm" GetProductPackageRecommendationsResponseDataProductDimensionRecommendationLength: type: object properties: min_value: type: string description: "Recommended range minimum; unit: cm" max_value: type: string description: "Recommended range maximum; unit: cm" GetProductPackageRecommendationsResponseDataProductDimensionRecommendationWidth: type: object properties: min_value: type: string description: "Recommended range minimum; unit: cm" max_value: type: string description: "Recommended range maximum; unit: cm" GetProductPackageRecommendationsResponseDataProductWeightRecommendation: type: object properties: unit: type: string description: Unit of weight, fixed as GRAM. weight: $ref: "#/components/schemas/GetProductPackageRecommendationsResponseDataProductWeightRecommendationWeight" description: Recommended values for weight. GetProductPackageRecommendationsResponseDataProductWeightRecommendationWeight: type: object properties: min_value: type: string description: "Recommended range minimum; unit: g" max_value: type: string description: "Recommended range maximum; unit: g" GetProductResponse: 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/GetProductResponseData" GetProductResponseData: type: object properties: audit: $ref: "#/components/schemas/GetProductResponseDataAudit" description: |- Product audit information. **Note**: Applicable only to products listed on TikTok Shop. Not applicable for products listed only on Tokopedia. audit_failed_reasons: type: array items: $ref: "#/components/schemas/GetProductResponseDataAuditFailedReason" description: TikTok Shop audit failure information. brand: $ref: "#/components/schemas/Brand" description: Product brand information. category_chains: type: array items: $ref: "#/components/schemas/GetProductResponseDataCategoryChain" description: Product category tree information. certifications: type: array items: $ref: "#/components/schemas/GetProductResponseDataCertification" description: The list of certifications for your product. create_time: type: integer format: int64 description: The time when the product was created, expressed as a Unix timestamp in seconds. delivery_options: type: array items: $ref: "#/components/schemas/GetProductResponseDataDeliveryOption" description: |- The custom delivery options applied to this product, overriding the default warehouse delivery option. **Note**: This field is not supported in post-live drafts, therefore the values here will always reflect those in the base version, even if you set `return_draft_version=true`. description: type: string description: The product description in HTML format. external_product_id: type: string description: An external identifier used in an external ecommerce platform. This is used to associate the product between TikTok Shop and the external ecommerce platform. global_product_association: $ref: "#/components/schemas/GetProductResponseDataGlobalProductAssociation" description: |- The global product association established through global product publishing or manual binding. **Note**: - Applicable for global sellers and intra-EU sellers. - Not applicable for EU sellers who synchronized products from other markets using the Global Product Replicate (GPR) tool. Refer to `global_listing_policy` instead to find the associated source products. has_draft: type: boolean description: |- A flag to indicate if the product has a draft. - true: It has a draft. - false: It does not have a draft. id: type: string description: The product ID generated by TikTok Shop. integrated_platform_statuses: type: array items: $ref: "#/components/schemas/GetProductResponseDataIntegratedPlatformStatus" description: |- The current status of the product on platforms that are natively integrated with TikTok Shop (e.g. TOKOPEDIA). **Note**: For Indonesia sellers, if you did not set the listing platform as `TOKOPEDIA` when creating or editing a product, this will be omitted. is_cod_allowed: type: boolean description: |- A flag indicating whether to show the Cash On Delivery (COD) payment option during checkout. Applicable only for the following markets: - Global sellers: MY, PH, SA, TH, VN - Local sellers: ID, MY, PH, SA, TH, VN is_not_for_sale: type: boolean description: |- A flag indicating whether the product is not for sale and only available through Gift with Purchase (GWP) promotions. Such products won't appear in searches or recommendations True: Not for sale False: For sale is_pre_owned: type: boolean description: |- A flag to indicate if the product is pre-owned. Applicable only if TOKOPEDIA is the sole listing platform. **Note**: Pre-owned products on the TikTok Shop platform are identified by the `category_id`, which must belong to one of the designated pre-owned product categories (e.g. pre-owned luxury bags, luggage, and accessories). is_replicated: type: boolean description: A flag to indicate if the product contains a replica (created through local replication) in other local markets. key_product_features: type: array items: type: string maxItems: 5 description: Key Product Features. They will be displayed in the Product highlight module on the product detail page and will be used by search engines to increase your search weight for more traffic. The total number of items should not exceed 5, and the total character count should not exceed 1500. listing_quality_tier: type: string enum: - POOR - FAIR - GOOD - EXCELLENT description: |- The current quality tier of this product listing. The quality tier of a product listing depends on the quality of the content in its product fields such as the title, image, attributes etc. Possible values: - POOR - FAIR - GOOD - EXCELLENT **Note**: Available only for the US market. main_images: type: array items: $ref: "#/components/schemas/GetProductResponseDataMainImage" description: A list of images to display in the product image gallery. manufacturer_ids: type: array items: type: string description: |- The list of manufacturer IDs. Pass this value to the `manufacturer_id` field in the [Search Manufacturers API](67066a580dcee902fa03ccf9) to obtain more information about a manufacturer. **Note**: Applicable only for the EU market in certain categories minimum_order_quantity: type: integer format: int64 minimum: 1 maximum: 20 description: |- The minimum order quantity for the product. Valid range: [1, 20] Applicable only for the Indonesia market and selected sellers in other SEA markets. Contact your account manager for more information about gaining access to this field. package_dimensions: $ref: "#/components/schemas/GetProductResponseDataPackageDimension" description: The dimensions of the product package package_weight: $ref: "#/components/schemas/GetProductResponseDataPackageWeight" description: The weight of the product package. pod_info: $ref: "#/components/schemas/GetProductResponseDataPodInfo" description: POD customization configuration for an MTO product. This object contains consumer-customizable templates, surfaces, and customization areas for Print-On-Demand products. prescription_requirement: $ref: "#/components/schemas/GetProductResponseDataPrescriptionRequirement" description: |- Prescription related information for the product. **Note**: Applicable only for Tokopedia. This object is returned for all pharmacy products, and omitted for non-pharmacy products. primary_combined_product_id: type: string description: If the product is a virtual bundle, this value is the ID of the primary product in the bundle. The value is omitted if the product is not a virtual bundle. product_attributes: type: array items: $ref: "#/components/schemas/GetProductResponseDataProductAttribute" description: A list of general attributes (e.g. manufacturer, country of origin, materials used) that describe the product as a whole, regardless of variant. product_families: type: array items: $ref: "#/components/schemas/ProductFamily" description: |- The **live** product family that this product belongs to. A product family is a virtual group of products that share common characteristics (such as flavor, version, or size), allowing them to appear as selectable variations on the product page. **Note**: - Applicable only for US local sellers. - Omitted if this product does not belong to any product family. product_status: type: string enum: - INITIAL - DRAFT - ACTIVATE - SELLER_DEACTIVATED - PLATFORM_DEACTIVATED - FREEZE - DELETED description: |- The product status in TikTok Shop unrelated to its audit status. Possible values: - INITIAL - DRAFT - ACTIVATE - SELLER_DEACTIVATED - PLATFORM_DEACTIVATED - FREEZE - DELETED **Note**: For Indonesia sellers, if you did not set the listing platform as `TIKTOK_SHOP` when creating or editing a product, this will be omitted. product_tags: type: array items: type: string enum: - AUCTION description: |- Product tag to identity special type product Possible values: AUCTION product_types: type: array items: type: string enum: - COMBINED_PRODUCT - IN_COMBINED_PRODUCT - GPR_TARGET_PRODUCT x-enum-descriptions: - Indicates this is a virtual bundle product. - Indicates this product is part of a virtual bundle. - Indicates this product is synchronized to global listings. Applicable only for the EU market. description: |- The product type. Possible values: - COMBINED_PRODUCT: Indicates this is a virtual bundle product. - IN_COMBINED_PRODUCT: Indicates this product is part of a virtual bundle. - GPR_TARGET_PRODUCT: Indicates this product is synchronized to global listings. Applicable only for the EU market. recommended_categories: type: array items: $ref: "#/components/schemas/RecommendedCategory" description: Recommended categories for the product based on the product title, description, and images. responsible_person_ids: type: array items: type: string description: |- The list of responsible person IDs. Pass this value to the `responsible_person_id` field in the [Search Responsible Persons API](67066a55f17b7d02f95d2fb1) to obtain more information about a responsible person. **Note**: Applicable only for the EU market in certain categories scheduled_sale: $ref: "#/components/schemas/GetProductResponseDataScheduledSale" description: Scheduled listing configuration for the product, including whether scheduled listing is enabled and the scheduled listing time. search_terms: type: array items: type: string description: Search terms (ST words). ST words will not be displayed to consumers; they are only used in search engines to increase your search weight and gain more traffic. Please ensure that ST words are consistent with the product description, with a maximum of 15 terms and a total of no more than 250 characters. shipping_insurance_requirement: type: string enum: - REQUIRED - OPTIONAL - NOT_SUPPORTED x-enum-descriptions: - Shipping insurance is mandatory and buyers can't opt out. - Buyers can choose to purchase shipping insurance through the platform. - Shipping insurance is not supported for the product. description: |- The shipping insurance purchase requirement imposed on buyers for the product. Possible values: - REQUIRED: Shipping insurance is mandatory and buyers can't opt out. - OPTIONAL: Buyers can choose to purchase shipping insurance through the platform. - NOT_SUPPORTED: Shipping insurance is not supported for the product. Default: OPTIONAL Applicable only if the listing platforms include TOKOPEDIA. shipping_template_id: type: string description: Identifier of the shipping template that was bound to the product size_chart: $ref: "#/components/schemas/GetProductResponseDataSizeChart" description: The measurement details of the product to help buyers find the right size. skus: type: array items: $ref: "#/components/schemas/GetProductResponseDataSku" description: A list of Stock Keeping Units (SKUs) used to identify distinct variants of the product. status: type: string enum: - DRAFT - PENDING - FAILED - ACTIVATE - SELLER_DEACTIVATED - PLATFORM_DEACTIVATED - FREEZE - DELETED - SCHEDULED description: |- The product status in TikTok Shop. This status incorporates both the product status and the audit status. Possible values: - DRAFT - PENDING - FAILED - ACTIVATE - SELLER_DEACTIVATED - PLATFORM_DEACTIVATED - FREEZE - DELETED - SCHEDULED **Note**: For Indonesia sellers, if you did not set the listing platform as `TIKTOK_SHOP` when creating or editing a product, this will be omitted. subscribe_info: $ref: "#/components/schemas/GetProductResponseDataSubscribeInfo" description: All the Save and Subscribe promotion info associated with the given product. title: type: string description: The product title. update_time: type: integer format: int64 description: The time when the product was last updated, expressed as a Unix timestamp in seconds. video: $ref: "#/components/schemas/GetProductResponseDataVideo" description: Product video information. selling_format: type: string enum: - FIXED_PRICE - LIVE_AUCTION - FIXED_PRICE_AND_LIVE_AUCTION description: "The product's sale format. Possible values: FIXED_PRICE, LIVE_AUCTION, FIXED_PRICE_AND_LIVE_AUCTION." is_blind_box: type: boolean description: "Whether the product is a blind box of lucky bag. For example: PopMart" GetProductResponseDataAudit: type: object properties: pre_approved_reasons: type: array items: type: string enum: - KYC_PENDING - RESTRICTED_CATEGORY_PENDING x-enum-descriptions: - The seller's onboarding (KYC - Know Your Customer information) is incomplete or awaiting processing. - The product is in a restricted category, and category approval is still pending. To request access, submit an application through the Qualification Center on TikTok Shop Seller Center. Applicable only for the US market. description: |- The reason why the product is pre-approved. Applicable only if `audit.status=PRE_APPROVED`, otherwise returns an empty array. Possible values: - KYC_PENDING: The seller's onboarding (KYC - Know Your Customer information) is incomplete or awaiting processing. - RESTRICTED_CATEGORY_PENDING: The product is in a restricted category, and category approval is still pending. To request access, submit an application through the Qualification Center on TikTok Shop Seller Center. Applicable only for the US market. status: type: string enum: - NONE - AUDITING - FAILED - PRE_APPROVED - APPROVED x-enum-descriptions: - The product is not applicable for audit because it has not been submitted for listing on this platform, or it is in a draft, frozen, or deactivated state. - The product is currently being audited. - The product failed the audit, or the audit was cancelled. - The product has passed the audit but is not yet listed due to pending prerequisites. Refer to `pre_approved_reasons` for the prerequisites. - The product passed the audit and has been listed on the platform. description: |- The product audit status. Possible values: - NONE: The product is not applicable for audit because it has not been submitted for listing on this platform, or it is in a draft, frozen, or deactivated state. - AUDITING: The product is currently being audited. - FAILED: The product failed the audit, or the audit was cancelled. - PRE_APPROVED: The product has passed the audit but is not yet listed due to pending prerequisites. Refer to `pre_approved_reasons` for the prerequisites. - APPROVED: The product passed the audit and has been listed on the platform. not_submitted_reasons: type: array items: type: string enum: - PAYMENT_ACCOUNT_NOT_LINKED - SHOP_INACTIVE - W8_NOT_CONFIGURED x-enum-descriptions: - No payment account is linked to the shop. - The shop is inactive. - The required W-8 tax information has not been provided for the shop. Applicable only to US shops. description: |- The reasons why the product has not been submitted for TikTok Shop audit. Applicable only when `audit.status=NONE` and the product cannot be submitted for audit because the shop has not met one or more listing prerequisites; otherwise, an empty array is returned. Possible values: - PAYMENT_ACCOUNT_NOT_LINKED: No payment account is linked to the shop. - SHOP_INACTIVE: The shop is inactive. - W8_NOT_CONFIGURED: The required W-8 tax information has not been provided for the shop. Applicable only to US shops. GetProductResponseDataAuditFailedReason: type: object properties: listing_platform: type: string enum: - TIKTOK_SHOP - TOKOPEDIA description: |- The platform for listing the product. Possible values: - TIKTOK_SHOP - TOKOPEDIA position: type: string description: The audit failure reason name. reasons: type: array items: type: string description: A brief reason for failing TikTok Shop audit. suggestions: type: array items: type: string description: A detailed explanation of the reason for failure. GetProductResponseDataCategoryChain: type: object properties: id: type: string description: The ID of the category of this product. is_leaf: type: boolean description: |- A flag to indicate if the category is a leaf category. **Note**: You can only create or edit products that belong to a leaf category. local_name: type: string description: The category name in the requested locale. parent_id: type: string description: |- The parent category ID. For the root category, the parent ID is `0`. GetProductResponseDataCertification: type: object properties: expiration_date: type: integer format: int64 description: The expiration date of this certification expressed in unix timestamp (seconds) UTC+0. files: type: array items: $ref: "#/components/schemas/GetProductResponseDataCertificationFile" description: A list of certification related files. id: type: string description: The ID to identify the type of certification required for the product. images: type: array items: $ref: "#/components/schemas/GetProductResponseDataCertificationImage" description: A list of certification related images. title: type: string description: The title of the certification type. GetProductResponseDataCertificationFile: type: object properties: format: type: string description: The format of the certification file. id: type: string description: The ID of the certification file. name: type: string description: The name of the certification file. urls: type: array items: type: string description: The URLs to view the certification files. GetProductResponseDataCertificationImage: type: object properties: height: type: integer format: int64 description: |- The image height. Unit: px thumb_urls: type: array items: type: string description: The URLs to view the image thumbnails. uri: type: string description: The URI of the image. urls: type: array items: type: string description: The URLs to view the images. width: type: integer format: int64 description: |- The image width. Unit: px GetProductResponseDataDeliveryOption: type: object properties: id: type: string description: The delivery option ID. is_available: type: boolean description: A flag indicating whether the delivery option is available for this product. name: type: string description: The delivery option name. GetProductResponseDataGlobalProductAssociation: type: object properties: global_product_id: type: string description: The global product ID in TikTok Shop. sku_mappings: type: array items: $ref: "#/components/schemas/GetProductResponseDataGlobalProductAssociationSkuMapping" description: The list of sku mappings between the global and local products. GetProductResponseDataGlobalProductAssociationSkuMapping: type: object properties: global_sku_id: type: string description: The global SKU ID in TikTok Shop. local_sku_id: type: string description: The local SKU ID in TikTok Shop. sales_attribute_mappings: type: array items: $ref: "#/components/schemas/GetProductResponseDataGlobalProductAssociationSkuMappingSalesAttributeMapping" description: The list of sales attribute mappings between the global and local SKUs. GetProductResponseDataGlobalProductAssociationSkuMappingSalesAttributeMapping: type: object properties: global_attribute_id: type: string description: The global sales attribute ID. global_value_id: type: string description: The global sales attribute value ID. local_attribute_id: type: string description: The local sales attribute ID. local_value_id: type: string description: The local sales attribute value ID. GetProductResponseDataIntegratedPlatformStatus: type: object properties: platform: type: string enum: - TOKOPEDIA description: |- The integrated platform name. Possible values: - TOKOPEDIA status: type: string enum: - UNKNOWN - DRAFT - PENDING - FAILED - ACTIVATE - SELLER_DEACTIVATED - PLATFORM_DEACTIVATED - FREEZE - DELETED description: |- The product status in the integrated platform. Possible values: - UNKNOWN - DRAFT - PENDING - FAILED - ACTIVATE - SELLER_DEACTIVATED - PLATFORM_DEACTIVATED - FREEZE - DELETED GetProductResponseDataMainImage: type: object properties: height: type: integer format: int64 description: |- The image height. Unit: px thumb_urls: type: array items: type: string description: The URLs to view the image thumbnails. uri: type: string description: The URI of the image. urls: type: array items: type: string description: The URLs to view the images. width: type: integer format: int64 description: |- The image width. Unit: px GetProductResponseDataPackageDimension: type: object properties: height: type: string description: The package height. length: type: string description: The package length. unit: type: string description: The unit for the package dimensions. width: type: string description: The package width. GetProductResponseDataPackageWeight: type: object properties: unit: type: string enum: - KILOGRAM - POUND description: |- The unit for the package weight. Possible values: - `KILOGRAM` - `POUND` value: type: string description: The package weight. GetProductResponseDataPodInfo: type: object properties: pod_templates: type: array items: $ref: "#/components/schemas/GetProductResponseDataPodInfoPodTemplate" description: A list of POD customization templates. Each template represents one customization plan and can be associated with one or more SKUs. GetProductResponseDataPodInfoPodTemplate: type: object properties: pod_template_id: type: string description: The unique identifier of the POD customization template. remark: type: string description: Optional notes or instructions for this customization template. These notes may be used to remind consumers about customization requirements on the customization page. sku_ids: type: array items: type: string description: A list of product SKU IDs associated with this customization template. The same SKU cannot be associated with more than one template. surfaces: type: array items: $ref: "#/components/schemas/GetProductResponseDataPodInfoPodTemplateSurface" maxItems: 10 description: A list of customizable product surfaces under this template, such as the front side, back side, collar, or sleeve. A template can contain up to 10 surfaces. template_name: type: string description: The name of the customization template, used by the seller for internal management. GetProductResponseDataPodInfoPodTemplateSurface: type: object properties: background_image: $ref: "#/components/schemas/GetProductResponseDataPodInfoPodTemplateSurfaceBackgroundImage" description: The background image of the customizable surface. It is usually the base product image on which customization areas are configured. custom_areas: type: array items: $ref: "#/components/schemas/GetProductResponseDataPodInfoPodTemplateSurfaceCustomArea" maxItems: 10 description: A list of customizable areas on this surface. The order of the elements represents the layer order to be used when rendering the final customization preview. A surface can contain up to 10 customization areas. external_surface_id: type: string description: The seller-defined external identifier of the customizable surface, used for mapping with the seller's own system. mask_image: $ref: "#/components/schemas/GetProductResponseDataPodInfoPodTemplateSurfaceMaskImage" description: An optional mask image placed above the customization areas to support irregular or cut-out effects. surface_name: type: string description: The name of the customizable surface, for example, `Front Side` or `Back Side`. GetProductResponseDataPodInfoPodTemplateSurfaceBackgroundImage: type: object properties: height: type: integer format: int64 description: The height of the background image, in pixels. thumb_urls: type: array items: type: string description: A list of thumbnail URLs for the background image. uri: type: string description: |- The URI of the background image. Obtain this URI by uploading the images through the [Upload Product Image API](6509df95defece02be598a22) with `use_case=CUSTOMIZATION_IMAGE`. urls: type: array items: type: string description: A list of URLs for the background image. width: type: integer format: int64 description: The width of the background image, in pixels. GetProductResponseDataPodInfoPodTemplateSurfaceCustomArea: type: object properties: area_name: type: string description: The name of the customizable area. area_placement: $ref: "#/components/schemas/AreaPlacement" description: The position, size, and rotation information of the customizable area on the surface. area_type: type: string description: "The type of the customizable area. Enum values: `TEXT`, `IMAGE`." external_area_id: type: string description: The seller-defined external identifier of the customizable area, used for mapping with the seller's own system. image_area: $ref: "#/components/schemas/GetProductResponseDataPodInfoPodTemplateSurfaceCustomAreaImageArea" description: Configuration for an image-type customization area. This field is returned when `area_type` is `IMAGE`. is_required: type: boolean description: Specifies whether the consumer must provide customization content for this area. If set to `false`, the default content or base product version may be used. text_area: $ref: "#/components/schemas/TextArea" description: Configuration for a text-type customization area. This field is returned when `area_type` is `TEXT`. GetProductResponseDataPodInfoPodTemplateSurfaceCustomAreaImageArea: type: object properties: default_image: $ref: "#/components/schemas/GetProductResponseDataPodInfoPodTemplateSurfaceCustomAreaImageAreaDefaultImage" description: Optional default image displayed in this area. If the consumer does not upload a custom image, the default image may be used. min_height: type: integer format: int64 description: The minimum required height, in pixels, for an image uploaded by the consumer. min_width: type: integer format: int64 description: The minimum required width, in pixels, for an image uploaded by the consumer. GetProductResponseDataPodInfoPodTemplateSurfaceCustomAreaImageAreaDefaultImage: type: object properties: height: type: integer format: int64 description: The height of the default image, in pixels. thumb_urls: type: array items: type: string description: A list of thumbnail URLs for the default image. uri: type: string description: |- The URI of the default image. Obtain this URI by uploading the images through the [Upload Product Image API](6509df95defece02be598a22) with `use_case=CUSTOMIZATION_IMAGE`. urls: type: array items: type: string description: A list of URLs for the default image. width: type: integer format: int64 description: The width of the default image, in pixels. GetProductResponseDataPodInfoPodTemplateSurfaceMaskImage: type: object properties: height: type: integer format: int64 description: The height of the mask image, in pixels. thumb_urls: type: array items: type: string description: A list of thumbnail URLs for the mask image. uri: type: string description: |- The URI of the mask image. Obtain this URI by uploading the images through the [Upload Product Image API](6509df95defece02be598a22) with `use_case=CUSTOMIZATION_IMAGE`. urls: type: array items: type: string description: A list of URLs for the mask image. width: type: integer format: int64 description: The width of the mask image, in pixels. GetProductResponseDataPrescriptionRequirement: type: object properties: needs_prescription: type: boolean description: A flag to indicate whether a prescription is required to purchase this pharmacy product. GetProductResponseDataProductAttribute: type: object properties: id: type: string description: The ID of the product attribute. name: type: string description: The product attribute name. values: type: array items: $ref: "#/components/schemas/GetProductResponseDataProductAttributeValue" description: A list of selectable values for the product attribute. GetProductResponseDataProductAttributeValue: type: object properties: id: type: string description: The product attribute value ID. name: type: string description: The product attribute value name. metric_standard_info: $ref: "#/components/schemas/GetProductResponseDataProductAttributeValueMetricStandardInfo" description: Defines the measurement template information used to describe the measurement standards and metric values configured for the product. GetProductResponseDataProductAttributeValueMetricStandardInfo: type: object properties: id: type: string description: The unique ID of the measurement template. Use this ID to identify which measurement standard template applies to the product. metric_value_module_infos: type: array items: $ref: "#/components/schemas/GetProductResponseDataProductAttributeValueMetricStandardInfoMetricValueModuleInfo" description: The list of metric value entries under the measurement template. Each object represents the value submitted by the seller for a specific metric in the template. GetProductResponseDataProductAttributeValueMetricStandardInfoMetricValueModuleInfo: type: object properties: id: type: string description: The unique ID of a metric item within the measurement template. This ID identifies which metric the submitted value belongs to. value: type: string description: The seller-provided value for the specified metric item in the measurement template. unit_id: type: string description: Metric value module unit id. unit_name: type: string description: Metric value module unit name. suffix: type: string description: Metric value suffix. prefix: type: string description: Metric value prefix. GetProductResponseDataScheduledSale: type: object properties: is_enabled_scheduled_sale: type: boolean description: Whether scheduled listing is enabled for this product. schedule_sale_time: type: integer format: int64 description: The stored scheduled listing time, expressed as a Unix timestamp in milliseconds. GetProductResponseDataSizeChart: type: object properties: image: $ref: "#/components/schemas/GetProductResponseDataCertificationImage" description: An image of the size chart. template: $ref: "#/components/schemas/DiagnoseAndOptimizeProductRequestSizeChartTemplate" description: A TikTok Shop size chart template generated by the size chart tool in Seller Center > Manage Products > Bulk action > Batch manage size charts. GetProductResponseDataSku: type: object properties: combined_skus: type: array items: $ref: "#/components/schemas/GetProductResponseDataSkuCombinedSku" description: If this SKU belongs to a virtual bundle, this object contains the list of individual SKUs that form the bundle (e.g. gift basket, starter pack). external_list_prices: type: array items: $ref: "#/components/schemas/GetProductResponseDataSkuExternalListPrice" description: |- The SKU list price (e.g. MSRP, RRP) or original price information on external ecommerce platforms. Applicable only for selected sellers in the US market. **Note**: This value may appear as the strikethrough price on the product page. However, whether the strikethrough price is shown and the amount shown are subject to the audit team's review and decision based on various pricing information. external_sku_id: type: string description: An external identifier used in an external ecommerce platform. This is used to associate the SKU between TikTok Shop and the external ecommerce platform. external_urls: type: array items: type: string description: A list of URLs for third-party product listing pages where consumers can place orders. extra_identifier_codes: type: array items: type: string description: |- A list of up to 10 additional identifier codes if the SKU belongs to a virtual bundle (containing multiple individual SKUs). **Note**: Applicable only for the EU market. fees: type: array items: $ref: "#/components/schemas/GetProductResponseDataSkuFee" description: The fees required for this product based on TikTok Shop policies. Fees are required only for certain product categories, retrieve the requirements from the [Get Category Rules API](https://partner.tiktokshop.com/docv2/page/6509c0febace3e02b74594a9). global_listing_policy: $ref: "#/components/schemas/GetProductResponseDataSkuGlobalListingPolicy" description: |- Global Product Replicate (GPR) related information if the product is a target for synchronization. Applicable only for the EU market. id: type: string description: The SKU ID generated by TikTok Shop. identifier_code: $ref: "#/components/schemas/IdentifierCode" description: A regulated identifier code assigned to a product based on international standardized regulations (e.g. GTIN) to ensure the product is universally identifiable across various platforms and systems. inventory: type: array items: $ref: "#/components/schemas/GetProductResponseDataSkuInventory" description: |- SKU inventory details. **Note**: This field is not supported in post-live drafts. Therefore, the values here will always reflect those in the base version, even if you set `return_draft_version=true`. list_price: $ref: "#/components/schemas/GetProductResponseDataSkuListPrice" description: |- The SKU's list price information that has been verified to be legitimate by the audit team. This is equivalent to the manufacturer's suggested retail price (MSRP), or the recommended retail price (RRP). Applicable only for the US market. **Note**: - This field will be empty or display the last verified price if the submitted price fails verification. - This value may appear as the strikethrough price on the product page. However, whether the strikethrough price is shown and the amount shown are subject to the audit team's review and decision based on various pricing information. pre_sale: $ref: "#/components/schemas/GetProductResponseDataSkuPreSale" description: |- SKU presale information, used to tag a product as a presale product based on its presale type. If this is not returned, it indicates that the product is a regular non-presale item. price: $ref: "#/components/schemas/GetProductResponseDataSkuPrice" description: SKU pricing information. sales_attributes: type: array items: $ref: "#/components/schemas/GetProductResponseDataSkuCombinedSkuSalesAttribute" description: A list of attributes (e.g. size, color, length) that define each variant of a product. seller_sku: type: string description: An internal code/name for managing SKUs, not visible to buyers. sku_dimensions: $ref: "#/components/schemas/GetProductResponseDataSkuSkuDimension" description: |- The dimensions of the sku. Note: - Provide the dimensions measured after packing the product. - These values impact the shipping cost, so it is important to ensure that dimensions are accurate. Any discrepancies in measurements may lead to additional shipping fees. - Optional for ID, TH, VN regions. sku_unit_count: type: string description: |- The total quantity/volume of the product represented by the SKU. For example, if the SKU represents 500ml of water, this value would be 500 if the unit type is defined as ml. Applicable only for the EU market. **Note**: - This is mainly used to calculate the unit price of the SKU, and is required only if you wish to display the unit price to facilitate easier price comparisons across different products and packaging sizes. - Unit price = Selling price/(SKU unit count/base unit count). Therefore if you want to obtain the unit price, you would also need to define the "base unit count" and the "unit type" product attributes. Retrieve the relevant information for these product attributes by using the [Get Attributes API](https://partner.tiktokshop.com/docv2/page/6509c5784a0bb702c0561cc8). sku_weight: $ref: "#/components/schemas/GetProductResponseDataSkuSkuWeight" description: The packaged weight of the SKU. The returned `value` and `unit` use the same measurement system as `sku_dimensions`; for example, `KILOGRAM` is used with `CENTIMETER`. This weight can affect shipping fees, and it takes precedence over package dimensions when the fee calculated from weight is higher. status_info: $ref: "#/components/schemas/GetProductResponseDataSkuStatusInfo" description: Status information of the SKU. purchase_order_quantity_limit: $ref: "#/components/schemas/PurchaseOrderQuantityLimit" description: The customer purchase limits for this SKU. `maximum_order_quantity` is the maximum quantity the customer can purchase in one order, and `cumulative_order_quantity` is the maximum quantity the customer can purchase across all orders while the limit is active. GetProductResponseDataSkuCombinedSku: type: object properties: brand: $ref: "#/components/schemas/Brand" description: Brand information of the source product included in the virtual bundle. categories: type: array items: $ref: "#/components/schemas/GetProductResponseDataSkuCombinedSkuCategory" description: The category tree information of the source product included in the virtual bundle. combined_listing_not_live_reasons: type: array items: type: string enum: - SUB_PRODUCT_DEACTIVATE - SUB_PRODUCT_DELETE - SUB_PRODUCT_FROZEN - SUB_SKU_DELETE - SUB_PRODUCT_CATEGORY_FIRST_LEVEL_ERROR - SUB_PRODUCT_CATEGORY_OVER_RESTRICTION x-enum-descriptions: - Indicate the source product has been deactivated. - Indicate the source product has been deleted. - Indicate the source product has been frozen. - Indicate the source SKU has been deleted. - Indicate the level one category of the virtual bundle does not match that of the source product. - Indicate the level one category of the source product is not in the set of restricted categories. description: |- The reasons linked to the source product included in the virtual bundle that are keeping the virtual bundle status from being live. Possible values: - SUB_PRODUCT_DEACTIVATE: Indicate the source product has been deactivated. - SUB_PRODUCT_DELETE: Indicate the source product has been deleted. - SUB_PRODUCT_FROZEN: Indicate the source product has been frozen. - SUB_SKU_DELETE: Indicate the source SKU has been deleted. - SUB_PRODUCT_CATEGORY_FIRST_LEVEL_ERROR: Indicate the level one category of the virtual bundle does not match that of the source product. - SUB_PRODUCT_CATEGORY_OVER_RESTRICTION: Indicate the level one category of the source product is not in the set of restricted categories. inventory: type: array items: $ref: "#/components/schemas/GetProductResponseDataSkuCombinedSkuInventory" description: Source SKU inventory details. price: $ref: "#/components/schemas/GetProductResponseDataSkuCombinedSkuPrice" description: Source SKU pricing information. product_id: type: string description: The ID of the source product included in the virtual bundle. product_main_image: $ref: "#/components/schemas/GetProductResponseDataSkuCombinedSkuProductMainImage" description: The main image of the source product included in the virtual bundle. sales_attributes: type: array items: $ref: "#/components/schemas/GetProductResponseDataSkuCombinedSkuSalesAttribute" description: A list of attributes (e.g. size, color, length) that define the source SKU. seller_sku: type: string description: An internal code/name for managing the source SKU, not visible to buyers. sku_count: type: integer format: int64 description: The quantity of the source SKU included in the virtual bundle. sku_id: type: string description: The ID of the source SKU included in the virtual bundle. title: type: string description: The title of the source product included in the virtual bundle. GetProductResponseDataSkuCombinedSkuCategory: type: object properties: id: type: string description: The ID of the category of the source product included in the virtual bundle. is_leaf: type: boolean description: A flag to indicate if the category is a leaf category. local_name: type: string description: The source product category name in the requested locale. parent_id: type: string description: The parent category ID of the source product included in the virtual bundle. GetProductResponseDataSkuCombinedSkuInventory: type: object properties: quantity: type: integer format: int64 description: The total quantity available in the warehouse of the source SKU. warehouse_id: type: string description: |- The ID of the warehouse where the source SKU is stored. Retrieve details of the warehouse from the [Get Warehouse List API](https://partner.tiktokshop.com/docv2/page/get-warehouse-list-202309). GetProductResponseDataSkuCombinedSkuPrice: type: object properties: currency: type: string enum: - BRL - CZK - EUR - GBP - HUF - IDR - JPY - MXN - MYR - PHP - PLN - SGD - THB - USD - VND x-enum-descriptions: - Brazil - Czech Republic - France, Germany, Ireland, Italy, Spain, Netherlands, Belgium, Austria, Greece, Portugal - United Kingdom - Hungary - Indonesia - Japan - Mexico - Malaysia - Philippines - Poland - Singapore - Thailand - United States - Vietnam description: |- The currency. Possible values based on the region: - BRL: Brazil - CZK: Czech Republic - EUR: France, Germany, Ireland, Italy, Spain, Netherlands, Belgium, Austria, Greece, Portugal - GBP: United Kingdom - HUF: Hungary - IDR: Indonesia - JPY: Japan - MXN: Mexico - MYR: Malaysia - PHP: Philippines - PLN: Poland - SGD: Singapore - THB: Thailand - USD: United States - VND: Vietnam sale_price: type: string description: |- All sellers The source SKU's local display price shown on the product page before any discounts. tax_exclusive_price: type: string description: |- Global sellers The source SKU's local pre-tax price. This excludes any applicable charges such as cross-border shipping costs, taxes, and other fees, and therefore does not appear on the product page. Note: Tax-exclusive pricing does not apply to JP and US shops using China warehouses, therefore this value is the same as sale_price. GetProductResponseDataSkuCombinedSkuProductMainImage: type: object properties: height: type: integer format: int64 description: |- The image height. Unit: px thumb_urls: type: array items: type: string description: The URLs to view the image thumbnails. uri: type: string description: The URI of the image. urls: type: array items: type: string description: The URLs to view the images. width: type: integer format: int64 description: |- The image width. Unit: px GetProductResponseDataSkuCombinedSkuSalesAttribute: type: object properties: id: type: string description: The sales attribute ID. name: type: string description: The sales attribute name. sku_img: $ref: "#/components/schemas/GetProductResponseDataSkuCombinedSkuSalesAttributeSkuImg" description: The default/main image for each value (e.g. red) of the primary sales attribute (e.g. color) of the source product. This appears in the product options gallery on TikTok Shop. supplementary_sku_images: type: array items: $ref: "#/components/schemas/GetProductResponseDataSkuCombinedSkuSalesAttributeSupplementarySkuImage" description: |- A list of supplementary images for each value (e.g. red) of the primary sales attribute (e.g. color) to provide multiple views or details of the source product for that attribute value. These appear in the product options gallery on TikTok Shop. Applicable only for the US market. value_id: type: string description: The sales attribute value ID. value_name: type: string description: The sales attribute value name. GetProductResponseDataSkuCombinedSkuSalesAttributeSkuImg: type: object properties: height: type: integer format: int64 description: |- The image height. Unit: px thumb_urls: type: array items: type: string description: The URLs to view the image thumbnails. uri: type: string description: The URI of the image. urls: type: array items: type: string description: The URLs to view the images. width: type: integer format: int64 description: |- The image width. Unit: px GetProductResponseDataSkuCombinedSkuSalesAttributeSupplementarySkuImage: type: object properties: height: type: integer format: int64 description: |- The image height. Unit: px thumb_urls: type: array items: type: string description: The URLs to view the image thumbnails. uri: type: string description: The URI of the image. urls: type: array items: type: string description: The URLs to view the images. width: type: integer format: int64 description: |- The image width. Unit: px GetProductResponseDataSkuExternalListPrice: type: object properties: amount: type: string description: The price amount. currency: type: string enum: - USD description: |- The currency. Possible values: USD source: type: string enum: - SHOPIFY_COMPARE_AT_PRICE x-enum-descriptions: - The compare_at_price in Shopify. description: |- The external ecommerce platform from which the price is sourced. Possible values: - SHOPIFY_COMPARE_AT_PRICE: The compare_at_price in Shopify. GetProductResponseDataSkuFee: type: object properties: additional_attribute: type: string enum: - SINGLE_USE - REUSABLE - NOT_APPLICABLE description: |- Possible values for Pfand: - SINGLE_USE - REUSABLE - NOT_APPLICABLE amount: type: string description: |- The fee amount. Valid range: - PFAND: [0.00 - 6300.00] type: type: string enum: - PFAND description: |- The type of fee. Possible values: PFAND GetProductResponseDataSkuGlobalListingPolicy: type: object properties: inventory_type: type: string enum: - SHARED - EXCLUSIVE x-enum-descriptions: - Inventory Area Sharing - Inventory Exclusive description: |- The type of inventory to synchronize. Possible values: - SHARED: Inventory Area Sharing - EXCLUSIVE: Inventory Exclusive price_sync: type: boolean description: A flag indicating whether the product price is synchronized. replicate_source: $ref: "#/components/schemas/GetProductResponseDataSkuGlobalListingPolicyReplicateSource" description: The source global listing product to synchronize from. GetProductResponseDataSkuGlobalListingPolicyReplicateSource: type: object properties: product_id: type: string description: The ID of the source product. shop_id: type: string description: The shop ID of the source product. sku_id: type: string description: The SKU ID of the source product. GetProductResponseDataSkuInventory: type: object properties: backorder_quantity: type: integer format: int64 description: |- The `backorder_quantity` will automatically be converted to `quantity` once in-stock inventory is sold out. The fulfillment of this inventory follows the `handling_time` specified below. Note: Made-to-order (MTO), pre-order, and custom products cannot be backordered, and thus are incompatible with backorder_quantity. handling_time: type: integer format: int64 description: The estimated number of working days needed for a backorder to be shipped. Currently, different warehouses for the same SKU are not allowed to have different `handling_time` quantity: type: integer format: int64 minimum: 1 maximum: 99999 description: |- The total SKU quantity available in the warehouse. Valid range: [1, 99,999] Note: This quantity specifically refers to the in-stock inventory that can be shipped immediately. warehouse_id: type: string description: |- The ID of the warehouse where the SKU is stored. Retrieve details of the warehouse from the [Get Warehouse List API](https://partner.tiktokshop.com/docv2/page/650aa418defece02be6e66b6). GetProductResponseDataSkuListPrice: type: object properties: amount: type: string description: The price amount. currency: type: string enum: - USD description: |- The currency. Possible values: USD GetProductResponseDataSkuPreSale: type: object properties: fulfillment_type: $ref: "#/components/schemas/FulfillmentType" description: |- Information about the type of pre-sale order fulfillment and the corresponding timeframe. - `handling_duration_days` is for fulfillment with an extended duration. - `release_date` is for starting fulfillment on a fixed date. type: type: string enum: - PRE_ORDER - MADE_TO_ORDER - CUSTOM x-enum-descriptions: - The product is not yet available or released. Fulfillment can be extended by specifying a release date. - The product is produced only after the order is received. Fulfillment can be extended by specifying a duration. - The product requires a fulfillment timeline that exceeds the standard due to other factors. Fulfillment can be extended by specifying a duration. description: |- The type of pre-sale. Possible values based on the region: **US** - `PRE_ORDER`: The product is not yet available or released. Fulfillment can be extended by specifying a **release date**. - `MADE_TO_ORDER`: The product is produced only after the order is received. Fulfillment can be extended by specifying a **duration**. - `CUSTOM`: The product requires a fulfillment timeline that exceeds the standard due to other factors. Fulfillment can be extended by specifying a **duration**. **UK, EU, SEA, JP, and LATAM** - `PRE_ORDER`: The product is not yet available or released. Fulfillment can be extended by specifying a **duration**. GetProductResponseDataSkuPrice: type: object properties: currency: type: string enum: - BRL - CZK - EUR - GBP - HUF - IDR - JPY - MXN - MYR - PHP - PLN - SGD - THB - USD - VND x-enum-descriptions: - Brazil - Czech Republic - France, Germany, Ireland, Italy, Spain, Netherlands, Belgium, Austria, Greece, Portugal - United Kingdom - Hungary - Indonesia - Japan - Mexico - Malaysia - Philippines - Poland - Singapore - Thailand - United States - Vietnam description: |- The currency. Possible values based on the region: - BRL: Brazil - CZK: Czech Republic - EUR: France, Germany, Ireland, Italy, Spain, Netherlands, Belgium, Austria, Greece, Portugal - GBP: United Kingdom - HUF: Hungary - IDR: Indonesia - JPY: Japan - MXN: Mexico - MYR: Malaysia - PHP: Philippines - PLN: Poland - SGD: Singapore - THB: Thailand - USD: United States - VND: Vietnam sale_price: type: string description: |- **All sellers** The SKU's **local display price** shown on the product page before any discounts. starting_bid_price: type: string description: starting bid price for auction product tax_exclusive_price: type: string description: |- **Global sellers** The SKU's **local pre-tax price**. This excludes any applicable charges such as cross-border shipping costs, taxes, and other fees, and therefore does not appear on the product page. **Note**: Tax-exclusive pricing does not apply to JP and US shops using China warehouses, therefore this value is the same as `sale_price`. unit_price: type: string description: |- The unit price of the SKU. You can display the unit price to facilitate easier price comparisons across different products and packaging sizes. Applicable only for the EU market. **Note**: - This value is available only if you have defined the elements used to calculate this price when creating the product. - Unit price = Selling price/(SKU unit count/base unit count) GetProductResponseDataSkuSkuDimension: type: object properties: height: type: string description: |- The package height. A positive whole number. Note: For the BR market, decimal values using . or , as separators are also accepted but will be rounded to the nearest whole number. length: type: string description: |- The package length. A positive whole number. Note: For the BR market, decimal values using . or , as separators are also accepted but will be rounded to the nearest whole number. unit: type: string description: |- The unit for the SKU dimensions. Possible values based on region: - US: CENTIMETER, INCH - Other regions: CENTIMETER Note: Use the same measurement system for `sku_weight` and `sku_dimensions`. For example, use `KILOGRAM` with `CENTIMETER`. width: type: string description: |- The package width. A positive whole number. Note: For the BR market, decimal values using . or , as separators are also accepted but will be rounded to the nearest whole number. GetProductResponseDataSkuSkuWeight: type: object properties: unit: type: string description: |- The unit for the package weight. Possible values based on region: - US: KILOGRAM, POUND - BR, JP, MX: KILOGRAM, GRAM - Other countries: KILOGRAM Note: You must use the same system of measurement (metric system or imperial system) for package_weight and package_dimensions. In other words, if you are using KILOGRAM for the weight, you must use CENTIMETER for the dimensions. value: type: string description: |- The package weight, which must be a positive number. The number format varies based on the unit: - GRAM: integer - KILOGRAM: up to 3 decimal places - POUND: up to 2 decimal places GetProductResponseDataSkuStatusInfo: type: object properties: deactivation_source: type: string enum: - SELLER - PLATFORM - COMBO_RELATION x-enum-descriptions: - Indicates that the seller deactivated the SKU - Indicates that the platform de-activated the SKU due to violation reasons - Indicates that the platform de-activated the bundle-SKU due to the deactivation of sub-SKU. description: |- The deactivation source of the SKU with `DEACTIVATED` status. Possible values: - SELLER: Indicates that the seller deactivated the SKU - PLATFORM: Indicates that the platform de-activated the SKU due to violation reasons - COMBO_RELATION: Indicates that the platform de-activated the bundle-SKU due to the deactivation of sub-SKU. status: type: string enum: - NORMAL - DEACTIVATED description: |- The SKU status in TikTok Shop. Possible values: - NORMAL - DEACTIVATED GetProductResponseDataSubscribeInfo: type: object properties: subscribe_discount_details: type: array items: $ref: "#/components/schemas/GetProductResponseDataSubscribeInfoSubscribeDiscountDetail" description: All of the Save and Subscribe discount details. subscribe_promotion_config: type: array items: $ref: "#/components/schemas/GetProductResponseDataSubscribeInfoSubscribePromotionConfig" description: A subscription configuration specific to the seller. It outlines the different types of promotions and associated constraints that are available for use. subscribe_status: type: string description: |- An enum outlining whether the given product has an active Subscribe and Save promotion: - ENABLED - NOT_ENABLED support_subscribe: type: boolean description: A flag outlining whether the seller and given product support Subscribe and Save promotions. GetProductResponseDataSubscribeInfoSubscribeDiscountDetail: type: object properties: discount_level: type: string description: |- An enum that communicated the type of discount: - REGULAR - FIRST_ORDER - RETENTION discount_value: type: integer format: int64 description: The value of the discount. A value of 10, would indicate a 10% discount. GetProductResponseDataSubscribeInfoSubscribePromotionConfig: type: object properties: discount_level: type: string description: |- An enum that communicated the type of discount: - REGULAR - FIRST_ORDER - RETENTION discount_options: type: array items: type: integer format: int64 description: The discount options available to the seller for the given discount level. max_discount: type: integer format: int64 description: The maximum discount a seller can set for the associated discount level. min_discount: type: integer format: int64 description: The minimum discount a seller can set for the associated discount level. GetProductResponseDataVideo: type: object properties: cover_url: type: string description: The URL to view the video cover image. format: type: string description: The video format. height: type: integer format: int64 description: |- The video height. Unit: px id: type: string description: The video ID. size: type: integer format: int64 description: |- The video's original file size. Unit: MB url: type: string description: The URL to view the video. width: type: integer format: int64 description: |- The video width. Unit: px GetProductSKPPDetailResponse: 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/GetProductSKPPDetailResponseData" GetProductSKPPDetailResponseData: type: object properties: product_id: type: string description: Platform product ID. affiliate_program_status: type: string description: "Affiliate Program enrolment. Possible values: ACTIVE / INACTIVE." total_score: type: integer format: int64 description: Current SKPP total score, as of update_time. target_score: type: integer format: int64 description: Score threshold to qualify for SKPP. rewards: type: array items: $ref: "#/components/schemas/GetProductSKPPDetailResponseDataReward" description: Reward list. task_details: type: array items: $ref: "#/components/schemas/GetProductSKPPDetailResponseDataTaskDetail" description: Per-category score breakdown with suggested actions. update_time: type: integer format: int64 description: Date of the offline data snapshot that total_score, rewards and the score breakdown are derived from, returned as a Unix timestamp in seconds, pinned to the last second of that date in UTC (23:59:59Z). The value is date-level only — the time component is always 23:59:59 UTC — because the SKPP scoring runs in an offline pipeline with no intraday granularity. Latency is typically T+1 (the evening of day N publishes the day N−1 snapshot) and at most T+2. skpp_status: type: string description: "Possible values: QUALIFIED / NOT_QUALIFIED / NOT_ELIGIBLE." GetProductSKPPDetailResponseDataReward: type: object properties: reward_type: type: string description: "Possible values: ADS_CREDIT / TOP_CREATOR_MATCHMAKING / SHOPTAB_PV / BIG_PROMOTION_CAMPAIGN / OFF_PLATFORM_BESTSELLER_ADS_CREDIT." title: type: string description: Localized reward name, resolved from the shared Seller-Center content by the request locale. status: type: string description: "Possible values: NOT_GRANTED / PENDING / AVAILABLE" ad_credit_claim_status: type: string description: "Ad-credit-only sub-status, returned only when reward_type = ADS_CREDIT and status = AVAILABLE. Possible values: UNCLAIMED (eligible, not yet claimed) / CLAIMED (claimed)." value: type: string description: Granted amount/quantity; currency-typed values lead with the currency symbol. claim_conditions: type: array items: $ref: "#/components/schemas/GetProductSKPPDetailResponseDataRewardClaimCondition" description: Thresholds to unlock the reward; used by ADS_CREDIT. campaign_id: type: string description: Returned only for reward_type = BIG_PROMOTION_CAMPAIGN. GetProductSKPPDetailResponseDataRewardClaimCondition: type: object properties: condition_type: type: string description: "Possible values: GMV / ORDER." current_value: type: string description: Current progress; GMV-typed values lead with the currency symbol. target_value: type: string description: Threshold value; same formatting as current_value. GetProductSKPPDetailResponseDataTaskDetail: type: object properties: category: type: string enum: - COMMISSION_RATE - FULFILMENT - PRICING - FREE_SHIPING - FOLLOWER_BENEFITS - SAMPLING - ADS_SPEND - STOCK - SHOPPABLE_VIDEOS - INFORMATION_QUALITY - CRM_HOSTING description: |- Key for the scoring category. Possible values: - COMMISSION_RATE - FULFILMENT - PRICING - FREE_SHIPING - FOLLOWER_BENEFITS - SAMPLING - ADS_SPEND - STOCK - SHOPPABLE_VIDEOS - INFORMATION_QUALITY - CRM_HOSTING name: type: string description: Localized category name, resolved from category via the shared content by the request locale. current_value: type: string description: Current value of this dimension's metric (e.g. current price, commission rate, free-shipping status). target_value: type: string description: The threshold this dimension must reach to pass. It uses the same unit as `current_value` and may include a leading comparison operator, such as `≥` or `≤`, to show the required direction. passed: type: boolean description: Whether this dimension meets its target_value. action_suggestions: type: array items: $ref: "#/components/schemas/GetProductSKPPDetailResponseDataTaskDetailActionSuggestion" description: Suggested actions to complete this task; returned only when passed = false. A task may have multiple suggestions. GetProductSKPPDetailResponseDataTaskDetailActionSuggestion: type: object properties: score_increase: type: integer format: int64 description: SKPP points added to total_score when this action is completed; for tiered actions, the maximum tier. url: type: string description: Link to the Seller Center page that completes the action. GetProductsSEOWordsResponse: 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/GetProductsSEOWordsResponseData" GetProductsSEOWordsResponseData: type: object properties: products: type: array items: $ref: "#/components/schemas/GetProductsSEOWordsResponseDataProduct" description: The requested products for which SEO keyword suggestions were returned. Products without returned suggestions are omitted. When no suggestions are returned, `products` may be omitted or returned as an empty list. GetProductsSEOWordsResponseDataProduct: type: object properties: id: type: string description: The product ID. seo_words: type: array items: $ref: "#/components/schemas/SeoWord" description: The list of SEO keyword suggestions for the product title. GetRecommendedProductTitleAndDescriptionResponse: 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/GetRecommendedProductTitleAndDescriptionResponseData" GetRecommendedProductTitleAndDescriptionResponseData: type: object properties: products: type: array items: $ref: "#/components/schemas/GetRecommendedProductTitleAndDescriptionResponseDataProduct" description: Returned products and their title and description suggestions. A requested product might not appear in the response. For a returned product, an empty `items` list for `TITLE` or `DESCRIPTION` means that no optimized text is available for that field. GetRecommendedProductTitleAndDescriptionResponseDataProduct: type: object properties: id: type: string description: The product ID. suggestions: type: array items: $ref: "#/components/schemas/GetRecommendedProductTitleAndDescriptionResponseDataProductSuggestion" description: The suggestions for each product field. GetRecommendedProductTitleAndDescriptionResponseDataProductSuggestion: type: object properties: field: type: string enum: - TITLE - DESCRIPTION description: |- The applicable product field. Possible values: - TITLE - DESCRIPTION items: type: array items: $ref: "#/components/schemas/GetRecommendedProductTitleAndDescriptionResponseDataProductSuggestionItem" description: The list of optimized text. GetRecommendedProductTitleAndDescriptionResponseDataProductSuggestionItem: type: object properties: text: type: string description: The optimized text. GetRejectReasonsResponse: 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/GetRejectReasonsResponseData" GetRejectReasonsResponseData: type: object properties: reasons: type: array items: $ref: "#/components/schemas/GetRejectReasonsResponseDataReason" description: The list of rejection reasons the seller has provided. GetRejectReasonsResponseDataReason: type: object properties: name: type: string description: "The reject reason key. Pass this exact value to the corresponding seller reject API as the reject reason. Note: The available reject reasons may change depending on the current aftersales request context. To avoid using stale or inapplicable reason keys, call this API close to the reject action and use the latest returned name values instead of hardcoding them." text: type: string description: The corresponding text to the reason name, localized based on the locale input parameter. GetReturnRecordsResponse: 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/GetReturnRecordsResponseData" GetReturnRecordsResponseData: type: object properties: records: type: array items: $ref: "#/components/schemas/GetReturnRecordsResponseDataRecord" description: A list of return records. GetReturnRecordsResponseDataRecord: type: object properties: event: type: string description: The event type that represents which lifecycle event this record describes. It can vary depending on the current status and the return flow of the request, including the initial request, seller actions, shipment events, and timeout or system events. role: type: string enum: - BUYER - SELLER - OPERATOR - SYSTEM x-enum-descriptions: - "" - "" - The action was triggered manually by a customer service agent. - The action was triggered automatically due to a policy reason. description: |- The actor that initiated this lifecycle event. Possible values: - `BUYER` - `SELLER` - `OPERATOR`: The action was triggered manually by a customer service agent. - `SYSTEM`: The action was triggered automatically due to a policy reason. description: type: string description: A human-readable description of this lifecycle event. reason_text: type: string description: The corresponding text for a return reason, localized based on the locale input parameter. note: type: string description: A note associated with the return record. Use role to identify the actor for the event. images: type: array items: $ref: "#/components/schemas/GetReturnRecordsResponseDataRecordImage" description: Images provided by the seller or buyer. You can use the role field to differentiate whether the images are from the seller or buyer. videos: type: array items: $ref: "#/components/schemas/GetReturnRecordsResponseDataRecordVideo" description: Videos uploaded by the buyer. Only buyers are allowed to upload videos. create_time: type: integer format: int64 description: The Unix timestamp, in seconds, when this record entry was created. GetReturnRecordsResponseDataRecordImage: type: object properties: url: type: string description: URL of the image. width: type: integer format: int64 description: |- The width of image. Unit: px height: type: integer format: int64 description: |- The height of image. Unit: px GetReturnRecordsResponseDataRecordVideo: type: object properties: url: type: string description: Video URL. cover: type: string description: Video thumbnail image. width: type: integer format: int64 description: |- Video image width. Unit: px height: type: integer format: int64 description: |- Video image height. Unit: px duration_millis: type: integer format: int64 description: |- Video duration. Unit: milliseconds GetSPSMetricDiagnosisResponse: 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/GetSPSMetricDiagnosisResponseData" GetSPSMetricDiagnosisResponseData: type: object properties: benchmarks: $ref: "#/components/schemas/Benchmark" description: Benchmark thresholds for this metric. calculation_rule: $ref: "#/components/schemas/GetSPSMetricDiagnosisResponseDataCalculationRule" description: Calculation details used to derive this metric. dimension: type: string description: SPS dimension that the metric belongs to. distribution_details: type: array items: $ref: "#/components/schemas/GetSPSMetricDiagnosisResponseDataDistributionDetail" description: Additional distribution details for the metric. evaluate_duration_days: type: integer format: int64 description: Number of days included in the metric evaluation period. end_evaluation_time: type: integer format: int64 description: Metric evaluation period end time. Unix timestamp in seconds. start_evaluation_time: type: integer format: int64 description: Metric evaluation period start time. Unix timestamp in seconds. metric_code: type: string description: "Stable metric code. Possible values: NRR, NBFR, SFCR, OTDR, AHT, and IM_DSAT." score: type: string description: Metric score, from 0 to 5. status: type: string description: Metric status. Possible values include EXCELLENT, GOOD, POOR, CRITICAL and NIL. status_text: type: string description: Metric status text. Values like Excellent, Good, Normal, Attention. trend: $ref: "#/components/schemas/GetSPSMetricDiagnosisResponseDataTrend" description: Metric trend over the requested lookback range. value: type: string description: Metric value. Ratios are represented as values from 0 to 1; percentages are represented as values from 0 to 100. value_unit: type: string description: Unit of the metric value. Possible values include PERCENT and HOURS. analyses: type: array items: $ref: "#/components/schemas/GetSPSMetricDiagnosisResponseDataAnalysis" description: Diagnostic insights for the selected metric. GetSPSMetricDiagnosisResponseDataAnalysis: type: object properties: summaries: type: array items: type: string description: Summarized causes affecting the selected metric. details: type: array items: type: string description: Detailed explanations for the selected metric diagnosis. GetSPSMetricDiagnosisResponseDataCalculationRule: type: object properties: denominator_label: type: string description: Denominator label. denominator_value: type: string description: Denominator value. numerator_label: type: string description: Numerator label. numerator_value: type: string description: Numerator value. GetSPSMetricDiagnosisResponseDataDistributionDetail: type: object properties: count: type: integer format: int64 description: Number of items in the distribution bucket. name: type: string description: Distribution detail name. percent: type: string description: Percentage of items in the distribution bucket, from 0 to 100. GetSPSMetricDiagnosisResponseDataTrend: type: object properties: data_points: type: array items: $ref: "#/components/schemas/GetSPSMetricDiagnosisResponseDataTrendDataPoint" description: Metric trend data points. GetSPSMetricDiagnosisResponseDataTrendDataPoint: type: object properties: record_date: type: string description: Trend date in yyyyMMdd format. value: type: string description: Metric value on the trend date, using the same unit as value_unit. GetSPSMetricProblemDetailsResponse: 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/GetSPSMetricProblemDetailsResponseData" GetSPSMetricProblemDetailsResponseData: type: object properties: aht_problem_order_items: type: array items: $ref: "#/components/schemas/GetSPSMetricProblemDetailsResponseDataAhtProblemOrderItem" description: AHT problem order items. im_dsat_chat_items: type: array items: $ref: "#/components/schemas/GetSPSMetricProblemDetailsResponseDataImDsatChatItem" description: IM_DSAT chat session items. metric_code: type: string description: "Stable metric code. Possible values: NRR, NBFR, SFCR, OTDR, AHT, and IM_DSAT." nbfr_problem_order_items: type: array items: $ref: "#/components/schemas/GetSPSMetricProblemDetailsResponseDataNbfrProblemOrderItem" description: NBFR problem order items. next_page_token: type: string description: An opaque token used to retrieve the next page of a paginated result set. Returns an empty string when there are no more results. nrr_problem_order_items: type: array items: $ref: "#/components/schemas/GetSPSMetricProblemDetailsResponseDataNrrProblemOrderItem" description: NRR problem order items. otdr_problem_order_items: type: array items: $ref: "#/components/schemas/GetSPSMetricProblemDetailsResponseDataOtdrProblemOrderItem" description: OTDR problem order items. sfcr_problem_order_items: type: array items: $ref: "#/components/schemas/GetSPSMetricProblemDetailsResponseDataSfcrProblemOrderItem" description: SFCR problem order items. total_count: type: integer format: int64 description: Total number of available records. GetSPSMetricProblemDetailsResponseDataAhtProblemOrderItem: type: object properties: aftersales_type_name: type: string description: Aftersales type returned by TikTok Shop aftersales classification. approve_duration_hours: type: string description: Approval duration in hours. inspect_duration_hours: type: string description: Inspection duration in hours. order_id: type: string description: Order ID. return_order_id: type: string description: Return order ID. review_count: type: integer format: int64 description: Number of review rounds. total_handle_duration_hours: type: string description: Total aftersales handle duration in hours. GetSPSMetricProblemDetailsResponseDataImDsatChatItem: type: object properties: chat_duration_hours: type: string description: Chat duration in hours. chat_record_id: type: string description: Chat record ID. customer_name: type: string description: Masked customer name. customer_rating: type: integer format: int64 description: Customer rating from 1 to 5. first_reply_time: type: integer format: int64 description: First reply time. Unix timestamp in seconds. rating_reasons: type: array items: type: string description: Customer rating reasons. service_agent: type: string description: Service agent name. GetSPSMetricProblemDetailsResponseDataNbfrProblemOrderItem: type: object properties: deliver_time: type: integer format: int64 description: Delivery time. Unix timestamp in seconds. order_create_time: type: integer format: int64 description: Order creation time. Unix timestamp in seconds. order_id: type: string description: Order ID. product_id: type: string description: Product ID, when available. product_name: type: string description: Product name. return_refund_reason: type: string description: Return or refund reason. sku_id: type: string description: SKU ID. GetSPSMetricProblemDetailsResponseDataNrrProblemOrderItem: type: object properties: deliver_time: type: integer format: int64 description: Delivery time. Unix timestamp in seconds. order_create_time: type: integer format: int64 description: Order creation time. Unix timestamp in seconds. order_id: type: string description: Order ID. product_id: type: string description: Product ID, when available. product_name: type: string description: Product name. sku_id: type: string description: SKU ID. user_review_rating: type: integer format: int64 description: User review rating from 1 to 5. GetSPSMetricProblemDetailsResponseDataOtdrProblemOrderItem: type: object properties: actual_deliver_time: type: integer format: int64 description: Actual deliver time. Unix timestamp in seconds. expect_deliver_time: type: integer format: int64 description: Expected deliver time. Unix timestamp in seconds. order_id: type: string description: Order ID. product_name: type: string description: Product name. sku_id: type: string description: SKU ID. GetSPSMetricProblemDetailsResponseDataSfcrProblemOrderItem: type: object properties: cancellation_reasons: type: array items: type: string description: Cancellation reasons. order_create_time: type: integer format: int64 description: Order creation time. Unix timestamp in seconds. order_id: type: string description: Order ID. product_id: type: string description: Product ID, when available. product_name: type: string description: Product name. sku_id: type: string description: SKU ID. GetSPSMetricTopItemsResponse: 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/GetSPSMetricTopItemsResponseData" GetSPSMetricTopItemsResponseData: type: object properties: aht_aftersales_type_items: type: array items: $ref: "#/components/schemas/GetSPSMetricTopItemsResponseDataAhtAftersalesTypeItem" description: Top product items for AHT, with fields for average handle duration and the top aftersales type. metric_code: type: string description: "Stable metric code selected in the request. One of: NRR, NBFR, OTDR, or AHT." nbfr_top_product_items: type: array items: $ref: "#/components/schemas/GetSPSMetricTopItemsResponseDataNbfrTopProductItem" description: NBFR top product items. nrr_top_product_items: type: array items: $ref: "#/components/schemas/GetSPSMetricTopItemsResponseDataNrrTopProductItem" description: NRR top product items. otdr_logistics_items: type: array items: $ref: "#/components/schemas/GetSPSMetricTopItemsResponseDataOtdrLogisticsItem" description: OTDR logistics provider items. total_count: type: integer format: int64 description: Number of items in the metric-specific list returned by this response. GetSPSMetricTopItemsResponseDataAhtAftersalesTypeItem: type: object properties: handle_duration_hours: type: string description: Average handle duration in hours. product_id: type: string description: Product ID. product_name: type: string description: Product name. return_order_count: type: integer format: int64 description: Total number of return orders. top_aftersales_type_name: type: string description: Top aftersales type returned by TikTok Shop aftersales classification. top_type_order_count: type: integer format: int64 description: Number of orders associated with the top aftersales type. image_url: type: string description: Product image URL. GetSPSMetricTopItemsResponseDataNbfrTopProductItem: type: object properties: product_id: type: string description: Product ID. product_name: type: string description: Product name. return_order_count: type: integer format: int64 description: Number of return or refund orders. top_reason_order_count: type: integer format: int64 description: Number of orders associated with the top return or refund reason. top_return_reasons: type: array items: type: string description: Top return or refund reasons. image_url: type: string description: Product image URL. GetSPSMetricTopItemsResponseDataNrrTopProductItem: type: object properties: delivered_order_count: type: integer format: int64 description: Total number of delivered orders. image_url: type: string description: Product image URL. negative_order_count: type: integer format: int64 description: Number of orders with negative reviews. product_id: type: string description: Product ID. product_name: type: string description: Product name. top_review_reasons: type: array items: type: string description: Top negative review reasons. GetSPSMetricTopItemsResponseDataOtdrLogisticsItem: type: object properties: delivered_order_count: type: integer format: int64 description: Total number of delivered orders. logistics_provider: type: string description: Logistics provider name. on_time_deliver_order_count: type: integer format: int64 description: Number of orders delivered on time. on_time_deliver_rate: type: string description: On-time delivery rate as a ratio from 0 to 1. GetSPSMetricsResponse: 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/GetSPSMetricsResponseData" GetSPSMetricsResponseData: type: object properties: metrics: type: array items: $ref: "#/components/schemas/GetSPSMetricsResponseDataMetric" description: Fixed complete SPS metric set for the authorized shop. GetSPSMetricsResponseDataMetric: type: object properties: benchmarks: $ref: "#/components/schemas/Benchmark" description: Benchmark thresholds for the metric, expressed in the unit specified by `value_unit`. dimension: type: string description: SPS dimension that the metric belongs to. evaluate_duration_days: type: integer format: int64 description: Number of days included in this metric's evaluation period. end_evaluation_time: type: integer format: int64 description: Metric evaluation period end time. Unix timestamp in seconds. start_evaluation_time: type: integer format: int64 description: Metric evaluation period start time. Unix timestamp in seconds. metric_code: type: string description: Stable metric code. Possible values include NRR, NBFR, SFCR, OTDR, AHT, and IM_DSAT. metric_name: type: string description: Localized metric display name. score: type: string description: Metric score, from 0 to 5. status: type: string description: Metric status. Possible values include EXCELLENT, GOOD, POOR, CRITICAL and NIL. status_text: type: string description: Metric status text. Values like Excellent, Good, Normal, Attention. value: type: string description: Metric value. Hours are represented as values; percentages are represented as values from 0 to 100. value_unit: type: string description: Unit of the metric value. Possible values include PERCENT and HOURS. top_reason_text: type: string description: Indicates that this metric is a key contributor to SPS. GetSPSOverviewResponse: 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/GetSPSOverviewResponseData" GetSPSOverviewResponseData: type: object properties: benefits: type: array items: $ref: "#/components/schemas/GetSPSOverviewResponseDataBenefit" description: Fixed complete set of benefits associated with the shop SPS score. dimensions: type: array items: $ref: "#/components/schemas/GetSPSOverviewResponseDataDimension" description: Score details by SPS dimension. evaluate_duration_days: type: integer format: int64 description: The number of days included in the score evaluation period. end_evaluation_time: type: integer format: int64 description: The evaluation period end time. Unix timestamp in seconds. start_evaluation_time: type: integer format: int64 description: The evaluation period start time. Unix timestamp in seconds. peer_percentile: type: string description: The shop's percentile among peers, from 0 to 100. primary_category: $ref: "#/components/schemas/GetSPSOverviewResponseDataPrimaryCategory" description: The shop's primary category. sps_score: type: string description: The shop SPS score, from 0 to 5 with one decimal place. sps_tier: type: string description: The SPS tier. Possible values include EXCELLENT, GOOD, POOR, CRITICAL and NIL. sps_tier_text: type: string description: The SPS tier. Values like Excellent, Good, Normal, Attention. top_issues: $ref: "#/components/schemas/GetSPSOverviewResponseDataTopIssue" description: Top SPS issues that contributed to the current score. update_time: type: integer format: int64 description: The latest score refresh time. Unix timestamp in seconds. GetSPSOverviewResponseDataBenefit: type: object properties: benefit_name: type: string description: Benefit display name localized by the requested locale. is_unlocked: type: boolean description: Whether the shop has unlocked this benefit. unlock_score: type: string description: Score required to unlock the benefit, from 0 to 5. GetSPSOverviewResponseDataDimension: type: object properties: name: type: string description: Dimension name. score: type: string description: Dimension score, from 0 to 5. status: type: string description: Dimension status enum. Possible values include EXCELLENT, GOOD, POOR, CRITICAL and NIL. status_text: type: string description: Dimension status text. Values like Excellent, Good, Normal, Attention. weight: type: string description: Dimension weight as a percent from 0 to 100. GetSPSOverviewResponseDataPrimaryCategory: type: object properties: category_id: type: string description: The primary category ID. category_name: type: string description: The primary category name. GetSPSOverviewResponseDataTopIssue: type: object properties: issues: type: array items: $ref: "#/components/schemas/GetSPSOverviewResponseDataTopIssueIssue" description: Ranked issue list. summary: type: string description: Localized summary of the top issues. GetSPSOverviewResponseDataTopIssueIssue: type: object properties: description: type: string description: Localized issue description. evaluate_duration_days: type: integer format: int64 description: Number of days included in this issue's evaluation period. end_evaluation_time: type: integer format: int64 description: Issue evaluation period end time. Unix timestamp in seconds. start_evaluation_time: type: integer format: int64 description: Issue evaluation period start time. Unix timestamp in seconds. metric_code: type: string description: Related metric code. Possible values include NRR, NBFR, SFCR, OTDR, AHT, and IM_DSAT. metric_name: type: string description: Localized metric display name. percentile: type: string description: Metric percentile among peer shops, from 0 to 100. rank: type: integer format: int64 description: Issue rank, where 1 is the top issue. GetSellerFinancialTransactionsResponse: 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/GetSellerFinancialTransactionsResponseData" GetSellerFinancialTransactionsResponseData: type: object properties: next_page_token: type: string description: Cursor used for searching for more information total_count: type: integer format: int64 description: The total num of the withdraws withdrawals: type: array items: $ref: "#/components/schemas/GetSellerFinancialTransactionsResponseDataWithdrawal" description: The list of transaction records matching the request filters. GetSellerFinancialTransactionsResponseDataWithdrawal: type: object properties: id: type: string description: A unique transaction ID generated by TikTok Shop. type: type: string enum: - WITHDRAW - SETTLE - TRANSFER - REVERSE - POLICY_VIOLATION_DEDUCTION - REWARD - PAYMENT - REFUND - UNKNOWN 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 deduction for a policy violation. - A reward transaction. - A payment transaction. - A refund transaction. - An unrecognized transaction type. description: |- The transaction type. Possible values: - WITHDRAW: The seller withdraws the settlement amount to a bank card. - SETTLE: The platform settles the amount to the seller. - TRANSFER: A platform subsidy or deduction due to platform policies. - REVERSE: A withdrawal failure caused by incorrect bank card information. - POLICY_VIOLATION_DEDUCTION: A deduction for a policy violation. - REWARD: A reward transaction. - PAYMENT: A payment transaction. - REFUND: A refund transaction. - UNKNOWN: An unrecognized transaction type. amount: type: string description: The transaction amount, in the currency specified by currency. currency: type: string description: The three-letter ISO 4217 currency code for the transaction amount. status: type: string enum: - SUCCESS - INIT - ORDERED - PROCESSING - RECEIVED - PROCESSED - FAILED - REVERSED - EXCEPTION - CLOSED - UNKNOWN x-enum-descriptions: - The transaction completed successfully. For a WITHDRAW transaction, this means that the withdrawal has been transferred to the seller. - The withdrawal was initialized. This status applies only to WITHDRAW transactions. - The transaction order was created. - The withdrawal is being processed. - The withdrawal was received. - The payout completed successfully. - The payout failed. - The transaction was refunded. - The transaction was partially refunded. - The transaction was closed. - The status could not be mapped. description: |- The processing status of the transaction. Possible values: - SUCCESS: The transaction completed successfully. For a WITHDRAW transaction, this means that the withdrawal has been transferred to the seller. - INIT: The withdrawal was initialized. This status applies only to WITHDRAW transactions. - ORDERED: The transaction order was created. - PROCESSING: The withdrawal is being processed. - RECEIVED: The withdrawal was received. - PROCESSED: The payout completed successfully. - FAILED: The payout failed. - REVERSED: The transaction was refunded. - EXCEPTION: The transaction was partially refunded. - CLOSED: The transaction was closed. - UNKNOWN: The status could not be mapped. create_time: type: integer format: int64 description: The transaction creation time, expressed as a Unix timestamp in seconds. GetShippingProvidersResponse: 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/GetShippingProvidersResponseData" GetShippingProvidersResponseData: type: object properties: shipping_providers: type: array items: $ref: "#/components/schemas/ShippingProvider" description: The shipping providers available for the specified delivery option. GetShippingTemplateAvailabilityRequest: type: object properties: product_attribute: $ref: "#/components/schemas/GetShippingTemplateAvailabilityRequestProductAttribute" description: The product's dimensions and weight to use when evaluating shipping template availability. GetShippingTemplateAvailabilityRequestProductAttribute: type: object properties: weight: $ref: "#/components/schemas/GetShippingTemplateAvailabilityRequestProductAttributeWeight" description: The weight of product dimension: $ref: "#/components/schemas/GetShippingTemplateAvailabilityRequestProductAttributeDimension" description: The dimension of the product GetShippingTemplateAvailabilityRequestProductAttributeDimension: type: object properties: length: type: string description: The length of the product width: type: string description: The width of the product height: type: string description: The height of the product unit: type: integer format: int64 description: |- 1: centimeter 2:inch 3:foot 4:millimeter 5:meter GetShippingTemplateAvailabilityRequestProductAttributeWeight: type: object properties: weight: type: string description: The weight of product unit: type: integer format: int64 description: |- 1:gram 2:pound 3:ounce 4:kilogram GetShippingTemplateAvailabilityResponse: 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/GetShippingTemplateAvailabilityResponseData" GetShippingTemplateAvailabilityResponseData: type: object properties: templates: type: array items: $ref: "#/components/schemas/GetShippingTemplateAvailabilityResponseDataTemplate" description: Shipping templates evaluated for availability for the seller's shop. GetShippingTemplateAvailabilityResponseDataTemplate: type: object properties: template_is_available: type: boolean description: Whether the template is available template: $ref: "#/components/schemas/GetShippingTemplateAvailabilityResponseDataTemplateTemplate" description: Shipping template details, including the template ID, name, fulfillment party, and whether it is the default template. service_unreachable_reason: type: array items: $ref: "#/components/schemas/GetShippingTemplateAvailabilityResponseDataTemplateServiceUnreachableReason" description: Reasons the shipping template is unavailable, grouped by shipping service. This field is omitted when the template is available. GetShippingTemplateAvailabilityResponseDataTemplateServiceUnreachableReason: type: object properties: service_id: type: string description: Id of the service filter_reason: type: array items: $ref: "#/components/schemas/GetShippingTemplateAvailabilityResponseDataTemplateServiceUnreachableReasonFilterReason" description: Reasons this shipping service is unavailable for the template. GetShippingTemplateAvailabilityResponseDataTemplateServiceUnreachableReasonFilterReason: type: object properties: filter_type: type: string description: |- 1 for length filter 2 for width filter 3 for height filter 4 for weight filter 9 for service mode filter 11 for service filter reason: type: string description: Detailed reason for unreachable GetShippingTemplateAvailabilityResponseDataTemplateTemplate: type: object properties: template_name: type: string description: The template name template_id: type: string description: The template_id is_default: type: boolean description: Is default template or not template_party: type: integer format: int64 description: |- 1 for shipping by platform template 2 for shipping by seller template GetShopGroupAndRelatedShopsResponse: 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/GetShopGroupAndRelatedShopsResponseData" GetShopGroupAndRelatedShopsResponseData: type: object properties: shop_group_data: $ref: "#/components/schemas/GetShopGroupAndRelatedShopsResponseDataShopGroupData" description: Information of product interoperability groups GetShopGroupAndRelatedShopsResponseDataShopGroupData: type: object properties: shop_group: $ref: "#/components/schemas/GetShopGroupAndRelatedShopsResponseDataShopGroupDataShopGroup" description: Basic information about the product interoperability group. This object is omitted when the authenticated shop does not belong to a group. shops: type: array items: $ref: "#/components/schemas/GetShopGroupAndRelatedShopsResponseDataShopGroupDataShop" description: The shops in the product interoperability group. If `shop_group` is omitted, this lists the shops associated with the same global seller as the authenticated shop. GetShopGroupAndRelatedShopsResponseDataShopGroupDataShop: type: object properties: shop_id: type: string description: The ID of the shop. seller_id: type: string description: The global seller ID associated with the shop. shop_name: type: string description: The name of the shop. shop_region: type: string description: Region where the shop operates GetShopGroupAndRelatedShopsResponseDataShopGroupDataShopGroup: type: object properties: source: type: string description: |- Used to distinguish the creation source of product interoperability groups. If it is a product interoperability group formed by a US local merchant opening an MX store, the enumeration value is: '1 -> US_MX_ONBOARD' If it is a product interoperability group formed by a Chinese cross-border merchant opening an MX store, the enumeration value is '2 -> GS_POP'. shop_group_name: type: string description: The unique name representing the product interoperability group GetShopLIVEMinutePerformanceResponse: 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/GetShopLIVEMinutePerformanceResponseData" GetShopLIVEMinutePerformanceResponseData: type: object properties: performance: $ref: "#/components/schemas/GetShopLIVEMinutePerformanceResponseDataPerformance" description: LIVE performance data, including minute-level intervals and overall totals. next_page_token: type: string description: Page token for retrieving the next page. An empty value means there are no more pages. total_count: type: integer format: int64 description: Total number of minute-level intervals across all pages. GetShopLIVEMinutePerformanceResponseDataPerformance: type: object properties: overall: $ref: "#/components/schemas/GetShopLIVEMinutePerformanceResponseDataPerformanceOverall" description: Overall LIVE performance totals, including duration, time range, GMV, impressions, items sold, title, and unique viewers. intervals: type: array items: $ref: "#/components/schemas/GetShopLIVEMinutePerformanceResponseDataPerformanceInterval" maxItems: 100 description: Minute-level interval data for the LIVE session, including traffic, interactions, conversion, and sales fields. Each page contains up to 100 intervals. GetShopLIVEMinutePerformanceResponseDataPerformanceInterval: type: object properties: start_time: type: integer format: int64 description: Start time of this interval as a Unix timestamp in seconds (UTC). end_time: type: integer format: int64 description: End time of this interval as a Unix timestamp in seconds (UTC). sales: $ref: "#/components/schemas/GetShopLIVEMinutePerformanceResponseDataPerformanceIntervalSale" description: Sales performance for the LIVE interval. traffic: $ref: "#/components/schemas/GetShopLIVEMinutePerformanceResponseDataPerformanceIntervalTraffic" description: Traffic metrics for this LIVE interval, including viewers, views, LIVE impressions, product impressions, product clicks, click-through rate, and enter-room rate. interactions: $ref: "#/components/schemas/GetShopLIVEMinutePerformanceResponseDataPerformanceIntervalInteraction" description: Interaction metrics for this LIVE interval, including new followers, shares, comments, likes, and their rates per view. conversion: $ref: "#/components/schemas/GetShopLIVEMinutePerformanceResponseDataPerformanceIntervalConversion" description: Conversion data for the LIVE interval, including order rates, created SKU orders, GPM, and average price. GetShopLIVEMinutePerformanceResponseDataPerformanceIntervalConversion: type: object properties: avg_price: $ref: "#/components/schemas/AvgPrice" description: Average direct GMV per main order. Also known as AOV (main order) click_to_order_rate: $ref: "#/components/schemas/ClickToOrderRate" description: Click-to-order rate metrics for SKU orders and main orders within this LIVE interval. gpm: $ref: "#/components/schemas/GetShopLIVEMinutePerformanceResponseDataPerformanceIntervalConversionGpm" description: GPM metrics for this LIVE interval, including GMV per 1,000 views and per 1,000 impressions. created_sku_orders: type: integer format: int64 description: The number of SKU orders created by users from the LIVE sku_order_rate: type: string description: Number of SKU orders from the LIVE divided by the impressions of the LIVE GetShopLIVEMinutePerformanceResponseDataPerformanceIntervalConversionGpm: type: object properties: watch_gpm: type: string description: The Watch GPM is the average GMV generated from 1,000 views of the LIVE. show_gpm: type: string description: The average GMV generated from 1,000 impressions of the LIVE. GetShopLIVEMinutePerformanceResponseDataPerformanceIntervalInteraction: type: object properties: new_followers: type: integer format: int64 description: Number of viewers who followed creator from the LIVE video shares: type: integer format: int64 description: Total number of shares of a LIVE. comments: type: integer format: int64 description: Total number of comments for a LIVE. likes: type: integer format: int64 description: The number of likes in the LIVE room. comment_rate: type: string description: Total number of comments during the LIVE divided by the number of views. follow_rate: type: string description: Number of users that followed the creator during the LIVE divided by the number of views. like_rate: type: string description: Total number of likes during the LIVE divided by the number of views. share_rate: type: string description: Total number of times the LIVE was shared divided by the total number of views. GetShopLIVEMinutePerformanceResponseDataPerformanceIntervalSale: type: object properties: gmv: $ref: "#/components/schemas/Gmv" description: The total amount paid for orders placed directly within this interval, including returns and refunds. items_sold: type: integer format: int64 description: The number of items sold directly within this interval. customers: type: integer format: int64 description: The total number of customers who placed orders within this interval, including customers who made returns or refunds. sku_orders: type: integer format: int64 description: The total number of paid SKU orders placed within this interval. main_orders: type: integer format: int64 description: Total number of paid main orders placed. Main orders refer to the single purchase transaction a customer makes. GetShopLIVEMinutePerformanceResponseDataPerformanceIntervalTraffic: type: object properties: viewers: type: integer format: int64 description: The number of viewers within this interval. views: type: integer format: int64 description: The number of views or viewings in the LIVE room. product_impressions: type: integer format: int64 description: Total number of times a product was viewed in LIVE, including product list and product card impressions. ctr: type: string description: The number of clicks divided by numbers of views of the LIVE during selected time period including clicks on product lists and product cards enter_room_rate: type: string description: LIVE views per LIVE room impressions. product_clicks: type: integer format: int64 description: Total number of product link clicks from LIVE streams, including product list and product card clicks. impressions: type: integer format: int64 description: The total number of times the LIVE was displayed to viewers. GetShopLIVEMinutePerformanceResponseDataPerformanceOverall: type: object properties: live_title: type: string description: LIVE session title start_time: type: integer format: int64 description: Start time of the LIVE session as a Unix timestamp in seconds (UTC). end_time: type: integer format: int64 description: End time of the LIVE session as a Unix timestamp in seconds (UTC). duration: type: integer format: int64 description: LIVE session duration in seconds gmv: $ref: "#/components/schemas/Gmv" description: The total amount paid for orders placed directly from the LIVE, including returns and refunds. items_sold: type: integer format: int64 description: The number of items sold directly from the LIVE. unique_viewers: type: integer format: int64 description: The number of unique viewers in the LIVE room. impressions: type: integer format: int64 description: The total number of times the LIVE was displayed to viewers. GetShopLIVEPerformanceListResponse: 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/GetShopLIVEPerformanceListResponseData" GetShopLIVEPerformanceListResponseData: type: object properties: latest_available_date: type: string format: date description: Latest date in local timezone where data is ready (ISO 8601 format). live_stream_sessions: type: array items: $ref: "#/components/schemas/GetShopLIVEPerformanceListResponseDataLiveStreamSession" description: List of live performance metrics. next_page_token: type: string description: Page token for the next page request. total_count: type: integer format: int64 description: Total number of LIVE stream sessions. updated_at: type: string description: Time when the data was last updated in shop registered timezone. GetShopLIVEPerformanceListResponseDataLiveStreamSession: type: object properties: creator: $ref: "#/components/schemas/GetShopLIVEPerformanceListResponseDataLiveStreamSessionCreator" description: Creator information for the LIVE session. end_time: type: string description: End time of the LIVE, unix timestamp GMT (UTC+00:00). id: type: string description: ID of the LIVE interaction_performance: $ref: "#/components/schemas/GetShopLIVEPerformanceListResponseDataLiveStreamSessionInteractionPerformance" description: |- This object will return only when the account type is: - OFFICIAL_ACCOUNTS: - MARKETING_ACCOUNTS sales_performance: $ref: "#/components/schemas/GetShopLIVEPerformanceListResponseDataLiveStreamSessionSalesPerformance" description: Sale performance data of the LIVE related to the shop start_time: type: string description: Start time of the LIVE, unix timestamp GMT (UTC+00:00). title: type: string description: Title of the LIVE traffic: $ref: "#/components/schemas/GetShopLIVEPerformanceListResponseDataLiveStreamSessionTraffic" description: Traffic efficiency metrics for the LIVE session. GetShopLIVEPerformanceListResponseDataLiveStreamSessionCreator: type: object properties: author_type: type: string description: The creator account type. creator_country: type: string description: The creator's country or region code. nick_name: type: string description: The creator's nickname. open_id: type: string description: The creator's Open ID. user_name: type: string description: The creator's username. GetShopLIVEPerformanceListResponseDataLiveStreamSessionInteractionPerformance: type: object properties: comment_rate: type: string description: Ratio of comments to views. Expressed as a raw decimal string. comments: type: integer format: int64 description: Number of comments on the LIVE video posted during the selected period. follow_rate: type: string description: Ratio of new followers to viewers. Expressed as a raw decimal string. like_rate: type: string description: Ratio of likes to views. Expressed as a raw decimal string. likes: type: integer format: int64 description: The number of likes a LIVE video received during the selected time period. new_followers: type: integer format: int64 description: The number of viewers who followed creators from the video during the selected period. share_rate: type: string description: Ratio of shares to views. Expressed as a raw decimal string. shares: type: integer format: int64 description: Number of times the LIVE video posted during the selected period were shared. GetShopLIVEPerformanceListResponseDataLiveStreamSessionSalesPerformance: type: object properties: aov: $ref: "#/components/schemas/Aov" description: Average order value for the LIVE session. attributed_customers: type: integer format: int64 description: Number of customers attributed to the LIVE session. avg_live_auction_price: $ref: "#/components/schemas/AvgLiveAuctionPrice" description: Average price per item sold for LIVE auction products. avg_price: $ref: "#/components/schemas/AvgPrice" description: The total price paid for all items divided by the number of items sold. created_sku_orders: type: integer format: int64 description: "The total number of orders created during the selected period, including those with pending payment for cash-on-delivery or PayLater. Example: If a customer orders 3 units of SKU A and 2 units of SKU B, the SKU orders would be 2." gmv_with_tiktok_coupons: $ref: "#/components/schemas/GetShopLIVEPerformanceListResponseDataLiveStreamSessionSalesPerformanceGmvWithTiktokCoupon" description: GMV including TikTok coupon funding. live_attributed_gmv: $ref: "#/components/schemas/LiveAttributedGmv" description: GMV attributed to the LIVE session. live_attributed_items_sold: type: integer format: int64 description: Number of items sold attributed to the LIVE session. live_attributed_orders: type: integer format: int64 description: Number of orders attributed to the LIVE session. live_attributed_sku_orders: type: integer format: int64 description: Number of paid SKU orders attributed to the LIVE session. live_auction_attributed_gmv: $ref: "#/components/schemas/LiveAuctionAttributedGmv" description: GMV attributed to LIVE auction products. live_auction_attributed_items_sold: type: integer format: int64 description: Number of items sold attributed to LIVE auction products. live_auction_attributed_sku_orders: type: integer format: int64 description: Number of paid SKU orders attributed to LIVE auction products. live_auction_gmv: $ref: "#/components/schemas/GetShopLIVEPerformanceListResponseDataLiveStreamSessionSalesPerformanceLiveAuctionGmv" description: Direct GMV generated from LIVE auction products. live_auction_indirect_gmv: $ref: "#/components/schemas/GetShopLIVEPerformanceListResponseDataLiveStreamSessionSalesPerformanceLiveAuctionIndirectGmv" description: Indirect GMV generated from LIVE auction products. live_gmv: $ref: "#/components/schemas/LiveGmv" description: Direct GMV generated from the LIVE session. live_indirect_gmv: $ref: "#/components/schemas/LiveIndirectGmv" description: Indirect GMV generated from the LIVE session. payment_rate: type: string description: Ratio of paid orders to created orders. Expressed as a raw decimal string. products_sold: type: integer format: int64 description: Number of distinct products sold from the LIVE session. GetShopLIVEPerformanceListResponseDataLiveStreamSessionSalesPerformanceGmvWithTiktokCoupon: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). GetShopLIVEPerformanceListResponseDataLiveStreamSessionSalesPerformanceLiveAuctionGmv: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). GetShopLIVEPerformanceListResponseDataLiveStreamSessionSalesPerformanceLiveAuctionIndirectGmv: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). GetShopLIVEPerformanceListResponseDataLiveStreamSessionTraffic: type: object properties: acu: type: integer format: int64 description: Average concurrent users. avg_viewing_duration: type: integer format: int64 description: Average viewing duration in seconds. avg_viewing_duration_per_viewer: type: integer format: int64 description: Average viewing duration per viewer in seconds. ctor: type: string description: Click-to-order rate. Expressed as a raw decimal string. ctor_sku_order: type: string description: Ratio of attributed SKU orders to product clicks. Expressed as a raw decimal string. ctr: type: string description: Click-through rate. Expressed as a raw decimal string. gmv_per_hour: $ref: "#/components/schemas/GetShopLIVEPerformanceListResponseDataLiveStreamSessionTrafficGmvPerHour" description: LIVE-attributed GMV generated per hour. impressions: type: integer format: int64 description: Number of LIVE impressions. impressions_per_hour: type: integer format: int64 description: Average number of impressions per hour. live_ctr: type: string description: Ratio of product clicks to product impressions. Expressed as a raw decimal string. order_rate_sku_orders: type: string description: Ratio of attributed SKU orders to views. Expressed as a raw decimal string. over_1m_live_viewing_rate: type: string description: Ratio of views lasting longer than one minute. Expressed as a raw decimal string. over_1m_views: type: integer format: int64 description: Number of views lasting longer than one minute. pcu: type: integer format: int64 description: Peak concurrent users. product_clicks: type: integer format: int64 description: Number of product clicks. product_impressions: type: integer format: int64 description: Number of product impressions. products_added: type: integer format: int64 description: Number of products added to the LIVE session. show_gpm: $ref: "#/components/schemas/ShowGpm" description: LIVE-attributed GMV generated per 1,000 impressions. tap_through_rate: type: string description: Ratio of LIVE views to LIVE impressions. Expressed as a raw decimal string. viewers: type: integer format: int64 description: Number of unique viewers. views: type: integer format: int64 description: Number of LIVE views. watch_gpm: $ref: "#/components/schemas/GetShopLIVEPerformanceListResponseDataLiveStreamSessionTrafficWatchGpm" description: LIVE-attributed GMV generated per 1,000 watch units. GetShopLIVEPerformanceListResponseDataLiveStreamSessionTrafficGmvPerHour: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). GetShopLIVEPerformanceListResponseDataLiveStreamSessionTrafficWatchGpm: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). GetShopLIVEPerformanceOverviewResponse: 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/GetShopLIVEPerformanceOverviewResponseData" GetShopLIVEPerformanceOverviewResponseData: type: object properties: latest_available_date: type: string format: date description: Latest date in local timezone where data is ready (ISO 8601 format). performance: $ref: "#/components/schemas/GetShopLIVEPerformanceOverviewResponseDataPerformance" description: Overall performance data for livestream. updated_at: type: string description: Time when the data was last updated in shop registered timezone. GetShopLIVEPerformanceOverviewResponseDataPerformance: type: object properties: intervals: type: array items: $ref: "#/components/schemas/GetShopLIVEPerformanceOverviewResponseDataPerformanceInterval" description: Interval data for the requested time range. The time range of each interval is determined by the granularity. GetShopLIVEPerformanceOverviewResponseDataPerformanceInterval: type: object properties: avg_live_auction_price: $ref: "#/components/schemas/AvgLiveAuctionPrice" description: Average price per item sold for LIVE auction products. avg_viewing_duration: type: integer format: int64 description: Average viewing duration in seconds. ctor_sku_order: type: string description: Ratio of LIVE-attributed SKU orders to product clicks in raw decimal format. end_date: type: string format: date description: End date of the interval (ISO 8601 YYYY-MM-DD format) in shop registered timezone, exclusive. live_attributed_gmv: $ref: "#/components/schemas/LiveAttributedGmv" description: GMV attributed to LIVE streams. live_attributed_items_sold: type: integer format: int64 description: Number of items sold attributed to LIVE streams. live_attributed_sku_orders: type: integer format: int64 description: Number of paid SKU orders attributed to LIVE streams. live_auction_attributed_gmv: $ref: "#/components/schemas/LiveAuctionAttributedGmv" description: GMV attributed to LIVE auction products. live_auction_attributed_items_sold: type: integer format: int64 description: Number of items sold attributed to LIVE auction products. live_auction_attributed_sku_orders: type: integer format: int64 description: Number of paid SKU orders attributed to LIVE auction products. live_ctr: type: string description: Ratio of product clicks to product impressions from LIVE streams in raw decimal format. live_gmv: $ref: "#/components/schemas/LiveGmv" description: Direct GMV generated from LIVE streams. live_indirect_gmv: $ref: "#/components/schemas/LiveIndirectGmv" description: Indirect GMV generated from LIVE streams. show_gpm: $ref: "#/components/schemas/ShowGpm" description: LIVE-attributed GMV generated per 1,000 impressions. start_date: type: string format: date description: Start date of the interval (ISO 8601 YYYY-MM-DD format) in shop registered timezone, inclusive. views: type: integer format: int64 description: Number of LIVE views. GetShopLIVEProductsPerformanceListResponse: 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/GetShopLIVEProductsPerformanceListResponseData" GetShopLIVEProductsPerformanceListResponseData: type: object properties: products: type: array items: $ref: "#/components/schemas/GetShopLIVEProductsPerformanceListResponseDataProduct" description: List of products and their sales and traffic performance for the LIVE session. GetShopLIVEProductsPerformanceListResponseDataProduct: type: object properties: id: type: string description: Product id name: type: string description: Product name sales: $ref: "#/components/schemas/GetShopLIVEProductsPerformanceListResponseDataProductSale" description: Sales performance for the product in the LIVE session, including average price, orders, customers, GMV, and items sold. traffic: $ref: "#/components/schemas/GetShopLIVEProductsPerformanceListResponseDataProductTraffic" description: Traffic performance for the product in the LIVE session, including add-to-cart, click-to-order, CTR, GPM, product impressions, and product clicks. GetShopLIVEProductsPerformanceListResponseDataProductSale: type: object properties: direct_gmv: $ref: "#/components/schemas/GetShopLIVEProductsPerformanceListResponseDataProductSaleDirectGmv" description: The total amount paid for orders of this product directly from the LIVE, including returns and refunds. items_sold: type: integer format: int64 description: The number of product items sold customers: type: integer format: int64 description: The total numbers of customers who ordered this product directly from the LIVE, including customers who made returns or refunds. created_sku_orders: type: integer format: int64 description: The total number of SKU orders created directly from the LIVE for this product. avg_price: $ref: "#/components/schemas/GetShopLIVEProductsPerformanceListResponseDataProductSaleAvgPrice" description: Average direct GMV per main order. Also known as AOV (main order) sku_orders: type: integer format: int64 description: The total number of paid SKU orders placed directly from the LIVE for this product. main_orders: type: integer format: int64 description: Total number of paid main orders placed. Main orders refer to the single purchase transaction a customer makes. payment_rate: type: string description: Main order paid / Main order created of this product GetShopLIVEProductsPerformanceListResponseDataProductSaleAvgPrice: type: object properties: currency: type: string description: Average price currency code. amount: type: string description: Average price amount in the corresponding currency. GetShopLIVEProductsPerformanceListResponseDataProductSaleDirectGmv: type: object properties: currency: type: string description: Direct GMV currency code. amount: type: string description: Direct GMV amount in the corresponding currency. GetShopLIVEProductsPerformanceListResponseDataProductTraffic: type: object properties: product_impressions: type: integer format: int64 description: Number of product impressions for this product during the LIVE video, including for product lists and product cards ctr: type: string description: "Click-through rate: The number of product clicks for this product from the LIVE video, divided by the number of product impressions for this product from the LIVE video, including product clicks and product impressions for product lists and product cards" add_to_cart_count: type: integer format: int64 description: The number of times viewers add the product to their cart. click_to_order_rate: $ref: "#/components/schemas/ClickToOrderRate" description: Click-to-order rate metrics for main orders and SKU orders for this product. gpm: $ref: "#/components/schemas/GetShopLIVEProductsPerformanceListResponseDataProductTrafficGpm" description: GPM data for product traffic, including watch GPM. produt_clicks: type: integer format: int64 description: The total number of times the product was clicked from this LIVE, including from the product list and product card GetShopLIVEProductsPerformanceListResponseDataProductTrafficGpm: type: object properties: watch_gpm: type: string description: The Watch GPM is the average GMV generated from 1,000 views of the LIVE. GetShopPerformancePerHourResponse: 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/GetShopPerformancePerHourResponseData" GetShopPerformancePerHourResponseData: type: object properties: performance: $ref: "#/components/schemas/GetShopPerformancePerHourResponseDataPerformance" description: Shop performance data for the requested date, including hourly intervals, overall totals, and the latest available timestamp. GetShopPerformancePerHourResponseDataPerformance: type: object properties: intervals: type: array items: $ref: "#/components/schemas/GetShopPerformancePerHourResponseDataPerformanceInterval" description: Hourly interval data for the requested date, including hour index, GMV, customers, items sold, and visitors. latest_available_timestamp: type: integer format: int64 description: The latest time when the data is ready, as a UNIX timestamp. overall: $ref: "#/components/schemas/GetShopPerformancePerHourResponseDataPerformanceOverall" description: Aggregated shop performance metrics for the requested date. GetShopPerformancePerHourResponseDataPerformanceInterval: type: object properties: avg_order_value: $ref: "#/components/schemas/AvgOrderValue" description: Average order value during the hour. avg_sku_order_value: $ref: "#/components/schemas/AvgSkuOrderValue" description: Average SKU order value during the hour. customers: type: integer format: int64 description: The number of individual customers who made a purchase. This metric counts each customer once, even if they made multiple purchases. customers_count: type: integer format: int64 description: Number of unique users who paid for orders during the hour. gmv: $ref: "#/components/schemas/Gmv" description: GMV for this hourly interval. index: type: integer format: int64 description: |- hour index, 0-23. 0 means 00:00 - 00:59. items_sold: type: integer format: int64 description: "The total number of individual items sold. Example: If a customer buys 3 units of SKU A and 2 units of SKU B, the items sold would be 5." live_attributed_gmv: $ref: "#/components/schemas/LiveAttributedGmv" description: GMV attributed to live streams during the hour. orders_count: type: integer format: int64 description: The number of paid orders during the hour. product_card_attributed_gmv: $ref: "#/components/schemas/ProductCardAttributedGmv" description: GMV attributed to product cards during the hour. product_clicks: type: integer format: int64 description: Total number of product clicks during the hour. product_impressions: type: integer format: int64 description: Total number of product impressions during the hour. sku_orders_count: type: integer format: int64 description: The number of distinct SKUs sold during the hour. unique_clicks: type: integer format: int64 description: Total number of unique product clicks during the hour. unique_product_impressions: type: integer format: int64 description: Total number of unique product impressions during the hour. video_attributed_gmv: $ref: "#/components/schemas/VideoAttributedGmv" description: GMV attributed to videos during the hour. visitors: type: integer format: int64 description: Number of unique users who visited your product detail pages before the most recent update time. GetShopPerformancePerHourResponseDataPerformanceOverall: type: object properties: avg_order_value: $ref: "#/components/schemas/AvgOrderValue" description: Average order value during the requested date. avg_sku_order_value: $ref: "#/components/schemas/AvgSkuOrderValue" description: Average SKU order value during the requested date. customers: type: integer format: int64 description: The number of individual customers who made a purchase. This metric counts each customer once, even if they made multiple purchases. customers_count: type: integer format: int64 description: Number of unique users who paid for orders during the requested date. gmv: $ref: "#/components/schemas/Gmv" description: The total amount paid by customers, including shipping fees, but subtracts platform co-funding and seller promotions. GMV does not subtract cancellations or refunds. items_sold: type: integer format: int64 description: "The total number of individual items sold. Example: If a customer buys 3 units of SKU A and 2 units of SKU B, the items sold would be 5." live_attributed_gmv: $ref: "#/components/schemas/LiveAttributedGmv" description: GMV attributed to live streams during the requested date. orders_count: type: integer format: int64 description: The number of paid orders during the requested date. product_card_attributed_gmv: $ref: "#/components/schemas/ProductCardAttributedGmv" description: GMV attributed to product cards during the requested date. product_clicks: type: integer format: int64 description: Total number of product clicks during the requested date. product_impressions: type: integer format: int64 description: Total number of product impressions during the requested date. sku_orders_count: type: integer format: int64 description: The number of distinct SKUs sold during the requested date. unique_clicks: type: integer format: int64 description: Total number of unique product clicks during the requested date. unique_product_impressions: type: integer format: int64 description: Total number of unique product impressions during the requested date. video_attributed_gmv: $ref: "#/components/schemas/VideoAttributedGmv" description: GMV attributed to videos during the requested date. visitors: type: integer format: int64 description: Number of unique users who visited your product detail pages before the most recent update time. GetShopPerformanceResponse: 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/GetShopPerformanceResponseData" GetShopPerformanceResponseData: type: object properties: latest_available_date: type: string format: date description: Latest date in local timezone where data is ready (ISO 8601 format). performance: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformance" description: Overall performance data for the shop. GetShopPerformanceResponseDataPerformance: type: object properties: intervals: type: array items: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceInterval" description: Interval data for the requested time range. The time range of each interval is determined by the granularity. GetShopPerformanceResponseDataPerformanceInterval: type: object properties: breakdowns: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceIntervalBreakdown" description: Breakdowns of performance data by content type, channel, and attribution. end_date: type: string format: date description: End date of the interval (ISO 8601 YYYY-MM-DD format) in shop registered timezone, exclusive. sales: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceIntervalSale" description: Sales performance within the interval. start_date: type: string format: date description: Start date of the interval (ISO 8601 YYYY-MM-DD format) in shop registered timezone, inclusive. traffic: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceIntervalTraffic" description: Traffic data for the interval. GetShopPerformanceResponseDataPerformanceIntervalBreakdown: type: object properties: affiliate_product_card_attributed_gmv: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceIntervalBreakdownAffiliateProductCardAttributedGmv" description: GMV attributed to affiliate product cards. content_breakdown: type: array items: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceIntervalBreakdownContentBreakdown" description: GMV breakdown by content type and channel. seller_product_card_gmv: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceIntervalBreakdownSellerProductCardGmv" description: GMV from seller product cards. shop_tab_and_search: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceIntervalBreakdownShopTabAndSearch" description: Attribution breakdown by shop tab and search. GetShopPerformanceResponseDataPerformanceIntervalBreakdownAffiliateProductCardAttributedGmv: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). GetShopPerformanceResponseDataPerformanceIntervalBreakdownContentBreakdown: type: object properties: channel: type: string enum: - CREATOR - SELLER description: |- Channel type. Possible values: CREATOR, SELLER content_type: type: string enum: - LIVE - VIDEO description: |- Content type. Possible values: LIVE, VIDEO gmv: $ref: "#/components/schemas/Gmv" description: GMV for this content type and channel. indirect_gmv: $ref: "#/components/schemas/IndirectGmv" description: Indirect GMV for this content type and channel. GetShopPerformanceResponseDataPerformanceIntervalBreakdownSellerProductCardGmv: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). GetShopPerformanceResponseDataPerformanceIntervalBreakdownShopTabAndSearch: type: object properties: others: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceIntervalBreakdownShopTabAndSearchOther" description: GMV from other attribution sources. search_attributed: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceIntervalBreakdownShopTabAndSearchSearchAttributed" description: GMV attributed to search. shop_tab_attributed: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceIntervalBreakdownShopTabAndSearchShopTabAttributed" description: GMV attributed to shop tab. GetShopPerformanceResponseDataPerformanceIntervalBreakdownShopTabAndSearchOther: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). GetShopPerformanceResponseDataPerformanceIntervalBreakdownShopTabAndSearchSearchAttributed: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). GetShopPerformanceResponseDataPerformanceIntervalBreakdownShopTabAndSearchShopTabAttributed: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). GetShopPerformanceResponseDataPerformanceIntervalSale: type: object properties: avg_order_value: $ref: "#/components/schemas/AvgOrderValue" description: Average order value during the selected period. avg_sku_order_value: $ref: "#/components/schemas/AvgSkuOrderValue" description: Average SKU order value during the selected period. cancellations_and_returns: type: integer format: int64 description: Total number of cancellations and returns during the selected period. creator_live_attributed_gmv: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceIntervalSaleCreatorLiveAttributedGmv" description: GMV attributed to creator live streams. creator_live_gmv: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceIntervalSaleCreatorLiveGmv" description: GMV from creator live streams. creator_live_indirect_gmv: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceIntervalSaleCreatorLiveIndirectGmv" description: Indirect GMV from creator live streams. creator_video_attributed_gmv: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceIntervalSaleCreatorVideoAttributedGmv" description: GMV attributed to creator videos. creator_video_gmv: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceIntervalSaleCreatorVideoGmv" description: GMV from creator videos. creator_video_indirect_gmv: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceIntervalSaleCreatorVideoIndirectGmv" description: Indirect GMV from creator videos. customers_count: type: integer format: int64 description: Number of unique users who paid for orders during the selected period. gmv: $ref: "#/components/schemas/Gmv" description: "Gross merchandise value: Total amount paid for orders during the selected period, including canceled and refunded orders." gmv_with_tax: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceIntervalSaleGmvWithTax" description: GMV including tax. gmv_with_tiktok_co_funding: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceIntervalSaleGmvWithTiktokCoFunding" description: GMV including TikTok co-funding. items_sold: type: integer format: int64 description: "The total number of individual items sold. Example: If a customer buys 3 units of SKU A and 2 units of SKU B, the items sold would be 5." live_attributed_gmv: $ref: "#/components/schemas/LiveAttributedGmv" description: GMV attributed to live streams. live_gmv: $ref: "#/components/schemas/LiveGmv" description: GMV from live streams. live_indirect_gmv: $ref: "#/components/schemas/LiveIndirectGmv" description: Indirect GMV from live streams. orders_count: type: integer format: int64 description: The number of paid orders during the selected period. product_card_attributed_gmv: $ref: "#/components/schemas/ProductCardAttributedGmv" description: GMV attributed to product cards. refunds: $ref: "#/components/schemas/Refund" description: The amount of order refunds generated. seller_live_attributed_gmv: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceIntervalSaleSellerLiveAttributedGmv" description: GMV attributed to seller live streams. seller_live_gmv: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceIntervalSaleSellerLiveGmv" description: GMV from seller live streams. seller_live_indirect_gmv: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceIntervalSaleSellerLiveIndirectGmv" description: Indirect GMV from seller live streams. seller_video_attributed_gmv: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceIntervalSaleSellerVideoAttributedGmv" description: GMV attributed to seller videos. seller_video_gmv: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceIntervalSaleSellerVideoGmv" description: GMV from seller videos. seller_video_indirect_gmv: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceIntervalSaleSellerVideoIndirectGmv" description: Indirect GMV from seller videos. shipping_fees: $ref: "#/components/schemas/ShippingFee" description: Total shipping fees during the selected period. sku_orders_count: type: integer format: int64 description: A total count of distinct SKUs sold. tax: $ref: "#/components/schemas/Tax" description: Tax amount during the selected period. video_attributed_gmv: $ref: "#/components/schemas/VideoAttributedGmv" description: GMV attributed to videos. video_gmv: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceIntervalSaleVideoGmv" description: GMV from videos. video_indirect_gmv: $ref: "#/components/schemas/VideoIndirectGmv" description: Indirect GMV from videos. GetShopPerformanceResponseDataPerformanceIntervalSaleCreatorLiveAttributedGmv: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). GetShopPerformanceResponseDataPerformanceIntervalSaleCreatorLiveGmv: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). GetShopPerformanceResponseDataPerformanceIntervalSaleCreatorLiveIndirectGmv: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). GetShopPerformanceResponseDataPerformanceIntervalSaleCreatorVideoAttributedGmv: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). GetShopPerformanceResponseDataPerformanceIntervalSaleCreatorVideoGmv: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). GetShopPerformanceResponseDataPerformanceIntervalSaleCreatorVideoIndirectGmv: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). GetShopPerformanceResponseDataPerformanceIntervalSaleGmvWithTax: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). GetShopPerformanceResponseDataPerformanceIntervalSaleGmvWithTiktokCoFunding: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). GetShopPerformanceResponseDataPerformanceIntervalSaleSellerLiveAttributedGmv: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). GetShopPerformanceResponseDataPerformanceIntervalSaleSellerLiveGmv: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). GetShopPerformanceResponseDataPerformanceIntervalSaleSellerLiveIndirectGmv: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). GetShopPerformanceResponseDataPerformanceIntervalSaleSellerVideoAttributedGmv: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). GetShopPerformanceResponseDataPerformanceIntervalSaleSellerVideoGmv: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). GetShopPerformanceResponseDataPerformanceIntervalSaleSellerVideoIndirectGmv: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). GetShopPerformanceResponseDataPerformanceIntervalSaleVideoGmv: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). GetShopPerformanceResponseDataPerformanceIntervalTraffic: type: object properties: avg_conversation_rate: type: string description: The daily average percentage of unique users who paid for orders after viewing product detail pages during the selected period. avg_page_views: type: integer format: int64 description: Daily average number of page views for all of your product detail pages during the selected period. avg_visitors: type: integer format: int64 description: Daily average number of unique users who visited your product detail pages during the selected period product_clicks: type: integer format: int64 description: Total number of product clicks during the selected period. product_impressions: type: integer format: int64 description: Total number of product impressions during the selected period. unique_clicks: type: integer format: int64 description: Total number of unique clicks during the selected period. unique_product_impressions: type: integer format: int64 description: Total number of unique product impressions during the selected period. GetShopProductPerformanceDetailResponse: 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/GetShopProductPerformanceDetailResponseData" GetShopProductPerformanceDetailResponseData: type: object properties: performance: $ref: "#/components/schemas/GetShopProductPerformanceDetailResponseDataPerformance" description: Overall performance data for the product. latest_available_date: type: string format: date description: Latest date in local timezone where data is ready (ISO 8601 format). GetShopProductPerformanceDetailResponseDataPerformance: type: object properties: intervals: type: array items: $ref: "#/components/schemas/GetShopProductPerformanceDetailResponseDataPerformanceInterval" description: Interval data for the requested time range. The time range of each interval is determined by the granularity. ratings: type: array items: $ref: "#/components/schemas/GetShopProductPerformanceDetailResponseDataPerformanceRating" description: ratings within the choosen start_date_ge and end_date_ge top_contents: type: array items: $ref: "#/components/schemas/GetShopProductPerformanceDetailResponseDataPerformanceTopContent" description: |- Product-related content for the period from `start_date_ge` (inclusive) to `end_date_lt` (exclusive). Sorted by GMV; returns only the top 100. top_creators: type: array items: $ref: "#/components/schemas/GetShopProductPerformanceDetailResponseDataPerformanceTopCreator" description: |- Product-related creators for the period from `start_date_ge` (inclusive) to `end_date_lt` (exclusive). Sorted by GMV; returns only the top 100. GetShopProductPerformanceDetailResponseDataPerformanceInterval: type: object properties: start_date: type: string format: date description: Start date of the interval (ISO 8601 YYYY-MM-DD format) in shop registered timezone, inclusive. end_date: type: string format: date description: End date of the interval (ISO 8601 YYYY-MM-DD format) in shop registered timezone, exclusive. sales: $ref: "#/components/schemas/GetShopProductPerformanceDetailResponseDataPerformanceIntervalSale" description: Sales performance within the interval. traffic: $ref: "#/components/schemas/GetShopProductPerformanceDetailResponseDataPerformanceIntervalTraffic" description: Traffic performance. cancel_and_refunds: $ref: "#/components/schemas/GetShopProductPerformanceDetailResponseDataPerformanceIntervalCancelAndRefund" description: cancel and refunds data GetShopProductPerformanceDetailResponseDataPerformanceIntervalCancelAndRefund: type: object properties: returned: type: integer format: int64 description: Returned refers to units that were returned and refunded. canceled: type: integer format: int64 description: Canceled refers to units included in orders that were either "Unpaid" or "Awaiting Shipment." refunded: type: integer format: int64 description: Refunded refers to units that were refunded but not returned. replacements: type: integer format: int64 description: Replacements refers to units that were returned and replaced. GetShopProductPerformanceDetailResponseDataPerformanceIntervalSale: type: object properties: gmv: $ref: "#/components/schemas/Gmv" description: "Gross merchandise value: Total amount paid for orders during the selected period, including canceled and refunded orders." orders: type: integer format: int64 description: Total (sum of all) orders for the product. items_sold: type: integer format: int64 description: Number of items sold for the product. breakdowns: type: array items: $ref: "#/components/schemas/GetShopProductPerformanceDetailResponseDataPerformanceIntervalSaleBreakdown" description: Sales breakdowns. GetShopProductPerformanceDetailResponseDataPerformanceIntervalSaleBreakdown: type: object properties: content_type: type: string enum: - VIDEO - LIVE - PRODUCT_CARD x-enum-descriptions: - Video content. - Live stream content. - Product card. description: |- Sales breakdown content type. Possible values: - VIDEO: Video content. - LIVE: Live stream content. - PRODUCT_CARD: Product card. sales: $ref: "#/components/schemas/GetShopProductPerformanceDetailResponseDataPerformanceIntervalSaleBreakdownSale" description: Sales of the corresponding content type. GetShopProductPerformanceDetailResponseDataPerformanceIntervalSaleBreakdownSale: type: object properties: gmv: $ref: "#/components/schemas/Gmv" description: Gross merchandise value. items_sold: type: integer format: int64 description: Number of items sold in the corresponding content type. avg_customers: type: integer format: int64 description: Daily average count of customers. GetShopProductPerformanceDetailResponseDataPerformanceIntervalTraffic: type: object properties: breakdowns: type: array items: $ref: "#/components/schemas/GetShopProductPerformanceDetailResponseDataPerformanceIntervalTrafficBreakdown" description: Traffic breakdowns. GetShopProductPerformanceDetailResponseDataPerformanceIntervalTrafficBreakdown: type: object properties: traffic: $ref: "#/components/schemas/GetShopProductPerformanceDetailResponseDataPerformanceIntervalTrafficBreakdownTraffic" description: Traffic performance of the corresponding content type. content_type: type: string enum: - VIDEO - LIVE - PRODUCT_CARD x-enum-descriptions: - Video content. - Live stream content. - Product card. description: |- Traffic breakdown content type. Possible values: - VIDEO: Video content. - LIVE: Live stream content. - PRODUCT_CARD: Product card. GetShopProductPerformanceDetailResponseDataPerformanceIntervalTrafficBreakdownTraffic: type: object properties: impressions: type: integer format: int64 description: Each time a link to your listing appears in the shop tab, it's counted as one impression. Users can tap links to visit your listings page directly. page_views: type: integer format: int64 description: Total number of product details page views during the selected period, including multiple views from unique users. avg_unique_page_views: type: integer format: int64 description: Daily average unique views visitors to your product details pages. ctr: type: string description: The percentage of viewers who clicked on product links after seeing them in the Shop tab. Number of clicks divided by the number of views. avg_conversion_rate: type: string description: Average percentage of unique page views that result in sales. GetShopProductPerformanceDetailResponseDataPerformanceRating: type: object properties: stars: type: string enum: - 1_STAR - 2_STAR - 3_STAR - 4_STAR - 5_STAR x-enum-descriptions: - One-star rating. - Two-star rating. - Three-star rating. - Four-star rating. - Five-star rating. description: |- Rating star bucket. Possible values: - 1_STAR: One-star rating. - 2_STAR: Two-star rating. - 3_STAR: Three-star rating. - 4_STAR: Four-star rating. - 5_STAR: Five-star rating. count: type: integer format: int64 description: Number of reviews in the corresponding rating. percentage: type: string description: Share of all product reviews in the corresponding rating bucket. The value is the bucket's review count divided by the total product review count and is returned as a decimal from 0 to 1, rounded to four decimal places. For example, `0.23` means 23%. GetShopProductPerformanceDetailResponseDataPerformanceTopContent: type: object properties: type: type: string enum: - LIVE - VIDEO x-enum-descriptions: - Live stream content. - Video content. description: |- Top content type. Possible values: - LIVE: Live stream content. - VIDEO: Video content. contents: type: array items: $ref: "#/components/schemas/GetShopProductPerformanceDetailResponseDataPerformanceTopContentContent" description: Content details GetShopProductPerformanceDetailResponseDataPerformanceTopContentContent: type: object properties: content_id: type: string description: LIVE session ID or video ID items_sold: type: integer format: int64 description: Number of items sold in the corresponding content. gmv: $ref: "#/components/schemas/Gmv" description: Gross merchandise value. GetShopProductPerformanceDetailResponseDataPerformanceTopCreator: type: object properties: creator_open_id: type: string description: Creator/s open id, use this open id to identify the unique creator. creator_name: type: string description: Creator name shown on the profile page. creator_profile: type: string description: The URL to the creator's profile picture. gmv: $ref: "#/components/schemas/Gmv" description: The GMV created by this creator. items_sold: type: integer format: int64 description: Number of items sold by this creator. GetShopProductPerformanceListResponse: 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/GetShopProductPerformanceListResponseData" GetShopProductPerformanceListResponseData: type: object properties: products: type: array items: $ref: "#/components/schemas/GetShopProductPerformanceListResponseDataProduct" description: List of product performance metrics. next_page_token: type: string description: Page token for the next page. Pass this value as `page_token` in the next request and reuse the same `start_date_ge`, `end_date_lt`, `sort_field`, `sort_order`, `currency`, `category_filter`, `product_status_filter`, and `page_size` values. An empty value means there is no next page. total_count: type: integer format: int64 description: Total number of products that match the request filters across all pages. latest_available_date: type: string format: date description: Latest date in local timezone where data is ready (ISO 8601 format). GetShopProductPerformanceListResponseDataProduct: type: object properties: id: type: string description: Product ID. total_performance: $ref: "#/components/schemas/GetShopProductPerformanceListResponseDataProductTotalPerformance" description: Product total sales performance. seller_live_performance: $ref: "#/components/schemas/GetShopProductPerformanceListResponseDataProductSellerLivePerformance" description: Performance metrics from seller's live streaming. seller_video_performance: $ref: "#/components/schemas/GetShopProductPerformanceListResponseDataProductSellerVideoPerformance" description: Performance metrics from seller's video content. seller_product_card_performance: $ref: "#/components/schemas/GetShopProductPerformanceListResponseDataProductSellerProductCardPerformance" description: Performance metrics from seller's product card exposure. affiliate_total_performance: $ref: "#/components/schemas/GetShopProductPerformanceListResponseDataProductAffiliateTotalPerformance" description: Total performance metrics from affiliate channel. affiliate_live_performance: $ref: "#/components/schemas/GetShopProductPerformanceListResponseDataProductAffiliateLivePerformance" description: Performance metrics from affiliate live streaming. affiliate_video_performance: $ref: "#/components/schemas/GetShopProductPerformanceListResponseDataProductAffiliateVideoPerformance" description: Performance metrics from affiliate video content. shop_tab_performance: $ref: "#/components/schemas/GetShopProductPerformanceListResponseDataProductShopTabPerformance" description: Performance metrics from shop tab. GetShopProductPerformanceListResponseDataProductAffiliateLivePerformance: type: object properties: live_attributed_gmv: $ref: "#/components/schemas/LiveAttributedGmv" description: GMV attributed from affiliate live. new_live_count: type: integer format: int64 description: Number of new live streams from affiliate. product_impressions: type: integer format: int64 description: Product impressions from affiliate live. product_clicks: type: integer format: int64 description: Product clicks from affiliate live. ctr: type: string description: Click-through rate from affiliate live. add_cart_count: type: integer format: int64 description: Number of times products were added to cart from affiliate live. add_cart_rate: type: string description: Add to cart rate from affiliate live. click_order_rate: type: string description: Click to order rate from affiliate live. unique_product_impressions: type: integer format: int64 description: Unique product impressions from affiliate live. unique_clicks: type: integer format: int64 description: Unique clicks from affiliate live. unique_ctr: type: string description: Unique click-through rate from affiliate live. atc_users: type: integer format: int64 description: Number of users who added to cart from affiliate live. unique_atc_rate: type: string description: Unique add to cart rate from affiliate live. unique_click_order_rate: type: string description: Unique click to order rate from affiliate live. GetShopProductPerformanceListResponseDataProductAffiliateTotalPerformance: type: object properties: attributed_gmv: $ref: "#/components/schemas/AttributedGmv" description: GMV attributed from affiliate. attributed_orders: type: integer format: int64 description: Number of orders attributed from affiliate. attributed_sku_orders: type: integer format: int64 description: Number of SKU orders attributed from affiliate. attributed_sold_items: type: integer format: int64 description: Number of items sold attributed from affiliate. estimated_customers: type: integer format: int64 description: Estimated number of customers from affiliate. aov: $ref: "#/components/schemas/Aov" description: Average order value from affiliate. avg_daily_creator_posted_content: type: integer format: int64 description: Average daily number of creator-posted content. product_impressions: type: integer format: int64 description: Product impressions from affiliate. product_clicks: type: integer format: int64 description: Product clicks from affiliate. ctr: type: string description: Click-through rate from affiliate. add_cart_count: type: integer format: int64 description: Number of times products were added to cart from affiliate. add_cart_rate: type: string description: Add to cart rate from affiliate. click_order_rate: type: string description: Click to order rate from affiliate. unique_product_impressions: type: integer format: int64 description: Unique product impressions from affiliate. unique_clicks: type: integer format: int64 description: Unique clicks from affiliate. unique_ctr: type: string description: Unique click-through rate from affiliate. add_cart_users: type: integer format: int64 description: Number of users who added to cart from affiliate. unique_atc_rate: type: string description: Unique add to cart rate from affiliate. unique_click_order_rate: type: string description: Unique click to order rate from affiliate. GetShopProductPerformanceListResponseDataProductAffiliateVideoPerformance: type: object properties: attributed_video_gmv: $ref: "#/components/schemas/GetShopProductPerformanceListResponseDataProductAffiliateVideoPerformanceAttributedVideoGmv" description: GMV attributed from affiliate video. new_video_count: type: integer format: int64 description: Number of new videos from affiliate. product_impressions: type: integer format: int64 description: Product impressions from affiliate video. product_clicks: type: integer format: int64 description: Product clicks from affiliate video. ctr: type: string description: Click-through rate from affiliate video. add_cart_count: type: integer format: int64 description: Number of times products were added to cart from affiliate video. add_cart_rate: type: string description: Add to cart rate from affiliate video. click_order_rate: type: string description: Click to order rate from affiliate video. unique_product_impressions: type: integer format: int64 description: Unique product impressions from affiliate video. unique_clicks: type: integer format: int64 description: Unique clicks from affiliate video. unique_ctr: type: string description: Unique click-through rate from affiliate video. atc_users: type: integer format: int64 description: Number of users who added to cart from affiliate video. unique_atc_rate: type: string description: Unique add to cart rate from affiliate video. unique_click_order_rate: type: string description: Unique click to order rate from affiliate video. GetShopProductPerformanceListResponseDataProductAffiliateVideoPerformanceAttributedVideoGmv: type: object properties: amount: type: string description: Attributed GMV amount. currency: type: string description: Attributed GMV currency code. GetShopProductPerformanceListResponseDataProductSellerLivePerformance: type: object properties: attributed_gmv: $ref: "#/components/schemas/AttributedGmv" description: Attributed gross merchandise value. attributed_orders: type: integer format: int64 description: Number of attributed orders. attributed_sku_orders: type: integer format: int64 description: Number of attributed SKU orders. attributed_sold_items: type: integer format: int64 description: Number of attributed items sold. estimated_customers: type: integer format: int64 description: Estimated number of customers. aov: $ref: "#/components/schemas/Aov" description: Average order value. new_live_count: type: integer format: int64 description: Number of new live streams. product_impressions: type: integer format: int64 description: Number of product impressions. product_clicks: type: integer format: int64 description: Number of product clicks. ctr: type: string description: Click-through rate. add_cart_count: type: integer format: int64 description: Number of times products were added to the cart. add_cart_rate: type: string description: Add to cart rate. click_order_rate: type: string description: Click to order rate. unique_product_impressions: type: integer format: int64 description: Number of unique product impressions from seller live streaming. unique_clicks: type: integer format: int64 description: Number of unique product clicks from seller live streaming. unique_ctr: type: string description: Unique click-through rate. add_cart_users: type: integer format: int64 description: Number of users who added to cart. unique_atc_rate: type: string description: Unique add to cart rate. unique_click_order_rate: type: string description: Unique click to order rate. GetShopProductPerformanceListResponseDataProductSellerProductCardPerformance: type: object properties: attributed_gmv: $ref: "#/components/schemas/AttributedGmv" description: Attributed gross merchandise value. attributed_orders: type: integer format: int64 description: Number of attributed orders. attributed_sku_orders: type: integer format: int64 description: Number of attributed SKU orders. attributed_sold_items: type: integer format: int64 description: Number of attributed items sold. estimated_customers: type: integer format: int64 description: Estimated number of customers. aov: $ref: "#/components/schemas/Aov" description: Average order value. product_impressions: type: integer format: int64 description: Number of product impressions. product_clicks: type: integer format: int64 description: Number of product clicks. ctr: type: string description: Click-through rate. add_cart_count: type: integer format: int64 description: Number of times products were added to the cart. add_cart_rate: type: string description: Add to cart rate. click_order_rate: type: string description: Click to order rate. unique_product_impressions: type: integer format: int64 description: Number of unique product impressions from seller product card exposure. unique_clicks: type: integer format: int64 description: Number of unique product clicks from seller product card exposure. unique_ctr: type: string description: Unique click-through rate. add_cart_users: type: integer format: int64 description: Number of users who added to cart. unique_atc_rate: type: string description: Unique add to cart rate. unique_click_order_rate: type: string description: Unique click to order rate. GetShopProductPerformanceListResponseDataProductSellerVideoPerformance: type: object properties: attributed_gmv: $ref: "#/components/schemas/AttributedGmv" description: Attributed gross merchandise value. attributed_orders: type: integer format: int64 description: Number of attributed orders. attributed_sku_orders: type: integer format: int64 description: Number of attributed SKU orders. attributed_sold_items: type: integer format: int64 description: Number of attributed items sold. estimated_customers: type: integer format: int64 description: Estimated number of customers. aov: $ref: "#/components/schemas/Aov" description: Average order value. new_video_count: type: integer format: int64 description: Number of new videos. product_impressions: type: integer format: int64 description: Number of product impressions. product_clicks: type: integer format: int64 description: Number of product clicks. ctr: type: string description: Click-through rate. add_cart_count: type: integer format: int64 description: Number of times products were added to the cart. add_cart_rate: type: string description: Add to cart rate. click_order_rate: type: string description: Click to order rate. unique_product_impressions: type: integer format: int64 description: Number of unique product impressions from seller video content. unique_clicks: type: integer format: int64 description: Number of unique product clicks from seller video content. unique_ctr: type: string description: Unique click-through rate. add_cart_users: type: integer format: int64 description: Number of users who added to cart. unique_atc_rate: type: string description: Unique add to cart rate. unique_click_order_rate: type: string description: Unique click to order rate. GetShopProductPerformanceListResponseDataProductShopTabPerformance: type: object properties: shop_tab_product_impressions: type: integer format: int64 description: Number of product impressions from Shop Tab. shop_tab_product_clicks: type: integer format: int64 description: Number of product clicks from Shop Tab. unique_shop_tab_product_clicks: type: integer format: int64 description: Number of unique product clicks from Shop Tab. estimated_shop_tab_customers: type: integer format: int64 description: Estimated number of customers from Shop Tab. shop_tab_ctr: type: string description: Click-through rate from Shop Tab. shop_tab_ctor_sku: type: string description: Click-to-order rate (SKU level) from Shop Tab. shop_tab_gmv: $ref: "#/components/schemas/GetShopProductPerformanceListResponseDataProductShopTabPerformanceShopTabGmv" description: GMV generated from shop tab. shop_tab_sold_items: type: integer format: int64 description: Items sold via shop tab. GetShopProductPerformanceListResponseDataProductShopTabPerformanceShopTabGmv: type: object properties: amount: type: string description: GMV amount. currency: type: string description: Currency code. GetShopProductPerformanceListResponseDataProductTotalPerformance: type: object properties: gmv: $ref: "#/components/schemas/Gmv" description: Gross merchandise value. orders: type: integer format: int64 description: Number of orders. sku_orders: type: integer format: int64 description: Number of SKU orders. items_sold: type: integer format: int64 description: Number of items sold. estimated_customers: type: integer format: int64 description: Estimated number of customers. aov: $ref: "#/components/schemas/Aov" description: Average order SKU value. product_impressions: type: integer format: int64 description: Number of product impressions. product_clicks: type: integer format: int64 description: Number of product clicks. ctr: type: string description: Click-through rate. add_cart_count: type: integer format: int64 description: Number of times products were added to the cart. add_cart_rate: type: string description: Add to cart rate. click_order_rate: type: string description: Click to order rate. unique_product_impressions: type: integer format: int64 description: Unique product impressions. unique_clicks: type: integer format: int64 description: Total number of unique product clicks across the product performance channels. unique_ctr: type: string description: Unique click-through rate. add_cart_users: type: integer format: int64 description: Number of users who added to cart. unique_atc_rate: type: string description: Unique add to cart rate. unique_click_order_rate: type: string description: Unique click to order rate. gmv_incl_tax: $ref: "#/components/schemas/GetShopProductPerformanceListResponseDataProductTotalPerformanceGmvInclTax" description: GMV including tax. This field only returns the local currency. tax: $ref: "#/components/schemas/Tax" description: Tax amount. This field only returns the local currency. gross_merchandise_value: $ref: "#/components/schemas/GetShopProductPerformanceListResponseDataProductTotalPerformanceGrossMerchandiseValue" description: Gross merchandise value for the product, including amount and currency. shipping_fees: $ref: "#/components/schemas/ShippingFee" description: Shipping fees. This field only returns the local currency. refunds: $ref: "#/components/schemas/Refund" description: Refund amount. refunded_items: type: integer format: int64 description: Number of items refunded. refund_customers: type: integer format: int64 description: Number of customers who received refunds. GetShopProductPerformanceListResponseDataProductTotalPerformanceGmvInclTax: type: object properties: amount: type: string description: GMV with tax amount. currency: type: string description: GMV with tax currency code. GetShopProductPerformanceListResponseDataProductTotalPerformanceGrossMerchandiseValue: type: object properties: amount: type: string description: Gross merchandise value amount. currency: type: string description: Gross merchandise value currency code. GetShopProductsResponse: 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/GetShopProductsResponseData" GetShopProductsResponseData: type: object properties: products: type: array items: $ref: "#/components/schemas/GetShopProductsResponseDataProduct" description: The searched product list. It will be empty when there are no search results. total_count: type: integer format: int64 description: The total number of products that meet the query conditions. next_page_token: type: string description: An opaque token used to retrieve the next page. Pass it as `page_token` in the next request. It is empty when there are no more products to retrieve. GetShopProductsResponseDataProduct: type: object properties: id: type: string description: TikTok product ID. title: type: string description: Product name. price: $ref: "#/components/schemas/Price" description: Product price shown with two decimal places and currency. added_status: type: string enum: - ADDABLE - ADDED - REJECTED description: |- Showcase add status with possible values: - ADDABLE - ADDED - REJECTED brand_name: type: string description: The brand name a seller has set for a product. images: type: array items: $ref: "#/components/schemas/GetReturnRecordsResponseDataRecordImage" description: Images of a product. sales_count: type: integer format: int64 description: The number of products that have been sold. GetShopSKPPSummaryResponse: 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/GetShopSKPPSummaryResponseData" GetShopSKPPSummaryResponseData: type: object properties: shop_summary: $ref: "#/components/schemas/GetShopSKPPSummaryResponseDataShopSummary" description: The shop-level SKPP summary of qualified and eligible product counts, earned ad credit, and incremental visibility in the last 30 days. GetShopSKPPSummaryResponseDataShopSummary: type: object properties: qualified_products_count: type: integer format: int64 description: Number of products that are already SKPP. eligible_products_count: type: integer format: int64 description: Number of products that are already SKPP, plus those that have not yet met the standard but can take SKPP tasks. earned_ad_credit: type: string description: Total ad credit earned by the shop, currency-prefixed. increased_visibility_l30d: type: string description: Incremental visibility gained from SKPP rewards in the last 30 days. GetShopSKUPerformanceDetailResponse: 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/GetShopSKUPerformanceDetailResponseData" GetShopSKUPerformanceDetailResponseData: type: object properties: latest_available_date: type: string format: date description: Latest date in local timezone where data is ready (ISO 8601 format). performance: $ref: "#/components/schemas/GetShopSKUPerformanceDetailResponseDataPerformance" description: Overall performance data for the SKU. GetShopSKUPerformanceDetailResponseDataPerformance: type: object properties: product_id: type: integer format: int64 description: The ID of the product that the SKU belongs to. sku_id: type: string description: The ID of the SKU for this performance object. intervals: type: array items: $ref: "#/components/schemas/GetShopSKUPerformanceDetailResponseDataPerformanceInterval" description: Interval data for the requested time range. The time range of each interval is determined by the granularity. GetShopSKUPerformanceDetailResponseDataPerformanceInterval: type: object properties: start_date: type: string format: date description: Start date of the interval (ISO 8601 YYYY-MM-DD format) in shop registered timezone, inclusive. end_date: type: string format: date description: End date of the interval (ISO 8601 YYYY-MM-DD format) in shop registered timezone, exclusive. gmv: $ref: "#/components/schemas/Gmv" description: Overall Gross Merchandise Value (GMV) for the SKU. gmv_breakdown: type: array items: $ref: "#/components/schemas/GetShopSKUPerformanceDetailResponseDataPerformanceIntervalGmvBreakdown" description: GMV breakdowns for the SKU. items_sold: type: integer format: int64 description: Number of units sold for the SKU. items_sold_breakdown: type: array items: $ref: "#/components/schemas/GetShopSKUPerformanceDetailResponseDataPerformanceIntervalItemsSoldBreakdown" description: Unit sold breakdowns. sku_orders: type: integer format: int64 description: Total (sum of all) orders for the SKU. GetShopSKUPerformanceDetailResponseDataPerformanceIntervalGmvBreakdown: type: object properties: amount: type: string description: GMV amount for the corresponding type and 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). type: type: string enum: - LIVE - VIDEO - PRODUCT_CARD x-enum-descriptions: - Live stream content. - Video content. - Product card. description: |- GMV breakdown type. Possible values: - LIVE: Live stream content. - VIDEO: Video content. - PRODUCT_CARD: Product card. GetShopSKUPerformanceDetailResponseDataPerformanceIntervalItemsSoldBreakdown: type: object properties: amount: type: integer format: int64 description: Number of units sold for the corresponding type. type: type: string enum: - LIVE - VIDEO - PRODUCT_CARD x-enum-descriptions: - Live stream content. - Video content. - Product card. description: |- Items-sold breakdown type. Possible values: - LIVE: Live stream content. - VIDEO: Video content. - PRODUCT_CARD: Product card. GetShopSKUPerformanceListResponse: 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/GetShopSKUPerformanceListResponseData" GetShopSKUPerformanceListResponseData: type: object properties: skus: type: array items: $ref: "#/components/schemas/GetShopSKUPerformanceListResponseDataSku" description: List of SKU performance metrics. next_page_token: type: string description: If nonempty, pass this token unchanged as `page_token` in the next request and reuse the same `start_date_ge`, `end_date_lt`, `page_size`, `sort_field`, `sort_order`, `currency`, `category_filter`, `product_status_filter`, and `product_ids` values. For optional parameters, preserve whether each parameter was omitted or present. An empty string means there are no more pages. total_count: type: integer format: int64 description: Total number of SKUs matching the request filters across all pages. latest_available_date: type: string format: date description: Latest date in local timezone where data is ready (ISO 8601 format). GetShopSKUPerformanceListResponseDataSku: type: object properties: id: type: integer format: int64 description: The ID of the SKU in the returned SKU performance record. product_id: type: integer format: int64 description: The ID of the product that the returned SKU belongs to. gmv: $ref: "#/components/schemas/Gmv" description: Overall Gross Merchandise Value (GMV) for the SKU. sku_orders: type: integer format: int64 description: Total (sum of all) orders for a SKU units_sold: type: integer format: int64 description: Number of units sold for a SKU GetShopVideoPerformanceDetailsResponse: 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/GetShopVideoPerformanceDetailsResponseData" GetShopVideoPerformanceDetailsResponseData: type: object properties: performance: $ref: "#/components/schemas/GetShopVideoPerformanceDetailsResponseDataPerformance" description: Overall performance data for the video. latest_available_date: type: string format: date description: Latest date in local timezone where data is ready (ISO 8601 format). GetShopVideoPerformanceDetailsResponseDataPerformance: type: object properties: intervals: type: array items: $ref: "#/components/schemas/GetShopVideoPerformanceDetailsResponseDataPerformanceInterval" description: Interval data for the requested time range. The time range of each interval is determined by the granularity. viewer_profile: type: array items: $ref: "#/components/schemas/GetShopVideoPerformanceDetailsResponseDataPerformanceViewerProfile" description: Viewer profile of the video GetShopVideoPerformanceDetailsResponseDataPerformanceInterval: type: object properties: start_date: type: string format: date description: Start date of the interval (ISO 8601 YYYY-MM-DD format) in shop registered timezone, inclusive. end_date: type: string format: date description: End date of the interval (ISO 8601 YYYY-MM-DD format) in shop registered timezone, exclusive. sales: $ref: "#/components/schemas/GetShopVideoPerformanceDetailsResponseDataPerformanceIntervalSale" description: Sale performance data. traffic: $ref: "#/components/schemas/GetShopVideoPerformanceDetailsResponseDataPerformanceIntervalTraffic" description: Traffic performance of the video. GetShopVideoPerformanceDetailsResponseDataPerformanceIntervalSale: type: object properties: overall: $ref: "#/components/schemas/GetShopVideoPerformanceDetailsResponseDataPerformanceIntervalSaleOverall" description: Overall performance breakdowns: type: array items: $ref: "#/components/schemas/GetShopVideoPerformanceDetailsResponseDataPerformanceIntervalSaleBreakdown" description: Breakdown data for product-level sales performance in each interval. GetShopVideoPerformanceDetailsResponseDataPerformanceIntervalSaleBreakdown: type: object properties: product_id: type: string description: Id of the product linked to this video gmv: $ref: "#/components/schemas/Gmv" description: Gross merchandise value (GMV) for this product in the interval. gpm: $ref: "#/components/schemas/Gpm" description: Average GMV generated for this product per 1,000 video impressions in the interval. customers: type: integer format: int64 description: The total number of customers who placed orders directly from the shoppable video. items_sold: type: integer format: int64 description: The total number of items sold directly from the shoppable video. ctr: type: string description: The number of product clicks from the video / The number of impressions of all video products product_impressions: type: integer format: int64 description: The number of impressions of all video products product_clicks: type: integer format: int64 description: The number of product clicks from the video GetShopVideoPerformanceDetailsResponseDataPerformanceIntervalSaleOverall: type: object properties: gmv: $ref: "#/components/schemas/Gmv" description: The total amount paid for orders placed directly from the shoppable video, including returns and refunds. gpm: $ref: "#/components/schemas/Gpm" description: The avg. video GPM is the average GMV generated from 1,000 impressions of the Video. customers: type: integer format: int64 description: The total number of customers who placed orders directly from the shoppable video. items_sold: type: integer format: int64 description: The total number of items sold directly from the shoppable video. ctr: type: string description: Ratio of product clicks from the video to impressions of all products in the video, expressed as a decimal fraction. product_impressions: type: integer format: int64 description: The number of impressions of all video products product_clicks: type: integer format: int64 description: The number of product clicks from the video GetShopVideoPerformanceDetailsResponseDataPerformanceIntervalTraffic: type: object properties: views: type: integer format: int64 description: Number of times the requested video was watched during the interval. Repeat views by the same user are counted separately. new_followers: type: integer format: int64 description: The number of times a user followed you after watching a video shares: type: integer format: int64 description: The cumulative number of times users shared the video comments: type: integer format: int64 description: The cumulative number of times users left comments on the video likes: type: integer format: int64 description: The cumulative number of times users liked the video GetShopVideoPerformanceDetailsResponseDataPerformanceViewerProfile: type: object properties: type: type: string enum: - NEW_FOLLOWER - VIEWERS x-enum-descriptions: - viewers who newly followed after watching the video - viewers of the video description: |- Viewer profile type. Possible values: - NEW_FOLLOWER: viewers who newly followed after watching the video - VIEWERS: viewers of the video gender_distribution: type: array items: $ref: "#/components/schemas/GenderDistribution" description: View gender distribution age_distribution: type: array items: $ref: "#/components/schemas/AgeDistribution" description: Viewer age distribution country_distribution: type: array items: $ref: "#/components/schemas/CountryDistribution" description: Viewer country distribution. GetShopVideoPerformanceListResponse: 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/GetShopVideoPerformanceListResponseData" GetShopVideoPerformanceListResponseData: type: object properties: latest_available_date: type: string format: date description: Latest date in local timezone where data is ready (ISO 8601 format). next_page_token: type: string description: Page token for the next page request. Pass a nonempty returned token as `page_token` in the next request and reuse the same `start_date_ge`, `end_date_lt`, `sort_field`, `sort_order`, `currency`, `account_type`, and `page_size` values. An empty value means there are no more pages. total_count: type: integer format: int64 description: Total number of videos matching the request filters across all pages. videos: type: array items: $ref: "#/components/schemas/GetShopVideoPerformanceListResponseDataVideo" description: List of video performance metrics. GetShopVideoPerformanceListResponseDataVideo: type: object properties: advertisable: type: boolean description: Whether the video can be used for advertising. attributed_gmv: $ref: "#/components/schemas/AttributedGmv" description: Total GMV attributed to the video. avg_customers: type: integer format: int64 description: Daily average customers. click_through_rate: type: string description: Ratio of product clicks to video views in raw decimal format. comments: type: integer format: int64 description: Number of comments received by the video. creator: $ref: "#/components/schemas/GetShopVideoPerformanceListResponseDataVideoCreator" description: Creator information for the video. ctor: type: string description: Click-to-order rate in raw decimal format. duration: type: integer format: int64 description: Video duration in seconds. gmv: $ref: "#/components/schemas/Gmv" description: GMV directly attributed to the video. gpm: $ref: "#/components/schemas/Gpm" description: Average GMV generated from 1,000 video views. hash_tags: type: array items: type: string description: Hash tags of the video. id: type: string description: The unique identifier of the video in the performance list. indirect_gmv: $ref: "#/components/schemas/IndirectGmv" description: Indirect GMV attributed to the video. items_sold: type: integer format: int64 description: Number of units sold from the video. likes: type: integer format: int64 description: Number of likes received by the video. new_followers: type: integer format: int64 description: Number of new followers attributed to the video. product_clicks: type: integer format: int64 description: Number of product clicks from the video. product_impressions: type: integer format: int64 description: Number of product impressions from the video. products: type: array items: $ref: "#/components/schemas/GetShopVideoPerformanceListResponseDataVideoProduct" description: Products promoted in the video. review_type: type: string description: Review classification of the video. shares: type: integer format: int64 description: Number of times the video was shared. sku_orders: type: integer format: int64 description: The total number of paid SKU orders placed directly from the current video. title: type: string description: The title of the video. username: type: string description: The username associated with the video. v_to_l_clicks: type: integer format: int64 description: Number of clicks from the video to a LIVE session. v_to_l_rate: type: string description: Rate of clicks from the video to a LIVE session in raw decimal format. video_finish_rate: type: string description: Video completion rate in raw decimal format. video_post_time: type: string description: Date and time when the video was posted. views: type: integer format: int64 description: Number of video views during the selected time range. GetShopVideoPerformanceListResponseDataVideoCreator: type: object properties: author_type: type: string description: Creator account type. creator_country: type: string description: Country or region of the creator. creator_id: type: string description: The creator ID. nick_name: type: string description: Creator nickname. open_id: type: string description: The creator open ID. user_name: type: string description: Creator username (handle). GetShopVideoPerformanceListResponseDataVideoProduct: type: object properties: id: type: string description: The unique identifier of the product. name: type: string description: The product name. GetShopVideoPerformanceOverviewResponse: 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/GetShopVideoPerformanceOverviewResponseData" GetShopVideoPerformanceOverviewResponseData: type: object properties: latest_available_date: type: string format: date description: Latest date in local timezone where data is ready (ISO 8601 format). performance: $ref: "#/components/schemas/GetShopVideoPerformanceOverviewResponseDataPerformance" description: Overall performance data for videos. GetShopVideoPerformanceOverviewResponseDataPerformance: type: object properties: intervals: type: array items: $ref: "#/components/schemas/GetShopVideoPerformanceOverviewResponseDataPerformanceInterval" description: Interval data for the requested time range. The time range of each interval is determined by the granularity. GetShopVideoPerformanceOverviewResponseDataPerformanceInterval: type: object properties: avg_daily_customers: type: integer format: int64 description: Daily average number of customers. ctor_sku_order: type: string description: Conversion rate from product clicks to SKU orders in raw decimal format. ctr: type: string description: Ratio of product clicks to video views in raw decimal format. end_date: type: string format: date description: End date of the interval (ISO 8601 YYYY-MM-DD format) in shop registered timezone, exclusive. gpm: $ref: "#/components/schemas/Gpm" description: GMV per thousand video views. Returned only for offline data. product_clicks: type: integer format: int64 description: The number of product clicks from videos. product_impressions: type: integer format: int64 description: The number of impressions of all video products. shoppable_video_attributed_gmv: $ref: "#/components/schemas/GetShopVideoPerformanceOverviewResponseDataPerformanceIntervalShoppableVideoAttributedGmv" description: GMV attributed to shoppable videos. Returned only for offline data. start_date: type: string format: date description: Start date of the interval (ISO 8601 YYYY-MM-DD format) in shop registered timezone, inclusive. today: type: boolean description: Whether the interval contains real-time data for today. video_attributed_gmv: $ref: "#/components/schemas/VideoAttributedGmv" description: GMV attributed to videos. video_attributed_sku_orders: type: integer format: int64 description: The number of paid SKU orders attributed to videos. video_gmv: $ref: "#/components/schemas/GetShopPerformanceResponseDataPerformanceIntervalSaleVideoGmv" description: GMV from videos. video_indirect_gmv: $ref: "#/components/schemas/VideoIndirectGmv" description: Indirect GMV from videos. video_product_viewers: type: integer format: int64 description: The number of users who viewed products from videos. Returned only for offline data. video_views: type: integer format: int64 description: The number of video views. Returned only for offline data. GetShopVideoPerformanceOverviewResponseDataPerformanceIntervalShoppableVideoAttributedGmv: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). GetShopVideoProductPerformanceListResponse: 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/GetShopVideoProductPerformanceListResponseData" GetShopVideoProductPerformanceListResponseData: type: object properties: latest_available_date: type: string format: date description: Latest date in local timezone where data is ready (ISO 8601 format). next_page_token: type: string description: Page token for the next page request. If this value is nonempty, pass it as `page_token` in the next request and reuse the same `video_id`, `start_date_ge`, `end_date_lt`, `sort_field`, `sort_order`, `currency`, and `page_size` values. An empty value means that there are no more pages. products: type: array items: $ref: "#/components/schemas/GetShopVideoProductPerformanceListResponseDataProduct" description: List of product performance metrics. total_count: type: integer format: int64 description: Total number of products matching the request across all pages. GetShopVideoProductPerformanceListResponseDataProduct: type: object properties: ctr: type: string description: Ratio of product clicks to product impressions in raw decimal format. customers: type: integer format: int64 description: Number of customers who purchased the product. daily_avg_buyers: type: string description: Average number of buyers per day for the current product. gmv: $ref: "#/components/schemas/Gmv" description: Overall Gross Merchandise Value (GMV) for the product. gpm: $ref: "#/components/schemas/Gpm" description: Average GMV generated per 1,000 product impressions. id: type: string description: The ID of the product promoted in the video. name: type: string description: The name of the product promoted in the video. product_clicks: type: integer format: int64 description: Number of product clicks. product_impressions: type: integer format: int64 description: Number of product impressions. units_sold: type: integer format: int64 description: Number of units sold for the current product. GetShopVideosPerformanceDetailsResponse: 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/GetShopVideosPerformanceDetailsResponseData" GetShopVideosPerformanceDetailsResponseData: type: object properties: latest_available_date: type: string format: date description: Latest date in local timezone where data is ready (ISO 8601 format). videos: type: array items: $ref: "#/components/schemas/GetShopVideosPerformanceDetailsResponseDataVideo" description: Performance details for the requested videos. GetShopVideosPerformanceDetailsResponseDataVideo: type: object properties: error: $ref: "#/components/schemas/GetAvailableReviewDecisionsResponseDataError" description: Error information when performance details for this video could not be returned. performance: $ref: "#/components/schemas/GetShopVideosPerformanceDetailsResponseDataVideoPerformance" description: Performance details for this video. Returned when the video is processed successfully. video: $ref: "#/components/schemas/GetShopVideosPerformanceDetailsResponseDataVideoVideo" description: Basic information about the video. video_id: type: string description: The requested video ID. GetShopVideosPerformanceDetailsResponseDataVideoPerformance: type: object properties: intervals: type: array items: $ref: "#/components/schemas/GetShopVideosPerformanceDetailsResponseDataVideoPerformanceInterval" description: Interval data for the requested time range. viewer_profile: type: array items: $ref: "#/components/schemas/GetShopVideosPerformanceDetailsResponseDataVideoPerformanceViewerProfile" description: Viewer profile of the video. GetShopVideosPerformanceDetailsResponseDataVideoPerformanceInterval: type: object properties: end_date: type: string format: date description: End date of the interval, exclusive. sales: $ref: "#/components/schemas/GetShopVideosPerformanceDetailsResponseDataVideoPerformanceIntervalSale" description: Sales performance data. start_date: type: string format: date description: Start date of the interval, inclusive. traffic: $ref: "#/components/schemas/GetShopVideosPerformanceDetailsResponseDataVideoPerformanceIntervalTraffic" description: Traffic performance of the video. GetShopVideosPerformanceDetailsResponseDataVideoPerformanceIntervalSale: type: object properties: overall: $ref: "#/components/schemas/GetShopVideosPerformanceDetailsResponseDataVideoPerformanceIntervalSaleOverall" description: Overall sales performance data. GetShopVideosPerformanceDetailsResponseDataVideoPerformanceIntervalSaleOverall: type: object properties: ctr: type: string description: Product clicks from the video divided by impressions of all video products. customers: type: integer format: int64 description: The total number of customers who placed orders directly from the shoppable video. gmv: $ref: "#/components/schemas/Gmv" description: Gross merchandise value generated directly from the shoppable video. gpm: $ref: "#/components/schemas/Gpm" description: GMV generated per 1,000 video views. items_sold: type: integer format: int64 description: The total number of items sold directly from the shoppable video. product_clicks: type: integer format: int64 description: The number of product clicks from the video. product_impressions: type: integer format: int64 description: The number of impressions of all video products. GetShopVideosPerformanceDetailsResponseDataVideoPerformanceIntervalTraffic: type: object properties: comments: type: integer format: int64 description: The number of comments received by the video. likes: type: integer format: int64 description: The number of likes received by the video. new_followers: type: integer format: int64 description: The number of new followers attributed to the video. shares: type: integer format: int64 description: The number of times the video was shared. views: type: integer format: int64 description: The number of video views. GetShopVideosPerformanceDetailsResponseDataVideoPerformanceViewerProfile: type: object properties: age_distribution: type: array items: $ref: "#/components/schemas/AgeDistribution" description: Distribution of viewers by age range. country_distribution: type: array items: $ref: "#/components/schemas/CountryDistribution" description: Distribution of viewers by country or region. gender_distribution: type: array items: $ref: "#/components/schemas/GenderDistribution" description: Distribution of viewers by gender. type: type: string enum: - NEW_FOLLOWER - VIEWERS description: "Viewer profile type. Possible values: NEW_FOLLOWER, VIEWERS." GetShopVideosPerformanceDetailsResponseDataVideoVideo: type: object properties: duration: type: integer format: int64 description: The video duration. id: type: string description: The video ID. play_url: type: string description: The video playback URL. thumbnail_url: type: string description: The video thumbnail URL. title: type: string description: The video title. username: type: string description: The username of the video creator. video_post_time: type: string description: The time when the video was posted. GetShopWebhooksResponse: 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/GetShopWebhooksResponseData" GetShopWebhooksResponseData: type: object properties: webhooks: type: array items: $ref: "#/components/schemas/GetShopWebhooksResponseDataWebhook" description: The list of enabled webhooks configured for the shop. total_count: type: integer format: int64 description: The total number of webhooks returned. GetShopWebhooksResponseDataWebhook: type: object properties: event_type: type: string enum: - ORDER_STATUS_CHANGE - RECIPIENT_ADDRESS_UPDATE - PACKAGE_UPDATE - PRODUCT_STATUS_CHANGE - SELLER_DEAUTHORIZATION - UPCOMING_AUTHORIZATION_EXPIRATION - CANCELLATION_STATUS_CHANGE - RETURN_STATUS_CHANGE - NEW_CONVERSATION - NEW_MESSAGE - PRODUCT_INFORMATION_CHANGE - PRODUCT_CREATION - PRODUCT_CATEGORY_CHANGE - NEW_MESSAGE_LISTENER - INVOICE_STATUS_CHANGE - PRODUCT_AUDIT_STATUS_CHANGE - REVERSE_STATUS_UPDATE x-enum-descriptions: - Triggers on each order status update, from new order placement through all subsequent status changes. See [Order Status change](650300b8a57708028b430b4a). - Triggers when the recipient's address is updated. See [Receipient address update](650301af5a12ff0294ea3bf9). - Triggers when a package is updated (e.g., combined, split, or address changed). See [Package update](650955cabace3e02b73cc886). - Triggers when product audit results are updated. See [Product status change](650956aff1fd3102b90b6261). - Triggers when a seller is deauthorized to inform developers and avoid misunderstandings about platform authorization issues. See [Seller deauthorization](65095746defece02be4d749d). - Triggers 30 days before authorization expiration, with daily notifications at 0:00 until re-authorization is completed. See [Upcoming authorization expiration](6509579c0fcef602bf11312c). - Triggers when an order's cancellation status changes. See [Cancellation status change](65030150746462028285f657). - Triggers when an order's return status changes. See [Return status change](65030162bb2a4d028d50cc51). - Triggers when a customer service agent joins or leaves a conversation. See [New conversation](6614330bfe9fdc02e002abfd). - Triggers when a new message is sent in a customer service conversation. See [New Message](66143486ef8a1202dc323258). - Triggers when changes to a product's title, description, main images, or attributes go live. See [Product information change](65d6f41411a60f02dc1cf8bf). - Triggers when a new product is created. See [Product creation](663c98b566828e02e4515580). - Triggers when the category of a product is changed. See [Product category change](668764a371f16d02eef1f393). - Triggers when a creator sends a message to the seller. See [New message listener](6790b76eb59cf9030997b783). - Triggers when the status of an invoice upload changes after using the [POST Upload Invoice](67b542559a140004b343984f) endpoint. See [Invoice Status Change](67b68ca185619104a6772e5d). - Triggers when the product audit status changes. See [Product audit status change](67b5c6cba42623049abe5062). - Triggers when buyer raises cancellation, refund only, or return & refund requests that need the seller to accept or reject. See [Reverse Status Update](https://partner.tiktokshop.com/doc/page/63fd7459715d622a338c5437). description: |- The topic of the webhook event. Possible values: - `ORDER_STATUS_CHANGE`: Triggers on each order status update, from new order placement through all subsequent status changes. See [Order Status change](650300b8a57708028b430b4a). - `RECIPIENT_ADDRESS_UPDATE`: Triggers when the recipient's address is updated. See [Receipient address update](650301af5a12ff0294ea3bf9). - `PACKAGE_UPDATE`: Triggers when a package is updated (e.g., combined, split, or address changed). See [Package update](650955cabace3e02b73cc886). - `PRODUCT_STATUS_CHANGE`: Triggers when product audit results are updated. See [Product status change](650956aff1fd3102b90b6261). - `SELLER_DEAUTHORIZATION`: Triggers when a seller is deauthorized to inform developers and avoid misunderstandings about platform authorization issues. See [Seller deauthorization](65095746defece02be4d749d). - `UPCOMING_AUTHORIZATION_EXPIRATION`: Triggers 30 days before authorization expiration, with daily notifications at 0:00 until re-authorization is completed. See [Upcoming authorization expiration](6509579c0fcef602bf11312c). - `CANCELLATION_STATUS_CHANGE`: Triggers when an order's cancellation status changes. See [Cancellation status change](65030150746462028285f657). - `RETURN_STATUS_CHANGE`: Triggers when an order's return status changes. See [Return status change](65030162bb2a4d028d50cc51). - `NEW_CONVERSATION`: Triggers when a customer service agent joins or leaves a conversation. See [New conversation](6614330bfe9fdc02e002abfd). - `NEW_MESSAGE`: Triggers when a new message is sent in a customer service conversation. See [New Message](66143486ef8a1202dc323258). - `PRODUCT_INFORMATION_CHANGE`: Triggers when changes to a product's title, description, main images, or attributes go live. See [Product information change](65d6f41411a60f02dc1cf8bf). - `PRODUCT_CREATION`: Triggers when a new product is created. See [Product creation](663c98b566828e02e4515580). - `PRODUCT_CATEGORY_CHANGE`: Triggers when the category of a product is changed. See [Product category change](668764a371f16d02eef1f393). - `NEW_MESSAGE_LISTENER`: Triggers when a creator sends a message to the seller. See [New message listener](6790b76eb59cf9030997b783). - `INVOICE_STATUS_CHANGE`: Triggers when the status of an invoice upload changes after using the [POST Upload Invoice](67b542559a140004b343984f) endpoint. See [Invoice Status Change](67b68ca185619104a6772e5d). - `PRODUCT_AUDIT_STATUS_CHANGE`: Triggers when the product audit status changes. See [Product audit status change](67b5c6cba42623049abe5062). - `REVERSE_STATUS_UPDATE`: Triggers when buyer raises cancellation, refund only, or return & refund requests that need the seller to accept or reject. See [Reverse Status Update](https://partner.tiktokshop.com/doc/page/63fd7459715d622a338c5437). address: type: string description: The webhook URL used to receive the event data. create_time: type: integer format: int64 description: The time when the webhook was created, represented as a Unix timestamp in milliseconds. update_time: type: integer format: int64 description: The time when the webhook was last updated, represented as a Unix timestamp in milliseconds. GetShoppableVideoPrecheckResultResponse: 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/GetShoppableVideoPrecheckResultResponseData" GetShoppableVideoPrecheckResultResponseData: type: object properties: precheck_task: $ref: "#/components/schemas/GetShoppableVideoPrecheckResultResponseDataPrecheckTask" description: Video pre-check task GetShoppableVideoPrecheckResultResponseDataPrecheckTask: type: object properties: id: type: string description: The id of the video pre-check task. violation_check_result: $ref: "#/components/schemas/GetShoppableVideoPrecheckResultResponseDataPrecheckTaskViolationCheckResult" description: violation check details good_quality_check_result: $ref: "#/components/schemas/GetShoppableVideoPrecheckResultResponseDataPrecheckTaskGoodQualityCheckResult" description: Good-quality check details. This field is omitted when the good-quality check is disabled. GetShoppableVideoPrecheckResultResponseDataPrecheckTaskGoodQualityCheckResult: type: object properties: status: type: string description: |- SUCCESS: The precheck task passed all good quality checks FAIL: The precheck task failed good quality checks. Check the 'issues' field for details. PROCESSING: The good qualtify check is still in progress issues: type: array items: $ref: "#/components/schemas/GetShoppableVideoPrecheckResultResponseDataPrecheckTaskGoodQualityCheckResultIssue" description: A list of quality issues and improvement suggestions when the good quality check fails. GetShoppableVideoPrecheckResultResponseDataPrecheckTaskGoodQualityCheckResultIssue: type: object properties: code: type: string description: Quality finding suggestions: type: string description: Recommended improvements based on the quality finding. GetShoppableVideoPrecheckResultResponseDataPrecheckTaskViolationCheckResult: type: object properties: status: type: string description: |- SUCCESS: The precheck task passed violation checks FAIL: The precheck task has failed due to violations. Check the 'issues' field for details. PROCESSING: The precheck violation task is still in progress issues: type: array items: $ref: "#/components/schemas/GetShoppableVideoPrecheckResultResponseDataPrecheckTaskViolationCheckResultIssue" description: A list of policy violation details returned when violation check fails GetShoppableVideoPrecheckResultResponseDataPrecheckTaskViolationCheckResultIssue: type: object properties: risk: type: string description: Policy violation suggestions: type: string description: Detailed guidance to resolve the detected violation. GetShoppableVideoStatusResponse: 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/GetShoppableVideoStatusResponseData" GetShoppableVideoStatusResponseData: type: object properties: video: $ref: "#/components/schemas/GetShoppableVideoStatusResponseDataVideo" description: returned video info GetShoppableVideoStatusResponseDataVideo: type: object properties: id: type: string description: Video id post_status: type: string enum: - SUCCESS - FAIL - PROCESSING x-enum-descriptions: - The video was posted successfully. - The video failed to post. - The video is still being processed. Call this API again later to get the latest status. description: |- Video posting status. Possible values: - SUCCESS: The video was posted successfully. - FAIL: The video failed to post. - PROCESSING: The video is still being processed. Call this API again later to get the latest status. post_time: type: integer format: int64 description: |- Returned if the video has been successfully posted, i.e. `posting_status = SUCCESS`. Represented in seconds. GetShowcaseProductsResponse: 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/GetShowcaseProductsResponseData" GetShowcaseProductsResponseData: type: object properties: products: type: array items: $ref: "#/components/schemas/GetShowcaseProductsResponseDataProduct" description: A list of products. next_page_token: type: string description: An opaque token used to retrieve the next page of a paginated result set. total_count: type: integer format: int64 description: Total count of products in the response. GetShowcaseProductsResponseDataProduct: type: object properties: id: type: string description: The product's product ID shop: $ref: "#/components/schemas/Shop" description: Data and metadata associated with the Seller's TikTok Shop. addition: $ref: "#/components/schemas/GetShowcaseProductsResponseDataProductAddition" description: An object including data about product images. price: $ref: "#/components/schemas/GetShowcaseProductsResponseDataProductPrice" description: An object including data about the product price. title: type: string description: The product's display title. main_images: type: array items: $ref: "#/components/schemas/GetShowcaseProductsResponseDataProductMainImage" description: A list of product images. status: $ref: "#/components/schemas/GetShowcaseProductsResponseDataProductStatus" description: An object including product status information. source: type: string description: |- The product source. This is an enumerated type with values: - THIRD_PARTY - AFFILIATE - TIKTOK_STORE detail_link: type: string description: The product detail page URL. third_party_link: type: string description: The off-TikTok Shop product detail page URL. sale_regions: type: array items: type: string description: A list of regions in which the product is offered for sale. commission: $ref: "#/components/schemas/GetShowcaseProductsResponseDataProductCommission" description: An object including data about commissions associated with the product. collaboration: $ref: "#/components/schemas/GetShowcaseProductsResponseDataProductCollaboration" description: An object containing collaboration data for the product. GetShowcaseProductsResponseDataProductAddition: type: object properties: customized_main_images: type: array items: $ref: "#/components/schemas/GetShowcaseProductsResponseDataProductAdditionCustomizedMainImage" description: A list of product images. GetShowcaseProductsResponseDataProductAdditionCustomizedMainImage: type: object properties: width: type: integer format: int64 description: The image width in pixels. heigth: type: integer format: int64 description: The image height in pixels. url: type: string description: The product's TikTok Shop image URL. GetShowcaseProductsResponseDataProductCollaboration: type: object properties: id: type: string description: The collaboration identifier. type: type: string description: |- The collaboration type. This an enumerated type with values: 1 - Open Collaboration 2 - Target Collaboration 5 - Partner Campaign 11 - Flat Fee 12 - Collaboration Plus 13 - Affiliate Promotion partner: $ref: "#/components/schemas/GetShowcaseProductsResponseDataProductCollaborationPartner" description: The partner information. GetShowcaseProductsResponseDataProductCollaborationPartner: type: object properties: id: type: string description: The partner identifier. name: type: string description: The partner name. GetShowcaseProductsResponseDataProductCommission: type: object properties: rate: type: integer format: int64 description: The commission rate in hundredths of a percent. For example, `3587` is a commission rate of `35.87%`. The range of this value is [100, 8000]. reward_rate: type: integer format: int64 description: The reward commission rate in hundredths of a percent. For example, `3587` is a commission rate of `35.87%`. GetShowcaseProductsResponseDataProductMainImage: type: object properties: width: type: integer format: int64 description: The image width in pixels. heigth: type: integer format: int64 description: The image height in pixels. url: type: string description: The product's TikTok Shop image URL. GetShowcaseProductsResponseDataProductPrice: type: object properties: original_price: $ref: "#/components/schemas/GetShowcaseProductsResponseDataProductPriceOriginalPrice" description: The original price of the product. seller_discount_price: $ref: "#/components/schemas/GetShowcaseProductsResponseDataProductPriceSellerDiscountPrice" description: An object including data about the product discount price. platform_discount_price: $ref: "#/components/schemas/GetShowcaseProductsResponseDataProductPricePlatformDiscountPrice" description: An object including data about the product platform discount price. GetShowcaseProductsResponseDataProductPriceOriginalPrice: type: object properties: minimum_amount: type: string description: The lowest original price for the product. maximum_amount: type: string description: The highest original price for the product. currency: type: string description: The ISO 4217 currency code. GetShowcaseProductsResponseDataProductPricePlatformDiscountPrice: type: object properties: minimum_amount: type: string description: The lowest product platform discount price. maximum_amount: type: string description: The highest product platform discount price. currency: type: string description: The ISO 4217 currency code. GetShowcaseProductsResponseDataProductPriceSellerDiscountPrice: type: object properties: minimum_amount: type: string description: The lowest discount price. maximum_amount: type: string description: The highest discount price. currency: type: string description: The ISO 4217 currency code. GetShowcaseProductsResponseDataProductStatus: type: object properties: inventory_status: type: string description: |- The product inventory status. This an enumerated type with values: - IN_STOCK - SOLD_OUT review_status: type: string description: |- The product review status. This is an enumerated type with values: - APPROVED - UNDER_REVIEW - CHANGES_UNDER_REVIEW - UNAVAILABLE - REJECTED - ZERO_COMMISSION is_hidden: type: boolean description: Set to `false` if the product is visible in the showcase. Set to `true` if the product is hidden from the showcase. added_status: type: string description: The product's add status for the request origin. For `SHOWCASE`, `ADDED` indicates that the product is in the showcase, while `REJECTED` indicates that the product is rejected for use in the current context. For `LIVE`, `ADDED` means the product is already in the Live room's product list (live bag), `NOT_ADDED` means the product can be added, and `REJECTED` means the product cannot be added. GetStatementsResponse: 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/GetStatementsResponseData" GetStatementsResponseData: type: object properties: next_page_token: type: string description: An opaque token used to retrieve the next page of a paginated result set. If this value is non-empty, provide it in the `page_token` parameter of the next request. An empty `next_page_token` means there are no more results. statements: type: array items: $ref: "#/components/schemas/GetStatementsResponseDataStatement" description: The list of statements that meet the query conditions. GetStatementsResponseDataStatement: type: object properties: id: type: string description: The statement ID. statement_time: type: integer format: int64 description: |- The time when the statement was generated, expressed as a Unix timestamp in seconds. Statements are generated daily at 00:00 UTC and include all transactions from the previous day. settlement_amount: type: string description: The settlement amount. currency: type: string description: The currency code in ISO 4217 format. revenue_amount: type: string description: |- The final revenue amount at the time of order settlement. Applicable for all regions except UK and US. fee_amount: type: string description: |- The fees charged by TikTok Shop at the time of order settlement. An order is deemed settled a certain number of days after delivery (varies by region) if no returns or refunds are pending. **Note**: Shipping-related costs are excluded, except for local sellers in the SEA region, where they are included. adjustment_amount: type: string description: |- The adjustment amount. For more details about the reason for adjustment, refer to the [Get Statement Transactions API](https://partner.tiktokshop.com/docv2/page/650a6749defece02be67da87). payment_status: type: string enum: - PAID - FAILED - PROCESSING - SETTLED x-enum-descriptions: - Payment has been transferred to the seller. - Payment transfer failed. - Payment is currently being processed. - Funds have been settled to the seller's account. description: |- The payment status, indicating whether payment has been transferred to the seller's bank account or settled to the seller's account. Possible values: - PAID: Payment has been transferred to the seller. - FAILED: Payment transfer failed. - PROCESSING: Payment is currently being processed. - SETTLED: Funds have been settled to the seller's account. payment_id: type: string description: The payment ID. net_sales_amount: type: string description: |- The final revenue amount after seller discounts are deducted. Applicable only for local sellers outside the SEA region. shipping_cost_amount: type: string description: |- The shipping fees. Applicable only for local sellers outside the SEA region. payment_time: type: integer format: int64 description: The Unix payment timestamp GetSubmissionRecordsResponse: 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/GetSubmissionRecordsResponseData" GetSubmissionRecordsResponseData: type: object properties: data: $ref: "#/components/schemas/GetSubmissionRecordsResponseDataData" description: The submission records and pagination information returned for this request. GetSubmissionRecordsResponseDataData: type: object properties: submissions: type: array items: $ref: "#/components/schemas/GetSubmissionRecordsResponseDataDataSubmission" description: List of submission records. next_page_token: type: string description: Token for fetching next page. Empty if no more pages. total_count: type: integer format: int64 description: Total number of matching submissions (approximate). GetSubmissionRecordsResponseDataDataSubmission: type: object properties: id: type: string description: Unique ID of this submission. opportunity_id: type: string description: The opportunity ID this submission is linked to. opportunity_title: type: string description: Opportunity title for reference. status: type: string description: "Current status: PENDING_REVIEW / APPROVED / REJECTED" product_id: type: string description: The submitted product ID. product_name: type: string description: Product name for reference. submit_time: type: integer format: int64 description: The time when the product was submitted, expressed as a Unix timestamp in seconds. review_time: type: integer format: int64 description: Review completion timestamp rejection_reason: type: - string - "null" description: Rejection reason if status is REJECTED. Null otherwise. product_orders: type: integer format: int64 description: The total number of units sold for the product in the last 30 days. product_pv: type: integer format: int64 description: The product page view count for the last 30 days. GetTokopediaAndTikTokShopProductIDMappingsRequest: type: object properties: toko_pids: type: array items: type: integer format: int64 description: List of Tokopedia product IDs to map to TikTok Shop product IDs. GetTokopediaAndTikTokShopProductIDMappingsResponse: 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/GetTokopediaAndTikTokShopProductIDMappingsResponseData" GetTokopediaAndTikTokShopProductIDMappingsResponseData: type: object properties: error: $ref: "#/components/schemas/GetTokopediaAndTikTokShopProductIDMappingsResponseDataError" description: error information product: type: array items: $ref: "#/components/schemas/Product" description: list of product data GetTokopediaAndTikTokShopProductIDMappingsResponseDataError: type: object properties: code: type: integer format: int64 description: The code identifying the product ID mapping error. message: type: string description: error detail information GetTradeInAccountTransactionsResponse: 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/GetTradeInAccountTransactionsResponseData" GetTradeInAccountTransactionsResponseData: type: object properties: flows: type: array items: $ref: "#/components/schemas/GetTradeInAccountTransactionsResponseDataFlow" description: The TradeIn account transactions that match the query conditions. An empty array is returned when no transaction matches. has_more: type: boolean description: Whether more account transactions are available. next_page_token: type: string description: An opaque token used to retrieve the next page. The value is empty when no more account transactions are available. total_count: type: integer format: int64 description: The total number of account transactions that match the query conditions. GetTradeInAccountTransactionsResponseDataFlow: type: object properties: amount: $ref: "#/components/schemas/GetTradeInAccountTransactionsResponseDataFlowAmount" description: The transaction amount and currency. Use direction to determine whether the transaction is a credit or debit. create_time: type: string format: date-time description: The time when the account transaction was created, in RFC 3339 format. direction: type: string description: |- The direction of the account transaction. - IN: Funds credited to the supplier's account. - OUT: Funds debited from the supplier's account. origin_transaction_id: type: string description: The original account transaction ID associated with a reversed transaction. This field is returned only for a REVERSE transaction when available. reference_id: type: string description: The TradeIn business order ID associated with the account transaction. transaction_id: type: string description: The unique ID of the account transaction. type: type: string description: |- The TradeIn business transaction type. - RECHARGE: Funds credited through a recharge. - WITHDRAW: Funds debited through a payout. - REVERSE: Funds returned after a payout reversal. GetTradeInAccountTransactionsResponseDataFlowAmount: type: object properties: amount: type: string description: The transaction amount represented as a decimal string. currency: type: string description: The currency code in ISO 4217 format. GetTradeInSupplierAccountBalanceResponse: 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/GetTradeInSupplierAccountBalanceResponseData" GetTradeInSupplierAccountBalanceResponseData: type: object properties: available_balance: $ref: "#/components/schemas/GetTradeInSupplierAccountBalanceResponseDataAvailableBalance" description: The available balance of the supplier's TradeIn account. GetTradeInSupplierAccountBalanceResponseDataAvailableBalance: type: object properties: amount: type: string description: The available balance amount represented as a decimal string. currency: type: string description: The currency code in ISO 4217 format. GetTransactionsByOrderResponse: 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/GetTransactionsByOrderResponseData" GetTransactionsByOrderResponseData: type: object properties: order_id: type: string description: The order ID in TikTok Shop. order_create_time: type: integer format: int64 description: The creation time of the order, as a Unix timestamp in seconds. currency: type: string description: The three-letter currency code in ISO 4217 format. revenue_amount: type: string description: The revenue amount for the order at the time of order settlement. This is equivalent to the net sales amount. fee_and_tax_amount: type: string description: The fees and taxes charged by the platform for the order at the time of order settlement. Shipping-related costs are excluded. shipping_cost_amount: type: string description: The shipping costs for the order at the time of order settlement. settlement_amount: type: string description: |- The settlement amount for the order. Formula: revenue_amount - shipping_cost_amount - fee_tax_amount sku_transactions: type: array items: $ref: "#/components/schemas/GetTransactionsByOrderResponseDataSkuTransaction" description: The list of SKU transaction records for the order. total_count: type: integer format: int64 description: The number of transaction records GetTransactionsByOrderResponseDataSkuTransaction: type: object properties: sku_id: type: string description: The SKU ID in TikTok Shop. sku_name: type: string description: The SKU name. statement_id: type: string description: The statement ID. product_name: type: string description: The product title. quantity: type: string description: The SKU quantity included in the order settlement. settlement_amount: type: string description: The settlement amount for the SKU. revenue_amount: type: string description: The revenue amount at the time of order settlement. This is equivalent to the sum of all amounts in `revenue_breakdown`. revenue_breakdown: $ref: "#/components/schemas/RevenueBreakdown" description: An object containing the amounts that directly contribute to `revenue_amount`. shipping_cost_amount: type: string description: The shipping costs at the time of order settlement. This is equivalent to the sum of all contributory amounts in `shipping_cost_breakdown`. shipping_cost_breakdown: $ref: "#/components/schemas/GetTransactionsByOrderResponseDataSkuTransactionShippingCostBreakdown" description: An object containing the amounts that directly contribute to `shipping_cost_amount`. fee_tax_amount: type: string description: The total fees and taxes charged by TikTok Shop at the time of order settlement. Shipping-related costs are excluded. This is equivalent to the sum of all contributory amounts in `fee_tax_breakdown`. fee_tax_breakdown: $ref: "#/components/schemas/GetTransactionsByOrderResponseDataSkuTransactionFeeTaxBreakdown" description: An object containing the fee and tax amounts that directly contribute to `fee_tax_amount`. GetTransactionsByOrderResponseDataSkuTransactionFeeTaxBreakdown: type: object properties: fee: $ref: "#/components/schemas/GetTransactionsByOrderResponseDataSkuTransactionFeeTaxBreakdownFee" description: An object containing the fee amounts that contribute to `fee_tax_amount`. tax: $ref: "#/components/schemas/GetTransactionsByOrderResponseDataSkuTransactionFeeTaxBreakdownTax" description: An object containing the tax amounts that contribute to `fee_tax_amount`. GetTransactionsByOrderResponseDataSkuTransactionFeeTaxBreakdownFee: type: object properties: platform_commission_amount: type: string description: The commission amount charged by TikTok Shop. referral_fee_amount: type: string description: |- The referral fee charged for processing successful orders. Applicable only for the US. refund_administration_fee_amount: type: string description: The 20% refund administration fee deducted from the total refunded referral fee amount. transaction_fee_amount: type: string description: The transaction fee charged for processing successful orders. credit_card_handling_fee_amount: type: string description: The handling fee charged when the buyer pays with a credit card. affiliate_commission_amount: type: string description: The commission amount charged to the seller for payment to the creator. affiliate_commission_amount_before_pit: type: string description: |- The affiliate ads commission paid to a creator before any personal income tax withholding. Applicable only for SEA markets. affiliate_partner_commission_amount: type: string description: The commission amount for purchases through affiliate partner links. affiliate_ads_commission_amount: type: string description: The commission for eligible orders from ads. sfp_service_fee_amount: type: string description: The service fee charged for participation in the [Seller Free Shipping Programme]. live_specials_fee_amount: type: string description: The service fee charged for participation in the [LIVE Specials Programme]. bonus_cashback_service_fee_amount: type: string description: The service fee charged for participation in the bonus cashback program. mall_service_fee_amount: type: string description: The service fee charged for using TikTok Shop Mall. voucher_xtra_service_fee_amount: type: string description: The service fee charged for participation in the Voucher Xtra program. flash_sales_service_fee_amount: type: string description: The service fee charged for participation in flash sales. cofunded_promotion_service_fee_amount: type: string description: The service fee charged for co-funded promotions. pre_order_service_fee_amount: type: string description: The service fee charged when seller joins Pre-order program. tsp_commission_amount: type: string description: The commission amount charged by TikTok Shop Partners (TSP). dt_handling_fee_amount: type: string description: The handling fee charged for orders that are fulfilled by Dilayani Tokopedia. epr_pob_service_fee_amount: type: string description: The eco-contributions TikTok Shop pays on your behalf to the qualified producer responsibility organization (PRO). fee_per_item_sold_amount: type: string description: |- The fee charged to sellers by the platform for each item sold. Applicable only for the Brazil market. seller_paylater_handling_fee_amount: type: string description: The handling fee charged to the seller for participation in the PayLater program. cofunded_creator_bonus_amount: type: string description: The portion of the creator bonus that you co-fund as part of the commission boost campaign. dynamic_commission_amount: type: string description: |- The dynamic commission fee is the amount that the platform charges to all sellers for every successfully delivered order. Applicable only for Indonesia. external_affiliate_marketing_fee_amount: type: string description: The service fee for participating in the External Affiliate Marketing Solution Program, as stated during registration. vn_fix_infrastructure_fee: type: string description: Infrastructure fees are a fixed service fee that TikTok Shop charges for providing, maintaining, and developing infrastructure for delivery services. It applies to delivered orders on the main order level. affiliate_commission_deposit: type: string description: The amount reserved for creator commissions after an order is paid. Applies only to commissions tied to order volume and is based on the highest earning rate. affiliate_commission_release: type: string description: The commission deposit refunded to you after order settlement. Applies only to commissions tied to order volume. tap_shop_ads_commission: type: string description: The advertising commission cost a merchant pays to TikTok Shop Affiliate Partner (TAP). shipping_fee_guarantee_service_fee: type: string description: A flat service fee charged for each order under the Shipping Fee Guarantee Program installation_service_fee: type: string description: The fee TikTok Shop charges you for using platform installation service campaign_resource_fee: type: string description: Amount of campaign resource fee from program seller joining in platform_special_service_fee_amount: type: string description: The portion of the Distance Shipping Fee paid by the customer that exceeds the logistics service provider's charge, retained by TikTok Shop to support a secure fulfillment experience smart_promotion_fee_amount: type: string description: This fee includes funds from TikTok Shop to help provide promotions to customers gmv_max_ad_fee_amount: type: string description: A percentage deducted from your net sales per order for GMV Max (net sales performance goal) advertising. platform_semi_managed_commission_fee: type: string description: Calculated as a percentage of (original price − seller discount + customer-paid shipping fee). platform_semi_managed_commission_fee_tax: type: string description: This amount is collected on behalf of the government. campaign_period_fee_cfp_amount: type: string description: Fee charged during Co-funded Promotion campaigns. campaign_period_fee_sp_amount: type: string description: Fee charged during Smart Promotion campaigns. campaign_period_fee_sp_tax_amount: type: string description: Sales tax applied to the campaign period fee under Smart Promotion. campaign_period_fee_cfp_tax_amount: type: string description: Sales tax applied to the campaign period fee under Co-funded Promotion. seller_growth_fee_amount: type: string description: A fee charged on each successful order to provide Bonus Cashback and other growth benefits. category_led_campaign_fee_amount: type: string description: Fee charged for participating in the Category-led campaign. category_led_campaign_fee_tax_amount: type: string description: Sales tax charged for the fee. brand_amplification_program_commission: type: string description: Commission fee charged for participating in the Brand Amplification Program. brand_amplification_program_fee_tax: type: string description: Sales tax charged for the fee. brand_campaign_fee: type: string description: Fee charged for participating in the Brand campaign. brand_campaign_fee_tax: type: string description: Sales tax charged for the fee. failed_delivery_shipping_fee: type: string description: Shipping fee for order that failed to be delivered to the customer. In some cases, the fee may be shared between seller and platform. buyer_fault_return_shipping_fee: type: string description: Shipping fee for buyer-fault returns. In some cases, the fee may be shared between seller and platform. insurance_fee: type: string description: Premium charged per order for insurance coverage gmv_max_coupon_fee: type: string description: The cost of GMV Max coupons. cps_shop_ads_commission_tax_amount: type: string description: Sales tax applied to GMV Max ad fee shipping_insurance_fee_tax_amount: type: string description: The tax amount charged on the shipping insurance fee. new_customer_growth_package_fee: type: string description: Fee for using the New Customer Growth Package to offer discounts that attract new customers to your shop. target_product_gmv_growth_package_fee: type: string description: Fee for using the Product GMV Growth Package to offer discounts on selected products and increase their sales. store_gmv_growth_package_fee: type: string description: Fee for using the Shop GMV Growth Package to offer store-wide discounts and grow your overall sales. auto_post_shoppable_video_commission_fee: type: string description: The commission fee charged to the seller for orders attributed to the AI-generated, auto-post shoppable videos. seller_funded_user_spoint_service_fee: type: string description: Service fee charged for seller-funded user S-Points issued to shoppers. Calculated based on the order's actual payment amount and refunded if the order is later returned. GetTransactionsByOrderResponseDataSkuTransactionFeeTaxBreakdownTax: type: object properties: vat_amount: type: string description: |- The VAT paid by the platform on the seller's behalf. Applicable only for cross-border shop orders. import_vat_amount: type: string description: |- The import VAT, a tax paid on goods bought in one country and imported into another. Applicable only for cross-border shop orders. In Japan, it refers to the Japan Consumption Tax (JCT). customs_duty_amount: type: string description: |- The customs duties, a type of tax on cross-border goods collected by governments. Applicable only for cross-border shop orders. customs_clearance_amount: type: string description: |- The fees charged by logistic suppliers for customs clearance services. Applicable only for cross-border shop orders. sst_amount: type: string description: The sales and service tax (SST) collected and remitted to the tax authority by the platform for low-value goods imported into Malaysia, effective January 1, 2024. gst_amount: type: string description: The goods and services tax (GST) collected and remitted to the tax authority by the platform for low-value goods imported into Singapore, effective January 1, 2023. iva_amount: type: string description: The Mexican VAT that TikTok Shop is required to withhold on your taxable products and remit to the tax authority. isr_amount: type: string description: The Mexican federal income tax that TikTok Shop is required to withhold. anti_dumping_duty_amount: type: string description: The anti-dumping duties collected by governments for import goods. local_vat_amount: type: string description: The VAT paid by the platform on the seller's behalf. Applicable only for local shop orders. pit_amount: type: string description: The personal income tax (PIT) paid by the platform on the seller's behalf. sales_tax_referral_fee_amount: type: string description: Some U.S. states consider referral fees taxable. To comply with state tax laws, TikTok Inc. collects and remits applicable sales tax when a taxable fee is charged. smart_promotion_fee_tax_amount: type: string description: Sales tax for the Smart Promotion fee cedular_tax: type: string description: The Mexican Guanajuato cedular tax new_customer_growth_package_fee_tax: type: string description: The sales tax applied to the New Customer Growth Package fee. store_gmv_growth_package_fee_sales_tax: type: string description: The sales tax applied to the Shop GMV Growth Package fee. target_product_gmv_growth_package_tax: type: string description: The sales tax applied to the Product GMV Growth Package fee. auto_post_shoppable_video_sales_tax: type: string description: The sales tax applied to the auto-post shoppable video commission fee. article_22_income_tax_withheld: type: string description: Article 22 Income Tax withheld by the platform under PMK 37/2025 GetTransactionsByOrderResponseDataSkuTransactionShippingCostBreakdown: type: object properties: actual_shipping_fee_amount: type: string description: The actual shipping fee calculated based on the weight/dimensions measured by the carrier. For details, check `shipping_cost_breakdown.supplementary_component`. international_leg_logistics_amount: type: string description: The delivery fee charged to the seller for the international leg of a cross-border shipment shipping_fee_discount_amount: type: string description: The shipping fee subsidies and incentives provided by the platform. This includes all subsidies regardless of fulfillment channels or policies. For details, check `shipping_cost_breakdown.supplementary_component`. customer_paid_shipping_fee_amount: type: string description: The actual shipping fee borne by the customer, calculated based on the product weight uploaded by the seller. Negative numbers refer to the refunded amount of customer-paid shipping fees return_shipping_fee_amount: type: string description: The shipping fee paid by the seller for the delivery of returns. replacement_shipping_fee_amount: type: string description: |- The shipping fee paid by the seller for the delivery of goods replacement. Applicable only for Indonesia. exchange_shipping_fee_amount: type: string description: |- The shipping fee paid by the seller for the delivery of goods exchange. Applicable only for Indonesia. signature_confirmation_fee_amount: type: string description: The fee incurred for packages requiring signature confirmation services shipping_insurance_fee_amount: type: string description: The shipping insurance fee incurred by the seller for purchasing additional TikTok shipping insurance services. fbt_fulfillment_fee_reimbursement_amount: type: string description: |- A reimbursement from TikTok Shop for Fulfilled by TikTok (FBT) orders that don't qualify for free shipping. Applicable only for the US. return_shipping_label_fee_amount: type: string description: The fee borne by the customer to cover the cost of return labels. This fee is collected on the seller's behalf and settled according to the agreed payment terms. seller_self_shipping_service_fee_amount: type: string description: A service fee charged for orders shipped through your own logistics provider. Applies to packages that don't meet the exemption criteria. return_shipping_fee_paid_buyer_amount: type: string description: Reimbursement for the shipping fees paid by customers to return packages failed_delivery_subsidy_amount: type: string description: For shipping fee from failed deliveries, you pay up to a standard rate, and TikTok Shop covers the remaining amount. fbt_free_shipping_fee_amount: type: string description: This is the fee that you cover when offering customers free shipping through FBT. free_return_subsidy_amount: type: string description: Reimbursement for the platform-funded portion of return shipping fees, as part of the free returns offered to customers. distant_shipping_fee_amount: type: string description: The distance fee for shipping paid by the customer. With your current settings for Horizon+ Program, this fee is included in product price for orders with shipping out of Java island. shipping_app_service_fee_amount: type: string description: Shipping App Service Fee for using shipping fee to generate shipping labels logistics_service_fee: type: string description: A fee charged to sellers throughout the order lifecycle for logistics-related services, including processing, coordination, handling of delivery-related matters, and basic shipping incentives. It is an amount per order, which is based on the parcel's weight tier and shipping route. It allows the platform to continuously enhance a high-quality, sustainable logistics network that serves both sellers and customers better over the long term, amidst changing global conditions. fbt_overall_merchant_subsidy: type: string description: Subsidy applied to your orders and offered to all FBT (Fulfilled by TikTok) merchants for the statement period. The amount is calculated based on your qualifying FBT order volume during this period. fbt_key_merchant_subsidy: type: string description: Subsidy applied to your orders based on eligibility for the key merchant program. The amount is calculated based on your qualifying FBT (Fulfilled by TikTok) order volume during the statement period. tiktok_shop_shipping_incentive_amount: type: string description: The shipping fee incentive provided by TikTok Shop. supplementary_component: $ref: "#/components/schemas/GetTransactionsByOrderResponseDataSkuTransactionShippingCostBreakdownSupplementaryComponent" description: Supplementary costs for your reference. These amounts do not directly contribute to `shipping_cost_amount`. hazmat_noncompliance_fee: type: string description: Fee charged when a parcel containing hazardous materials is shipped without the required declaration or compliant packaging, as assessed by the carrier. Charged when the parcel is delivered. hazmat_handling_fee: type: string description: Fee charged for the additional handling required to ship a parcel containing hazardous materials. Charged when the parcel is delivered. non_standard_weight_fee: type: string description: Fee charged when a parcel exceeds the standard weight range. The rate is set by TikTok Shop and charged when the parcel is delivered. non_standard_dimension_fee: type: string description: Fee charged when a parcel exceeds the standard size range. The rate is set by TikTok Shop and charged when the parcel is delivered. GetTransactionsByOrderResponseDataSkuTransactionShippingCostBreakdownSupplementaryComponent: type: object properties: fbt_fulfillment_fee_reimbursement_amount: type: string description: "(**Deprecated**: This field is deprecated and will return an empty string. Please refer to `shipping_cost_breakdown.fbt_fulfillment_fee_reimbursement_amount` instead for the relevant details.)" deprecated: true platform_shipping_fee_discount_amount: type: string description: The shipping fee discount provided in accordance with a campaign policy. This is part of `shipping_fee_discount_amount`. promo_shipping_incentive_amount: type: string description: The additional shipping incentive that the seller will receive if the seller signed up for the Co-Funded Free Shipping Program. A negative amount indicates a reversal of incentives due to order refunds attributed to the seller's responsibility. This is part of `shipping_fee_discount_amount`. shipping_fee_subsidy_amount: type: string description: |- The shipping fee subsidy funded by the platform for seller shipping. This is part of `shipping_fee_discount_amount`. - Positive amount represents a subsidy received by the seller. - Negative amount represents a subsidy that the seller must return to TikTok Shop. seller_shipping_fee_discount_amount: type: string description: The shipping fee discount provided by sellers. fbt_shipping_cost_amount: type: string description: |- The shipping fee incurred by the seller for orders fulfilled by TikTok (FBT). This is part of `actual_shipping_fee_amount`. Applicable only for EU and UK. customer_shipping_fee_offset_amount: type: string description: |- The fee to offset TikTok Shop Shipping Incentive or customer-paid shipping fee, resulting in a net charge of $0 to the seller. Applicable only for the US. fbm_shipping_cost_amount: type: string description: The shipping fee incurred by the seller for using TikTok Shipping. This is part of `actual_shipping_fee_amount`. fbt_fulfillment_fee_amount: type: string description: |- The shipping and warehouse fulfillment fee incurred by the seller for orders fulfilled by TikTok (FBT). This is part of `actual_shipping_fee_amount`. Applicable only for the US. return_refund_subsidy_amount: type: string description: For shipping fee from returns and refunds, you pay up to a standard rate, and TikTok Shop covers the remaining amount.This is part of `customer_paid_shipping_fee_amount`. refunded_customer_shipping_fee_amount: type: string description: Shipping fee returned to customers due returns and refunds.Does not include subsidies.This is part of `customer_paid_shipping_fee_amount`. shipping_fee_guarantee_reimbursement: type: string description: Reimbursement from the Shipping Fee Guarantee Program for failed deliveries or returns GetTransactionsByStatementResponse: 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/GetTransactionsByStatementResponseData" GetTransactionsByStatementResponseData: type: object properties: next_page_token: type: string description: An opaque token used to retrieve the next page of a paginated result set. If this value is present and non-empty, provide it in the `page_token` parameter of your next request. If this value is absent or empty, there are no more results to retrieve. id: type: string description: The statement ID. create_time: type: integer format: int64 description: |- The time when the statement was generated, as a Unix timestamp in seconds. Statements are generated daily at 00:00 UTC. status: type: string description: The statement status. Only supports `SETTLED`. currency: type: string description: The three-letter currency code in ISO 4217 format. payable_amount: type: string description: |- The final amount paid out after accounting for reserve funds. Formula: total_settlement_amount + total_reserve_amount total_reserve_amount: type: string description: |- The total amount withheld from settlement based on TikTok Shop Reserve Policy. Refer to TikTok Shop Academy for more information. - A positive amount indicates the funds that have been released. - A negative amount indicates the funds being withheld from the settlement. Applicable only for UK and US local sellers. total_settlement_amount: type: string description: |- The total settlement amount. Formula: total_revenue_amount - total_shipping_cost_amount - total_fee_tax_amount - total_adjustment_amount total_settlement_breakdown: $ref: "#/components/schemas/GetTransactionsByStatementResponseDataTotalSettlementBreakdown" description: An object containing the amounts that directly contribute to `total_settlement_amount`. total_count: type: integer format: int64 description: The number of transaction records in the statement. transactions: type: array items: $ref: "#/components/schemas/GetTransactionsByStatementResponseDataTransaction" description: The list of transaction records in the statement. Each transaction corresponds to an order, an adjustment, or a reserve-related transaction. GetTransactionsByStatementResponseDataTotalSettlementBreakdown: type: object properties: total_revenue_amount: type: string description: The total revenue amount at the time of order settlement. This is equivalent to the net sales amount. total_shipping_cost_amount: type: string description: The total shipping costs at the time of order settlement. total_fee_tax_amount: type: string description: The total fees and taxes charged by the platform at the time of order settlement. Shipping-related costs are excluded. total_adjustment_amount: type: string description: |- The total adjustment amount based on TikTok Shop policy. Refer to `transactions.type` for the list of adjustment-related policies. GetTransactionsByStatementResponseDataTransaction: type: object properties: id: type: string description: The transaction ID. type: type: string description: |- The transaction type. **Standard transactions** - `ORDER`: A transaction related to an order settlement. - `RESERVE`: A transaction involving collection or release of reserve funds. - If the transaction is an adjustment, it returns one of the following values: **Platform-related adjustments** - `CHARGE_BACK`: Charges returned to a payment card after a customer has successfully disputed an item on their account statement or transactions report. - `CUSTOMER_SERVICE_COMPENSATION`: Extra compensation or compensation paid to a customer after the after-sales period by customer service. - `DEDUCTIONS_INCURRED_BY_SELLER`: Deduction arising from customer dissatisfaction as a result of the seller's responsibility. This includes issues such as fraud, empty packages, items that do not match the product display page, or items of lower value than advertised. - `GMV_PAYMENT_FOR_ADS`: Amount used to pay for your advertisement if you are enabled "auto pay ads with shop GMV", or to pay for Tiktok Promote ads orders. - `PLATFORM_COMMISSION_ADJUSTMENT`: Adjustment when there are differences in the platform commission paid by the seller. - `PLATFORM_COMMISSION_COMPENSATION`: Compensation paid to the seller when there are differences in the platform commission paid by the seller. - `PLATFORM_PENALTY`: Penalty imposed for a violation of TikTok Shop policies (the corresponding amount has been deducted from the seller's account). For details, please refer to the email notification sent to the seller. - `PROMOTION_ADJUSTMENT`: Adjustment when a seller takes part in a platform promotion and there are differences between the promotion price and the actual amount paid by the seller. - `REBATE`: A discount on referral fees offered by TikTok Shop to eligible sellers. - `PLATFORM_COMPENSATION`: Compensation paid to the seller after the seller successfully appealed for a customer dispute. - `PLATFORM_REIMBURSEMENT`: Reimbursement paid by TikTok Shop for an order refunded under TikTok's refund without return policy (the seller is not responsible). - `COFUNDED_CREATOR_REWARDS`: Fees charged for joining the co-funded creator rewards program to reward creator activities. - `STAMP_DUTY`: To comply with Thailand's tax regulations, TikTok Shop withholds and remits the stamp duty levied on the withholding tax agent appointment letter. This document falls under Instrument No. 21 (Agency) and is subject to a THB 30 stamp duty. **Logistics-related adjustments** - `FBT_WAREHOUSE_SERVICE_FEE`: Amount charged by TikTok Fulfillment Portal (Pipak) for warehousing-related bills incurred by the seller under the Fulfilled by TikTok (FBT) service. - `LOGISTICS_REIMBURSEMENT`: Reimbursement paid by TikTok Shop for an order refunded due to logistics-related issues (e.g. lost or damaged order). - `SHIPPING_FEE_ADJUSTMENT`: Adjustment when there are differences or mistakes with the shipping fee paid by the seller. - `SHIPPING_FEE_COMPENSATION`: Compensation given to sellers due to differences between the actual shipping fee and the pre-paid shipping fee. - `SHIPPING_FEE_REBATE`: Shipping fee rebate provided to the seller as part of their participation in a platform campaign. - `SAMPLE_SHIPPING_FEE`: Fees charged for sending samples using the TikTok logistics provider. - `SELLER_MISSION_REWARD`: Platform provided cash reward for seller mission completion. - `Violation fee （settlement fee）`: The deduction to cover the cost of buyer's losses for the unpleasant experience of the buyer due to an issue that is the seller's responsibility. - `Violation fee （credit card）`: The amount owed to TikTok Shop from previous transactions, charged to your primary credit card. - `Bill payment （negative balance）`: The amount you owe TikTok Shop, charged to your primary credit card. - `Sales proceed（negative balance） `:Sales proceed that is ready to pay for negeative balance. - `Bill deduction for negative balance `:Deduction for the amount you owe TikTok Shop after all platform fees are deducted from your net earnings. **Miscellaneous adjustments** `OTHER_ADJUSTMENT`: Adjustment for other reasons. order_id: type: string description: |- The order ID. Each transaction can only be associated with an order ID or an adjustment ID. order_create_time: type: integer format: int64 description: The time when the order was created, as a Unix timestamp in seconds. adjustment_id: type: string description: |- The adjustment ID if the transaction is an adjustment. Each transaction can only be associated with an order ID or an adjustment ID. adjustment_order_id: type: string description: The order ID associated with the adjustment, if any. adjustment_amount: type: string description: |- The adjustment amount based on TikTok Shop policy. Refer to `transactions.type` for the list of adjustment-related policies. settlement_amount: type: string description: |- The settlement amount for the order. Formula: revenue_amount - shipping_cost_amount - fee_tax_amount - adjustment_amount revenue_amount: type: string description: The revenue amount at the time of order settlement. This is equivalent to the sum of all amounts in `revenue_breakdown`. revenue_breakdown: $ref: "#/components/schemas/GetTransactionsByStatementResponseDataTransactionRevenueBreakdown" description: An object containing the amounts that directly contribute to `revenue_amount`. shipping_cost_amount: type: string description: The shipping costs at the time of order settlement. This is equivalent to the sum of all contributory amounts in `shipping_cost_breakdown`. shipping_cost_breakdown: $ref: "#/components/schemas/GetTransactionsByStatementResponseDataTransactionShippingCostBreakdown" description: An object containing the amounts that directly contribute to `shipping_cost_amount`. fee_tax_amount: type: string description: The total fees and taxes charged by TikTok Shop at the time of order settlement. Shipping-related costs are excluded. This is equivalent to the sum of all contributory amounts in `fee_tax_breakdown`. fee_tax_breakdown: $ref: "#/components/schemas/GetTransactionsByStatementResponseDataTransactionFeeTaxBreakdown" description: An object containing the fee and tax amounts that directly contribute to `fee_tax_amount`. supplementary_component: $ref: "#/components/schemas/GetTransactionsByStatementResponseDataTransactionSupplementaryComponent" description: Supplementary costs for your reference. These amounts do not directly contribute to the settlement amount. reserve_id: type: string description: The ID of a reserve transaction. reserve_amount: type: string description: |- The amount withheld from settlement based on TikTok Shop Reserve Policy. Refer to TikTok Shop Academy for more information. - A positive amount indicates funds that have been released. - A negative amount indicates funds being withheld from the settlement. associated_order_id: type: string description: The order ID associated with the reserve transaction. reserve_status: type: string enum: - COLLECTED - RELEASED x-enum-descriptions: - A portion of the order's settlement amount has been withheld as reserve funds. - The previously reserved funds have been released and paid out to the seller. description: |- The status of the reserve funds. Possible values: - COLLECTED: A portion of the order's settlement amount has been withheld as reserve funds. - RELEASED: The previously reserved funds have been released and paid out to the seller. estimated_release_time: type: string description: |- The estimated date when the reserve funds will be released and paid out to the seller. Unix timestamp. Returns an empty value if the reserve funds have already been released. GetTransactionsByStatementResponseDataTransactionFeeTaxBreakdown: type: object properties: fee: $ref: "#/components/schemas/GetTransactionsByStatementResponseDataTransactionFeeTaxBreakdownFee" description: An object containing the fee amounts that contribute to `fee_tax_amount`. tax: $ref: "#/components/schemas/GetTransactionsByOrderResponseDataSkuTransactionFeeTaxBreakdownTax" description: An object containing the tax amounts that contribute to `fee_tax_amount`. GetTransactionsByStatementResponseDataTransactionFeeTaxBreakdownFee: type: object properties: platform_commission_amount: type: string description: The commission amount charged by the platform. referral_fee_amount: type: string description: |- The referral fee charged for processing successful orders. Applicable only for the US. refund_administration_fee_amount: type: string description: The 20% refund administration fee deducted from the total refunded referral fee amount. transaction_fee_amount: type: string description: The transaction fee charged for processing successful orders. credit_card_handling_fee_amount: type: string description: The handling fee charged when the buyer pays with a credit card. affiliate_commission_amount: type: string description: The commission amount charged to the seller for payment to the creator. affiliate_commission_amount_before_pit: type: string description: |- The affiliate ads commission paid to a creator before any personal income tax withholding. Applicable only for SEA markets. affiliate_partner_commission_amount: type: string description: The commission amount for purchases through affiliate partner links. affiliate_ads_commission_amount: type: string description: The commission for eligible orders from ads. sfp_service_fee_amount: type: string description: The service fee charged for participation in the [Seller Free Shipping Programme]. live_specials_fee_amount: type: string description: The service fee charged for participation in the [LIVE Specials Programme]. bonus_cashback_service_fee_amount: type: string description: The service fee charged for participation in the bonus cashback program. mall_service_fee_amount: type: string description: The service fee charged for using TikTok Shop Mall. voucher_xtra_service_fee_amount: type: string description: The service fee charged for participation in the Voucher Xtra program. flash_sales_service_fee_amount: type: string description: The service fee charged for participation in flash sales. cofunded_promotion_service_fee_amount: type: string description: The service fee charged for co-funded promotions. pre_order_service_fee_amount: type: string description: The service fee charged for participation in the pre-order program. tsp_commission_amount: type: string description: The commission amount charged by TikTok Shop Partners (TSP). dt_handling_fee_amount: type: string description: The handling fee charged for orders that are fulfilled by Dilayani Tokopedia. epr_pob_service_fee_amount: type: string description: The eco-contributions TikTok Shop pays on your behalf to the qualified producer responsibility organization (PRO). seller_paylater_handling_fee_amount: type: string description: The handling fee charged to the seller for participation in the PayLater program. fee_per_item_sold_amount: type: string description: |- The fee charged to sellers by the platform for each item sold. This is equivalent to the sum of all per-item fees for all SKUs in the order. Applicable only for the Brazil market. cofunded_creator_bonus_amount: type: string description: The portion of the creator bonus that you co-fund as part of the commission boost campaign. dynamic_commission_amount: type: string description: |- The dynamic commission fee is the amount that the platform charges to all sellers for every successfully delivered order. Applicable only for Indonesia. external_affiliate_marketing_fee_amount: type: string description: The service fee for participating in the External Affiliate Marketing Solution Program, as stated during registration. vn_fix_infrastructure_fee: type: string description: Infrastructure fees are a fixed service fee that TikTok Shop charges for providing, maintaining, and developing infrastructure for delivery services. It applies to delivered orders on the main order level. affiliate_commission_deposit: type: string description: The amount reserved for creator commissions after an order is paid. Applies only to commissions tied to order volume and is based on the highest earning rate. affiliate_commission_release: type: string description: The commission deposit refunded to you after order settlement. Applies only to commissions tied to order volume. tap_shop_ads_commission: type: string description: The advertising commission cost a merchant pays to TikTok Shop Affiliate Partner (TAP). shipping_fee_guarantee_service_fee: type: string description: A flat service fee charged for each order under the Shipping Fee Guarantee Program installation_service_fee: type: string description: The fee TikTok Shop charges you for using platform installation service campaign_resource_fee: type: string description: Amount of campaign resource fee from program seller joining in platform_special_service_fee_amount: type: string description: The portion of the Distance Shipping Fee paid by the customer that exceeds the logistics service provider's charge, retained by TikTok Shop to support a secure fulfillment experience smart_promotion_fee_amount: type: string description: This fee includes funds from TikTok Shop to help provide promotions to customers gmv_max_ad_fee_amount: type: string description: A percentage deducted from your net sales per order for GMV Max (net sales performance goal) advertising. platform_semi_managed_commission_fee: type: string description: Calculated as a percentage of (original price − seller discount + customer-paid shipping fee). platform_semi_managed_commission_fee_tax: type: string description: This amount is collected on behalf of the government. campaign_period_fee_cfp_amount: type: string description: Fee charged during Co-funded Promotion campaigns. campaign_period_fee_sp_amount: type: string description: Fee charged during Smart Promotion campaigns. campaign_period_fee_sp_tax_amount: type: string description: Sales tax applied to the campaign period fee under Smart Promotion. campaign_period_fee_cfp_tax_amount: type: string description: Sales tax applied to the campaign period fee under Co-funded Promotion. seller_growth_fee_amount: type: string description: A fee charged on each successful order to provide Bonus Cashback and other growth benefits. category_led_campaign_fee_amount: type: string description: Fee charged for participating in the Category-led campaign. category_led_campaign_fee_tax_amount: type: string description: Sales tax charged for the fee. brand_amplification_program_commission: type: string description: Commission fee charged for participating in the Brand Amplification Program. brand_amplification_program_fee_tax: type: string description: Sales tax charged for the fee. brand_campaign_fee: type: string description: Fee charged for participating in the Brand campaign. brand_campaign_fee_tax: type: string description: Sales tax charged for the fee. failed_delivery_shipping_fee: type: string description: Shipping fee for order that failed to be delivered to the customer. In some cases, the fee may be shared between seller and platform. buyer_fault_return_shipping_fee: type: string description: Shipping fee for buyer-fault returns. In some cases, the fee may be shared between seller and platform. insurance_fee: type: string description: Premium charged per order for insurance coverage gmv_max_coupon_fee: type: string description: The cost of GMV Max coupons. cps_shop_ads_commission_tax_amount: type: string description: Sales tax applied to GMV Max ad fee shipping_insurance_fee_tax_amount: type: string description: The tax amount charged on the shipping insurance fee. new_customer_growth_package_fee: type: string description: Fee for using the New Customer Growth Package to offer discounts that attract new customers to your shop. target_product_gmv_growth_package_fee: type: string description: Fee for using the Product GMV Growth Package to offer discounts on selected products and increase their sales. store_gmv_growth_package_fee: type: string description: Fee for using the Shop GMV Growth Package to offer store-wide discounts and grow your overall sales. auto_post_shoppable_video_commission_fee: type: string description: The commission fee charged to the seller for orders attributed to the AI-generated, auto-post shoppable videos. seller_funded_user_spoint_service_fee: type: string description: Service fee charged for seller-funded user S-Points issued to shoppers. Calculated based on the order's actual payment amount and refunded if the order is later returned. GetTransactionsByStatementResponseDataTransactionRevenueBreakdown: type: object properties: subtotal_before_discount_amount: type: string description: The total price of all order items before any seller discounts and platform discounts are deducted. This is equivalent to the shop's gross sales. refund_subtotal_before_discount_amount: type: string description: The total price of all refunded items before any seller discounts. This is equivalent to the shop's gross sales refund. seller_discount_amount: type: string description: |- The total amount of discounts funded by the seller, including: - Seller promotions (Product Discount, Flash Deal, Buy More Save More, Voucher and Bundle Deal) - Seller's portion of a co-funded voucher discount in co-funding campaigns - Seller discounts during a campaign seller_discount_refund_amount: type: string description: Discounts returned to the sellers due to returns or refunds. cod_service_fee_amount: type: string description: |- The cash on delivery service fees charged to buyers. Applicable only for Saudi Arabia. refund_cod_service_fee_amount: type: string description: |- The refund for cash on delivery service fees. Applicable only for Saudi Arabia. distant_item_fee_amount: type: string description: The distance fee for items paid by the customer. With your current settings for Horizon+ Program, this fee is included in product price for orders with shipping out of Java island. GetTransactionsByStatementResponseDataTransactionShippingCostBreakdown: type: object properties: actual_shipping_fee_amount: type: string description: The actual shipping fee calculated based on the weight/dimensions measured by the carrier. For details, check `shipping_cost_breakdown.supplementary_component`. international_leg_logistics_amount: type: string description: The delivery fee charged to the seller for the international leg of a cross-border shipment shipping_fee_discount_amount: type: string description: The shipping fee subsidies and incentives provided by the platform. This includes all subsidies regardless of fulfillment channels or policies. For details, check `shipping_cost_breakdown.supplementary_component`. customer_paid_shipping_fee_amount: type: string description: The actual shipping fee borne by the customer, calculated based on the product weight uploaded by the seller. Negative numbers refer to the refunded amount of customer-paid shipping fees return_shipping_fee_amount: type: string description: The shipping fee paid by the seller for the delivery of returns. replacement_shipping_fee_amount: type: string description: |- The shipping fee paid by the seller for the delivery of goods replacement. Applicable only for Indonesia. exchange_shipping_fee_amount: type: string description: |- The shipping fee paid by the seller for the delivery of goods exchange. Applicable only for Indonesia. signature_confirmation_fee_amount: type: string description: The fee incurred for packages requiring signature confirmation services. shipping_insurance_fee_amount: type: string description: The shipping insurance fee incurred by the seller for purchasing additional TikTok shipping insurance services. fbt_fulfillment_fee_reimbursement_amount: type: string description: |- A reimbursement from TikTok Shop for Fulfilled by TikTok (FBT) orders that don't qualify for free shipping. Applicable only for the US. return_shipping_label_fee_amount: type: string description: The fee borne by the customer to cover the cost of return labels. This fee is collected on the seller's behalf and settled according to the agreed payment terms. seller_self_shipping_service_fee_amount: type: string description: A service fee charged for orders shipped through your own logistics provider. Applies to packages that don't meet the exemption criteria. return_shipping_fee_paid_buyer_amount: type: string description: Reimbursement for the shipping fees paid by customers to return packages failed_delivery_subsidy_amount: type: string description: For shipping fee from failed deliveries, you pay up to a standard rate, and TikTok Shop covers the remaining amount. shipping_fee_guarantee_reimbursement: type: string description: Reimbursement from the Shipping Fee Guarantee Program for failed deliveries or returns fbt_free_shipping_fee_amount: type: string description: This is the fee that you cover when offering customers free shipping through FBT. free_return_subsidy_amount: type: string description: Reimbursement for the platform-funded portion of return shipping fees, as part of the free returns offered to customers. distant_shipping_fee_amount: type: string description: The distance fee for shipping paid by the customer. With your current settings for Horizon+ Program, this fee is included in product price for orders with shipping out of Java island. shipping_app_service_fee_amount: type: string description: Shipping App Service Fee for using shipping fee to generate shipping labels logistics_service_fee: type: string description: A fee charged to sellers throughout the order lifecycle for logistics-related services, including processing, coordination, handling of delivery-related matters, and basic shipping incentives. It is an amount per order, which is based on the parcel's weight tier and shipping route. It allows the platform to continuously enhance a high-quality, sustainable logistics network that serves both sellers and customers better over the long term, amidst changing global conditions. fbt_overall_merchant_subsidy: type: string description: Subsidy applied to your orders and offered to all FBT (Fulfilled by TikTok) merchants for the statement period. The amount is calculated based on your qualifying FBT order volume during this period. fbt_key_merchant_subsidy: type: string description: Subsidy applied to your orders based on eligibility for the key merchant program. The amount is calculated based on your qualifying FBT (Fulfilled by TikTok) order volume during the statement period. tiktok_shop_shipping_incentive_amount: type: string description: The shipping fee incentive provided by TikTok Shop. supplementary_component: $ref: "#/components/schemas/GetTransactionsByStatementResponseDataTransactionShippingCostBreakdownSupplementaryComponent" description: Supplementary costs for your reference. These amounts do not directly contribute to `shipping_cost_amount`. hazmat_noncompliance_fee: type: string description: Fee charged when a parcel containing hazardous materials is shipped without the required declaration or compliant packaging, as assessed by the carrier. Charged when the parcel is delivered. hazmat_handling_fee: type: string description: Fee charged for the additional handling required to ship a parcel containing hazardous materials. Charged when the parcel is delivered. non_standard_weight_fee: type: string description: Fee charged when a parcel exceeds the standard weight range. The rate is set by TikTok Shop and charged when the parcel is delivered. non_standard_dimension_fee: type: string description: Fee charged when a parcel exceeds the standard size range. The rate is set by TikTok Shop and charged when the parcel is delivered. GetTransactionsByStatementResponseDataTransactionShippingCostBreakdownSupplementaryComponent: type: object properties: platform_shipping_fee_discount_amount: type: string description: The shipping fee discount provided in accordance with a campaign policy. This is part of `shipping_fee_discount_amount`. promo_shipping_incentive_amount: type: string description: The additional shipping incentive that the seller will receive if the seller signed up for the Co-Funded Free Shipping Program. A negative amount indicates a reversal of incentives due to order refunds attributed to the seller's responsibility. This is part of `shipping_fee_discount_amount`. shipping_fee_subsidy_amount: type: string description: |- The shipping fee subsidy funded by the platform for seller shipping. This is part of `shipping_fee_discount_amount`. - Positive amount represents a subsidy received by the seller. - Negative amount represents a subsidy that the seller must return to TikTok Shop. seller_shipping_fee_discount_amount: type: string description: The shipping fee discount provided by sellers. customer_shipping_fee_offset_amount: type: string description: |- The fee to offset TikTok Shop Shipping Incentive or customer-paid shipping fee, resulting in a net charge of $0 to the seller. Applicable only for the US. fbm_shipping_cost_amount: type: string description: The shipping fee incurred by the seller for using TikTok Shipping. This is part of `actual_shipping_fee_amount`. fbt_shipping_cost_amount: type: string description: |- The shipping fee incurred by the seller for orders fulfilled by TikTok (FBT). This is part of `actual_shipping_fee_amount`. Applicable only for EU and UK. fbt_fulfillment_fee_amount: type: string description: |- The shipping and warehouse fulfillment fee incurred by the seller for orders fulfilled by TikTok (FBT). This is part of `actual_shipping_fee_amount`. Applicable only for the US. fbt_fulfillment_fee_reimbursement_amount: type: string description: "(**Deprecated**: This field is deprecated and will return an empty string. Please refer to `shipping_cost_breakdown.fbt_fulfillment_fee_reimbursement_amount` instead for the relevant details.)" deprecated: true return_refund_subsidy_amount: type: string description: For shipping fee from returns and refunds, you pay up to a standard rate, and TikTok Shop covers the remaining amount.This is part of `customer_paid_shipping_fee_amount`. refunded_customer_shipping_fee_amount: type: string description: Shipping fee returned to customers due returns and refunds.Does not include subsidies.This is part of `customer_paid_shipping_fee_amount`. customer_shipping_fee: type: string description: The shipping fee borne by the customer.This is part of `customer_paid_shipping_fee_amount`. refund_customer_shipping_fee: type: string description: Refund the shipping fee borne by the customer. Include subsidies.This is part of `customer_paid_shipping_fee_amount`. GetTransactionsByStatementResponseDataTransactionSupplementaryComponent: type: object properties: customer_payment_amount: type: string description: The total amount paid by the customer. customer_refund_amount: type: string description: The exact amount refunded to the customer. platform_discount_amount: type: string description: The discounts funded by the platform, such as coupons and campaign discounts. platform_discount_refund_amount: type: string description: The platform discounts to be reversed (and deducted from the final settlement) if the order was refunded as a result of the seller's responsibility. seller_cofunded_discount_amount: type: string description: The seller's portion of a co-funded voucher discount in co-funding campaigns. seller_cofunded_discount_refund_amount: type: string description: The seller's portion of a co-funded voucher discount in co-funding campaigns that was refunded to the seller. platform_cofunded_discount_amount: type: string description: The platform's portion of a co-funded voucher discount in co-funding campaigns. platform_cofunded_discount_refund_amount: type: string description: The platform's portion of a co-funded voucher discount in co-funding campaigns that was refunded to the platform. retail_delivery_fee_amount: type: string description: |- The final retail delivery fee for deliveries in Colorado, US. For more information, see [Colorado Retail Delivery Fee FAQ](https://seller-us.tiktok.com/university/essay?knowledge_id=2459780628350762&default_language=en&identity=1). Formula: retail_delivery_fee_payment_amount + retail_delivery_fee_refund_amount retail_delivery_fee_payment_amount: type: string description: The retail delivery fee for deliveries in Colorado, US. For more information, see [Colorado Retail Delivery Fee FAQ](https://seller-us.tiktok.com/university/essay?knowledge_id=2459780628350762&default_language=en&identity=1). retail_delivery_fee_refund_amount: type: string description: The retail delivery fee subsidy by the platform for losses due to returns, refunds, or other issues in Colorado, US. sales_tax_amount: type: string description: |- The final sales tax to be paid by the customer for the product and delivery. Formula: sales_tax_payment_amount - sales_tax_refund_amount sales_tax_payment_amount: type: string description: The expected sales tax to be paid by the customer for the product and delivery. sales_tax_refund_amount: type: string description: The sales tax amount returned to the customer in the event of a refund. GetUnsettledTransactionsResponse: 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/GetUnsettledTransactionsResponseData" GetUnsettledTransactionsResponseData: type: object properties: next_page_token: type: string description: An opaque token used to retrieve the next page of a paginated result set. If this value is present and non-empty, provide it in the `page_token` parameter of the next request and reuse the same shop context, explicit `search_time_ge`, `search_time_lt`, `sort_field`, and `sort_order` values. If this value is absent or empty, pagination is complete. total_count: type: integer format: int64 description: The total number of matching unsettled transaction records across all pages. sum_est_settlement_amount: type: string description: The sum of the estimated settlement amount. sum_est_revenue_amount: type: string description: The sum of the estimated revenue amount. sum_est_adjustment_amount: type: string description: The sum of the estimated adjustment amount. sum_est_fee_amount: type: string description: The sum of the estimated fee amount. transactions: type: array items: $ref: "#/components/schemas/GetUnsettledTransactionsResponseDataTransaction" description: The list of transaction records in the statement. Each transaction corresponds to an order, an adjustment, or a reserve-related transaction. GetUnsettledTransactionsResponseDataTransaction: type: object properties: type: type: string description: |- The transaction type. Standard transactions - `ORDER`: A transaction related to an order settlement. - If the transaction is an adjustment, it returns one of the following values: Platform-related adjustments - `CHARGE_BACK`: Charges returned to a payment card after a customer has successfully disputed an item on their account statement or transactions report. - `CUSTOMER_SERVICE_COMPENSATION`: Extra compensation or compensation paid to a customer after the after-sales period by customer service. - `DEDUCTIONS_INCURRED_BY_SELLER`: Deduction arising from customer dissatisfaction as a result of the seller's responsibility. This includes issues such as fraud, empty packages, items that do not match the product display page, or items of lower value than advertised. - `GMV_PAYMENT_FOR_ADS`: Amount used to pay for your advertisement if you are enabled "auto pay ads with shop GMV", or to pay for Tiktok Promote ads orders. - `PLATFORM_COMMISSION_ADJUSTMENT`: Adjustment when there are differences in the platform commission paid by the seller. - `PLATFORM_COMMISSION_COMPENSATION`: Compensation paid to the seller when there are differences in the platform commission paid by the seller. - `PLATFORM_PENALTY`: Penalty imposed for a violation of TikTok Shop policies (the corresponding amount has been deducted from the seller's account). For details, please refer to the email notification sent to the seller. - `PROMOTION_ADJUSTMENT`: Adjustment when a seller takes part in a platform promotion and there are differences between the promotion price and the actual amount paid by the seller. - `REBATE`: A discount on referral fees offered by TikTok Shop to eligible sellers. - `PLATFORM_COMPENSATION`: Compensation paid to the seller after the seller successfully appealed for a customer dispute. - `PLATFORM_REIMBURSEMENT`: Reimbursement paid by TikTok Shop for an order refunded under TikTok's refund without return policy (the seller is not responsible). Logistics-related adjustments - `FBT_WAREHOUSE_SERVICE_FEE`: Amount charged by TikTok Fulfillment Portal (Pipak) for warehousing-related bills incurred by the seller under the Fulfilled by TikTok (FBT) service. - `LOGISTICS_REIMBURSEMENT`: Reimbursement paid by TikTok Shop for an order refunded due to logistics-related issues (e.g. lost or damaged order). - `SHIPPING_FEE_ADJUSTMENT`: Adjustment when there are differences or mistakes with the shipping fee paid by the seller. - `SHIPPING_FEE_COMPENSATION`: Compensation given to sellers due to differences between the actual shipping fee and the pre-paid shipping fee. - `SHIPPING_FEE_REBATE`: Shipping fee rebate provided to the seller as part of their participation in a platform campaign. - `SAMPLE_SHIPPING_FEE`: Fees charged for sending samples using the TikTok logistics provider. Miscellaneous adjustments `OTHER_ADJUSTMENT`: Adjustment for other reasons. id: type: string description: The transaction ID. status: type: string description: The transaction status. Only supports `UNSETTLED`. currency: type: string description: The three-letter currency code in ISO 4217 format. estimated_settlement: type: string description: |- Estimated settlement time for the transaction. Possible return values: - A relative settlement schedule, such as `Delivered + N days`, when the order has not been delivered and only an approximate settlement policy is available. - A Unix timestamp in seconds when the order has been delivered and the estimated settlement time is available. unsettled_reason: type: string description: reason for why transaction is pending for settlement order_create_time: type: integer format: int64 description: The time when the order was created, as a Unix timestamp in seconds. order_delivery_time: type: integer format: int64 description: The time when the order was delivered, as a Unix timestamp in seconds. No delivery time is available if the order has not been delivered. order_id: type: string description: |- The order ID. Each transaction can only be associated with an order ID or an adjustment ID. adjustment_id: type: string description: |- The adjustment ID if the transaction is an adjustment. Each transaction can only be associated with an order ID or an adjustment ID. adjustment_order_id: type: string description: The order ID associated with the adjustment, if any. est_adjustment_amount: type: string description: |- The estimated adjustment amount based on TikTok Shop policy. Refer to `transactions.type` for the list of adjustment-related policies. est_settlement_amount: type: string description: |- The estimated settlement amount for the order. Formula: revenue_amount - shipping_cost_amount - fee_tax_amount - adjustment_amount est_revenue_amount: type: string description: The estimated revenue amount. This is equivalent to the sum of all amounts in `revenue_breakdown`. revenue_breakdown: $ref: "#/components/schemas/RevenueBreakdown" description: The revenue amounts that directly contribute to `est_revenue_amount`. est_shipping_cost_amount: type: string description: The estimated shipping costs, please note that when order hasn't been delivered, no complete shipping cost can be provided. This is equivalent to the sum of all contributory amounts in `shipping_cost_breakdown`. shipping_cost_breakdown: $ref: "#/components/schemas/GetUnsettledTransactionsResponseDataTransactionShippingCostBreakdown" description: The shipping cost amounts that directly contribute to `est_shipping_cost_amount`. est_fee_tax_amount: type: string description: The estimated total fees and taxes charged by TikTok Shop. Shipping-related costs are excluded. This is equivalent to the sum of all contributory amounts in `fee_tax_breakdown`. fee_tax_breakdown: $ref: "#/components/schemas/GetUnsettledTransactionsResponseDataTransactionFeeTaxBreakdown" description: The fee and tax amounts that directly contribute to `est_fee_tax_amount`. GetUnsettledTransactionsResponseDataTransactionFeeTaxBreakdown: type: object properties: fee: $ref: "#/components/schemas/GetUnsettledTransactionsResponseDataTransactionFeeTaxBreakdownFee" description: The fee amounts that contribute to `est_fee_tax_amount`. tax: $ref: "#/components/schemas/GetUnsettledTransactionsResponseDataTransactionFeeTaxBreakdownTax" description: The tax amounts that contribute to `est_fee_tax_amount`. GetUnsettledTransactionsResponseDataTransactionFeeTaxBreakdownFee: type: object properties: platform_commission_amount: type: string description: The commission amount charged by the platform. referral_fee_amount: type: string description: |- The referral fee charged for processing successful orders. Applicable only for the US. refund_administration_fee_amount: type: string description: The 20% refund administration fee deducted from the total refunded referral fee amount. transaction_fee_amount: type: string description: The transaction fee charged for processing successful orders. credit_card_handling_fee_amount: type: string description: The handling fee charged when the buyer pays with a credit card. affiliate_commission_amount: type: string description: The commission amount charged to the seller for payment to the creator. affiliate_commission_before_pit_amount: type: string description: |- The affiliate ads commission paid to a creator before any personal income tax withholding. Applicable only for SEA markets. pit_withheld_from_ads_commission_amount: type: string description: |- The creator's personal income tax withholding amount, deducted from the affiliate ads commission. Sellers are responsible for declaration and remittance to the tax authority, as well as providing finalized personal income tax documentation to creators. Applicable only for SEA markets. affiliate_partner_commission_amount: type: string description: The commission amount for purchases through affiliate partner links. affiliate_ads_commission_amount: type: string description: The commission for eligible orders from ads. sfp_service_fee_amount: type: string description: The service fee charged for participation in the [Seller Free Shipping Programme]. live_specials_fee_amount: type: string description: The service fee charged for participation in the [LIVE Specials Programme]. bonus_cashback_service_fee_amount: type: string description: The service fee charged for participation in the bonus cashback program. mall_service_fee_amount: type: string description: The service fee charged for using TikTok Shop Mall. retail_delivery_fee_amount: type: string description: |- The final retail delivery fee for deliveries in Colorado, US. For more information, see [Colorado Retail Delivery Fee FAQ](https://seller-us.tiktok.com/university/essay?knowledge_id=2459780628350762&default_language=en&identity=1). Formula: retail_delivery_fee_payment_amount + retail_delivery_fee_refund_amount retail_delivery_fee_payment_amount: type: string description: The retail delivery fee for deliveries in Colorado, US. For more information, see [Colorado Retail Delivery Fee FAQ](https://seller-us.tiktok.com/university/essay?knowledge_id=2459780628350762&default_language=en&identity=1). retail_delivery_fee_refund_amount: type: string description: The retail delivery fee subsidy by the platform for losses due to returns, refunds, or other issues in Colorado, US. platform_special_service_fee_amount: type: string description: The portion of the Distance Shipping Fee paid by the customer that exceeds the logistics service provider's charge, retained by TikTok Shop to support a secure fulfillment experience smart_promotion_fee_amount: type: string description: This fee includes funds from TikTok Shop to help provide promotions to customers vn_fix_infrastructure_fee: type: string description: Infrastructure fees are a fixed service fee that TikTok Shop charges for providing, maintaining, and developing infrastructure for delivery services. It applies to delivered orders on the main order level. dynamic_commission_amount: type: string description: |- The dynamic commission fee is the amount that the platform charges to all sellers for every successfully delivered order. Applicable only for Indonesia. campaign_period_fee_cfp_amount: type: string description: Fee charged during Co-funded Promotion campaigns. campaign_period_fee_sp_amount: type: string description: Fee charged during Smart Promotion campaigns. campaign_period_fee_sp_tax_amount: type: string description: Sales tax applied to the campaign period fee under Smart Promotion. campaign_period_fee_cfp_tax_amount: type: string description: Sales tax applied to the campaign period fee under Co-funded Promotion. seller_growth_fee_amount: type: string description: A fee charged on each successful order to provide Bonus Cashback and other growth benefits. failed_delivery_shipping_fee: type: string description: Shipping fee for order that failed to be delivered to the customer. In some cases, the fee may be shared between seller and platform. buyer_fault_return_shipping_fee: type: string description: Shipping fee for buyer-fault returns. In some cases, the fee may be shared between seller and platform. insurance_fee: type: string description: Premium charged per order for insurance coverage cps_shop_ads_commission_tax_amount: type: string description: Sales tax applied to GMV Max ad fee shipping_insurance_fee_tax_amount: type: string description: Tax applied to the shipping protection fee. new_customer_growth_package_fee: type: string description: Fee for using the New Customer Growth Package to offer discounts that attract new customers to your shop. target_product_gmv_growth_package_fee: type: string description: Fee for using the Product GMV Growth Package to offer discounts on selected products and increase their sales. store_gmv_growth_package_fee: type: string description: Fee for using the Shop GMV Growth Package to offer store-wide discounts and grow your overall sales. auto_post_shoppable_video_commission_fee: type: string description: The commission fee charged to the seller for orders attributed to the AI-generated, auto-post shoppable videos. seller_funded_user_spoint_service_fee: type: string description: Service fee charged for seller-funded user S-Points issued to shoppers. Calculated based on the order's actual payment amount and refunded if the order is later returned. flash_sales_service_fee_amount: type: string description: The service fee charged for participation in flash sales. GetUnsettledTransactionsResponseDataTransactionFeeTaxBreakdownTax: type: object properties: sales_tax_amount: type: string description: |- The final sales tax to be paid by the customer for the product and delivery. Formula: sales_tax_payment_amount - sales_tax_refund_amount sales_tax_payment_amount: type: string description: The expected sales tax to be paid by the customer for the product and delivery. sales_tax_refund_amount: type: string description: The sales tax amount returned to the customer in the event of a refund. vat_amount: type: string description: |- The VAT paid by the platform on the seller's behalf. Applicable only for cross-border shop orders. import_vat_amount: type: string description: |- The import VAT, a tax paid on goods bought in one country and imported into another. Applicable only for cross-border shop orders. customs_duty_amount: type: string description: |- The customs duties, a type of tax on cross-border goods collected by governments. Applicable only for cross-border shop orders. customs_clearance_amount: type: string description: |- The fees charged by logistic suppliers for customs clearance services. Applicable only for cross-border shop orders. sst_amount: type: string description: The sales and service tax (SST) collected and remitted to the tax authority by the platform for low-value goods imported into Malaysia, effective January 1, 2024. gst_amount: type: string description: The goods and services tax (GST) collected and remitted to the tax authority by the platform for low-value goods imported into Singapore, effective January 1, 2023. sales_tax_referral_fee_amount: type: string description: Some U.S. states consider referral fees taxable. To comply with state tax laws, TikTok Inc. collects and remits applicable sales tax when a taxable fee is charged. smart_promotion_fee_tax_amount: type: string description: The sales tax applied to the Smart Promotion fee. cedular_tax: type: string description: The Mexican Guanajuato cedular tax new_customer_growth_package_fee_tax: type: string description: The sales tax applied to the New Customer Growth Package fee. store_gmv_growth_package_fee_sales_tax: type: string description: The sales tax applied to the Shop GMV Growth Package fee. target_product_gmv_growth_package_tax: type: string description: The sales tax applied to the Product GMV Growth Package fee. auto_post_shoppable_video_sales_tax: type: string description: The sales tax applied to the auto-post shoppable video commission fee. GetUnsettledTransactionsResponseDataTransactionShippingCostBreakdown: type: object properties: actual_shipping_fee_amount: type: string description: The actual shipping fee calculated based on the weight/dimensions measured by the carrier. For details, check ` shipping_cost_breakdown.supplementary_component`. international_leg_logistics_amount: type: string description: The delivery fee charged to the seller for the international leg of a cross-border shipment shipping_fee_discount_amount: type: string description: The shipping fee subsidies and incentives provided by the platform. This includes all subsidies regardless of fulfillment channels or policies. For details, check ` shipping_cost_breakdown.supplementary_component`. customer_paid_shipping_fee_amount: type: string description: The actual shipping fee borne by the customer, calculated based on the product weight uploaded by the seller. return_shipping_fee_amount: type: string description: The shipping fee paid by the seller for the delivery of returns. replacement_shipping_fee_amount: type: string description: |- The shipping fee paid by the seller for the delivery of goods replacement. Applicable only for Indonesia. exchange_shipping_fee_amount: type: string description: |- The shipping fee paid by the seller for the delivery of goods exchange. Applicable only for Indonesia. signature_confirmation_fee_amount: type: string description: The fee incurred for packages requiring signature confirmation services shipping_insurance_fee_amount: type: string description: The shipping insurance fee incurred by the seller for purchasing additional TikTok shipping insurance services. distant_shipping_fee_amount: type: string description: The distance fee for shipping paid by the customer. With your current settings for Horizon+ Program, this fee is included in product price for orders with shipping out of Java island. shipping_app_service_fee_amount: type: string description: Shipping App Service Fee for using shipping fee to generate shipping labels logistics_service_fee: type: string description: A fee charged to sellers throughout the order lifecycle for logistics-related services, including processing, coordination, handling of delivery-related matters, and basic shipping incentives. It is an amount per order, which is based on the parcel's weight tier and shipping route. It allows the platform to continuously enhance a high-quality, sustainable logistics network that serves both sellers and customers better over the long term, amidst changing global conditions. fbt_overall_merchant_subsidy: type: string description: Subsidy applied to your orders and offered to all FBT (Fulfilled by TikTok) merchants for the statement period. The amount is calculated based on your qualifying FBT order volume during this period. fbt_key_merchant_subsidy: type: string description: Subsidy applied to your orders based on eligibility for the key merchant program. The amount is calculated based on your qualifying FBT (Fulfilled by TikTok) order volume during the statement period. supplementary_component: $ref: "#/components/schemas/GetUnsettledTransactionsResponseDataTransactionShippingCostBreakdownSupplementaryComponent" description: Supplementary shipping cost amounts for reference. These amounts do not directly contribute to `est_shipping_cost_amount`. sfr_reimbursement: type: string description: Reimbursement from the Shipping Fee Reimbursement Program for failed deliveries or returns. tiktok_shop_shipping_incentive_amount: type: string description: The shipping fee incentive provided by TikTok Shop. hazmat_noncompliance_fee: type: string description: Fee charged when a parcel containing hazardous materials is shipped without the required declaration or compliant packaging, as assessed by the carrier. Charged when the parcel is delivered. hazmat_handling_fee: type: string description: Fee charged for the additional handling required to ship a parcel containing hazardous materials. Charged when the parcel is delivered. non_standard_weight_fee: type: string description: Fee charged when a parcel exceeds the standard weight range. The rate is set by TikTok Shop and charged when the parcel is delivered. non_standard_dimension_fee: type: string description: Fee charged when a parcel exceeds the standard size range. The rate is set by TikTok Shop and charged when the parcel is delivered. GetUnsettledTransactionsResponseDataTransactionShippingCostBreakdownSupplementaryComponent: type: object properties: customer_shipping_fee_offset_amount: type: string description: |- The fee to offset TikTok Shop Shipping Incentive or customer-paid shipping fee, resulting in a net charge of $0 to the seller. Applicable only for the US. shipping_fee_subsidy_amount: type: string description: |- The shipping fee subsidy funded by the platform for seller shipping. This is part of `shipping_fee_discount_amount`. - Positive amount represents a subsidy received by the seller. - Negative amount represents a subsidy that the seller must return to TikTok Shop. platform_shipping_fee_discount_amount: type: string description: The shipping fee discount provided in accordance with a campaign policy.. This is part of `shipping_fee_discount_amount`. fbm_shipping_cost_amount: type: string description: The shipping fee incurred by the seller for using TikTok Shipping. This is part of `actual_shipping_fee_amount`. fbt_shipping_cost_amount: type: string description: |- The shipping fee incurred by the seller for orders fulfilled by TikTok (FBT). This is part of `actual_shipping_fee_amount`. Applicable for all regions except the US. promo_shipping_incentive_amount: type: string description: The additional shipping incentive that the seller will receive if the seller signed up for the Co-Funded Free Shipping Program from 2024/08/26 to 2024/12/31. A negative amount indicates a reversal of incentives due to order refunds attributed to the seller's responsibility. This is part of `shipping_fee_discount_amount`. fbt_fulfillment_fee_amount: type: string description: |- The shipping and warehouse fulfillment fee incurred by the seller for orders fulfilled by TikTok (FBT). This is part of `actual_shipping_fee_amount`. Applicable only for the US. seller_shipping_fee_discount_amount: type: string description: The shipping fee discount provided by sellers. GetVideoPerformancesResponse: 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/GetVideoPerformancesResponseData" GetVideoPerformancesResponseData: type: object properties: videos: type: array items: $ref: "#/components/schemas/GetVideoPerformancesResponseDataVideo" description: Contains a list of video objects. The inner list of objects will be organized in ascending order based on the video_id field. GetVideoPerformancesResponseDataVideo: type: object properties: id: type: string description: The video ID. The performances array contains the daily metrics for this video. performances: type: array items: $ref: "#/components/schemas/GetVideoPerformancesResponseDataVideoPerformance" description: The list of objects within will be arranged in ascending order based on the start_time field. GetVideoPerformancesResponseDataVideoPerformance: type: object properties: time_range: $ref: "#/components/schemas/GetVideoPerformancesResponseDataVideoPerformanceTimeRange" description: Time range object metrics: $ref: "#/components/schemas/GetVideoPerformancesResponseDataVideoPerformanceMetric" description: Performance metrics for this video. GetVideoPerformancesResponseDataVideoPerformanceMetric: type: object properties: anchor_display_rate: type: string description: Display rate for anchors, specified with two decimal numbers. click_through_rate: type: string description: Click through rate, specified with two decimal numbers. order_count: type: integer format: int64 description: Number of orders in this date. item_sold_count: type: integer format: int64 description: Number of sold items in this date. gmv: $ref: "#/components/schemas/Gmv" description: Gross merchandise value (GMV) for this video. GetVideoPerformancesResponseDataVideoPerformanceTimeRange: type: object properties: start_time: type: integer format: int64 description: Date of the metrics. end_time: type: integer format: int64 description: Date of the metrics. GetWarehouseDeliveryOptionsResponse: 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/GetWarehouseDeliveryOptionsResponseData" GetWarehouseDeliveryOptionsResponseData: type: object properties: delivery_options: type: array items: $ref: "#/components/schemas/GetWarehouseDeliveryOptionsResponseDataDeliveryOption" description: Delivery options available for the seller's warehouse or assignable to a product, depending on `scope`. Each option identifies its supported platforms. Options returned for `WAREHOUSE` may also include applicable weight and dimension limits. GetWarehouseDeliveryOptionsResponseDataDeliveryOption: type: object properties: id: type: string description: Delivery option ID. name: type: string description: Delivery option name. type: type: string enum: - STANDARD - EXPRESS - ECONOMY - SEND_BY_SELLER - INSTANT - SAMEDAY - NEXTDAY - CARGO description: |- Delivery option type. Possible values: - STANDARD - EXPRESS - ECONOMY - SEND_BY_SELLER - INSTANT - SAMEDAY - NEXTDAY - CARGO description: type: string description: Delivery option description. dimension_limit: $ref: "#/components/schemas/GetWarehouseDeliveryOptionsResponseDataDeliveryOptionDimensionLimit" description: The length, width, and height restrictions of the delivery option. weight_limit: $ref: "#/components/schemas/GetWarehouseDeliveryOptionsResponseDataDeliveryOptionWeightLimit" description: The weight restrictions of this delivery option. platform: type: array items: type: string enum: - TIKTOK_SHOP - TOKOPEDIA description: |- The platform on which the delivery option is available Possible values: - TIKTOK_SHOP - TOKOPEDIA GetWarehouseDeliveryOptionsResponseDataDeliveryOptionDimensionLimit: type: object properties: max_height: type: integer format: int64 description: Maximum height limit. max_length: type: integer format: int64 description: Maximum length limit. max_width: type: integer format: int64 description: Maximum width limit. unit: type: string enum: - CM - INCH description: |- The unit of measurement for the dimensions, with possible values: - CM - INCH GetWarehouseDeliveryOptionsResponseDataDeliveryOptionWeightLimit: type: object properties: max_weight: type: integer format: int64 description: Maximum weight limit. min_weight: type: integer format: int64 description: Minimum weight limit. unit: type: string enum: - GRAM - POUND - OUNCE - KILOGRAM description: |- The unit of measurement for the weight. Possible values: - GRAM - POUND - OUNCE - KILOGRAM GetWarehouseListResponse: 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/GetWarehouseListResponseData" GetWarehouseListResponseData: type: object properties: warehouses: type: array items: $ref: "#/components/schemas/GetWarehouseListResponseDataWarehouse" description: Warehouses returned for the seller. This field is omitted when the result contains no warehouse. GetWarehouseListResponseDataWarehouse: type: object properties: id: type: string description: The warehouse ID, a unique and immutable primary key, used for all warehouse logistics. entity_id: type: string description: The warehouse entity ID, used to associate physical information of a warehouse, different warehouses may be associated with the same entity. name: type: string description: Warehouse name. This name is not unique across the TikTok Shop system. effect_status: type: string enum: - ENABLED - DISABLED - RESTRICTED x-enum-descriptions: - All products in stock are available for sale. - All products in stock are unavailable for sale. - The warehouse is in holiday mode or order limit mode, so all products in stock are unavailable for sale. description: |- Indicates whether inventory at the warehouse is available for sale. Possible values: - `ENABLED`: All products in stock are available for sale. - `DISABLED`: All products in stock are unavailable for sale. - `RESTRICTED`: The warehouse is in holiday mode or order limit mode, so all products in stock are unavailable for sale. The seller can enable holiday mode in Seller Center when the seller cannot fulfill orders from the warehouse. Order limit mode is applied when TikTok Shop limits the order volume that can be fulfilled by the warehouse because of policy violations. type: type: string enum: - SALES_WAREHOUSE - RETURN_WAREHOUSE x-enum-descriptions: - Warehouse for shipping products. - Warehouse for receiving returned products. description: |- Possible values: - SALES_WAREHOUSE: Warehouse for shipping products. - RETURN_WAREHOUSE: Warehouse for receiving returned products. You can have the same warehouse for both shipping and receiving returns, but they will have different warehouse IDs with the same address. sub_type: type: string enum: - DOMESTIC_WAREHOUSE - CB_OVERSEA_WAREHOUSE - CB_DIRECT_SHIPPING_WAREHOUSE x-enum-descriptions: - The warehouse is in the same country as the target market and the seller. - For cross-border sellers, a local warehouse in the target market. - For cross-border sellers, a warehouse in the seller's base country, e.g., Mainland China or Hong Kong. description: |- Possible values: - DOMESTIC_WAREHOUSE: The warehouse is in the same country as the target market and the seller. - CB_OVERSEA_WAREHOUSE: For cross-border sellers, a local warehouse in the target market. - CB_DIRECT_SHIPPING_WAREHOUSE: For cross-border sellers, a warehouse in the seller's base country, e.g., Mainland China or Hong Kong. is_default: type: boolean description: The default warehouse. If a product is listed with no designated warehouse, the default warehouse will be used. address: $ref: "#/components/schemas/GetWarehouseListResponseDataWarehouseAddress" description: Warehouse address. GetWarehouseListResponseDataWarehouseAddress: type: object properties: region: type: string description: The country or region of the warehouse address. state: type: string description: Warehouse state or province. city: type: string description: Warehouse city. distict: type: string description: Warehouse district. town: type: string description: Warehouse town. contact_person: type: string description: Warehouse contact person name. first_name: type: string description: |- Kanji first name Applicable only for the JP market. last_name: type: string description: |- Kanji last name Applicable only for the JP market. first_name_local_script: type: string description: |- Hiragana or Katakana first name Applicable only for the JP market. last_name_local_script: type: string description: |- Hiragana or Katakana last name Applicable only for the JP market. postal_code: type: string description: Warehouse address postal code (also known as zip code) full_address: type: string description: The combined warehouse address, including the street address and other address information such as apartment number, building, floor..etc (optional) region_code: type: string description: The country or region code of the warehouse address. phone_number: type: string description: Warehouse phone number. address_line1: type: string description: |- The first line of the warehouse address, like street name and street number. Note: - For Brazilian market, this represents the neighborhood or district. - For the JP market, this represents the district (Chome), block (Banchi), building number (Go). address_line2: type: string description: |- The second line of the warehouse address, like flat, apartment, or suit. Note: For the Brazilian market, this represents the street name. address_line3: type: string description: The street number. The literal value `s/n` indicates that no street number is available. Available only in the Brazilian market. address_line4: type: string description: |- This represents supplement information, like flat, apartment, or suit (optional). Note: Available only in the Brazilian market. geolocation: $ref: "#/components/schemas/GetWarehouseListResponseDataWarehouseAddressGeolocation" description: The geographical location of the address. GetWarehouseListResponseDataWarehouseAddressGeolocation: type: object properties: latitude: type: string description: The latitude of the address. longitude: type: string description: The longitude of the address. GetWeeklyCreatorOutreachQuotaResponse: 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/GetWeeklyCreatorOutreachQuotaResponseData" GetWeeklyCreatorOutreachQuotaResponseData: type: object properties: data: $ref: "#/components/schemas/GetWeeklyCreatorOutreachQuotaResponseDataData" description: Creator outreach quota information for the shop. GetWeeklyCreatorOutreachQuotaResponseDataData: type: object properties: shop_id: type: string description: Shop id quota_type: type: string description: |- Quota type, e.g. bouns quota; period quota gmv_tier: type: string description: Shop gmv tier quota_sum: type: string description: Shop quota sum quota_use: type: string description: Shop quota used unlimited: type: boolean description: Whether the shop has unlimited creator outreach quota. reached_max_follower_cnt: type: string description: Max creator follower count this shop can reach new_connect_count: type: string description: New connect creator count during this quota period pair_connect_count: type: string description: Connect paired creator count during this quota period start_time: type: string description: Quota period start time end_time: type: string description: Quota period end time gmv_level_rule: type: array items: $ref: "#/components/schemas/GetWeeklyCreatorOutreachQuotaResponseDataDataGmvLevelRule" description: Quota GMV level rules quota_details: type: array items: $ref: "#/components/schemas/GetWeeklyCreatorOutreachQuotaResponseDataDataQuotaDetail" description: Creator-level quota detail information bonus_exposure_post_percentile_threshold: type: string description: Threshold for exposure posts percentile for shops to obtain additional reward of creator-level quota, 0.8 means the 80th percentile. GetWeeklyCreatorOutreachQuotaResponseDataDataGmvLevelRule: type: object properties: reached_max_follower_cnt: type: string description: Maximum follower count for creators the shop can reach under this GMV tier. gmv_tier: type: string description: GMV tier id left_gmv: $ref: "#/components/schemas/GetWeeklyCreatorOutreachQuotaResponseDataDataGmvLevelRuleLeftGmv" description: Rule gmv left bound right_gmv: $ref: "#/components/schemas/GetWeeklyCreatorOutreachQuotaResponseDataDataGmvLevelRuleRightGmv" description: Rule gmv right bound quota_details: type: array items: $ref: "#/components/schemas/GetWeeklyCreatorOutreachQuotaResponseDataDataGmvLevelRuleQuotaDetail" description: Creator-level quota detail rules GetWeeklyCreatorOutreachQuotaResponseDataDataGmvLevelRuleLeftGmv: type: object properties: amount: type: string description: GMV amount currency: type: string description: GMV currency GetWeeklyCreatorOutreachQuotaResponseDataDataGmvLevelRuleQuotaDetail: type: object properties: creator_levels: type: array items: type: integer format: int64 description: Creator tiers covered in the current quota tiering quota_period_sum: type: integer format: int64 description: Period quota num in the current quota tiering quota_bonus_sum: type: integer format: int64 description: Bonus quota num in the current quota tiering, if the seller meet the exposure posts percentile threshold, will gain quota bonus GetWeeklyCreatorOutreachQuotaResponseDataDataGmvLevelRuleRightGmv: type: object properties: amount: type: string description: GMV amount currency: type: string description: GMV currency GetWeeklyCreatorOutreachQuotaResponseDataDataQuotaDetail: type: object properties: creator_levels: type: array items: type: integer format: int64 description: Creator tiers covered in the current quota tiering quota_period_sum: type: integer format: int64 description: Period quota num in the current quota tiering quota_period_use: type: integer format: int64 description: Period quota use in the current quota tiering quota_bonus_sum: type: integer format: int64 description: Bonus quota num in the current quota tiering, if the seller meet the exposure posts percentile threshold, will gain quota bonus quota_bonus_use: type: integer format: int64 description: Bonus quota use in the current quota tiering, bonus will be consume first. GetWeeklyCreatorOutreachRecordsRequest: type: object properties: page_index: type: integer format: int64 description: Page index, need > 0 page_size: type: integer format: int64 description: Page size, need > 1 and < =50 required: - page_index - page_size GetWeeklyCreatorOutreachRecordsResponse: 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/GetWeeklyCreatorOutreachRecordsResponseData" GetWeeklyCreatorOutreachRecordsResponseData: type: object properties: data: $ref: "#/components/schemas/GetWeeklyCreatorOutreachRecordsResponseDataData" description: Creator outreach records and the total number of matching records. GetWeeklyCreatorOutreachRecordsResponseDataData: type: object properties: total: type: integer format: int64 description: Total number of records matching the query before pagination. connect_list: type: array items: $ref: "#/components/schemas/GetWeeklyCreatorOutreachRecordsResponseDataDataConnectList" description: Return the list of newly connected creator records for the shop GetWeeklyCreatorOutreachRecordsResponseDataDataConnectList: type: object properties: id: type: string description: Record ID creator_open_id: type: string description: Creator open id has_sent_im_message: type: boolean description: Has send im message to creator has_sent_invitation: type: boolean description: Has send invitation to creator is_paired: type: boolean description: Is shop creator paired GiftDetail: type: object properties: product_id: type: string description: TikTok Shop product id of gift. sku_id: type: string description: TikTok Shop sku id of gift. total_claim_limit: type: string description: The total claim limit for the gift SKU in this activity. Enter an integer from `1` to `99999`. required: - product_id - sku_id - total_claim_limit GiftDiscount: type: object properties: gift_receiving_type: type: string description: |- The receiving type of gift. Currently only one type is supported: - `ALL_RECEIVE`: All gifts configured in the promotion can be collected. gift_infos: type: array items: $ref: "#/components/schemas/GiftInfo" description: Gift With Purchase tier configurations. Provide at least one tier. A maximum of two tiers is permitted in SEA and the UK, while only one tier is permitted in the US. `threshold_type` must be the same across all tiers. required: - gift_receiving_type - gift_infos GiftInfo: type: object properties: tier: type: integer format: int64 description: |- `tier` uses 1-based indexing, i.e. the first and second tiers are counted "1, 2", not "0, 1". `threshold_value` for a given tier must be greater than that of the previous tier. E.g. If `tier`==1 has `threshold_value`==`2`, `tier`==2 must have `threshold_value` > `2`. threshold_type: type: string enum: - MINIMAL_ITEM_QUANTITY - MINIMAL_ORDER_AMOUNT x-enum-descriptions: - Buyer must meet or exceed the minimum spend criteria with eligible products. - Buyer must meet or exceed the minimum spend criteria with eligible order. description: |- The purchase threshold type of discount. Possible enumerations are: - `MINIMAL_ITEM_QUANTITY`: Buyer must meet or exceed the minimum spend criteria with eligible products. - `MINIMAL_ORDER_AMOUNT`: Buyer must meet or exceed the minimum spend criteria with eligible order. threshold_value: type: string description: |- The purchase threshold for the gift, determined by `threshold_type`. - When `threshold_type==MINIMAL_ITEM_QUANTITY`, enter a positive integer number of eligible products. - When `threshold_type==MINIMAL_ORDER_AMOUNT`, enter a positive eligible-product subtotal in local currency, with at most two decimal places. gift_details: type: array items: $ref: "#/components/schemas/GiftDetail" description: The gift SKUs for this tier. Across all tiers, provide at least one gift SKU in total, and do not repeat the same sku_id anywhere in the activity. For a MINIMAL_ITEM_QUANTITY tier, this list must not be empty. required: - tier - threshold_type - threshold_value - gift_details GlobalListingMethodChangeWebhook: type: object properties: type: type: integer const: 52 description: The ID of the webhook type. tts_notification_id: type: string description: The ID of this webhook notification. timestamp: type: integer format: int64 description: The time when this webhook is triggered. Unix timestamp. seller_open_id: type: string description: The open_id of the seller. For more information, refer to [Authorization overview](https://partner.tiktokshop.com/docv2/page/authorization-overview-202407). data: $ref: "#/components/schemas/GlobalListingMethodChangeWebhookData" required: - type GlobalListingMethodChangeWebhookData: type: object properties: global_product_id: type: string description: The global product ID associated with the local product. local_product_id: type: array items: type: string description: The local product ID. listing_method: type: string enum: - GLOBAL_PUBLISHING - LOCAL_REPLICATION x-enum-descriptions: - Create a global product, then publish it to target local markets. - Create local product, then replicate it to other target local markets. description: |- The listing method applicable to the local product. Possible values: * GLOBAL_PUBLISHING: Create a global product, then publish it to target local markets. * LOCAL_REPLICATION: Create local product, then replicate it to other target local markets. GlobalReplicationStatusChangeWebhook: type: object properties: type: type: integer const: 51 description: The ID of the webhook type. tts_notification_id: type: string description: The ID of this webhook notification. shop_id: type: string description: The shop ID. timestamp: type: integer format: int64 description: The time when this webhook is triggered. Unix timestamp. data: $ref: "#/components/schemas/GlobalReplicationStatusChangeWebhookData" required: - type GlobalReplicationStatusChangeWebhookData: type: object properties: source_product_id: type: string description: The ID of the product that's being replicated to other markets. replicated_product: $ref: "#/components/schemas/GlobalReplicationStatusChangeWebhookDataReplicatedProduct" description: The product that was replicated from the source product. GlobalReplicationStatusChangeWebhookDataReplicatedProduct: type: object properties: product_id: type: string description: |- The ID of the product created through replication. Pass this ID to the [GET Product](https://partner.tiktokshop.com/docv2/page/get-product-202309) endpoint for more details about the product. region: type: string description: The market where the product has been replicated. result: type: string enum: - SUCCESS - DRAFT - FAILED x-enum-descriptions: - The product was successfully replicated to the local shop, submitted for listing, and is now under review. - The product was successfully replicated to the local shop but saved as a draft local product due to validation errors. You need to call [GET Product](https://partner.tiktokshop.com/docv2/page/get-product-202309) to obtain the original submitted data, pass that data to [POST Check Product Listing](https://partner.tiktokshop.com/docv2/page/check-product-listing-202309) to identify the errors, then call [PUT Edit Product](https://partner.tiktokshop.com/docv2/page/edit-product-202309) to rectify the errors and send for review. - Replication of the product to the local shop was unsuccessful. description: |- The result of replicating the product. Possible values: * SUCCESS: The product was successfully replicated to the local shop, submitted for listing, and is now under review. * DRAFT: The product was successfully replicated to the local shop but saved as a draft local product due to validation errors. You need to call [GET Product](https://partner.tiktokshop.com/docv2/page/get-product-202309) to obtain the original submitted data, pass that data to [POST Check Product Listing](https://partner.tiktokshop.com/docv2/page/check-product-listing-202309) to identify the errors, then call [PUT Edit Product](https://partner.tiktokshop.com/docv2/page/edit-product-202309) to rectify the errors and send for review. * FAILED: Replication of the product to the local shop was unsuccessful. fail_reasons: type: array items: $ref: "#/components/schemas/GlobalReplicationStatusChangeWebhookDataReplicatedProductFailReason" description: The list of reasons for why the replication failed. GlobalReplicationStatusChangeWebhookDataReplicatedProductFailReason: type: object properties: message: type: string description: The reason for why the replication failed. GlobalSku: type: object properties: id: type: string description: The global SKU ID generated by TikTok Shop. One product can contain multiple SKU IDs. seller_sku: type: string description: An internal code/name for managing SKUs, not visible to buyers. sales_attributes: type: array items: $ref: "#/components/schemas/SalesAttribute" description: A list of attributes (e.g. size, color, length) that define each variant of a product. external_global_sku_id: type: string maxLength: 999 description: |- An external identifier used in an external ecommerce platform. This is used to associate the global SKU between TikTok Shop and the external ecommerce platform. Max length: 999 characters Gmv: 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). GmvRange: type: object properties: currency: type: string description: The currency code. minimum_amount: type: string description: The lowest GMV value. maximum_amount: type: string description: The highest GMV value. formatted_range: type: string description: The formatted range of GMV values associated with this creator. GoodsMatchWebhook: type: object properties: type: type: integer const: 23 description: The ID of the webhook type. tts_notification_id: type: string description: The ID of this webhook notification. seller_open_id: type: string description: The open_id of the seller. For more information, refer to [Authorization overview](authorization-overview-202407). timestamp: type: integer format: int64 description: The time when this webhook is triggered. Unix timestamp. data: $ref: "#/components/schemas/GoodsMatchWebhookData" required: - type GoodsMatchWebhookData: type: object properties: match_type: type: string enum: - MATCH - UNMATCH description: "Indicates whether the seller is matching or unmatching products. Possible enumerations are: `MATCH` and `UNMATCH`." product_type: type: string enum: - LOCAL - GLOBAL description: "Possible enumerations are: `LOCAL` and `GLOBAL`." goods_id: type: string description: FBT Goods ID. product_id: type: string description: TikTok Shop product ID. sku_id: type: string description: TikTok Shop SKU ID. update_time: type: integer format: int64 description: The time when the action occurred. Unix timestamp. GoodsSafetyAttribute: type: object properties: is_fragile: type: boolean description: where fragile is_liquid: type: boolean description: Whether the goods are liquid. is_sharp: type: boolean description: where sharp Gpm: type: object properties: amount: type: string description: GPM amount in the corresponding currency. currency: type: string description: GPM 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). HandlingDuration: type: object properties: days: type: string description: The number of days. type: type: string enum: - CALENDAR_DAY - BUSINESS_DAY x-enum-descriptions: - Represents consecutive days, including weekends and holidays. - Represents business days, excluding weekends and public holidays. description: |- Indicates if the duration is calculated in calendar days or business days. Possible values: - `CALENDAR_DAY`: Represents consecutive days, including weekends and holidays. - `BUSINESS_DAY`: Represents business days, excluding weekends and public holidays. Default: `BUSINESS_DAY` HazmatInfo: type: object properties: hazmat_type: type: string enum: - MAGNETIZED - BATTERY - FLAMMABLE_LIQUID - AEROSOLS description: |- hazardous goods type Possible values: -MAGNETIZED -BATTERY -FLAMMABLE_LIQUID -AEROSOLS battery_extra_info: $ref: "#/components/schemas/BatteryExtraInfo" description: Battery details for goods with hazmat_type set to BATTERY. total_battery_weight must be greater than 0. When battery_packaging_type is STANDALONE, battery_count_per_package must be greater than 0. When is_need_un_38_3_test is true, provide un_38_3_test_file_url. flammable_liquids_extra_info: $ref: "#/components/schemas/FlammableLiquidsExtraInfo" description: Flammable-liquid details for goods with hazmat_type set to FLAMMABLE_LIQUID. flammable_liquids_volume must be a numeric string greater than 0. dg_class: type: string enum: - CLASS_2 - CLASS_3 - CLASS_9 description: |- Hazmat class Possible values: -CLASS_2 -CLASS_3 -CLASS_9 dg_uncode: type: string enum: - UN2807 - UN3480 - UN3090 - UN3481 - UN3091 - UN1263 - UN1266 - UN3065 - OTHER description: |- UN identifier for the hazardous substance. Standard UN values use the `UN` prefix followed by four digits; `OTHER` is also supported. Possible values: - UN2807 - UN3480 - UN3090 - UN3481 - UN3091 - UN1263 - UN1266 - UN3065 - OTHER msds_file_url: type: string description: Material safety data sheet of the hazmat goods to support review the goods' safety compliance in FBT aerosol_extra_info: $ref: "#/components/schemas/AerosolExtraInfo" description: Aerosol info required: - hazmat_type - dg_class - dg_uncode - msds_file_url Header: type: object properties: id: type: string description: |- Standard size-system or measurement ID. For standard measurement columns, call Get Category Rules for the corresponding category and use the ID from measurement_and_options[].options[].id under the applicable measurement_type. For size-system columns, use the following predefined IDs: - Size: size_chart_size_system_size - US: size_chart_size_system_us - UK: size_chart_size_system_uk - EU: size_chart_size_system_eu - JP: size_chart_size_system_jp - MX: size_chart_size_system_mx Omit this field for custom columns. name: type: string maxLength: 32 description: "Header display name. Maximum length: 32 characters." required: - name IdentifierCode: type: object properties: code: type: string description: |- The identifier code. **Format**: - GTIN: 14 digits - EAN: 8, 13, or 14 digits - UPC: 12 digits - ISBN: 13 digits, or 9 digits ending in capital `X` - JAN: 8 or 13 digits **Note**: The identifier code must be unique for each SKU, with no repetition allowed. type: type: string enum: - GTIN - EAN - UPC - ISBN - JAN description: |- The type of identifier code. Possible values: - GTIN - EAN - UPC - ISBN - JAN Image: type: object properties: uri: type: string description: |- The URI of the image. Obtain this URI by uploading the images through the [Upload Product Image API](6509df95defece02be598a22) with `use_case=CERTIFICATION_IMAGE`. required: - uri ImageTranslationCompletedWebhook: type: object properties: type: type: integer const: 46 description: The ID of the webhook type. tts_notification_id: type: string description: The ID of this webhook notification. shop_id: type: string description: The shop ID. timestamp: type: integer format: int64 description: The time when this webhook is triggered. Unix timestamp. data: $ref: "#/components/schemas/ImageTranslationCompletedWebhookData" required: - type ImageTranslationCompletedWebhookData: type: object properties: translation_task: $ref: "#/components/schemas/ImageTranslationCompletedWebhookDataTranslationTask" description: The image translation task and the corresponding results. Each task corresponds to the translation of 1 image into 1 target language. ImageTranslationCompletedWebhookDataTranslationTask: type: object properties: id: type: string description: The ID to identify the image translation task. status: type: string enum: - PROCESSING - COMPLETED - FAILED x-enum-descriptions: - Translation is underway and has not yet completed. - Translation has completed and results are ready. - Translation did not complete due to an error. description: |- The translation status. Possible values: - PROCESSING: Translation is underway and has not yet completed. - COMPLETED: Translation has completed and results are ready. - FAILED: Translation did not complete due to an error. fail_reason: type: string description: The reason why the translation task failed. target_language: type: string enum: - de-DE - en-IE - es-ES - fr-FR - it-IT description: |- The target language to translate the image into. Possible values: - de-DE - en-IE - es-ES - fr-FR - it-IT original_image: $ref: "#/components/schemas/ImageTranslationCompletedWebhookDataTranslationTaskOriginalImage" description: The original image to be translated. translated_image: $ref: "#/components/schemas/ImageTranslationCompletedWebhookDataTranslationTaskTranslatedImage" description: The translated image. ImageTranslationCompletedWebhookDataTranslationTaskOriginalImage: type: object properties: uri: type: string description: The URI of the original image. url: type: string description: The URL of the original image. ImageTranslationCompletedWebhookDataTranslationTaskTranslatedImage: type: object properties: uri: type: string description: The URI of the translated image. url: type: string description: The URL of the translated image. InboundFBTOrderStatusChangeWebhook: type: object properties: type: type: integer const: 21 description: The ID of the webhook type. tts_notification_id: type: string description: The ID of this webhook notification. seller_open_id: type: string description: The open_id of the seller. For more information, refer to [Authorization overview](authorization-overview-202407). timestamp: type: integer format: int64 description: The time when this webhook is triggered. Unix timestamp. data: $ref: "#/components/schemas/InboundFBTOrderStatusChangeWebhookData" required: - type InboundFBTOrderStatusChangeWebhookData: type: object properties: inbound_order_id: type: string description: FBT inbound order ID. order_status: type: string enum: - TO_BE_RECEIVED - ARRIVE_HUB - RECEIVING - PARTIALLY_RECEIVED - RECEIVED - CANCELLED description: |- Inbound order status. Possible enumerations: - TO_BE_RECEIVED - ARRIVE_HUB, - RECEIVING, - PARTIALLY_RECEIVED, - RECEIVED, - CANCELLED update_time: type: integer format: int64 description: The time when the change occurred. Unix timestamp. IndirectGmv: 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). Inventory: type: object properties: warehouse_id: type: string description: |- The ID of the warehouse where the SKU is stored. Retrieve the list of warehouses available for your shop from the [Get Warehouse List API](https://partner.tiktokshop.com/docv2/page/650aa418defece02be6e66b6). quantity: type: integer format: int64 minimum: 1 maximum: 99999 description: |- The total SKU quantity available in the warehouse. Valid range: [1, 99,999] Note: This quantity specifically refers to the in-stock inventory that can be shipped immediately. backorder_quantity: type: integer format: int64 description: |- The `backorder_quantity` will automatically be converted to `quantity` once in-stock inventory is sold out. The fulfillment of this inventory follows the `handling_time` specified below. **Note**: - For non-virtual product categories, provide `backorder_quantity` and `handling_time` together. - Made-to-order (MTO), pre-order, and custom products cannot be backordered and are incompatible with `backorder_quantity`. handling_time: type: integer format: int64 description: The estimated number of working days needed for a backorder to be shipped. For non-virtual product categories, provide `handling_time` and `backorder_quantity` together. All warehouses for the same SKU must use the same `handling_time`. required: - warehouse_id InventoryChangedByShopWebhook: type: object properties: type: type: integer const: 71 description: The ID of the webhook type. tts_notification_id: type: string description: The notification ID. shop_id: type: string description: The shop ID. timestamp: type: integer format: int64 description: The time when the webhook is triggered, expressed as a Unix timestamp. data: $ref: "#/components/schemas/InventoryChangedByShopWebhookData" description: The inventory change event data. required: - type - tts_notification_id - shop_id - timestamp - data InventoryChangedByShopWebhookData: type: object properties: event_id: type: string description: An identifier for the inventory event; use it to deduplicate events. occurred_at: type: string format: date-time description: The event time in UTC, formatted as ISO 8601. shop_id: type: integer format: int64 description: The ID of the shop whose inventory changed. product_id: type: integer format: int64 description: The ID of the affected product. sku_id: type: integer format: int64 description: The ID of the affected SKU. quantity_snapshot_after_change: $ref: "#/components/schemas/InventoryChangedByShopWebhookDataQuantitySnapshotAfterChange" description: The SKU inventory quantities after the change. change_detail: type: array items: $ref: "#/components/schemas/InventoryChangedByShopWebhookDataChangeDetail" description: The individual inventory changes associated with the event. required: - event_id - occurred_at - shop_id - product_id - sku_id - quantity_snapshot_after_change - change_detail InventoryChangedByShopWebhookDataChangeDetail: type: object properties: idempotency_key: type: string description: An identifier for an individual change; use it to deduplicate change details. trigger_source: type: string description: The cause of the change. See the trigger sources in Section 1. occurred_at: type: string format: date-time description: The UTC time of the individual change. total_quantity_delta: type: integer format: int64 description: The change in `total_quantity`. available_quantity_delta: type: integer format: int64 description: The change in `total_available_quantity`. committed_quantity_delta: type: integer format: int64 description: The change in `total_committed_quantity`. in_shop_quantity_delta: type: integer format: int64 description: The change in `in_shop_quantity`. campaign_locked_quantity_delta: type: integer format: int64 description: The change in `campaign_locked_quantity`. creator_locked_quantity_delta: type: integer format: int64 description: The change in `creator_locked_quantity`. required: - idempotency_key - trigger_source - occurred_at - total_quantity_delta - available_quantity_delta - committed_quantity_delta - in_shop_quantity_delta - campaign_locked_quantity_delta - creator_locked_quantity_delta InventoryChangedByShopWebhookDataQuantitySnapshotAfterChange: type: object properties: total_quantity: type: integer format: int64 description: "Total inventory: `total_available_quantity + total_committed_quantity`." total_available_quantity: type: integer format: int64 description: Available inventory, including quantities reserved for campaigns and creator collaborations. total_committed_quantity: type: integer format: int64 description: Inventory committed to orders that have not yet shipped. in_shop_quantity: type: integer format: int64 description: "Available shop inventory: `total_available_quantity - campaign_locked_quantity - creator_locked_quantity`." campaign_locked_quantity: type: integer format: int64 description: Inventory reserved for marketing campaigns. creator_locked_quantity: type: integer format: int64 description: Inventory reserved for creator collaborations. required: - total_quantity - total_available_quantity - total_committed_quantity - in_shop_quantity - campaign_locked_quantity - creator_locked_quantity InventorySearchRequest: type: object properties: product_ids: type: array items: type: string description: |- A list of product IDs used to search for inventory information. Max IDs: 100 sku_ids: type: array items: type: string description: |- A list of SKU IDs used to search for inventory information. Max IDs: 600 **Note**: If both `sku_ids` and `product_ids` are passed, `sku_ids` will take precedence. InventorySearchResponse: 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/InventorySearchResponseData" InventorySearchResponseData: type: object properties: inventory: type: array items: $ref: "#/components/schemas/InventorySearchResponseDataInventory" description: Inventory information for the requested products or SKUs. InventorySearchResponseDataInventory: type: object properties: product_id: type: string description: The ID of the requested product. skus: type: array items: $ref: "#/components/schemas/InventorySearchResponseDataInventorySku" description: The list of requested SKUs. InventorySearchResponseDataInventorySku: type: object properties: id: type: string description: The SKU ID generated by TikTok Shop. seller_sku: type: string description: An internal code/name for managing SKUs, not visible to buyers. total_available_quantity: type: integer format: int64 description: |- The total number of units available for ordering across all warehouses. It is the sum of the `warehouse_inventory.available_quantity` values in all warehouses. total_committed_quantity: type: integer format: int64 description: |- The total number of units reserved by existing customer orders across all warehouses (and therefore not available for ordering). It is the sum of the `warehouse_inventory.committed_quantity` values in all warehouses. warehouse_inventory: type: array items: $ref: "#/components/schemas/InventorySearchResponseDataInventorySkuWarehouseInventory" description: SKU warehouse inventory information. total_available_inventory_distribution: $ref: "#/components/schemas/InventorySearchResponseDataInventorySkuTotalAvailableInventoryDistribution" description: The distribution of the total available inventory for the SKU across different channels. InventorySearchResponseDataInventorySkuTotalAvailableInventoryDistribution: type: object properties: campaign_inventory: type: array items: $ref: "#/components/schemas/InventorySearchResponseDataInventorySkuTotalAvailableInventoryDistributionCampaignInventory" description: Inventory that is allocated to a specific campaign. creator_inventory: type: array items: $ref: "#/components/schemas/InventorySearchResponseDataInventorySkuTotalAvailableInventoryDistributionCreatorInventory" description: Inventory that is allocated to TikTok creators. in_shop_inventory: $ref: "#/components/schemas/InventorySearchResponseDataInventorySkuTotalAvailableInventoryDistributionInShopInventory" description: The remaining inventory available for the shop after deducting those allocated for campaigns and creators. InventorySearchResponseDataInventorySkuTotalAvailableInventoryDistributionCampaignInventory: type: object properties: quantity: type: integer format: int64 description: The number of units allocated. campaign_name: type: string description: The name of the associated campaign. InventorySearchResponseDataInventorySkuTotalAvailableInventoryDistributionCreatorInventory: type: object properties: quantity: type: integer format: int64 description: The number of units allocated. creator_name: type: string description: The name of the associated TikTok creator. InventorySearchResponseDataInventorySkuTotalAvailableInventoryDistributionInShopInventory: type: object properties: quantity: type: integer format: int64 description: The number of units allocated. InventorySearchResponseDataInventorySkuWarehouseInventory: type: object properties: warehouse_id: type: string description: |- The ID of the warehouse where the SKU is stored. Retrieve details of the warehouse from the [Get Warehouse List API](https://partner.tiktokshop.com/docv2/page/650aa418defece02be6e66b6). available_quantity: type: integer format: int64 description: |- The total number of units available for ordering in this warehouse. This is equivalent to the `inventory.quantity` value returned in the [Get Product API](https://partner.tiktokshop.com/docv2/page/6509d85b4a0bb702c057fdda). committed_quantity: type: integer format: int64 description: The total number of units reserved by existing customer orders in this warehouse (and therefore not available for ordering). InventoryStatusChangeWebhook: type: object properties: type: type: integer const: 27 description: The ID of the webhook type. tts_notification_id: type: string description: The ID of this webhook notification. shop_id: type: string description: The shop ID. timestamp: type: integer format: int64 description: The time when this webhook is triggered. Unix timestamp. data: $ref: "#/components/schemas/InventoryStatusChangeWebhookData" required: - type InventoryStatusChangeWebhookData: type: object properties: product_id: type: string description: The ID of the product. sku_id: type: string description: The ID of the SKU. trigger_reason: $ref: "#/components/schemas/InventoryStatusChangeWebhookDataTriggerReason" current_inventory_status: type: string description: |- SUFFICIENT_STOCK: defined as having enough stocks. LOW_STOCK: defined as available stock ≤ stock alert value OUT_OF_STOCK: defined as having 0 available stock. inventory_distribution: $ref: "#/components/schemas/InventoryStatusChangeWebhookDataInventoryDistribution" update_time: type: integer format: int64 description: The time when the status changed, represented as a Unix timestamp (seconds). InventoryStatusChangeWebhookDataInventoryDistribution: type: object properties: total_quantity: type: integer format: int64 description: The total quantity of the stock physically in the warehouses. `total_quantity`=`available_quantity` + `creator_reserved_quantity` + `campaign_reserved_quantity` + `committed_quantity`. available_quantity: type: integer format: int64 description: The total number of SKUs available for ordering in the warehouses. creator_reserved_quantity: type: integer format: int64 description: The total number of SKUs reserved for creators in the warehouses. campaign_reserved_quantity: type: integer format: int64 description: The total number of SKUs reserved for campaigns in the warehouses. committed_quantity: type: integer format: int64 description: The total number of SKUs reserved by existing customer orders in the warehouses. InventoryStatusChangeWebhookDataTriggerReason: type: object properties: alert_type: type: string description: |- PREDICTION: TikTok Shop predicts the inventory will go out of stock in X days REALTIME: The inventory has reached LOW_STOCK or OUT_OF_STOCK lead_days: type: integer format: int64 description: |- When `alert_type == PREDICTION`, the value is the time slot between `update_time` and the predicted out-of-stock date. When `alert_type == REALTIME`, the parameter is not returned. low_stock_threshold: type: integer format: int64 description: |- When `alert_type == REALTIME`, the value is the low stock threshold met. When `alert_type == PREDICTION`, the parameter is not returned. InvoiceStatusChangeWebhook: type: object properties: shop_id: type: string description: The TikTok Shop ID. type: type: integer const: 36 description: The ID of the webhook type. tts_notification_id: type: string description: The ID of this webhook notification. timestamp: type: integer format: int64 description: The time when this webhook is triggered. Unix timestamp. data: $ref: "#/components/schemas/InvoiceStatusChangeWebhookData" required: - type InvoiceStatusChangeWebhookData: type: object properties: package_id: type: string description: The ID of the package. order_ids: type: array items: type: string description: List of order IDs in the corresponding `package_id`. invoice_status: type: string enum: - SUCCESS - PROCESSING - FAILED - INVALID description: |- The status of the invoice upload. Possible values: * `SUCCESS` * `PROCESSING` * `FAILED` * `INVALID` invalid_reason: type: string enum: - UNKNOWN - FAILED - NOT_FOUND - NOT_AUTHORIZED - ACCESS_KEY_DUPLICATE - CNPJ_NOT_MATCH - UF_Inconsistent_Required - UF_Inconsistent_Dismisse_Retirada_missing - UF_Inconsistent_Dismissed_Retirada_Inconsistent x-enum-descriptions: - Internal system error. Please try again later. - The NFe file or access key is invalid. Please check the XML file for correctness. - The NFe was not found. This may be due to data delay. Please try again later. - The NFe is not legally authorized. It may not have been issued or has been canceled. - The access key already exists. You cannot upload an invoice with duplicate access key. - Ensure the NF-e has the same 8-digit prefix as the CNPJ you provided during onboarding. - "NF-e validation failed: The CNPJ used to issue the NF-e is registered in a different state from your warehouse." - "NF-e validation failed: The CNPJ used to issue the NF-e is registered in a different state from your warehouse. To issue a valid NF-e with this CNPJ, include warehouse information (Pickup Location Identification) in your NF-e." - The CNPJ used to issue the NF-e is registered in a different state from your warehouse. To issue a valid NF-e with this CNPJ, include warehouse information (Pickup Location Identification) in your NF-e. description: |- The reason why `invoice_status = INVALID`. Possible values: * `UNKNOWN`: Internal system error. Please try again later. * `FAILED`: The NFe file or access key is invalid. Please check the XML file for correctness. * `NOT_FOUND`: The NFe was not found. This may be due to data delay. Please try again later. * `NOT_AUTHORIZED`: The NFe is not legally authorized. It may not have been issued or has been canceled. * `ACCESS_KEY_DUPLICATE`: The access key already exists. You cannot upload an invoice with duplicate access key. * `CNPJ_NOT_MATCH`：Ensure the NF-e has the same 8-digit prefix as the CNPJ you provided during onboarding. * `UF_Inconsistent_Required`: NF-e validation failed: The CNPJ used to issue the NF-e is registered in a different state from your warehouse. * `UF_Inconsistent_Dismisse_Retirada_missing`: NF-e validation failed: The CNPJ used to issue the NF-e is registered in a different state from your warehouse. To issue a valid NF-e with this CNPJ, include warehouse information (Pickup Location Identification) in your NF-e. * `UF_Inconsistent_Dismissed_Retirada_Inconsistent`: The CNPJ used to issue the NF-e is registered in a different state from your warehouse. To issue a valid NF-e with this CNPJ, include warehouse information (Pickup Location Identification) in your NF-e. Item: type: object properties: goods_id: type: string description: The Fulfilled by TikTok goods identifier for this carton item. The goods must belong to the merchant associated with the authenticated seller, be approved for fulfillment, and be matched to an SKU. quantity: type: integer format: int64 description: Quantity of this goods item in each carton. Must be greater than 0. lot_code: type: string description: Lot code for this goods item. Required when lot-code management is enabled for the goods. Every occurrence of the same `goods_id` in `cartons` must use the same `lot_code` and `expiration_timestamp` values. expiration_timestamp: type: string description: The expiration date for this item, as a Unix timestamp in seconds. Required when expiration management is enabled for the goods. It must be no earlier than the current time plus the goods-specific `inbound_cutoff_days`. Obtain this value from `data.goods[].lot_expiration_info.inbound_cutoff_days` in Search Goods Info (`POST /fbt/202607/goods/search`). required: - goods_id - quantity ItemTax: type: object properties: tax_type: type: string enum: - SALES_TAX x-enum-descriptions: - US market sales tax description: |- Tax type. Available values: - `SALES_TAX` (US market sales tax) **Note**: Currently only sales tax is available. tax_amount: type: string description: Tax amount. tax_rate: type: string description: Tax rate. LineItem: type: object properties: return_line_item_id: type: string description: Unique identifier for this item in the return. In the case of virtual bundle, this is corresponds to the id of the original parent item bundle. sub_return_line_item_id: type: string description: Unique identifier for this item in the return. In the case of virtual bundle, this is corresponds to the id of the current child item being returned. sku_id: type: string description: SKU identifier associated with this item (for product details). main_order_id: type: string description: Identifier of the associated main (forward) order. sku_return_request_id: type: string description: Identifier of the associated SKU-level, sub return request. ListAvailableInboundMethodsRequest: type: object properties: plan_id: type: string description: Inbound plan identifier required: - plan_id ListAvailableInboundMethodsResponse: 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/ListAvailableInboundMethodsResponseData" ListAvailableInboundMethodsResponseData: type: object properties: available_inbound_method_list: type: array items: $ref: "#/components/schemas/ListAvailableInboundMethodsResponseDataAvailableInboundMethodList" description: List of available inbound methods for the specified plan, including arrival time windows, placement fee estimates, and warehouses. ListAvailableInboundMethodsResponseDataAvailableInboundMethodList: type: object properties: inbound_method: type: string description: |- Inbound method. - D2FC - ONE_HUB available_time_window_list: type: array items: $ref: "#/components/schemas/ListAvailableInboundMethodsResponseDataAvailableInboundMethodListAvailableTimeWindowList" description: Weekly arrival time windows available for this inbound method. warehouse_list: type: array items: $ref: "#/components/schemas/ListAvailableInboundMethodsResponseDataAvailableInboundMethodListWarehouseList" description: List of warehouses available for this inbound method option. placement_fee_estimate: $ref: "#/components/schemas/ListAvailableInboundMethodsResponseDataAvailableInboundMethodListPlacementFeeEstimate" description: Estimated placement fee for this inbound method. As of April 2026, only ONE_HUB methods can include an amount. ListAvailableInboundMethodsResponseDataAvailableInboundMethodListAvailableTimeWindowList: type: object properties: start_timestamp: type: string description: |- Epoch seconds representing Sunday at midnight like 2026-03-29T07:00:00Z, in US we are using US west time zone **This value should be passed in the subsequent GetInboundMethodDetail API** end_timestamp: type: string description: |- Epoch seconds representing Sunday at midnight like 2026-03-29T07:00:00Z, in US we are using US west time zone **This value should be passed in the subsequent GetInboundMethodDetail API** ListAvailableInboundMethodsResponseDataAvailableInboundMethodListPlacementFeeEstimate: type: object properties: amount: type: string description: Placement fee amount. currency: type: string description: |- - USD - CNY - EUR ListAvailableInboundMethodsResponseDataAvailableInboundMethodListWarehouseList: type: object properties: warehouse_name: type: string description: Warehouse name for this available inbound method option. warehouse_id: type: string description: Warehouse identifier for this available inbound method option. ListOpportunitiesRequest: type: object properties: opportunity_type: type: string enum: - PRODUCT - KEYWORD - CATEGORY x-enum-descriptions: - Product opportunity - Search keyword opportunity - Category opportunity description: |- The type of opportunity. Possible values: - `PRODUCT`: Product opportunity - `KEYWORD`: Search keyword opportunity - `CATEGORY`: Category opportunity category_ids: type: array items: type: string description: Filter by category IDs. Leave empty to return all leads that available to the seller. create_time_ge: type: integer format: int64 description: Filter opportunities created at or after this time. Provide a Unix timestamp in seconds (UTC). create_time_lt: type: integer format: int64 description: Filter opportunities created before this time. timestamp in seconds tag_codes: type: array items: type: string description: A list of tag codes used to filter the results. You can provide at most 20 values. Use lowercase tag codes. The `core_product` and `top_product` tag codes are supported only when `opportunity_type` is `PRODUCT`; their availability also depends on the seller and market configuration. required: - opportunity_type ListOpportunitiesResponse: 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/ListOpportunitiesResponseData" ListOpportunitiesResponseData: type: object properties: data: $ref: "#/components/schemas/ListOpportunitiesResponseDataData" description: Paginated opportunity results. ListOpportunitiesResponseDataData: type: object properties: opportunities: type: array items: $ref: "#/components/schemas/ListOpportunitiesResponseDataDataOpportunity" description: The opportunities returned on the current page. next_page_token: type: string description: Pagination token to pass as `page_token` in the next request. This field is omitted when there are no more results. total_count: type: integer format: int64 description: Total number of matching opportunities (approximate). ListOpportunitiesResponseDataDataOpportunity: type: object properties: id: type: string description: Unique ID of the opportunity title: type: string description: Opportunity title. reference_images: type: array items: type: string description: Reference product images of the product to list. category_id_level_1: type: string description: TikTok Shop L1 category ID. category_id_level_2: type: string description: TikTok Shop L2 category ID. category_id_level_3: type: string description: TikTok Shop L3 category ID. category_name_level_1: type: string description: Category name of 1st level category. category_name_level_2: type: string description: Category name of 2nd level category. category_name_level_3: type: string description: Category name of 3rd level category. is_collected: type: boolean description: Whether the authorized seller has saved this opportunity to their collection. query_words: type: string description: Comma-separated TikTok Shop in-site search keywords associated with the opportunity. opportunity_type: type: string description: |- Type of opportunity: PRODUCT（品线索）/ KEYWORD（词线索）/ CATEGORY（类目线索） Empty return for a specific opportunity type indicates the business team has not enabled merchant submission for this lead type in the corresponding market. brand_name: type: string description: The brand name for products specified by the opportunity. create_time: type: integer format: int64 description: The opportunity creation time as a Unix timestamp in seconds (UTC). expire_time: type: integer format: int64 description: Opportunity expiry date, second-level timestamp est_market_sales_volume: type: string description: "Estimated market sales volume for the last 30 days, returned as an approximate bucket: `<100`, a value rounded down to a hundreds bucket ending in `00+`, a `k+` or `M+` value, or `100M+`." est_market_gmv: type: string description: "Estimated market sales GMV in USD for the last 30 days, returned as an approximate bucket: `<100`, a value rounded down to a hundreds bucket ending in `00+`, a `k+` or `M+` value, or `100M+`." search_volume: type: string description: TikTok Shop in-site search volume, rounded to the nearest whole number and returned as a decimal string. competitor_product_count: type: string description: Approximate number of competing products listed in the last 30 days, returned as one of `< 10`, `< 50`, `< 100`, or `100+`. video_view_pv: type: string description: The cumulative short video view count of all videos associated with this product opportunity. tags: type: string description: Comma-separated display values for the opportunity tags. Each value is localized when a translation is available; otherwise, the configured tag description or tag code is returned. tag_codes: type: array items: type: string description: Tag codes for the opportunity. The available codes depend on seller and market configuration. Examples for Latam include `core_product` and `top_product`. reward_info: type: string description: Comma-separated descriptions of rewards that sellers can gain by listing products as required. Values are localized when a translation is available; otherwise, the configured reward description is returned. external_product_id: type: string description: Product ID on the reference source. reference_source: type: string enum: - "1" - "2" - "3" - "4" - "5" - "6" - "7" - "8" - "9" - "10" - "11" - "12" - "13" - "14" - "15" - "16" - "17" - "18" - "19" - "20" - "21" - "22" x-enum-descriptions: - SHOPEE - AMAZON - LOOKFANTASTIC - WALMART - TTS - ASOS - UNIVERSAL_PRODUCT - DTCNEXUS - TEMU - SHOPIFY - NEXUS_SHOPIFY - SHEIN - PIXEL - SHOPIFY_NON_1P - MIRAVIA - RAKUTEN - EBAY - ONBUY - MERCADO_LIBRE - ALLEGRO - BOL - DTC description: |- The reference platform code, returned only when `external_product_id` is present. Possible values: - `1`: SHOPEE - `2`: AMAZON - `3`: LOOKFANTASTIC - `4`: WALMART - `5`: TTS - `6`: ASOS - `7`: UNIVERSAL_PRODUCT - `8`: DTCNEXUS - `9`: TEMU - `10`: SHOPIFY - `11`: NEXUS_SHOPIFY - `12`: SHEIN - `13`: PIXEL - `14`: SHOPIFY_NON_1P - `15`: MIRAVIA - `16`: RAKUTEN - `17`: EBAY - `18`: ONBUY - `19`: MERCADO_LIBRE - `20`: ALLEGRO - `21`: BOL - `22`: DTC ListPrice: type: object properties: amount: type: string description: |- The price amount. Valid range: [0.01, 7600] **Note**: The value must be equal to or greater than `skus.price.amount`. Otherwise, it will be discarded. currency: type: string enum: - USD description: |- The currency. Possible values: USD required: - amount - currency ListProductSKPPStatusesRequest: type: object properties: product_ids: type: array items: type: string maxItems: 100 description: Product IDs generated by Tiktok Shop; up to 100 per call. skpp_status: type: string description: |- Optional filter. Possible values:QUALIFIED (already an SKPP product) / NOT_QUALIFIED (not yet meeting the standard, but eligible to take SKPP tasks). page_size: type: integer format: int64 description: "Number of products returned per page. Range: 1–100. Default: 50." page_no: type: integer format: int64 description: "Page number, starting from 1. Default: 1." ListProductSKPPStatusesResponse: 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/ListProductSKPPStatusesResponseData" ListProductSKPPStatusesResponseData: type: object properties: products: type: array items: $ref: "#/components/schemas/ListProductSKPPStatusesResponseDataProduct" description: Product list, each with its SKPP status.。 total_count: type: integer format: int64 description: Total products matching the filter. update_time: type: integer format: int64 description: Date of the offline data snapshot that total_score and rewards are derived from, returned as a Unix timestamp in seconds, pinned to the last second of that date in UTC (23:59:59Z). The value is date-level only — the time component is always 23:59:59 UTC — because the SKPP scoring runs in an offline pipeline with no intraday granularity. Latency is typically T+1 (the evening of day N publishes the day N−1 snapshot) and at most T+2. ListProductSKPPStatusesResponseDataProduct: type: object properties: product_id: type: string description: Product IDs generated by Tiktok Shop title: type: string description: Product title. skpp_status: type: string description: "Possible values: QUALIFIED / NOT_QUALIFIED" affiliate_program_status: type: string description: "Affiliate Program enrolment status. Possible values: ACTIVE / INACTIVE." total_score: type: integer format: int64 description: Current SKPP total score, as of update_time. target_score: type: integer format: int64 description: Score threshold to qualify for SKPP. rewards: type: array items: $ref: "#/components/schemas/ListProductSKPPStatusesResponseDataProductReward" description: Rewards data. ListProductSKPPStatusesResponseDataProductReward: type: object properties: reward_type: type: string description: "Possible values: ADS_CREDIT / TOP_CREATOR_MATCHMAKING / SHOPTAB_PV." status: type: string description: "Possible values: NOT_GRANTED (below threshold, locked) / PENDING (qualified, not yet granted) / AVAILABLE (granted)." value: type: string description: Granted amount/quantity; present only when status = AVAILABLE. Currency-typed (ADS_CREDIT) leads with the currency symbol (e.g. $15); count-typed (TOP_CREATOR_MATCHMAKING, SHOPTAB_PV) are bare numbers. ad_credit_claim_status: type: string description: "Ad-credit-only sub-status, returned only when reward_type = ADS_CREDIT and status = AVAILABLE. Possible values: UNCLAIMED (eligible, not yet claimed) / CLAIMED (claimed). Ad credit must be claimed manually." ListingQuality: type: object properties: current_tier: type: string enum: - POOR - FAIR - GOOD description: |- The current quality tier of this product listing. The quality tier of a product listing depends on the quality of the content in its product fields such as the title, image, attributes etc. Possible values: - POOR - FAIR - GOOD **NOTE**: Available only for the US market. remaining_recommendations: type: integer format: int64 description: |- The remaining number of recommendations (see `diagnosis_results`) that must be implemented for the product to advance to the highest tier. **Note**: - To advance to the highest tier, you must implement all recommendations listed in `diagnosis_results`. - Available only for the US market. LiveAttributedGmv: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). LiveAuctionAttributedGmv: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). LiveGmv: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). LiveIndirectGmv: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). LocalGmv: type: object properties: amount: type: string description: The amount of GMV currency: type: string description: The ISO 4217 currency code for `amount`. LocalUnitPrice: type: object properties: amount: type: string description: The amount of unit price currency: type: string description: The ISO 4217 currency code for `amount`. MainImage: type: object properties: uri: type: string description: |- The URI of the image. Obtain this URI by uploading the images through the [Upload Product Image API](6509df95defece02be598a22) with `use_case=MAIN_IMAGE`. You can use the returned URI directly, or process it through the [Optimize Images API](665692b35d39dc02deb49a97) first and use the resulting URI. required: - uri Manufacturer: type: object properties: name: type: string description: The name of the manufacturer. address: type: string description: The address of the manufacturer. phone_number: type: string description: |- The phone number of the manufacturer, prefixed by a plus `+` symbol. There must be a space or hyphen between the country code and the local phone number. email: type: string description: The email address of the manufacturer. MapTokopediaToTikTokShopProductIDsRequest: type: object properties: toko_pids: type: array items: type: integer format: int64 description: List of Tokopedia product IDs to map to TikTok Shop product IDs. MapTokopediaToTikTokShopProductIDsResponse: 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/MapTokopediaToTikTokShopProductIDsResponseData" MapTokopediaToTikTokShopProductIDsResponseData: type: object properties: error: $ref: "#/components/schemas/GetTokopediaAndTikTokShopProductIDMappingsResponseDataError" description: Error details returned when the product mapping request fails. product: type: array items: $ref: "#/components/schemas/Product" description: list of product data MarkBuyerMessagesAsReadRequest: type: object properties: {} MarkBuyerMessagesAsReadResponse: 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/MarkBuyerMessagesAsReadResponseData" MarkBuyerMessagesAsReadResponseData: type: object properties: {} MarkConversationsAsReadRequest: type: object properties: conversation_ids: type: array items: type: string description: |- The array of conversations to read. After the API is called, all the messages in the specified conversations will be read, and the read timestamp is set to the time when the API is called. The length of the array must not exceed `20`. required: - conversation_ids MarkConversationsAsReadResponse: 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/MarkConversationsAsReadResponseData" MarkConversationsAsReadResponseData: type: object properties: failed_conversation_ids: type: array items: type: string description: The conversation IDs that could not be marked as read. Retry the request using only these IDs. MarkPackageAsShippedRequest: type: object properties: order_line_list: type: array items: $ref: "#/components/schemas/ConfirmOrderSplitRequestSplittableGroupsV2OrderLineList" description: This new parameter is completely backward compatible with the previous oder_line_items_ids field and in addition this supports bundle order splitting, use the sub items accordingly shipping_info_list: type: array items: $ref: "#/components/schemas/ShippingInfoList" description: |- "Only supports uploading multiple tracking numbers for split-shipment in 3PL single item scenarios (non-virtual bundle) (This function is only support for whitelist sellers； If you are not on the allowlist, it is recommended to contact AM to apply) For other scenarios, only one tracking number can be uploaded at a time." MarkPackageAsShippedResponse: 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/MarkPackageAsShippedResponseData" MarkPackageAsShippedResponseData: type: object properties: order_id: type: string description: TikTok Shop order ID. order_line_item_ids: type: array items: type: string description: List of order line item IDs. package_id: type: string description: Package ID. warning: $ref: "#/components/schemas/Warning" description: Warning message. MaxDiscount: type: object properties: amount: type: string description: Monetary value of the `max_discount`. currency: type: string description: Currency of the `max_discount`. MaxPrice: type: object properties: amount: type: string description: Product amount currency: type: string description: Product currency MetricStandardInfo: type: object properties: id: type: string description: The unique ID of the measurement template. Use this ID to identify which measurement standard template applies to the product. metric_value_module_infos: type: array items: $ref: "#/components/schemas/MetricValueModuleInfo" description: The list of metric value entries under the measurement template. Each object represents the value submitted by the seller for a specific metric in the template. MetricValueModuleInfo: type: object properties: id: type: string description: The unique ID of a metric item within the measurement template. This ID identifies which metric the submitted value belongs to. value: type: string description: The seller-provided value for the specified metric item in the measurement template. unit_id: type: string description: Metric value module unit id. MinPrice: type: object properties: amount: type: string description: Price amout currency: type: string description: Price currency MinSpend: type: object properties: amount: type: string description: Monetary value of the `min_spend`. currency: type: string description: Currency of the `min_spend` threshold. MoveShowcaseProductsToTheTopRequest: type: object properties: product_ids: type: array items: type: string description: The IDs of products that are already in the creator's showcase and should be moved to the top. If you provide multiple product IDs, the products are displayed at the top in the same order as the IDs in this array. required: - product_ids MoveShowcaseProductsToTheTopResponse: 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/MoveShowcaseProductsToTheTopResponseData" MoveShowcaseProductsToTheTopResponseData: type: object properties: code: type: integer format: int64 description: The success or failure status code returned in API response. message: type: string description: The success or failure messages are returned in API response. Reasons of failure will be described in the message. request_id: type: string description: Every request generates a unique request_id for logging purposes. NewConversationWebhook: type: object properties: type: type: integer const: 13 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/NewConversationWebhookData" required: - type NewConversationWebhookData: type: object properties: conversation_id: type: string description: The identification of the conversation create_time: type: integer format: int64 description: Conversation creation time, represented as a Unix timestamp (in seconds). NewMessageListenerWebhook: type: object properties: type: type: integer const: 33 description: The ID of the webhook type. shop_id: type: string description: TikTok shop ID. tts_notification_id: type: string description: ID of the webhook. timestamp: type: integer format: int64 description: The UNIX timestamp when this webhook was triggered. data: $ref: "#/components/schemas/NewMessageListenerWebhookData" required: - type NewMessageListenerWebhookData: type: object properties: index: type: string description: Index of the message in the conversation. A large index number corresponds to newer message. message_id: type: string description: Message ID. conversation_id: type: string description: ID of the conversation to which the message belongs. msg_type: type: string enum: - TEXT - PRODUCT_CARD - TARGET_COLLABORATION_CARD - FREE_SAMPLE_CARD description: |- Message type, with possible values: * TEXT * PRODUCT_CARD * TARGET_COLLABORATION_CARD * FREE_SAMPLE_CARD content: type: string description: |- Message content, in JSON serialized string. * TEXT: {"content": "simple text"} * PRODUCT_CARD: {"product_id": "12345"} * TARGET_INVITATION_CARD: {"invitation_group_id": "1234"} * FREE_SAMPLE_CARD: {"apply_id": "1234"} create_time: type: string description: Message creation time, represented as a Unix timestamp (seconds). sender: $ref: "#/components/schemas/NewMessageListenerWebhookDataSender" NewMessageListenerWebhookDataSender: type: object properties: sender_im_user_id: type: string description: ID in IM system for the sender. NewMessageWebhook: type: object properties: type: type: integer const: 14 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/NewMessageWebhookData" required: - type NewMessageWebhookData: type: object properties: message_id: type: string description: The identification of the message index: type: string description: |- The message index that can be used to sort messages. Newer messages have a larger index. conversation_id: type: string description: The identification of the conversation type: type: string enum: - TEXT - IMAGE - ALLOCATED_SERVICE - NOTIFICATION - BUYER_ENTER_FROM_TRANSFER - BUYER_ENTER_FROM_PRODUCT - BUYER_ENTER_FROM_ORDER - PRODUCT_CARD - ORDER_CARD - EMOTICONS - VIDEO - COUPON_CARD - LOGISTICS_CARD - OTHER description: |- Message type, with possible values: * TEXT * IMAGE * ALLOCATED_SERVICE * NOTIFICATION * BUYER_ENTER_FROM_TRANSFER * BUYER_ENTER_FROM_PRODUCT * BUYER_ENTER_FROM_ORDER * PRODUCT_CARD * ORDER_CARD * EMOTICONS * VIDEO * COUPON_CARD *LOGISTICS_CARD * OTHER content: type: string description: |- Message content, in JSON serialized string. Examples: * TEXT: {"content": "simple text"} * IMAGE: { "height": "290", "url": "https://tosv.boei18n.byted.org/obj/temai-im/FszkJ53nSapYG6KDaJQmqR3jjoZGwww304-290", "width": "304" } * PRODUCT_CARD, BUYER_ENTER_FROM_PRODUCT: {"product_id": "12345"} * ORDER_CARD, BUYER_ENTER_FROM_ORDER : {"order_id": "12345"} * VIDEO: { "url": "https://video-boei18n.byted.org/storage/v1/tos-boei18n-v-c72c01/e8240f35244646428df9c3244d1a7408?x-tos-algorithm=v2&x-tos-authkey=5bf25627da095a5cba28ace592de46cc&x-tos-expires=1681980481&x-tos-signature=r_bRxtrvGhXAuZgMmNhlZ_Upqzg", "cover": "https://p-boei18n.byted.org/tos-boei18n-v-c72c01/o8keEOhzTcNCcJyAbkWZwpLIyTfkJxcGbRBvLP~tplv-jvtte31kaf-origin-jpeg.jpeg?", "width": 640, "height": 360, "duration": "20.504", "vid": "v0e30cg700f7cgcmu8jc77u9e2bdp95g", "expire_time": "1681980481", "format": "mp4", "size": 400000, "bit_rate": 156067, "quality": "original", "codec_type": "h264" } * LOGISTICS_CARD: { "order_id": "580874485811283206", "package_id": "123456" // Optional (recommended for one order with multiple packages; not required for one order with one package) } * COUPON_CARD: {"coupon_id": "7262992004278206762"} Note: Use Get Coupon for the details of the coupon. * ALLOCATED_SERVICE, NOTIFICATION, BUYER_ENTER_FROM_TRANSFER, OTHER: {"content": "simple text"} create_time: type: integer format: int64 description: Message creation time, represented as a Unix timestamp (seconds). is_visible: type: boolean description: Whether this message should be displayed to customer service. sender: $ref: "#/components/schemas/NewMessageWebhookDataSender" description: |- The message sender. For system and robot roles, the shop is the sender. NewMessageWebhookDataSender: type: object properties: im_user_id: type: string description: |- Sender's ID These are IM IDs, and can not be used to query orders. role: type: string enum: - BUYER - SHOP - CUSTOMER_SERVICE - SYSTEM - ROBOT description: |- Sender's role, with possible values: * BUYER * SHOP * CUSTOMER_SERVICE * SYSTEM * ROBOT OpportunityMatchingStatusChangeWebhook: type: object properties: type: type: integer const: 25 description: The ID of the webhook type. tts_notification_id: type: string description: The ID of this webhook notification. shop_id: type: string description: The shop ID. timestamp: type: integer format: int64 description: The time when this webhook is triggered. Unix timestamp. data: $ref: "#/components/schemas/OpportunityMatchingStatusChangeWebhookData" required: - type OpportunityMatchingStatusChangeWebhookData: type: object properties: external_product_id: type: string description: An external product identifier used in the external ecommerce platform. opportunity_matching_status: type: string enum: - PENDING - MATCHED - NOT_MATCHED x-enum-descriptions: - Waiting for opportunity matching. - There are one or more matched opportunities. - There are no matches. description: |- The status of opportunity matching. Possible values: - `PENDING`: Waiting for opportunity matching. - `MATCHED`: There are one or more matched opportunities. - `NOT_MATCHED`: There are no matches. opportunity_ids: type: array items: type: string description: A list of IDs for the matched opportunities. opportunity_matching_end_time: type: integer format: int64 description: |- The time by which the system will stop matching opportunities for this candidate product. Unix timestamp. - Default: 60 days from the upload time. - Latest allowable time: 60 days from the upload time. update_time: type: integer format: int64 description: The time when the opportunity matching status is last updated. Unix timestamp. OptimizeImagesRequest: type: object properties: images: type: array items: $ref: "#/components/schemas/OptimizeImagesRequestImage" maxItems: 200 description: |- The list of images to be optimized. Use the [Upload Product Image API](https://partner.tiktokshop.com/docv2/page/6509df95defece02be598a22) to upload the images first and obtain the corresponding image URIs. Max count: 200 OptimizeImagesRequestImage: type: object properties: uri: type: string description: |- The URI of the image. Retrieve the URI from the [Upload Product Image API](https://partner.tiktokshop.com/docv2/page/6509df95defece02be598a22). optimization_mode: type: array items: type: string enum: - WHITE_BACKGROUND x-enum-descriptions: - Change the background to white. description: |- The optimization type. Possible values: - WHITE_BACKGROUND: Change the background to white. OptimizeImagesResponse: 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/OptimizeImagesResponseData" OptimizeImagesResponseData: type: object properties: images: type: array items: $ref: "#/components/schemas/OptimizeImagesResponseDataImage" description: The list of images to be optimized. OptimizeImagesResponseDataImage: type: object properties: height: type: integer format: int64 description: The height of the original image, in pixels. width: type: integer format: int64 description: The width of the original image, in pixels. original_uri: type: string description: The original URI of the image to be optimized. original_url: type: string description: The original URL of the image to be optimized. optimized_uri: type: string description: |- The URI of the image after optimization. Pass this value when creating or editing a product to associate the image with the product. Applicable only if `optimize_status`is `SUCCESS`. optimized_url: type: string description: |- The URL of the image after optimization. Use this URL in product descriptions by embedding it within an HTML `` tag. Applicable only if `optimize_status`is `SUCCESS`. optimize_status: type: string enum: - SUCCESS - IGNORE - PROCESSING x-enum-descriptions: - The image has been successfully optimized. - The image already has a white background, so no optimization was applied. - The optimization is in progress, and typically completes within a few seconds. Call this API again to obtain the final optimization status. description: |- The optimization status. Possible values: - SUCCESS: The image has been successfully optimized. - IGNORE: The image already has a white background, so no optimization was applied. - PROCESSING: The optimization is in progress, and typically completes within a few seconds. Call this API again to obtain the final optimization status. Option: type: object properties: id: type: string description: Option id name: type: string description: The option name. option_children: type: array items: $ref: "#/components/schemas/OptionChildren" description: Children option detail list, used if the option has sub option choices OptionChildren: type: object properties: id: type: string description: Children Option id name: type: string description: Children Option name Order: type: object properties: id: type: string description: TikTok Shop order ID. skus: type: array items: $ref: "#/components/schemas/GetPackageDetailResponseDataOrderSku" description: "[Deprecated]SKU information." deprecated: true OrderLineList: type: object properties: order_line_item_id: type: string description: The corresponding order line ID sub_order_line_item_id: type: string description: |- The sub-order-line ID inside a bundle product - Required for bundle products - Not required for non-bundle products OrderStatusChangeWebhook: type: object properties: type: type: integer const: 1 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/OrderStatusChangeWebhookData" required: - type OrderStatusChangeWebhookData: type: object properties: order_id: type: string description: The identification of a TikTok Shop order order_status: type: string enum: - UNPAID - ON_HOLD - AWAITING_SHIPMENT - AWAITING_COLLECTION - CANCEL - IN_TRANSIT - DELIVERED - COMPLETED description: |- The most recent order status, with possible values: * `UNPAID` * `ON_HOLD` * `AWAITING_SHIPMENT` * `AWAITING_COLLECTION` * `CANCEL` * `IN_TRANSIT` * `DELIVERED` * `COMPLETED` is_on_hold_order: type: boolean description: Indicates whether the order has experienced or will experience `ON_HOLD` status update_time: type: integer format: int64 description: The order status update time, represented as a Unix timestamp (seconds). OriginalPrice: type: object properties: currency: type: string description: The currency in the sale region. minimum_amount: type: string description: The minimum original price of all skus of this product. maximum_amount: type: string description: The maximum original price of all skus of this product. Package: type: object properties: id: type: string description: The new package ID generated after the package has been successfully combined. order_ids: type: array items: type: string description: List of order IDs corresponding to a new combined package ID. PackageDimension: type: object properties: length: type: string description: |- The package length. A positive whole number. **Note**: For the BR market, decimal values using `.` or `,` as separators are also accepted but will be rounded to the nearest whole number. width: type: string description: |- The package width. A positive whole number. **Note**: For the BR market, decimal values using `.` or `,` as separators are also accepted but will be rounded to the nearest whole number. height: type: string description: |- The package height. A positive whole number. **Note**: For the BR market, decimal values using `.` or `,` as separators are also accepted but will be rounded to the nearest whole number. unit: type: string description: |- The unit for the package dimensions. Possible values based on region: - US: CENTIMETER, INCH - Other regions: CENTIMETER **Note**: You must use the same system of measurement (metric system or imperial system) for `package_weight` and `package_dimensions`. In other words, if you are using KILOGRAM for the weight, you must use CENTIMETER for the dimensions. required: - length - width - height - unit PackageUpdateWebhook: type: object properties: type: type: integer const: 4 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/PackageUpdateWebhookData" required: - type PackageUpdateWebhookData: type: object properties: sc_type: type: string enum: - COMBINE - CANCEL_COMBINE - SPLIT - CANCEL_SPLIT - ADDRESS_UPDATE_SPLIT - CANCEL_FULFILL_SPLIT - FULFILL_UNCOMBINE - PARTLY_CANCEL_SPLIT - SPLIT_BY_SKU_CANCEL description: |- Type of the event trigger, with possible values: * COMBINE * CANCEL_COMBINE * SPLIT * CANCEL_SPLIT * ADDRESS_UPDATE_SPLIT * CANCEL_FULFILL_SPLIT * FULFILL_UNCOMBINE * PARTLY_CANCEL_SPLIT * SPLIT_BY_SKU_CANCEL role_type: type: string enum: - ROLE_USER - ROLE_SELLER - ROLE_OPERATOR - ROLE_SYSTEM description: |- Operator of the event trigger, with possible values: * ROLE_USER * ROLE_SELLER * ROLE_OPERATOR * ROLE_SYSTEM package_list: type: array items: $ref: "#/components/schemas/PackageUpdateWebhookDataPackageList" description: Package list updated by the event trigger update_time: type: integer format: int64 description: The time when the package was updated, represented as a Unix timestamp (seconds). PackageUpdateWebhookDataPackageList: type: object properties: package_id: type: string description: The identification of a package order_id_list: type: array items: type: string description: List of order IDs in a given package PackageWeight: type: object properties: value: type: string description: |- The package weight, which must be a positive number. The number format varies based on the `unit`: - `GRAM`: integer - `KILOGRAM`: up to 3 decimal places - `POUND`: up to 2 decimal places unit: type: string description: |- The unit for the package weight. Possible values based on region: - US: `KILOGRAM`, `POUND` - BR, JP, MX: `KILOGRAM`, `GRAM` - Other countries: `KILOGRAM` **Note**: You must use the same system of measurement (metric system or imperial system) for `package_weight` and `package_dimensions`. In other words, if you are using `KILOGRAM` for the weight, you must use `CENTIMETER` for the dimensions. required: - value - unit Pagination: type: object properties: page_size: type: integer format: int64 minimum: 1 maximum: 100 description: "Number of records to return per page. Minimum: 1. Maximum: 100." page_token: type: string description: Identifies the page to retrieve. PartialEditGlobalProductRequest: type: object properties: title: type: string description: |- The product title. Title length: - DE, ES, FR, IE, IT, JP, UK, US: [1, 255] - MX:[1,300] - Other regions: [25, 255] description: type: string maxLength: 10000 description: |- The product description in HTML format. **Note**: - 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 `
` tags as images. - Max length: 10,000 characters. - Image guidelines: You must use [TikTok Shop image URLs](6509df95defece02be598a22). Max 30 `` tags, each under 4000px with `src`, `width`, and `height` attributes. **Recommendations**: - If you are syncing a pre-existing description from another platform, include the full HTML source description here. - Provide a detailed description, ideally over 300 characters. - Include 3-5 key selling points, each under 250 characters, with supporting images. - Use 1600x1600 px for the image dimensions. category_id: type: string description: |- The product's current category ID. If provided, it must match the existing category; this API cannot change the product category. - It must be a leaf category that corresponds to the category tree type specified in the `category_version` property. - It must be a main category (`categories.permission_statuses=AVAILABLE` in [Get Global Categories API](650a03f8f1fd3102b91b338a)). **Note**: Refer to TikTok Shop Academy for information on product category restrictions. brand_id: type: string description: |- The ID of the brand of this product. **Note**: Unauthorized brands won't be displayed on TikTok Shop. main_images: type: array items: $ref: "#/components/schemas/MainImage" maxItems: 9 description: |- A list of images to display in the product image gallery. - Max count: 9 - Arrange your image URIs in the sequence that they should appear on TikTok Shop. - Image dimensions: [300x300 px, 4000x4000 px] **Recommendations**: - Use a minimum of 5 images. - The first image should have a white background. Use the [Optimize Images API](https://partner.tiktokshop.com/docv2/page/665692b35d39dc02deb49a97) to change the background to white. skus: type: array items: $ref: "#/components/schemas/PartialEditGlobalProductRequestSku" description: |- A list of global Stock Keeping Units (SKUs) used to identify distinct variants of the product. **Note**: - Max SKUs for EU, JP, UK, US: 300 - Max SKUs for other regions: 100 **Recommendations**: Place the most important variant at the beginning of the array. package_weight: $ref: "#/components/schemas/PackageWeight" description: |- The weight of the product package. **Note**: - Provide the weight measured after packing the product. - This value impacts the shipping cost, so it is important to ensure that the measurements are accurate. Any discrepancies may lead to additional shipping fees. - The package weight will take precedence over package dimensions in fee calculation if the fee based on weight is higher. certifications: type: array items: $ref: "#/components/schemas/CreateGlobalProductRequestCertification" maxItems: 10 description: |- The list of certifications for your product. If a non-empty list is provided, it replaces the existing certifications. If omitted or passed as an empty array, the existing certifications are retained. Max count: 10 As per TikTok Shop guidelines, certifications are required for certain restricted product categories. Retrieve the certification requirements for your product from the [Get Global Category Rules API](https://partner.tiktokshop.com/docv2/page/650a056df1fd3102b91b5b8e). Refer to [TikTok Shop Restricted Products Policy](https://seller-us.tiktok.com/university/essay?identity=1&role=1&knowledge_id=3238037484275457&from=policy) for information on product category restrictions. package_dimensions: $ref: "#/components/schemas/PackageDimension" description: |- The dimensions of the product package. **Note**: - Provide the dimensions measured after packing the product. - These values impact the shipping cost, so it is important to ensure that dimensions are accurate. Any discrepancies may lead to additional shipping fees. product_attributes: type: array items: $ref: "#/components/schemas/ProductAttribute" description: |- A list of general attributes (e.g. manufacturer, country of origin, materials used) that describe the product as a whole, regardless of variant. If a non-empty list is provided, it replaces the existing product attributes. If omitted or passed as an empty array, the existing product attributes are retained. **Important**: The attributes available for use are determined by the system based on the product's assigned category, with some being mandatory. You must provide the product attributes marked as `is_required` in the response of the [Get Global Attributes API](650a0483c16ffe02b8dfc80a). size_chart: $ref: "#/components/schemas/SizeChart" description: |- The measurement details of the product to help buyers find the right size. If omitted, the existing size chart is retained. Pass an empty object to remove the existing size chart. Otherwise, the provided object replaces the existing size chart. **Note**: - For certain product categories, size charts may be required or not supported. Use the [Get Global Category Rules API](https://partner.tiktokshop.com/docv2/page/650a056df1fd3102b91b5b8e) to check the requirements. - If size charts are not supported, even if you provide a size chart here, the size chart will not be saved. - Provide either a TikTok Shop size chart template ID or a size chart image; if both are provided, the ID takes priority. video: $ref: "#/components/schemas/Video" description: |- A product introduction or promotion video to display for your product. **Recommendations**: - Aspect ratio: 1:1 - Resolution: HD 720p or higher - Duration: 20 - 60 seconds manufacturer: $ref: "#/components/schemas/Manufacturer" description: |- (**Deprecated**: This field is deprecated and will be removed in a future API version. Use `manufacturer_ids` instead.) The product manufacturer's details. deprecated: true manufacturer_ids: type: array items: type: string description: |- A list of manufacturer IDs. Retrieve the IDs from the [Search Manufacturers API](67066a580dcee902fa03ccf9). If omitted, the manufacturer IDs already associated with the global product are retained. Pass an empty array to remove all existing manufacturer IDs. **Note**: Applicable only for the EU market in certain categories. Use the [Get Global Category Rules API](650a056df1fd3102b91b5b8e) to check the requirements. responsible_person_ids: type: array items: type: string description: |- A list of responsible person IDs. Retrieve the IDs from the [Search Responsible Persons API](67066a55f17b7d02f95d2fb1). If omitted, the responsible person IDs already associated with the global product are retained. Pass an empty array to remove all existing responsible person IDs. **Note**: Applicable only for the EU market in certain categories. Use the [Get Global Category Rules API](650a056df1fd3102b91b5b8e) to check the requirements. category_version: type: string enum: - v2 - v1 x-enum-descriptions: - "US: represents the 7-level category tree." - "Other regions: represents the 3-level category tree." description: |- The category tree version used by `category_id`. Possible values based on region: - US: `v2`, represents the 7-level category tree. **Important**: If the seller account contains an active US shop, you must pass `v2` when using this API. - Other regions: `v1`, represents the 3-level category tree. Default: `v1` external_global_product_id: type: string maxLength: 999 description: |- An external identifier used in an external ecommerce platform. This is used to associate the global product between TikTok Shop and the external ecommerce platform. Max length: 999 characters PartialEditGlobalProductRequestSku: type: object properties: id: type: string description: |- The global SKU ID in TikTok Shop. One product can contain multiple SKU IDs. **Note**: - To edit an existing SKU, include its SKU ID. - Any existing SKU IDs not listed here will result in the deletion of those SKUs. For example, if this product contains 5 SKUs and you only provide 2 SKU IDs, the remaining 3 will be deleted. - To create new SKUs, leave the SKU ID blank and complete the other fields. global_quantity: type: integer format: int64 description: |- The total SKU inventory quantity across all shops globally. The inventory for each local shop is automatically calculated when a product is first published. After publishing, this global quantity cannot be manually changed. You can only modify the inventory quantity in each local shop. seller_sku: type: string minLength: 1 maxLength: 50 description: |- An internal code/name for managing SKUs, not visible to buyers. - Valid length: 1-50 characters - Format: Text without spaces price: $ref: "#/components/schemas/CreateGlobalProductRequestSkuPrice" description: |- The SKU's **global uniform pre-tax** price that serves as the baseline for calculating the local prices across different markets. **Note**: - Upon publishing, this price will be automatically converted to the local pre-tax price and local display price based on market-specific exchange rates and applicable charges such as shipping costs, taxes, and other fees. - The auto-conversion will exclude JP and US shops using China warehouses. For these shops, please use `sale_prices` instead. sales_attributes: type: array items: $ref: "#/components/schemas/CreateGlobalProductRequestSkuSalesAttribute" description: |- A list of attributes (e.g. size, color, length) that define each variant of a product. **Note**: - You must retain at least 1 sales attribute, deleting all existing sales attributes is not allowed. - You can only have up to 3 types of sales attributes per product. - Each SKU must include the same number and type of sales attributes. For example, you cannot have one SKU that has only a Color attribute, while another SKU has both Color and Size attributes. - Provide either a built-in ID or a custom name; if both are provided, the ID takes priority. - The `id/name` and `value_id/value_name` pairs must be unique in each SKU. For example, you cannot repeat `"name": "Color"`, `"value_name": "Red"` in different SKUs. inventory: type: array items: $ref: "#/components/schemas/CreateGlobalProductRequestSkuInventory" maxItems: 50 description: |- SKU inventory information per warehouse. If multi-warehouse is enabled in Seller Center, you must provide the inventory details for each warehouse. Max count: 50 **Note**: `global_quantity` will not take effect if inventory details are provided for each warehouse. identifier_code: $ref: "#/components/schemas/IdentifierCode" description: |- A regulated identifier code assigned to a product based on international standardized regulations (e.g. GTIN) to ensure the product is universally identifiable across various platforms and systems. **Note**: Editable only if the product is in DRAFT state. Otherwise, changes are not allowed. sku_unit_count: type: string description: |- The total quantity/volume of the product represented by the SKU. For example, if the SKU represents 500ml of water, this value would be 500 if the unit type is defined as ml. Valid range: [0.01, 99,999.9999] Applicable only for the EU market. **Note**: - This is mainly used to calculate the unit price of the SKU, and is required only if you wish to display the unit price to facilitate easier price comparisons across different products and packaging sizes. - Unit price = Selling price/(SKU unit count/base unit count). Therefore if you want to obtain the unit price, you would also need to define the "base unit count" and the "unit type" product attributes. Retrieve the relevant information for these product attributes by using the [Get Global Attributes API](https://partner.tiktokshop.com/docv2/page/650a0483c16ffe02b8dfc80a). The unit price would then be returned in the [Get Global Product API](https://partner.tiktokshop.com/docv2/page/6509e2b0bace3e02b7490c96). extra_identifier_codes: type: array items: type: string description: |- If the SKU belongs to a virtual bundle (containing multiple individual SKUs), you can add up to 10 additional identifier codes here for the SKUs included in the bundle. **Format**: GTIN: 14 digits EAN: 8, 13, or 14 digits UPC: 12 digits ISBN: 13 digits, or 9 digits ending in capital `X` **Note**: - Applicable only for the EU market. - The identifier code must be unique for each SKU, with no repetition allowed. external_global_sku_id: type: string maxLength: 999 description: |- An external identifier used in an external ecommerce platform. This is used to associate the global SKU between TikTok Shop and the external ecommerce platform. Max length: 999 characters sale_prices: type: array items: $ref: "#/components/schemas/PartialEditGlobalProductRequestSkuSalePrice" description: |- The SKU's **local display price** shown on the product page before any discounts. **Note**: - Required for JP and US shops using China warehouses, optional for others. - This is the definitive final price shown on the product page, all other prices will be ignored. PartialEditGlobalProductRequestSkuSalePrice: type: object properties: region: type: string enum: - DE - ES - FR - GB - ID - IE - IT - JP - MY - PH - SG - TH - US - VN x-enum-descriptions: - Germany - Spain - France - United Kingdom - Indonesia - Ireland - Italy - Japan - Malaysia - Philippines - Singapore - Thailand - United States - Vietnam description: |- The market where you want to sync the sale price. Possible values: - DE: Germany - ES: Spain - FR: France - GB: United Kingdom - ID: Indonesia - IE: Ireland - IT: Italy - JP: Japan - MY: Malaysia - PH: Philippines - SG: Singapore - TH: Thailand - US: United States - VN: Vietnam amount: type: string description: |- The price amount. Refer to [Product Pricing](https://partner.tiktokshop.com/docv2/page/67e1288d76cfee049d9af858) for the allowed price ranges in each market. required: - region - amount PartialEditGlobalProductResponse: 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/PartialEditGlobalProductResponseData" PartialEditGlobalProductResponseData: type: object properties: global_skus: type: array items: $ref: "#/components/schemas/GlobalSku" description: A list of global Stock Keeping Units (SKUs) used to identify distinct variants of the product. publish_results: type: array items: $ref: "#/components/schemas/PartialEditGlobalProductResponseDataPublishResult" description: Results of syncing the changes in the edited product to markets where it is published. PartialEditGlobalProductResponseDataPublishResult: type: object properties: region: type: string enum: - DE - ES - FR - GB - ID - IE - IT - JP - MX - MY - PH - SG - TH - US - VN x-enum-descriptions: - Germany - Spain - France - United Kingdom - Indonesia - Ireland - Italy - Japan - Mexico - Malaysia - Philippines - Singapore - Thailand - United States - Vietnam description: |- The market where the product is published Possible values: - DE: Germany - ES: Spain - FR: France - GB: United Kingdom - ID: Indonesia - IE: Ireland - IT: Italy - JP: Japan - MX: Mexico - MY: Malaysia - PH: Philippines - SG: Singapore - TH: Thailand - US: United States - VN: Vietnam status: type: string enum: - SUCCESS - FAILED x-enum-descriptions: - The global product was successfully synchronized to the local shop, submitted for listing, and is now under review. Use the [Product status change](650956aff1fd3102b90b6261) webhook to track subsequent audit status changes and completion. - Synchronization of the global product to the local shop was unsuccessful. description: |- The status of syncing the product to the market. Possible values: - SUCCESS: The global product was successfully synchronized to the local shop, submitted for listing, and is now under review. Use the [Product status change](650956aff1fd3102b90b6261) webhook to track subsequent audit status changes and completion. - FAILED: Synchronization of the global product to the local shop was unsuccessful. fail_reasons: type: array items: $ref: "#/components/schemas/FailReason" description: The list of errors that occurred. PartialEditManufacturerRequest: type: object properties: name: type: string maxLength: 255 description: |- The manufacturer name. Max length: 255 characters registered_trade_name: type: string maxLength: 200 description: |- The registered trade name of the manufacturer. Max length: 200 characters email: type: string description: The manufacturer's email address. Use a valid email format such as `name@example.com`. phone_number: $ref: "#/components/schemas/PhoneNumber" description: The phone number of the manufacturer. address: type: string maxLength: 500 description: |- The postal address of the manufacturer. Max length: 500 characters locale: type: string enum: - de-DE - en-IE - es-ES - fr-FR - it-IT description: |- The BCP-47 locale code representing the language of the manufacturer information to update. Possible values: - de-DE - en-IE - es-ES - fr-FR - it-IT Default: The locale of the seller's registered business address. **Note**: Only the language version selected by this locale is updated; other language versions remain unchanged. Ensure the locale matches the language used in the supplied field values. PartialEditManufacturerResponse: 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/PartialEditManufacturerResponseData" PartialEditManufacturerResponseData: type: object properties: {} PartialEditProductRequest: type: object properties: auto_translate_enabled: type: boolean description: Whether to automatically translate the product content when listing the product in a market where multiple languages are needed. Omit this field when automatic translation is not needed. brand_id: type: string description: |- The ID of the brand of this product. Use the [Get Brands API](https://partner.tiktokshop.com/docv2/page/6503075656e2bb0289dd5d01) to get the list of available brands for a shop. **Note**: Unauthorized brands won't be displayed on TikTok Shop. category_version: type: string description: |- Filter categories by the category tree version.Possible values based on region: - US, EU and SEA: v2, represents the 7-level category tree. Important: For US, EU and SEA shops, you must pass v2 when using this API. - Other regions: v1, represents the 3-level category tree.Default: v1 certifications: type: array items: $ref: "#/components/schemas/PartialEditProductRequestCertification" maxItems: 10 description: |- The list of certifications for your product. Max count: 10 As per TikTok Shop guidelines, certifications are required for certain restricted product categories. Retrieve the certification requirements for your product from the [Get Category Rules API](https://partner.tiktokshop.com/docv2/page/6509c0febace3e02b74594a9). Refer to [TikTok Shop Restricted Products Policy](https://seller-us.tiktok.com/university/essay?identity=1&role=1&knowledge_id=3238037484275457&from=policy) for information on product category restrictions. description: type: string maxLength: 10000 description: |- The product description in HTML format. **Note**: - 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 `
` tags as images. - Max length: 10,000 characters. - Image guidelines: You must use [TikTok Shop image URLs](6509df95defece02be598a22). Max 30 `` tags, each under 4000px with `src`, `width`, and `height` attributes. **Recommendations**: - If you are syncing a pre-existing description from another platform, include the full HTML source description here. - Provide a detailed description, ideally over 300 characters. - Include 3-5 key selling points, each under 250 characters, with supporting images. - Use 1600x1600 px for the image dimensions. external_product_id: type: string maxLength: 999 description: |- An external identifier used in an external ecommerce platform. This is used to associate the product between TikTok Shop and the external ecommerce platform. Max length: 999 characters inventory_mode: type: string description: |- Defines the inventory mode for the duplicated source product. This parameter supports two modes: SHARED and EXCLUSIVE. - SHARED: In this mode, the inventory of all interconnected (shared) products must be strictly consistent; otherwise, an error will be returned. - EXCLUSIVE: In this mode, the inventory for each product can be set independently without affecting others. Applicability: This feature is applicable ONLY for the EU market. Default Value: If left empty, the system defaults to the EXCLUSIVE mode. is_cod_allowed: type: boolean description: |- A flag indicating whether to show the Cash On Delivery (COD) payment option during checkout. Use the [Get Category Rules API](https://partner.tiktokshop.com/docv2/page/6509c0febace3e02b74594a9) to check if COD is supported for your product category. Applicable only for the following markets: - Global sellers: MY, PH, SA, TH, VN - Local sellers: ID, MY, PH, SA, TH, VN **Note**: If COD is not supported, the listing will fail if you set this to `true`. key_product_features: type: array items: type: string maxItems: 5 description: Key Product Features. They will be displayed in the Product highlight module on the product detail page and will be used by search engines to increase your search weight for more traffic. The total number of items should not exceed 5, and the total character count should not exceed 1500. listing_platforms: type: array items: type: string enum: - TOKOPEDIA - TIKTOK_SHOP description: |- The platforms for listing the product. Possible values: - TOKOPEDIA - TIKTOK_SHOP Applicable only for sellers that migrated from Tokopedia. **IMPORTANT**: This field controls the product's visibility on the listing platforms. - If the product is live on both platforms but the request contains only 1 platform, the product will be deactivated and hidden from the omitted platform. - If the product is live on 1 platform but the request contains a different platform, the product will be deactivated and hidden from the omitted platform. - If you want to deactivate the product on both platforms, use the Deactivate Product API. locale: 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 description: |- The BCP-47 locale code used when retrieving the existing product information for this edit. Default: The default locale of your shop. Possible values: - 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 main_images: type: array items: $ref: "#/components/schemas/MainImage" maxItems: 9 description: |- A list of images to display in the product image gallery. - Max count: 9 - Arrange your image URIs in the sequence that they should appear on TikTok Shop. - Image dimensions: [300x300 px, 4000x4000 px] **Recommendations**: - Use a minimum of 5 images. - The first image should have a white background. Use the [Optimize Images API](https://partner.tiktokshop.com/docv2/page/665692b35d39dc02deb49a97) to change the background to white. manufacturer_ids: type: array items: type: string description: |- A list of manufacturer IDs. Retrieve the IDs from the [Search Manufacturers API](67066a580dcee902fa03ccf9). **Note**: Applicable only for the EU market in certain categories. Use the [Get Category Rules API](6509c0febace3e02b74594a9) to check the requirements. package_dimensions: $ref: "#/components/schemas/PartialEditProductRequestPackageDimension" description: |- The dimensions of the product package. **Note**: - Provide the dimensions measured after packing the product. - These values impact the shipping cost, so it is important to ensure that dimensions are accurate. Any discrepancies in measurements may lead to additional shipping fees. - Optional for ID, TH, VN regions. package_weight: $ref: "#/components/schemas/PartialEditProductRequestPackageWeight" description: |- The weight of the product package. **Note**: - Provide the weight measured after packing the product. - This value impacts the shipping cost, so it is important to ensure that the weight is accurate. Any discrepancies in measurements may lead to additional shipping fees. - The package weight will take precedence over package dimensions in fee calculation if the fee based on weight is higher. pod_info: $ref: "#/components/schemas/PartialEditProductRequestPodInfo" description: POD customization configuration for an MTO product. Use this object to configure consumer-customizable templates, surfaces, and customization areas for Print-On-Demand products. product_attributes: type: array items: $ref: "#/components/schemas/CreateProductRequestProductAttribute" description: |- A list of general attributes (e.g. manufacturer, country of origin, materials used) that describe the product as a whole, regardless of variant. **Important**: The attributes available for use are determined by the system based on the product's assigned category, with some being mandatory. You must provide the product attributes marked as `is_required` in the response of the [Get Attributes API](6509c5784a0bb702c0561cc8) to avoid listing failure. replicated_products: type: array items: $ref: "#/components/schemas/PartialEditProductRequestReplicatedProduct" description: |- The list of local market replicas to which updates should be synced. As this is a partial edit endpoint, only updated fields will be synced. **Compulsory sync** - **Sales attribute changes** (in sales attribute id/name) must be synced to other markets. Therefore, you must provide the `seller_sku` above and complete the details in this object. The API call will fail if you don't provide these details. **Optional sync** - **New SKUs** (new sales attribute value id/name) are optional to sync to other markets. To sync, please provide the `seller_sku` above and complete the details in this object. - **General changes** are optional to sync to other markets. To sync, you only need to provide `replicated_products.region`. responsible_person_ids: type: array items: type: string description: |- A list of responsible person IDs. Retrieve the IDs from the [Search Responsible Persons API](67066a55f17b7d02f95d2fb1). **Note**: Applicable only for the EU market in certain categories. Use the [Get Category Rules API](6509c0febace3e02b74594a9) to check the requirements. save_mode: type: string enum: - AS_DRAFT - LISTING x-enum-descriptions: - Save the product as a draft for future editing. - Submit the edits for listing. Changes that require review are published after approval; changes to the `price` or `inventory` fields are published immediately. description: |- Indicates how the product should be saved. Possible values: - AS_DRAFT: Save the product as a draft for future editing. - LISTING: Submit the edits for listing. Changes that require review are published after approval; changes to the `price` or `inventory` fields are published immediately. Default: LISTING **Note**: - Saving as draft is not supported when the product status is `DELETED`, or when the product is `PENDING` or `FREEZE` on any listing platform. - When saving a post-live draft with `save_mode=AS_DRAFT`, SKU `inventory` fields are not supported and will not be saved. scheduled_sale: $ref: "#/components/schemas/ScheduledSale" description: Scheduled listing configuration for the product, including whether scheduled listing is enabled and the scheduled listing time. search_terms: type: array items: type: string description: Search terms (ST words). ST words will not be displayed to consumers; they are only used in search engines to increase your search weight and gain more traffic. Please ensure that ST words are consistent with the product description, with a maximum of 15 terms and a total of no more than 250 characters. size_chart: $ref: "#/components/schemas/SizeChart" description: |- The measurement details of the product to help buyers find the right size. **Note**: - For certain product categories, size charts may be required or not supported. Use the [Get Category Rules API](https://partner.tiktokshop.com/docv2/page/6509c0febace3e02b74594a9) to check the requirements. - If size charts are not supported, even if you provide a size chart here, the size chart will not be saved. - Provide either a TikTok Shop size chart template ID or a size chart image; if both are provided, the ID takes priority. skus: type: array items: $ref: "#/components/schemas/PartialEditProductRequestSku" description: |- A list of Stock Keeping Units (SKUs) used to identify distinct variants of the product. **Note**: - Max SKUs for BR, EU, JP, MX, UK, US: 300 - Max SKUs for other regions: 100 **Recommendations**: Place the most important variant at the beginning of the array. subscribe_info_edit: $ref: "#/components/schemas/PartialEditProductRequestSubscribeInfoEdit" description: All of the Save and Subscribe discount details. title: type: string description: |- The product title. Title length: - DE, ES, FR, IE, IT, JP, UK, US: [1, 255] - BR, MX: [1, 300] - Other regions: [25, 255] video: $ref: "#/components/schemas/Video" description: |- A product introduction or promotion video to display for your product. **Recommendations**: - Aspect ratio: 1:1 - Resolution: HD 720p or higher - Duration: 20 - 60 seconds is_blind_box: type: boolean description: "Whether the product is a blind box of lucky bag. For example: PopMart" PartialEditProductRequestCertification: type: object properties: expiration_date: type: integer format: int64 description: |- The expiration date of this certification expressed in unix timestamp (seconds) UTC+0. This 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. files: type: array items: $ref: "#/components/schemas/PartialEditProductRequestCertificationFile" description: A list of certification related files. id: type: string description: |- The ID to identify the type of certification required for the product category. Retrieve 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. required: - id PartialEditProductRequestCertificationFile: type: object properties: format: type: string description: The format of the certification file. Only PDF is supported. id: type: string description: |- The ID of the certification file. Use the [Upload Product File API](https://partner.tiktokshop.com/docv2/page/6509dffdc16ffe02b8dc10c5) to upload the files first and obtain the corresponding file ID. name: type: string description: The name of the certification file, including the file extension. required: - format - id - name PartialEditProductRequestPackageDimension: type: object properties: height: type: string description: |- The package height. A positive whole number. **Note**: For the BR market, decimal values using `.` or `,` as separators are also accepted but will be rounded to the nearest whole number. length: type: string description: |- The package length. A positive whole number. **Note**: For the BR market, decimal values using `.` or `,` as separators are also accepted but will be rounded to the nearest whole number. unit: type: string description: |- The unit for the package dimensions. Possible values based on region: - US: CENTIMETER, INCH - Other regions: CENTIMETER **Note**: You must use the same system of measurement (metric system or imperial system) for `package_weight` and `package_dimensions`. In other words, if you are using KILOGRAM for the weight, you must use CENTIMETER for the dimensions. width: type: string description: |- The package width. A positive whole number. **Note**: For the BR market, decimal values using `.` or `,` as separators are also accepted but will be rounded to the nearest whole number. required: - height - length - unit - width PartialEditProductRequestPackageWeight: type: object properties: unit: type: string description: |- The unit for the package weight. Possible values based on region: - US: `KILOGRAM`, `POUND` - BR, JP, MX: `KILOGRAM`, `GRAM` - Other countries: `KILOGRAM` **Note**: You must use the same system of measurement (metric system or imperial system) for `package_weight` and `package_dimensions`. In other words, if you are using `KILOGRAM` for the weight, you must use `CENTIMETER` for the dimensions. value: type: string description: |- The package weight, which must be a positive number. The number format varies based on the `unit`: - `GRAM`: integer - `KILOGRAM`: up to 3 decimal places - `POUND`: up to 2 decimal places required: - unit - value PartialEditProductRequestPodInfo: type: object properties: pod_templates: type: array items: $ref: "#/components/schemas/PartialEditProductRequestPodInfoPodTemplate" description: A list of POD customization templates. Each template represents one customization plan and can be associated with one or more SKUs. PartialEditProductRequestPodInfoPodTemplate: type: object properties: pod_template_id: type: string description: The unique identifier of the POD customization template. This field is generated by the system and is not required when creating a new template. remark: type: string description: Optional notes or instructions for this customization template. These notes may be used to remind consumers about customization requirements on the customization page. sku_ids: type: array items: type: string description: A list of product SKU IDs associated with this customization template. The same SKU cannot be associated with more than one template. surfaces: type: array items: $ref: "#/components/schemas/PartialEditProductRequestPodInfoPodTemplateSurface" maxItems: 10 description: A list of customizable product surfaces under this template, such as the front side, back side, collar, or sleeve. A template can contain up to 10 surfaces. template_name: type: string description: The name of the customization template, used by the seller for internal management. PartialEditProductRequestPodInfoPodTemplateSurface: type: object properties: background_image: $ref: "#/components/schemas/PartialEditProductRequestPodInfoPodTemplateSurfaceBackgroundImage" description: The background image of the customizable surface. It is usually the base product image on which customization areas are configured. custom_areas: type: array items: $ref: "#/components/schemas/PartialEditProductRequestPodInfoPodTemplateSurfaceCustomArea" maxItems: 10 description: A list of customizable areas on this surface. The order of the elements represents the layer order to be used when rendering the final customization preview. A surface can contain up to 10 customization areas. external_surface_id: type: string description: The seller-defined external identifier of the customizable surface, used for mapping with the seller's own system. mask_image: $ref: "#/components/schemas/PartialEditProductRequestPodInfoPodTemplateSurfaceMaskImage" description: An optional mask image placed above the customization areas to support irregular or cut-out effects. surface_name: type: string description: The name of the customizable surface, for example, `Front Side` or `Back Side`. PartialEditProductRequestPodInfoPodTemplateSurfaceBackgroundImage: type: object properties: uri: type: string description: |- The URI of the background image. Obtain this URI by uploading the images through the [Upload Product Image API](6509df95defece02be598a22) with `use_case=CUSTOMIZATION_IMAGE`. PartialEditProductRequestPodInfoPodTemplateSurfaceCustomArea: type: object properties: area_name: type: string description: The name of the customizable area. area_placement: $ref: "#/components/schemas/AreaPlacement" description: The position, size, and rotation information of the customizable area on the surface. area_type: type: string description: "The type of the customizable area. Enum values: `TEXT`, `IMAGE`." external_area_id: type: string description: The seller-defined external identifier of the customizable area, used for mapping with the seller's own system. image_area: $ref: "#/components/schemas/PartialEditProductRequestPodInfoPodTemplateSurfaceCustomAreaImageArea" description: Configuration for an image-type customization area. This field should be provided when `area_type` is `IMAGE`. is_required: type: boolean description: Specifies whether the consumer must provide customization content for this area. If set to `false`, the default content or base product version may be used. text_area: $ref: "#/components/schemas/TextArea" description: Configuration for a text-type customization area. This field should be provided when `area_type` is `TEXT`. PartialEditProductRequestPodInfoPodTemplateSurfaceCustomAreaImageArea: type: object properties: default_image: $ref: "#/components/schemas/PartialEditProductRequestPodInfoPodTemplateSurfaceCustomAreaImageAreaDefaultImage" description: Optional default image displayed in this area. If the consumer does not upload a custom image, the default image may be used. min_height: type: integer format: int64 description: The minimum required height, in pixels, for an image uploaded by the consumer. min_width: type: integer format: int64 description: The minimum required width, in pixels, for an image uploaded by the consumer. PartialEditProductRequestPodInfoPodTemplateSurfaceCustomAreaImageAreaDefaultImage: type: object properties: uri: type: string description: |- The URI of the default image. Obtain this URI by uploading the images through the [Upload Product Image API](6509df95defece02be598a22) with `use_case=CUSTOMIZATION_IMAGE`. PartialEditProductRequestPodInfoPodTemplateSurfaceMaskImage: type: object properties: uri: type: string description: |- The URI of the mask image. Obtain this URI by uploading the images through the [Upload Product Image API](6509df95defece02be598a22) with `use_case=CUSTOMIZATION_IMAGE`. PartialEditProductRequestReplicatedProduct: type: object properties: inventory_mode: type: string description: |- Defines the inventory mode for the duplicated target product. This parameter supports two modes: SHARED and EXCLUSIVE. - SHARED: In this mode, the inventory of all interconnected (shared) products must be strictly consistent; otherwise, an error will be returned. - EXCLUSIVE: In this mode, the inventory for each product can be set independently without affecting others. Applicability: This feature is applicable ONLY for the EU market. Default Value: If left empty, the system defaults to the EXCLUSIVE mode. region: type: string enum: - AT - BE - CZ - DE - ES - FR - GB - GR - HU - ID - IE - IT - JP - MY - NL - PH - PO - PT - SG - TH - US - VN - MX x-enum-descriptions: - Austria - Belgium - Czech Republic - Germany - Spain - France - United Kingdom - Greece - Hungary - Indonesia - Ireland - Italy - Japan - Malaysia - Netherlands(NL) - Philippines - Poland - Portugal - Singapore - Thailand - United States - Vietnam - Mexico description: |- The local market replica region to which this product's updates should be synchronized. Possible values: - AT: Austria - BE:Belgium - CZ:Czech Republic - DE: Germany - ES: Spain - FR: France - GB: United Kingdom - GR: Greece - HU:Hungary - ID: Indonesia - IE: Ireland - IT: Italy - JP: Japan - MY: Malaysia - NL: Netherlands(NL) - PH: Philippines - PO: Poland - PT:Portugal - SG: Singapore - TH: Thailand - US: United States - VN: Vietnam - MX: Mexico skus: type: array items: $ref: "#/components/schemas/PartialEditProductRequestReplicatedProductSku" description: |- The SKUs to be synced to the specified market. Specify this **only if** you are adding SKUs or changing the sales attribute id/name. **Note**: - You must pass in all existing SKUs. Any existing SKU IDs not listed here will result in the deletion of those SKUs. For example, if this product contains 5 SKUs and you only provide 2 SKU IDs, the remaining 3 will be deleted. - To create new SKUs, leave the SKU ID blank and provide the seller_sku. required: - region PartialEditProductRequestReplicatedProductSku: type: object properties: external_sku_id: type: string maxLength: 999 description: |- An external identifier used in an external ecommerce platform. This is used to associate the SKU between TikTok Shop and the external ecommerce platform. Max length: 999 characters id: type: string description: The SKU ID generated by TikTok Shop. Provide this for existing SKUs inventory: type: array items: $ref: "#/components/schemas/PartialEditProductRequestReplicatedProductSkuInventory" description: SKU inventory information per warehouse. This field is mandatory for other regions. But when syncing products from the US to MX, the MX product inventory field is optional. price: $ref: "#/components/schemas/PartialEditProductRequestReplicatedProductSkuPrice" description: The SKU's **local display price** shown on the product page before any discounts seller_sku: type: string description: |- An internal code/name for managing SKUs, not visible to buyers. Valid length: - DE, ES, FR, IT, PL, NL, BE, CZ, AT, GR, PT, HU: 6-50 characters - Other regions: 1-50 characters Format: - DE, ES, FR, IT, PL, NL, BE, CZ, AT, GR, PT, HU: Use alphabets, numbers, hyphens (-), or underscores (_) only - Other regions: Text without spaces required: - price PartialEditProductRequestReplicatedProductSkuInventory: type: object properties: quantity: type: integer format: int64 minimum: 1 maximum: 999999 description: |- The SKU quantity available in the warehouse. Valid range: [1, 999,999]. This field is mandatory for other regions. But when syncing products from the US to MX, the MX product inventory field is optional. warehouse_id: type: string description: The warehouse ID. Retrieve this value from the [Get Warehouse List API](650aa418defece02be6e66b6) or Get Inventory Rules API. This field is mandatory for other regions. But when syncing products from the US to MX, the MX product inventory field is optional. PartialEditProductRequestReplicatedProductSkuPrice: type: object properties: currency: type: string enum: - BRL - CZK - EUR - GBP - HUF - IDR - JPY - MXN - MYR - PHP - PLN - SGD - THB - USD - VND x-enum-descriptions: - Brazil - Czech Republic - France, Germany, Ireland, Italy, Spain, Netherlands, Belgium, Austria, Greece, Portugal - United Kingdom - Hungary - Indonesia - Japan - Mexico - Malaysia - Philippines - Poland - Singapore - Thailand - United States - Vietnam description: |- The currency. Possible values based on the region: - BRL: Brazil - CZK: Czech Republic - EUR: France, Germany, Ireland, Italy, Spain, Netherlands, Belgium, Austria, Greece, Portugal - GBP: United Kingdom - HUF: Hungary - IDR: Indonesia - JPY: Japan - MXN: Mexico - MYR: Malaysia - PHP: Philippines - PLN: Poland - SGD: Singapore - THB: Thailand - USD: United States - VND: Vietnam sale_price: type: string description: |- The SKU's local display price shown on the product page before any discounts. Refer to Product Pricing for the allowed price ranges in each market. required: - currency - sale_price PartialEditProductRequestSku: type: object properties: external_list_prices: type: array items: $ref: "#/components/schemas/PartialEditProductRequestSkuExternalListPrice" description: |- The SKU list price (e.g. MSRP, RRP) or original price information on external ecommerce platforms. Applicable only for selected sellers in the US market. **Note**: This value may appear as the strikethrough price on the product page. However, whether the strikethrough price is shown and the amount shown are subject to the audit team's review and decision based on various pricing information. external_sku_id: type: string maxLength: 999 description: |- An external identifier used in an external ecommerce platform. This is used to associate the SKU between TikTok Shop and the external ecommerce platform. Max length: 999 characters external_urls: type: array items: type: string description: |- A list of URLs for third-party product listing pages where consumers can place orders. Add this property if you have products listed on third-party sites other than TikTok Shop and would like to map them. Max string length: 500 extra_identifier_codes: type: array items: type: string description: |- If the SKU belongs to a virtual bundle (containing multiple individual SKUs), you can add up to 10 additional identifier codes here for the SKUs included in the bundle. **Format**: GTIN: 14 digits EAN: 8, 13, or 14 digits UPC: 12 digits ISBN: 13 digits, or 9 digits ending in capital `X` **Note**: - Applicable only for the EU market. - The identifier code must be unique for each SKU, with no repetition allowed. fees: type: array items: $ref: "#/components/schemas/GetProductResponseDataSkuFee" description: The fees required for this product based on TikTok Shop policies. Fees are required only for certain product categories, retrieve the requirements from the [Get Category Rules API](https://partner.tiktokshop.com/docv2/page/6509c0febace3e02b74594a9). id: type: string description: |- The SKU ID generated by TikTok Shop. One product can contain multiple SKU IDs. **Note**: - To edit an existing SKU, include its SKU ID. - Any existing SKU IDs not listed here will result in the deletion of those SKUs. For example, if this product contains 5 SKUs and you only provide 2 SKU IDs, the remaining 3 will be deleted. - To create new SKUs, leave the SKU ID blank and complete the other fields. identifier_code: $ref: "#/components/schemas/IdentifierCode" description: |- A regulated identifier code assigned to a product based on international standardized regulations (e.g. GTIN) to ensure the product is universally identifiable across various platforms and systems. **Note**: Editable only if the product is in DRAFT state. Otherwise, changes are not allowed. inventory: type: array items: $ref: "#/components/schemas/PartialEditProductRequestSkuInventory" description: |- SKU inventory information. **Note**: If you are saving a post-live draft with `save_mode=AS_DRAFT`, this field is not supported and will not be saved. When using Get Product to retrieve the draft, the values will reflect those in the base version. list_price: $ref: "#/components/schemas/ListPrice" description: |- The SKU's list price information. This is equivalent to the manufacturer's suggested retail price (MSRP), or the recommended retail price (RRP). Applicable only for the US market. **Note**: This value may appear as the strikethrough price on the product page. However, whether the strikethrough price is shown and the amount shown are subject to the audit team's review and decision based on various pricing information. pre_sale: $ref: "#/components/schemas/GetProductResponseDataSkuPreSale" description: |- SKU presale information, used to tag a product as a presale product based on its presale type. Applicable only if `allowed_special_product_types` from [Get Category Rules](6509c0febace3e02b74594a9) is not empty. **Rules for the US market**: - Regular / Preorder product: Once the product goes live, you cannot change the product type. - Made-to-order product: You can change it to a regular product at any time. price: $ref: "#/components/schemas/PartialEditProductRequestSkuPrice" description: SKU pricing information. sales_attributes: type: array items: $ref: "#/components/schemas/PartialEditProductRequestSkuSalesAttribute" description: |- A list of attributes (e.g. size, color, length) that define each variant of a product. **Note**: - You must retain at least 1 sales attribute, deleting all existing sales attributes is not allowed. - You can only have up to 3 types of sales attributes per product. - Each SKU must include the same number and type of sales attributes. For example, you cannot have one SKU that has only a Color attribute, while another SKU has both Color and Size attributes. - Provide either a built-in ID or a custom name; if both are provided, the ID takes priority. - The `id/name` and `value_id/value_name` pairs must be unique in each SKU. For example, you cannot repeat `"name": "Color"`, `"value_name": "Red"` in different SKUs. seller_sku: type: string description: |- An internal code/name for managing SKUs, not visible to buyers. Valid length: - DE, ES, FR, IT, PL, NL, BE, CZ, AT, GR, PT, HU: 6-50 characters - Other regions: 1-50 characters Format: - DE, ES, FR, IT, PL, NL, BE, CZ, AT, GR, PT, HU: Use alphabets, numbers, hyphens (-), or underscores (_) only - Other regions: Text without spaces sku_dimensions: $ref: "#/components/schemas/PartialEditProductRequestSkuSkuDimension" description: |- The dimensions of the sku. Note: - Provide the dimensions measured after packing the product. - These values impact the shipping cost, so it is important to ensure that dimensions are accurate. Any discrepancies in measurements may lead to additional shipping fees. - Optional for ID, TH, VN regions. sku_unit_count: type: string description: |- The total quantity/volume of the product represented by the SKU. For example, if the SKU represents 500ml of water, this value would be 500 if the unit type is defined as ml. Valid range: [0.01, 99,999.9999] Applicable only for the EU market. **Note**: - This is mainly used to calculate the unit price of the SKU, and is required only if you wish to display the unit price to facilitate easier price comparisons across different products and packaging sizes. - Unit price = Selling price/(SKU unit count/base unit count). Therefore if you want to obtain the unit price, you would also need to define the "base unit count" and the "unit type" product attributes. Retrieve the relevant information for these product attributes by using the [Get Attributes API](https://partner.tiktokshop.com/docv2/page/6509c5784a0bb702c0561cc8). The unit price would then be returned in the [Get Product API](https://partner.tiktokshop.com/docv2/page/6509d85b4a0bb702c057fdda). sku_weight: $ref: "#/components/schemas/PartialEditProductRequestSkuSkuWeight" description: |- The packaged weight of the SKU. Note: - Product package weight is mandatory by default, except for products under Virtual Products categories. This requirement applies to `package_weight`, not `sku_weight`. - Provide the weight measured after packing the SKU. - This value impacts the shipping cost, so ensure that the SKU weight is accurate. Any discrepancies in measurements may lead to additional shipping fees. - The package weight takes precedence over package dimensions in fee calculation if the fee based on weight is higher. PartialEditProductRequestSkuExternalListPrice: type: object properties: amount: type: string description: |- The price amount. Valid range: [0.01, 7600] currency: type: string enum: - USD description: |- The currency. Possible values: USD source: type: string enum: - SHOPIFY_COMPARE_AT_PRICE x-enum-descriptions: - The compare_at_price in Shopify. description: |- The external ecommerce platform from which the price is sourced. Possible values: - SHOPIFY_COMPARE_AT_PRICE: The compare_at_price in Shopify. required: - amount - currency - source PartialEditProductRequestSkuInventory: type: object properties: backorder_quantity: type: integer format: int64 description: |- The `backorder_quantity` is automatically converted to `quantity` once in-stock inventory is sold out. Its fulfillment follows the specified `handling_time`. **Note**: - For non-virtual products, provide `backorder_quantity` and `handling_time` together. - Made-to-order (MTO), pre-order, and custom products cannot be backordered and therefore cannot use `backorder_quantity`. handling_time: type: integer format: int64 description: The estimated number of working days needed for a backorder to be shipped. For non-virtual products, provide `handling_time` and `backorder_quantity` together. Different warehouses for the same SKU cannot use different `handling_time` values. quantity: type: integer format: int64 minimum: 1 maximum: 99999 description: |- The total SKU quantity available in the warehouse. Valid range: [1, 99,999] Note: This quantity specifically refers to the in-stock inventory that can be shipped immediately. warehouse_id: type: string description: |- The ID of the warehouse where the SKU is stored. Retrieve the list of warehouses available for your shop from the [Get Warehouse List API](https://partner.tiktokshop.com/docv2/page/650aa418defece02be6e66b6). required: - quantity - warehouse_id PartialEditProductRequestSkuPrice: type: object properties: amount: type: string description: |- **Local sellers/Intra-EU sellers** The SKU's **local display price** shown on the product page before any discounts. Refer to [Product Pricing](https://partner.tiktokshop.com/docv2/page/67e1288d76cfee049d9af858) for the allowed price ranges in each market. currency: type: string enum: - BRL - CZK - EUR - GBP - HUF - IDR - JPY - MXN - MYR - PHP - PLN - SGD - THB - USD - VND x-enum-descriptions: - Brazil - Czech Republic - France, Germany, Ireland, Italy, Spain, Netherlands, Belgium, Austria, Greece, Portugal - United Kingdom - Hungary - Indonesia - Japan - Mexico - Malaysia - Philippines - Poland - Singapore - Thailand - United States - Vietnam description: |- The currency. Possible values based on the region: - BRL: Brazil - CZK: Czech Republic - EUR: France, Germany, Ireland, Italy, Spain, Netherlands, Belgium, Austria, Greece, Portugal - GBP: United Kingdom - HUF: Hungary - IDR: Indonesia - JPY: Japan - MXN: Mexico - MYR: Malaysia - PHP: Philippines - PLN: Poland - SGD: Singapore - THB: Thailand - USD: United States - VND: Vietnam sale_price: type: string description: |- **Global sellers** The SKU's **local display price** shown on the product page before any discounts. Refer to [Product Pricing](https://partner.tiktokshop.com/docv2/page/67e1288d76cfee049d9af858) for the allowed price ranges in each market. **Note**: - Applicable for all global sellers. - Required for JP and US shops using China warehouses. Optional for others. - This is the definitive final price shown on the product page, all other prices will be ignored. required: - currency PartialEditProductRequestSkuSalesAttribute: type: object properties: id: type: string description: |- The ID of the sales attribute. This is either a built-in sales attribute ID from [Get Attributes API](https://partner.tiktokshop.com/docv2/page/6509c5784a0bb702c0561cc8) or a custom attribute ID returned after calling [Create Product API](https://partner.tiktokshop.com/docv2/page/6502fc8da57708028b42b18a). name: type: string maxLength: 20 description: |- A self-defined custom sales attribute name if the existing attributes do not satisfy your needs. The system will auto-generate an ID after editing. **Note**: - Do not include sensitive characters. - Max length: 20 characters sku_img: $ref: "#/components/schemas/SkuImg" description: |- The default/main image for each value (e.g. red) of the primary sales attribute (e.g. color). This appears in the product options gallery on TikTok Shop. You can attach images to only 1 type of sales attribute, which will serve as the primary attribute for display. An image must be provided for each value of the primary attribute. For example, if a product has 2 colors and 3 sizes, you can choose to attach images for either the color sales attribute or the size sales attribute. If you choose to attach images for color, you must attach 2 images, one for each color. If you want to add more images, use `supplementary_sku_images`. supplementary_sku_images: type: array items: $ref: "#/components/schemas/SupplementarySkuImage" description: |- A list of supplementary images for each value (e.g. red) of the primary sales attribute (e.g. color) to provide multiple views or details of the product for that attribute value. These appear in the product options gallery on TikTok Shop. **Note**: - Max number of image URIs: 8. - Arrange your image URIs in the sequence that they should appear on TikTok Shop. - Applicable only for the US market. value_id: type: string description: |- The ID of the sales attribute value. This is either a built-in sales attribute value ID from [Get Attributes API](https://partner.tiktokshop.com/docv2/page/6509c5784a0bb702c0561cc8) or a custom sales attribute value ID returned after calling [Create Product API](https://partner.tiktokshop.com/docv2/page/6502fc8da57708028b42b18a). value_name: type: string maxLength: 50 description: |- A self-defined custom sales attribute value if the existing values do not satisfy your needs. The system will auto-generate an ID after editing. **Note**: - No duplicates allowed under the same attribute. - Max length: 50 characters. PartialEditProductRequestSkuSkuDimension: type: object properties: height: type: string description: |- The package height. A positive whole number. Note: For the BR market, decimal values using . or , as separators are also accepted but will be rounded to the nearest whole number. length: type: string description: |- The package length. A positive whole number. Note: For the BR market, decimal values using . or , as separators are also accepted but will be rounded to the nearest whole number. unit: type: string description: |- The unit for the SKU dimensions. Possible values based on region: - US: CENTIMETER, INCH - Other regions: CENTIMETER Note: Use the same measurement system (metric or imperial) for `sku_weight` and `sku_dimensions`. For example, use `KILOGRAM` with `CENTIMETER`. width: type: string description: |- The package width. A positive whole number. Note: For the BR market, decimal values using . or , as separators are also accepted but will be rounded to the nearest whole number. required: - height - length - unit - width PartialEditProductRequestSkuSkuWeight: type: object properties: unit: type: string description: |- The unit for the SKU weight. Possible values based on region: - US: KILOGRAM, POUND - BR, JP, MX: KILOGRAM, GRAM - Other countries: KILOGRAM Note: Use the same measurement system (metric or imperial) for `sku_weight` and `sku_dimensions`. For example, use `KILOGRAM` with `CENTIMETER`. value: type: string description: |- The package weight, which must be a positive number. The number format varies based on the unit: - GRAM: integer - KILOGRAM: up to 3 decimal places - POUND: up to 2 decimal places required: - unit - value PartialEditProductRequestSubscribeInfoEdit: type: object properties: discount_details: type: array items: $ref: "#/components/schemas/DiscountDetail" description: All of the Save and Subscribe discount details. subscribe_status: type: string description: |- An enum outlining whether the given product has an active Subscribe and Save promotion: - ENABLED - NOT_ENABLED This field is required if the subscription is being created or modified. PartialEditProductResponse: 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/PartialEditProductResponseData" PartialEditProductResponseData: type: object properties: audit: $ref: "#/components/schemas/PartialEditProductResponseDataAudit" description: |- Product audit information. **Note**: Applicable only to products listed on TikTok Shop. Not applicable for products listed only on Tokopedia. product_id: type: string description: The product ID generated by TikTok Shop. skus: type: array items: $ref: "#/components/schemas/PartialEditProductResponseDataSku" description: A list of Stock Keeping Units (SKUs) used to identify distinct variants of the product. PartialEditProductResponseDataAudit: type: object properties: status: type: string enum: - NONE - AUDITING - APPROVED x-enum-descriptions: - The product is not applicable for audit because it has not been submitted for listing on this platform, or it is in a draft, frozen, or deactivated state. - The product is currently being audited. - If you only edited the `price` or `inventory` fields of an approved product, the product remains approved and the edits are immediately published on the platform. description: |- The product audit status. Possible values: - NONE: The product is not applicable for audit because it has not been submitted for listing on this platform, or it is in a draft, frozen, or deactivated state. - AUDITING: The product is currently being audited. - APPROVED: If you only edited the `price` or `inventory` fields of an approved product, the product remains approved and the edits are immediately published on the platform. PartialEditProductResponseDataSku: type: object properties: external_sku_id: type: string description: An external identifier used in an external ecommerce platform. This is used to associate the SKU between TikTok Shop and the external ecommerce platform. fees: type: array items: $ref: "#/components/schemas/GetProductResponseDataSkuFee" description: The fees required for this product based on TikTok Shop policies. Fees are required only for certain product categories, retrieve the requirements from the [Get Category Rules API](https://partner.tiktokshop.com/docv2/page/6509c0febace3e02b74594a9). id: type: string description: The SKU ID generated by TikTok Shop. One product can contain multiple SKU IDs. sales_attributes: type: array items: $ref: "#/components/schemas/SalesAttribute" description: A list of attributes (e.g. size, color, length) that define each variant of a product. seller_sku: type: string description: |- An internal code/name for managing SKUs, not visible to buyers. Valid length: - DE, ES, FR, IT, PL, NL, BE, CZ, AT, GR, PT, HU: 6-50 characters - Other regions: 1-50 characters Format: - DE, ES, FR, IT, PL, NL, BE, CZ, AT, GR, PT, HU: Use alphabets, numbers, hyphens (-), or underscores (_) only - Other regions: Text without spaces PartialEditResponsiblePersonRequest: type: object properties: name: type: string maxLength: 200 description: |- The responsible person name to update. Chinese characters are not supported when this field is provided. Max length: 200 characters email: type: string description: The email address of the responsible person to update. Chinese characters are not supported when this field is provided. phone_number: $ref: "#/components/schemas/CreateResponsiblePersonRequestPhoneNumber" description: The phone number of the responsible person to update. Chinese characters are not supported in `local_number` when this object is provided. address: $ref: "#/components/schemas/Address" description: The residential address of the responsible person to update. Chinese characters are not supported in any supplied address field. locale: type: string enum: - de-DE - en-IE - es-ES - fr-FR - it-IT description: |- The BCP-47 locale code representing the language of the responsible person information to update. Possible values: - de-DE - en-IE - es-ES - fr-FR - it-IT Default: The locale of the seller's registered business address. **Note**: Only the language version selected by this locale is updated; other language versions remain unchanged. Ensure the locale matches the language used in the supplied field values. PartialEditResponsiblePersonResponse: 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/PartialEditResponsiblePersonResponseData" PartialEditResponsiblePersonResponseData: type: object properties: {} PartialRefund: type: object properties: currency: type: string description: Refund currency must match the currency of the current return request. amount: type: string description: The partial refund amount seller would like to offer to the buyer PartialRefundAmount: type: object properties: partial_refund_total: type: string description: Partial refund amount. When `decision` is `OFFER_PARTIAL_REFUND_AFTER_RECEIVING_PKG`, this field is required and must be a numeric string representing an amount greater than 0. currency: type: string description: Currency of the partial refund amount. When `decision` is `OFFER_PARTIAL_REFUND_AFTER_RECEIVING_PKG`, this field is required and must match the return order's currency. Payment: type: object properties: currency: type: string description: Currency for payment. sub_total: type: string description: |- Buyer paid subtotal of all the SKUs in the order. For the US market, this is pre-tax total amount. `sub_total` = `original_total_product_price` - `seller_discount` - `platform_discount` shipping_fee: type: string description: |- Buyer paid shipping fee. `shipping_fee` = `original_shipping_fee` - `shipping_fee_seller_discount` - `shipping_fee_platform_discount` For the US market, this is pre-tax total amount. seller_discount: type: string description: Product discount by seller. platform_discount: type: string description: Product discount by platform. payment_platform_discount: type: string description: Discount applied to the order funded by a payment platform payment_discount_service_fee: type: string description: Service fee as paid by the buyer to apply payment platform discount total_amount: type: string description: |- Buyer paid total amount. `total_amount` = `sub_total` + `shipping_fee` + `taxes` + `retail_delivery_fee` original_total_product_price: type: string description: |- Total original price of products (VAT included for crossborder shop). For the US market, this is pre-tax total amount. original_shipping_fee: type: string description: Shipping fee before discount shipping_fee_seller_discount: type: string description: "Shipping fee discount provided by seller for an order that will not qualify for co-funded reimbursement. **Note**: If an order meets the minimum order value for co-funded reimbursement, this will be 0. In this case, refer to `shipping_fee_cofunded_discount` for the shipping discount the buyer received." shipping_fee_platform_discount: type: string description: Shipping fee discount by platform. shipping_fee_cofunded_discount: type: string description: "Shipping fee discount provided by seller, eligible for co-funded reimbursement upon order delivery, based on Co-Funded Free Shipping program terms. **Note**: This will be 0 for orders that did not meet minimum order value for co-funded reimbursement. In this case, refer to `shipping_fee_seller_discount` for the shipping discount the buyer received." tax: type: string description: Buyer paid total taxes of the order. Applicable to crossborder shops and the US market. small_order_fee: type: string description: |- Small order fee for TH. Small order fee is for Thailand only. small order fee means that the platform will set a minimum order spending amount, when the order amount is lower than the minimum order spending amount, the user needs to pay small order fee to meet the platform minimum spending amount. e.g. Minimum order spending amount is 100, order amount is 80. So the small order fee will be 20. shipping_fee_tax: type: string description: The tax on the shipping price. product_tax: type: string description: The tax on the total item price. retail_delivery_fee: type: string description: RDF (retail delivery fee). Available only in the US market. buyer_service_fee: type: string description: A service fee is charged on every transaction made. The charge is applied from the fifth order onwards and collected directly from customers during checkout. Only available in Indonesia market. handling_fee: type: string description: A fee charged to buyers to cover the additional processing, handling, and/or installment costs associated with the chosen payment method. shipping_insurance_fee: type: string description: |- The cost incurred by the buyers for coverage against loss or damage to goods during transit. **Note**: Available only in the Indonesia market. item_insurance_fee: type: string description: |- The cost incurred by the buyers for coverage against defects or damage to the product after purchase. **Note**: Only available in the US and Indonesia markets. item_insurance_tax: type: string description: |- The tax paid on the insurance purchased by buyers. Note: Only applicable in US market. distance_shipping_fee: type: string description: |- Distance shipping fee is fee that charged charged by our logistics partner and covers the separate distance-based cost for deliveries outside Java island as a part of Horizon+ Program. Only applicable in ID Market. distance_fee: type: string description: Total distance fee for Horizon+ Program. Only applicable for ID market PhoneNumber: type: object properties: availability: type: string enum: - AVAILABLE - UNAVAILABLE x-enum-descriptions: - The phone number is available and required. - No phone number is available. description: |- Indicates the availability of the phone number. Possible values: - `AVAILABLE`: The phone number is available and required. - `UNAVAILABLE`: No phone number is available. Default: AVAILABLE country_code: type: string description: |- The country code of the phone number, prefixed by a plus `+` symbol. E.g. +353 for Ireland. Max digits: 4 Required if `availability=AVAILABLE`. local_number: type: string description: |- The local number. Length: 7 - 20 digits Required if `availability=AVAILABLE`. PickupSlot: type: object properties: start_time: type: integer format: int64 description: The start of the package pickup time slot, as a Unix timestamp in seconds. end_time: type: integer format: int64 description: The end of the package pickup time slot, as a Unix timestamp in seconds. PostShoppablePhotosRequest: type: object properties: photos_info: type: array items: $ref: "#/components/schemas/PostShoppablePhotosRequestPhotosInfo" description: Photo Info Metadata music_id: type: string description: Music ID title: type: string description: "Post title:The maximum length is 5000 in UTF-16 runes. If not specified, the ticket post will not have any captions. - You can add relevant hashtags to increase discoverability. The format is simply # followed by the topic name. Multiple hashtags are supported,e.g.,#humor#BFCM" link_info: $ref: "#/components/schemas/PostShoppablePhotosRequestLinkInfo" description: Photo anchor and linking metadata is_ai_generated: type: boolean description: Field to indicate whether the content was AI generated. Marking this field as true will display a tag indicating this post as an AI generated post. required: - photos_info PostShoppablePhotosRequestLinkInfo: type: object properties: post_type: type: string description: 1-LINK_TO_PRODUCT, 2-LINK_TO_SHOP, 3-LINK_TO_ONE_PIC_ONE_PRODUCT shop_info: $ref: "#/components/schemas/PostShoppablePhotosRequestLinkInfoShopInfo" description: Shop Info links: type: array items: $ref: "#/components/schemas/PostShoppablePhotosRequestLinkInfoLink" description: Photo Anchor List required: - post_type PostShoppablePhotosRequestLinkInfoLink: type: object properties: product_id: type: string description: Product ID link_title: type: string maxLength: 29 description: Photo Anchor Title:The title to be shown on the product anchor. Anchor title should be shorter than 30 characters PostShoppablePhotosRequestLinkInfoShopInfo: type: object properties: shop_id: type: string description: Shop ID group_type: type: string description: 1 for shop_home_page, 2 for category, 3 for collection group_id: type: string description: Category ID/Collection ID. Use [Get Shop Category And Collection] to retrieve a valid category_id or collection_id, then set it in this field PostShoppablePhotosRequestPhotosInfo: type: object properties: photo_file_uris: type: string description: Photo file uris, not a file upload. Use [Upload Shoppable Photo File] to upload the image and obtain the photo_file_uri, then pass that URI in this field required: - photo_file_uris PostShoppablePhotosResponse: 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/PostShoppablePhotosResponseData" PostShoppablePhotosResponseData: type: object properties: photo: $ref: "#/components/schemas/PostShoppablePhotosResponseDataPhoto" description: Post shoppable photos response quota: type: string description: Content posting quota for the creator. Returned on successful publish; included in the error message on failure; omitted if no quota restriction applies. PostShoppablePhotosResponseDataPhoto: type: object properties: photo_post_id: type: string description: Photo post ID PostShoppableVideoRequest: type: object properties: video_info: $ref: "#/components/schemas/PostShoppableVideoRequestVideoInfo" description: Video information product_link_info: $ref: "#/components/schemas/ProductLinkInfo" description: Product link information required: - video_info - product_link_info PostShoppableVideoRequestVideoInfo: type: object properties: file_id: type: string description: The video file ID returned by Upload Shoppable Video File (`POST /affiliate_creator/202505/videos/video_files`). title: type: string description: |- The video caption. The maximum length is 2200 in UTF-16 runes. If not specified, the ticket post will not have any captions. cover_uri: type: string description: The video cover image URI returned by Upload Shoppable Photo File (`POST /affiliate_creator/202511/photos/photo_files`). cover_timestamp_ms: type: integer format: int64 description: The input parameter is a timestamp, which specifies a particular moment in the video. The frame at that timestamp will be used as the video cover. If cover_uri and cover_timestamp_ms are both not provided, the cover will default to the first frame of the uploaded video. Only one of cover_uri or cover_timestamp_ms can be provided. If both parameters are passed, cover_uri will take precedence. music_id: type: string description: The music ID for the video's background music. Obtain it from Search Music (`GET /affiliate_creator/202602/music/search`). If not provided, no music will be associated with the video. required: - file_id - title PostShoppableVideoResponse: 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/PostShoppableVideoResponseData" PostShoppableVideoResponseData: type: object properties: video: $ref: "#/components/schemas/PostShoppableVideoResponseDataVideo" description: Submitted shoppable video information. PostShoppableVideoResponseDataVideo: type: object properties: id: type: string description: The video id, use this id to query video publish status. PreSale: type: object properties: type: type: string enum: - PRE_ORDER - MADE_TO_ORDER - CUSTOM x-enum-descriptions: - The product is not yet available or released. Fulfillment can be extended by specifying a release date. - The product is produced only after the order is received. Fulfillment can be extended by specifying a duration. - The product requires a fulfillment timeline that exceeds the standard due to other factors. Fulfillment can be extended by specifying a duration. description: |- The type of pre-sale. Possible values based on the region: **US** - `PRE_ORDER`: The product is not yet available or released. Fulfillment can be extended by specifying a release date. - `MADE_TO_ORDER`: The product is produced only after the order is received. Fulfillment can be extended by specifying a duration. - `CUSTOM`: The product requires a fulfillment timeline that exceeds the standard due to other factors. Fulfillment can be extended by specifying a duration. **UK, EU, SEA, JP, and LATAM** - `PRE_ORDER`: The product is not yet available or released. Fulfillment can be extended by specifying a duration. fulfillment_type: $ref: "#/components/schemas/FulfillmentType" description: |- Information about the type of pre-sale order fulfillment and the corresponding timeframe. - `handling_duration_days` is for fulfillment with an extended duration. - `release_date` is for starting fulfillment on a fixed date. **Note**: Provide either the `handling_duration_days` or the `release_date`, depending on the value of `pre_sale.type` and your shop's region. PredictProductPackageDimensionsAndWeightRequest: type: object properties: category_id: type: string description: The ID of the leaf category selected for the product. required: - category_id PredictProductPackageDimensionsAndWeightResponse: 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/PredictProductPackageDimensionsAndWeightResponseData" PredictProductPackageDimensionsAndWeightResponseData: type: object properties: package_dimensions: $ref: "#/components/schemas/PredictProductPackageDimensionsAndWeightResponseDataPackageDimension" description: Predicted package dimensions for the product. package_weight: $ref: "#/components/schemas/PredictProductPackageDimensionsAndWeightResponseDataPackageWeight" description: Predicted package weight for the product. PredictProductPackageDimensionsAndWeightResponseDataPackageDimension: type: object properties: height: type: integer format: int64 description: Predicted positive package height. length: type: integer format: int64 description: Predicted positive package length. unit: type: string enum: - CENTIMETER - INCH - FOOT - MILLIMETER - METER description: |- Unit of the predicted package dimensions. Possible values: - `CENTIMETER` - `INCH` - `FOOT` - `MILLIMETER` - `METER` width: type: integer format: int64 description: Predicted positive package width. required: - height - length - unit - width PredictProductPackageDimensionsAndWeightResponseDataPackageWeight: type: object properties: unit: type: string enum: - GRAM - POUND - OUNCE - KILOGRAM description: |- Unit of the predicted package weight. Possible values: - `GRAM` - `POUND` - `OUNCE` - `KILOGRAM` value: type: string description: Predicted positive package weight. required: - unit - value Price: type: object properties: amount: type: string description: The SKU price in major units of the currency specified by `currency`, represented as a decimal string. currency: type: string description: The price currency code. PriceDetail: type: object properties: currency: type: string description: Ignore this field. It is not yet supported. refund_total: type: string description: Ignore this field. It is not yet supported. refund_subtotal: type: string description: Ignore this field. It is not yet supported. refund_shipping_fee: type: string description: Ignore this field. It is not yet supported. refund_tax: type: string description: Ignore this field. It is not yet supported. PrintInboundOrderLabelsRequest: type: object properties: order_id: type: string description: |- The numeric identifier of the child inbound order to print labels for. **Note:** Provide the numeric sequence only; do not include the `IBR` prefix (for example, use `123456` instead of `IBR123456`). Do not use an inbound plan ID. print_items: type: array items: type: string enum: - CARTON_PALLET_LABEL - PACKING_PICKING_LIST - FBT_BARCODE x-enum-descriptions: - Identification labels for cartons or pallets. Apply carton labels to at least two adjacent sides of each carton. - Warehouse document for identifying and packing items. - Fulfilled by TikTok barcode labels. description: |- Specifies the types of documents to generate. Multiple values can be included in one combined output. **Allowed Values:** * `CARTON_PALLET_LABEL`: Identification labels for cartons or pallets. Apply carton labels to at least two adjacent sides of each carton. * `PACKING_PICKING_LIST`: Warehouse document for identifying and packing items. * `FBT_BARCODE`: Fulfilled by TikTok barcode labels. **Note:** If this list is empty or omitted, `CARTON_PALLET_LABEL` is generated by default. carton_label_format: type: string enum: - DEFAULT_1UP - A4_4UP x-enum-descriptions: - Standard format (1 label per page). - A4 paper format (4 labels per page). description: |- Specifies the layout and dimensions for the carton labels. If this parameter is omitted or an invalid value is provided, the system will use the default single-label format. **Allowed Values:** * `DEFAULT_1UP`: Standard format (1 label per page). * `A4_4UP`: A4 paper format (4 labels per page). **Note:** If no value is provided, `DEFAULT_1UP` will be used as the default format. barcode_format: type: string description: |- Specifies the layout and dimensions for the generated label PDF. If this parameter is omitted or an invalid value is provided, the system will use the default thermal label format. **Allowed Values:** **Standard / Default** * `DEFAULT_40MM_60MM`: Standard 40mm x 60mm thermal label format **A4 Paper Layouts** * `A4_21UP_60_0MM_40_0MM`: 21-up labels (60.0mm x 40.0mm) on A4 * `A4_21UP_63_5MM_38_1MM`: 21-up labels (63.5mm x 38.1mm) on A4 * `A4_24UP_63_5MM_33_9MM`: 24-up labels (63.5mm x 33.9mm) on A4 * `A4_24UP_64_6MM_33_8MM`: 24-up labels (64.6mm x 33.8mm) on A4 * `A4_24UP_66_0MM_33_9MM`: 24-up labels (66.0mm x 33.9mm) on A4 * `A4_24UP_66_0MM_35_0MM`: 24-up labels (66.0mm x 35.0mm) on A4 * `A4_24UP_70_0MM_36_0MM`: 24-up labels (70.0mm x 36.0mm) on A4 * `A4_24UP_70_0MM_37_0MM`: 24-up labels (70.0mm x 37.0mm) on A4 * `A4_27UP_63_5MM_29_6MM`: 27-up labels (63.5mm x 29.6mm) on A4 * `A4_40UP_52_5MM_29_7MM`: 40-up labels (52.5mm x 29.7mm) on A4 * `A4_44UP_48_5MM_25_4MM`: 44-up labels (48.5mm x 25.4mm) on A4 **US Letter Layouts** * `US_LETTER_30UP_1IN_2_625IN`: 30-up labels (1" x 2-5/8") on US Letter **Note:** If no value is provided, `DEFAULT_40MM_60MM` will be used as the default format. required: - order_id PrintInboundOrderLabelsResponse: 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/PrintInboundOrderLabelsResponseData" PrintInboundOrderLabelsResponseData: type: object properties: download_url: type: string description: |- URL containing labels for the inbound order. **Please note: the URL will be unicode-escaped. If attempting to manually paste the URL into a browser, you will need to unescape the URL first (e.g. '\u0026'->'&')** task_status: type: string description: |- * `PROCESSING`: Task is currently being processed. Continue to periodically poll. * `SUCCESS`: Task is finished. `download_url` should be included in response Product: type: object properties: toko_pid: type: integer format: int64 description: product id in tokopedia format tts_pid: type: integer format: int64 description: product id in tts format ProductAttribute: type: object properties: id: type: string description: The ID of the product attribute, retrieved from the [Get Attributes API](https://partner.tiktokshop.com/docv2/page/6509c5784a0bb702c0561cc8). values: type: array items: $ref: "#/components/schemas/Value" description: |- A list of selectable values for the product attribute. **Note**: Provide either a built-in ID or a custom name; if both are provided, the ID takes priority. required: - id - values ProductAuditStatusChangeWebhook: type: object properties: type: type: integer const: 37 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/ProductAuditStatusChangeWebhookData" required: - type ProductAuditStatusChangeWebhookData: type: object properties: product_id: type: integer format: int64 description: The ID of the product. audit: $ref: "#/components/schemas/ProductAuditStatusChangeWebhookDataAudit" description: The product audit information. integrated_platform_statuses: $ref: "#/components/schemas/ProductAuditStatusChangeWebhookDataIntegratedPlatformStatus" description: The current audit status of the product on platforms that are natively integrated with TikTok Shop (e.g. TOKOPEDIA). update_time: type: integer format: int64 description: The time when the status changed, represented as a Unix timestamp (seconds). ProductAuditStatusChangeWebhookDataAudit: type: object properties: status: type: string enum: - NONE - AUDITING - FAILED - PRE_APPROVED - APPROVED x-enum-descriptions: - The product is not applicable for audit because it has not been submitted for listing on this platform, or it is in a draft, frozen, or deactivated state. - The product is currently being audited. - The product failed the audit, or the audit was cancelled. - The product has passed the audit but is not yet listed due to pending prerequisites. Refer to `pre_approved_reasons` for the prerequisites. - The product passed the audit and has been listed on the platform. description: |- The product audit status. Possible values: * NONE: The product is not applicable for audit because it has not been submitted for listing on this platform, or it is in a draft, frozen, or deactivated state. * AUDITING: The product is currently being audited. * FAILED: The product failed the audit, or the audit was cancelled. * PRE_APPROVED: The product has passed the audit but is not yet listed due to pending prerequisites. Refer to `pre_approved_reasons` for the prerequisites. * APPROVED: The product passed the audit and has been listed on the platform. pre_approved_reasons: type: array items: type: string enum: - KYC_PENDING - RESTRICTED_CATEGORY_PENDING x-enum-descriptions: - The seller's onboarding (KYC - Know Your Customer information) is incomplete or awaiting processing. - Applicable only for the US market. The product is in a restricted category, and category approval is still pending. To request access, submit an application through the Qualification Center on TikTok Shop Seller Center. description: |- The reason why the audit status of the product is `PRE_APPROVED`. Possible values: * KYC_PENDING: The seller's onboarding (KYC - Know Your Customer information) is incomplete or awaiting processing. * RESTRICTED_CATEGORY_PENDING: Applicable only for the US market. The product is in a restricted category, and category approval is still pending. To request access, submit an application through the Qualification Center on TikTok Shop Seller Center. ProductAuditStatusChangeWebhookDataIntegratedPlatformStatus: type: object properties: platform: type: string enum: - TOKOPEDIA description: |- The integrated platform name. Possible values: * TOKOPEDIA. status: type: string enum: - NONE - AUDITING - FAILED - APPROVED x-enum-descriptions: - The product is not applicable for audit because it has not been submitted for listing on this platform, or it is in a draft, frozen, or deactivated state. - The product is currently being audited. - The product failed the audit or the audit was cancelled. - The product passed the audit and has been listed on the platform. description: |- The product audit status. Possible values: * NONE: The product is not applicable for audit because it has not been submitted for listing on this platform, or it is in a draft, frozen, or deactivated state. * AUDITING: The product is currently being audited. * FAILED: The product failed the audit or the audit was cancelled. * APPROVED: The product passed the audit and has been listed on the platform. ProductCardAttributedGmv: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). ProductCategoryChangeWebhook: type: object properties: type: type: integer const: 18 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/ProductCategoryChangeWebhookData" required: - type ProductCategoryChangeWebhookData: type: object properties: product_id: type: string description: ID of the product promoted in the creator's video. previous_category_id: type: string description: The category ID of the product before the category update. current_category_id: type: string description: The category ID of the product after the category update. update_time: type: integer format: int64 description: The time when this category update happens, represented by Unix timestamp. ProductCreationWebhook: type: object properties: type: type: integer const: 16 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/ProductCreationWebhookData" required: - type ProductCreationWebhookData: type: object properties: product_id: type: integer format: int64 description: The identification of a TikTok Shop product product_types: type: array items: type: string description: |- The type of product, including: * COMBINED_PRODUCT: Virtual bundle product. * GPR_PRODUCT: Target products created using the GPR tool update_time: type: integer format: int64 description: The time when the product was created, represented as a Unix timestamp (seconds). ProductFamily: type: object properties: id: type: string description: The product family ID. products: type: array items: $ref: "#/components/schemas/ProductFamilyProduct" description: A list of products that belong to the family. ProductFamilyProduct: type: object properties: id: type: string description: The product ID. ProductImage: type: object properties: url: type: string description: Ignore this field. It is not yet supported. width: type: integer format: int64 description: Ignore this field. It is not yet supported. height: type: integer format: int64 description: Ignore this field. It is not yet supported. ProductInformationChangeWebhook: type: object properties: type: type: integer const: 15 description: The ID of the webhook type. tts_notification_id: type: string description: The ID of this webhook notification. shop_id: type: string description: The shop ID. timestamp: type: integer format: int64 description: The time when this webhook is triggered. Unix timestamp. data: $ref: "#/components/schemas/ProductInformationChangeWebhookData" required: - type ProductInformationChangeWebhookData: type: object properties: product_id: type: string description: The ID of the product that's being changed. change_source: type: string enum: - SELLER_CENTER - OPEN_API description: |- The originating source of the change. Possible values: - `SELLER_CENTER` - `OPEN_API` changed_fields: type: array items: type: string enum: - title - description - main_images - product_attributes - size_chart_image - size_chart_template - others x-enum-descriptions: - The product name was changed. - The product description was changed. - Product images that appear in the image gallery were added, removed, or changed. - Product attributes were added, removed, or edited. - The size chart image was added, removed, or changed. - The associated size chart template was removed or its details were edited, or a new size chart template was associated. - Other product properties not specified above were changed. description: |- The product properties that were changed. Possible values: - `title`: The product name was changed. - `description`: The product description was changed. - `main_images`: Product images that appear in the image gallery were added, removed, or changed. - `product_attributes`: Product attributes were added, removed, or edited. - `size_chart_image`: The size chart image was added, removed, or changed. - `size_chart_template`: The associated size chart template was removed or its details were edited, or a new size chart template was associated. - `others`: Other product properties not specified above were changed. update_time: type: integer format: int64 description: The time when the change occurred. Unix timestamp. ProductLinkInfo: type: object properties: product_id: type: string description: |- Use product_id to bind the product with the video. The product_id from [Get Shop Products](https://api/affiliate_creator/202509/shop_products) or [Get Showcase Products](https://api/affiliate_creator/202405/showcases/products) title: type: string maxLength: 29 description: The title to be shown on the product anchor. Anchor title should be shorter than 30 characters. Titles may be rejected for punctuation, emoji, or offensive language. required: - product_id - title ProductPackageRecommendedWebhook: type: object properties: type: type: integer const: 62 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 of the seller. To get the value, see [Authorization overview](https://partner.tiktokshop.com/docv2/page/678e3a3292b0f40314a92d75). timestamp: type: integer format: int64 description: The UNIX timestamp when this webhook was triggered. data: $ref: "#/components/schemas/ProductPackageRecommendedWebhookData" required: - type ProductPackageRecommendedWebhookData: type: object properties: product_id: type: string description: The product ID generated by TikTok Shop. abnormality_types: type: array items: type: string description: |- List of current anomaly types. Return ["None"] if status is NORMAL. weight_recommendation: $ref: "#/components/schemas/ProductPackageRecommendedWebhookDataWeightRecommendation" description: Weight correction recommendation. dimension_recommendation: $ref: "#/components/schemas/ProductPackageRecommendedWebhookDataDimensionRecommendation" description: Dimension correction recommendation. ProductPackageRecommendedWebhookDataDimensionRecommendation: type: object properties: unit: type: string description: Recommended value unit length: $ref: "#/components/schemas/ProductPackageRecommendedWebhookDataDimensionRecommendationLength" description: Recommended values for length. width: $ref: "#/components/schemas/ProductPackageRecommendedWebhookDataDimensionRecommendationWidth" description: Recommended values for width. height: $ref: "#/components/schemas/ProductPackageRecommendedWebhookDataDimensionRecommendationHeight" description: Recommended values for height. ProductPackageRecommendedWebhookDataDimensionRecommendationHeight: type: object properties: min_value: type: string description: "Recommended range minimum; unit: cm" max_value: type: string description: "Recommended range maximum; unit: cm" ProductPackageRecommendedWebhookDataDimensionRecommendationLength: type: object properties: min_value: type: string description: "Recommended range minimum; unit: cm" max_value: type: string description: "Recommended range maximum.unit: cm" ProductPackageRecommendedWebhookDataDimensionRecommendationWidth: type: object properties: min_value: type: string description: "Recommended range minimum; unit: cm" max_value: type: string description: "Recommended range maximum.unit: cm" ProductPackageRecommendedWebhookDataWeightRecommendation: type: object properties: unit: type: string description: Recommended value unit weight: $ref: "#/components/schemas/ProductPackageRecommendedWebhookDataWeightRecommendationWeight" description: Recommended values for weight. ProductPackageRecommendedWebhookDataWeightRecommendationWeight: type: object properties: min_value: type: string description: "Recommended range minimum; unit: g" max_value: type: string description: "Recommended range maximum; unit: g" ProductStatusChangeWebhook: type: object properties: type: type: integer const: 5 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/ProductStatusChangeWebhookData" required: - type ProductStatusChangeWebhookData: type: object properties: product_id: type: integer format: int64 description: The identification of a TikTok Shop product status: type: string enum: - PRODUCT_FIRST_PASS_REVIEW - PRODUCT_STATUS_CHANGED - PRODUCT_AUDIT_FAILURE description: |- Product audit status, with possible values: * PRODUCT_FIRST_PASS_REVIEW * PRODUCT_STATUS_CHANGED * PRODUCT_AUDIT_FAILURE suspended_reason: type: string description: The reason a product audit was rejected or frozen update_time: type: integer format: int64 description: The time when the status changed, represented as a Unix timestamp (seconds). ProductTagOperation: type: object properties: product_tag: type: string enum: - AUCTION description: "Possible values: AUCTION" enable: type: boolean description: Whether to enable the specified product tag. Set to `true` to enable the `AUCTION` tag or `false` to disable it. required: - product_tag - enable PublishAffiliatePartnerCampaignRequest: type: object properties: {} PublishAffiliatePartnerCampaignResponse: 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/PublishAffiliatePartnerCampaignResponseData" PublishAffiliatePartnerCampaignResponseData: type: object properties: {} PublishGlobalProductRequest: type: object properties: publish_target: type: array items: $ref: "#/components/schemas/PublishGlobalProductRequestPublishTarget" description: Target markets for publishing global products. required: - publish_target PublishGlobalProductRequestPublishTarget: type: object properties: region: type: string enum: - AT - BE - CZ - DE - ES - FR - GB - GR - HU - ID - IE - IT - JP - MY - NL - PH - PO - PT - SG - TH - US - VN - MX x-enum-descriptions: - Austria - Belgium - Czech Republic - Germany - Spain - France - United Kingdom - Greece - Hungary - Indonesia - Ireland - Italy - Japan - Malaysia - Netherlands(NL) - Philippines - Poland - Portugal - Singapore - Thailand - United States - Vietnam - Mexico description: |- The new market where you want to publish the global product. Possible values: - AT: Austria - BE:Belgium - CZ:Czech Republic - DE: Germany - ES: Spain - FR: France - GB: United Kingdom - GR: Greece - HU:Hungary - ID: Indonesia - IE: Ireland - IT: Italy - JP: Japan - MY: Malaysia - NL: Netherlands(NL) - PH: Philippines - PO: Poland - PT:Portugal - SG: Singapore - TH: Thailand - US: United States - VN: Vietnam - MX: Mexico responsible_person_ids: type: array items: type: string description: |- A list of responsible person IDs. Retrieve the IDs from the [Search Responsible Persons API](67066a55f17b7d02f95d2fb1). Default: The IDs provided when the global product was created. **Note**: Applicable only for the EU market in certain categories. Use the [Get Global Category Rules API](650a056df1fd3102b91b5b8e) to check the requirements. manufacturer_ids: type: array items: type: string description: |- A list of manufacturer IDs. Retrieve the IDs from the [Search Manufacturers API](67066a580dcee902fa03ccf9). Default: The IDs provided when the global product was created. **Note**: Applicable only for the EU market in certain categories. Use the [Get Global Category Rules API](650a056df1fd3102b91b5b8e) to check the requirements. skus: type: array items: $ref: "#/components/schemas/PublishGlobalProductRequestPublishTargetSku" description: |- The SKUs to be published in the specified market. - Max SKUs for EU, JP, UK, US: 300 - Max SKUs for other regions: 100 required: - region - skus PublishGlobalProductRequestPublishTargetSku: type: object properties: related_global_sku_id: type: string description: |- The global SKU ID to be published. After publishing, a corresponding local product SKU will be created and linked to the global SKU. price: $ref: "#/components/schemas/PartialEditProductRequestSkuPrice" description: |- The SKU's local pricing information in the specified market. **Note**: - Provide this only if you want to manually override the default local prices, which are automatically calculated from the global uniform price. - Specify either `amount` or `sale_price`, the other will be auto-filled. If both are provided, `sale_price` takes precedence. - JP and US shops using China warehouses must provide `price.sale_price`. inventory: $ref: "#/components/schemas/PublishGlobalProductRequestPublishTargetSkuInventory" description: |- SKU inventory information per warehouse. Required for sellers without multiple warehouses, optional for others. **Note**: If inventory details are not provided, the global SKU quantity will be evenly split among all markets, and any surplus will be added to the last published product SKU. fees: type: array items: $ref: "#/components/schemas/Fee" description: The fees required for this product based on TikTok Shop policies. Fees are required only for certain product categories, retrieve the requirements from the [Get Category Rules API](https://partner.tiktokshop.com/docv2/page/6509c0febace3e02b74594a9). required: - related_global_sku_id PublishGlobalProductRequestPublishTargetSkuInventory: type: object properties: warehouse_id: type: string description: |- The warehouse ID. Retrieve this value from the [Get Warehouse List API](https://partner.tiktokshop.com/docv2/page/650aa418defece02be6e66b6). Default: - Sellers without multiple warehouses: The available warehouses will be used, prioritizing local warehouses in the specified market over warehouses in the seller's base country. - Sellers with multiple warehouses: The global warehouse ID quantity: type: integer format: int64 minimum: 1 maximum: 99999 description: |- The SKU quantity available in the warehouse. Valid range: [1, 99,999] **Note**: If the local SKU inventory quantity exceeds the global SKU quantity, the global SKU quantity will be updated to be the sum of all local inventories. PublishGlobalProductResponse: 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/PublishGlobalProductResponseData" PublishGlobalProductResponseData: type: object properties: products: type: array items: $ref: "#/components/schemas/PublishGlobalProductResponseDataProduct" description: The local products converted from the global product. Match each item to its publication result in `publish_result` by `region`. A region can have a `publish_result` item without a corresponding local product when its status is `FAILED`. publish_result: type: array items: $ref: "#/components/schemas/PublishResult" description: Results of publishing the global product. PublishGlobalProductResponseDataProduct: type: object properties: region: type: string enum: - AT - BE - CZ - DE - ES - FR - GB - GR - HU - ID - IE - IT - JP - MY - NL - PH - PO - PT - SG - TH - US - VN - MX x-enum-descriptions: - Austria - Belgium - Czech Republic - Germany - Spain - France - United Kingdom - Greece - Hungary - Indonesia - Ireland - Italy - Japan - Malaysia - Netherlands(NL) - Philippines - Poland - Portugal - Singapore - Thailand - United States - Vietnam - Mexico description: |- The market of this local product. Possible values: - AT: Austria - BE:Belgium - CZ:Czech Republic - DE: Germany - ES: Spain - FR: France - GB: United Kingdom - GR: Greece - HU:Hungary - ID: Indonesia - IE: Ireland - IT: Italy - JP: Japan - MY: Malaysia - NL: Netherlands(NL) - PH: Philippines - PO: Poland - PT:Portugal - SG: Singapore - TH: Thailand - US: United States - VN: Vietnam - MX: Mexico shop_id: type: string description: The ID of the local shop in the specified market. One market can only have one local shop. skus: type: array items: $ref: "#/components/schemas/PublishGlobalProductResponseDataProductSku" description: The newly created local SKUs in the specified market. id: type: string description: The newly generated local product ID. PublishGlobalProductResponseDataProductSku: type: object properties: related_global_sku_id: type: string description: The associated global SKU ID. id: type: string description: The newly generated local SKU ID. seller_sku: type: string description: An internal code/name for managing SKUs, not visible to buyers. sale_attributes: type: array items: $ref: "#/components/schemas/PublishGlobalProductResponseDataProductSkuSaleAttribute" description: A list of attributes (e.g. size, color, length) that define each variant of a product. PublishGlobalProductResponseDataProductSkuSaleAttribute: type: object properties: id: type: string description: The newly generated local sales attribute ID. value_id: type: string description: The newly generated local sales attribute value ID. PublishResult: type: object properties: region: type: string enum: - AT - BE - CZ - DE - ES - FR - GB - GR - HU - ID - IE - IT - JP - MY - NL - PH - PO - PT - SG - TH - US - VN - MX x-enum-descriptions: - Austria - Belgium - Czech Republic - Germany - Spain - France - United Kingdom - Greece - Hungary - Indonesia - Ireland - Italy - Japan - Malaysia - Netherlands (NL) - Philippines - Poland - Portugal - Singapore - Thailand - United States - Vietnam - Mexico description: |- The market associated with this synchronization result. Possible values: - AT: Austria - BE: Belgium - CZ: Czech Republic - DE: Germany - ES: Spain - FR: France - GB: United Kingdom - GR: Greece - HU: Hungary - ID: Indonesia - IE: Ireland - IT: Italy - JP: Japan - MY: Malaysia - NL: Netherlands (NL) - PH: Philippines - PO: Poland - PT: Portugal - SG: Singapore - TH: Thailand - US: United States - VN: Vietnam - MX: Mexico status: type: string enum: - SUCCESS - DRAFT - FAILED x-enum-descriptions: - The global product was successfully synchronized to the local shop, submitted for listing, and is now under review. Use the [Product Status Change webhook](https://partner.tiktokshop.com/docv2/page/650956aff1fd3102b90b6261) to track the final audit status. - Synchronization did not complete, and the local product remains in draft. - Synchronization of the global product to the local shop was unsuccessful. description: |- The status of syncing the product to the market. Possible values: - SUCCESS: The global product was successfully synchronized to the local shop, submitted for listing, and is now under review. Use the [Product Status Change webhook](https://partner.tiktokshop.com/docv2/page/650956aff1fd3102b90b6261) to track the final audit status. - DRAFT: Synchronization did not complete, and the local product remains in draft. - FAILED: Synchronization of the global product to the local shop was unsuccessful. fail_reasons: type: array items: $ref: "#/components/schemas/FailReason" description: The list of errors that occurred. PurchaseOrderQuantityLimit: type: object properties: maximum_order_quantity: type: integer format: int64 description: |- The maximum purchase quantity per order for each product variation (SKU). For example: If you set a maximum limit of 2 for a product with 5 variations (SKUs), the customer can purchase up to 2 of each SKU, for a total of 10 items per order. cumulative_order_quantity: type: integer format: int64 description: |- · The total quantity a customer can buy of a product's variations (SKUs) across all orders, while the limit is active. Clearing the limit will reset their past purchases, allowing them to buy again up to the new limit, or without restriction if no limit is set. • For example, if you set a total limit of 2 for a product with 5 variations (SKUs), the customer can buy up to 2 of each SKU, for a total of 10 items across multiple purchases. After that, they can't buy more unless you clear the limits.The total limit must be more than or equal to the maximum limit. QueryCreatorPromotionDetailsInTargetCollaborationRequest: type: object properties: creator_user_open_id: type: string description: Creator open id invitation_group_id: type: string description: Invitation Group Id query: type: string description: Product ID or product title to match, as selected by `query_type`. Provide both fields to filter the returned products. query_type: type: string enum: - PRODUCT_ID - PRODUCT_NAME x-enum-descriptions: - Match the product ID exactly. - Match product titles by case-sensitive substring. description: |- Specifies how `query` filters products. Possible values: - `PRODUCT_ID`: Match the product ID exactly. - `PRODUCT_NAME`: Match product titles by case-sensitive substring. invitation_id: type: string description: Creator Invitation Id product_filter: $ref: "#/components/schemas/QueryCreatorPromotionDetailsInTargetCollaborationRequestProductFilter" description: Product Fitler required: - creator_user_open_id - invitation_group_id QueryCreatorPromotionDetailsInTargetCollaborationRequestProductFilter: type: object properties: added_types: type: array items: type: string description: |- Product added type list, support status: -ALL: all status -ADDED: creator added product NOT_ADDED: creator not added product QueryCreatorPromotionDetailsInTargetCollaborationResponse: 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/QueryCreatorPromotionDetailsInTargetCollaborationResponseData" QueryCreatorPromotionDetailsInTargetCollaborationResponseData: type: object properties: data: $ref: "#/components/schemas/QueryCreatorPromotionDetailsInTargetCollaborationResponseDataData" description: Promotion details for products in the target collaboration invitation group. QueryCreatorPromotionDetailsInTargetCollaborationResponseDataData: type: object properties: product_details: type: array items: $ref: "#/components/schemas/QueryCreatorPromotionDetailsInTargetCollaborationResponseDataDataProductDetail" description: Product detail infomation QueryCreatorPromotionDetailsInTargetCollaborationResponseDataDataProductDetail: type: object properties: product_base_info: $ref: "#/components/schemas/QueryCreatorPromotionDetailsInTargetCollaborationResponseDataDataProductDetailProductBaseInfo" description: Product basic infomation product_add_status: type: boolean description: Product added or not video_count: type: integer format: int64 description: Creator post video count in collaboration live_count: type: integer format: int64 description: Creator LIVE count in collaboration is_commission_effective: type: boolean description: Whether the target collaboration commission for this creator-product pair is currently effective. `false` means an active campaign collaboration takes precedence. QueryCreatorPromotionDetailsInTargetCollaborationResponseDataDataProductDetailProductBaseInfo: type: object properties: product_id: type: string description: Product ID title: type: string description: Product titile image: $ref: "#/components/schemas/QueryCreatorPromotionDetailsInTargetCollaborationResponseDataDataProductDetailProductBaseInfoImage" description: Product Image price: $ref: "#/components/schemas/QueryCreatorPromotionDetailsInTargetCollaborationResponseDataDataProductDetailProductBaseInfoPrice" description: Product Price promotion_price: $ref: "#/components/schemas/QueryCreatorPromotionDetailsInTargetCollaborationResponseDataDataProductDetailProductBaseInfoPromotionPrice" description: Product promotion price target_commission: type: integer format: int64 description: Product target collaboration commission. e.g. 2200 mean 22% commission rate open_commission: type: integer format: int64 description: Product open collaboration commission. e.g. 2200 mean 22% commission rate target_ads_commission: type: integer format: int64 description: Product target ads collaboration commission old_target_commission: type: integer format: int64 description: Product old target collaboration commission old_target_ads_commission: type: integer format: int64 description: Product old target ads collaboration commission commission_effective_time: type: integer format: int64 description: Unix timestamp in milliseconds when the target collaboration commission becomes effective. ads_commission_effective_time: type: integer format: int64 description: Unix timestamp in milliseconds when the target collaboration Ads commission becomes effective. product_status: type: string description: |- Product status 1: Active 2; Sold out 3: product deactivated by seller; 4: product deactivated by platform 5: product reject 6: product deleted QueryCreatorPromotionDetailsInTargetCollaborationResponseDataDataProductDetailProductBaseInfoImage: type: object properties: url: type: string description: Product Image URL QueryCreatorPromotionDetailsInTargetCollaborationResponseDataDataProductDetailProductBaseInfoPrice: type: object properties: min_price: $ref: "#/components/schemas/MinPrice" description: Product min price max_price: $ref: "#/components/schemas/MaxPrice" description: Product max price QueryCreatorPromotionDetailsInTargetCollaborationResponseDataDataProductDetailProductBaseInfoPromotionPrice: type: object properties: min_price: $ref: "#/components/schemas/MinPrice" description: Product promotion min price max_price: $ref: "#/components/schemas/MaxPrice" description: Product promotion max price QueryGoodsInventoryForMCFRequest: type: object properties: goods: type: array items: $ref: "#/components/schemas/QueryGoodsInventoryForMCFRequestGood" description: Goods to query. The array must contain 1 to 50 entries. required: - goods QueryGoodsInventoryForMCFRequestGood: type: object properties: goods_id: type: string description: The Fulfilled by TikTok goods ID. The value must represent a positive integer. required: - goods_id QueryGoodsInventoryForMCFResponse: 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/QueryGoodsInventoryForMCFResponseData" QueryGoodsInventoryForMCFResponseData: type: object properties: goods_inventory_list: type: array items: $ref: "#/components/schemas/QueryGoodsInventoryForMCFResponseDataGoodsInventoryList" description: Inventory entries for the requested goods. For MCF, only goods associated with the seller for the shop region and having an inventory-group result are returned. A requested goods ID without an inventory-group result is omitted; the API does not add an entry with `available_qty` set to `0`. The list is empty when none of the requested goods has an inventory-group result. Each entry represents one goods-and-inventory-group result, so the same `goods_id` may appear in multiple entries when it has multiple inventory groups. Request goods IDs are not deduplicated; repeating a `goods_id` may repeat the same inventory-group entries. Include each `goods_id` only once, and do not align response entries with request entries by list position. QueryGoodsInventoryForMCFResponseDataGoodsInventoryList: type: object properties: goods_id: type: string description: The identifiers for goods generated by Fulfilled by TikTok system. available_qty: type: integer format: int64 description: Available inventory of goods QueryOrderLine: type: object properties: order_line_id: type: string description: The unique identifier of the order line item. product_id: type: string description: The unique identifier of the product. sku_id: type: string description: The unique identifier of the sku. pod_order_data_id: type: string description: The unique identifier of the pod data. required: - order_line_id - product_id - sku_id - pod_order_data_id QueryTargetCollaborationDetailResponse: 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/QueryTargetCollaborationDetailResponseData" QueryTargetCollaborationDetailResponseData: type: object properties: target_collaboration: $ref: "#/components/schemas/QueryTargetCollaborationDetailResponseDataTargetCollaboration" description: Target Collaboration detail. QueryTargetCollaborationDetailResponseDataTargetCollaboration: type: object properties: id: type: string description: Target collaboration ID. name: type: string description: Target collaboration name. message: type: string description: Message seller has sent to creators about seller's introduction and why excited to collaborate. seller_contact_info: $ref: "#/components/schemas/SellerContactInfo" description: Contact information for the seller in the target collaboration. start_time: type: integer format: int64 description: The start time of the target collaboration, as a Unix timestamp in seconds. end_time: type: integer format: int64 description: The end time of the target collaboration, as a Unix timestamp in seconds. update_time: type: integer format: int64 description: The update time of the target collaboration, as a Unix timestamp in seconds. creator_invited_count: type: integer format: int64 description: |- The count of creators invited in the target collaboration. The count will only include the NORMAL state. showcase_creator_count: type: integer format: int64 description: |- This field indicates the number of creators who added the product to the showcase from target collaboration. The count will only include the NORMAL state. content_creator_count: type: integer format: int64 description: |- The number of creators who posted content featuring products from target collaboration. The count will only include the NORMAL state. product_count: type: integer format: int64 description: |- The count of products added in the target collaboration. The count will only include the NORMAL state. free_sample_rule: $ref: "#/components/schemas/QueryTargetCollaborationDetailResponseDataTargetCollaborationFreeSampleRule" description: The free sample rules set by the seller in the target collaboration. products: type: array items: $ref: "#/components/schemas/QueryTargetCollaborationDetailResponseDataTargetCollaborationProduct" description: The information of products in the target collaboration. creators: type: array items: $ref: "#/components/schemas/QueryTargetCollaborationDetailResponseDataTargetCollaborationCreator" description: The information of creators in the target collaboration. type: type: string description: |- The type of target collaboration. Field values: - STANDARD: The target collaboration is created by sellers manually selecting products and creators. - TOP_CREATOR_PROGRAM: The target collaboration created by seller joining TikTok Shop Top Creator Program, requiring only product submission. QueryTargetCollaborationDetailResponseDataTargetCollaborationCreator: type: object properties: username: type: string description: The TikTok user name. nickname: type: string description: The TikTok nick name. avatar: $ref: "#/components/schemas/Avatar" description: Data associated with the TikTok creator's profile avatar. selection_region: type: string description: The regions in which the creator is eligible to promote products in showcases, videos, and live streams. showcase_product_count: type: integer format: int64 description: |- This field indicates the number of products creator has added to the showcase from target collaboration. The count includes NORMAL and DELETING states. content_product_count: type: integer format: int64 description: |- This field indicates the number of products creator has posted video or live from target collaboration. The count includes NORMAL and DELETING states. collaboration_status: type: string description: |- The status of the creator in the current target cooperation. Field values: - NORMAL: The status of the creator in the current target collaboration is normal. - DELETING: The status of the creator in the current target collaboration is deleting.The creator's product promotion relationship in the DELETING status will end the delayed effectiveness status and flow to the DELETED status at 00:00 the next day. - DELETED: The status of the creator in the current target collaboration is deleted. product_effective_status: type: string description: |- The effectiveness of the target collaboration's product commissions for this creator. Field values: - EFFECTIVE_ALL: The commission is effective for this creator on all products in the target collaboration. - EFFECTIVE_PARTIALLY: The commission is effective for this creator on some products in the target collaboration. - EFFECTIVE_NONE: The commission is not effective for this creator on any products in the target collaboration. Normally, the commission rate for all products under Target Collaboration is effective. If the merchant participates in TOP_CREATOR_PROGRAM, and TOP_CREATOR_PROGRAM includes the current creator and some products, the commission rate will be based on TOP_CREATOR_PROGRAM. The products' commission under the current Target Collaboration will only be partially effective for the creator, corresponding to EFFECTIVE_PARTIALLY status. creator_open_id: type: string description: Creator Open ID. [More details](https://partner.tiktokshop.com/docv2/page/3obfokj6) QueryTargetCollaborationDetailResponseDataTargetCollaborationFreeSampleRule: type: object properties: has_free_sample: type: boolean description: If true, free samples are provided to creators invited to the target collaboration group. is_sample_approval_exempt: type: boolean description: |- If true, creators invited to the target collaboration are exempt from seller review and will automatically be approved for a free sample. Note that if has_free_sample=false, this field will not take effect. QueryTargetCollaborationDetailResponseDataTargetCollaborationProduct: type: object properties: id: type: string description: The product identifier. main_image_url: type: string description: The product image url. title: type: string description: The product name. original_price: $ref: "#/components/schemas/OriginalPrice" description: The original price of the product. commission: $ref: "#/components/schemas/QueryTargetCollaborationDetailResponseDataTargetCollaborationProductCommission" description: Commission info. status: type: string description: |- Product's status. Field values: - LIVE: When the product is normal for sale, return to the LIVE status - OUT_OF_STOCK: When the product is out of stock for the consumer, the OUT_OF_STOCK state is returned - SELLER_DEACTIVATE: When the product is deactivated by the merchant, the SELLER_DEACTIVATE status is returned - PLATFORM_DEACTIVATE: When the product is deactivated by the platform or is not available for sale, the PLATFORM_DEACTIVATE status is returned - GNE_REJECT: When the product is governed or the target collaboration is dismissed, the GNE_REJECT state is returned - DELETE: When the product is deleted, the DELETE status is returned - OTHER: When the product is in an unsaleable state, such as draft, frozen, review, etc, the OTHER status is returned commission_effective_status: type: string description: |- The effectiveness of this product's target collaboration commission across creators. Field values: - EFFECTIVE_ALL: The commission is effective for all creators. - EFFECTIVE_PARTIALLY: The commission is effective for some creators. - EFFECTIVE_NONE: The commission is not effective for any creators. Normally, the commission for a product will be the same for all creators. If the merchant participates in TOP_CREATOR_PROGRAM, and TOP_CREATOR_PROGRAM includes the current product and some creators, the commission rate will be based on TOP_CREATOR_PROGRAM. The product commission under the current Target Collaboration will be effective for some creators, corresponding to EFFECTIVE_PARTIALLY status. collaboration_status: type: string description: |- The status of the product in the current target cooperation. Field values: - NORMAL: The status of the product in the current target collaboration is normal. - DELETING: The status of the product in the current target collaboration is deleting.Product in the DELETING state will end their delayed effectiveness state and move to the DELETED state at 00:00 the next day. - DELETED: The status of the product in the current target collaboration is deleted. QueryTargetCollaborationDetailResponseDataTargetCollaborationProductCommission: type: object properties: rate: type: integer format: int64 description: The commission rate in hundredths of a percent. For example, 3587 is a commission rate of 35.87%. This value must a minimum of 1000. The range of this value is [100, 8000]. effective_time: type: string description: The time when the commission becomes effective, as a Unix timestamp in seconds represented as a string. currency: type: string description: The currency code. minimum_amount: type: string description: The minimum estimated commission amount for all SKUs of this product. maximum_amount: type: string description: The maximum estimated commission amount for all SKUs of this product. shop_ads_commission_rate: type: integer format: int64 description: |- The commission rate applies only to orders generated from ads. If a creator’s video is used as an ad without this rate being set, the resulting orders will instead earn either: - The Shop Ads commission you configured in open collaboration, or - The standard commission defined in this invitation. The commission rate is specified in increments of 1/10,000. For example, 1000 stands for 0.1 or 10%. RMAStatusUpdateWebhook: 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: 65 description: The ID of the webhook type. data: $ref: "#/components/schemas/RMAStatusUpdateWebhookData" required: - type RMAStatusUpdateWebhookData: type: object properties: rma_id: type: string description: Unique identifier of the RMA. aftersales_request_id: type: string description: Parent aftersales request identifier. return_role: type: string enum: - BUYER - SELLER description: |- Role that initiated the return flow. Possible enumerations: * `BUYER` * `SELLER` rma_status: type: string enum: - INIT - AWAITING_BUYER_SHIPPED - RETURN_IN_TRANSIT - PENDING_PACKAGE_REVIEW - PACKAGE_REVIEW_COMPLETED x-enum-descriptions: - The RMA has been created - Awaiting buyer's action to ship the return package with carrier - Buyer has shipped the return and is in transit to the sellers destination warehouse - The return package has been delivered and is pending seller package review. The seller has 2-4 business days SLA to respond with a refund review/decision. Please refer to the latest seller academy document. - The package review lifecycle is complete, and the RMA refund has either been approved or rejected. description: |- Current RMA status. Possible enumerations: * `INIT` = The RMA has been created * `AWAITING_BUYER_SHIPPED` = Awaiting buyer's action to ship the return package with carrier * `RETURN_IN_TRANSIT` = Buyer has shipped the return and is in transit to the sellers destination warehouse * `PENDING_PACKAGE_REVIEW` = The return package has been delivered and is pending seller package review. The seller has **2-4 business days** **SLA** to respond with a refund review/decision. Please refer to the latest seller academy document. * `PACKAGE_REVIEW_COMPLETED` = The package review lifecycle is complete, and the RMA refund has either been approved or rejected. rma_request_create_time: type: integer format: int64 description: Creation time of the RMA in Unix seconds. rma_request_update_time: type: integer format: int64 description: Last update time of the RMA in Unix seconds. RecipientAddressUpdateWebhook: type: object properties: type: type: integer const: 3 description: The ID of the webhook type. 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/RecipientAddressUpdateWebhookData" required: - type RecipientAddressUpdateWebhookData: type: object properties: order_id: type: string description: The identification of a TikTok Shop order update_time: type: integer format: int64 description: The time when recipient address is updated, represented as a Unix timestamp (seconds). RecommendCategoryRequest: type: object properties: category_version: type: string description: |- Filter categories by the category tree version.Possible values based on region: - US, EU and SEA: v2, represents the 7-level category tree. Important: For US, EU and SEA shops, you must pass v2 when using this API. - Other regions: v1, represents the 3-level category tree.Default: v1 description: type: string maxLength: 10000 description: |- The product description in HTML format. **Note**: - 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 `
` tags as images. - Max length: 10,000 characters. - Image guidelines: You must use [TikTok Shop image URLs](6509df95defece02be598a22). Max 30 `` tags, each under 4000px with `src`, `width`, and `height` attributes. **Recommendations**: - If you are syncing a pre-existing description from another platform, include the full HTML source description here. - Provide a detailed description, ideally over 300 characters. - Include 3-5 key selling points, each under 250 characters, with supporting images. - Use 1600x1600 px for the image dimensions. images: type: array items: $ref: "#/components/schemas/DiagnoseAndOptimizeProductRequestSizeChartImage" description: Product images, including gallery images, images that appear in the description, product variant images. include_prohibited_categories: type: boolean description: |- A flag to indicate whether to include matching categories that are prohibited on TikTok Shop. Set this to `true` to identify if the product falls under a category that you can't list on TikTok Shop in any circumstances. **Note**: - Applicable only for BR and MX markets. - Default: `false` listing_platform: type: string enum: - TIKTOK_SHOP - TOKOPEDIA description: |- Recommend categories that belong to the specified platform. Possible values: - TIKTOK_SHOP - TOKOPEDIA Default: TIKTOK_SHOP Applicable only for sellers that migrated from Tokopedia. locale: 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 description: |- The BCP-47 locale codes for displaying category information. Default: The default locale of your shop. Possible values: - `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` origin_platform_product_type: type: string description: The product type defined on the source platform. origin_platform_vendor: type: string description: The product vendor or brand name on the source platform. origin_platform_tags: type: array items: type: string description: Tags associated with the product on the source platform. origin_platform_category: $ref: "#/components/schemas/RecommendCategoryRequestOriginPlatformCategory" description: Category information assigned to the product on the source platform. origin_platform_product_meta_data: $ref: "#/components/schemas/RecommendCategoryRequestOriginPlatformProductMetaData" description: Additional product metadata provided by the source platform. product_title: type: string description: |- The product title. Title length: - DE, ES, FR, IE, IT, JP, UK, US: [1, 255] - BR, MX: [1, 300] - Other regions: [25, 255] is_live_quick: type: boolean description: |- false — NORMAL products true — LIVE_QUICK products. Only seller with the required permissions can creat LIVE_QUICK products. Default: false required: - product_title RecommendCategoryRequestOriginPlatformCategory: type: object properties: id: type: string description: The category ID on the source platform. name: type: string description: The category name on the source platform. full_name: type: string description: The full category path or full category name on the source platform. is_leaf: type: boolean description: Whether the category is a leaf category. is_root: type: boolean description: Whether the category is a root category. RecommendCategoryRequestOriginPlatformProductMetaData: type: object properties: attribute_value_list: type: array items: $ref: "#/components/schemas/RecommendCategoryRequestOriginPlatformProductMetaDataAttributeValueList" description: A list of product metadata attributes and their values. RecommendCategoryRequestOriginPlatformProductMetaDataAttributeValueList: type: object properties: name: type: string description: The metadata attribute name. values: type: array items: type: string description: The values associated with the metadata attribute. RecommendCategoryResponse: 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/RecommendCategoryResponseData" RecommendCategoryResponseData: type: object properties: categories: type: array items: $ref: "#/components/schemas/RecommendCategoryResponseDataCategory" description: The category hierarchy for the recommended leaf category, ordered from the top-level category to the leaf category. leaf_category_id: type: string description: The recommended category ID. This is always a leaf category. RecommendCategoryResponseDataCategory: type: object properties: id: type: string description: The category ID. is_leaf: type: boolean description: |- A flag to indicate if the category is a leaf category. **Note**: You can only create or edit products that belong to a leaf category. level: type: integer format: int64 description: The category level. name: type: string description: The category name. permission_statuses: type: array items: type: string enum: - AVAILABLE - INVITE_ONLY - NON_MAIN_CATEGORY - PROHIBITED x-enum-descriptions: - You have the permission to create products in this category. - This is a restricted category and you do not have permission to use it. Submit an application through the Qualification Center on TikTok Shop Seller Center to gain access. In Seller Center, `INVITE_ONLY` is also known as "restricted". - This category is not in the shop's main category. - This category is prohibited on TikTok Shop. If your product falls under this category, do not attempt to list it, as it will be rejected during audit. Applicable only for BR and MX markets. description: |- The shop's permission status for this category. Possible values: - AVAILABLE: You have the permission to create products in this category. - INVITE_ONLY: This is a restricted category and you do not have permission to use it. Submit an application through the Qualification Center on TikTok Shop Seller Center to gain access. In Seller Center, `INVITE_ONLY` is also known as "restricted". - NON_MAIN_CATEGORY: This category is not in the shop's main category. - PROHIBITED: This category is prohibited on TikTok Shop. If your product falls under this category, do not attempt to list it, as it will be rejected during audit. Applicable only for BR and MX markets. RecommendGlobalCategoriesRequest: type: object properties: product_title: type: string description: |- The product title. Title length: - DE, ES, FR, IE, IT, JP, UK, US: [1, 255] - MX:[1,300] - Other regions: [25, 255] description: type: string maxLength: 10000 description: |- The product description in HTML format. **Note**: - 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 `
` tags as images. - Max length: 10,000 characters. - Image guidelines: You must use [TikTok Shop image URLs](6509df95defece02be598a22). Max 30 `` tags, each under 4000px with `src`, `width`, and `height` attributes. **Recommendations**: - If you are syncing a pre-existing description from another platform, include the full HTML source description here. - Provide a detailed description, ideally over 300 characters. - Include 3-5 key selling points, each under 250 characters, with supporting images. - Use 1600x1600 px for the image dimensions. images: type: array items: $ref: "#/components/schemas/DiagnoseAndOptimizeProductRequestSizeChartImage" description: Product images, including gallery images, images that appear in the description, product variant images. category_version: type: string enum: - v2 - v1 x-enum-descriptions: - "US: represents the 7-level category tree." - "Other regions: represents the 3-level category tree." description: |- The category tree version to use for this product. Possible values based on region: - US: `v2`, represents the 7-level category tree. **Important**: If the seller account contains an active US shop, you must pass `v2` when using this API. - Other regions: `v1`, represents the 3-level category tree. Default: `v1` required: - product_title RecommendGlobalCategoriesResponse: 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/RecommendGlobalCategoriesResponseData" RecommendGlobalCategoriesResponseData: type: object properties: leaf_category_id: type: string description: The recommended category ID. This is always a leaf category. categories: type: array items: $ref: "#/components/schemas/RecommendGlobalCategoriesResponseDataCategory" description: The category hierarchy for the recommended leaf category, ordered from the top-level category to the leaf category. RecommendGlobalCategoriesResponseDataCategory: type: object properties: id: type: string description: The category ID. name: type: string description: The category name. level: type: integer format: int64 description: The category level. is_leaf: type: boolean description: |- A flag to indicate if the category is a leaf category. **Note**: You can only create or edit products that belong to a leaf category. RecommendRequiredProductPropertiesRequest: type: object properties: category_id: type: string description: The ID of the leaf category selected for the product. description: type: string description: Product description used to improve prediction accuracy. Do not include personal data. images: type: array items: $ref: "#/components/schemas/Image" description: Ordered product images used to improve prediction accuracy. Do not include images containing personal data. product_title: type: string description: Product title used to predict required properties. Do not include personal data. sales_properties: type: array items: $ref: "#/components/schemas/RecommendRequiredProductPropertiesRequestSalesProperty" description: Existing standard sales properties that define the product variants and provide additional prediction context. target_property_ids: type: array items: type: string description: Optional property IDs that limit prediction to specific properties. When omitted, no property ID filter is applied. required: - category_id - product_title RecommendRequiredProductPropertiesRequestSalesProperty: type: object properties: id: type: string description: ID of the sales property. values: type: array items: $ref: "#/components/schemas/RecommendRequiredProductPropertiesRequestSalesPropertyValue" description: Existing values selected for the sales property. required: - id - values RecommendRequiredProductPropertiesRequestSalesPropertyValue: type: object properties: id: type: string description: ID of the sales property value. required: - id RecommendRequiredProductPropertiesResponse: 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/RecommendRequiredProductPropertiesResponseData" RecommendRequiredProductPropertiesResponseData: type: object properties: recommended_properties: type: array items: $ref: "#/components/schemas/RecommendRequiredProductPropertiesResponseDataRecommendedProperty" description: Ordered required properties predicted for the product. The array is empty when no property recommendation is available. RecommendRequiredProductPropertiesResponseDataRecommendedProperty: type: object properties: id: type: string description: ID of the recommended property. is_customizable: type: boolean description: Whether the seller can enter a custom value when no recommended value applies. is_multiple_selection: type: boolean description: Whether the seller can select more than one value for the property. is_required: type: boolean description: Whether the property must be provided when the product is created or edited. name: type: string description: Display name of the recommended property for the shop's region. type: type: string enum: - UNSPECIFIED - KEY_PROPERTY - SALES_PROPERTY - PRODUCT_PROPERTY x-enum-descriptions: - The service could not classify the property type. - A key property used to identify the product. - A sales property that defines product variants. - A property that describes the product as a whole. description: |- Type of the recommended property. Possible values: - `UNSPECIFIED`: The service could not classify the property type. - `KEY_PROPERTY`: A key property used to identify the product. - `SALES_PROPERTY`: A sales property that defines product variants. - `PRODUCT_PROPERTY`: A property that describes the product as a whole. values: type: array items: $ref: "#/components/schemas/RecommendRequiredProductPropertiesResponseDataRecommendedPropertyValue" description: Ordered values recommended for the property. The array is empty when the property requires a custom value or no value is recommended. required: - id - is_customizable - is_multiple_selection - is_required - name - type - values RecommendRequiredProductPropertiesResponseDataRecommendedPropertyValue: type: object properties: id: type: string description: ID of the recommended property value. name: type: string description: Display name of the recommended property value for the shop's region. required: - id - name RecommendedCategory: type: object properties: id: type: string description: The ID of the recommended category. local_name: type: string description: The recommended category name in the requested locale. RecoverProductsRequest: type: object properties: product_ids: type: array items: type: string description: |- The product IDs to recover. Max number of IDs: 20. required: - product_ids RecoverProductsResponse: 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/RecoverProductsResponseData" RecoverProductsResponseData: type: object properties: errors: type: array items: $ref: "#/components/schemas/Error" description: The errors for individual products that could not be recovered. Check this list even when the top-level `code` is `0`. RedemptionDuration: type: object properties: type: type: string description: |- Values: - `ABSOLUTE`: the redemption period starts from `start_time` and ends at `end_time`. - `RELATIVE`: the redemption period starts from the time the coupon is claimed and lasts for `relative_time`. start_time: type: integer format: int64 description: The UNIX timestamp, in seconds, at which the redemption period starts, if `type == 'ABSOLUTE'`. end_time: type: integer format: int64 description: The UNIX timestamp, in seconds, at which the redemption period ends, if `type == 'ABSOLUTE'`. relative_time: type: integer format: int64 description: The number of days after coupon claim time for which a coupon is valid to be redeemed, `type = 'RELATIVE'`. ReductionAmount: type: object properties: amount: type: string description: Monetary value of an `AMOUNT_OFF` discount. currency: type: string description: Currency of the discount amount. Refund: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). RefundAmount: type: object properties: currency: type: string description: Payment currency. refund_total: type: string description: Total refund amount to buyer. refund_subtotal: type: string description: Subtotal refund amount to buyer. refund_shipping_fee: type: string description: Shipping fee refund amount to buyer. refund_tax: type: string description: Tax refund amount 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. buyer_service_fee: type: string description: Buyer service fee. RefundSuccessWebhook: 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: 67 description: The ID of the webhook type. data: $ref: "#/components/schemas/RefundSuccessWebhookData" required: - type RefundSuccessWebhookData: type: object properties: aftersales_request_id: type: string description: Parent aftersales request identifier. line_items: type: array items: $ref: "#/components/schemas/RefundSuccessWebhookDataLineItem" description: Line-item level identifiers included in the successful refund. refund_currency: type: string description: Currency of the refunded amount. refund_status: type: string description: Refund result. Current example shows `REFUND_SUCCESS`. refund_timestamp: type: integer format: int64 description: Refund completion time in Unix seconds. refund_total: type: string description: Total refunded amount. rma_id: type: string description: Associated RMA identifier. RefundSuccessWebhookDataLineItem: type: object properties: main_order_id: type: string description: Main forward order identifier. return_line_item_id: type: string description: Return line-item identifier. sku_id: type: string description: SKU identifier. sku_return_request_id: type: string description: SKU-level return request identifier. sub_return_line_item_id: type: string description: Optional child line-item identifier, only applicable for Virtual Bundle returns. RejectCancellationRequest: type: object properties: reject_reason: type: string description: Seller's reason for rejecting the buyer's order cancellation request. Use the [Get Decision Eligibility](https://partner.tiktokshop.com/docv2/page/69844a11eeba77049695c7f6) endpoint to retrieve the currently available rejection reasons for the same cancellation request, and submit the returned rejection reason name in this field. comment: type: string description: Seller's comment on rejection decision. This is where a seller will provide more information about rejecting the request. images: type: array items: $ref: "#/components/schemas/RejectCancellationRequestImage" description: List of images provided by the seller to support seller's decision to reject the order cancellation request. required: - reject_reason RejectCancellationRequestImage: type: object properties: image_id: type: string description: Image ID. mime_type: type: string description: MIME type. height: type: integer format: int64 description: |- Image height. Unit: px width: type: integer format: int64 description: |- Image width. Unit: px required: - image_id RejectCancellationResponse: 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/RejectCancellationResponseData" RejectCancellationResponseData: type: object properties: {} RejectReturnRequest: type: object properties: decision: type: string enum: - REJECT_REFUND - REJECT_RETURN - REJECT_RECEIVED_PACKAGE - REJECT_REPLACEMENT - OFFER_PARTIAL_REFUND_AFTER_RECEIVING_PKG x-enum-descriptions: - seller reject a refund-only request - seller reject the initial return-and-refund request - seller reject return-and-refund request after the buyer has already shipped or handed over the item. - seller reject replacement request - seller offer partial refund regarding to the package item quality check description: |- Seller's decision for the request, available values: - `REJECT_REFUND`: seller reject a refund-only request - `REJECT_RETURN`: seller reject the initial return-and-refund request - `REJECT_RECEIVED_PACKAGE`: seller reject return-and-refund request after the buyer has already shipped or handed over the item. - `REJECT_REPLACEMENT`: seller reject replacement request - `OFFER_PARTIAL_REFUND_AFTER_RECEIVING_PKG`: seller offer partial refund regarding to the package item quality check reject_reason: type: string description: "Seller's reason for rejecting the aftersales request. For `OFFER_PARTIAL_REFUND_AFTER_RECEIVING_PKG`, first call Get Review Decision (`GET /return_refund/202606/review_decision`) for the same aftersales request: pass this request's `return_id` as `return_or_cancel_id` and set `check_decisions` to `OFFER_PARTIAL_REFUND_AFTER_RECEIVING_PKG`. In the response, select the `data.line_items[]` entry for the affected return line item, then select its `decisions[]` entry whose `decision` is `OFFER_PARTIAL_REFUND_AFTER_RECEIVING_PKG`, and submit one of that decision's `available_reject_reasons[].name` values in this field. For other decisions, use the [Get Decision Eligibility](https://partner.tiktokshop.com/docv2/page/69844a11eeba77049695c7f6) endpoint to retrieve the currently available rejection options for the same request and submit the returned rejection reason name. **Note**: Available decisions and rejection reasons depend on the current request status, so retrieve eligibility again before calling this API." comment: type: string description: Seller's comment about the rejection decision. For `OFFER_PARTIAL_REFUND_AFTER_RECEIVING_PKG`, the comment must not exceed 500 characters. images: type: array items: $ref: "#/components/schemas/RejectCancellationRequestImage" description: Images provided by the seller to support the decision. For `OFFER_PARTIAL_REFUND_AFTER_RECEIVING_PKG`, a maximum of 6 images is allowed. partial_refund_amount: $ref: "#/components/schemas/PartialRefundAmount" description: Partial refund amount and currency. Required when `decision` is `OFFER_PARTIAL_REFUND_AFTER_RECEIVING_PKG`. required: - decision - reject_reason RejectReturnResponse: 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/RejectReturnResponseData" RejectReturnResponseData: type: object properties: {} RemoveCreatorFromOpenCollaborationProductRequest: type: object properties: creator_user_open_id: type: string description: Creator Open ID. [More details](https://partner.tiktokshop.com/docv2/page/3obfokj6) product_id: type: string description: The product identifier. required: - creator_user_open_id - product_id RemoveCreatorFromOpenCollaborationProductResponse: 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/RemoveCreatorFromOpenCollaborationProductResponseData" RemoveCreatorFromOpenCollaborationProductResponseData: type: object properties: {} RemoveOpenCollaborationRequest: type: object properties: {} RemoveOpenCollaborationResponse: 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/RemoveOpenCollaborationResponseData" RemoveOpenCollaborationResponseData: type: object properties: terminated_effective_time: type: integer format: int64 description: The Unix timestamp, in seconds, when the open collaboration termination takes effect. This is usually 00:00 on the next day in the shop's time zone. RemovePromotionActivityProductsRequest: type: object properties: product_ids: type: array items: type: string maxItems: 300 description: |- IDs of the products to remove. Max count: 300. sku_ids: type: array items: type: string maxItems: 300 description: |- IDs of the SKUs to remove. Do not specify this field for a product-level activity. Max count: 300. benefit_product_ids: type: array items: type: string description: "IDs of benefit-product relations to remove from a `BUY_MORE_SAVE_MORE` or `BUY_X_GET_Y` activity. Maximum: 100 IDs." exclude_product_ids: type: array items: type: string description: "IDs of excluded-product relations to remove from a SHOP-scoped `BUY_MORE_SAVE_MORE`, `BUY_X_GET_Y`, or `SHIPPING_DISCOUNT` activity. Maximum: 100 IDs." RemovePromotionActivityProductsResponse: 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/RemovePromotionActivityProductsResponseData" RemovePromotionActivityProductsResponseData: type: object properties: activity_id: type: string description: A unique ID that identifies activities. status: type: string enum: - DRAFT - NOT_START - ONGOING - EXPIRED - DEACTIVATED - NOT_EFFECTIVE x-enum-descriptions: - Promotion activities with this status are not available to TikTok users. - Promotion activities with this status are not available to TikTok users until the set activity start time. - Promotion activities with this status are available to TikTok users. - Promotion activities with this status are not available to TikTok users because it has expired. - The activity has been deactivated by the seller and is not available to TikTok users. - The activity is terminated by the platform and is not available to TikTok users. description: |- Activity status. Possible values: - DRAFT: Promotion activities with this status are not available to TikTok users. - NOT_START: Promotion activities with this status are not available to TikTok users until the set activity start time. - ONGOING: Promotion activities with this status are available to TikTok users. - EXPIRED: Promotion activities with this status are not available to TikTok users because it has expired. - DEACTIVATED: The activity has been deactivated by the seller and is not available to TikTok users. - NOT_EFFECTIVE: The activity is terminated by the platform and is not available to TikTok users. update_time: type: integer format: int64 description: The time when the response was generated, as a Unix timestamp in seconds (UTC). RemoveShowcaseProductsRequest: type: object properties: product_ids: type: array items: type: string description: The product IDs to remove from the creator's showcase. Specify at least one product ID. The maximum number of products to delete at once is 200. required: - product_ids RemoveShowcaseProductsResponse: 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/RemoveShowcaseProductsResponseData" RemoveShowcaseProductsResponseData: type: object properties: code: type: integer format: int64 description: The success or failure status code returned in API response. message: type: string description: The success or failure messages are returned in API response. Reasons of failure will be described in the message. request_id: type: string description: Every request generates a unique request_id for logging purposes. RemoveTargetCollaborationRequest: type: object properties: {} RemoveTargetCollaborationResponse: 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/RemoveTargetCollaborationResponseData" RemoveTargetCollaborationResponseData: type: object properties: {} ReplicateProductRequest: type: object properties: inventory_mode: type: string enum: - SHARED - EXCLUSIVE x-enum-descriptions: - Inventory for interconnected products must remain consistent; otherwise, an error is returned. - Inventory for each product can be set independently without affecting the others. description: |- The inventory mode for the source product in the source shop. This field is applicable only to EU markets. Possible values: - SHARED: Inventory for interconnected products must remain consistent; otherwise, an error is returned. - EXCLUSIVE: Inventory for each product can be set independently without affecting the others. If omitted, the inventory mode defaults to EXCLUSIVE. replicate_target: type: array items: $ref: "#/components/schemas/ReplicateProductRequestReplicateTarget" description: Target markets for replicating the local product. ReplicateProductRequestReplicateTarget: type: object properties: certifications: type: array items: $ref: "#/components/schemas/ReplicateProductRequestReplicateTargetCertification" maxItems: 10 description: |- The list of certifications for your product. Max count: 10 As per TikTok Shop guidelines, certifications are required for certain restricted product categories. Retrieve the certification requirements for your product from the [Get Category Rules API](https://partner.tiktokshop.com/docv2/page/6509c0febace3e02b74594a9). Refer to [TikTok Shop Restricted Products Policy](https://seller-us.tiktok.com/university/essay?identity=1&role=1&knowledge_id=3238037484275457&from=policy) for information on product category restrictions. inventory_mode: type: string enum: - SHARED - EXCLUSIVE x-enum-descriptions: - Inventory for interconnected products must remain consistent; otherwise, an error is returned. - Inventory for each product can be set independently without affecting the others. description: |- The inventory mode for the replicated product in this target market. This field is applicable only to EU markets. Possible values: - SHARED: Inventory for interconnected products must remain consistent; otherwise, an error is returned. - EXCLUSIVE: Inventory for each product can be set independently without affecting the others. If omitted, the inventory mode defaults to EXCLUSIVE. manufacturer_ids: type: array items: type: string description: |- A comma-delimited list of manufacturer IDs. Retrieve the IDs from the [Search Manufacturers API](67066a580dcee902fa03ccf9). **Note**: Applicable only for the EU market in certain categories. Use the [Get Category Rules API](6509c0febace3e02b74594a9) to check the requirements. product_attributes: type: array items: $ref: "#/components/schemas/ProductAttribute" description: |- A list of general attributes (e.g. manufacturer, country of origin, materials used) that describe the product as a whole, regardless of variant. **Important**: The attributes available for use are determined by the system based on the product's assigned category, with some being mandatory. You must provide the product attributes marked as `is_required` in the response of the [Get Attributes API](6509c5784a0bb702c0561cc8) to avoid listing failure. region: type: string description: The new market where you want to replicate the product. responsible_person_ids: type: array items: type: string description: |- A comma-delimited list of responsible person IDs. Retrieve the IDs from the [Search Responsible Persons API](67066a55f17b7d02f95d2fb1). **Note**: Applicable only for the EU market in certain categories. Use the [Get Category Rules API](6509c0febace3e02b74594a9) to check the requirements. skus: type: array items: $ref: "#/components/schemas/ReplicateProductRequestReplicateTargetSku" description: |- The SKUs to be published in the specified market. - Max SKUs for EU, JP, UK, US: 300 - Max SKUs for other regions: 100 Note: SKUs of all source country must be included. ReplicateProductRequestReplicateTargetCertification: type: object properties: expiration_date: type: integer format: int64 description: |- The expiration date of this certification expressed in unix timestamp (seconds) UTC+0. This 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. files: type: array items: $ref: "#/components/schemas/ReplicateProductRequestReplicateTargetCertificationFile" description: A list of certification related files. id: type: string description: |- The ID to identify the type of certification required for the product category. Retrieve 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. required: - id ReplicateProductRequestReplicateTargetCertificationFile: type: object properties: format: type: string description: The format of the certification file. Only PDF is supported. id: type: string description: |- The ID of the certification file. Use the [Upload Product File API](https://partner.tiktokshop.com/docv2/page/6509dffdc16ffe02b8dc10c5) to upload the files first and obtain the corresponding file ID. name: type: string description: The name of the certification file, including the file extension. required: - id - name ReplicateProductRequestReplicateTargetSku: type: object properties: inventory: type: array items: $ref: "#/components/schemas/PartialEditProductRequestReplicatedProductSkuInventory" description: |- SKU inventory information per warehouse. This field is only required if the inventory allocation mode for the warehouse is MANUAL. Otherwise, it is optional. price: $ref: "#/components/schemas/ReplicateProductRequestReplicateTargetSkuPrice" description: The SKU's **local display price** shown on the product page before any discounts. source_sku_id: type: string description: The ID of the SKU being replicated seller_sku: type: string description: |- An internal code/name for managing SKUs, not visible to buyers. Valid length: - DE, ES, FR, IT, PL, NL, BE, CZ, AT, GR, PT, HU: 6-50 characters - Other regions: 1-50 characters Format: - DE, ES, FR, IT, PL, NL, BE, CZ, AT, GR, PT, HU: Use alphabets, numbers, hyphens (-), or underscores (_) only - Other regions: Text without spaces ReplicateProductRequestReplicateTargetSkuPrice: type: object properties: currency: type: string description: The currency. You must specify the local currency in the target market. sale_price: type: string description: |- The SKU's local display price shown on the product page before any discounts. Refer to Product Pricing for the allowed price ranges in each market. required: - sale_price ReplicateProductResponse: 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/ReplicateProductResponseData" ReplicateProductResponseData: type: object properties: errors: type: array items: $ref: "#/components/schemas/ReplicateProductResponseDataError" description: The pre-submission validation errors for target markets. When this list is non-empty, asynchronous replication is not submitted. Use each item's `detail.region` to identify the affected target market. ReplicateProductResponseDataError: type: object properties: code: type: integer format: int64 description: The error code. detail: $ref: "#/components/schemas/ReplicateProductResponseDataErrorDetail" description: The details of the error. message: type: string description: The error message. ReplicateProductResponseDataErrorDetail: type: object properties: region: type: string description: The target region where the error occurred. RepublishActivityRequest: type: object properties: end_time: type: integer format: int64 description: Activity end time as a Unix timestamp in seconds. It must be later than begin_time, and the effective period must be at least 10 minutes. The maximum period depends on the activity type and shop region; for FLASHSALE activities, it must not exceed 3 days. begin_time: type: integer format: int64 description: Activity start time as a Unix timestamp in seconds. The value must be later than the current time. RepublishActivityResponse: 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/RepublishActivityResponseData" RepublishActivityResponseData: type: object properties: activity_id: type: string description: On success, the ID of the republished activity. This is the same activity_id supplied in the request path; republishing does not create a new activity. Use this ID for subsequent activity, product, or SKU edits. RequirementCondition: type: object properties: condition_type: type: string enum: - VALUE_ID_MATCH x-enum-descriptions: - The condition is true when the seller selects a value whose ID matches the one specified in this condition. description: |- The type of condition. Possible values: - VALUE_ID_MATCH: The condition is true when the seller selects a value whose ID matches the one specified in this condition. attribute_id: type: string description: The ID of the product attribute that is being evaluated by the condition. attribute_value_id: type: string description: The ID of the product attribute value that must match the seller's input for the condition to be true. ResolveTargetCollaborationConflictsRequest: type: object properties: conflict_items: type: array items: $ref: "#/components/schemas/ResolveTargetCollaborationConflictsRequestConflictItem" description: A list of creators and their existing target collaborations involved in conflicts that caused target collaboration failure. Each item identifies a creator and the existing target collaboration from which that creator will be removed. required: - conflict_items ResolveTargetCollaborationConflictsRequestConflictItem: type: object properties: existing_collaboration_id: type: string description: The confict target collaboration id creator_open_id: type: string description: Creator Open ID. [More details](https://partner.tiktokshop.com/docv2/page/3obfokj6) required: - existing_collaboration_id - creator_open_id ResolveTargetCollaborationConflictsResponse: 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/ResolveTargetCollaborationConflictsResponseData" ResolveTargetCollaborationConflictsResponseData: type: object properties: success_items: type: array items: $ref: "#/components/schemas/ResolveTargetCollaborationConflictsResponseDataSuccessItem" description: success update items failed_items: type: array items: $ref: "#/components/schemas/ResolveTargetCollaborationConflictsResponseDataFailedItem" description: failed update items ResolveTargetCollaborationConflictsResponseDataFailedItem: type: object properties: creator_open_id: type: string description: Creator Open ID. [More details](https://partner.tiktokshop.com/docv2/page/3obfokj6) existing_collaboration_id: type: string description: The confict target collaboration id ResolveTargetCollaborationConflictsResponseDataSuccessItem: type: object properties: creator_open_id: type: string description: Creator Open ID. [More details](https://partner.tiktokshop.com/docv2/page/3obfokj6) existing_collaboration_id: type: string description: The confict target collaboration id ReturnLineItem: type: object properties: return_line_item_id: type: string description: Return order line ID. order_line_item_id: type: string description: Order line ID. sku_id: type: string description: SKU ID. sku_name: type: string description: SKU name. product_image: $ref: "#/components/schemas/ProductImage" description: Product image information. product_name: type: string description: Product name. seller_sku: type: string description: SKU name defined by seller. refund_amount: $ref: "#/components/schemas/RefundAmount" description: Refund amount details. return_sub_line_items: type: array items: $ref: "#/components/schemas/ReturnSubLineItem" description: |- Return sub order lines items. Sub items represent skus that belong to a "virtual bundle" that has been defined by a seller. The sub_items will include all relevant information about each item that is a part of the virtual bundle. ReturnStatusChangeWebhook: type: object properties: type: type: integer const: 12 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/ReturnStatusChangeWebhookData" required: - type ReturnStatusChangeWebhookData: type: object properties: order_id: type: string description: The identification of a TikTok Shop order return_role: type: string enum: - BUYER - SELLER - SYSTEM description: |- Return or refund request user, with possible values: * BUYER * SELLER * SYSTEM return_type: type: string enum: - REFUND - REPLACEMENT - RETURN_AND_REFUND description: |- The return or refund request type, with possible values: * REFUND * REPLACEMENT * RETURN_AND_REFUND return_status: type: string enum: - AWAITING_BUYER_SHIP - BUYER_SHIPPED_ITEM - REFUND_OR_RETURN_REQUEST_REJECT - REJECT_RECEIVE_PACKAGE - REPLACEMENT_REQUEST_CANCEL - REPLACEMENT_REQUEST_COMPLETE - REPLACEMENT_REQUEST_PENDING - REPLACEMENT_REQUEST_REFUND_SUCCESS - REPLACEMENT_REQUEST_REJECT - RETURN_OR_REFUND_REQUEST_CANCEL - RETURN_OR_REFUND_REQUEST_COMPLETE - RETURN_OR_REFUND_REQUEST_PENDING - RETURN_OR_REFUND_REQUEST_SUCCESS description: |- The return status for a request, with possible values: * AWAITING_BUYER_SHIP * BUYER_SHIPPED_ITEM * REFUND_OR_RETURN_REQUEST_REJECT * REJECT_RECEIVE_PACKAGE * REPLACEMENT_REQUEST_CANCEL * REPLACEMENT_REQUEST_COMPLETE * REPLACEMENT_REQUEST_PENDING * REPLACEMENT_REQUEST_REFUND_SUCCESS * REPLACEMENT_REQUEST_REJECT * RETURN_OR_REFUND_REQUEST_CANCEL * RETURN_OR_REFUND_REQUEST_COMPLETE * RETURN_OR_REFUND_REQUEST_PENDING * RETURN_OR_REFUND_REQUEST_SUCCESS return_id: type: string description: The identifier of a specific return create_time: type: integer format: int64 description: The time when the request was created. update_time: type: integer format: int64 description: The time when return order status update, represented as a Unix timestamp (seconds). ReturnSubLineItem: type: object properties: return_sub_line_item_id: type: string description: Return sub order line ID. return_line_item_id: type: string description: Return order line ID. sub_order_line_item_id: type: string description: Sub order line ID. order_line_item_id: type: string description: Order line ID. sku_id: type: string description: SKU ID. sku_name: type: string description: SKU name. product_image: $ref: "#/components/schemas/ProductImage" description: Product image information. product_name: type: string description: Product name. seller_sku: type: string description: SKU name defined by seller. refund_amount: $ref: "#/components/schemas/RefundAmount" description: Refund amount details. ReturnWarehouseAddress: type: object properties: full_address: type: string description: The full return warehouse address. RevenueBreakdown: type: object properties: subtotal_before_discount_amount: type: string description: The total price of all order items before any seller discounts and platform discounts are deducted. This is equivalent to the shop's gross sales. seller_discount_amount: type: string description: |- The total amount of discounts funded by the seller, including: - Seller promotions (Product Discount, Flash Deal, Buy More Save More, Voucher and Bundle Deal) - Seller's portion of a co-funded voucher discount in co-funding campaigns - Seller discounts during a campaign refund_subtotal_before_discount_amount: type: string description: The total price of all refunded items before any seller discounts. This is equivalent to the shop's gross sales refund. seller_discount_refund_amount: type: string description: Discounts returned to the sellers due to returns or refunds. cod_service_fee_amount: type: string description: |- The cash on delivery service fees charged to buyers. Applicable only for Saudi Arabia. refund_cod_service_fee_amount: type: string description: |- The refund for cash on delivery service fees. Applicable only for Saudi Arabia. distant_item_fee_amount: type: string description: The distance fee for items paid by the customer. With your current settings for Horizon+ Program, this fee is included in product price for orders with shipping out of Java island. ReviewASampleApplicationRequest: type: object properties: review_result: type: string enum: - APPROVE - REJECT x-enum-descriptions: - Approves the sample application. - Rejects the sample application. description: |- The review action to take on the sample application. Possible values: - APPROVE: Approves the sample application. - REJECT: Rejects the sample application. reject_reason: type: string enum: - NOT_MATCH - OFFLINE - OUT_OF_STOCK - OTHER x-enum-descriptions: - The creator does not meet the seller's collaboration requirements. - The product has been taken offline. - The product is temporarily out of stock. - Any other reason not covered by the above categories. description: |- The reason why a seller rejected a creator's sample application. The possible enumerated values are: - NOT_MATCH: The creator does not meet the seller's collaboration requirements. - OFFLINE: The product has been taken offline. - OUT_OF_STOCK: The product is temporarily out of stock. - OTHER: Any other reason not covered by the above categories. Required if the review_result is set to REJECT This field allows the seller to specify the reason for rejecting a sample application, providing clarity to the creator regarding the rejection. required: - review_result ReviewASampleApplicationResponse: 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/ReviewASampleApplicationResponseData" ReviewASampleApplicationResponseData: type: object properties: {} ReviewAffiliatePartnerCampaignProductRequest: type: object properties: review_result: type: string description: |- The product review decision by the TikTok Affiliate Partner. This is an enumerated type with values: - APPROVE - REJECT - REJECT_FOREVER reject_reasons: type: array items: type: string enum: - COMMISSION_TOO_LOW - PRODUCT_HARD_TO_PROMOTE - PRODUCT_TOO_EXPENSIVE - NO_SUITABLE_CREATOR description: |- Rejection reasons for the product when `review_result` is `REJECT` or `REJECT_FOREVER`. Possible values for each item: - COMMISSION_TOO_LOW - PRODUCT_HARD_TO_PROMOTE - PRODUCT_TOO_EXPENSIVE - NO_SUITABLE_CREATOR required: - review_result ReviewAffiliatePartnerCampaignProductResponse: 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/ReviewAffiliatePartnerCampaignProductResponseData" ReviewAffiliatePartnerCampaignProductResponseData: type: object properties: {} ReviewAftersalesRequestsRequest: type: object properties: aftersales_request_decisions: type: array items: $ref: "#/components/schemas/ReviewAftersalesRequestsRequestAftersalesRequestDecision" description: Decisions to apply to aftersales requests. ReviewAftersalesRequestsRequestAftersalesRequestDecision: type: object properties: request_id: type: string description: Identifies the object upon which this decision is made. request_id_type: type: string enum: - AFTERSALES - RMA description: |- Type of identifier provided in request_id. Possible values: - `AFTERSALES` - `RMA` line_item_decisions: type: array items: $ref: "#/components/schemas/ReviewAftersalesRequestsRequestAftersalesRequestDecisionLineItemDecision" description: |- Decisions applied at the line item level. One SKU may only have one decision, so all line items (corresponding to that same SKU) should fall under the same decision object. Different line item decisions for the same SKU will soon be supported in the future. action_unix_time: type: integer format: int64 description: The timestamp at which the decision/action was made (in unix seconds). idempotency_key: type: string maxLength: 255 description: The idempotency key is a unique value generated by the client which the server uses to recognize the same request. How you create unique keys is up to you, but we suggest using UUIDs, or another random string with enough entropy to avoid collisions. Idempotency keys can be up to 255 characters long. required: - request_id - line_item_decisions ReviewAftersalesRequestsRequestAftersalesRequestDecisionLineItemDecision: type: object properties: line_items: type: array items: $ref: "#/components/schemas/ReviewAftersalesRequestsRequestAftersalesRequestDecisionLineItemDecisionLineItem" description: Line items for which this decision applies. Decision details apply to each line item individually (e.g. a partial refund amount of $1.00 for 3 line items will result in a total partial refund amount of $3.00). action: type: string enum: - APPROVE_REQUEST - APPROVE_RETURN_PACKAGE - REJECT_REQUEST - REJECT_RETURN_PACKAGE - REFUND_INSTEAD - OFFER_PARTIAL_REFUND - OFFER_PARTIAL_REFUND_AFTER_RECEIVING_PKG description: |- Action/decision to be applied. Possible values: - `APPROVE_REQUEST` - `APPROVE_RETURN_PACKAGE` - `REJECT_REQUEST` - `REJECT_RETURN_PACKAGE` - `REFUND_INSTEAD` - `OFFER_PARTIAL_REFUND` - `OFFER_PARTIAL_REFUND_AFTER_RECEIVING_PKG` alternative_solution_details: $ref: "#/components/schemas/ReviewAftersalesRequestsRequestAftersalesRequestDecisionLineItemDecisionAlternativeSolutionDetail" description: Details for an alternative resolution (if applicable). reason: $ref: "#/components/schemas/ReviewAftersalesRequestsRequestAftersalesRequestDecisionLineItemDecisionReason" description: To justify the action/decision (generally required for rejection). required: - line_items - action ReviewAftersalesRequestsRequestAftersalesRequestDecisionLineItemDecisionAlternativeSolutionDetail: type: object properties: partial_refund_amount: type: string description: Proposed refund amount. currency: type: string description: Currency of the refund amount (ISO 4217). Must match the currency of the forward order. ReviewAftersalesRequestsRequestAftersalesRequestDecisionLineItemDecisionLineItem: type: object properties: return_line_item_id: type: string description: Unique identifier for this item in the return. In the case of virtual bundle, this corresponds to the id of the original parent item bundle. sub_return_line_item_id: type: string description: Unique identifier for this item in the return. In the case of virtual bundle, this corresponds to the id of the current child item being returned. required: - return_line_item_id ReviewAftersalesRequestsRequestAftersalesRequestDecisionLineItemDecisionReason: type: object properties: reason_id: type: string description: |- Seller's reason for rejecting the aftersales request. Use the [Get Review Decision](https://partner.tiktokshop.com/docv2/page/get-review-decision-202606) endpoint to retrieve the currently available rejection options for the same request, and submit the returned rejection reason name in this field. **Note**: The available decisions and rejection reasons can change depending on the current request status, so fetch eligibility again before calling this API. text: type: string description: Additional explanation for the decision. media: $ref: "#/components/schemas/ReviewAftersalesRequestsRequestAftersalesRequestDecisionLineItemDecisionReasonMedia" description: Supporting evidence (such as images). ReviewAftersalesRequestsRequestAftersalesRequestDecisionLineItemDecisionReasonMedia: type: object properties: uri: type: string description: Image URI obtained from the [Upload Product Image](https://partner.tiktokshop.com/docv2/page/6509df95defece02be598a22) API. mime_type: type: string description: MIME type of the media (such as image/jpeg). ReviewAftersalesRequestsResponse: 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/ReviewAftersalesRequestsResponseData" ReviewAftersalesRequestsResponseData: type: object properties: errors: type: array items: $ref: "#/components/schemas/GetAvailableReviewDecisionsResponseDataError" description: |- Lists errors for partially failed requests. For example, if a request reviews multiple orders or items and only some fail, individual error details are returned here. **IMPORTANT**: Partial failures still return a top-level success code (0), so clients must also check this field to detect partial errors. For complete failures (e.g. validation errors), the top-level response code and message will indicate a failure, but this field will remain empty. SKUStatusChangeWebhook: type: object properties: type: type: integer const: 50 description: The ID of the webhook type. tts_notification_id: type: string description: The ID of this webhook notification. shop_id: type: string description: The shop ID. timestamp: type: integer format: int64 description: The time when this webhook is triggered. Unix timestamp. data: $ref: "#/components/schemas/SKUStatusChangeWebhookData" description: The business payload of this webhook. required: - type SKUStatusChangeWebhookData: type: object properties: product_id: type: string description: The ID of the product whose SKU status changed. skus: type: array items: $ref: "#/components/schemas/SKUStatusChangeWebhookDataSku" description: The list of SKUs whose status changed. update_time: type: integer format: int64 description: The time when the change occurred. Unix timestamp. SKUStatusChangeWebhookDataSku: type: object properties: sku_id: type: string description: The ID of the SKU whose status changed. status: type: string enum: - CREATED - DELETED - ACTIVATED - DEACTIVATED description: "The new SKU status. Possible values: `CREATED`, `DELETED`, `ACTIVATED`, `DEACTIVATED`." deactivation_source: type: string enum: - SELLER - PLATFORM - COMBO_RELATION description: "The source of deactivation. This field is returned only when `status` is `DEACTIVATED`. Possible values: `SELLER`, `PLATFORM`, `COMBO_RELATION`." SalesAttribute: type: object properties: id: type: string description: |- The sales attribute ID. If you included the custom sales attribute name in the request, this is a newly generated ID. value_id: type: string description: |- The sales attribute value ID. If you included the custom sales attribute value name in the request, this is a newly generated ID. SalesPrice: type: object properties: currency: type: string description: Currency code for the promotional price. minimum_amount: type: string description: The minimum promotion price of all skus of this product. maximum_amount: type: string description: The maximum promotion price of all skus of this product. SalesPriceRange: type: object properties: amount_ge: type: string description: The product price must be greater than this value in order to be included in the search results. The value must be greater than `0`. amount_lt: type: string description: The product price must be greater than this value in order to be included in the search results. The value must be greater than `0`. No upper bound is set if this property is not included. SampleApplicationStatusChangeWebhook: type: object properties: type: type: integer const: 56 description: The ID of the webhook type. tts_notification_id: type: string description: The ID of the notification. shop_id: type: string description: TikTok shop ID timestamp: type: integer format: int64 description: The UNIX timestamp when this webhook was triggered. data: $ref: "#/components/schemas/SampleApplicationStatusChangeWebhookData" required: - type SampleApplicationStatusChangeWebhookData: type: object properties: application_id: type: string description: The id of the sample application new_status: type: string enum: - PENDING - AWAITING_SHIPMENT - SHIPPED - CONTENT_PENDING - REJECT_CANCELLED - OVERDUE_CANCELLED - UNFULFILL_CANCELLED - DEL_OPEN_COLLAB - SELLER_NOT_SHIP_CANCELLED - WITHDRAW_CANCELLED - UNFULFILLABLE_CANCELLED - OPS_CANCELLED - OPS_FAILED - OPS_COMPLETED - COMPLETED x-enum-descriptions: - The sample application is waiting for the seller's review. - The application is approved, and the seller needs to ship the sample. - The sample has been shipped by the seller and is waiting for the creator to receive the package. - The creator has received the sample package and is expected to create content. - The sample application has been rejected by the seller. - The sample application has expired due to being overdue. - The creator did not fulfill the commitment to create content within the agreed timeframe. - Open collaboration has been deleted. - The seller did not ship the sample within the required timeframe. - The creator withdrew the sample application before the seller approved it. - The application was cancelled due to reasons beyond the creator's control, making it impossible to create content. - The application was manually cancelled by operations staff. - The application was marked as failed by operations staff. - The application was manually marked as completed by operations staff. - The application is complete, and the creator has posted the content. description: |- The status of sample applications. The possible enumerated values are: * `PENDING`: The sample application is waiting for the seller's review. * `AWAITING_SHIPMENT`: The application is approved, and the seller needs to ship the sample. * `SHIPPED`: The sample has been shipped by the seller and is waiting for the creator to receive the package. * `CONTENT_PENDING`: The creator has received the sample package and is expected to create content. * `REJECT_CANCELLED`: The sample application has been rejected by the seller. * `OVERDUE_CANCELLED`: The sample application has expired due to being overdue. * `UNFULFILL_CANCELLED`: The creator did not fulfill the commitment to create content within the agreed timeframe. * `DEL_OPEN_COLLAB`: Open collaboration has been deleted. * `SELLER_NOT_SHIP_CANCELLED`: The seller did not ship the sample within the required timeframe. * `WITHDRAW_CANCELLED`: The creator withdrew the sample application before the seller approved it. * `UNFULFILLABLE_CANCELLED`: The application was cancelled due to reasons beyond the creator's control, making it impossible to create content. * `OPS_CANCELLED`: The application was manually cancelled by operations staff. * `OPS_FAILED`: The application was marked as failed by operations staff. * `OPS_COMPLETED`: The application was manually marked as completed by operations staff. * `COMPLETED`: The application is complete, and the creator has posted the content. This field allows for tracking the status of a sample application throughout its lifecycle, providing visibility into each stage of the process for sellers and creators. creator: type: array items: $ref: "#/components/schemas/SampleApplicationStatusChangeWebhookDataCreator" description: Creator detailed information. It includes various details such as the creator's TikTok user name and TikTok user id. product: type: array items: $ref: "#/components/schemas/SampleApplicationStatusChangeWebhookDataProduct" description: Product information. SampleApplicationStatusChangeWebhookDataCreator: type: object properties: creator_open_id: type: string description: Creator Open ID. [More details](https://partner.tiktokshop.com/docv2/page/3obfokj6) SampleApplicationStatusChangeWebhookDataProduct: type: object properties: id: type: string description: The product identifier. sku_id: type: string description: The unique id of product sku which the creator applied for as a sample. SampleProduct: type: object properties: id: type: string description: The product identifier. sku_id: type: string description: The SKU identifier. sku_sale_property_value_names: type: array items: type: string description: Sku property name list for this sku id. ScheduledSale: type: object properties: is_enabled_scheduled_sale: type: boolean description: Whether scheduled listing is enabled for this product. If `true`, `schedule_sale_time` must be provided. schedule_sale_time: type: integer format: int64 description: Scheduled listing time, expressed as a Unix timestamp in milliseconds; must be later than the current time and within 90 days, and is required when is_enabled_scheduled_sale is true. required: - is_enabled_scheduled_sale - schedule_sale_time SearchAffiliateOrdersByCreatorRequest: type: object properties: time_ge: type: integer format: int64 description: The inclusive start of the time range for the selected `time_type`, as a Unix timestamp in milliseconds. Orders with timestamps greater than or equal to `time_ge` and less than `time_lt` are included. time_lt: type: integer format: int64 description: The exclusive end of the time range for the selected `time_type`, as a Unix timestamp in milliseconds. Orders with timestamps greater than or equal to `time_ge` and less than `time_lt` are included. time_type: type: string enum: - PAY_TIME - DELIVERY_TIME - SETTLE_TIME - CREATE_TIME x-enum-descriptions: - Filter based on the order payment time. - Filter based on the order delivery/shipment time. - Filter based on the order settlement time. - default Filter based on the order creation time. description: |- Specifies the type of timestamp to filter the orders by. The query time range (time_ge and time_lt) will be applied to the selected time type. Possible values: - PAY_TIME: Filter based on the order payment time. - DELIVERY_TIME: Filter based on the order delivery/shipment time. - SETTLE_TIME: Filter based on the order settlement time. - CREATE_TIME (default): Filter based on the order creation time. required: - time_ge - time_lt SearchAffiliateOrdersByCreatorResponse: 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/SearchAffiliateOrdersByCreatorResponseData" SearchAffiliateOrdersByCreatorResponseData: type: object properties: orders: type: array items: $ref: "#/components/schemas/SearchAffiliateOrdersByCreatorResponseDataOrder" description: The order resource. next_page_token: type: string description: An opaque token used to retrieve the next page of a paginated result set. total_count: type: integer format: int64 description: Total count of orders in the response. SearchAffiliateOrdersByCreatorResponseDataOrder: type: object properties: id: type: integer format: int64 description: The order identifier. status: type: string enum: - UNSPECIFIED - ORDERED - SETTLED - REFUNDED - FROZEN - DEDUCTED x-enum-descriptions: - The status is undefined and may be updated later. - The order has been placed, but commission has not been settled. The estimated commission is available. - The commission has been settled. Actual commission values are populated when the corresponding settled amounts are available. - The order was returned, refunded, or canceled by the buyer; actual commission and actual commission base amounts are returned as localized zero values. - Possible fraud was detected. Commission remains frozen until the issue is resolved. - An additional deduction was made from the balance account. description: |- The current status of the order. Possible values: - UNSPECIFIED: The status is undefined and may be updated later. - ORDERED: The order has been placed, but commission has not been settled. The estimated commission is available. - SETTLED: The commission has been settled. Actual commission values are populated when the corresponding settled amounts are available. - REFUNDED: The order was returned, refunded, or canceled by the buyer; actual commission and actual commission base amounts are returned as localized zero values. - FROZEN: Possible fraud was detected. Commission remains frozen until the issue is resolved. - DEDUCTED: An additional deduction was made from the balance account. For statuses other than SETTLED or REFUNDED, actual commission values can be empty. Bonus, shop ads, and creator commission reward amounts are populated only when the corresponding commission data exists; their availability is not determined by order status alone. skus: type: array items: $ref: "#/components/schemas/SearchAffiliateOrdersByCreatorResponseDataOrderSku" description: A list of SKUs associated with the order. create_time: type: integer format: int64 description: Time and date of order created, UTC+0 timing delivery_time: type: integer format: int64 description: Time and date order delivered, UTC+0 timing SearchAffiliateOrdersByCreatorResponseDataOrderSku: type: object properties: id: type: string description: The SKU identifier. product_id: type: string description: The product identifier. price: $ref: "#/components/schemas/Price" description: An object representing the localized price of the product. quantity: type: integer format: int64 description: The quantity of this SKU in the order. commission_rate: type: integer format: int64 description: The commission rate associated with the collaboration, in hundredths of a percent. The value does not include a percent sign. For example, `3000` represents 30%. estimated_commission_base: $ref: "#/components/schemas/EstimatedCommissionBase" description: An object representing the estimated base commission at the time of order creation. actual_commission: $ref: "#/components/schemas/ActualCommission" description: An object representing the actual creator commission. Its amount includes the components also reported in `actual_bonus_commission` and `actual_creator_commission_reward_fee`. The `actual_shop_ads_commission` amount is separate and is not included. shop_ads_commission_rate: type: integer format: int64 description: The commission rate received by a creator for a sale associated with a specific piece of content, in hundredths of a percent. The value does not include a percent sign. For example, `3000` represents 30%. commission_bonus_rate: type: integer format: int64 description: The commission bonus rate associated with the collaboration, in hundredths of a percent. The value does not include a percent sign. For example, `3000` represents 30%. product_name: type: string description: The product name in the TikTok Shop. shop_name: type: string description: The name of the TIkTok Shop in which the product is offered for sale. returned_quantity: type: integer format: int64 description: The returned quantity of this SKU in the order. refunded_quantity: type: integer format: int64 description: The refunded quantity of this SKU in the order. campaign_id: type: string description: The campaign identifier associated with the order. actual_commission_base: $ref: "#/components/schemas/ActualCommissionBase" description: An object representing the actual commission base, calculated by multiplying the product sale price by the number of products sold, subtracting returned and refunded orders. actual_shop_ads_commission: $ref: "#/components/schemas/ActualShopAdsCommission" description: An object representing the actual shop ads commission, calculated by multiplying the commission base by the shop_ads_commission_rate. estimated_shop_ads_commission: $ref: "#/components/schemas/EstimatedShopAdsCommission" description: An object representing the estimated shop ads commission, calculated by multiplying the estimated commission base by the shop_ads_commission_rate estimated_bonus_commission: $ref: "#/components/schemas/EstimatedBonusCommission" description: An object representing the estimated bonus commission, calculated by multiplying the estimated commission base by the commission bonus rate. delivery_time: type: integer format: int64 description: Time and date order delivered, UTC+0 timing creator_commission_reward_rate: type: integer format: int64 description: The commission reward rate that affiliate partners allocate to creators, in hundredths of a percent. The value does not include a percent sign. For example, `1000` represents 10%. estimated_creator_commission_reward_fee: $ref: "#/components/schemas/EstimatedCreatorCommissionRewardFee" description: Estimated creator commission reward fee. actual_creator_commission_reward_fee: $ref: "#/components/schemas/ActualCreatorCommissionRewardFee" description: Actual creator commission reward fee. content_type: type: string enum: - SHOP - VIDEO - LIVE - PRE_LIVE - PROMOTION_PAGE - LINKSHARE description: |- The content format of the creator content through which the order was created. Possible values: - SHOP - VIDEO - LIVE - PRE_LIVE - PROMOTION_PAGE - LINKSHARE content_id: type: string description: The content identifier for the creator content through which the order was created. trace: $ref: "#/components/schemas/SearchAffiliateOrdersByCreatorResponseDataOrderSkuTrace" description: Extra information for tracing purposes. estimated_commission: $ref: "#/components/schemas/EstimatedCommission" description: An object representing the estimated creator commission. Its amount includes the components also reported in `estimated_bonus_commission` and `estimated_creator_commission_reward_fee`. The `estimated_shop_ads_commission` amount is separate and is not included. actual_bonus_commission: $ref: "#/components/schemas/ActualBonusCommission" description: An object representing the actual bonus commission, calculated by multiplying the actual commission base by the commission bonus rate. SearchAffiliateOrdersByCreatorResponseDataOrderSkuTrace: type: object properties: id: type: string description: When `trace.type` is `GENERAL`, this is the `event_id` embedded in the general sharing link. When `trace.type` is `SPECIFIC`, this is the `publisher_id` supplied when generating the specific-publisher sharing link. type: type: string description: For the orders coming from the sharing links for specific publishers, the value is `SPECIFIC`; for the orders coming from the general sharing links, the value is `GENERAL`. SearchAftersalesRequestsRequest: type: object properties: whitelisted_data_fields: type: array items: type: string enum: - LINE_ITEMS - SKU_RETURN_REQUESTS - RETURN_MERCHANDISE_AUTHORIZATIONS x-enum-descriptions: - Includes `line_items`. - Includes `sku_return_requests`. - Includes `return_merchandise_authorizations`. description: |- Controls which additional fields are included for each aftersales request. Possible values: - `LINE_ITEMS`: Includes `line_items`. - `SKU_RETURN_REQUESTS`: Includes `sku_return_requests`. - `RETURN_MERCHANDISE_AUTHORIZATIONS`: Includes `return_merchandise_authorizations`. filters: $ref: "#/components/schemas/SearchAftersalesRequestsRequestFilter" description: Filters to narrow the result set. sort: $ref: "#/components/schemas/Sort" description: Sorting criteria for the result set. pagination: $ref: "#/components/schemas/Pagination" description: Pagination configuration. SearchAftersalesRequestsRequestFilter: type: object properties: aftersales_request_ids: type: array items: type: string description: Restricts results to the specified aftersales requests. Each ID must be a base-10 integer string that fits in a signed 64-bit integer. aftersales_request_statuses: type: array items: type: string enum: - INIT - PENDING_REQUEST_REVIEW - REQUEST_REVIEW_COMPLETED description: |- Restricts results to the specified aftersales request statuses. Possible values: - `INIT` - `PENDING_REQUEST_REVIEW` - `REQUEST_REVIEW_COMPLETED` return_types: type: array items: type: string enum: - REFUND - RETURN_AND_REFUND - REPLACEMENT - EXCHANGE description: |- Restricts results to aftersales request data which includes at least one sku return request with a given type. Possible values: - `REFUND` - `RETURN_AND_REFUND` - `REPLACEMENT` - `EXCHANGE` main_order_ids: type: array items: type: string description: Restricts results to aftersales requests that contain at least one SKU return request for a specified main (forward) order. Each main order ID must be a base-10 integer string that fits in a signed 64-bit integer. buyer_ids: type: array items: type: string description: Restricts results to aftersales requests that contain at least one SKU return request for a specified buyer. Each buyer ID must be a base-10 integer string that fits in a signed 64-bit integer. time: $ref: "#/components/schemas/Time" description: Time-based filtering criteria. SearchAftersalesRequestsResponse: 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/SearchAftersalesRequestsResponseData" SearchAftersalesRequestsResponseData: type: object properties: aftersales_requests: type: array items: $ref: "#/components/schemas/SearchAftersalesRequestsResponseDataAftersalesRequest" description: List of aftersales requests matching the filters. This field is omitted when no aftersales requests match. total_count: type: integer format: int64 description: The total result set size, independent of pagination. next_page_token: type: string description: Used to fetch the next page/set of results. SearchAftersalesRequestsResponseDataAftersalesRequest: type: object properties: id: type: string description: Unique identifier for this aftersales request. line_items: type: array items: $ref: "#/components/schemas/LineItem" description: List of items associated with this aftersales request. This field is returned only when `LINE_ITEMS` is included in `whitelisted_data_fields` and matching item data is available. status: type: string enum: - INIT - PENDING_REQUEST_REVIEW - REQUEST_REVIEW_COMPLETED description: |- Current state of this aftersales request. Possible values: - `INIT` - `PENDING_REQUEST_REVIEW` - `REQUEST_REVIEW_COMPLETED` sku_return_requests: type: array items: $ref: "#/components/schemas/SkuReturnRequest" description: SKU-level sub return requests associated with this aftersales request, also known as reverse orders or return requests. This field is returned only when `SKU_RETURN_REQUESTS` is included in `whitelisted_data_fields` and matching data is available. return_merchandise_authorizations: type: array items: $ref: "#/components/schemas/SearchAftersalesRequestsResponseDataAftersalesRequestReturnMerchandiseAuthorization" description: Return merchandise authorization (RMA) records associated with this aftersales request. This field is returned only when `RETURN_MERCHANDISE_AUTHORIZATIONS` is included in `whitelisted_data_fields` and matching RMA data is available. SearchAftersalesRequestsResponseDataAftersalesRequestReturnMerchandiseAuthorization: type: object properties: id: type: string description: Unique identifier for this RMA data. package_id: type: string description: Identifier of the associated physical return package. aftersales_request_id: type: string description: Identifier of the parent aftersales request. status: type: string enum: - INIT - AWAITING_BUYER_RETURN - RETURN_IN_TRANSIT - PENDING_PACKAGE_REVIEW - PACKAGE_REVIEW_COMPLETED description: |- The current state of this RMA data. Possible values: - `INIT` - `AWAITING_BUYER_RETURN` - `RETURN_IN_TRANSIT` - `PENDING_PACKAGE_REVIEW` - `PACKAGE_REVIEW_COMPLETED` line_items: type: array items: $ref: "#/components/schemas/LineItem" description: List of items associated with this return merchandise authorization (RMA). SearchAftersalesRequestsResponseDataAftersalesRequestSkuReturnRequestDiscount: type: object properties: product_platform_discount: type: string description: The refund amount of platform discount. product_seller_discount: type: string description: The refund amount of product seller discount. shipping_fee_platform_discount: type: string description: The refund amount of shipping fee platform discount. shipping_fee_seller_discount: type: string description: The refund amount of shipping fee seller discount. SearchAftersalesRequestsResponseDataAftersalesRequestSkuReturnRequestShippingFee: type: object properties: seller_paid_return_shipping_fee_amount: type: string description: The amount of return shipping fee seller paid. buyer_paid_return_shipping_fee_amount: type: string description: The amount of return shipping fee buyer paid. platform_paid_return_shipping_fee_amount: type: string description: The amount of return shipping fee platform paid. SearchCAPAffiliateOrdersRequest: type: object properties: order_id: type: string description: Transaction main order ID product_id: type: string description: Unique identifier for Product settle_status: type: integer format: int64 description: |- Filter orders by settlement status. Send one of the following integer values; the response `settle_status` field uses the corresponding label: - `1` → `CUSTOMER UNPAID`: The customer has not paid for the order. - `2` → `PENDING`: The customer can still return the order or request a refund, so earnings are estimated and awaiting settlement. - `3` → `SETTLED`: Earnings have been settled to your account. - `4` → `INELIGIBLE`: The order was returned, refunded, or canceled, so no commission will be settled. - `5` → `FROZEN`: Possible fraud was detected; the commission will be unfrozen after the fraud is resolved. create_time_ge: type: integer format: int64 description: Filter orders created at or after this time. Unix timestamp in seconds. `create_time_ge` and `create_time_lt` must be provided together. An explicitly supplied range can span at most 92 days. If neither field is provided, the API searches from three calendar months before the request time through the request time. create_time_lt: type: integer format: int64 description: Filter orders created before this time. Unix timestamp in seconds. `create_time_ge` and `create_time_lt` must be provided together. SearchCAPAffiliateOrdersResponse: 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/SearchCAPAffiliateOrdersResponseData" SearchCAPAffiliateOrdersResponseData: type: object properties: sku_orders: type: array items: $ref: "#/components/schemas/SearchCAPAffiliateOrdersResponseDataSkuOrder" description: |- SKU orders returned for the current page. For monetary fields whose names start with `actual_`, the nested `amount` can be present only when `settle_status` is `SETTLED` or `INELIGIBLE`. For all other statuses, the `amount` property is omitted. Even for `SETTLED` or `INELIGIBLE` orders, an individual `actual_*` field can still omit `amount`. next_page_token: type: string description: Pagination token for the next page. The token contains only the search-after sort position; it does not preserve the search filters or `page_size`. If this field is returned, pass it as `page_token` in the next request, 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. Stop paginating when this field is omitted. The field is omitted when the returned page contains fewer records than `page_size`. total_count: type: integer format: int64 description: Total number of SKU orders matching the current search criteria across all pages. SearchCAPAffiliateOrdersResponseDataSkuOrder: type: object properties: id: type: string description: Transaction main order ID tags: type: string description: The customizable ID for each order, used for tracking performance at difference front end modules. create_time: type: integer format: int64 description: Unix timestamp in seconds when the order was created (UTC). delivery_time: type: integer format: int64 description: Unix timestamp in seconds when the order was delivered (UTC). This field is omitted when no delivery timestamp is available. settle_status: type: string description: |- Settlement Status of the order. Possible values: 1. "CUSTOMER UNPAID", customer hasn't paid for the orders. 2. "PENDING", customers can still return or get a refund for this order. The earnings shown are estimates and waiting for settlement. 3. "SETTLED", your earnings have already settled to your account 4. "INELIGIBLE", The order has been returned/refunded/canceled by the buyer, and no commission will be settled. 5. "FROZEN", Possible fraud has been detected regarding the order. The commission will be unfrozen after the fraud is resolved. sku_id: type: string description: The SKU identifier. open_collaboration_id: type: string description: The open collaboration identifier associated with the order. target_collaboration_id: type: string description: The target collaboration identifier associated with the order. creator_username: type: string description: Creator username product_name: type: string description: The product name. product_id: type: string description: Unique identifier for Product price: $ref: "#/components/schemas/Price" description: The SKU selling price information quantity: type: integer format: int64 description: Number of SKU items in the order, including refunded items. shop_name: type: string description: Shop / Seller name content_type: type: string enum: - SHOP - VIDEO - LIVE - PRE_LIVE - PROMOTION_PAGE - LINKSHARE description: |- The content format of the creator content through which the order was created. Possible values: - SHOP - VIDEO - LIVE - PRE_LIVE - PROMOTION_PAGE - LINKSHARE content_id: type: string description: Unique identifier for content attribution_type: type: string enum: - Direct - Indirect x-enum-descriptions: - same-shop attribution. - non-same-shop attribution. The settlement commission rate is usually lower than the rate agreed in the Marketplace or target collaboration. description: |- Attribution type for `LINKSHARE` content. Possible values: - `Direct`: same-shop attribution. - `Indirect`: non-same-shop attribution. The settlement commission rate is usually lower than the rate agreed in the Marketplace or target collaboration. For other content types, this field is an empty string. commission_model: type: string description: |- Commission calculation model. Possible values: - `Fixed commission` - `Tiered commission` commission_tier_setting: type: string description: Seller-configured commission rates for a tiered commission model, expressed as percentages and separated by ` OR `. Returns `-` for the fixed commission model. standard_commission_rate: type: integer format: int64 description: Seller-to-creator standard commission rate. Returned as an integer in hundredths of a percent without a percent sign; for example, 3000 represents 30%. commission_bonus_rate: type: integer format: int64 description: TTS-to-creator commission bonus rate. Returned as an integer in hundredths of a percent without a percent sign; for example, 3000 represents 30%. shop_ads_commission_rate: type: integer format: int64 description: Shop Ads commission rate paid to the creator. Returned as an integer in hundredths of a percent without a percent sign; for example, 3000 represents 30%. tap_bonus_commission_rate: type: integer format: int64 description: Commission bonus rate that the affiliate partner allocates to the creator. Returned as an integer in hundredths of a percent without a percent sign; for example, 3000 represents 30%. revenue_sharing_portion_rate: type: integer format: int64 description: Revenue-sharing portion between the creator and agency. Returned as an integer in hundredths of a percent without a percent sign; for example, 3000 represents 30%. estimated_commission_base: $ref: "#/components/schemas/EstimatedCommissionBase" description: The estimated commission base is the product sale price multiplied by the number of products sold when the order is created. estimated_standard_commission: $ref: "#/components/schemas/EstimatedStandardCommission" description: Estimated standard commission on sales that a creator will obtain. estimated_bonus_commission: $ref: "#/components/schemas/EstimatedBonusCommission" description: Estimated commission TTS pays well-performed creators estimated_shop_ads_commission: $ref: "#/components/schemas/EstimatedShopAdsCommission" description: Estimated commission on sales that a creator will receive from seller/advertisers purchasing a specific creative estimated_tap_bonus_commission: $ref: "#/components/schemas/SearchCAPAffiliateOrdersResponseDataSkuOrderEstimatedTapBonusCommission" description: Estimated commission bonus which TAP provided to creator estimated_creator_tax_isr: $ref: "#/components/schemas/SearchCAPAffiliateOrdersResponseDataSkuOrderEstimatedCreatorTaxIsr" description: Only for Mexico creator, the platform collected related revenue taxes on behalf of government based on regulation. estimated_creator_tax_iva: $ref: "#/components/schemas/SearchCAPAffiliateOrdersResponseDataSkuOrderEstimatedCreatorTaxIva" description: Only for Mexico creator, the platform collected related revenue taxes on behalf of government based on regulation. estimated_creator_tax_pit: $ref: "#/components/schemas/SearchCAPAffiliateOrdersResponseDataSkuOrderEstimatedCreatorTaxPit" description: Only for VN/TH/PH/ID creators, sellers collect related withholding taxes based on regulation. estimated_creator_total_earnings_after_tax: $ref: "#/components/schemas/SearchCAPAffiliateOrdersResponseDataSkuOrderEstimatedCreatorTotalEarningsAfterTax" description: Total after-tax earnings for creator before splitting revenue with agency estimated_total_agency_earnings: $ref: "#/components/schemas/SearchCAPAffiliateOrdersResponseDataSkuOrderEstimatedTotalAgencyEarning" description: Total after-tax earnings for agency estimated_agency_isr: $ref: "#/components/schemas/SearchCAPAffiliateOrdersResponseDataSkuOrderEstimatedAgencyIsr" description: Estimated ISR tax amount for Mexico agency estimated_agency_iva: $ref: "#/components/schemas/SearchCAPAffiliateOrdersResponseDataSkuOrderEstimatedAgencyIva" description: Estimated IVA tax amount for Mexico agency actual_commission_base: $ref: "#/components/schemas/ActualCommissionBase" description: The actual commission base is the product sale price multiplied by the number of products sold, excluding returned and refunded orders. actual_standard_commission: $ref: "#/components/schemas/ActualStandardCommission" description: Actual commission on sales that a creator will obtain before revenue spliting actual_bonus_commission: $ref: "#/components/schemas/ActualBonusCommission" description: The creator's actual TikTok Shop bonus commission. actual_shop_ads_commission: $ref: "#/components/schemas/ActualShopAdsCommission" description: actual commission on sales that a creator will receive from seller/advertisers purchasing a specific creative actual_tap_bonus_commission: $ref: "#/components/schemas/SearchCAPAffiliateOrdersResponseDataSkuOrderActualTapBonusCommission" description: Actual commission bonus which TAP provided to creator actual_creator_tax_isr: $ref: "#/components/schemas/SearchCAPAffiliateOrdersResponseDataSkuOrderActualCreatorTaxIsr" description: Only for Mexico creator, the platform collected related revenue taxes on behalf of government based on regulation. actual_creator_tax_iva: $ref: "#/components/schemas/SearchCAPAffiliateOrdersResponseDataSkuOrderActualCreatorTaxIva" description: Only for Mexico creator, the platform collected related revenue taxes on behalf of government based on regulation. actual_creator_tax_pit: $ref: "#/components/schemas/SearchCAPAffiliateOrdersResponseDataSkuOrderActualCreatorTaxPit" description: Only for VN/TH/PH/ID creators, sellers collected related withholding taxes based on regulation. actual_creator_total_earnings_after_tax: $ref: "#/components/schemas/SearchCAPAffiliateOrdersResponseDataSkuOrderActualCreatorTotalEarningsAfterTax" description: Total after-tax earnings for creator before splitting revenue with agency actual_total_agency_commission: $ref: "#/components/schemas/SearchCAPAffiliateOrdersResponseDataSkuOrderActualTotalAgencyCommission" description: Total after-tax earnings for agency actual_agency_isr: $ref: "#/components/schemas/SearchCAPAffiliateOrdersResponseDataSkuOrderActualAgencyIsr" description: The actual ISR tax amount for Mexico agency actual_agency_iva: $ref: "#/components/schemas/SearchCAPAffiliateOrdersResponseDataSkuOrderActualAgencyIva" description: The actual IVA tax amount for Mexico agency fully_return: type: string enum: - Yes - No x-enum-descriptions: - this SKU order was fully returned or refunded, and no commission is paid. - this SKU order was not fully returned or refunded. description: |- Whether this SKU order was fully returned or refunded. Possible values: - `Yes`: this SKU order was fully returned or refunded, and no commission is paid. - `No`: this SKU order was not fully returned or refunded. settlement_time: type: integer format: int64 description: Unix timestamp in seconds when the order commission was settled (UTC). This field is omitted when no settlement timestamp is available. last_update_time: type: integer format: int64 description: Unix timestamp in seconds when the record was last updated (UTC). is_carousel: type: boolean description: Carousel content may involve a commission rate discount. Returns true when the SKU order is attributed to carousel content. SearchCAPAffiliateOrdersResponseDataSkuOrderActualAgencyIsr: type: object properties: amount: type: string description: Tax amount without a currency symbol. Use the sibling `currency` field to identify the currency. currency: type: string description: Type of currency use SearchCAPAffiliateOrdersResponseDataSkuOrderActualAgencyIva: type: object properties: amount: type: string description: Tax amount without a currency symbol. Use the sibling `currency` field to identify the currency. currency: type: string description: Type of currency use SearchCAPAffiliateOrdersResponseDataSkuOrderActualCreatorTaxIsr: type: object properties: amount: type: string description: The actual creator ISR amount. currency: type: string description: The currency code. SearchCAPAffiliateOrdersResponseDataSkuOrderActualCreatorTaxIva: type: object properties: amount: type: string description: The actual creator IVA amount. currency: type: string description: The currency code. SearchCAPAffiliateOrdersResponseDataSkuOrderActualCreatorTaxPit: type: object properties: amount: type: string description: The actual creator PIT amount. currency: type: string description: The currency code. SearchCAPAffiliateOrdersResponseDataSkuOrderActualCreatorTotalEarningsAfterTax: type: object properties: amount: type: string description: The actual creator's earnings amount currency: type: string description: The currency code. SearchCAPAffiliateOrdersResponseDataSkuOrderActualTapBonusCommission: type: object properties: amount: type: string description: Actual TAP Bonus Commission amount currency: type: string description: Type of currency use SearchCAPAffiliateOrdersResponseDataSkuOrderActualTotalAgencyCommission: type: object properties: amount: type: string description: The actual agency earnings amount currency: type: string description: The currency code. SearchCAPAffiliateOrdersResponseDataSkuOrderEstimatedAgencyIsr: type: object properties: amount: type: string description: Tax amount without a currency symbol. Use the sibling `currency` field to identify the currency. currency: type: string description: Type of currency use SearchCAPAffiliateOrdersResponseDataSkuOrderEstimatedAgencyIva: type: object properties: amount: type: string description: Tax amount without a currency symbol. Use the sibling `currency` field to identify the currency. currency: type: string description: Type of currency use SearchCAPAffiliateOrdersResponseDataSkuOrderEstimatedCreatorTaxIsr: type: object properties: amount: type: string description: The estimated creator ISR amount. currency: type: string description: Type of currency use SearchCAPAffiliateOrdersResponseDataSkuOrderEstimatedCreatorTaxIva: type: object properties: amount: type: string description: The estimated creator IVA amount. currency: type: string description: Type of currency use SearchCAPAffiliateOrdersResponseDataSkuOrderEstimatedCreatorTaxPit: type: object properties: amount: type: string description: The estimated creator PIT amount. currency: type: string description: The currency code. SearchCAPAffiliateOrdersResponseDataSkuOrderEstimatedCreatorTotalEarningsAfterTax: type: object properties: amount: type: string description: The estimated creator earnings amount currency: type: string description: The currency code. SearchCAPAffiliateOrdersResponseDataSkuOrderEstimatedTapBonusCommission: 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 SearchCAPAffiliateOrdersResponseDataSkuOrderEstimatedTotalAgencyEarning: type: object properties: amount: type: string description: The estimated agency earnings amount currency: type: string description: The currency code. SearchCancellationsRequest: type: object properties: cancel_ids: type: array items: type: string description: List of order cancellations IDs. order_ids: type: array items: type: string description: List of TikTok Shop order IDs. buyer_user_ids: type: array items: type: string description: List of TikTok Shop buyer user IDs. cancel_types: type: array items: type: string enum: - CANCEL - BUYER_CANCEL x-enum-descriptions: - Cancel by seller or system. - Cancel by buyer. Need to be approved by seller or system. description: |- List of order cancellation types. Possible values: - `CANCEL`: Cancel by seller or system. - `BUYER_CANCEL`: Cancel by buyer. Need to be approved by seller or system. cancel_status: type: array items: type: string enum: - CANCELLATION_REQUEST_PENDING - CANCELLATION_REQUEST_SUCCESS - CANCELLATION_REQUEST_CANCEL - CANCELLATION_REQUEST_COMPLETE description: |- List of order cancellation statuses. Possible values: - `CANCELLATION_REQUEST_PENDING` - `CANCELLATION_REQUEST_SUCCESS` - `CANCELLATION_REQUEST_CANCEL` - `CANCELLATION_REQUEST_COMPLETE` Please see "API Overview" for more information about these statuses. create_time_ge: type: integer format: int64 description: Filter cancellations to show only orders that have been created after a specified date and time. Unix timestamp. create_time_lt: type: integer format: int64 description: Filter cancellations to show only orders that have been created before a specified date and time. Unix timestamp. update_time_ge: type: integer format: int64 description: Filter cancellations to show only orders that have been updated after a specified date and time. Unix timestamp. update_time_lt: type: integer format: int64 description: Filter cancellations to show only orders that have been updated before a specified date and time. Unix timestamp. locale: type: string description: |- The BCP-47 locale codes for displaying the order, delimited by commas. Default: en-US Refer to [Locale codes](678e3a47bae28f030a8c7523) for the list of supported locale codes. SearchCancellationsResponse: 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/SearchCancellationsResponseData" SearchCancellationsResponseData: type: object properties: cancellations: type: array items: $ref: "#/components/schemas/SearchCancellationsResponseDataCancellation" description: List of order cancellations. total_count: type: integer format: int64 description: The number of cancellations that meet the query conditions. next_page_token: type: string description: An opaque token used to retrieve the next page of results. If this value is non-empty, provide it in the `page_token` parameter of the next request. An empty value indicates that there are no more results. SearchCancellationsResponseDataCancellation: type: object properties: order_id: type: string description: TikTok Shop order ID. cancel_type: type: string enum: - CANCEL - BUYER_CANCEL x-enum-descriptions: - Cancel by seller or system. - Cancel by buyer. Need to be approved by seller or system. description: |- Order cancellation type. Possible values: - `CANCEL`: Cancel by seller or system. - `BUYER_CANCEL`: Cancel by buyer. Need to be approved by seller or system. cancel_status: type: string enum: - CANCELLATION_REQUEST_PENDING - CANCELLATION_REQUEST_SUCCESS - CANCELLATION_REQUEST_CANCEL - CANCELLATION_REQUEST_COMPLETE description: |- Order cancellation status. Possible values: - `CANCELLATION_REQUEST_PENDING` - `CANCELLATION_REQUEST_SUCCESS` - `CANCELLATION_REQUEST_CANCEL` - `CANCELLATION_REQUEST_COMPLETE` role: type: string enum: - BUYER - SELLER - OPERATOR - SYSTEM description: |- Order cancellation initiator. Possible values: - `BUYER` - `SELLER` - `OPERATOR` - `SYSTEM` cancel_reason: type: string description: Order cancellation reason. cancel_reason_text: type: string description: |- Order cancellation reason, localized to another language. You can change language using the locale field in the request parameter. create_time: type: integer format: int64 description: The time when the order cancellation was created. Unix timestamp in seconds. update_time: type: integer format: int64 description: The time when the order cancellation was last updated. Unix timestamp in seconds. seller_next_action_response: type: array items: $ref: "#/components/schemas/SearchCancellationsResponseDataCancellationSellerNextActionResponse" description: Seller's next action and deadline. refund_amount: $ref: "#/components/schemas/RefundAmount" description: Refund amount information. cancel_line_items: type: array items: $ref: "#/components/schemas/SearchCancellationsResponseDataCancellationCancelLineItem" description: Cancellation line items. cancel_id: type: string description: The identifier of a specific order cancellation. should_replenish_stock: type: boolean description: Should seller replenish the stock when order cancelled successfully. SearchCancellationsResponseDataCancellationCancelLineItem: type: object properties: cancel_line_item_id: type: string description: Cancellation line item ID. order_line_item_id: type: string description: Order line item ID. sku_id: type: string description: SKU ID. sku_name: type: string description: SKU name. product_image: $ref: "#/components/schemas/ProductImage" description: Product image object. Contains product image information. product_name: type: string description: Product name. seller_sku: type: string description: SKU name defined by the seller. refund_amount: $ref: "#/components/schemas/RefundAmount" description: Refund amount information. cancel_sub_line_items: type: array items: $ref: "#/components/schemas/SearchCancellationsResponseDataCancellationCancelLineItemCancelSubLineItem" description: |- Cancellation sub line items. Sub items represent skus that belong to a "virtual bundle" that has been defined by a seller. The sub_items will include all relevant information about each item that is a part of the virtual bundle. SearchCancellationsResponseDataCancellationCancelLineItemCancelSubLineItem: type: object properties: cancel_sub_line_item_id: type: string description: Cancellation sub line item ID. cancel_line_item_id: type: string description: Cancellation line item ID. sub_order_line_item_id: type: string description: Sub Order line item ID. order_line_item_id: type: string description: Order line item ID. sku_id: type: string description: SKU ID. sku_name: type: string description: SKU name. product_image: $ref: "#/components/schemas/ProductImage" description: Product image object. Contains product image information. product_name: type: string description: Product name. seller_sku: type: string description: SKU name defined by the seller. refund_amount: $ref: "#/components/schemas/RefundAmount" description: Refund amount information. SearchCancellationsResponseDataCancellationSellerNextActionResponse: type: object properties: action: type: string description: "**Optional.** For buyer-initiated cancellation requests that still require seller handling, the action value is `SELLER_RESPOND_BUYER_CANCEL`." deadline: type: integer format: int64 description: Unix timestamp in seconds indicating the deadline for the seller to perform the next action. SearchCombinablePackagesResponse: 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/SearchCombinablePackagesResponseData" SearchCombinablePackagesResponseData: type: object properties: combinable_packages: type: array items: $ref: "#/components/schemas/SearchCombinablePackagesResponseDataCombinablePackage" description: List of eligible packages that can be combined. next_page_token: type: string description: An opaque token used to retrieve the next page of a paginated result set. Provide this value in the `page_token` parameter of your request if the current response does not return all the results. total_count: type: integer format: int64 description: The number of combinable packages counted by this result. SearchCombinablePackagesResponseDataCombinablePackage: type: object properties: id: type: string description: The pre-generated package ID obtained after calling the Search Draft Package API. Use this ID when confirming the package combination. order_ids: type: array items: type: string description: List of order IDs for this package. SearchCouponListRequest: type: object properties: status: type: array items: type: string description: |- Coupon's promotion status. Values: - `NOT_START`: Not available to TikTok users until the coupon's configured start time. - `ONGOING`: Available to TikTok users. - `EXPIRED`: Not available to TikTok users because it has expired. - `DEACTIVATED`: Deactivated by the seller and is not available to TikTok users. title_keyword: type: string description: Keywords in coupon titles to search for. The UTF-8 byte length must be from 1 to 100. Fuzzy matching is not supported. display_type: type: array items: type: string description: |- The display type of coupons. Values: - `REGULAR`: Regular coupons which are displayed to TikTok users across all display locations available in TTS, including PLPs, PDPs, TikTok Videos, LIVE Rooms, Creator Showcases, and may be shared via TTS Customer Support instant messages. Includes coupons which target select customer segments. - `LIVE`: Coupons which are only displayed to TikTok users in LIVE Rooms. - `CREATOR_EXCLUSIVE`: Coupons that can be claimed through the display channels of the specified creator, such as their LIVE Rooms, and their Creator Showcase. - `CHAT`: Exclusive coupons that may be sent to customers via TTS customer support chat messages, but are not displayed in other display locations. - `PROMO_CODE`: Promo codes do not have dedicated display locations on TikTok, but may be shared with customers in LIVEs, in TikTok videos, or other social media platforms. They can be claimed by customers entering a claim code at checkout or by customers that use a custom promo code landing page URL. SearchCouponListResponse: 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/SearchCouponListResponseData" SearchCouponListResponseData: type: object properties: total_count: type: integer format: int64 description: Total number of coupon records matching the supplied filters. This value can be greater than the number of entries in coupons. next_page_token: type: string description: Cursor for the next page. If this field is present and non-empty, pass its value as `page_token` in the next request. Stop pagination when this field is absent or empty. coupons: type: array items: $ref: "#/components/schemas/SearchCouponListResponseDataCoupon" description: The list of coupons matching the search criteria. SearchCouponListResponseDataCoupon: type: object properties: id: type: string description: A unique ID that identifies different coupons. title: type: string description: Seller-specified title of the coupon. display_type: type: string description: |- The display type of coupons. Values: - `REGULAR`: Regular coupons which are displayed to TikTok users across all display locations available in TTS, including PLPs, PDPs, TikTok Videos, LIVE Rooms, Creator Showcases, and may be shared via TTS Customer Support instant messages. Includes coupons which target select customer segments. - `LIVE`: Coupons which are only displayed to TikTok users in LIVE Rooms. - `CREATOR_EXCLUSIVE`: Coupons that can be claimed through the display channels of the specified creator, such as their LIVE Rooms, and their Creator Showcase. - `CHAT`: Exclusive coupons that may be sent to customers via TTS customer support chat messages, but are not displayed in other display locations. - `PROMO_CODE`: Promo codes do not have dedicated display locations on TikTok, but may be shared with customers in LIVEs, in TikTok videos, or other social media platforms. They can be claimed by customers entering a claim code at checkout or by customers that use a custom promo code landing page URL. status: type: string description: |- Coupon's promotion status. Values: - `NOT_START`: Not available to TikTok users until the coupon's configured start time. - `ONGOING`: Available to TikTok users. - `EXPIRED`: Not available to TikTok users because it has expired. - `DEACTIVATED`: Deactivated by the seller and is not available to TikTok users. create_time: type: integer format: int64 description: The Unix timestamp, in milliseconds, when the coupon was created. update_time: type: integer format: int64 description: The Unix timestamp, in milliseconds, when the coupon was last updated. claim_duration: $ref: "#/components/schemas/ClaimDuration" description: Claimable period of the coupon redemption_duration: $ref: "#/components/schemas/RedemptionDuration" description: Period during which the coupon can be redeemed (i.e. applied to an order). promo_code: type: string description: Promotion code. Returned only when `display_type == 'PROMO_CODE'`. The string contains only Unicode letters or digits. The length of the string is in the range of `[6, 12]`. target_buyer_segment: type: string enum: - ALL - NEW - REPEAT_CUSTOMERS - RECENT_CUSTOMERS - FREQUENT_CUSTOMERS - LAPSED_CUSTOMERS - NEW_FOLLOWERS - EXISTING_ACTIVE_FOLLOWERS x-enum-descriptions: - May be discovered and claimed by all TTS buyers. - Customers who have never purchased from your shop. - People who have previously placed orders in your shop and made another purchase within certain days(30 days for non-US and 90 days for US). - People who have made their first purchase in your shop in the past certain days(30 days for non-US and 90 days for US). - Customers with more than 1 purchase within the last 90 days. - Customers with at least 1 purchase in the past 365 days but no purchases within the last certain days(90 days for non-US and 30 days for US). - People who started following the TikTok account of your shop in the past 30 days. - People who followed the TikTok account of your shop and engaged with your shop through LIVE, short videos or product cards in the past 30 days. description: |- The target buyer segment of the coupon. Possible enumerations are: - `ALL`: May be discovered and claimed by all TTS buyers. - `NEW`:Customers who have never purchased from your shop. - `REPEAT_CUSTOMERS`: People who have previously placed orders in your shop and made another purchase within certain days(30 days for non-US and 90 days for US). - `RECENT_CUSTOMERS`: People who have made their first purchase in your shop in the past certain days(30 days for non-US and 90 days for US). - `FREQUENT_CUSTOMERS`: Customers with more than 1 purchase within the last 90 days. - `LAPSED_CUSTOMERS`: Customers with at least 1 purchase in the past 365 days but no purchases within the last certain days(90 days for non-US and 30 days for US). - `NEW_FOLLOWERS`: People who started following the TikTok account of your shop in the past 30 days. - `EXISTING_ACTIVE_FOLLOWERS`: People who followed the TikTok account of your shop and engaged with your shop through LIVE, short videos or product cards in the past 30 days. usage_limits: $ref: "#/components/schemas/UsageLimit" description: Limitations for the use of the coupons. discount: $ref: "#/components/schemas/GetCouponResponseDataCouponDiscount" description: The coupon discount configuration, including type, reduction_amount, percentage, and max_discount. threshold: $ref: "#/components/schemas/GetCouponResponseDataCouponThreshold" description: Optional minimum purchase criteria that must be met in order to receive the coupon's discount. product_scope: type: string enum: - FULL_SHOP - SPECIFIC_PRODUCTS x-enum-descriptions: - All products sold in the shop are eligible for the coupon. - Only specified products are eligible for the coupon. The list of specified products are returned in the response of the `get_coupon` API. description: |- The range of the products which the coupon applies to. The possible enumerations are: - `FULL_SHOP`: All products sold in the shop are eligible for the coupon. - `SPECIFIC_PRODUCTS`: Only specified products are eligible for the coupon. The list of specified products are returned in the response of the `get_coupon` API. creation_source: type: string description: |- The system where the coupon is created: - `SELLER_CENTER`: Created via the Promotions section of TikTok Seller Center. - `SELLER_APP`: Created via the TikTok Seller Mobile App. - `TTS_CRM`: Created via the TikTok Shop CRM. SearchCreatorAffiliateOrdersRequest: type: object properties: create_time_ge: type: integer format: int64 description: |- Filter orders to show only those that are created on or after the specified date and time. Unix timestamp. Note: `create_time_ge` and `create_time_lt` together constitute the creation time filter condition. - If `create_time_ge` is filled but `create_time_lt` is empty, `create_time_lt` will default to the current time. - If `create_time_lt` is filled but `create_time_ge` is empty, `create_time_ge` will default to the earliest shop time. create_time_lt: type: integer format: int64 description: Filter orders to show only those created before the specified time, expressed as a Unix timestamp in seconds. Refer to the notes in `create_time_ge` for more usage information. SearchCreatorAffiliateOrdersResponse: 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/SearchCreatorAffiliateOrdersResponseData" SearchCreatorAffiliateOrdersResponseData: type: object properties: orders: type: array items: $ref: "#/components/schemas/SearchCreatorAffiliateOrdersResponseDataOrder" description: The order resource. next_page_token: type: string description: An opaque token used to retrieve the next page of results. Specify `create_time_ge` and `create_time_lt` in the first request and reuse the same values for every page. Pass a non-empty returned token as `page_token` in the next request. An empty value indicates the last page; stop requesting additional pages. total_count: type: integer format: int64 description: The total number of SKU orders that match the search criteria. `page_size` limits SKU-order rows before they are grouped into `orders`; because one order can contain multiple SKUs, the number of returned order objects can be less than `page_size`. Use `next_page_token` to continue pagination. SearchCreatorAffiliateOrdersResponseDataOrder: type: object properties: id: type: string description: The order identifier. create_time: type: integer format: int64 description: The time when the order was created, as a Unix timestamp in seconds (UTC). delivery_time: type: integer format: int64 description: The time when the order was delivered, as a Unix timestamp in seconds (UTC). status: type: string description: |- The current status of the order. Possible options are: - UNSPECIFIED: The status of the order is undefined. It might be updated later. - AWAITING PAYMENT：The order hasn't been paid yet, only estimated commission is available - To-SETTLE：The order is waiting for settlement, only estimated commission is available - SETTLED: The commission of the order is already settled. - REFUNDED: The order has been returned/refunded/canceled by the buyer, and no commission will be settled. - FROZEN: Possible fraud has been detected regarding the order. The commission will be unfrozen after the fraud is resolved. skus: type: array items: $ref: "#/components/schemas/SearchCreatorAffiliateOrdersResponseDataOrderSku" description: A list of SKUs associated with the order. SearchCreatorAffiliateOrdersResponseDataOrderSku: type: object properties: id: type: string description: The SKU identifier. campaign_id: type: string description: The campaign identifier associated with the order. open_collaboration_id: type: string description: The open collaboration identifier associated with the order. target_collaboration_id: type: string description: The target collaboration identifier associated with the order. product_name: type: string description: The product name in the TikTok Shop. product_id: type: string description: The product identifier. price: $ref: "#/components/schemas/Price" description: An object representing the localized price of the product. shop_name: type: string description: The name of the TIkTok Shop in which the product is offered for sale. content_type: type: string enum: - SHOP - VIDEO - LIVE - PRE_LIVE - PROMOTION_PAGE - LINKSHARE description: |- The content format of the creator content through which the order was created. Possible values: - SHOP - VIDEO - LIVE - PRE_LIVE - PROMOTION_PAGE - LINKSHARE content_id: type: string description: The content identifier for the creator content through which the order was created. quantity: type: integer format: int64 description: The quantity of this SKU in the order, including refunded units. commission_rate: type: integer format: int64 description: The total commission rate for this SKU, equal to the sum of the standard commission rate, shop ads commission rate, bonus rate, and reward rate. It is expressed in hundredths of a percent; the percent sign (`%`) is not included. For example, `3000` represents a 30% commission. commission_tier_setting: type: string description: Between Seller & Creator percentagecommission. When tiering commission model applied, will return each tier's commission rate seller set. commission_model: type: string description: |- The commission model used for the order. Possible values: - Fixed commission - Tiered commission commission_bonus_rate: type: integer format: int64 description: The commission bonus rate associated with the collaboration. It is expressed in hundredths of a percent; the percent sign (`%`) is not included. For example, `3000` represents a 30% commission. estimated_commission_base: $ref: "#/components/schemas/EstimatedCommissionBase" description: An object representing the estimated base commission at the time of order creation. standard_commission_rate: type: integer format: int64 description: The standard affiliate commission rate associated with the collaboration. It is expressed in hundredths of a percent; the percent sign (`%`) is not included. For example, `3000` represents a 30% commission. shop_ads_commission_rate: type: integer format: int64 description: The commission rate received by a creator for a sale associated with a specific piece of content. It is expressed in hundredths of a percent; the percent sign (`%`) is not included. For example, `3000` represents a 30% commission. estimated_bonus_commission: $ref: "#/components/schemas/EstimatedBonusCommission" description: An object representing the estimated bonus commission, calculated by multiplying the estimated commission base by the commission bonus rate. estimated_standard_commission: $ref: "#/components/schemas/EstimatedStandardCommission" description: An object representing the estimated standard affiliate commission, calculated by multiplying the estimated commission base by the `standard_commission_rate`. estimated_shop_ads_commission: $ref: "#/components/schemas/EstimatedShopAdsCommission" description: An object representing the estimated shop ads commission, calculated by multiplying the estimated commission base by the shop_ads_commission_rate estimated_commission: $ref: "#/components/schemas/EstimatedCommission" description: The creator's total estimated commission earnings for this SKU after applicable additions and deductions. actual_commission: $ref: "#/components/schemas/ActualCommission" description: Represents the final earnings of this sku, calculated by multiplying the actual commission base by the total commission rate, and then deducting the taxes or revenue sharing with the agency amount. actual_bonus_commission: $ref: "#/components/schemas/ActualBonusCommission" description: An object representing the actual bonus commission, calculated by multiplying the actual commission base by the commission bonus rate. actual_commission_base: $ref: "#/components/schemas/ActualCommissionBase" description: An object representing the actual commission base, calculated by multiplying the product sale price by the number of products sold, subtracting returned and refunded orders. actual_standard_commission: $ref: "#/components/schemas/ActualStandardCommission" description: An object representing the actual standard affiliate commission, calculated by multiplying the commission base by the standard_commission_rate. actual_shop_ads_commission: $ref: "#/components/schemas/ActualShopAdsCommission" description: An object representing the actual shop ads commission, calculated by multiplying the commission base by the shop_ads_commission_rate. returned_quantity: type: integer format: int64 description: The returned quantity for this SKU in the order. refunded_quantity: type: integer format: int64 description: The refunded quantity for this SKU in the order. tag: type: string description: A field for storing user-defined metadata for tracking purposes. creator_commission_reward_rate: type: integer format: int64 description: The commission reward rate that an affiliate partner allocates to the creator. It is expressed in hundredths of a percent; the percent sign (`%`) is not included. For example, `1000` represents 10%. estimated_creator_commission_reward_fee: $ref: "#/components/schemas/EstimatedCreatorCommissionRewardFee" description: Estimated creator commission reward fee. actual_creator_commission_reward_fee: $ref: "#/components/schemas/ActualCreatorCommissionRewardFee" description: Actual creator commission reward fee. isr: $ref: "#/components/schemas/SearchCreatorAffiliateOrdersResponseDataOrderSkuIsr" description: Only for Mexico creator, platform collected related revenue taxes on behalf of government based on regulation. iva: $ref: "#/components/schemas/SearchCreatorAffiliateOrdersResponseDataOrderSkuIva" description: Only for Mexico creator, platform collected related revenue taxes on behalf of government based on regulation. pit: $ref: "#/components/schemas/SearchCreatorAffiliateOrdersResponseDataOrderSkuPit" description: Only for VN/TH/PH/ID creators, sellers collect related withholding taxes based on regulation. shared_with_partner: $ref: "#/components/schemas/SearchCreatorAffiliateOrdersResponseDataOrderSkuSharedWithPartner" description: The amount of the creator's after-tax revenue shared with the affiliated institution under the applicable fee agreement. trace_info: $ref: "#/components/schemas/SearchCreatorAffiliateOrdersResponseDataOrderSkuTraceInfo" description: Extra information for tracing purposes. last_update_time: type: integer format: int64 description: The time when the record was last updated, as a Unix timestamp in seconds (UTC). is_carousel: type: boolean description: Carousel content may involve a commission rate discount. Returns true when the order is attributed to carousel content. SearchCreatorAffiliateOrdersResponseDataOrderSkuIsr: type: object properties: amount: type: string description: The actual isr amount. currency: type: string description: The currency code. SearchCreatorAffiliateOrdersResponseDataOrderSkuIva: type: object properties: amount: type: string description: The actual iva amount. currency: type: string description: The currency code. SearchCreatorAffiliateOrdersResponseDataOrderSkuPit: type: object properties: amount: type: string description: The actual pit amount. currency: type: string description: The currency code. SearchCreatorAffiliateOrdersResponseDataOrderSkuSharedWithPartner: type: object properties: amount: type: string description: The actual shared with partner amount. currency: type: string description: The currency code. SearchCreatorAffiliateOrdersResponseDataOrderSkuTraceInfo: type: object properties: id: type: string description: When `trace_info.type` is `GENERAL`, this is the `{eid}` provided in `sharing_link`; when `trace_info.type` is `SPECIFIC`, this is the `publisher_id`. type: type: string description: For the orders coming from the sharing links for specific publishers, the value is `SPECIFIC`; for the orders coming from the general sharing links, the value is `GENERAL`. SearchCreatorSampleApplicationsRequest: type: object properties: application_statuses: type: array items: type: string description: |- Filter sample applications by status. The possible enumerated values are: - PENDING: The sample application is waiting for the seller's review. - AWAITING_SHIPMENT: The application is approved, and the seller needs to ship the sample. - SHIPPED: The sample has been shipped by the seller and is waiting for the creator to receive the package. - CONTENT_PENDING: The creator has received the sample package and is expected to create content. - REJECT_CANCELLED: The sample application has been rejected by the seller. - OVERDUE_CANCELLED: The sample application has expired due to being overdue. - UNFULFILL_CANCELLED: The creator did not fulfill the commitment to create content within the agreed timeframe. - FULFILLMENT_SUSPEND: The application fulfillment was paused because the product could not be promoted. - DEL_OPEN_COLLAB: Open collaboration has been deleted. - SELLER_NOT_SHIP_CANCELLED: The seller did not ship the sample within the required timeframe. - WITHDRAW_CANCELLED: The creator withdrew the sample application before the seller approved it. - UNFULFILLABLE_CANCELLED: The application was cancelled due to reasons beyond the creator's control, making it impossible to create content. - OPS_CANCELLED: The application was manually cancelled by operations staff. - OPS_FAILED: The application was marked as failed by operations staff. - OPS_ COMPLETED: The application was manually marked as completed by operations staff. - COMPLETED: The application is complete, and the creator has posted the content. - TO_BE_POST: The creator has not posted a video or LIVE for this sample. - POST_IN_REVIEW: The creator has posted a video or LIVE that has not yet satisfied the fulfillment requirements. - POST_FAILED: The creator posted a video or LIVE but deleted it before completing sample fulfillment. - CANCELED: The sample application has been canceled. This field allows for tracking the status of a sample application throughout its lifecycle, providing visibility into each stage of the process for sellers and creators. SearchCreatorSampleApplicationsResponse: 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/SearchCreatorSampleApplicationsResponseData" SearchCreatorSampleApplicationsResponseData: type: object properties: next_page_token: type: string description: Page token to query next page orders, last page is empty string. sample_applications: type: array items: $ref: "#/components/schemas/SearchCreatorSampleApplicationsResponseDataSampleApplication" description: The sample application information. SearchCreatorSampleApplicationsResponseDataSampleApplication: type: object properties: id: type: string description: The unique id of sample application. sample_product: $ref: "#/components/schemas/SampleProduct" description: The sample product information. main_order_id: type: string description: The sample order is generated after the sample application is approved by seller. activity_id: type: string description: The sample activity identifier id(only for sample activity). status: type: string description: |- The status of sample applications. The possible enumerated values are: - PENDING: The sample application is waiting for the seller's review. - AWAITING_SHIPMENT: The application is approved, and the seller needs to ship the sample. - SHIPPED: The sample has been shipped by the seller and is waiting for the creator to receive the package. - REJECT_CANCELLED: The sample application has been rejected by the seller. - OVERDUE_CANCELLED: The sample application has expired due to being overdue. - UNFULFILL_CANCELLED: The creator did not fulfill the commitment to create content within the agreed timeframe. - FULFILLMENT_SUSPEND: the application fulfillment was paused due to the product status being unpromotable. - DEL_OPEN_COLLAB: Open collaboration has been deleted. - SELLER_NOT_SHIP_CANCELLED: The seller did not ship the sample within the required timeframe. - WITHDRAW_CANCELLED: The creator withdrew the sample application before the seller approved it. - UNFULFILLABLE_CANCELLED: The application was cancelled due to reasons beyond the creator's control, making it impossible to create content. - OPS_CANCELLED: The application was manually cancelled by operations staff. - OPS_FAILED: The application was marked as failed by operations staff. - OPS_ COMPLETED: The application was manually marked as completed by operations staff. - COMPLETED: The application is complete, and the creator has posted the content. - TO_BE_POST: the creator has not posted videos/lives for this sample - POST_IN_REVIEW: the creator has posted videos/lives which have not satisfied fulfillment rules. - POST_FAILED: the creator has posted videos/lives and deleted them before completing sample fulfillment. - CANCELED: this application(order) has been canceled. This field allows tracking the status of a sample application throughout its lifecycle, providing visibility into each stage of the process for sellers and creators. creator_fulfillment: $ref: "#/components/schemas/SearchCreatorSampleApplicationsResponseDataSampleApplicationCreatorFulfillment" description: Fulfillment info for this sample application. SearchCreatorSampleApplicationsResponseDataSampleApplicationCreatorFulfillment: type: object properties: id: type: string description: Fulfillment ID. expiration_time: type: integer format: int64 description: Fulfillment deadline timestamp, in seconds. total_suspend_duration: type: integer format: int64 description: Total suspension duration for fulfillment, in seconds. status: type: string enum: - PENDING - ONGOING - SUCCEED - FAILED - OVERDUE - SUSPEND - CANCELLED - EXEMPTED x-enum-descriptions: - The creator is yet to fulfill the content creation obligation. - Fulfillment is in progress; content has been created and is being evaluated against criteria. - Fulfillment has been successfully completed; the content meets the required standards. - Fulfillment failed; the content did not meet the required standards. - Fulfillment is overdue; the creator did not meet the deadline. - Fulfillment has been suspended. - Fulfillment has been cancelled, either by the creator or due to operational reasons. - The creator has been exempted from the fulfillment obligation. description: |- Fulfillment status, It indicates the current status of the fulfillment process. The possible values are: - PENDING: The creator is yet to fulfill the content creation obligation. - ONGOING: Fulfillment is in progress; content has been created and is being evaluated against criteria. - SUCCEED: Fulfillment has been successfully completed; the content meets the required standards. - FAILED: Fulfillment failed; the content did not meet the required standards. - OVERDUE: Fulfillment is overdue; the creator did not meet the deadline. - SUSPEND: Fulfillment has been suspended. - CANCELLED: Fulfillment has been cancelled, either by the creator or due to operational reasons. - EXEMPTED: The creator has been exempted from the fulfillment obligation. bound_product_status: type: string enum: - UNKNOWN - LIVE - OUT_OF_STOCK - SELLER_DEACTIVATE - PLATFORM_DEACTIVATE - NO_PLAN - PERMANENT_DELETED x-enum-descriptions: - The marketing status of the product is unknown. - The product is available and can be used for fulfillment. - The product is out of stock and cannot be fulfilled. - The product has been deactivated by the seller. - The product has been deactivated by the platform. - There is no valid plan available for the creator to market the product. - The product has been permanently deleted and is no longer available. description: |- Represents the marketing status of a product associated with a fulfillment order. It indicates whether the product is available for marketing and fulfillment. The possible values are: - UNKNOWN: The marketing status of the product is unknown. - LIVE: The product is available and can be used for fulfillment. - OUT_OF_STOCK: The product is out of stock and cannot be fulfilled. - SELLER_DEACTIVATE: The product has been deactivated by the seller. - PLATFORM_DEACTIVATE: The product has been deactivated by the platform. - NO_PLAN: There is no valid plan available for the creator to market the product. - PERMANENT_DELETED: The product has been permanently deleted and is no longer available. This field helps sellers and creators understand the current status of products associated with fulfillment orders, ensuring that all parties are aware of the availability and marketing status of the products involved in sample applications and collaborations. SearchCreatorTargetCollaborationsRequest: type: object properties: shop_id: type: string description: The TikTok Shop identifier. keyword_type: type: string enum: - TARGET_COLLABORATIONS_ID - TARGET_COLLABORATIONS_NAME x-enum-descriptions: - Match by target collaboration ID and return matching collaborations in the `LIVE`, `EXPIRED`, `DELETED`, or `ENDED` state. - Match by target collaboration name and return matching collaborations in the `LIVE` state only. description: |- The type of value specified in `keyword`. Provide `keyword` and `keyword_type` together to filter by ID or name. Omit both fields to search without an ID or name filter. Possible values: - `TARGET_COLLABORATIONS_ID`: Match by target collaboration ID and return matching collaborations in the `LIVE`, `EXPIRED`, `DELETED`, or `ENDED` state. - `TARGET_COLLABORATIONS_NAME`: Match by target collaboration name and return matching collaborations in the `LIVE` state only. keyword: type: string description: The target collaboration ID or name to search for, as specified by `keyword_type`. For `TARGET_COLLABORATIONS_ID`, provide a base-10 integer. For `TARGET_COLLABORATIONS_NAME`, provide a value shorter than 500 bytes. required: - shop_id SearchCreatorTargetCollaborationsResponse: 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/SearchCreatorTargetCollaborationsResponseData" SearchCreatorTargetCollaborationsResponseData: type: object properties: total_count: type: integer format: int64 description: The total number of target collaborations that match the search criteria. next_page_token: type: string description: An opaque token used to retrieve the next page of a paginated result set. target_collaborations: type: array items: $ref: "#/components/schemas/SearchCreatorTargetCollaborationsResponseDataTargetCollaboration" description: A list of target collaboration objects. SearchCreatorTargetCollaborationsResponseDataTargetCollaboration: type: object properties: id: type: string description: The target collaboration identifier. name: type: string description: The target collaboration name. status: type: string description: |- The target collaboration state. This is an enumerated type with values: - LIVE - EXPIRED - DELETED - ENDED products: type: array items: $ref: "#/components/schemas/SearchCreatorTargetCollaborationsResponseDataTargetCollaborationProduct" description: A list of products associated with the target collaboration. SearchCreatorTargetCollaborationsResponseDataTargetCollaborationProduct: type: object properties: id: type: string description: The product identifier. title: type: string description: The product name. main_image_url: type: string description: The product image URL in the TikTok Shop. commission: $ref: "#/components/schemas/SearchCreatorTargetCollaborationsResponseDataTargetCollaborationProductCommission" description: The commission rate and estimated commission amount for the product in this target collaboration. SearchCreatorTargetCollaborationsResponseDataTargetCollaborationProductCommission: type: object properties: rate: type: integer format: int64 description: The commission rate for the target collaboration in hundredths of a percent. For example, `3587` is a commission rate of `35.87%`. amount: type: string description: The estimated commission amount calculated from the product's minimum price, in the currency specified by `currency`. currency: type: string description: The currency code. SearchCreatorsInCreatorMarketplaceRequest: type: object properties: search_key: type: string description: |- Caching search results improves api performance and ensures stable request results. You don't need to pass a value on the first call. For the second call, please pass the value returned in the response of the first call. keyword: type: string description: Searching creators by keyword, matching based on TikTok Username and Nickname. follower_demographics: $ref: "#/components/schemas/SearchCreatorsInCreatorMarketplaceRequestFollowerDemographic" description: Filtering creators by follower demographics gmv_ranges: type: array items: type: string description: |- Filtering by GMV range intervals which include: GMV_RANGE_0_100: "0-100", GMV_RANGE_100_1000: "100-1000", GMV_RANGE_1000_10000: "1000-10000", GMV_RANGE_10000_AND_ABOVE: "10000+" For example: - If GMV_RANGE_0_100 is passed, it means filtering the creator data that is greater than or equal to 0 and less than or equal to 100. - If GMV_RANGE_0_100 and GMV_RANGE_100_1000 are passed, it means to filter the creator data that is greater than or equal to 0 and less than or equal to 1000. units_sold_ranges: type: array items: type: string description: |- Filtering by sales volume range intervals which include: UNITS_SOLD_RANGE_0_10: "0-10", UNITS_SOLD_RANGE_10_100: "10-100", UNITS_SOLD_RANGE_100_1000: "100-1000", UNITS_SOLD_RANGE_1000_AND_ABOVE: "1000+" For example: - If UNITS_SOLD_RANGE_0_10 is passed, it means filtering the creator data that is greater than or equal to 0 and less than or equal to 10. - If UNITS_SOLD_RANGE_0_10 and UNITS_SOLD_RANGE_10_100 are passed, it means to filter the creator data that is greater than or equal to 0 and less than or equal to 100. category: type: array items: $ref: "#/components/schemas/SearchCreatorsInCreatorMarketplaceRequestCategory" description: Array of category filter objects. Use [Get Categories](https://partner.tiktokshop.com/docv2/page/get-categories-202309) to retrieve category IDs. content_performance: $ref: "#/components/schemas/SearchCreatorsInCreatorMarketplaceRequestContentPerformance" description: Object containing content performance filters affiliate_data: $ref: "#/components/schemas/SearchCreatorsInCreatorMarketplaceRequestAffiliateData" description: Object which contains affiliate based data advanced_filters: $ref: "#/components/schemas/SearchCreatorsInCreatorMarketplaceRequestAdvancedFilter" description: Advanced filters are specific to each country. Before using advanced filters with this API, use [Get Seller Search Creator Marketplace Advanced Filters](https://partner.tiktokshop.com/docv2/page/get-seller-search-creator-marketplace-advanced-filters) to retrieve the filters available for the relevant country. data_groups: type: array items: type: string description: |- Creator's Data Group, get all group by default, which include: - BASIC_CREATOR_INFORMATION - CONTENT_PERFORMANCE - FOLLOWER_INFORMATION - COLLABORATION - SALES_AND_GMV SearchCreatorsInCreatorMarketplaceRequestAdvancedFilter: type: object properties: content_preference_type: type: array items: type: string description: |- Content preference type. e.g. -VIDEO -LIVE eligible_flat_fee: type: boolean description: Creator is eligible for flat fee invitation, only available in US local seller option_list: type: array items: $ref: "#/components/schemas/SearchCreatorsInCreatorMarketplaceRequestAdvancedFilterOptionList" description: Creator Marketplace Advanced Filter Option List. Please use "Get Seller Search Creator Marketplace Advanced Filters"(https://partner.tiktokshop.com/docv2/page/get-seller-search-creator-marketplace-advanced-filters) get available options for you first sorter_algorithm_id: type: string description: Sorter algorithm id. Please use "Get Seller Search Creator Marketplace Advanced Filters"(https://partner.tiktokshop.com/docv2/page/get-seller-search-creator-marketplace-advanced-filters) get available sorter algorithm for you first. Default is 1(default sorter) SearchCreatorsInCreatorMarketplaceRequestAdvancedFilterOptionList: type: object properties: options: type: array items: $ref: "#/components/schemas/Option" description: Options in this option type option_type: type: string description: option type SearchCreatorsInCreatorMarketplaceRequestAffiliateData: type: object properties: avg_commission_rate: type: string description: |- - ALL - LESS_THAN_20% - LESS_THAN_15% - LESS_THAN_10% - LESS_THAN_5% Creator's average commission rate range based on showcase products, sales, and promoted products in the last 30 days. You can only pick one value. post_rate: type: string description: |- These categories represent how often a creator posts a shoppable video or LIVE after receiving a sample. - ALL - OK - GOOD - BETTER Every country has its own benchmark based on what is a GOOD vs BETTER fulfillment rate. BETTER is always going to have the highest fulfillment rate, including 100% fulfillment rate. creator_agency_staus: type: string description: |- - AGENCY_MANAGED - INDEPENDENT is_fast_growing: type: boolean description: Top 10% of creators with the greatest increase in transactions, revenue, shoppable videos, live views, or followers in the last 30 days not_invited_l90_days: type: boolean description: |- True/False Select this filter to see creators you haven't invited in the last 90 days SearchCreatorsInCreatorMarketplaceRequestCategory: type: object properties: parent_category_id: type: string description: Category of the parent category. If you are only using a parent category, you do not need to pass in a child category ID. child_category_id_list: type: array items: type: string description: If you are using the category ID for a child category, you must pass the parent category as well. A child category is only 1 level deeper than the parent category. We do not support going deeper down the category tree (some countries have 4 levels, others have 7) SearchCreatorsInCreatorMarketplaceRequestContentPerformance: type: object properties: avg_video_views: type: string description: |- Average Video Views more than You can pass in average video views anywhere between 0 and 100k Pick any whole number between 0 and 100,000, and we will return all results with average video views greater than that number. You can only pass in Average Video Views OR Average Shoppable Video Views. Using both filters will cause the API call to fail. avg_shoppable_video_views: type: string description: |- You can pass in average shoppable video views anywhere between 0 and 100k Pick any whole number between 0 and 100,000, and we will return all results with average shoppable video views greater than that number. You can only pass in Average Video Views OR Average Shoppable Video Views. Using both filters will cause the API call to fail. avg_engagement_rate: type: string description: |- Average engagement rate more than 0-20. You can only filter by increments of 1% point, up to 20%. avg_shopable_engagement_rate: type: string description: |- Average shoppable engagement rate more than 0-20. You can only filter by increments of 1% point, up to 20%. avg_live_avg_viewers_ge: type: string description: |- Filters creators whose average LIVE viewers are greater than or equal to the specified value. Enter a whole number from 0 to 100,000. You can only pass one of avg_live_avg_viewers_ge and avg_shoppable_live_avg_viewers_ge. Using both filters causes the API call to fail. avg_shoppable_live_avg_viewers_ge: type: string description: |- Filters creators whose average shoppable LIVE viewers are greater than or equal to the specified value. Enter a whole number from 0 to 100,000. You can only pass one of avg_live_avg_viewers_ge and avg_shoppable_live_avg_viewers_ge. Using both filters causes the API call to fail. SearchCreatorsInCreatorMarketplaceRequestFollowerDemographic: type: object properties: age_ranges: type: array items: type: string description: |- Follower age filtering options, which are range intervals, include: AGE_RANGE_18_24: "18-24", AGE_RANGE_25_34: "25-34", AGE_RANGE_35_44: "35-44", AGE_RANGE_45_54: "45-54", AGE_RANGE_55_AND_ABOVE: "55+" count_range: $ref: "#/components/schemas/SearchCreatorsInCreatorMarketplaceRequestFollowerDemographicCountRange" description: Follower count filtering gender_distribution: $ref: "#/components/schemas/SearchCreatorsInCreatorMarketplaceRequestFollowerDemographicGenderDistribution" description: |- Filters creators by follower gender. Possible values: - MALE - FEMALE SearchCreatorsInCreatorMarketplaceRequestFollowerDemographicCountRange: type: object properties: count_ge: type: integer format: int64 description: |- The minimum value of follower count. The value passed in must be greater than or equal to 0 count_le: type: integer format: int64 description: |- The maximum value of follower count. - Generally, a value greater than or equal to 0 needs to be passed. If a value less than 0 is passed, it means that the field will not be filtered. SearchCreatorsInCreatorMarketplaceRequestFollowerDemographicGenderDistribution: type: object properties: gender: type: string description: A particular gender, "MALE" or "FEMALE" percentage_ge: type: integer format: int64 description: |- Greater than or equal to a certain percentage, scaled up by 10,000 times. For example, 6000 stands for 0.6 or 60% SearchCreatorsInCreatorMarketplaceResponse: 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/SearchCreatorsInCreatorMarketplaceResponseData" SearchCreatorsInCreatorMarketplaceResponseData: type: object properties: next_page_token: type: string description: Pagination token for the next page. To continue, pass this value as query parameter `page_token`, pass the `search_key` returned in the same response as request-body `search_key`, and reuse the same `page_size`. An empty token means there are no more results. search_key: type: string description: Search key for continuing the same search with stable results. Pass this value as search_key in the next request. creators: type: array items: $ref: "#/components/schemas/SearchCreatorsInCreatorMarketplaceResponseDataCreator" description: Creator records with basic profile, content performance, follower, GMV, and sales-range information. Included fields depend on the requested `data_groups`. SearchCreatorsInCreatorMarketplaceResponseDataCreator: type: object properties: username: type: string description: Creator's TikTok Username nickname: type: string description: Creator's TikTok Nickname avatar: $ref: "#/components/schemas/Avatar" description: Creator's profile picture selection_region: type: string description: Regions where the creator operates and promotes products category_ids: type: array items: type: string description: It indicates the main product categories when the creator posts products. avg_ec_live_uv: type: integer format: int64 description: Average UV for creator's e-commerce live streams avg_ec_video_view_count: type: integer format: int64 description: Average views for creator's e-commerce videos follower_count: type: integer format: int64 description: Follower count gmv: $ref: "#/components/schemas/GetLiveRoomGMVAndOrderTrendsResponseDataGmvTrendPerformanceDataPointGmv" description: |- Creator GMV-related information If the creator does not authorize sharing precise data, this will be omitted. live_gmv: $ref: "#/components/schemas/GetMarketplaceCreatorPerformanceResponseDataCreatorLiveGmv" description: |- Live stream GMV If the creator does not authorize sharing precise data, this will be omitted. video_gmv: $ref: "#/components/schemas/VideoGmv" description: |- Video GMV-related information If the creator does not authorize sharing precise data, this will be omitted. gmv_range: $ref: "#/components/schemas/GmvRange" description: |- GMV range. Applicable if the target market is the US and the creator does not authorize sharing precise data. units_sold_range: $ref: "#/components/schemas/UnitsSoldRange" description: The range of minimum number of units sold to maximum number of units sold over the lifetime of the creator account. Note that this property is included if the target market is US only. Note that if the creator has not given permission for precise data sharing, these properties will not be present. top_follower_demographics: $ref: "#/components/schemas/SearchCreatorsInCreatorMarketplaceResponseDataCreatorTopFollowerDemographic" description: Top follower information of the creator creator_open_id: type: string description: Creator Open ID. [More details](https://partner.tiktokshop.com/docv2/page/3obfokj6) creator_profile: $ref: "#/components/schemas/SearchCreatorsInCreatorMarketplaceResponseDataCreatorCreatorProfile" description: Advanced creator profile information. An empty object means that this profile information is not currently supported for your account or region. SearchCreatorsInCreatorMarketplaceResponseDataCreatorCreatorProfile: type: object properties: is_official_recommend: type: boolean description: Creator has official recommend tag or not creator_bind_mcn_name: type: string description: Creator bind MCN name is_fast_growing: type: boolean description: Creator has fast growing tag or not has_collaborated: type: boolean description: Has collaborated with this creator or not user_type_tag: type: array items: type: integer format: int64 enum: - 1 - 2 x-enum-descriptions: - Privacy creator - Carve-out creator description: |- User type tag. Possible values: - 1: Privacy creator - 2: Carve-out creator has_invited_90d: type: boolean description: Has invited creaor before 90 days is_creator_blocked: type: boolean description: Is this creator blocked by shop or not pps_score: type: string description: Creator promotion performance score(PPS).The score reflects the quality of a creator's shoppable content and product selection over the past 30 days. A high score may indicate a better shopping experience, with fewer potential refunds or negative reviews. e.g. 4.3/5.0 is_eligible_flat_fee: type: boolean description: Is creator eligible for flat fee, only available for US local seller is_rising_star: type: boolean description: Creator has rising star tag or not creator_level: type: integer format: int64 description: Creator level SearchCreatorsInCreatorMarketplaceResponseDataCreatorTopFollowerDemographic: type: object properties: age_ranges: type: array items: type: string description: |- Return the top 3 age ranges of the followers. Ranges are : AGE_RANGE_18_24: "18-24", AGE_RANGE_25_34: "25-34", AGE_RANGE_35_44: "35-44", AGE_RANGE_45_54: "45-54", AGE_RANGE_55_AND_ABOVE: "55+" major_gender: $ref: "#/components/schemas/SearchCreatorsInCreatorMarketplaceResponseDataCreatorTopFollowerDemographicMajorGender" description: Major gender of the followers SearchCreatorsInCreatorMarketplaceResponseDataCreatorTopFollowerDemographicMajorGender: type: object properties: gender: type: string description: Top follower gender category of the creator, "MALE" or "FEMALE" percentage: type: integer format: int64 description: |- Percentage of top follower gender, scaled up by 10,000 times. For example, 6524 stands for 0.6524 or 65.24%. You can then infer that the opposite gender would be 0.3476 or 34.76%. SearchFBTInventoryRecordRequest: type: object properties: goods_ids: type: array items: type: string description: "The IDs of goods generated by the Fulfilled by TikTok system to search. Maximum: 100 IDs. If IDs are provided, the API returns only inventory records for those goods; if omitted, it returns inventory records for all goods with non-zero inventory." fbt_warehouse_ids: type: array items: type: string description: "The IDs of Fulfilled by TikTok warehouses to search. Maximum: 100 IDs. The API searches only warehouses available to the merchant: if IDs are provided, the search is limited to matching IDs; if omitted, all available warehouses are searched." create_time_ge: type: integer format: int64 description: Filter inventory record creation time to show only those that are created on or after the specified date and time. Unix timestamp in seconds. `create_time_ge` is 0 by default. create_time_le: type: integer format: int64 description: Filter inventory record creation time to show only those that are created on or before the specified date and time. Unix timestamp in seconds. `create_time_le` is the current time by default. SearchFBTInventoryRecordResponse: 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/SearchFBTInventoryRecordResponseData" SearchFBTInventoryRecordResponseData: type: object properties: inventory_records: type: array items: $ref: "#/components/schemas/SearchFBTInventoryRecordResponseDataInventoryRecord" description: A list of inventory records information. next_page_token: type: string description: An opaque token used to retrieve the next page of a paginated result set. Provide this value in the `page_token` parameter of your request if the current response does not return all the results. total_count: type: integer format: int64 description: The total number of the search results. SearchFBTInventoryRecordResponseDataInventoryRecord: type: object properties: goods: $ref: "#/components/schemas/SearchFBTInventoryRecordResponseDataInventoryRecordGood" description: The reference used to track products and SKUs within Fulfilled by TikTok's network. fbt_warehouse_id: type: string description: The identifier for warehouse generated by Fulfilled by TikTok system. order: $ref: "#/components/schemas/SearchFBTInventoryRecordResponseDataInventoryRecordOrder" description: The information of order that triggers current inventory change. create_time: type: integer format: int64 description: The time when the inventory record is created, Unix timestamp in seconds. inventory_goods_type: type: string enum: - NORMAL - DEFECTIVE description: |- The type of goods in current inventory record. Possible values: - NORMAL - DEFECTIVE initial_on_hand_quantity: type: integer format: int64 description: The number of goods units physically in the Fulfilled by TikTok warehouse before current inventory change, excluding those in transit. final_on_hand_quantity: type: integer format: int64 description: The number of goods units physically in the Fulfilled by TikTok warehouse after current inventory change, excluding those in transit. changed_quantity: type: integer format: int64 description: The change in the number of units is calculated as the `final_on_hand_quantity` - `initial_on_hand_quantity`. SearchFBTInventoryRecordResponseDataInventoryRecordGood: type: object properties: id: type: string description: The identifier for goods generated by Fulfilled by TikTok system. reference_code: type: string description: The identifier for goods defined by merchant. name: type: string description: The goods name. SearchFBTInventoryRecordResponseDataInventoryRecordOrder: type: object properties: id: type: string description: The identifier for order generated by Fulfilled by TikTok system. type: type: string enum: - INBOUND_ORDER - RETURN_TO_SUPPLIER_ORDER - DISPOSAL - INVENTORY_STATUS_ADJUSTMENT_ORDER - CONSIGN_ORDER - INVENTORY_COUNT_ORDER - FAILED_DELIVERY - CUSTOMER_RETURN - INVENTORY_QUANTITY_ADJUSTMENT_ORDER - INVENTORY_TRANSFER_ORDER description: |- The type of order. Possible values: - INBOUND_ORDER - RETURN_TO_SUPPLIER_ORDER - DISPOSAL - INVENTORY_STATUS_ADJUSTMENT_ORDER - CONSIGN_ORDER - INVENTORY_COUNT_ORDER - FAILED_DELIVERY - CUSTOMER_RETURN - INVENTORY_QUANTITY_ADJUSTMENT_ORDER - INVENTORY_TRANSFER_ORDER SearchFBTInventoryRequest: type: object properties: goods_ids: type: array items: type: string description: |- The identifiers for goods generated by the Fulfilled by TikTok system. Maximum: 100 goods IDs per request. If specified, only inventory information for those goods is returned. If both `goods_ids` and `sku_ids` are omitted, all goods with non-zero inventory are returned. Do not provide `goods_ids` and `sku_ids` in the same request. Both fields may be omitted. fbt_warehouse_ids: type: array items: type: string maxItems: 100 description: The identifiers of warehouses generated by the Fulfilled by TikTok system. Specify up to 100 warehouse IDs to return inventory records only for subscribed warehouses that match those IDs. If omitted or empty, inventory records from all warehouses subscribed by the merchant are returned. sku_ids: type: array items: type: string description: "TikTok Shop SKU identifiers used to select goods matched to those SKUs. Maximum: 100 SKU IDs per request. Do not provide `sku_ids` and `goods_ids` in the same request; both fields may be omitted. For each matched goods record, the returned `goods.skus` list contains the SKU inventory supplied for that goods record and is not restricted to the requested SKU IDs." SearchFBTInventoryResponse: 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/SearchFBTInventoryResponseData" SearchFBTInventoryResponseData: type: object properties: next_page_token: type: string description: An opaque token used to retrieve the next page of a paginated result set. Provide this value in the `page_token` parameter of your next request. An empty `next_page_token` means there are no more pages. total_count: type: integer format: int64 description: The total number of warehouse-goods inventory records that match the applied filters. inventory: type: array items: $ref: "#/components/schemas/SearchFBTInventoryResponseDataInventory" description: A list of inventory records. Each item represents one goods item at one Fulfilled by TikTok warehouse and can include the associated SKU inventory breakdown. SearchFBTInventoryResponseDataInventory: type: object properties: goods: $ref: "#/components/schemas/SearchFBTInventoryResponseDataInventoryGood" description: The reference used to track products and SKUs within Fulfilled by TikTok's network. fbt_warehouse_id: type: string description: The identifier for warehouse generated by Fulfilled by TikTok system. in_transit_quantity: type: integer format: int64 description: The number of goods units currently en route to the warehouse. The inventory includes inbound replenishments, customer returns, unsuccessful delivery returns, etc. on_hand_detail: $ref: "#/components/schemas/SearchFBTInventoryResponseDataInventoryOnHandDetail" description: The current-in-warehouse inventory detail for the goods. SearchFBTInventoryResponseDataInventoryGood: type: object properties: id: type: string description: The identifier for goods generated by Fulfilled by TikTok system. reference_code: type: string description: The identifier for goods defined by the merchant, commonly used to reference the ID from the merchant's other order management systems. name: type: string description: The goods name. skus: type: array items: $ref: "#/components/schemas/SearchFBTInventoryResponseDataInventoryGoodSku" description: A list of inventory information for Stock Keeping Units (SKUs) matched with current Fulfilled by TikTok goods. SearchFBTInventoryResponseDataInventoryGoodSku: type: object properties: id: type: string description: The identifier for SKU generated by TikTok Shop system. on_hand_detail: $ref: "#/components/schemas/SearchFBTInventoryResponseDataInventoryGoodSkuOnHandDetail" description: The inventory information of SKU physically in the warehouse, excluding those in transit or broken. SearchFBTInventoryResponseDataInventoryGoodSkuOnHandDetail: type: object properties: total_quantity: type: integer format: int64 description: The total number of units for current SKU, consist of `available_quantity` and `reserved_quantity`. available_quantity: type: integer format: int64 description: |- The number of units available for sale. Note: The number does not include reserved units. reserved_quantity: type: integer format: int64 description: The number of units reserved for customer orders or return to supplier shipment. SearchFBTInventoryResponseDataInventoryOnHandDetail: type: object properties: total_quantity: type: integer format: int64 description: The total on-hand quantity for the goods at the Fulfilled by TikTok warehouse, excluding in-transit inventory. available_quantity: type: integer format: int64 description: |- The number of units available for sale. Note: The number does not include reserved units. reserved_quantity: type: integer format: int64 description: The number of units reserved for customer orders or return to supplier shipment. unfulfillable_quantity: type: integer format: int64 description: The number of defective units in the warehouse. SearchGlobalProductsRequest: type: object properties: status: type: string enum: - PUBLISHED - UNPUBLISHED - DRAFT - DELETED description: |- Filter global products by their status. Possible values: - PUBLISHED - UNPUBLISHED - DRAFT - DELETED seller_skus: type: array items: type: string description: A Seller SKU used to filter global products. Provide no more than one Seller SKU. The API returns global products that include the specified Seller SKU. create_time_ge: type: integer format: int64 description: |- Filter global products to show only those that are created on or after the specified date and time. Unix timestamp in seconds. **Note**: The "create_time_ge" and "create_time_le" together constitute the creation time filter condition. - If "create_time_ge" is filled but "create_time_le" is empty, "create_time_le" will default to the current time. - If "create_time_le" is filled but "create_time_ge" is empty, "create_time_ge" will default to the earliest shop time. create_time_le: type: integer format: int64 description: |- Filter global products to show only those that are created on or before the specified date and time. Unix timestamp in seconds. Refer to notes in "create_time_ge" for more usage information. update_time_ge: type: integer format: int64 description: |- Filter global products to show only those that are updated on or after the specified date and time. Unix timestamp in seconds. **Note**: The fields "update_time_ge" and "update_time_le" together define the update time filter condition. - If "update_time_ge" is filled but "update_time_le" is empty, "update_time_le" will default to the current time. - If "update_time_le" is filled but "update_time_ge" is empty, "update_time_ge" will default to the earliest shop time. update_time_le: type: integer format: int64 description: |- Filter global products to show only those that are updated on or before the specified date and time. Unix timestamp in seconds. Refer to notes in `update_time_ge` for more usage information. SearchGlobalProductsResponse: 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/SearchGlobalProductsResponseData" SearchGlobalProductsResponseData: type: object properties: next_page_token: type: string description: An opaque token used to retrieve the next page of a paginated result set. Provide this value in the `page_token` parameter of your request if the current response does not return all the results. total_count: type: integer format: int64 description: The total number of global products that meet the query conditions. global_products: type: array items: $ref: "#/components/schemas/SearchGlobalProductsResponseDataGlobalProduct" description: The list of global products that meet the query conditions. SearchGlobalProductsResponseDataGlobalProduct: type: object properties: id: type: string description: The global product ID in TikTok Shop. title: type: string description: The product title. status: type: string enum: - PUBLISHED - UNPUBLISHED - DRAFT - DELETED description: |- The status of the product. Possible values: - PUBLISHED - UNPUBLISHED - DRAFT - DELETED skus: type: array items: $ref: "#/components/schemas/SearchGlobalProductsResponseDataGlobalProductSku" description: A list of global Stock Keeping Units (SKUs) used to identify distinct variants of the product. create_time: type: integer format: int64 description: |- The time when the product is created. Unix timestamp in seconds. update_time: type: integer format: int64 description: |- The time when the product is last updated. Unix timestamp in seconds. SearchGlobalProductsResponseDataGlobalProductSku: type: object properties: id: type: string description: The global SKU ID in TikTok Shop. One product can contain multiple SKU IDs. seller_sku: type: string description: An internal code/name for managing SKUs, not visible to buyers. SearchGoodsHazmatAndExpirationInfoRequest: type: object properties: tts_sku_ids: type: array items: type: string description: Identifier for Stock Keeping Unit (SKU) generated by TikTok Shop system required: - tts_sku_ids SearchGoodsHazmatAndExpirationInfoResponse: 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/SearchGoodsHazmatAndExpirationInfoResponseData" SearchGoodsHazmatAndExpirationInfoResponseData: type: object properties: hazmat_and_expiration_info: $ref: "#/components/schemas/SearchGoodsHazmatAndExpirationInfoResponseDataHazmatAndExpirationInfo" description: Container for per-SKU hazmat, lot-control, and expiration-management results. SearchGoodsHazmatAndExpirationInfoResponseDataHazmatAndExpirationInfo: type: object properties: hazmat_and_expiration_dto_list: type: array items: $ref: "#/components/schemas/SearchGoodsHazmatAndExpirationInfoResponseDataHazmatAndExpirationInfoHazmatAndExpirationDtoList" description: Per-SKU hazmat, lot-control, and expiration-management results. Correlate each entry with the requested SKU using `tts_sku_id`. SearchGoodsHazmatAndExpirationInfoResponseDataHazmatAndExpirationInfoHazmatAndExpirationDtoList: type: object properties: tts_sku_id: type: string description: Identifier for Stock Keeping Unit (SKU) generated by TikTok Shop system is_hazmat: type: boolean description: |- Indicates whether the product is classified as hazardous material under FBT rules. - `true`: The product is classified as hazardous material. Provide the required hazmat declaration through `hazmat_info` when calling **Create FBT Goods** or **Update FBT Goods Info**. - `false`: The product is not classified as hazardous material. is_lot_code: type: boolean description: |- if the product requires lot management based on FBT category rule TRUE:this product requires lot control FALSE:this product does not require lot control is_expiration_management: type: boolean description: |- Indicates whether the product requires expiration management based on the FBT category rule. TRUE: this product requires expiration management. FALSE: this product does not require expiration management. exp_base_info: $ref: "#/components/schemas/SearchGoodsHazmatAndExpirationInfoResponseDataHazmatAndExpirationInfoHazmatAndExpirationDtoListExpBaseInfo" description: Expiration-management thresholds for the product associated with the SKU when `is_expiration_management` is `true`. SearchGoodsHazmatAndExpirationInfoResponseDataHazmatAndExpirationInfoHazmatAndExpirationDtoListExpBaseInfo: type: object properties: inbound_cutoff_days: type: integer format: int64 description: The period before a product's expiration date when the warehouse will stop accepting inbound shipments.For example, if the product expiration date is December 1, 2024, and the inbound cutoff days are 20 days, then the warehouse will stop accepting inbound shipments for this product after November 11, 2024 (20 days before expiration) expiration_alert_days: type: integer format: int64 description: The period of time before expiration in which the platform will send expiration alerts. sales_cutoff_days: type: integer format: int64 description: The period before a product's expiration date when the inventory will no longer be available for sale. For example, if the product expiration date is December 1, 2024, and the sales cutoff days are 20 days, then the inventory will stop being available for sale after November 11, 2024 (20 days before expiration). SearchGoodsInfoRequest: type: object properties: goods_ids: type: array items: type: string description: "Fulfilled by TikTok goods IDs used to filter the results. Each ID must be a positive decimal string. Maximum: 100 IDs per request." product_ids: type: array items: type: string description: "TikTok Shop product IDs used to filter the results. Each ID must be a positive decimal string. Maximum: 100 IDs per request." reference_codes: type: array items: type: string description: "Merchant-defined goods reference codes used to filter the results. Maximum: 100 codes per request." sku_ids: type: array items: type: string description: "TikTok Shop SKU IDs used to filter the results. Each ID must be a positive decimal string. Maximum: 100 IDs per request." SearchGoodsInfoResponse: 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/SearchGoodsInfoResponseData" SearchGoodsInfoResponseData: type: object properties: next_page_token: type: string description: An opaque token used to retrieve the next page. When this value is non-empty, pass it unchanged in the next request's `page_token`. An empty string means there are no more pages. total_count: type: integer format: int64 description: The total number of goods that meet the query conditions. goods: type: array items: $ref: "#/components/schemas/SearchGoodsInfoResponseDataGood" description: A list of detailed information for Fulfilled by TikTok goods. SearchGoodsInfoResponseDataGood: type: object properties: id: type: string description: The identifier for goods generated by Fulfilled by TikTok system. name: type: string description: The goods name. barcodes: type: array items: $ref: "#/components/schemas/SearchGoodsInfoResponseDataGoodBarcode" description: A list of detailed information for goods barcodes. reference_code: type: string description: The identifier for goods defined by merchant. image_url: type: string description: The goods image url. merchant_declaration_info: $ref: "#/components/schemas/SearchGoodsInfoResponseDataGoodMerchantDeclarationInfo" description: The dimension and weight info input by merchant. warehouse_confirmation_info: $ref: "#/components/schemas/SearchGoodsInfoResponseDataGoodWarehouseConfirmationInfo" description: Dimension and weight information verified by the warehouse during the goods' first inbound. Returned only when at least one warehouse-confirmed weight, length, width, or height value is available. If this object is omitted, no warehouse-confirmed measurement is available in this response. skus: type: array items: $ref: "#/components/schemas/SearchGoodsInfoResponseDataGoodSku" description: A list of Stock Keeping Units (SKUs) infomation matched with current FBT goods. lot_expiration_info: $ref: "#/components/schemas/SearchGoodsInfoResponseDataGoodLotExpirationInfo" description: The goods lot control and expiration managment information. is_hazmat: type: boolean description: whether is hazmat goods hazmat_info: $ref: "#/components/schemas/SearchGoodsInfoResponseDataGoodHazmatInfo" description: "Hazardous-material details. Returned only when `is_hazmat` is `true`. The subtype object depends on `hazmat_type`: `battery_extra_info` for `BATTERY`, `flammable_liquids_extra_info` for `FLAMMABLE_LIQUID`, and `aerosol_extra_info` for `AEROSOLS`. `MAGNETIZED` does not include a subtype object." sioc_approval_status: type: string enum: - SIOC_APPROVAL_STATUS_INVALID - SIOC_APPROVAL_STATUS_INIT - SIOC_APPROVAL_STATUS_UNDER_REVIEW - SIOC_APPROVAL_STATUS_APPROVE - SIOC_APPROVAL_STATUS_REJECT description: |- SIOC-specific approval status. This field is returned when `is_sioc` is `true` and an SIOC approval status is available. Possible values: - SIOC_APPROVAL_STATUS_INVALID - SIOC_APPROVAL_STATUS_INIT - SIOC_APPROVAL_STATUS_UNDER_REVIEW - SIOC_APPROVAL_STATUS_APPROVE - SIOC_APPROVAL_STATUS_REJECT hazmat_approval_status: type: string enum: - APPROVAL_STATUS_INVALID - APPROVAL_STATUS_INIT - APPROVAL_STATUS_UNDER_REVIEW - APPROVAL_STATUS_FULFILLABLE - APPROVAL_STATUS_UNFULFILLABLE description: |- FBT fulfillment approval status. This field is returned for goods that are hazardous materials or managed as Ships in Own Container (SIOC). Possible values: - APPROVAL_STATUS_INVALID - APPROVAL_STATUS_INIT - APPROVAL_STATUS_UNDER_REVIEW - APPROVAL_STATUS_FULFILLABLE - APPROVAL_STATUS_UNFULFILLABLE bulky_item_attribute: $ref: "#/components/schemas/SearchGoodsInfoResponseDataGoodBulkyItemAttribute" description: bulky item info goods_safety_attributes: $ref: "#/components/schemas/GoodsSafetyAttribute" description: safety attribute info is_sioc: type: boolean description: whether sioc sioc_attribute: $ref: "#/components/schemas/SiocAttribute" description: sioc info SearchGoodsInfoResponseDataGoodBarcode: type: object properties: code: type: string description: The printable barcode for the goods. type: type: string enum: - UPC - EAN - GTIN - ASIN_OR_FNSKU - MERCHANT_SKU_ID - FBT_SPECIFIC_BARCODE description: |- The barcode type. Possible values: - UPC - EAN - GTIN - ASIN_OR_FNSKU - MERCHANT_SKU_ID - FBT_SPECIFIC_BARCODE SearchGoodsInfoResponseDataGoodBulkyItemAttribute: type: object properties: is_bulky_item: type: boolean description: whether the goods is_bulky_item is_bulky_item_accessories: type: boolean description: whether the goods is bulky accessories SearchGoodsInfoResponseDataGoodHazmatInfo: type: object properties: hazmat_type: type: string enum: - MAGNETIZED - BATTERY - FLAMMABLE_LIQUID - AEROSOLS description: |- hazardous goods type Possible values: -MAGNETIZED -BATTERY -FLAMMABLE_LIQUID -AEROSOLS battery_extra_info: $ref: "#/components/schemas/SearchGoodsInfoResponseDataGoodHazmatInfoBatteryExtraInfo" description: Additional battery information for hazmat goods. flammable_liquids_extra_info: $ref: "#/components/schemas/SearchGoodsInfoResponseDataGoodHazmatInfoFlammableLiquidsExtraInfo" description: flammable liquids info aerosol_extra_info: $ref: "#/components/schemas/AerosolExtraInfo" description: aerosol info dg_class: type: string enum: - CLASS_2 - CLASS_3 - CLASS_9 description: |- Hazmat class Possible values: -CLASS_2 -CLASS_3 -CLASS_9 dg_uncode: type: string enum: - UN2807 - UN3480 - UN3090 - UN3481 - UN3091 - UN1263 - UN1266 - UN3065 - OTHER description: |- UN identifier for the hazardous substance. Standard UN values use the `UN` prefix followed by four digits; `OTHER` is also supported. Possible values: - UN2807 - UN3480 - UN3090 - UN3481 - UN3091 - UN1263 - UN1266 - UN3065 - OTHER msds_file_url: type: string description: Material safety data sheet of the hazmat goods to support review the goods' safety compliance in FBT SearchGoodsInfoResponseDataGoodHazmatInfoBatteryExtraInfo: type: object properties: battery_type: type: string description: |- Battery type Possible values: LITHIUM_ION LITHIUM_METAL OTHER battery_packaging_type: type: string enum: - STANDALONE - IN_EQUIPMENT - WITH_EQUIPMENT - OTHER description: |- Battery packaging type. Possible values: - STANDALONE - IN_EQUIPMENT - WITH_EQUIPMENT - 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. battery_count_per_package: type: string description: per package battery count 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 total_battery_capacity_unit: type: string description: Unit for `total_battery_capacity`, such as `WATT_HOURS`. SearchGoodsInfoResponseDataGoodHazmatInfoFlammableLiquidsExtraInfo: type: object properties: flammable_liquids_type: type: string enum: - PAINT - PERFUMERY - ALCOHOLIC - OTHER description: |- Flammable liquid type, possible values -PAINT -PERFUMERY -ALCOHOLIC -OTHER flammable_liquids_volume: type: string description: Volume of flammable liquid in the unit specified by volume_unit. volume_unit: type: string description: Unit for `flammable_liquids_volume`, such as `MILLILITER`. SearchGoodsInfoResponseDataGoodLotExpirationInfo: type: object properties: is_lot_control: type: boolean description: |- A flag indicating whether the goods is under lot control. True: Under lot control. False: Not under lot control. Note: Lot code and expiration date management information is mandatory for these [product categories](https://bytedance.us.larkoffice.com/sheets/OoT2sKH7jhykXCtHEseuzkGYsod) according to Fulfilled by TikTok guidelines. is_expiration_management: type: boolean description: |- A flag indicating whether the goods is under expiration managment. True: Under expiration managment. False: Not under expiration managment. shelf_life_days: type: integer format: int64 description: The goods shelf life days input by merchant, represent the total number of days the product remains usable or sellable from the time it is manufactured until its expiration. inbound_cutoff_days: type: integer format: int64 description: The goods inbound cutoff days before expiration, represent the time period before the product's expiration when the warehouse will no longer accept inbound shipments. expiration_alert_days: type: integer format: int64 description: The goods alert days before expired, represent the period of time before platform send expiration reminder alerts to the merchant. sales_cutoff_days: type: integer format: int64 description: The goods sales cut off days before expired, represent the period of time before expiration in which the goods will no longer be available for sale. handling_method: type: string enum: - STORE_UNITS - RETURN_TO_SELLER - DISPOSE x-enum-descriptions: - Move the units to defective inventory. - Return the units to the seller. - Dispose of the units. description: |- The handling method for expired inventory. Possible values: - `STORE_UNITS`: Move the units to defective inventory. - `RETURN_TO_SELLER`: Return the units to the seller. - `DISPOSE`: Dispose of the units. SearchGoodsInfoResponseDataGoodMerchantDeclarationInfo: type: object properties: weight: $ref: "#/components/schemas/SearchGoodsInfoResponseDataGoodMerchantDeclarationInfoWeight" description: The goods weight. dimension: $ref: "#/components/schemas/SearchGoodsInfoResponseDataGoodMerchantDeclarationInfoDimension" description: The goods dimension. SearchGoodsInfoResponseDataGoodMerchantDeclarationInfoDimension: type: object properties: width: type: string description: Width value, up to three decimal places. length: type: string description: Length value, up to three decimal places. height: type: string description: Height value, up to three decimal places. unit: type: string enum: - MILLIMETER - CENTIMETER - METER - FOOT - INCH - MICROMETER description: |- Dimension unit. Possible values: - MILLIMETER - CENTIMETER - METER - FOOT - INCH - MICROMETER SearchGoodsInfoResponseDataGoodMerchantDeclarationInfoWeight: type: object properties: value: type: string description: Weight value, up to three decimal places. unit: type: string enum: - MILLIGRAM - GRAM - KILOGRAM - POUND - OUNCE description: |- Weight unit. Possible values: - MILLIGRAM - GRAM - KILOGRAM - POUND - OUNCE SearchGoodsInfoResponseDataGoodSku: type: object properties: id: type: string description: The identifier for SKU generated by TikTok Shop system. name: type: string description: The SKU name. image_url: type: string description: The TikTok Shop SKU image url. product: $ref: "#/components/schemas/SearchGoodsInfoResponseDataGoodSkuProduct" description: The TikTok Shop product matched with current Fulfilled by TikTok goods. regions: type: array items: type: string description: The regions where the SKU is being sold, represented by region codes in the two-character ISO 3166-1 alpha-2 format. matched: type: boolean description: Indicates that the SKU is matched to the current Fulfilled by TikTok goods. Entries in `skus` are matched relations, so this value is always `true`. SearchGoodsInfoResponseDataGoodSkuProduct: type: object properties: id: type: string description: The identifier for product generated by TikTok Shop system. name: type: string description: The TikTok Shop product name. image_url: type: string description: The Tiktok Shop product image url. SearchGoodsInfoResponseDataGoodWarehouseConfirmationInfo: type: object properties: weight: $ref: "#/components/schemas/SearchGoodsInfoResponseDataGoodMerchantDeclarationInfoWeight" description: The goods weight. dimension: $ref: "#/components/schemas/SearchGoodsInfoResponseDataGoodWarehouseConfirmationInfoDimension" description: The goods dimension. SearchGoodsInfoResponseDataGoodWarehouseConfirmationInfoDimension: type: object properties: width: type: string description: Width value verified by warehouse, up to three decimal places. length: type: string description: Length value verified by warehouse, up to three decimal places. height: type: string description: Height value verified by warehouse, up to three decimal places. unit: type: string enum: - MILLIMETER - CENTIMETER - METER - FOOT - INCH - MICRO description: |- Dimension unit. Possible values: - MILLIMETER - CENTIMETER - METER - FOOT - INCH - MICRO SearchManufacturersRequest: type: object properties: manufacturer_ids: type: array items: type: string description: |- Filter results by these manufacturer IDs. Max IDs: The value of `page_size` keyword: type: string maxLength: 200 description: |- Filter results to show those that contain this keyword. Search scope: name, registered trade name, local_number, email Max length: 200 characters **Note**: Provide either the `manufacturer_ids` or `keyword`; if both are provided, `manufacturer_ids` will take priority. locales: type: array items: type: string enum: - de-DE - en-IE - es-ES - fr-FR - it-IT description: |- The BCP-47 locale codes for displaying the manufacturer information. Default: The locale of the seller's registered business address. Possible values: - de-DE - en-IE - es-ES - fr-FR - it-IT SearchManufacturersResponse: 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/SearchManufacturersResponseData" SearchManufacturersResponseData: type: object properties: manufacturers: type: array items: $ref: "#/components/schemas/SearchManufacturersResponseDataManufacturer" description: The list of manufacturers that meet the query conditions. total_count: type: integer format: int64 description: The number of manufacturers that meet the query conditions. next_page_token: type: string description: An opaque token used to retrieve the next page of a paginated result set. Provide this value in the `page_token` parameter of your request if the current response does not return all the results. SearchManufacturersResponseDataManufacturer: type: object properties: id: type: string description: The manufacturer ID in TikTok Shop. regional_profiles: type: array items: $ref: "#/components/schemas/SearchManufacturersResponseDataManufacturerRegionalProfile" description: A list of contact details for the manufacturer, presented in different languages for each supported EU country. SearchManufacturersResponseDataManufacturerRegionalProfile: type: object properties: locale: type: string enum: - de-DE - en-IE - es-ES - fr-FR - it-IT description: |- The BCP-47 locale code representing the language used for specifying the manufacturer information. Possible values: - de-DE - en-IE - es-ES - fr-FR - it-IT name: type: string maxLength: 255 description: |- The manufacturer name. Max length: 255 characters registered_trade_name: type: string maxLength: 200 description: |- The registered trade name of the manufacturer. Max length: 200 characters email: type: string description: The email address of the manufacturer. phone_number: $ref: "#/components/schemas/PhoneNumber" description: The phone number of the manufacturer. address: type: string maxLength: 500 description: |- The postal address of the manufacturer. Max length: 500 characters SearchOpenCollaborationProductsRequest: type: object properties: title_keywords: type: array items: type: string description: A list of product keywords for searching. Product titles, or names, are loosely matched. Keywords in the list form a query and the resulting set of matching product names is based on the conjunctive operator `AND` between each keyword. For example, the keyword list `["Men", "Fashion"]` creates a query `"Men" AND "Fashion"` and the resulting set of matching product names contains the loosely matched conjuction of "Men" and "Fashion" such as "Male Fashionable". Maximum length of the list is 20 keywords. Maximum keyword string length is 255 characters. sales_price_range: $ref: "#/components/schemas/SalesPriceRange" description: Restricts the products in the search results to those with prices greater than or equal to the expressed minimum price and less than the expressed maximum price. category: $ref: "#/components/schemas/Category" description: Restricts the products in the search results to those that are associated with the expressed product category. commission_rate_range: $ref: "#/components/schemas/SearchOpenCollaborationProductsRequestCommissionRateRange" description: The commission rate of the searched product needs to be limited within this range. SearchOpenCollaborationProductsRequestCommissionRateRange: type: object properties: rate_ge: type: integer format: int64 description: The minimum commission rate. Products with a commission rate greater than or equal to this value are included in the results. Express the rate in hundredths of a percent; for example, `3587` means `35.87%`. The value must be from `100` to `8000`, inclusive. rate_lt: type: integer format: int64 description: The commission rate must be less than this value in order to be included in the search results. The commission rate is expressed in hundredths of a percent. For example, `3587` is a commission rate of `35.87%`. This value must a minimum of `1000`. SearchOpenCollaborationProductsResponse: 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/SearchOpenCollaborationProductsResponseData" SearchOpenCollaborationProductsResponseData: type: object properties: products: type: array items: $ref: "#/components/schemas/SearchOpenCollaborationProductsResponseDataProduct" description: A list of products. next_page_token: type: string description: An opaque token used to retrieve the next page of a paginated result set. total_count: type: integer format: int64 description: Total count of products meeting the search criteria expressed in the request body. SearchOpenCollaborationProductsResponseDataProduct: type: object properties: shop: $ref: "#/components/schemas/Shop" description: Data and metadata associated with the Seller's TikTok Shop. id: type: string description: The product identifier. has_inventory: type: boolean description: Set to `true` if there are more than zero units of the product in inventory. Set to `false` if there are zero units in inventory. units_sold: type: integer format: int64 description: Total number of units sold. Units are indexed to SKU. Note that if the creator has not given permission for precise data sharing, this property will not be present. title: type: string description: The product name. sale_region: type: string description: The region where the product is offered for sale. main_image_url: type: string description: The product image URL. detail_link: type: string description: The URL for the product's detail page. original_price: $ref: "#/components/schemas/OriginalPrice" description: The original price of the product. category_chains: type: array items: $ref: "#/components/schemas/CategoryChain" description: A list of categories associated with the product. Maximum length of the list is `3` categories. commission: $ref: "#/components/schemas/Commission" description: Metadata and data associated with the commission rates for the product. sales_price: $ref: "#/components/schemas/SalesPrice" description: Metadata and data associated with the sale price of the product SearchOpenCollaborationsRequest: type: object properties: keyword_type: type: string enum: - PRODUCT_ID - PRODUCT_NAME x-enum-descriptions: - Search for open collaboration information for the specified product ID. - Fuzzy-search open collaboration information by related product names. description: |- Specifies the type of value in `keyword`. To filter open collaborations by product name or product ID, provide `keyword_type` and `keyword` together. Possible values: - `PRODUCT_ID`: Search for open collaboration information for the specified product ID. - `PRODUCT_NAME`: Fuzzy-search open collaboration information by related product names. keyword: type: string description: Search based on the product name or product ID. Pass in the appropriate value based on the keyword_type above. top_level_category_id: type: string description: |- Filter products by a first-level category ID. The value of `top_level_category_id` must be greater than 0. SearchOpenCollaborationsResponse: 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/SearchOpenCollaborationsResponseData" SearchOpenCollaborationsResponseData: type: object properties: next_page_token: type: string description: Pagination token for the next page. Pass this value as `page_token` in the next request. An empty value indicates that there are no more results. total_count: type: integer format: int64 description: Total count of products that satisfy all the input search conditions. open_collaborations: type: array items: $ref: "#/components/schemas/SearchOpenCollaborationsResponseDataOpenCollaboration" description: Open collaborations matching the search criteria on the current page. SearchOpenCollaborationsResponseDataOpenCollaboration: type: object properties: id: type: string description: The open collaboration id status: type: string description: |- Status of open collaboration. Field values: - NORMAL：NORMAL means the current open collaboration status is normal and in effect. - TERMINATING: TERMINATING means that the merchant has removed open collaboration and the open collaboration will expire soon. The expiration time can be found at the end_time of current_commission. The open collaborations which were removed and expired will not be returned in the response. current_commission: $ref: "#/components/schemas/SearchOpenCollaborationsResponseDataOpenCollaborationCurrentCommission" description: The commission information is currently in effect for this open collaboration. showcase_creator_count: type: integer format: int64 description: This field indicates the number of creators who added the product to the showcase from open collaboration. content_creator_count: type: integer format: int64 description: This field indicates the number of creators who posted the LIve or Video from open collaboration. product: $ref: "#/components/schemas/SearchOpenCollaborationsResponseDataOpenCollaborationProduct" description: The open collaboration bound product information. SearchOpenCollaborationsResponseDataOpenCollaborationCurrentCommission: type: object properties: rate: type: integer format: int64 description: |- The commission rate for this product is set by merchants for creators' public promotion. The range of this value is [100, 8000]. This value is expressed in 1/10000 increments. For example: 3000 means the actual commission rate is 30.00%, and 3555 means 35.55% start_time: type: integer format: int64 description: The Unix timestamp, in seconds, when the commission rate becomes effective. end_time: type: integer format: int64 description: The Unix timestamp, in seconds, when the commission rate stops being effective. SearchOpenCollaborationsResponseDataOpenCollaborationProduct: type: object properties: id: type: string description: Product's unique id. title: type: string description: Product's name. main_image_url: type: string description: The product image url. status: type: string description: |- Product's status. Field values: - LIVE: When the product is normal for sale, return to the LIVE status - OUT_OF_STOCK: When the product is out of stock for the consumer, the OUT_OF_STOCK state is returned - SELLER_DEACTIVATE: When the product is deactivated by the merchant, the SELLER_DEACTIVATE status is returned - PLATFORM_DEACTIVATE: When the product is deactivated by the platform or is not available for sale, the PLATFORM_DEACTIVATE status is returned - GNE_REJECT: When the product is governed or the open collaboration is dismissed, the GNE_REJECT state is returned - DELETE: When the product is deleted, the DELETE status is returned - OTHER: When the product is in an unsaleable state, such as draft, frozen, review, etc, the OTHER status is returned inventory: type: integer format: int64 description: The inventory of this product. original_price: $ref: "#/components/schemas/OriginalPrice" description: The product's original price SearchOrdersByExternalOrderReferenceRequest: type: object properties: {} SearchOrdersByExternalOrderReferenceResponse: 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/SearchOrdersByExternalOrderReferenceResponseData" SearchOrdersByExternalOrderReferenceResponseData: type: object properties: orders: type: array items: $ref: "#/components/schemas/SearchOrdersByExternalOrderReferenceResponseDataOrder" description: A list of TikTok Shop orders that match the specified external order ID and OMS platform. This field may be omitted when no orders match. SearchOrdersByExternalOrderReferenceResponseDataOrder: type: object properties: id: type: string description: The unique identifier for a TikTok Shop order. external_order: $ref: "#/components/schemas/ExternalOrder" description: Order in your OMS. SearchPODCustomizationDetailsRequest: type: object properties: main_order_id: type: string description: TikTok Shop order ID. query_order_lines: type: array items: $ref: "#/components/schemas/QueryOrderLine" description: The order lines for which to retrieve POD customization details. required: - main_order_id - query_order_lines SearchPODCustomizationDetailsResponse: 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/SearchPODCustomizationDetailsResponseData" SearchPODCustomizationDetailsResponseData: type: object properties: pod_details: type: array items: $ref: "#/components/schemas/SearchPODCustomizationDetailsResponseDataPodDetail" description: POD customization details for the requested order lines. status_code: type: integer format: int64 description: The status code for the POD customization details query. SearchPODCustomizationDetailsResponseDataPodDetail: type: object properties: order_line_id: type: string description: The unique identifier of the order line associated with the POD customization details. pod_detail: type: string description: The unique identifier of the order line item. SearchPackageRequest: type: object properties: create_time_ge: type: integer format: int64 description: Filter packages to those created at or after the specified time. Unix timestamp, in seconds. create_time_lt: type: integer format: int64 description: Filter packages to those created before the specified time. Unix timestamp, in seconds. update_time_ge: type: integer format: int64 description: Filter packages to those updated at or after the specified time. Unix timestamp, in seconds. update_time_lt: type: integer format: int64 description: Filter packages to those updated before the specified time. Unix timestamp, in seconds. package_status: type: string enum: - TO_FULFILL - PROCESSING - FULFILLING - COMPLETED - CANCELLED x-enum-descriptions: - "" - Package has been arranged by seller. Waiting for carrier to collect the parcel. - Package has been collected by carrier and in transit. - Package has been delivered. - Package has been canceled. Normally, the package is canceled due to the package being lost or damaged. description: |- Possible values: - `TO_FULFILL` - `PROCESSING`: Package has been arranged by seller. Waiting for carrier to collect the parcel. - `FULFILLING`: Package has been collected by carrier and in transit. - `COMPLETED`: Package has been delivered. - `CANCELLED`: Package has been canceled. Normally, the package is canceled due to the package being lost or damaged. SearchPackageResponse: 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/SearchPackageResponseData" SearchPackageResponseData: type: object properties: next_page_token: type: string description: An opaque token used to retrieve the next page of a paginated result set. If this value is non-empty, provide it in the `page_token` parameter of the next request. If this value is empty, stop pagination. total_count: type: integer format: int64 description: The number of packages that meet the query conditions. packages: type: array items: $ref: "#/components/schemas/SearchPackageResponseDataPackage" description: The response list of packages. SearchPackageResponseDataPackage: type: object properties: id: type: string description: Package ID. orders: type: array items: $ref: "#/components/schemas/Order" description: The response list of TikTok Shop orders. create_time: type: integer format: int64 description: Package creation time. Unix timestamp, in seconds. update_time: type: integer format: int64 description: The time when the package was last updated. Unix timestamp, in seconds. status: type: string enum: - TO_FULFILL - PROCESSING - FULFILLING - COMPLETED - CANCELLED x-enum-descriptions: - "" - Package has been arranged by seller. Waiting for carrier to collect the parcel. - Package has been collected by carrier and in transit. - Package has been delivered. - Package has been canceled. Normally, the package is canceled due to the package being lost or damaged. description: |- Possible values: - `TO_FULFILL` - `PROCESSING`: Package has been arranged by seller. Waiting for carrier to collect the parcel. - `FULFILLING`: Package has been collected by carrier and in transit. - `COMPLETED`: Package has been delivered. - `CANCELLED`: Package has been canceled. Normally, the package is canceled due to the package being lost or damaged. tracking_number: type: string description: Package tracking number. shipping_provider_name: type: string description: Package shipping provider. shipping_provider_id: type: string description: Package shipping provider ID. order_line_item_ids: type: array items: type: string description: The order line item ID contained in the package. SearchProductsForComplianceAuditingRequest: type: object properties: product_title: type: string description: |- The product title. Title length: - DE, ES, FR, IE, IT, JP, UK, US: [1, 255] - BR, MX: [1, 300] - Other regions: [25, 255] product_ids: type: array items: type: string description: The product ID generated by TikTok Shop. Max is 20 seller_id: type: string description: The Shop identity ID. category_ids: type: array items: type: string description: Filter shop-search results by TikTok Shop category IDs. brand_ids: type: array items: type: string description: Filter shop-search results by TikTok Shop brand IDs. seller_name: type: string description: The name of the shop which product belongs to. SearchProductsForComplianceAuditingResponse: 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/SearchProductsForComplianceAuditingResponseData" SearchProductsForComplianceAuditingResponseData: type: object properties: next_page_token: type: string description: The opaque token returned for a subsequent page. When this value is non-empty, pass it in the next request's `page_token`. total_count: type: integer format: int64 description: The total number of products selected by the active mode. For direct product-ID lookup, this is the number of product IDs used for the lookup. For shop search, this is the total number of products matching the seller, product-title, category, and brand filters. products: type: array items: $ref: "#/components/schemas/SearchProductsForComplianceAuditingResponseDataProduct" description: Product information SearchProductsForComplianceAuditingResponseDataProduct: type: object properties: id: type: string description: The product ID generated by TikTok Shop. title: type: string description: |- The product title. Title length: - DE, ES, FR, IE, IT, JP, UK, US: [1, 255] - BR, MX: [1, 300] - Other regions: [25, 255] country: type: string enum: - BR - DE - ES - FR - GB - ID - IE - IT - JP - MX - MY - PH - SG - TH - US - VN x-enum-descriptions: - Brazil - Germany - Spain - France - United Kingdom - Indonesia - Ireland - Italy - Japan - Mexico - Malaysia - Philippines - Singapore - Thailand - United States - Vietnam description: |- The regions where the product is sold. Possible values: - BR: Brazil - DE: Germany - ES: Spain - FR: France - GB: United Kingdom - ID: Indonesia - IE: Ireland - IT: Italy - JP: Japan - MX: Mexico - MY: Malaysia - PH: Philippines - SG: Singapore - TH: Thailand - US: United States - VN: Vietnam description: type: string description: The product description in HTML format. variants: type: array items: $ref: "#/components/schemas/SearchProductsForComplianceAuditingResponseDataProductVariant" description: A list of Stock Keeping Units (SKUs) used to identify distinct variants of the product. listing_url: type: string description: The product detail page URL of the product. seller_name: type: string description: The name of the shop which product belongs to. seller_id: type: string description: The Shop identity ID. main_image_urls: type: array items: type: string description: The URLs to view the images. brand_id: type: string description: The ID of the brand of this product. brand_name: type: string description: The brand name. categories: type: array items: $ref: "#/components/schemas/SearchProductsForComplianceAuditingResponseDataProductCategory" description: The category hierarchy of the product. SearchProductsForComplianceAuditingResponseDataProductCategory: type: object properties: id: type: string description: The ID of the category of this product. name: type: string description: The name of the category in the country where the shop operates. level: type: integer format: int64 description: The level of the category in the country where the shop operates. parent_id: type: string description: |- The parent category ID. For the root category, the parent ID is 0 is_leaf: type: boolean description: |- A flag to indicate if the category is a leaf category. Note: You can only create or edit products that belong to a leaf category. SearchProductsForComplianceAuditingResponseDataProductVariant: type: object properties: id: type: string description: The SKU ID generated by TikTok Shop. SearchProductsRequest: type: object properties: status: type: string enum: - ALL - DRAFT - PENDING - FAILED - ACTIVATE - SELLER_DEACTIVATED - PLATFORM_DEACTIVATED - FREEZE - DELETED description: |- Filter products based on the product's base version. In other words, this filter does not apply to post-live drafts or edits. For example, `status=DRAFT` returns only unpublished products in the DRAFT state, not live products with an active draft. Possible values: - ALL - DRAFT - PENDING - FAILED - ACTIVATE - SELLER_DEACTIVATED - PLATFORM_DEACTIVATED - FREEZE - DELETED Default: ALL seller_skus: type: array items: type: string description: Filter products by these seller SKU codes. create_time_ge: type: integer format: int64 description: |- Filter products to show only those that are created on or after the specified date and time. Unix timestamp in seconds. **Note**: `create_time_ge` and `create_time_le` together constitute the creation time filter condition. - If `create_time_ge` is filled but `create_time_le` is empty, `create_time_le` will default to the current time. - If `create_time_le` is filled but `create_time_ge` is empty, `create_time_ge` will default to the earliest shop time. create_time_le: type: integer format: int64 description: |- Filter products to show only those that are created on or before the specified date and time. Unix timestamp in seconds. Refer to notes in `create_time_ge` for more usage information. update_time_ge: type: integer format: int64 description: |- Filter products to show only those that are updated on or after the specified date and time. Unix timestamp in seconds. **Note**: `update_time_ge` and `update_time_le` together define the update time filter condition. - If `update_time_ge` is filled but `update_time_le` is empty, `update_time_le` will default to the current time. - If `update_time_le` is filled but `update_time_ge` is empty, `update_time_ge` will default to the earliest shop time. update_time_le: type: integer format: int64 description: |- Filter products to show only those that are updated on or before the specified date and time. Unix timestamp in seconds. Refer to notes in `update_time_ge` for more usage information. category_version: type: string enum: - v2 - v1 x-enum-descriptions: - "US: represents the 7-level category tree." - "Other regions: represents the 3-level category tree." description: |- Filter products by the category tree version. Possible values based on region: - US: `v2`, represents the 7-level category tree. - Other regions: `v1`, represents the 3-level category tree. Default: Return all products from both `v1` and `v2` category trees. listing_quality_tiers: type: array items: type: string enum: - POOR - FAIR - GOOD - EXCELLENT description: |- Filter products by their listing quality tier. Possible values: - POOR - FAIR - GOOD - EXCELLENT Default: Returns all **Note**: Available only for the US market. listing_platforms: type: array items: type: string enum: - TOKOPEDIA - TIKTOK_SHOP description: |- Filter products by the listing platforms. Possible values: - TOKOPEDIA - TIKTOK_SHOP Default: Return all products regardless of their listing platform. Applicable only for sellers that migrated from Tokopedia. **Note**: - You must also specify a `status` value other than `ALL` when filtering by listing platforms. Returning all statuses is not supported. - If you pass in one platform, the search will return products that are listed on that platform, including those that are listed on both platforms. - If you pass in `["TIKTOK_SHOP", "TOKOPEDIA"]`, only products listed on both platforms will be returned, not those listed on just one. audit_status: type: array items: type: string enum: - AUDITING - FAILED - APPROVED x-enum-descriptions: - Returns products where the base version or a post-live edit is currently being audited. - Returns products where the base version or a post-live edit has failed audit, or had the audit cancelled. - Returns products that passed the audit and has been listed on the platform. description: |- Filter products by their audit status for TikTok Shop. Possible values: - AUDITING: Returns products where the base version or a post-live edit is currently being audited. - FAILED: Returns products where the base version or a post-live edit has failed audit, or had the audit cancelled. - APPROVED: Returns products that passed the audit and has been listed on the platform. sku_ids: type: array items: type: string maxItems: 10 description: |- Filter products by SKU IDs. Max count: 10 sns_filter: type: string enum: - CONFIGURED - ELIGIBLE description: |- Filter products by their Subscribe and Save (SNS) status. Possible values: - CONFIGURED - ELIGIBLE return_draft_version: type: boolean description: |- Filter products to show only those that have a draft. - true: Returns products in their draft version only. Excludes those without a draft. - false: Returns all products regardless of whether they have a draft. Default: false **Note**: Applicable only if the product status filter is `ALL`, `DRAFT`, `ACTIVATE`, `SELLER_DEACTIVATED`, or `PLATFORM_DEACTIVATED`. locale: 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 description: |- The BCP-47 locale codes for displaying category information. Default: The default locale of your shop. Possible values: - 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 include_live_quick_products: type: boolean description: |- Whether to include LIVE_QUICK products in the query results. true — Returns LIVE_QUICK products and normal product. false —only return normal product. Default: false SearchProductsResponse: 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/SearchProductsResponseData" SearchProductsResponseData: type: object properties: total_count: type: integer format: int64 description: The total number of products that meet the query conditions. products: type: array items: $ref: "#/components/schemas/SearchProductsResponseDataProduct" description: The list of products that meet the query conditions. next_page_token: type: string description: An opaque token used to retrieve the next page of a paginated result set. Provide this value in the `page_token` parameter of your request if the current response does not return all the results. SearchProductsResponseDataProduct: type: object properties: id: type: string description: The product ID generated by TikTok Shop. title: type: string description: The product title. status: type: string enum: - UNKNOWN - DRAFT - PENDING - FAILED - ACTIVATE - SELLER_DEACTIVATED - PLATFORM_DEACTIVATED - FREEZE - DELETED description: |- The product status in TikTok Shop. Possible values: - UNKNOWN - DRAFT - PENDING - FAILED - ACTIVATE - SELLER_DEACTIVATED - PLATFORM_DEACTIVATED - FREEZE - DELETED **Note**: For Indonesia sellers, if you did not set the listing platform as `TIKTOK_SHOP` when creating or editing a product, this will be omitted. skus: type: array items: $ref: "#/components/schemas/SearchProductsResponseDataProductSku" description: A list of Stock Keeping Units (SKUs) used to identify distinct variants of the product. sales_regions: type: array items: type: string enum: - BR - DE - ES - FR - GB - ID - IE - IT - JP - MX - MY - PH - SG - TH - US - VN x-enum-descriptions: - Brazil - Germany - Spain - France - United Kingdom - Indonesia - Ireland - Italy - Japan - Mexico - Malaysia - Philippines - Singapore - Thailand - United States - Vietnam description: |- The regions where the product is sold. Possible values: - BR: Brazil - DE: Germany - ES: Spain - FR: France - GB: United Kingdom - ID: Indonesia - IE: Ireland - IT: Italy - JP: Japan - MX: Mexico - MY: Malaysia - PH: Philippines - SG: Singapore - TH: Thailand - US: United States - VN: Vietnam create_time: type: integer format: int64 description: |- The time when the product is created. Unix timestamp in seconds. update_time: type: integer format: int64 description: |- The time when the product is last updated. Unix timestamp in seconds. product_sync_fail_reasons: type: array items: type: string description: |- The reasons why synchronizing of global product information to local products failed. Only applicable for cross-border sellers. is_not_for_sale: type: boolean description: |- A flag indicating whether the product is not for sale. True: Not for sale. False: For sale. recommended_categories: type: array items: $ref: "#/components/schemas/RecommendedCategory" description: Recommended categories for the product based on the product title, description, and images. listing_quality_tier: type: string enum: - POOR - FAIR - GOOD - EXCELLENT description: |- The current quality tier of this product listing. The quality tier of a product listing depends on the quality of the content in its product fields such as the title, image, attributes etc. Possible values: - POOR - FAIR - GOOD - EXCELLENT **Note**: Available only for the US market. integrated_platform_statuses: type: array items: $ref: "#/components/schemas/SearchProductsResponseDataProductIntegratedPlatformStatus" description: |- The current status of the product on platforms that are natively integrated with TikTok Shop (e.g. TOKOPEDIA). **Note**: For Indonesia sellers, if you did not set the listing platform as `TOKOPEDIA` when creating or editing a product, this will be omitted. audit: $ref: "#/components/schemas/SearchProductsResponseDataProductAudit" description: Product audit information for TikTok Shop. product_families: type: array items: $ref: "#/components/schemas/ProductFamily" description: |- The **live** product family that this product belongs to. A product family is a virtual group of products that share common characteristics (such as flavor, version, or size), allowing them to appear as selectable variations on the product page. **Note**: - Applicable only for US local sellers. - Omitted if this product does not belong to any product family. has_draft: type: boolean description: |- A flag to indicate if the product has a draft. - true: It has a draft. - false: It does not have a draft. Use Get Product with `return_draft_version=true` to obtain full details of the draft. scheduled_sale: $ref: "#/components/schemas/GetProductResponseDataScheduledSale" description: Scheduled listing configuration for the product, including whether scheduled listing is enabled and the scheduled listing time. product_tags: type: array items: type: string enum: - AUCTION - LIVE_QUICK description: |- Product tag to identity special type product Possible values: AUCTION、LIVE_QUICK selling_format: type: string enum: - FIXED_PRICE - LIVE_AUCTION - FIXED_PRICE_AND_LIVE_AUCTION description: "The product's sale format. Possible values: FIXED_PRICE, LIVE_AUCTION, FIXED_PRICE_AND_LIVE_AUCTION." SearchProductsResponseDataProductAudit: type: object properties: status: type: string enum: - NONE - AUDITING - FAILED - PRE_APPROVED - APPROVED x-enum-descriptions: - The product is not applicable for audit as it is still in a draft, frozen, or deactivated state. - The product is currently being audited. - The product failed the audit, or the audit was cancelled. - The product has passed the audit but is not yet listed due to pending prerequisites. - The product passed the audit and has been listed on the platform. description: |- The product audit status. Possible values: - NONE: The product is not applicable for audit as it is still in a draft, frozen, or deactivated state. - AUDITING: The product is currently being audited. - FAILED: The product failed the audit, or the audit was cancelled. - PRE_APPROVED: The product has passed the audit but is not yet listed due to pending prerequisites. - APPROVED: The product passed the audit and has been listed on the platform. pre_approved_reasons: type: array items: type: string enum: - KYC_PENDING - RESTRICTED_CATEGORY_PENDING x-enum-descriptions: - The seller's onboarding (KYC - Know Your Customer information) is incomplete or awaiting processing. - The product is in a restricted category, and category approval is still pending. To request access, submit an application through the Qualification Center on TikTok Shop Seller Center. Applicable only for the US market. description: |- The reason why the product is pre-approved. Applicable only if `audit.status=PRE_APPROVED`, otherwise returns an empty array. Possible values: - KYC_PENDING: The seller's onboarding (KYC - Know Your Customer information) is incomplete or awaiting processing. - RESTRICTED_CATEGORY_PENDING: The product is in a restricted category, and category approval is still pending. To request access, submit an application through the Qualification Center on TikTok Shop Seller Center. Applicable only for the US market. SearchProductsResponseDataProductIntegratedPlatformStatus: type: object properties: platform: type: string enum: - TOKOPEDIA description: |- The integrated platform name. Possible values: - TOKOPEDIA status: type: string enum: - DRAFT - PENDING - FAILED - ACTIVATE - SELLER_DEACTIVATED - PLATFORM_DEACTIVATED - FREEZE - DELETED description: |- The product status in the integrated platform. Possible values: - DRAFT - PENDING - FAILED - ACTIVATE - SELLER_DEACTIVATED - PLATFORM_DEACTIVATED - FREEZE - DELETED SearchProductsResponseDataProductSku: type: object properties: id: type: string description: The SKU ID generated by TikTok Shop. seller_sku: type: string description: An internal code/name for managing SKUs, not visible to buyers. price: $ref: "#/components/schemas/SearchProductsResponseDataProductSkuPrice" description: SKU pricing information. inventory: type: array items: $ref: "#/components/schemas/SearchProductsResponseDataProductSkuInventory" description: |- SKU inventory information. **Note**: This field is not supported in post-live drafts, therefore the values here will always reflect those in the base version, even if you set `return_draft_version=true`. list_price: $ref: "#/components/schemas/GetProductResponseDataSkuListPrice" description: |- The SKU's list price information that has been verified to be legitimate by the audit team. This is equivalent to the manufacturer's suggested retail price (MSRP), or the recommended retail price (RRP). Applicable only for the US market. **Note**: - This field will be empty or display the last verified price if the submitted price fails verification. - This value may appear as the strikethrough price on the product page. However, whether the strikethrough price is shown and the amount shown are subject to the audit team's review and decision based on various pricing information. external_list_prices: type: array items: $ref: "#/components/schemas/SearchProductsResponseDataProductSkuExternalListPrice" description: |- The SKU list price (e.g. MSRP, RRP) or original price information on external ecommerce platforms. Applicable only for selected sellers in the US market. **Note**: This value may appear as the strikethrough price on the product page. However, whether the strikethrough price is shown and the amount shown are subject to the audit team's review and decision based on various pricing information. pre_sale: $ref: "#/components/schemas/PreSale" description: |- SKU presale information, used to tag a product as a presale product based on its presale type. If this is not returned, it indicates that the product is a regular non-presale item. status_info: $ref: "#/components/schemas/SearchProductsResponseDataProductSkuStatusInfo" description: Status information of the SKU. fees: type: array items: $ref: "#/components/schemas/Fee" description: The fees required for this product based on TikTok Shop policies. Fees are required only for certain product categories, retrieve the requirements from the [Get Category Rules API](https://partner.tiktokshop.com/docv2/page/6509c0febace3e02b74594a9). SearchProductsResponseDataProductSkuExternalListPrice: type: object properties: source: type: string enum: - SHOPIFY_COMPARE_AT_PRICE x-enum-descriptions: - The compare_at_price in Shopify. description: |- The external ecommerce platform from which the price is sourced. Possible values: - SHOPIFY_COMPARE_AT_PRICE: The compare_at_price in Shopify. amount: type: string description: The price amount. currency: type: string enum: - USD description: |- The currency. Possible values: USD SearchProductsResponseDataProductSkuInventory: type: object properties: warehouse_id: type: string description: |- The ID of the warehouse where the SKU is stored. Retrieve details of the warehouse from the [Get Warehouse List API](https://partner.tiktokshop.com/docv2/page/650aa418defece02be6e66b6). quantity: type: integer format: int64 minimum: 1 maximum: 99999 description: |- The total SKU quantity available in the warehouse. Valid range: [1, 99,999] Note: This quantity specifically refers to the in-stock inventory that can be shipped immediately. backorder_quantity: type: integer format: int64 description: |- The `backorder_quantity` will automatically be converted to `quantity` once in-stock inventory is sold out. The fulfillment of this inventory follows the `handling_time` specified below. Note: Made-to-order (MTO), pre-order, and custom products cannot be backordered, and thus are incompatible with backorder_quantity. handling_time: type: integer format: int64 description: The estimated number of working days needed for a backorder to be shipped. Currently, different warehouses for the same SKU are not allowed to have different `handling_time` SearchProductsResponseDataProductSkuPrice: type: object properties: currency: type: string enum: - BRL - EUR - GBP - IDR - JPY - MXN - MYR - PHP - SGD - THB - USD - VND x-enum-descriptions: - Brazil - France, Germany, Ireland, Italy, Spain - United Kingdom - Indonesia - Japan - Mexico - Malaysia - Philippines - Singapore - Thailand - United States - Vietnam description: |- The currency. Possible values: - BRL: Brazil - EUR: France, Germany, Ireland, Italy, Spain - GBP: United Kingdom - IDR: Indonesia - JPY: Japan - MXN: Mexico - MYR: Malaysia - PHP: Philippines - SGD: Singapore - THB: Thailand - USD: United States - VND: Vietnam tax_exclusive_price: type: string description: |- **Local sellers/Intra-EU sellers** The SKU's **local display price** shown on the product page before any discounts. **Global sellers** The SKU's **local pre-tax price**. This excludes any applicable charges such as cross-border shipping costs, taxes, and other fees, and therefore does not appear on the product page. **Note**: Tax-exclusive pricing does not apply to the JP market, therefore this value is the same as `sale_price`. sale_price: type: string description: |- **Global sellers** The SKU's **local display price** shown on the product page before any discounts. starting_bid_price: type: string description: starting bid price for auction product SearchProductsResponseDataProductSkuStatusInfo: type: object properties: status: type: string enum: - NORMAL - DEACTIVATED description: |- The SKU status in TikTok Shop. Possible values: - NORMAL - DEACTIVATED deactivation_source: type: string enum: - SELLER - PLATFORM - COMBO_RELATION x-enum-descriptions: - Indicates that the seller deactivated the SKU - Indicates that the platform de-activated the SKU due to violation reasons - Indicates that the platform de-activated the combined-SKU due to the deactivation of sub-SKU. description: |- The deactivation source of the SKU with `DEACTIVATED` status. Possible values: - SELLER: Indicates that the seller deactivated the SKU - PLATFORM: Indicates that the platform de-activated the SKU due to violation reasons - COMBO_RELATION: Indicates that the platform de-activated the combined-SKU due to the deactivation of sub-SKU. SearchPromotionActivitiesRequest: type: object properties: status: type: string enum: - NOT_START - ONGOING - EXPIRED - DEACTIVATED x-enum-descriptions: - The activity is not available to TikTok users until its start time. - The activity is available to TikTok users. - The activity is no longer available because it has expired. - The activity was deactivated by the seller and is not available to TikTok users. description: |- Filter activities by status. If omitted, activities with `NOT_START`, `ONGOING`, `EXPIRED`, or `DEACTIVATED` status are returned. Possible values: - `NOT_START`: The activity is not available to TikTok users until its start time. - `ONGOING`: The activity is available to TikTok users. - `EXPIRED`: The activity is no longer available because it has expired. - `DEACTIVATED`: The activity was deactivated by the seller and is not available to TikTok users. activity_title: type: string description: Activity title key words. No fuzzy matching. page_size: type: integer format: int64 description: "Number of activities to return per page. Range: 0 to 100. If omitted or set to 0, the effective page size is 10." page_token: type: string description: Specify the value for the page. Use `""` for the first page. activity_type: type: string enum: - FIXED_PRICE - DIRECT_DISCOUNT - FLASHSALE - SHIPPING_DISCOUNT - BUY_MORE_SAVE_MORE - GIFT_WITH_PURCHASE - BUY_X_GET_Y x-enum-descriptions: - Product discount activity with a fixed price. - Product discount activity with a percentage off. - Flash sale activity. - Shipping fee discount activity. - Buy More Save More activity. - Gift With Purchase activity. - Buy X Get Y activity. description: |- The type of promotion activity to return. If `activity_type` is omitted, activities of all supported types are returned. Possible values: - `FIXED_PRICE`: Product discount activity with a fixed price. - `DIRECT_DISCOUNT`: Product discount activity with a percentage off. - `FLASHSALE`: Flash sale activity. - `SHIPPING_DISCOUNT`: Shipping fee discount activity. - `BUY_MORE_SAVE_MORE`: Buy More Save More activity. - `GIFT_WITH_PURCHASE`: Gift With Purchase activity. - `BUY_X_GET_Y`: Buy X Get Y activity. SearchPromotionActivitiesResponse: 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/SearchPromotionActivitiesResponseData" SearchPromotionActivitiesResponseData: type: object properties: total_count: type: integer format: int64 description: Total number of activities matching the supplied filters. This value can be greater than the number of entries in activities. next_page_token: type: string description: Page cursor for the next request. Pass a non-empty returned token as `page_token` to retrieve the next page. Stop when `next_page_token` is omitted or empty. activities: type: array items: $ref: "#/components/schemas/SearchPromotionActivitiesResponseDataActivity" description: Activities list information. SearchPromotionActivitiesResponseDataActivity: type: object properties: id: type: string description: A unique ID that identifies different activities. title: type: string description: Activity name (50 characters max). activity_type: type: string enum: - FIXED_PRICE - DIRECT_DISCOUNT - FLASHSALE - SHIPPING_DISCOUNT - BUY_MORE_SAVE_MORE - GIFT_WITH_PURCHASE - BUY_X_GET_Y x-enum-descriptions: - Product discount activity with a fixed price. - Product discount activity with a percentage off. - Flash sale activity. - Shipping fee discount activity. - Buy More Save More activity. - Gift With Purchase activity. - Buy X Get Y activity. description: |- The type of promotion activity. Possible values: - `FIXED_PRICE`: Product discount activity with a fixed price. - `DIRECT_DISCOUNT`: Product discount activity with a percentage off. - `FLASHSALE`: Flash sale activity. - `SHIPPING_DISCOUNT`: Shipping fee discount activity. - `BUY_MORE_SAVE_MORE`: Buy More Save More activity. - `GIFT_WITH_PURCHASE`: Gift With Purchase activity. - `BUY_X_GET_Y`: Buy X Get Y activity. duration_type: type: string description: |- The effective time type of the current activity - NORMAL: `begin_time` and `end_time` must be filled - INDEFINITE: `begin_time` and `end_time` aren't required, and the promotion will be a long-term activity which runs indefinitely. 1. `INDEFINITE` is only valid when `activity_type` is `SHIPPING_DISCOUNT`, 2. If `duration_type` is `INDEFINITE`, `start_time` and `end_time` should be 0 Default: NORMAL begin_time: type: integer format: int64 description: Activity start time, as a Unix timestamp in seconds. end_time: type: integer format: int64 description: Activity end time, as a Unix timestamp in seconds. status: type: string enum: - DRAFT - NOT_START - ONGOING - EXPIRED - DEACTIVATED - NOT_EFFECTIVE x-enum-descriptions: - Promotion activities with this status are not available to TikTok users. - Promotion activities with this status are not available to TikTok users until the set activity start time. - Promotion activities with this status are available to TikTok users. - Promotion activities with this status are not available to TikTok users because it has expired. - The activity has been deactivated by the seller and is not available to TikTok users. - The activity is terminated by the platform and is not available to TikTok users. description: |- Activity status. Possible values: - DRAFT: Promotion activities with this status are not available to TikTok users. - NOT_START: Promotion activities with this status are not available to TikTok users until the set activity start time. - ONGOING: Promotion activities with this status are available to TikTok users. - EXPIRED: Promotion activities with this status are not available to TikTok users because it has expired. - DEACTIVATED: The activity has been deactivated by the seller and is not available to TikTok users. - NOT_EFFECTIVE: The activity is terminated by the platform and is not available to TikTok users. create_time: type: integer format: int64 description: The time when the activity was created, as a Unix timestamp in milliseconds. update_time: type: integer format: int64 description: The time when the activity was last updated, as a Unix timestamp in milliseconds. product_level: type: string description: |- Activity product dimension, values are: ​- PRODUCT: Promotion activity applies at the product (SPU) level. Any and all SKUs that are part of this product will be subject to the promotion. ​- VARIATION: Promotion activity only applies to specified SKUs. ​- SHOP: Promotion activity applies to all products in the shop. activity_commands: type: array items: type: string description: |- Applicable commands to the activity: - IMMUTABLE: The activity cannot be edited or deactivated. participation_limit: type: array items: $ref: "#/components/schemas/SearchPromotionActivitiesResponseDataActivityParticipationLimit" description: The number of times a buyer can participate in the promotion. discount: $ref: "#/components/schemas/GetActivityResponseDataDiscount" description: Discount information. This field is omitted for `FIXED_PRICE`, `DIRECT_DISCOUNT`, and `FLASHSALE` activities. auction_support_type: type: string enum: - ALL - EXCLUDE_AUCTION x-enum-descriptions: - The activity supports both normal products and auction products. - The activity does not support auction products. description: |- Whether a `SHIPPING_DISCOUNT` activity supports auction products. This field is omitted for other activity types and can be omitted when auction-support data is unavailable. Possible values: - `ALL`: The activity supports both normal products and auction products. - `EXCLUDE_AUCTION`: The activity does not support auction products. SearchPromotionActivitiesResponseDataActivityParticipationLimit: type: object properties: type: type: string description: |- Determines whether the promotion activity limits the number of times each buyer can receive its benefit. e.g.: - `BUYER_NO_LIMIT`: No limit for buyer​s. Buyers can benefit from this promotion across multiple orders. - `BUYER_LIMIT_ONLY_ONE`: Buyers can benefit from this promotion activity for no more than one order. ​Default: `BUYER_NO_LIMIT` SearchResponsiblePersonsRequest: type: object properties: responsible_person_ids: type: array items: type: string description: |- Filter results by these responsible person IDs. Max IDs: The value of `page_size` keyword: type: string maxLength: 200 description: |- Filter results to show those that contain this keyword. Search scope: name, local_number, email Max length: 200 characters **Note**: Provide either the `responsible_person_ids` or `keyword`; if both are provided, `responsible_person_ids` will take priority. locales: type: array items: type: string enum: - de-DE - en-IE - es-ES - fr-FR - it-IT description: |- The BCP-47 locale codes for displaying the responsible person information. Default: The locale of the seller's registered business address. Possible values: - de-DE - en-IE - es-ES - fr-FR - it-IT SearchResponsiblePersonsResponse: 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/SearchResponsiblePersonsResponseData" SearchResponsiblePersonsResponseData: type: object properties: responsible_persons: type: array items: $ref: "#/components/schemas/SearchResponsiblePersonsResponseDataResponsiblePerson" description: The list of responsible persons that meet the query conditions. total_count: type: integer format: int64 description: The number of responsible persons that meet the query conditions. next_page_token: type: string description: An opaque token used to retrieve the next page of a paginated result set. Provide this value in the `page_token` parameter of your request if the current response does not return all the results. SearchResponsiblePersonsResponseDataResponsiblePerson: type: object properties: id: type: string description: The responsible person ID in TikTok Shop. regional_profiles: type: array items: $ref: "#/components/schemas/SearchResponsiblePersonsResponseDataResponsiblePersonRegionalProfile" description: A list of contact details for the responsible person, presented in different languages for each supported EU country. SearchResponsiblePersonsResponseDataResponsiblePersonRegionalProfile: type: object properties: locale: type: string enum: - de-DE - en-IE - es-ES - fr-FR - it-IT description: |- The BCP-47 locale code representing the language used for specifying the responsible person information. Possible values: - de-DE - en-IE - es-ES - fr-FR - it-IT name: type: string maxLength: 200 description: |- The responsible person name. Max length: 200 characters email: type: string description: The email address of the responsible person. phone_number: $ref: "#/components/schemas/SearchResponsiblePersonsResponseDataResponsiblePersonRegionalProfilePhoneNumber" description: The phone number of the responsible person. address: $ref: "#/components/schemas/SearchResponsiblePersonsResponseDataResponsiblePersonRegionalProfileAddress" description: The residential address of the responsible person. SearchResponsiblePersonsResponseDataResponsiblePersonRegionalProfileAddress: 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. Max length: 500 characters street_address_line2: type: string maxLength: 500 description: |- (**Deprecated**: This field is deprecated and will return an empty string. Please refer to `street_address_line1` instead for the relevant details.) An optional secondary line for additional address details, if necessary. Max length: 500 characters deprecated: true district: type: string maxLength: 500 description: |- (**Deprecated**: This field is deprecated and will return an empty string. Please refer to `street_address_line1` instead for the district name.) The district name. Max length: 500 characters deprecated: true city: type: string description: "**Deprecated**: This field returns an empty string. Use `street_address_line1` for the city name." deprecated: true postal_code: type: string maxLength: 500 description: |- The postal code. Max length: 500 characters province: type: string description: "**Deprecated**: This field returns an empty string. Use `street_address_line1` for the province, state, or region name." 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. SearchResponsiblePersonsResponseDataResponsiblePersonRegionalProfilePhoneNumber: type: object properties: country_code: type: string description: |- The country code of the phone number, prefixed by a plus `+` symbol. E.g. +353 for Ireland. Only EU country codes are allowed. Max digits: 4 local_number: type: string description: |- The local number. Length: 7 - 11 digits SearchReturnMerchandiseAuthorizationsRequest: type: object properties: whitelisted_data_fields: type: array items: type: string enum: - LINE_ITEMS - SKU_RETURN_REQUESTS x-enum-descriptions: - Includes `line_items`. - Includes `sku_return_requests`. description: |- Controls which additional fields are included for each RMA. Possible values: - `LINE_ITEMS`: Includes `line_items`. - `SKU_RETURN_REQUESTS`: Includes `sku_return_requests`. filters: $ref: "#/components/schemas/SearchReturnMerchandiseAuthorizationsRequestFilter" description: Filters to narrow the result set. sort: $ref: "#/components/schemas/Sort" description: Sorting criteria for the result set. pagination: $ref: "#/components/schemas/Pagination" description: Pagination configuration. SearchReturnMerchandiseAuthorizationsRequestFilter: type: object properties: rma_ids: type: array items: type: string description: Restricts results to the specified RMA records. Each RMA ID must be a base-10 integer string that fits in a signed 64-bit integer. package_ids: type: array items: type: string description: Restricts results to the specified packages. Each package ID must be a base-10 integer string that fits in a signed 64-bit integer. statuses: type: array items: type: string enum: - INIT - AWAITING_BUYER_RETURN - RETURN_IN_TRANSIT - PENDING_PACKAGE_REVIEW - PACKAGE_REVIEW_COMPLETED description: |- Restricts results to the specified RMA data statuses. Possible values: - `INIT` - `AWAITING_BUYER_RETURN` - `RETURN_IN_TRANSIT` - `PENDING_PACKAGE_REVIEW` - `PACKAGE_REVIEW_COMPLETED` aftersales_request_ids: type: array items: type: string description: Restricts results to the specified aftersales requests. Each ID must be a base-10 integer string that fits in a signed 64-bit integer. main_order_ids: type: array items: type: string description: Restricts results to the specified main (forward) order IDs. time: $ref: "#/components/schemas/Time" description: Time-based filtering criteria. SearchReturnMerchandiseAuthorizationsResponse: 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/SearchReturnMerchandiseAuthorizationsResponseData" SearchReturnMerchandiseAuthorizationsResponseData: type: object properties: return_merchandise_authorizations: type: array items: $ref: "#/components/schemas/SearchReturnMerchandiseAuthorizationsResponseDataReturnMerchandiseAuthorization" description: List of return merchandise authorization (RMA) records matching the filters. This field is omitted when no records match. total_count: type: integer format: int64 description: The total result set size, independent of pagination. next_page_token: type: string description: Used to fetch the next page/set of results. SearchReturnMerchandiseAuthorizationsResponseDataReturnMerchandiseAuthorization: type: object properties: id: type: string description: Unique identifier for this RMA data. package_id: type: string description: Identifier of the associated physical return package. aftersales_request_id: type: string description: Identifier of the parent aftersales request. status: type: string enum: - INIT - AWAITING_BUYER_RETURN - RETURN_IN_TRANSIT - PENDING_PACKAGE_REVIEW - PACKAGE_REVIEW_COMPLETED description: |- The current state of this RMA data. Possible values: - `INIT` - `AWAITING_BUYER_RETURN` - `RETURN_IN_TRANSIT` - `PENDING_PACKAGE_REVIEW` - `PACKAGE_REVIEW_COMPLETED` line_items: type: array items: $ref: "#/components/schemas/LineItem" description: Item units expected in this return package. This field is returned only when `LINE_ITEMS` is included in `whitelisted_data_fields` and matching item data is available. sku_return_requests: type: array items: $ref: "#/components/schemas/SkuReturnRequest" description: SKU-level sub return requests associated with this RMA. This field is returned only when `SKU_RETURN_REQUESTS` is included in `whitelisted_data_fields` and matching data is available. SearchReturnsRequest: type: object properties: return_ids: type: array items: type: string description: List of return IDs. Each ID must be a base-10 integer string that fits in a signed 64-bit integer. order_ids: type: array items: type: string description: List of TikTok Shop order IDs. Each ID must be a base-10 integer string that fits in a signed 64-bit integer. buyer_user_ids: type: array items: type: string description: List of TikTok Shop buyer user IDs. Each ID must be a base-10 integer string that fits in a signed 64-bit integer. return_types: type: array items: type: string enum: - REFUND - RETURN_AND_REFUND - REPLACEMENT - EXCHANGE description: |- List of return types. Available values: - `REFUND` - `RETURN_AND_REFUND` - `REPLACEMENT` - `EXCHANGE` return_status: type: array items: type: string enum: - RETURN_OR_REFUND_REQUEST_PENDING - REFUND_OR_RETURN_REQUEST_REJECT - AWAITING_BUYER_SHIP - BUYER_SHIPPED_ITEM - REJECT_RECEIVE_PACKAGE - RETURN_OR_REFUND_REQUEST_SUCCESS - RETURN_OR_REFUND_REQUEST_CANCEL - RETURN_OR_REFUND_REQUEST_COMPLETE - REPLACEMENT_REQUEST_PENDING - REPLACEMENT_REQUEST_REJECT - REPLACEMENT_REQUEST_REFUND_SUCCESS - REPLACEMENT_REQUEST_CANCEL - REPLACEMENT_REQUEST_COMPLETE - AWAITING_BUYER_RESPONSE - EXCHANGE_REQUEST_PENDING - EXCHANGE_REQUEST_REFUND_SUCCESS - EXCHANGE_REQUEST_CANCEL - EXCHANGE_REQUEST_COMPLETE x-enum-descriptions: - Buyer has initiated a return or refund request. The request is pending review by seller or system. - The return or refund request was rejected. - The return request was approved. The seller is waiting for the buyer to ship the approved items to the seller. If the buyer doesn't ship the items to the seller before the deadline, the platform will close the request. - Buyer has shipped the approved items to seller. - Seller inspected the returned items and rejected the return request. - The return/refund request was successful. The buyer will be refunded. - The request has been cancelled by the buyer or system. - The return/refund was processed successfully. The buyer has been refunded. - Buyer has initiated a replacement request. The request is pending review by seller. - Seller reject the buyer replacement request. - Buyer's replacement request was resolved by refund due to insufficient inventory. - Buyer canceled the replacement request. - Seller has approved the buyer's replacement request, platform will generate a new order for seller to fulfill. - Seller offer another return type to the buyer, and waiting buyer response. Seller proposed return type can check the `seller_proposed_return_type`. - Buyer has initiated an exchange request. The request is pending review by seller. - Buyer's exchange request was resolved by refund due to insufficient inventory. - Buyer canceled the exchange request. - Seller has approved the buyer's exchange request, platform will generate a new order for seller to fulfill. description: |- List of return status. Available values: - `RETURN_OR_REFUND_REQUEST_PENDING`: Buyer has initiated a return or refund request. The request is pending review by seller or system. - `REFUND_OR_RETURN_REQUEST_REJECT`: The return or refund request was rejected. - `AWAITING_BUYER_SHIP`: The return request was approved. The seller is waiting for the buyer to ship the approved items to the seller. If the buyer doesn't ship the items to the seller before the deadline, the platform will close the request. - `BUYER_SHIPPED_ITEM`: Buyer has shipped the approved items to seller. - `REJECT_RECEIVE_PACKAGE`: Seller inspected the returned items and rejected the return request. - `RETURN_OR_REFUND_REQUEST_SUCCESS`: The return/refund request was successful. The buyer will be refunded. - `RETURN_OR_REFUND_REQUEST_CANCEL`: The request has been cancelled by the buyer or system. - `RETURN_OR_REFUND_REQUEST_COMPLETE`: The return/refund was processed successfully. The buyer has been refunded. - `REPLACEMENT_REQUEST_PENDING`: Buyer has initiated a replacement request. The request is pending review by seller. - `REPLACEMENT_REQUEST_REJECT`: Seller reject the buyer replacement request. - `REPLACEMENT_REQUEST_REFUND_SUCCESS`: Buyer's replacement request was resolved by refund due to insufficient inventory. - `REPLACEMENT_REQUEST_CANCEL`: Buyer canceled the replacement request. - `REPLACEMENT_REQUEST_COMPLETE`: Seller has approved the buyer's replacement request, platform will generate a new order for seller to fulfill. - `AWAITING_BUYER_RESPONSE`: Seller offer another return type to the buyer, and waiting buyer response. Seller proposed return type can check the `seller_proposed_return_type`. - `EXCHANGE_REQUEST_PENDING`: Buyer has initiated an exchange request. The request is pending review by seller. - `EXCHANGE_REQUEST_REFUND_SUCCESS`: Buyer's exchange request was resolved by refund due to insufficient inventory. - `EXCHANGE_REQUEST_CANCEL`: Buyer canceled the exchange request. - `EXCHANGE_REQUEST_COMPLETE`: Seller has approved the buyer's exchange request, platform will generate a new order for seller to fulfill. seller_proposed_return_type: type: array items: type: string enum: - PARTIAL_REFUND description: |- List of seller proposed return types. Available values: - `PARTIAL_REFUND` create_time_ge: type: integer format: int64 description: |- Filter returns to show only those that are created on or after the specified date and time. Unix timestamp. Note: `create_time_ge` and `create_time_le` together constitute the creation time filter condition. - If `create_time_ge` is filled but `create_time_le` is empty, `create_time_le` will default to the current time. - If `create_time_lt` is filled but `create_time_ge` is empty, `create_time_ge` will default to the earliest shop time. arbitration_status: type: array items: type: string enum: - IN_PROGRESS - SUPPORT_BUYER - SUPPORT_SELLER - CLOSED x-enum-descriptions: - The TikTok Shop platform operator is processing arbitration. Platform may request additional information from the seller. - The platform operator supports buyer. - The platform operator supports seller. - Arbitration is closed. description: |- List of arbitration statuses. Available values: - `IN_PROGRESS`: The TikTok Shop platform operator is processing arbitration. Platform may request additional information from the seller. - `SUPPORT_BUYER`: The platform operator supports buyer. - `SUPPORT_SELLER`: The platform operator supports seller. - `CLOSED`: Arbitration is closed. update_time_ge: type: integer format: int64 description: |- Filter returns to show only those that are updated on or after the specified date and time. Unix timestamp. Note: `update_time_ge` and `update_time_le` together define the update time filter condition. - If `update_time_ge` is filled but `update_time_le` is empty, `update_time_le` will default to the current time. - If `update_time_lt` is filled but `update_time_ge` is empty, `update_time_ge` will default to the earliest shop time. update_time_lt: type: integer format: int64 description: Filter returns to those updated before the specified time. Provide a Unix timestamp in seconds. locale: type: string description: |- The BCP-47 locale codes for displaying the returns, delimited by commas. Default: `en` Refer to [Locale codes](678e3a47bae28f030a8c7523) for the list of supported locale codes. create_time_lt: type: integer format: int64 description: Filter returns to those created before the specified time. Provide a Unix timestamp in seconds. SearchReturnsResponse: 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/SearchReturnsResponseData" SearchReturnsResponseData: type: object properties: return_orders: type: array items: $ref: "#/components/schemas/SearchReturnsResponseDataReturnOrder" description: List of returns in the current page. This field is omitted when the current page contains no return records. total_count: type: integer format: int64 description: The number of returns that meet the query conditions. next_page_token: type: string description: An opaque token used to retrieve the next page of a paginated result set. If `next_page_token` is non-empty, provide it in the `page_token` parameter of the next request. If `next_page_token` is empty, stop pagination. SearchReturnsResponseDataReturnOrder: type: object properties: order_id: type: string description: TikTok Shop order ID. return_id: type: string description: The identifier of a specific return. return_type: type: string enum: - REFUND - RETURN_AND_REFUND - REPLACEMENT - EXCHANGE x-enum-descriptions: - Seller will issue a refund without return. The buyer is not required to send the item(s) back to the seller. - Buyer is required to send the item(s) back to the seller. The seller will need to review the condition of the returned item(s) before a refund can be issued to the buyer. - The buyer requires the seller to replace the item(s). - The buyer requires the seller to exchange the item(s). description: |- Return type. Available values: - `REFUND`: Seller will issue a refund without return. The buyer is not required to send the item(s) back to the seller. - `RETURN_AND_REFUND`: Buyer is required to send the item(s) back to the seller. The seller will need to review the condition of the returned item(s) before a refund can be issued to the buyer. - `REPLACEMENT`: The buyer requires the seller to replace the item(s). - `EXCHANGE`: The buyer requires the seller to exchange the item(s). return_status: type: string enum: - RETURN_OR_REFUND_REQUEST_PENDING - REFUND_OR_RETURN_REQUEST_REJECT - AWAITING_BUYER_SHIP - BUYER_SHIPPED_ITEM - REJECT_RECEIVE_PACKAGE - RETURN_OR_REFUND_REQUEST_SUCCESS - RETURN_OR_REFUND_REQUEST_CANCEL - RETURN_OR_REFUND_REQUEST_COMPLETE - REPLACEMENT_REQUEST_PENDING - REPLACEMENT_REQUEST_REJECT - REPLACEMENT_REQUEST_REFUND_SUCCESS - REPLACEMENT_REQUEST_CANCEL - REPLACEMENT_REQUEST_COMPLETE - AWAITING_BUYER_RESPONSE - EXCHANGE_REQUEST_PENDING - EXCHANGE_REQUEST_REFUND_SUCCESS - EXCHANGE_REQUEST_CANCEL - EXCHANGE_REQUEST_COMPLETE x-enum-descriptions: - Buyer has initiated a return or refund request. The request is pending review by seller or platform. - The return or refund request was rejected. - The return request was approved. The seller is waiting for the buyer to ship the approved items to the seller. If the buyer doesn't ship the items to the seller before the deadline, the platform will close the request. - Buyer has shipped the approved items to seller. - Seller inspected the returned items and rejected the return package. - The return/refund request was approved. The buyer will be refunded. - The request has been cancelled by the buyer or system. - The return/refund was processed successfully. The buyer has been refunded. - Buyer has initiated a replacement request. The request is pending review by seller. - Seller reject the buyer replacement request. - Buyer's replacement request was resolved by refund due to insufficient inventory. - Buyer canceled the replacement request. - Seller has approved the buyer's replacement request, platform will generate a new order for seller to fulfill. - Seller offer another return type to the buyer, and waiting buyer response. Seller proposed return type can check the `seller_proposed_return_type`. - Buyer has initiated an exchange request. The request is pending review by seller. - Buyer's exchange request was resolved by refund due to insufficient inventory. - Buyer canceled the exchange request. - Seller has approved the buyer's exchange request, platform will generate a new order for seller to fulfill. description: |- Return status. Available values: - `RETURN_OR_REFUND_REQUEST_PENDING`: Buyer has initiated a return or refund request. The request is pending review by seller or platform. - `REFUND_OR_RETURN_REQUEST_REJECT`: The return or refund request was rejected. - `AWAITING_BUYER_SHIP`: The return request was approved. The seller is waiting for the buyer to ship the approved items to the seller. If the buyer doesn't ship the items to the seller before the deadline, the platform will close the request. - `BUYER_SHIPPED_ITEM`: Buyer has shipped the approved items to seller. - `REJECT_RECEIVE_PACKAGE`: Seller inspected the returned items and rejected the return package. - `RETURN_OR_REFUND_REQUEST_SUCCESS`: The return/refund request was approved. The buyer will be refunded. - `RETURN_OR_REFUND_REQUEST_CANCEL`: The request has been cancelled by the buyer or system. - `RETURN_OR_REFUND_REQUEST_COMPLETE`: The return/refund was processed successfully. The buyer has been refunded. - `REPLACEMENT_REQUEST_PENDING`: Buyer has initiated a replacement request. The request is pending review by seller. - `REPLACEMENT_REQUEST_REJECT`: Seller reject the buyer replacement request. - `REPLACEMENT_REQUEST_REFUND_SUCCESS`: Buyer's replacement request was resolved by refund due to insufficient inventory. - `REPLACEMENT_REQUEST_CANCEL`: Buyer canceled the replacement request. - `REPLACEMENT_REQUEST_COMPLETE`: Seller has approved the buyer's replacement request, platform will generate a new order for seller to fulfill. - `AWAITING_BUYER_RESPONSE`: Seller offer another return type to the buyer, and waiting buyer response. Seller proposed return type can check the `seller_proposed_return_type`. - `EXCHANGE_REQUEST_PENDING`: Buyer has initiated an exchange request. The request is pending review by seller. - `EXCHANGE_REQUEST_REFUND_SUCCESS`: Buyer's exchange request was resolved by refund due to insufficient inventory. - `EXCHANGE_REQUEST_CANCEL`: Buyer canceled the exchange request. - `EXCHANGE_REQUEST_COMPLETE`: Seller has approved the buyer's exchange request, platform will generate a new order for seller to fulfill. arbitration_status: type: string enum: - IN_PROGRESS - SUPPORT_BUYER - SUPPORT_SELLER - CLOSED x-enum-descriptions: - The TikTok Shop platform operator is processing arbitration and may request additional information from the seller. - The platform operator supports the buyer. - The platform operator supports the seller. - Arbitration is closed. description: |- Arbitration status. Available values: - `IN_PROGRESS`: The TikTok Shop platform operator is processing arbitration and may request additional information from the seller. - `SUPPORT_BUYER`: The platform operator supports the buyer. - `SUPPORT_SELLER`: The platform operator supports the seller. - `CLOSED`: Arbitration is closed. role: type: string enum: - BUYER - SELLER - OPERATOR - SYSTEM x-enum-descriptions: - "" - "" - TikTok Shop platform operator. - TikTok Shop system. description: |- Return initiation role. Available values: - `BUYER` - `SELLER` - `OPERATOR` : TikTok Shop platform operator. - `SYSTEM`: TikTok Shop system. Please see "API overview" to learn more about roles. return_reason: type: string description: Machine-readable reason code for the return. Use `return_reason_text` for localized display text. return_reason_text: type: string description: |- Reason for return, in localized text. You can change language using the locale request parameter. shipment_type: type: string enum: - PLATFORM - BUYER_ARRANGE x-enum-descriptions: - The buyer uses TikTok Shop's shipping service. See `handover_method` for whether the buyer uses `DROP_OFF` or `PICKUP`. - The buyer arranges the return shipment. description: |- The shipment method selected by the buyer for sending the item(s) back to the seller. Available values: - `PLATFORM`: The buyer uses TikTok Shop's shipping service. See `handover_method` for whether the buyer uses `DROP_OFF` or `PICKUP`. - `BUYER_ARRANGE`: The buyer arranges the return shipment. handover_method: type: string description: |- The handover method buyer chooses to use when returning item(s) to seller using platform's shipping service. - `DROP_OFF`: buyer will drop off the item(s) at courier - `PICKUP`: buyer is scheduling a pick up service offered by the courier. return_tracking_number: type: string description: The tracking number of parcels when buyer returns the item(s). return_provider_name: type: string description: The provider name of parcel when buyer returns the item(s). return_provider_id: type: string description: The provider ID of parcel when buyer returns the items. pre_return_id: type: string description: The previous return ID the current return order is edited from. next_return_id: type: string description: The next return ID the current return order is edited to. can_buyer_keep_item: type: boolean description: Indicates whether the buyer may keep the item(s). This field is returned as `true` for replacement requests and is omitted for other return types. update_time: type: integer format: int64 description: The time when the return was last updated, as a Unix timestamp in seconds. seller_next_action_response: type: array items: $ref: "#/components/schemas/SellerNextActionResponse" description: Seller's next action and deadline. create_time: type: integer format: int64 description: The time when the return was created, as a Unix timestamp in seconds. return_line_items: type: array items: $ref: "#/components/schemas/SearchReturnsResponseDataReturnOrderReturnLineItem" description: Return order lines items. discount_amount: type: array items: $ref: "#/components/schemas/SearchReturnsResponseDataReturnOrderDiscountAmount" description: Discount refund details. shipping_fee_amount: type: array items: $ref: "#/components/schemas/SearchReturnsResponseDataReturnOrderShippingFeeAmount" description: The return shipping fee details. refund_amount: $ref: "#/components/schemas/RefundAmount" description: Total refund amount to buyer. return_shipping_document_type: type: string enum: - SHIPPING_LABEL - QR_CODE - QR_CODE_NBNL x-enum-descriptions: - "" - QR Code with Box - QR Code with No Box No Label description: |- The type of return shipping document selected by the buyer. Available values: - `SHIPPING_LABEL` - `QR_CODE` - QR Code with Box - `QR_CODE_NBNL` - QR Code with No Box No Label return_method: type: string description: |- Return method: - `SELLER_SHIPPED`: Seller offers the return shipping service. - `BUYER_SHIPPED`: Buyer offers the return shipping service. - `PLATFORM_SHIPPED`: TikTok Shop offers the return shipping service. is_combined_return: type: boolean description: This field will return true if the buyer is asking to combine multiple returns into one return package. combined_return_id: type: string description: If `is_combined_return` is `true`, this field will return the `combined_return_id` associated with the combined return. seller_proposed_return_type: type: string description: |- Seller proposed return type: - `PARTIAL_REFUND` partial_refund: $ref: "#/components/schemas/PartialRefund" description: Partial refund details. buyer_rejected_partial_refund: type: boolean description: |- Only return this field when seller initiated the partial refund. Available values: - `TRUE`: Buyer reject the seller partial refund offer. - `FALSE`: Buyer accept the seller partial refund offer or awaiting buyer response. return_warehouse_address: $ref: "#/components/schemas/ReturnWarehouseAddress" description: The return warehouse address details provided by the seller. is_quick_refund: type: boolean description: If the return hit the quick refund strategy, the seller cannot reject the received package SearchReturnsResponseDataReturnOrderDiscountAmount: type: object properties: currency: type: string description: The discount currency. product_seller_discount: type: string description: The refund amount of product seller discount. shipping_fee_platform_discount: type: string description: The refund amount of shipping fee platform discount. shipping_fee_seller_discount: type: string description: The refund amount of shipping fee seller discount. product_platform_discount: type: string description: The refund amount of platform discount. SearchReturnsResponseDataReturnOrderReturnLineItem: type: object properties: return_line_item_id: type: string description: Return order line ID. order_line_item_id: type: string description: Order line ID. sku_id: type: string description: SKU ID. sku_name: type: string description: SKU name. product_name: type: string description: Product name. seller_sku: type: string description: SKU name defined by seller. product_image: $ref: "#/components/schemas/ProductImage" description: Product image information. refund_amount: $ref: "#/components/schemas/RefundAmount" description: Refund amount details. return_sub_line_items: type: array items: $ref: "#/components/schemas/ReturnSubLineItem" description: Return sub-order line items. These items represent SKUs that belong to a "virtual bundle" defined by a seller. This field includes all relevant information about each item in the virtual bundle. SearchReturnsResponseDataReturnOrderShippingFeeAmount: type: object properties: currency: type: string description: Return shipping fee currency. seller_paid_return_shipping_fee: type: string description: The amount of return shipping fee seller paid. platform_paid_return_shipping_fee: type: string description: The amount of return shipping fee platform paid. buyer_paid_return_shipping_fee: type: string description: The amount of return shipping fee buyer paid. SearchSampleApplicationFulfillmentsRequest: type: object properties: content_format: type: string enum: - LIVE - VIDEO description: |- The content type generated by the creator after receiving the samples. Possible enumerations: - LIVE - VIDEO SearchSampleApplicationFulfillmentsResponse: 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/SearchSampleApplicationFulfillmentsResponseData" SearchSampleApplicationFulfillmentsResponseData: type: object properties: fulfillments: type: array items: $ref: "#/components/schemas/SearchSampleApplicationFulfillmentsResponseDataFulfillment" description: Fulfillments SearchSampleApplicationFulfillmentsResponseDataFulfillment: type: object properties: product: $ref: "#/components/schemas/SearchSampleApplicationFulfillmentsResponseDataFulfillmentProduct" description: Product information content: $ref: "#/components/schemas/SearchSampleApplicationFulfillmentsResponseDataFulfillmentContent" description: Fulfillment content information. SearchSampleApplicationFulfillmentsResponseDataFulfillmentContent: type: object properties: id: type: string description: The video or live room identifier. format: type: string description: |- The format of the generated content: - LIVE - `VIDEO` url: type: string description: The content source link. view_count: type: integer format: int64 description: The cumulative number of views of the content. like_count: type: integer format: int64 description: The cumulative number of likes on the content. comment_count: type: integer format: int64 description: The cumulative number of comments on the content. paid_order_count: type: integer format: int64 description: The cumulative total number of orders paid for content. page_link: type: string description: Content page url of TikTok. description: type: string description: The title of video or the description of the live room. create_time: type: integer format: int64 description: |- - When `format` is `VIDEO`, this is the Unix timestamp, in seconds, when the video is first made public and linked to the product. - When `format` is `LIVE`, this is the Unix timestamp, in seconds, when the product link is first added to the live stream. live_end_time: type: integer format: int64 description: |- Only when `format==LIVE`. It refers to the time when the product link is removed from the live room. If the product link remains active and is not removed, then it is the end of the live stream. SearchSampleApplicationFulfillmentsResponseDataFulfillmentProduct: type: object properties: id: type: string description: The product identifier. main_image_url: type: string description: The cover image url of product. SearchSampleApplicationsRequest: type: object properties: product_id: type: string description: The unique identifier of a product. It is used to specify which product's sample application details are being queried. title: type: string description: Product name, supports fuzzy search queries. It allows sellers to search for products by name when managing sample applications. creator_user_oepn_id: type: string description: The creator's Open ID. Do not use a user ID, creator ID, or seller ID. Send this property as `creator_user_oepn_id` exactly as spelled; do not change the wire key to `creator_user_open_id`. username: type: string description: TikTok User Name of a creator, supports fuzzy search target_collabration_id: type: string description: The unique ID generated after creating a target collaboration. Send this property as `target_collabration_id` exactly as spelled; do not change the wire key to `target_collaboration_id`. order_id: type: string description: Main order ID associated with a sample order when the sample application is approved by seller. status: type: string enum: - PENDING - AWAITING_SHIPMENT - SHIPPED - CONTENT_PENDING - REJECT_CANCELLED - OVERDUE_CANCELLED - UNFULFILL_CANCELLED - DEL_OPEN_COLLAB - SELLER_NOT_SHIP_CANCELLED - WITHDRAW_CANCELLED - UNFULFILLABLE_CANCELLED - OPS_CANCELLED - OPS_FAILED - OPS_COMPLETED - COMPLETED x-enum-descriptions: - The sample application is waiting for the seller's review. - The application is approved, and the seller needs to ship the sample. - The sample has been shipped by the seller and is waiting for the creator to receive the package. - The creator has received the sample package and is expected to create content. - The sample application has been rejected by the seller. - The sample application has expired due to being overdue. - The creator did not fulfill the commitment to create content within the agreed timeframe. - Open collaboration has been deleted. - The seller did not ship the sample within the required timeframe. - The creator withdrew the sample application before the seller approved it. - The application was cancelled due to reasons beyond the creator's control, making it impossible to create content. - The application was manually cancelled by operations staff. - The application was marked as failed by operations staff. - The application was manually marked as completed by operations staff. - The application is complete, and the creator has posted the content. description: |- The status of sample applications. The possible enumerated values are: - PENDING: The sample application is waiting for the seller's review. - AWAITING_SHIPMENT: The application is approved, and the seller needs to ship the sample. - SHIPPED: The sample has been shipped by the seller and is waiting for the creator to receive the package. - CONTENT_PENDING: The creator has received the sample package and is expected to create content. - REJECT_CANCELLED: The sample application has been rejected by the seller. - OVERDUE_CANCELLED: The sample application has expired due to being overdue. - UNFULFILL_CANCELLED: The creator did not fulfill the commitment to create content within the agreed timeframe. - DEL_OPEN_COLLAB: Open collaboration has been deleted. - SELLER_NOT_SHIP_CANCELLED: The seller did not ship the sample within the required timeframe. - WITHDRAW_CANCELLED: The creator withdrew the sample application before the seller approved it. - UNFULFILLABLE_CANCELLED: The application was cancelled due to reasons beyond the creator's control, making it impossible to create content. - OPS_CANCELLED: The application was manually cancelled by operations staff. - OPS_FAILED: The application was marked as failed by operations staff. - OPS_COMPLETED: The application was manually marked as completed by operations staff. - COMPLETED: The application is complete, and the creator has posted the content. This field allows for tracking the status of a sample application throughout its lifecycle, providing visibility into each stage of the process for sellers and creators. SearchSampleApplicationsResponse: 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/SearchSampleApplicationsResponseData" SearchSampleApplicationsResponseData: type: object properties: next_page_token: type: string description: The pagination token to pass as `page_token` in the next request. Reuse the same `page_size` for each subsequent page. An empty string indicates that there are no more pages. total_count: type: integer format: int64 description: total count sample_applications: type: array items: $ref: "#/components/schemas/SearchSampleApplicationsResponseDataSampleApplication" description: The sample applications from creators SearchSampleApplicationsResponseDataSampleApplication: type: object properties: id: type: string description: The unique id of sample request application ID commission_rate: type: string description: The commission rate set by the merchant for creators for this product, represented as a decimal fraction with two decimal places. For example, `0.20` represents 20%. The range is [0.01, 0.8]. status: type: string enum: - PENDING - AWAITING_SHIPMENT - SHIPPED - CONTENT_PENDING - REJECT_CANCELLED - OVERDUE_CANCELLED - UNFULFILL_CANCELLED - DEL_OPEN_COLLAB - SELLER_NOT_SHIP_CANCELLED - WITHDRAW_CANCELLED - UNFULFILLABLE_CANCELLED - OPS_CANCELLED - OPS_FAILED - OPS_COMPLETED - COMPLETED x-enum-descriptions: - The sample application is waiting for the seller's review. - The application is approved, and the seller needs to ship the sample. - The sample has been shipped by the seller and is waiting for the creator to receive the package. - The creator has received the sample package and is expected to create content. - The sample application has been rejected by the seller. - The sample application has expired due to being overdue. - The creator did not fulfill the commitment to create content within the agreed timeframe. - The open collaboration plan has been deleted. - The seller did not ship the sample within the required timeframe. - The creator withdrew the sample application before the seller approved it. - The application was cancelled due to reasons beyond the creator's control, making it impossible to create content. - The application was manually cancelled by operations staff. - The application was marked as failed by operations staff. - The application was manually marked as completed by operations staff. - The application is complete, and the creator has finished creating the content. description: |- The status of sample applications. The possible enumerated values are: - PENDING: The sample application is waiting for the seller's review. - AWAITING_SHIPMENT: The application is approved, and the seller needs to ship the sample. - SHIPPED: The sample has been shipped by the seller and is waiting for the creator to receive the package. - CONTENT_PENDING: The creator has received the sample package and is expected to create content. - REJECT_CANCELLED: The sample application has been rejected by the seller. - OVERDUE_CANCELLED: The sample application has expired due to being overdue. - UNFULFILL_CANCELLED: The creator did not fulfill the commitment to create content within the agreed timeframe. - DEL_OPEN_COLLAB: The open collaboration plan has been deleted. - SELLER_NOT_SHIP_CANCELLED: The seller did not ship the sample within the required timeframe. - WITHDRAW_CANCELLED: The creator withdrew the sample application before the seller approved it. - UNFULFILLABLE_CANCELLED: The application was cancelled due to reasons beyond the creator's control, making it impossible to create content. - OPS_CANCELLED: The application was manually cancelled by operations staff. - OPS_FAILED: The application was marked as failed by operations staff. - OPS_COMPLETED: The application was manually marked as completed by operations staff. - COMPLETED: The application is complete, and the creator has finished creating the content. order_id: type: string description: The sample order is generated after the sample application is approved by seller available_quantity: type: integer format: int64 description: The remaining stock quota of a sample product. approve_expiration_time: type: integer format: int64 description: The seller approval deadline for the sample application, expressed as a Unix timestamp in seconds. shipment_expiration_time: type: integer format: int64 description: The deadline for the seller to ship the sample for the application, expressed as a Unix timestamp in seconds. tracking_number: type: string description: The logistics tracking number for the sample application order fulfillment_status: type: string enum: - PENDING - ONGOING - SUCCEED - FAILED - OVERDUE - SUSPEND - CANCELLED - EXEMPTED x-enum-descriptions: - The creator is yet to fulfill the content creation obligation. - Fulfillment is in progress; content has been created and is being evaluated against criteria. - Fulfillment has been successfully completed; the content meets the required standards. - Fulfillment failed; the content did not meet the required standards. - Fulfillment is overdue; the creator did not meet the deadline. - Fulfillment has been suspended. - Fulfillment has been cancelled, either by the creator or due to operational reasons. - The creator has been exempted from the fulfillment obligation. description: |- It indicates the current status of the fulfillment process. The possible values are: - PENDING: The creator is yet to fulfill the content creation obligation. - ONGOING: Fulfillment is in progress; content has been created and is being evaluated against criteria. - SUCCEED: Fulfillment has been successfully completed; the content meets the required standards. - FAILED: Fulfillment failed; the content did not meet the required standards. - OVERDUE: Fulfillment is overdue; the creator did not meet the deadline. - SUSPEND: Fulfillment has been suspended. - CANCELLED: Fulfillment has been cancelled, either by the creator or due to operational reasons. - EXEMPTED: The creator has been exempted from the fulfillment obligation. is_approvable: type: boolean description: The sample application can be approved or not. disapprovable_reasons: type: array items: type: string description: Reasons the sample application cannot be approved. This list may be absent or empty even when `is_approvable` is `false`; always check `is_approvable` to determine whether approval is allowed. partner_name: type: string description: The name of the partner if the sample application is submitted on behalf of a creator by an agency. It is only populated when an agency handles the application process instead of the creator directly. creator: $ref: "#/components/schemas/SearchSampleApplicationsResponseDataSampleApplicationCreator" description: Creator details, including the creator's TikTok username, Creator Open ID, profile information, and e-commerce performance metrics such as sales and fulfillment rates. product: $ref: "#/components/schemas/SearchSampleApplicationsResponseDataSampleApplicationProduct" description: product information SearchSampleApplicationsResponseDataSampleApplicationCreator: type: object properties: creator_open_id: type: string description: Creator Open ID. [More details](https://partner.tiktokshop.com/docv2/page/3obfokj6) username: type: string description: TikTok User Name of a creator nickname: type: string description: TikTok Nick Name of a creator follower_count: type: integer format: int64 description: The number of creator's followers avatar_url: type: string description: The URL of the creator's avatar image gmv: $ref: "#/components/schemas/Gmv" description: GMV generated by a creators' shoppable content over the past 30 days. It is formatted as a floating-point number with a currency symbol (e.g., "$1234.56"). If the creator has not authorized the disclosure of this information, the field returns an empty string. content_count: type: integer format: int64 description: The number of contents a creator has posted in the last 30 days. It is formatted as an integer. If the creator has not authorized the sharing of this information, the field returns an empty string. fulfillment_percentage: type: string description: The creator's sample fulfillment rate over the past 90 days, returned as a percentage string with no percent sign (for example, `60.85`). If the creator has not authorized disclosure of this information, the field returns an empty string. ec_video_view: type: integer format: int64 description: The median number of creators' shoppable video views over the past 30 days. If the creator has not authorized the sharing of this information, the field returns an empty string. SearchSampleApplicationsResponseDataSampleApplicationProduct: type: object properties: id: type: string description: The product identifier. title: type: string description: The product name of the product. sku_id: type: string description: The unique id of product sku which creator apply for as sample. sku_image_url: type: string description: The URL of SKU image. sku_name: type: string description: The SKU property value names, joined by commas. SearchSellerAffiliateOrdersRequest: type: object properties: create_time_lt: type: integer format: int64 description: Filter orders created before this time, specified as a Unix timestamp in seconds. Use it with `create_time_ge`; the interval in a single request must not exceed three months. See `create_time_ge` for omitted-bound behavior. create_time_ge: type: integer format: int64 description: |- Filter orders to show only those that are created on or after the specified date and time. Unix timestamp. Note: `create_time_ge` and `create_time_lt` together constitute the creation time filter condition. - If `create_time_ge` is filled but `create_time_lt` is empty, `create_time_lt` will default to the current time. - If `create_time_lt` is filled but `create_time_ge` is empty, `create_time_ge` will default to the earliest shop time. If both are not specified, data from the last three months will be queried by default. program_id: type: string description: Filter orders by the associated affiliate partner campaign ID. SearchSellerAffiliateOrdersResponse: 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/SearchSellerAffiliateOrdersResponseData" SearchSellerAffiliateOrdersResponseData: type: object properties: orders: type: array items: $ref: "#/components/schemas/SearchSellerAffiliateOrdersResponseDataOrder" description: The orders represented by the SKU-order records selected for this page, grouped by order ID. Pagination is applied before grouping, so `orders` can contain fewer objects than `page_size`, and SKU entries for the same order can appear on different pages. Aggregate SKU entries with the same order ID across all retrieved pages. next_page_token: type: string description: An opaque token for retrieving the next page. To keep the effective time filter fixed across pages, provide explicit `create_time_ge` and `create_time_lt` values in the first request. If this value is non-empty, pass it as `page_token` in the next request and reuse those exact time values and the same `program_id` value or omission. An empty string indicates that there is no next page. total_count: type: integer format: int64 description: The total number of sku orders that matches the query conditions. SearchSellerAffiliateOrdersResponseDataOrder: type: object properties: id: type: string description: The order ID. delivery_time: type: integer format: int64 description: The date and time when the order was delivered. Unix timestamp. create_time: type: integer format: int64 description: The Unix timestamp, in seconds, when the order was created. status: type: string description: Deprecated. This field is not returned. Use each SKU's `settlement_status` instead. deprecated: true skus: type: array items: $ref: "#/components/schemas/SearchSellerAffiliateOrdersResponseDataOrderSku" description: The list of SKUs that are included in this order. SearchSellerAffiliateOrdersResponseDataOrderSku: type: object properties: sku_id: type: string description: The ID of your SKU settlement_status: type: string description: |- The current settlement status of the sku order. Possible options are: - Unknown: The status of the order is undefined. It might be updated later. - AWAITING PAYMENT：The order hasn't been paid by customer yet, only estimated commission is available - To-SETTLE：The order is waiting for settlement, only estimated commission is available - SETTLED: The commission of the order is already settled. - INELIGIBLE: The order has been returned/refunded/canceled by the buyer, and no commission will be settled. open_collaboration_id: type: string description: The ID of the open collaboration in which the product is enrolled. target_collaboration_id: type: string description: The ID of the target collaboration in which the product is enrolled. campaign_id: type: string description: The ID of the TAP campaign in which the product is enrolled. creator_username: type: string description: The username of the creator attributed to the SKU order. This field is returned as an empty string for affiliate partner campaign orders. price: $ref: "#/components/schemas/Price" description: The SKU selling price information. quantity: type: integer format: int64 description: The number of units of the SKU in the order, including units that were later refunded. content_type: type: string enum: - SHOP - VIDEO - LIVE - PRE_LIVE - PROMOTION_PAGE - LINKSHARE description: |- The content format of the creator content through which the order was created. Possible values: - SHOP - VIDEO - LIVE - PRE_LIVE - PROMOTION_PAGE - LINKSHARE content_id: type: string description: The content identifier. product_id: type: string description: The product ID in TikTok Shop. commission_model: type: string description: |- The commission model selected for the SKU order. Possible values: - `Fixed commission`: The fixed commission model is selected. - `Tiered commission`: The tiered commission model is selected; see `commission_tier_setting` for any available tier settings. commission_tier_setting: type: string description: For `Tiered commission`, the creator commission rates configured by the seller, expressed as percentages in ascending threshold order and separated by ` OR `. Returns `-` when tiered commission does not apply or no tier is configured. commission_rate: type: string description: The commission rate established by the seller for creators involved in the collaboration, expressed in hundredths of a percent. For example, 1550 represents a commission rate of 15.50%. This value is returned only when the order is generated directly by the seller's creator. For affiliate partner campaign orders, see `partner_commission_rate`. partner_commission_rate: type: string description: The commission rate established by the seller to be paid to affiliate partner involved in the collaboration, expressed in hundredths of a percent. For example, 1550 represents a commission rate of 15.50%. shop_ads_commission_rate: type: string description: The commission rate for orders generated through Shop Ads, expressed in hundredths of a percent. For example, 5000 represents 50.00%. estimated_commission_base: $ref: "#/components/schemas/EstimatedCommissionBase" description: |- The estimated total sales value before deducting any refunds, used as a base for calculating commission. Formula: selling price * order quantity estimated_paid_shop_ads_commission: $ref: "#/components/schemas/SearchSellerAffiliateOrdersResponseDataOrderSkuEstimatedPaidShopAdsCommission" description: |- The estimated Shop Ads commission that a seller will pay on sales. Formula: estimated commission base * Shop Ads commission rate estimated_paid_commission: $ref: "#/components/schemas/SearchSellerAffiliateOrdersResponseDataOrderSkuEstimatedPaidCommission" description: |- The estimated commission that the seller will pay on sales. Formula: estimated commission base * commission rate. This value is returned only when the order is generated directly by the seller's creator. For affiliate partner campaign orders, see `estimated_paid_partner_commission`. estimated_paid_partner_commission: $ref: "#/components/schemas/SearchSellerAffiliateOrdersResponseDataOrderSkuEstimatedPaidPartnerCommission" description: |- The estimated commission that a seller will pay on sales to affiliate partner. Formula: estimated commission base * partner commission rate actual_commission_base: $ref: "#/components/schemas/ActualCommissionBase" description: |- The actual total sales value after deducting any refunds, used as a base for calculating commission. Formula: selling price * (order quantity - return/refund quantity) actual_paid_commission: $ref: "#/components/schemas/SearchSellerAffiliateOrdersResponseDataOrderSkuActualPaidCommission" description: |- The actual commission that the seller will pay on sales. Formula: actual commission base * commission rate. This value is returned only when the order is generated directly by the seller's creator. For affiliate partner campaign orders, see `actual_paid_partner_commission`. actual_paid_partner_commission: $ref: "#/components/schemas/SearchSellerAffiliateOrdersResponseDataOrderSkuActualPaidPartnerCommission" description: |- The actual commission that a seller will pay on sales to affiliate partner. Formula: actual commission base * partner commission rate actual_paid_shop_ads_commission: $ref: "#/components/schemas/SearchSellerAffiliateOrdersResponseDataOrderSkuActualPaidShopAdsCommission" description: |- The actual Shop Ads commission the seller will pay on sales. Formula: actual commission base * Shop Ads commission rate estimated_cofunded_creator_bonus_amount: $ref: "#/components/schemas/SearchSellerAffiliateOrdersResponseDataOrderSkuEstimatedCofundedCreatorBonusAmount" description: The portion of the estimated creator bonus that you co-fund in commission boost. actual_cofunded_creator_bonus_amount: $ref: "#/components/schemas/SearchSellerAffiliateOrdersResponseDataOrderSkuActualCofundedCreatorBonusAmount" description: The portion of the actual creator bonus that you co-fund in commission boost. refunded_quantity: type: integer format: int64 description: Deprecated. This field is not returned. Use `fully_return` to determine whether the SKU order was fully returned or refunded. deprecated: true returned_quantity: type: integer format: int64 description: Deprecated. This field is not returned. Use `fully_return` to determine whether the SKU order was fully returned or refunded. deprecated: true fully_return: type: string enum: - Yes - No x-enum-descriptions: - The full quantity was returned or refunded, so no commission is paid. - The full quantity was not returned or refunded. description: |- Indicates whether the entire SKU order was returned or refunded. Possible values: - `Yes`: The full quantity was returned or refunded, so no commission is paid. - `No`: The full quantity was not returned or refunded. is_carousel: type: boolean description: Indicates whether the SKU order is attributed to carousel content. Carousel content may involve a commission rate discount. Returns `true` for a carousel-attributed SKU order and `false` otherwise. SearchSellerAffiliateOrdersResponseDataOrderSkuActualCofundedCreatorBonusAmount: type: object properties: amount: type: string description: The commission amount. currency: type: string description: The commission currency. SearchSellerAffiliateOrdersResponseDataOrderSkuActualPaidCommission: type: object properties: amount: type: string description: The commission amount. currency: type: string description: The commission currency. SearchSellerAffiliateOrdersResponseDataOrderSkuActualPaidPartnerCommission: type: object properties: amount: type: string description: The commission amount. currency: type: string description: The commission currency. SearchSellerAffiliateOrdersResponseDataOrderSkuActualPaidShopAdsCommission: type: object properties: amount: type: string description: The commission amount. currency: type: string description: The commission currency. SearchSellerAffiliateOrdersResponseDataOrderSkuEstimatedCofundedCreatorBonusAmount: type: object properties: amount: type: string description: The commission amount. currency: type: string description: The commission currency. SearchSellerAffiliateOrdersResponseDataOrderSkuEstimatedPaidCommission: type: object properties: amount: type: string description: The commission amount. currency: type: string description: The commission currency. SearchSellerAffiliateOrdersResponseDataOrderSkuEstimatedPaidPartnerCommission: type: object properties: amount: type: string description: The commission amount. currency: type: string description: The commission currency. SearchSellerAffiliateOrdersResponseDataOrderSkuEstimatedPaidShopAdsCommission: type: object properties: amount: type: string description: The commission amount. currency: type: string description: The commission currency. SearchSessionsRequest: type: object properties: begin_time_ge: type: integer format: int64 description: Return sessions whose begin_time is greater than or equal to this Unix timestamp, in seconds. Only data from the last 90 days is supported. begin_time_lt: type: integer format: int64 description: Return sessions whose begin_time is less than this Unix timestamp, in seconds. The value must be greater than or equal to begin_time_ge. buyer_nickname: type: string description: Filter sessions by the buyer's nickname. required: - begin_time_ge - begin_time_lt SearchSessionsResponse: 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/SearchSessionsResponseData" SearchSessionsResponseData: type: object properties: next_page_token: type: string description: If there is no more record, this field will be ""(empty string). sessions: type: array items: $ref: "#/components/schemas/SearchSessionsResponseDataSession" description: Customer service sessions that match the request filters. SearchSessionsResponseDataSession: type: object properties: id: type: string description: Session id. conversation_id: type: string description: Conversation id. begin_time: type: integer format: int64 description: The Unix timestamp, in seconds, when the session began. end_time: type: integer format: int64 description: The timestamp when the session end. buyer_nickname: type: string description: Buyer's nickname. chat_tags: type: array items: type: string description: AfterSale/Logistics/Presale satisfaction_score: type: integer format: int64 description: Customer satisfaction rating for the session (e.g., 1–5). Higher scores indicate greater satisfaction. dissatisfaction_reason: type: string description: |- Reason provided by the buyer for a low satisfaction rating. The language of the reason is determined by the locale request parameter. first_response_late: type: boolean description: Indicates whether the first response exceeded the expected response time or SLA. first_response_time: type: integer format: int64 description: Time elapsed in seconds between when the buyer sends the first message and when the seller sends the first response. SearchSizeChartsRequest: type: object properties: ids: type: array items: type: string description: |- Filter size charts by size chart template IDs. Max: 50 IDs keyword: type: string description: |- Filter size charts by size chart template name or by key words in the template name. Keyword searches do not return PRODUCT_SCOPED size charts because they do not have a template name. If both ids and keyword are provided, ids takes priority. size_chart_mode: type: string enum: - REUSABLE_TEMPLATE - PRODUCT_SCOPED x-enum-descriptions: - A size chart template that can be reused across multiple products. - A size chart created for and used by a single product. If omitted, the existing search behavior is preserved. description: "Filter size charts by usage mode. Possible values: REUSABLE_TEMPLATE: A size chart template that can be reused across multiple products. PRODUCT_SCOPED: A size chart created for and used by a single product. If omitted, the existing search behavior is preserved." SearchSizeChartsResponse: 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/SearchSizeChartsResponseData" SearchSizeChartsResponseData: type: object properties: size_chart: type: array items: $ref: "#/components/schemas/SearchSizeChartsResponseDataSizeChart" description: The list of size charts that meet the query conditions. next_page_token: type: string description: An opaque token used to retrieve the next page of a paginated result set. If this value is non-empty, pass it in the `page_token` parameter of the next request. An empty value means there are no more results. total_count: type: integer format: int64 description: The number of size charts that meet the query conditions. SearchSizeChartsResponseDataSizeChart: type: object properties: template_id: type: string description: The size chart template ID. template_name: type: string description: The size chart template name. images: type: array items: $ref: "#/components/schemas/SearchSizeChartsResponseDataSizeChartImage" description: The list of images included in a size chart. related_category_ids: type: array items: type: string description: Leaf category IDs applicable to this size chart. size_chart_datas: type: array items: $ref: "#/components/schemas/SearchSizeChartsResponseDataSizeChartSizeChartData" description: Localized structured size chart data. Each item contains a locale and the structured data for that locale. size_chart_mode: type: string enum: - REUSABLE_TEMPLATE - PRODUCT_SCOPED x-enum-descriptions: - A size chart template that can be reused across multiple products. - A size chart created for and used by a single product. If omitted, the existing search behavior is preserved. description: "Filter size charts by usage mode. Possible values: REUSABLE_TEMPLATE: A size chart template that can be reused across multiple products. PRODUCT_SCOPED: A size chart created for and used by a single product. If omitted, the existing search behavior is preserved." SearchSizeChartsResponseDataSizeChartImage: type: object properties: uri: type: string description: The URI to identify the image in API requests and responses. url: type: string description: The URL to access and view the image. locale: type: string description: The language of the size chart image. SearchSizeChartsResponseDataSizeChartSizeChartData: type: object properties: locale: type: string description: The language of the size chart table. size_chart_data: $ref: "#/components/schemas/SearchSizeChartsResponseDataSizeChartSizeChartDataSizeChartData" description: Structured size chart data for the specified locale. SearchSizeChartsResponseDataSizeChartSizeChartDataSizeChartData: type: object properties: table: $ref: "#/components/schemas/SearchSizeChartsResponseDataSizeChartSizeChartDataSizeChartDataTable" description: Structured table containing headers and rows. description: type: string description: Additional size chart description. is_one_size: type: boolean description: Whether this is a one-size chart. measurement_type: type: string enum: - GENERIC_MEASUREMENTS - BODY_MEASUREMENTS - PRODUCT_MEASUREMENTS x-enum-descriptions: - generic measurements - shopper body measurements - finished-product measurements. description: "Possible values: GENERIC_MEASUREMENTS: generic measurements; BODY_MEASUREMENTS: shopper body measurements; PRODUCT_MEASUREMENTS: finished-product measurements." unit_system: type: string enum: - METRIC - IMPERIAL x-enum-descriptions: - metric units - imperial units. description: "Possible values: METRIC: metric units; IMPERIAL: imperial units." size_types: type: array items: type: string description: "Possible values include: size_chart_common_size_type: Common; size_chart_size_type_regular: Regular; size_chart_size_type_juniors: Juniors; size_chart_size_type_plus: Plus; size_chart_size_type_big&tall: Big & Tall; size_chart_size_type_petite: Petite. Available values depend on the category." SearchSizeChartsResponseDataSizeChartSizeChartDataSizeChartDataTable: type: object properties: headers: type: array items: $ref: "#/components/schemas/SearchSizeChartsResponseDataSizeChartSizeChartDataSizeChartDataTableHeader" description: Ordered header definitions. rows: type: array items: $ref: "#/components/schemas/SearchSizeChartsResponseDataSizeChartSizeChartDataSizeChartDataTableRow" description: Rows of the size chart. SearchSizeChartsResponseDataSizeChartSizeChartDataSizeChartDataTableHeader: type: object properties: name: type: string description: Header display name. id: type: string description: Standard size-system ID or measurement key. SearchSizeChartsResponseDataSizeChartSizeChartDataSizeChartDataTableRow: type: object properties: cells: type: array items: $ref: "#/components/schemas/SearchSizeChartsResponseDataSizeChartSizeChartDataSizeChartDataTableRowCell" description: Cells aligned by index with table.headers. SearchSizeChartsResponseDataSizeChartSizeChartDataSizeChartDataTableRowCell: type: object properties: value: type: string description: Cell value. SearchTAPAffiliateOrdersRequest: type: object properties: create_time_ge: type: integer format: int64 description: |- Filter orders created at or after this time, specified as a Unix timestamp in seconds (UTC). `create_time_ge` and `create_time_lt` must be provided together, and the interval must not exceed three months. If both fields are omitted, the API queries orders from the last three months. create_time_lt: type: integer format: int64 description: Filter orders created before this time, specified as a Unix timestamp in seconds (UTC). See `create_time_ge` for the pairing, interval, and default behavior. campaign_id: type: string description: Filter orders by a TAP campaign using its identifier. SearchTAPAffiliateOrdersResponse: 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/SearchTAPAffiliateOrdersResponseData" SearchTAPAffiliateOrdersResponseData: type: object properties: sku_orders: type: array items: $ref: "#/components/schemas/SearchTAPAffiliateOrdersResponseDataSkuOrder" description: SKU-level affiliate order records. Estimated commission amount fields are populated when the corresponding estimated component is available. Actual commission amount fields are populated only for `SETTLED` or `INELIGIBLE` orders and are omitted before those states; an individual actual amount can still be omitted when its underlying component is unavailable. next_page_token: type: string description: Pass this pagination token as `page_token` in the next request. Reuse the same `campaign_id` (if specified), `create_time_ge`, and `create_time_lt` values for every page; specify both time bounds in the first request to keep the search window fixed. Stop paginating when this field is omitted. total_count: type: integer format: int64 description: The total number of SKU orders matching the request filters across all pages. SearchTAPAffiliateOrdersResponseDataSkuOrder: type: object properties: id: type: string description: Transaction main order ID create_time: type: integer format: int64 description: The order creation time as a Unix timestamp in seconds (UTC). delivery_time: type: integer format: int64 description: The order delivery time as a Unix timestamp in seconds (UTC). settle_status: type: string description: |- Settlement Status of the order. Possible values: 1. "CUSTOMER UNPAID", customer hasn't paid for the orders. 2. "PENDING", customers can still return or get a refund for this order. The earnings shown are estimates and waiting for settlement. 3. "SETTLED", your earnings have already settled to your account 4. "INELIGIBLE", The order has been returned/refunded/canceled by the buyer, and no commission will be settled. 5. "FROZEN", Possible fraud has been detected regarding the order. The commission will be unfrozen after the fraud is resolved. sku_id: type: string description: sku ID campaign_id: type: string description: The identifier of the TAP campaign associated with the order. creator_username: type: string description: Creator username product_name: type: string description: The product name. product_id: type: string description: Unique identifier for Product price: $ref: "#/components/schemas/Price" description: Price quantity: type: integer format: int64 description: Number of SKU items in the order, including refunded items. content_type: type: string enum: - SHOP - VIDEO - LIVE - PRE_LIVE - PROMOTION_PAGE - LINKSHARE description: |- The content format of the creator content through which the order was created. Possible values: - SHOP - VIDEO - LIVE - PRE_LIVE - PROMOTION_PAGE - LINKSHARE content_id: type: string description: Unique identifier for content creator_standard_commission_rate: type: integer format: int64 description: The creator standard commission rate, scaled by 10,000. For example, `3000` represents 30%. partner_standard_commission_rate: type: integer format: int64 description: The affiliate partner's standard commission rate, scaled by 10,000. For example, `4000` represents 40%. creator_shop_ads_commission_rate: type: integer format: int64 description: The creator Shop Ads commission rate, scaled by 10,000. For example, `3000` represents 30%. partner_shop_ads_commission_rate: type: integer format: int64 description: The affiliate partner's Shop Ads commission rate, scaled by 10,000. For example, `4000` represents 40%. partner_tap_bonus_commission_rate: type: integer format: int64 description: The additional commission rate TikTok Shop offers to affiliate partners for driving product sales in specific campaigns, scaled by 10,000. For example, `1000` represents 10%. creator_tap_bonus_commission_rate: type: integer format: int64 description: The commission reward rate allocated by the affiliate partner to the creator, scaled by 10,000. For example, `2000` represents 20%. estimated_commission_base: $ref: "#/components/schemas/EstimatedCommissionBase" description: The estimated commission base is the item price multiplied by the number of items ordered at the time the order is created. estimated_creator_standard_commission: $ref: "#/components/schemas/SearchTAPAffiliateOrdersResponseDataSkuOrderEstimatedCreatorStandardCommission" description: Estimated TAP commission x creator commission rate estimated_partner_standard_commission: $ref: "#/components/schemas/SearchTAPAffiliateOrdersResponseDataSkuOrderEstimatedPartnerStandardCommission" description: Estimated commission base x TAP commission rate estimated_creator_shop_ads_commission: $ref: "#/components/schemas/SearchTAPAffiliateOrdersResponseDataSkuOrderEstimatedCreatorShopAdsCommission" description: Estimated commission base x creator shop ads commission rate estimated_partner_shop_ads_commission: $ref: "#/components/schemas/SearchTAPAffiliateOrdersResponseDataSkuOrderEstimatedPartnerShopAdsCommission" description: Estimated commission base x partner shop ads commission rate estimated_partner_tap_bonus_commission: $ref: "#/components/schemas/SearchTAPAffiliateOrdersResponseDataSkuOrderEstimatedPartnerTapBonusCommission" description: Estimated partner commission reward fee estimated_creator_tap_bonus_commission: $ref: "#/components/schemas/SearchTAPAffiliateOrdersResponseDataSkuOrderEstimatedCreatorTapBonusCommission" description: Estimated creator commission reward fee estimated_partner_isr: $ref: "#/components/schemas/SearchTAPAffiliateOrdersResponseDataSkuOrderEstimatedPartnerIsr" description: Estimated ISR tax amount for Mexico partner estimated_partner_iva: $ref: "#/components/schemas/SearchTAPAffiliateOrdersResponseDataSkuOrderEstimatedPartnerIva" description: Estimated IVA tax amount for Mexico partner actual_commission_base: $ref: "#/components/schemas/ActualCommissionBase" description: The actual commission base is the item price multiplied by the number of items ordered minus returns at the time the order is completed. actual_creator_standard_commission: $ref: "#/components/schemas/SearchTAPAffiliateOrdersResponseDataSkuOrderActualCreatorStandardCommission" description: Actual TAP commission x creator commission rate actual_partner_standard_commission: $ref: "#/components/schemas/SearchTAPAffiliateOrdersResponseDataSkuOrderActualPartnerStandardCommission" description: Actual commission base x TAP commission rate actual_creator_shop_ads_commission: $ref: "#/components/schemas/SearchTAPAffiliateOrdersResponseDataSkuOrderActualCreatorShopAdsCommission" description: actual commission base x creator shop ads commission rate actual_partner_shop_ads_commission: $ref: "#/components/schemas/SearchTAPAffiliateOrdersResponseDataSkuOrderActualPartnerShopAdsCommission" description: actual commission base x partner shop ads commission rate actual_partner_isr: $ref: "#/components/schemas/SearchTAPAffiliateOrdersResponseDataSkuOrderActualPartnerIsr" description: Actual ISR tax amount for Mexico partner actual_partner_iva: $ref: "#/components/schemas/SearchTAPAffiliateOrdersResponseDataSkuOrderActualPartnerIva" description: actual IVA tax amount for Mexico partner actual_partner_tap_bonus_commission: $ref: "#/components/schemas/SearchTAPAffiliateOrdersResponseDataSkuOrderActualPartnerTapBonusCommission" description: Actual partner commission reward fee actual_creator_tap_bonus_commission: $ref: "#/components/schemas/SearchTAPAffiliateOrdersResponseDataSkuOrderActualCreatorTapBonusCommission" description: Actual creator commission reward fee fully_return: type: string enum: - Yes - No x-enum-descriptions: - The SKU was fully returned or refunded, and no commission is paid. - The SKU was not fully returned or refunded. description: |- Whether the SKU was fully returned or refunded. Possible values: - `Yes`: The SKU was fully returned or refunded, and no commission is paid. - `No`: The SKU was not fully returned or refunded. settlement_time: type: integer format: int64 description: The time when the order commission was settled, as a Unix timestamp in seconds (UTC). last_update_time: type: integer format: int64 description: The time when the record was last updated, as a Unix timestamp in seconds (UTC). is_carousel: type: boolean description: Carousel content may involve a commission rate discount. Returns true when the order is attributed to carousel content. SearchTAPAffiliateOrdersResponseDataSkuOrderActualCreatorShopAdsCommission: type: object properties: amount: type: string description: The actual creator Shop Ads commission amount without a currency symbol. Use `currency` to identify the currency. currency: type: string description: Type of currency use SearchTAPAffiliateOrdersResponseDataSkuOrderActualCreatorStandardCommission: type: object properties: amount: type: string description: The actual creator standard commission amount without a currency symbol. Use `currency` to identify the currency. currency: type: string description: Type of currency use SearchTAPAffiliateOrdersResponseDataSkuOrderActualCreatorTapBonusCommission: type: object properties: amount: type: string description: The actual fee creators receive from affiliate partners through commission rewards currency: type: string description: Type of currency use SearchTAPAffiliateOrdersResponseDataSkuOrderActualPartnerIsr: type: object properties: amount: type: string description: The actual ISR tax amount without a currency symbol. Use `currency` to identify the currency. currency: type: string description: Type of currency use SearchTAPAffiliateOrdersResponseDataSkuOrderActualPartnerIva: type: object properties: amount: type: string description: The actual IVA tax amount without a currency symbol. Use `currency` to identify the currency. currency: type: string description: Type of currency use SearchTAPAffiliateOrdersResponseDataSkuOrderActualPartnerShopAdsCommission: type: object properties: amount: type: string description: The actual affiliate partner Shop Ads commission amount without a currency symbol. Use `currency` to identify the currency. currency: type: string description: Type of currency use SearchTAPAffiliateOrdersResponseDataSkuOrderActualPartnerStandardCommission: type: object properties: amount: type: string description: The actual affiliate partner standard commission amount without a currency symbol. Use `currency` to identify the currency. currency: type: string description: Type of currency use SearchTAPAffiliateOrdersResponseDataSkuOrderActualPartnerTapBonusCommission: type: object properties: amount: type: string description: The actual fee affiliate partners earn from commission rewards currency: type: string description: Type of currency use SearchTAPAffiliateOrdersResponseDataSkuOrderEstimatedCreatorShopAdsCommission: type: object properties: amount: type: string description: The estimated creator Shop Ads commission amount without a currency symbol. Use `currency` to identify the currency. currency: type: string description: Type of currency use SearchTAPAffiliateOrdersResponseDataSkuOrderEstimatedCreatorStandardCommission: type: object properties: amount: type: string description: The estimated creator standard commission amount without a currency symbol. Use `currency` to identify the currency. currency: type: string description: Type of currency use SearchTAPAffiliateOrdersResponseDataSkuOrderEstimatedCreatorTapBonusCommission: type: object properties: amount: type: string description: The estimated creator commission reward amount without a currency symbol. Use `currency` to identify the currency. currency: type: string description: Type of currency use SearchTAPAffiliateOrdersResponseDataSkuOrderEstimatedPartnerIsr: type: object properties: amount: type: string description: The estimated ISR tax amount without a currency symbol. Use `currency` to identify the currency. currency: type: string description: Type of currency use SearchTAPAffiliateOrdersResponseDataSkuOrderEstimatedPartnerIva: type: object properties: amount: type: string description: The estimated IVA tax amount without a currency symbol. Use `currency` to identify the currency. currency: type: string description: Type of currency use SearchTAPAffiliateOrdersResponseDataSkuOrderEstimatedPartnerShopAdsCommission: type: object properties: amount: type: string description: The estimated affiliate partner Shop Ads commission amount without a currency symbol. Use `currency` to identify the currency. currency: type: string description: Type of currency use SearchTAPAffiliateOrdersResponseDataSkuOrderEstimatedPartnerStandardCommission: type: object properties: amount: type: string description: The estimated affiliate partner standard commission amount without a currency symbol. Use `currency` to identify the currency. currency: type: string description: Type of currency use SearchTAPAffiliateOrdersResponseDataSkuOrderEstimatedPartnerTapBonusCommission: type: object properties: amount: type: string description: The estimated affiliate partner commission reward amount without a currency symbol. Use `currency` to identify the currency. currency: type: string description: Type of currency use SearchTargetCollaborationsRequest: type: object properties: creator_accept_status: type: string enum: - ACCEPT - ALL x-enum-descriptions: - The creators have added the products to their showcases. - Do not filter by whether the creators have added the products to their showcases. description: |- Filter target collaborations by the acceptance status of invited creators. Allowed values: - ACCEPT: The creators have added the products to their showcases. - ALL: Do not filter by whether the creators have added the products to their showcases. Default: ALL. free_sample_setting: type: string description: |- Filtering by target collaborations' free sample setting. You can query based on: - "WITH_FREE_SAMPLE" - "ALL" By default, the target collaborations will be searched by "ALL" setting. search_param: $ref: "#/components/schemas/SearchTargetCollaborationsRequestSearchParam" description: Search criteria for target collaborations. When this object is provided, provide both keyword_type and keyword. creator_user_open_id: type: string description: The creator's TikTok User Open ID. Provide this field to filter target collaborations for the specified creator. [More details](https://partner.tiktokshop.com/docv2/page/3obfokj6) collaboration_status: type: string description: |- Filtering by target collaborations' status. You can query based on: - ONGOING: If you use ONGOING to search, the remaining validity period of the returned target collaborations will be greater than 7 days. - EXPIRING: If you use EXPIRING to search, the remaining validity period of the returned target collaborations will be less than 7 days. - VALID: If you use VALID to search, all returned target collaborations will be valid. - CANCELING: If you use CANCELING to search, all returned target collaborations will be in the process of canceling. - COMPLETED: If you use COMPLETED to search, all returned target collaborations will be in the state of completed, including expired and canceled. required: - collaboration_status SearchTargetCollaborationsRequestSearchParam: type: object properties: keyword_type: type: string enum: - PRODUCT_ID - PRODUCT_NAME - TARGET_COLLABORATION_ID - TARGET_COLLABORATION_NAME x-enum-descriptions: - Search for a specific product ID. - Fuzzy-search by product name. - Search for a specific target collaboration ID. - Fuzzy-search by target collaboration name. description: |- Type of value provided in keyword. Possible values: - PRODUCT_ID: Search for a specific product ID. - PRODUCT_NAME: Fuzzy-search by product name. - TARGET_COLLABORATION_ID: Search for a specific target collaboration ID. - TARGET_COLLABORATION_NAME: Fuzzy-search by target collaboration name. keyword: type: string description: The value to search for, interpreted according to keyword_type. required: - keyword_type - keyword SearchTargetCollaborationsResponse: 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/SearchTargetCollaborationsResponseData" SearchTargetCollaborationsResponseData: type: object properties: total_count: type: integer format: int64 description: Total number of target collaborations that match the request across all pages. next_page_token: type: string description: Cursor for the next page request. target_collaborations: type: array items: $ref: "#/components/schemas/SearchTargetCollaborationsResponseDataTargetCollaboration" description: The basic information of target collaboration which creators can view in Targeted Invitation on TikTok EC Center. SearchTargetCollaborationsResponseDataTargetCollaboration: type: object properties: id: type: string description: Target collaboration ID. name: type: string description: Target collaboration name. message: type: string description: Message seller has sent to creators about seller's introduction and why excited to collaborate. start_time: type: integer format: int64 description: Unix timestamp, in seconds, when the target collaboration starts. end_time: type: integer format: int64 description: Unix timestamp, in seconds, when the target collaboration ends. create_time: type: integer format: int64 description: Unix timestamp, in seconds, when the target collaboration was created. update_time: type: integer format: int64 description: Unix timestamp, in seconds, when the target collaboration was last updated. creator_inivited_count: type: integer format: int64 description: The count of creators invited in the target collaboration. showcase_creator_count: type: integer format: int64 description: The number of creators in the target collaboration who added at least one of its products to their showcase. content_creator_count: type: integer format: int64 description: The number of creators who posted content featuring products from target collaboration. product_count: type: integer format: int64 description: The count of products added in the target collaboration. free_sample_rule: $ref: "#/components/schemas/QueryTargetCollaborationDetailResponseDataTargetCollaborationFreeSampleRule" description: The free sample rules set by the seller in the target collaboration. type: type: string description: |- The type of target collaboration. Field values: - STANDARD: The target collaboration is created by sellers manually selecting products and creators. - TOP_CREATOR_PROGRAM: The target collaboration created by seller joining TikTok Shop Top Creator Program, requiring only product submission. SelfShipment: type: object properties: tracking_number: type: string description: For packages with the `SEND_BY_SELLER` delivery option type (seller shipping), you must provide the package's tracking number. shipping_provider_id: type: string description: For packages with the `SEND_BY_SELLER` delivery option type (seller shipping), you must provide the shipping provider information. Please use the [Get Shipping Providers](https://partner.tiktokshop.com/docv2/page/650aa48d4a0bb702c06d85cd?external_id=650aa48d4a0bb702c06d85cd#Back%20To%20Top) API to obtain the `shipping_provider_id`. required: - tracking_number - shipping_provider_id SellerContactInfo: type: object properties: email: type: string description: The seller's email address. phone_number: type: string description: The phone number of the seller. whatsapp: type: string description: The phone number used by the seller to register for WhatsApp. telegram: type: string description: The seller's Telegram username or phone number. line: type: string description: The phone number used by the seller to register for the Line app. SellerDeauthorizationWebhook: type: object properties: type: type: integer const: 6 description: The ID of the webhook type. shop_id: type: string description: The identification of the shop timestamp: type: integer format: int64 description: The time when the notification is pushed, represented as a Unix timestamp (seconds). tts_notification_id: type: string description: The ID of the notification. data: $ref: "#/components/schemas/SellerDeauthorizationWebhookData" description: The object contains business parameters related to the specific notification type required: - type SellerDeauthorizationWebhookData: type: object properties: message: type: string SellerGetSampleRequestDeeplinkResponse: 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/SellerGetSampleRequestDeeplinkResponseData" SellerGetSampleRequestDeeplinkResponseData: type: object properties: deeplink: type: string description: "Use this deeplink to invoke TikTok:" SellerNextActionResponse: type: object properties: action: type: string enum: - SELLER_RESPOND_REFUND - SELLER_RESPOND_RETURN - SELLER_RESPOND_RECEIVE_PACKAGE - SELLER_RESPOND_REPLACEMENT description: |- Seller's next action. Available values: - `SELLER_RESPOND_REFUND` - `SELLER_RESPOND_RETURN` - `SELLER_RESPOND_RECEIVE_PACKAGE` - `SELLER_RESPOND_REPLACEMENT` deadline: type: integer format: int64 description: The deadline for the seller to perform the specified action, as a Unix timestamp in seconds. SellerSearchOpenCollaborationProductsRequest: type: object properties: title_keywords: type: array items: type: string description: A list of product keywords. Product titles, or names, are loosely matched. Keywords in the list form a query and the resulting set of matching product names is based on the conjunctive operator `AND` between each keyword. For example, the keyword list `["Men", "Fashion"]` creates a query `"Men" AND "Fashion"` and the resulting set of matching product names contains the loosely matched conjuction of "Men" and "Fashion" such as "Male Fashionable". Maximum length of the list is 20 keywords. Maximum keyword string length is 255 characters. sales_price_range: $ref: "#/components/schemas/SalesPriceRange" description: Restricts the products in the search results to those with prices greater than or equal to the expressed minimum price and less than the expressed maximum price category: $ref: "#/components/schemas/Category" description: Restricts the products in the search results to those that are associated with the expressed product category. commission_rate_range: $ref: "#/components/schemas/SellerSearchOpenCollaborationProductsRequestCommissionRateRange" description: Filters products by the commission rate range specified by `rate_ge` and `rate_lt`. SellerSearchOpenCollaborationProductsRequestCommissionRateRange: type: object properties: rate_ge: type: integer format: int64 minimum: 100 maximum: 8000 description: "Products with a commission rate greater than or equal to this value are included in the search results. The rate is expressed in hundredths of a percent; for example, `3587` means `35.87%`. Valid range: [100, 8000]." rate_lt: type: integer format: int64 description: The commission rate must be less than this value in order to be included in the search results. The commission rate is expressed in hundredths of a percent. For example, `3587` is a commission rate of `35.87%`. This value must a minimum of `100`. SellerSearchOpenCollaborationProductsResponse: 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/SellerSearchOpenCollaborationProductsResponseData" SellerSearchOpenCollaborationProductsResponseData: type: object properties: products: type: array items: $ref: "#/components/schemas/SearchOpenCollaborationProductsResponseDataProduct" description: The list of products meeting the search criteria expressed in the request body. next_page_token: type: string description: An opaque token used to retrieve the next page of a paginated result set. If this value is non-empty, pass it as page_token in the next request and keep shop_cipher, page_size, sort_field, sort_order, and the request body unchanged. An empty value means that there are no more pages. total_count: type: integer format: int64 description: Total count of products meeting the search criteria expressed in the request body. SendEngagementMessageRequest: type: object properties: buyer_emails: type: array items: type: string description: |- The anonymized email addresses of the buyers. Retrieve these values from the [Get Order Details API](650aa8ccc16ffe02b8f167a0). Provide 1 to 50 addresses per request. **Note**: You can only send messages to buyers who have placed at least one order with the shop in the past 365 days. task_id: type: string description: |- The ID of the associated customer engagement task. Use the value returned when you call the [Create Engagement Task API](67777e436b61b002f60f01da). **Note**: Ensure the task is still active. You cannot send messages to tasks that have ended. required: - buyer_emails SendEngagementMessageResponse: 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/SendEngagementMessageResponseData" SendEngagementMessageResponseData: type: object properties: errors: type: array items: $ref: "#/components/schemas/SendEngagementMessageResponseDataError" description: The list of per-buyer validation or eligibility errors. SendEngagementMessageResponseDataError: type: object properties: code: type: integer format: int64 description: The error code. message: type: string description: The error message. detail: $ref: "#/components/schemas/SendEngagementMessageResponseDataErrorDetail" description: The details of the error. SendEngagementMessageResponseDataErrorDetail: type: object properties: buyer_email: type: string description: The anonymized buyer email address associated with the error. SendIMMessageRequest: type: object properties: msg_type: type: string enum: - TEXT - PRODUCT_CARD - TARGET_COLLABORATION_CARD - FREE_SAMPLE_CARD - IMAGE - CRM_TEXT_WITH_IMAGE_CARD - CRM_TEXT_WITH_PRODUCTS_CARD description: |- Message type. The value determines the decoded JSON object required in `content`. Possible values: - `TEXT` - `PRODUCT_CARD` - `TARGET_COLLABORATION_CARD` - `FREE_SAMPLE_CARD` - `IMAGE` - `CRM_TEXT_WITH_IMAGE_CARD` - `CRM_TEXT_WITH_PRODUCTS_CARD` content: type: string description: |- Message content as a JSON-serialized string. The decoded JSON object depends on `msg_type`: - `TEXT`: `{"content": "simple text"}`. `content` is required, must not be empty, and supports up to 2,000 Unicode characters. - `PRODUCT_CARD`: `{"product_id": "12345"}`. `product_id` is required. - `TARGET_COLLABORATION_CARD`: `{"target_collaboration_id": "1234"}`. `target_collaboration_id` is required and is the invitation group ID. - `FREE_SAMPLE_CARD`: `{"apply_id": "1234"}`. `apply_id` is required. - `IMAGE`: `{"url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/2ca53c34ad8443e6b39f4e0153d3aed4~tplv-o3syd03w52-origin-image.image?from=1320446476", "width": 1280, "height": 720}`. `url`, `width`, and `height` are required; `width` and `height` must be integers. You can obtain `url` by calling [Upload Messages Image](https://partner.tiktokshop.com/docv2/page/upload-message-image-v2-202608). - `CRM_TEXT_WITH_PRODUCTS_CARD`: `{"product_ids": "12345,123456", "title": "abc", "content": "abc"}`. `product_ids` is required and contains one to five comma-separated positive product IDs. `content` is required, must not be empty, and supports up to 500 Unicode characters. `title` supports up to 50 Unicode characters. - `CRM_TEXT_WITH_IMAGE_CARD`: `{"image_url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/2ca53c34ad8443e6b39f4e0153d3aed4~tplv-o3syd03w52-origin-image.image?from=1320446476", "title": "abc", "content": "abc"}`. `image_url` and `content` are required. `content` must not be empty and supports up to 500 Unicode characters. `title` supports up to 50 Unicode characters. required: - msg_type - content SendIMMessageResponse: 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/SendIMMessageResponseData" SendIMMessageResponseData: type: object properties: message_id: type: string description: The message ID. The `message_id` field is not always returned upon successful message submission. SendMessageRequest: type: object properties: type: type: string enum: - TEXT - IMAGE - VIDEO - PRODUCT_CARD - ORDER_CARD - RETURN_REFUND_CARD - COUPON_CARD - LOGISTICS_CARD description: |- Message type. Possible enumerations: - `TEXT` - `IMAGE` - `VIDEO` - `PRODUCT_CARD` - `ORDER_CARD` - `RETURN_REFUND_CARD` - `COUPON_CARD` - `LOGISTICS_CARD` content: type: string description: |- Message content, in JSON serialized string. Examples of content for each type of message are listed below: ​ - TEXT: { "content": "hi, I want to get refunded." } (Note: Max 2000 characters. Do not use sensitive words that violate TikTok Shop terms & policies.) - VIDEO { "vid": "v10394g5000cd499vc7og65mqn3r3dg0" } - LOGISTICS_CARD { "order_id": "580874485811283206", "package_id": "123456" // Optional (recommended for one order with multiple packages; not required for one order with one package) } ​ - PRODUCT_CARD { "product_id": "7494560109732334265" } ​ - ORDER_CARD: { "order_id": "7494560109732334267" } - RETURN_REFUND_CARD: { "order_id": "7494560109732334267", "sku_id": "7494560109732363423" } Note: The order of the RETURN_REFUND_CARD to send must meet after-sale conditions. To check the eligibility, use [Get Aftersale Eligibility](650ab645c16ffe02b8f2e1c1). ​ - IMAGE: { "url":"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/2ca53c34ad8443e6b39f4e0153d3aed4~tplv-o3syd03w52-origin-image.image?from=1320446476", "width": 1280, "height": 720 } Note: You can get the value of `url` by calling [Upload Buyer Messages Image](650a599d0fcef602bf2a1dc8). - COUPON_CARD: { "coupon_id": "7262992004278206762" } Note: Coupons that can be sent in a message must meet all the following conditions: 1. `display_type==CHAT` or `display_type==REGULAR` 2. `status==ONGOING` 3. `creation_source==SELLER_CENTER` 4. `target_buyer_segment!=REPEAT_CUSTOMERS` sender_role: type: string description: |- Message sending role. - 'CUSTOMER_SERVICE' : Messages replied by real customer service - 'SYSTEM': Replies automatically triggered by the system, such as welcome messages and timeout replies - 'ROBOT': Messages replied by intelligent robot required: - type - content SendMessageResponse: 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/SendMessageResponseData" SendMessageResponseData: type: object properties: message_id: type: string description: Message ID SeoWord: type: object properties: text: type: string description: The suggested SEO keyword text. ShelfLifeAttributeInfo: type: object properties: shelf_life: type: integer format: int64 description: The goods shelf life (days) inbound_cutoff_days: type: integer format: int64 description: The goods inbound cutoff days before expiration, represent the time period before the product's expiration when the warehouse will no longer accept inbound shipments. expiration_alert_days: type: integer format: int64 description: The goods alert days before expired, represent the period of time before platform send expiration reminder alerts to the merchant. sales_cutoff_days: type: integer format: int64 description: The goods sales cut off days before expired, represent the period of time before expiration in which the goods will no longer be available for sale. handling_method_expired_goods: type: string enum: - STORE_UNITS - RETURN_TO_SELLER - DISPOSE x-enum-descriptions: - Move the units to defective inventory. - Return the units to the seller. - Dispose of the units. description: |- How expired inventory is handled. Possible values: - `STORE_UNITS`: Move the units to defective inventory. - `RETURN_TO_SELLER`: Return the units to the seller. - `DISPOSE`: Dispose of the units. required: - inbound_cutoff_days - expiration_alert_days - sales_cutoff_days ShipInboundOrderRequest: type: object properties: inbound_order_id: type: string description: Identifier of the inbound order to ship. cartons: type: array items: $ref: "#/components/schemas/Carton" description: Carton details. Required when the inbound plan was created or updated using `goods_items` instead of `cartons` and the order has not already been shipped. Not required when retrying an order that has already been shipped. shipment_option: $ref: "#/components/schemas/ShipInboundOrderRequestShipmentOption" description: Shipment option containing freight type and shipping method. required: - inbound_order_id - shipment_option ShipInboundOrderRequestShipmentOption: type: object properties: shipping_method: type: string enum: - SMALL_PARCEL - FREIGHT x-enum-descriptions: - small parcel shipping - freight shipping . description: "Shipping method. Possible values: SMALL_PARCEL (small parcel shipping); FREIGHT (freight shipping)." freight_type: type: string enum: - FTL - LTL description: |- Freight load type. Required when `shipping_method` is `FREIGHT` for EU and UK shops. It is optional for US shops and is not required when `shipping_method` is `SMALL_PARCEL`. **Possible values:** * `FTL` * `LTL` required: - shipping_method ShipInboundOrderResponse: 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/ShipInboundOrderResponseData" ShipInboundOrderResponseData: type: object properties: inbound_order_id: type: string description: Identifier of the shipped inbound order. ShipPackageRequest: type: object properties: handover_method: type: string enum: - PICKUP - DROP_OFF x-enum-descriptions: - A logistics carrier will pick up the package(s) from the seller's pickup address. - The seller will need to drop off the package(s) to a designated location. description: |- Possible values: - `PICKUP`: A logistics carrier will pick up the package(s) from the seller's pickup address. - `DROP_OFF`: The seller will need to drop off the package(s) to a designated location. pickup_slot: $ref: "#/components/schemas/PickupSlot" description: Pickup time slot. self_shipment: $ref: "#/components/schemas/SelfShipment" description: Only needed for merchant self-shipping packages. Check the `delivery_option` field of [Get Package Detail](https://partner.tiktokshop.com/docv2/page/650aa39fbace3e02b75d8617?external_id=650aa39fbace3e02b75d8617#Back%20To%20Top) to see how to differentiate platform-logistics and self-shipping. Use the `shipping_provider_id` retrieved from [Get Shipping Providers](https://partner.tiktokshop.com/docv2/page/650aa48d4a0bb702c06d85cd?external_id=650aa48d4a0bb702c06d85cd) and upload the corresponding `tracking_number`. ShipPackageResponse: 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/ShipPackageResponseData" ShipPackageResponseData: type: object properties: {} ShippingDiscount: type: object properties: threshold_type: type: string enum: - NO_THRESHOLD - MINIMAL_ITEM_QUANTITY - MINIMAL_ORDER_AMOUNT x-enum-descriptions: - No minimum purchase criteria. - Buyer must meet or exceed the minimum spend criteria with eligible products. - Buyer must meet or exceed the minimum spend criteria with eligible order. description: |- The type of purchase criteria. Possible enumerations are: - `NO_THRESHOLD`: No minimum purchase criteria. - `MINIMAL_ITEM_QUANTITY`: Buyer must meet or exceed the minimum spend criteria with eligible products. - `MINIMAL_ORDER_AMOUNT`: Buyer must meet or exceed the minimum spend criteria with eligible order. `MINIMAL_ITEM_QUANTITY` and `MINIMAL_ORDER_AMOUNT` can only be set when `product_level==SHOP`. threshold_value: type: string description: |- The purchase threshold of the discount, based on `threshold_type`, for example, `3`. Determined by the user. - When `threshold_type==NO_THRESHOLD`, this value is not required. - When `threshold_type==MINIMAL_ITEM_QUANTITY`, the buyer must purchase at least the specified number of eligible products (for example, 3 eligible products). If it represents a quantity, it must be an integer. - When `threshold_type==MINIMAL_ORDER_AMOUNT`, the eligible-product subtotal must meet or exceed the specified value in local currency (for example, 3 units of local currency). If it represents an order value, it must be limited to two decimal places. type: type: string description: |- The shipping benefit type. - `FREE_SHIPPING`: Reduce the buyer's shipping fee to zero. - `DISCOUNT_SHIPPING_FEE`: Reduce the buyer's shipping fee by up to the amount specified in `shipping_discount.value`. value: type: string description: |- The shipping discount value determined by `type`. - When `type==FREE_SHIPPING`, omit this value. - When `type==DISCOUNT_SHIPPING_FEE`, enter the maximum amount deducted from the buyer's shipping fee in local currency, with at most two decimal places. shipping_method: type: string description: |- The shipping methods to which this promotion applies. - When `STANDARD_SHIPPING`: Only applies to Standard Shipping methods, including Economy. - `EXPRESS_SHIPPING`: Only applies to Express Shipping methods. - `ALL_SHIPPING_METHOD`: Applies to all shipping methods that the shop offers. Default: `STANDARD_SHIPPING` inventory_type: type: string description: |- The inventory types to which the promotion activity applies: - `SELF_FULFILLED`: Only applies to Inventory fulfilled from seller warehouses - `FULFILLED_BY_TIKTOK`: Only applies to Inventory fulfilled by TikTok from FBT (Fulfilled by TikTok) warehouses. - `ALL`: Applies to all inventory of eligible products. Default: `SELF_FULFILLED` `FULFILLED_BY_TIKTOK` and `ALL` can only be set when `product_level`==`SHOP` and `threshold_type=NO_THRESHOLD`. area_scope: $ref: "#/components/schemas/AreaScope" description: The (buyer's) geographical areas to which the promotion activity applies. required: - threshold_type - type - area_scope ShippingFee: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). ShippingInfoList: type: object properties: tracking_number: type: string description: Tracking number.​ shipping_provider_id: type: string description: Use Get Shipping Provider API to retrieve the shipping_provider_id for shipping providers.​ note: type: string description: |- "Only available for a part of white list merchants.This applies to scenarios where a large single item needs to be shipped in multiple packages.Merchants not on the whitelist who upload this field will have it automatically ignored by the platform. For example, where Package 1 is marked with ""headboard"" and Package 2 is marked with ""bed frame"". This field will be displayed to buyers, so please fill it in carefully." ShippingProvider: type: object properties: id: type: string description: The shipping carrier unique id. name: type: string description: The shipping carrier name. Shop: type: object properties: name: type: string description: The name of the shop to which the product belongs. ShoppableContentPostingWebhook: type: object properties: type: type: integer const: 17 description: The ID of the webhook type. tts_notification_id: type: string description: The ID of the notification. creator_open_id: type: string description: The open_id of the creator. To get the value, see [Authorization overview](authorization-overview-202407). timestamp: type: integer format: int64 description: The UNIX timestamp when this webhook was triggered. data: $ref: "#/components/schemas/ShoppableContentPostingWebhookData" required: - type ShoppableContentPostingWebhookData: type: object properties: product_id: type: string description: ID of the product promoted in the creator's video. event: $ref: "#/components/schemas/ShoppableContentPostingWebhookDataEvent" ShoppableContentPostingWebhookDataEvent: type: object properties: type: type: string enum: - ADD - UPDATE - REMOVE x-enum-descriptions: - Add the product. - Update the product. - Remove the product. description: |- The action which the creator takes to the product promoted in the video or live stream. The possible enumerations are: * `ADD`: Add the product. * `UPDATE`: Update the product. * `REMOVE`: Remove the product. scene: type: string enum: - VIDEO x-enum-descriptions: - short video. description: |- The scene where the creator promotes the product. The possible enumerations are: * `VIDEO`: short video. content_id: type: string description: The ID of the short video. ShoppableVideoPrecheckTasksResultWebhook: type: object properties: type: type: integer const: 59 description: The ID of the webhook type. tts_notification_id: type: string description: The ID of the notification. creator_open_id: type: string description: The open_id of the creator. To get the value, see [Authorization overview](authorization-overview-202407). timestamp: type: integer format: int64 description: The UNIX timestamp when this webhook was triggered. data: $ref: "#/components/schemas/ShoppableVideoPrecheckTasksResultWebhookData" required: - type ShoppableVideoPrecheckTasksResultWebhookData: type: object properties: task_id: type: string description: ID of precheck task generated by TikTok Shop. violation_check_result: $ref: "#/components/schemas/ShoppableVideoPrecheckTasksResultWebhookDataViolationCheckResult" good_quality_check_result: $ref: "#/components/schemas/ShoppableVideoPrecheckTasksResultWebhookDataGoodQualityCheckResult" ShoppableVideoPrecheckTasksResultWebhookDataGoodQualityCheckResult: type: object properties: status: type: string enum: - SUCCESS - FAIL - PROCESSING description: |- Possible enumerations: `SUCCESS` `FAIL` `PROCESSING` issues: type: array items: $ref: "#/components/schemas/ShoppableVideoPrecheckTasksResultWebhookDataGoodQualityCheckResultIssue" ShoppableVideoPrecheckTasksResultWebhookDataGoodQualityCheckResultIssue: type: object properties: code: type: string description: Quality check code. suggestions: type: string description: How to improve video quality. ShoppableVideoPrecheckTasksResultWebhookDataViolationCheckResult: type: object properties: status: type: string enum: - SUCCESS - FAIL - PROCESSING description: |- Possible enumerations: `SUCCESS` `FAIL` `PROCESSING` issues: type: array items: $ref: "#/components/schemas/ShoppableVideoPrecheckTasksResultWebhookDataViolationCheckResultIssue" ShoppableVideoPrecheckTasksResultWebhookDataViolationCheckResultIssue: type: object properties: risk: type: string description: Risk type. suggestions: type: string description: Suggestions on how to fix the risk. ShowGpm: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). SiocAttribute: type: object properties: sioc_files: type: array items: $ref: "#/components/schemas/SiocFile" description: Sioc files SiocFile: type: object properties: sioc_certification_url: type: string description: sico attachment url sioc_file_type: type: string description: |- sioc attachment type: - PHOTO - DOCUMENT - DROP_TEST_VIDEO SizeChart: type: object properties: image: $ref: "#/components/schemas/Image" description: |- An image of the size chart. **Recommendations**: - Resolution: Minimum 1024px on the shorter side - Content: Include key measurement dimensions (e.g., bust, waist, hips, inseam), the more the better. - Format: Use a table with distinct columns and row. - Use only one table per product and image. - Display each dimension in a separate row. - Display units in column headers. template: $ref: "#/components/schemas/Template" description: A TikTok Shop size chart template generated by the size chart tool in Seller Center > Manage Products > Bulk action > Batch manage size charts. SizeChartChangeWebhook: type: object properties: type: type: integer const: 19 description: The ID of the webhook type. tts_notification_id: type: string description: The ID of this webhook notification. seller_open_id: type: string description: The open_id of the seller. For more information, refer to [Authorization overview](authorization-overview-202407). timestamp: type: integer format: int64 description: The time when this webhook is triggered. Unix timestamp. data: $ref: "#/components/schemas/SizeChartChangeWebhookData" required: - type SizeChartChangeWebhookData: type: object properties: size_chart_template_id: type: string description: The ID of the size chart template that's being changed. size_chart_template_name: type: string description: The name of the size chart template that's being changed. event_type: type: string enum: - CREATE - EDIT - DELETE x-enum-descriptions: - A new size chart is created - The size chart is edited - The size chart is deleted description: |- The change that occurred for the size chart. Possible values: - `CREATE`: A new size chart is created - `EDIT`: The size chart is edited - `DELETE`: The size chart is deleted update_time: type: integer format: int64 description: The time when the change occurred. Unix timestamp. SizeChartData: type: object properties: description: type: string description: Additional size chart description. is_one_size: type: boolean description: Whether this is a one-size chart. measurement_type: type: string enum: - GENERIC_MEASUREMENTS - BODY_MEASUREMENTS - PRODUCT_MEASUREMENTS x-enum-descriptions: - generic measurements - shopper body measurements - finished-product measurements. description: "Possible values: GENERIC_MEASUREMENTS: generic measurements; BODY_MEASUREMENTS: shopper body measurements; PRODUCT_MEASUREMENTS: finished-product measurements." size_types: type: array items: type: string description: "Possible values: size_chart_common_size_type: Common; size_chart_size_type_regular: Regular; size_chart_size_type_juniors: Juniors; size_chart_size_type_plus: Plus; size_chart_size_type_big&tall: Big & Tall; size_chart_size_type_petite: Petite. Available values depend on the category." table: $ref: "#/components/schemas/Table" description: Table containing headers and rows. unit_system: type: string enum: - METRIC - IMPERIAL x-enum-descriptions: - metric units - imperial units. description: "Possible values: METRIC: metric units; IMPERIAL: imperial units." required: - measurement_type - table - unit_system Sku: type: object properties: sku_id: type: string description: TikTok Shop SKU ID to include in the refund calculation. quantity: type: integer format: int64 description: Quantity of this SKU to include in the refund calculation. required: - sku_id - quantity SkuDimension: type: object properties: length: type: string description: |- The package length. A positive whole number. Note: For the BR market, decimal values using . or , as separators are also accepted but will be rounded to the nearest whole number. width: type: string description: |- The package width. A positive whole number. Note: For the BR market, decimal values using . or , as separators are also accepted but will be rounded to the nearest whole number. height: type: string description: |- The package height. A positive whole number. Note: For the BR market, decimal values using . or , as separators are also accepted but will be rounded to the nearest whole number. unit: type: string description: |- The unit for the SKU dimensions. Possible values based on region: - US: CENTIMETER, INCH - Other regions: CENTIMETER Note: Use the same measurement system (metric or imperial) for `sku_weight` and `sku_dimensions`. For example, use `KILOGRAM` with `CENTIMETER`. required: - length - width - height - unit SkuImg: type: object properties: uri: type: string description: |- The URI of the image. Obtain this URI by uploading the images through the [Upload Product Image API](6509df95defece02be598a22) with `use_case=ATTRIBUTE_IMAGE`. required: - uri SkuReturnRequest: type: object properties: order_id: type: string description: TikTok Shop main order ID associated with this SKU return request. return_id: type: string description: The identifier of a specific return. return_type: type: string enum: - REFUND - RETURN_AND_REFUND - REPLACEMENT - EXCHANGE x-enum-descriptions: - Seller will issue a refund without return. The buyer is not required to send the item(s) back to the seller. - Buyer is required to send the item(s) back to the seller. The seller will need to review the condition of the returned item(s) before a refund can be issued to the buyer. - The buyer requires the seller to replace the item(s). - The buyer requires the seller to exchange the item(s). description: |- Return type. Available values: - `REFUND`: Seller will issue a refund without return. The buyer is not required to send the item(s) back to the seller. - `RETURN_AND_REFUND`: Buyer is required to send the item(s) back to the seller. The seller will need to review the condition of the returned item(s) before a refund can be issued to the buyer. - `REPLACEMENT`: The buyer requires the seller to replace the item(s). - `EXCHANGE`: The buyer requires the seller to exchange the item(s). return_status: type: string enum: - RETURN_OR_REFUND_REQUEST_PENDING - REFUND_OR_RETURN_REQUEST_REJECT - AWAITING_BUYER_SHIP - BUYER_SHIPPED_ITEM - REJECT_RECEIVE_PACKAGE - RETURN_OR_REFUND_REQUEST_SUCCESS - RETURN_OR_REFUND_REQUEST_CANCEL - RETURN_OR_REFUND_REQUEST_COMPLETE - REPLACEMENT_REQUEST_PENDING - REPLACEMENT_REQUEST_REJECT - REPLACEMENT_REQUEST_REFUND_SUCCESS - REPLACEMENT_REQUEST_CANCEL - REPLACEMENT_REQUEST_COMPLETE - AWAITING_BUYER_RESPONSE - EXCHANGE_REQUEST_PENDING - EXCHANGE_REQUEST_REFUND_SUCCESS - EXCHANGE_REQUEST_CANCEL - EXCHANGE_REQUEST_COMPLETE x-enum-descriptions: - Buyer has initiated a return or refund request. The request is pending review by seller or platform. - The return or refund request was rejected. - The return request was approved. The seller is waiting for the buyer to ship the approved items to the seller. If the buyer doesn't ship the items to the seller before the deadline, the platform will close the request. - Buyer has shipped the approved items to seller. - Seller inspected the returned items and rejected the return package. - The return/refund request was approved. The buyer will be refunded. - The request has been cancelled by the buyer or system. - The return/refund was processed successfully. The buyer has been refunded. - Buyer has initiated a replacement request. The request is pending review by seller. - Seller reject the buyer replacement request. - Buyer's replacement request was resolved by refund due to insufficient inventory. - Buyer canceled the replacement request. - Seller has approved the buyer's replacement request, platform will generate a new order for seller to fulfill. - Seller offer another return type to the buyer, and waiting buyer response. Seller proposed return type can check the `seller_proposed_return_type`. - Buyer has initiated an exchange request. The request is pending review by seller. - Buyer's exchange request was resolved by refund due to insufficient inventory. - Buyer canceled the exchange request. - Seller has approved the buyer's exchange request, platform will generate a new order for seller to fulfill. description: |- Return status. Available values: - `RETURN_OR_REFUND_REQUEST_PENDING`: Buyer has initiated a return or refund request. The request is pending review by seller or platform. - `REFUND_OR_RETURN_REQUEST_REJECT`: The return or refund request was rejected. - `AWAITING_BUYER_SHIP`: The return request was approved. The seller is waiting for the buyer to ship the approved items to the seller. If the buyer doesn't ship the items to the seller before the deadline, the platform will close the request. - `BUYER_SHIPPED_ITEM`: Buyer has shipped the approved items to seller. - `REJECT_RECEIVE_PACKAGE`: Seller inspected the returned items and rejected the return package. - `RETURN_OR_REFUND_REQUEST_SUCCESS`: The return/refund request was approved. The buyer will be refunded. - `RETURN_OR_REFUND_REQUEST_CANCEL`: The request has been cancelled by the buyer or system. - `RETURN_OR_REFUND_REQUEST_COMPLETE`: The return/refund was processed successfully. The buyer has been refunded. - `REPLACEMENT_REQUEST_PENDING`: Buyer has initiated a replacement request. The request is pending review by seller. - `REPLACEMENT_REQUEST_REJECT`: Seller reject the buyer replacement request. - `REPLACEMENT_REQUEST_REFUND_SUCCESS`: Buyer's replacement request was resolved by refund due to insufficient inventory. - `REPLACEMENT_REQUEST_CANCEL`: Buyer canceled the replacement request. - `REPLACEMENT_REQUEST_COMPLETE`: Seller has approved the buyer's replacement request, platform will generate a new order for seller to fulfill. - `AWAITING_BUYER_RESPONSE`: Seller offer another return type to the buyer, and waiting buyer response. Seller proposed return type can check the `seller_proposed_return_type`. - `EXCHANGE_REQUEST_PENDING`: Buyer has initiated an exchange request. The request is pending review by seller. - `EXCHANGE_REQUEST_REFUND_SUCCESS`: Buyer's exchange request was resolved by refund due to insufficient inventory. - `EXCHANGE_REQUEST_CANCEL`: Buyer canceled the exchange request. - `EXCHANGE_REQUEST_COMPLETE`: Seller has approved the buyer's exchange request, platform will generate a new order for seller to fulfill. arbitration_status: type: string enum: - IN_PROGRESS - SUPPORT_BUYER - SUPPORT_SELLER - CLOSED x-enum-descriptions: - The TikTok Shop platform operator is processing arbitration and may request additional information from the seller. - The platform operator supports the buyer. - The platform operator supports the seller. - Arbitration is closed. description: |- Arbitration status. Available values: - `IN_PROGRESS`: The TikTok Shop platform operator is processing arbitration and may request additional information from the seller. - `SUPPORT_BUYER`: The platform operator supports the buyer. - `SUPPORT_SELLER`: The platform operator supports the seller. - `CLOSED`: Arbitration is closed. role: type: string enum: - BUYER - SELLER - OPERATOR - SYSTEM x-enum-descriptions: - "" - "" - TikTok Shop platform operator. - TikTok Shop system. description: |- Return initiation role. Available values: - `BUYER` - `SELLER` - `OPERATOR` : TikTok Shop platform operator. - `SYSTEM`: TikTok Shop system. Please see "API overview" to learn more about roles. return_reason: type: string description: Machine-readable reason code for the return. Use `return_reason_text` for localized display text. return_reason_text: type: string description: |- Reason for return, in localized text. You can change language using the locale request parameter. seller_next_action_response: type: array items: $ref: "#/components/schemas/SellerNextActionResponse" description: Seller's next action and deadline. shipment_type: type: string enum: - PLATFORM - BUYER_ARRANGE x-enum-descriptions: - The buyer uses TikTok Shop's shipping service. See `handover_method` for whether the buyer uses `DROP_OFF` or `PICKUP`. - The buyer arranges the return shipment. description: |- The shipment method selected by the buyer for sending the item(s) back to the seller. Available values: - `PLATFORM`: The buyer uses TikTok Shop's shipping service. See `handover_method` for whether the buyer uses `DROP_OFF` or `PICKUP`. - `BUYER_ARRANGE`: The buyer arranges the return shipment. handover_method: type: string description: |- The handover method buyer chooses to use when returning item(s) to seller using platform's shipping service. - `DROP_OFF`: buyer will drop off the item(s) at courier - `PICKUP`: buyer is scheduling a pick up service offered by the courier. return_tracking_number: type: string description: The tracking number of parcels when buyer returns the item(s). return_provider_name: type: string description: The provider name of parcel when buyer returns the item(s). return_provider_id: type: string description: The provider ID of parcel when buyer returns the items. pre_return_id: type: string description: The previous return ID the current return order is edited from. next_return_id: type: string description: The next return ID the current return order is edited to. refund_amount: $ref: "#/components/schemas/RefundAmount" description: Refund amount details. return_line_items: type: array items: $ref: "#/components/schemas/ReturnLineItem" description: Return order lines items. create_time: type: integer format: int64 description: The time when the return was created, as a Unix timestamp in seconds. update_time: type: integer format: int64 description: The time when the return was last updated, as a Unix timestamp in seconds. discount: $ref: "#/components/schemas/SearchAftersalesRequestsResponseDataAftersalesRequestSkuReturnRequestDiscount" description: Discount refund amounts, denominated in the currency specified by `refund_amount.currency`. shipping_fee: $ref: "#/components/schemas/SearchAftersalesRequestsResponseDataAftersalesRequestSkuReturnRequestShippingFee" description: Return shipping fee amounts, denominated in the currency specified by `refund_amount.currency`. buyer_keep_item: type: boolean description: Indicates whether the buyer may keep the item(s). This field is returned as `true` for replacement requests and is omitted for other return types. return_shipping_document_type: type: string enum: - SHIPPING_LABEL - QR_CODE - QR_CODE_NBNL x-enum-descriptions: - "" - QR Code with Box - QR Code with No Box No Label description: |- The type of return shipping document selected by the buyer. Available values: - `SHIPPING_LABEL` - `QR_CODE` - QR Code with Box - `QR_CODE_NBNL` - QR Code with No Box No Label return_method: type: string description: |- Return method: - `SELLER_SHIPPED`: Seller offers the return shipping service. - `BUYER_SHIPPED`: Buyer offers the return shipping service. - `PLATFORM_SHIPPED`: TikTok Shop offers the return shipping service. is_combined_return: type: boolean description: This field will return true if the buyer is asking to combine multiple returns into one return package. combined_return_id: type: string description: If `is_combined_return` is `true`, this field will return the `combined_return_id` associated with the combined return. seller_proposed_return_type: type: string description: |- Seller proposed return type: - `PARTIAL_REFUND` partial_refund_amount: $ref: "#/components/schemas/PartialRefundAmount" description: Partial refund details. buyer_rejected_partial_refund: type: boolean description: |- Only return this field when seller initiated the partial refund. Available values: - `TRUE`: Buyer reject the seller partial refund offer. - `FALSE`: Buyer accept the seller partial refund offer or awaiting buyer response. return_warehouse_address: $ref: "#/components/schemas/ReturnWarehouseAddress" description: The return warehouse address details provided by the seller. exchange_order_lines: type: array items: $ref: "#/components/schemas/ExchangeOrderLine" description: Ignore this field. It is not yet supported. reshipment_order_id: type: string description: Ignore this field. It is not yet supported. is_quick_refund: type: boolean description: If the return hit the quick refund strategy, the seller cannot reject the received package return_sub_line_items: type: array items: $ref: "#/components/schemas/ReturnSubLineItem" description: Deprecated. Do not use this field. deprecated: true SkuWeight: type: object properties: value: type: string description: |- The package weight, which must be a positive number. The number format varies based on the unit: - GRAM: integer - KILOGRAM: up to 3 decimal places - POUND: up to 2 decimal places unit: type: string description: |- The unit for the SKU weight. Possible values based on region: - US: KILOGRAM, POUND - BR, JP, MX: KILOGRAM, GRAM - Other countries: KILOGRAM Note: Use the same measurement system (metric or imperial) for `sku_weight` and `sku_dimensions`. For example, use `KILOGRAM` with `CENTIMETER`. required: - value - unit SmartText: type: object properties: text: type: string description: The suggested intelligent text. Sort: type: object properties: sort_field: type: string enum: - CREATE_TIME - UPDATE_TIME description: |- Name of the field used for sorting. Possible values: - `CREATE_TIME` - `UPDATE_TIME` sort_order: type: string enum: - ASC - DESC description: |- Sort direction. Possible values: - `ASC` - `DESC` StrikethroughPriceExpiredWebhook: type: object properties: type: type: integer const: 38 description: The ID of the webhook type. tts_notification_id: type: string description: The ID of this webhook notification. shop_id: type: string description: The shop ID. timestamp: type: integer format: int64 description: The time when this webhook is triggered. Unix timestamp. data: $ref: "#/components/schemas/StrikethroughPriceExpiredWebhookData" required: - type StrikethroughPriceExpiredWebhookData: type: object properties: product_id: type: string description: The TikTok Shop product ID. sku_id: type: string description: The TikTok Shop SKU ID. SubItemInfo: type: object properties: id: type: string description: Line item id of the sub_item. This unique identifier can be used when performing split/line-level fulfillment events. sku_id: type: string description: SKU ID. display_status: type: string enum: - UNPAID - AWAITING_SHIPMENT - AWAITING_COLLECTION - IN_TRANSIT - DELIVERED - COMPLETED - CANCELLED x-enum-descriptions: - The order has been placed, but payment has not yet completed. - The order is ready for shipment, but no items have been shipped yet. - Shipping has been arranged, but the package is waiting to be collected by the carrier. - The package has been collected by the carrier and delivery is in progress. - The package has been delivered to the buyer. - The order has been completed, and no further returns or refunds are allowed. - The order has been cancelled. description: |- Available values: - `UNPAID`: The order has been placed, but payment has not yet completed. - `AWAITING_SHIPMENT`: The order is ready for shipment, but no items have been shipped yet. - `AWAITING_COLLECTION`: Shipping has been arranged, but the package is waiting to be collected by the carrier. - `IN_TRANSIT`: The package has been collected by the carrier and delivery is in progress. - `DELIVERED`: The package has been delivered to the buyer. - `COMPLETED`: The order has been completed, and no further returns or refunds are allowed. - `CANCELLED`: The order has been cancelled. product_name: type: string description: Product name. seller_sku: type: string description: The seller stock keeping unit (SKU) of the item. sku_image: type: string description: SKU image. sku_name: type: string description: The name of the SKU, combined by product SKU attribute like size or color. e.g. "Black, 26" product_id: type: string description: Product ID. sale_price: type: string description: Item sale price. Please refer to the currency of `payment_info`. platform_discount: type: string description: Platform discount amount. Please refer to the currency of `payment_info`. seller_discount: type: string description: Seller discount amount. Please refer to the currency of `payment_info`. cancel_reason: type: string description: The cancellation reason. Please visit [our list of cancel reasons](https://partner.tiktokshop.com/docv2/page/67e61eee427345048595487d) for more information. original_price: type: string description: Item original price. Please refer to the currency of `payment_info`. rts_time: type: integer format: int64 description: The time sellers shipped the order (called [Ship Package API](https://partner.tiktokshop.com/docv2/page/650aa4f1defece02be6e7cb1) successfully). Unix timestamp. package_status: type: string enum: - TO_FULFILL - PROCESSING - FULFILLING - COMPLETED - CANCELLED x-enum-descriptions: - Package awaiting seller to arrange shipment. - Shipping has been arranged by the seller. Awaiting carrier collection. - Package has been collected by carrier and is in transit. - Package has been delivered. - Package has been canceled. Normally, the package is canceled due to the package being lost or damaged. description: |- The package status of the item. Available values: - `TO_FULFILL`: Package awaiting seller to arrange shipment. - `PROCESSING`: Shipping has been arranged by the seller. Awaiting carrier collection. - `FULFILLING`: Package has been collected by carrier and is in transit. - `COMPLETED`: Package has been delivered. - `CANCELLED`: Package has been canceled. Normally, the package is canceled due to the package being lost or damaged. currency: type: string description: Currency for payment. shipping_provider_name: type: string description: The shipping provider name. cancel_user: type: string enum: - BUYER - SELLER - OPERATOR - SYSTEM description: |- Cancellation request initiator. Available values: - `BUYER` - `SELLER` - `OPERATOR` - `SYSTEM` shipping_provider_id: type: string description: The shipping provider ID of the item. item_tax: type: array items: $ref: "#/components/schemas/ItemTax" description: Item tax detail. tracking_number: type: string description: Tracking number. Available after package has been shipped. package_id: type: string description: An order can contain one or more packages based on how the seller chooses to ship. Each package has a unique `package_id` and `tracking_id`. retail_delivery_fee: type: string description: |- Retail delivery fee (RDF). **Note**: Only available in the US market. is_dangerous_good: type: boolean description: Whether the SKU is a hazmat item. When creating the label for a hazmat item, you must follow the platform rules to put certain items into one package. Please refer to the relationship between `sku_id` and `package_id` to determine how to follow platform rules. warehouse_id: type: string description: Seller warehouse ID. SubmitCustomsClearanceInformationRequest: type: object properties: order_list: type: array items: $ref: "#/components/schemas/SubmitCustomsClearanceInformationRequestOrderList" description: "List of orders for which to submit customs clearance information. Maximum: 100 orders per request." SubmitCustomsClearanceInformationRequestOrderList: type: object properties: order_id: type: string description: TikTok Shop order ID item_list: type: array items: $ref: "#/components/schemas/SubmitCustomsClearanceInformationRequestOrderListItemList" description: List of customs clearance entries for order lines. Within the same order, explicit order_line_id values must be unique. required: - order_id SubmitCustomsClearanceInformationRequestOrderListItemList: type: object properties: order_line_id: type: string description: Sub order ID; order_line_id and sku_id should not be both empty. sku_id: type: string description: SKU ID; order_line_id and sku_id should not be both empty. item_detail: type: array items: $ref: "#/components/schemas/SubmitCustomsClearanceInformationRequestOrderListItemListItemDetail" description: List of SKU-level customs clearance details for the order line. SubmitCustomsClearanceInformationRequestOrderListItemListItemDetail: type: object properties: sku_id: type: string description: The SKU ID for this customs clearance detail. qty: type: integer format: int64 description: Quantity of this SKU in the customs clearance detail. Must be greater than 0. price_percent: type: integer format: int64 description: Percentage assigned to this SKU within the order line. Each value must be non-negative, and the price_percent values in item_detail must total 100. For example, 10 means 10%. required: - sku_id - qty - price_percent SubmitCustomsClearanceInformationResponse: 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/SubmitCustomsClearanceInformationResponseData" SubmitCustomsClearanceInformationResponseData: type: object properties: {} SubmitProductViaOpportunityRequest: type: object properties: product_id: type: string description: The TikTok Shop product ID to submit. Must be in ACTIVATE status. required: - product_id SubmitProductViaOpportunityResponse: 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/SubmitProductViaOpportunityResponseData" SubmitProductViaOpportunityResponseData: type: object properties: submission: $ref: "#/components/schemas/SubmitProductViaOpportunityResponseDataSubmission" description: The submission record that links the product to the opportunity. SubmitProductViaOpportunityResponseDataSubmission: type: object properties: id: type: string description: Unique ID of this submission record. Use for tracking review status. opportunity_id: type: string description: The opportunity ID this submission is linked to. product_id: type: string description: The submitted product ID. status: type: string description: |- APPROVED, UNDER_REVIEW, REJECTED are supported. Initial submission status: PENDING_REVIEW. submit_time: type: integer format: int64 description: The submission time as a Unix timestamp in seconds (UTC). rejection_reason: type: string description: the reason when the status is REJECTED SubmitRedemptionInformationRequest: type: object properties: order_id: type: string description: TikTok Shop order ID. order_info_list: type: array items: $ref: "#/components/schemas/SubmitRedemptionInformationRequestOrderInfoList" description: Order line items for which to submit redemption information. Include at least one item. Each `order_line_id` must belong to the order specified by `order_id` and must appear only once in the list. required: - order_id - order_info_list SubmitRedemptionInformationRequestOrderInfoList: type: object properties: order_line_id: type: string description: The unique identifier of the order line item. redeem_info: $ref: "#/components/schemas/SubmitRedemptionInformationRequestOrderInfoListRedeemInfo" description: The redemption information generated by your system for this order line item. source_unique_id: type: string description: Optional, a unique id related to the order line in the caller system required: - order_line_id - redeem_info SubmitRedemptionInformationRequestOrderInfoListRedeemInfo: type: object properties: redeem_type: type: string description: |- What redeem type that you callback. 'CODE' - type code 'URL' - type url 'CODE_PIN' - type pin and code redeem_data: type: string description: |- Set the redeem data to this field with the maximum number of characters 1200. The example of each type is shown below, CODE: abc12344 URL: https://{your_domain}/abc CODE_PIN(json format): {"type": "CODE_PIN","code": "12345","pin": "abc"} redeem_instruction_info: type: string description: |- Additional redemption instruction in JSON format. Use instruction_url to specify a third-party website where the buyer completes redemption. This URL is included as a clickable link in the fulfillment email. Example: {"instruction_url": "https://example.com/redeem"} required: - redeem_type SubmitRedemptionInformationResponse: 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/SubmitRedemptionInformationResponseData" SubmitRedemptionInformationResponseData: type: object properties: order_statuses: type: array items: $ref: "#/components/schemas/SubmitRedemptionInformationResponseDataOrderStatus" description: Callback result.For partial failure usage, if some of order line id in the request fail, it will be recorded with a none zero status_code. SubmitRedemptionInformationResponseDataOrderStatus: type: object properties: order_line_id: type: string description: Line order id, same as the input line order id. status_code: type: integer format: int64 description: Callback status of this line order id. A none zero code represent a failure callback. SubmitSizeChartAppealRequest: type: object properties: product_id: type: integer format: int64 description: product_id appeal_message: $ref: "#/components/schemas/SubmitSizeChartAppealRequestAppealMessage" description: Details of the products submitted for appeal required: - product_id - appeal_message SubmitSizeChartAppealRequestAppealMessage: type: object properties: field_name: type: string enum: - APPEAL_MESSAGE_FIELD_SIZE_CHART description: |- The target fields to appeal. Possible values: - APPEAL_MESSAGE_FIELD_SIZE_CHART indicator_details: type: array items: $ref: "#/components/schemas/SubmitSizeChartAppealRequestAppealMessageIndicatorDetail" description: Indicator details of the products submitted for appeal size_chart_id: type: string description: size_chart_id size_chart_image_uri: type: string description: uri of size_chart_image required: - field_name - indicator_details SubmitSizeChartAppealRequestAppealMessageIndicatorDetail: type: object properties: indicator_type: type: string enum: - REQUIRED_DIMENSION - CONTAINS_ALL_SALE_PROPERTY - VALUE_RANGE_OUT_OF_RANGE x-enum-descriptions: - Does the size chart include all required dimensions? - Does the size chart cover all sales attributes?"" - Are the value ranges in the size chart valid? description: |- The target indicator_type to appeal of this field. Possible values: - REQUIRED_DIMENSION：Does the size chart include all required dimensions? - CONTAINS_ALL_SALE_PROPERTY：Does the size chart cover all sales attributes?"" - VALUE_RANGE_OUT_OF_RANGE：Are the value ranges in the size chart valid? required: - indicator_type SubmitSizeChartAppealResponse: 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/SubmitSizeChartAppealResponseData" SubmitSizeChartAppealResponseData: type: object properties: {} SubmitStrikethroughPriceRequest: type: object properties: external_product_id: type: string description: An external product identifier used on an external ecommerce platform. This value must match the `external_product_id` used when the product was created. skus: type: array items: $ref: "#/components/schemas/SubmitStrikethroughPriceRequestSku" description: A list of SKUs whose external pricing information is submitted for verification. All SKU IDs must belong to the product identified by `product_id`. required: - external_product_id - skus SubmitStrikethroughPriceRequestSku: type: object properties: external_retail_price: $ref: "#/components/schemas/SubmitStrikethroughPriceRequestSkuExternalRetailPrice" description: The SKU retail price on the external ecommerce platform. external_sku_id: type: string description: An external SKU identifier used on an external ecommerce platform. This value must match the `external_sku_id` used when the SKU was created. external_transaction_price: $ref: "#/components/schemas/SubmitStrikethroughPriceRequestSkuExternalTransactionPrice" description: The highest actual transaction price recorded for the SKU on the external ecommerce platform during the past 90 days. id: type: string description: The SKU ID generated by TikTok Shop. required: - external_retail_price - external_sku_id - external_transaction_price - id SubmitStrikethroughPriceRequestSkuExternalRetailPrice: type: object properties: amount: type: string description: The retail price amount. The valid range is 0.01 to 7600. currency: type: string description: The ISO 4217 currency code. The supported value is `USD`. required: - amount - currency SubmitStrikethroughPriceRequestSkuExternalTransactionPrice: type: object properties: amount: type: string description: The transaction price amount. The valid range is 0.01 to 7600, and the value must be equal to or greater than the list price specified when the product was created or edited. currency: type: string description: The ISO 4217 currency code. The supported value is `USD`. image: $ref: "#/components/schemas/Image" description: A reference to a previously uploaded image resource that proves the highest transaction price, such as an order or invoice screenshot. Mask all customer information before uploading the image. transaction_time: type: string format: date-time description: The RFC 3339 time when the highest transaction price was recorded. The time must include a timezone and be within the 90 days before the request. required: - amount - currency - transaction_time SubmitStrikethroughPriceResponse: 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/SubmitStrikethroughPriceResponseData" SubmitStrikethroughPriceResponseData: type: object properties: errors: type: array items: $ref: "#/components/schemas/SubmitStrikethroughPriceResponseDataError" description: Item-level failures for SKUs that could not be submitted. The array is empty when every requested SKU is accepted for verification. SubmitStrikethroughPriceResponseDataError: type: object properties: code: type: integer format: int64 description: The stable business failure code for this SKU. detail: $ref: "#/components/schemas/SubmitStrikethroughPriceResponseDataErrorDetail" description: Information that identifies the failed SKU. message: type: string description: A human-readable description of the failure and the action needed to correct it. required: - code - detail - message SubmitStrikethroughPriceResponseDataErrorDetail: type: object properties: sku_id: type: string description: The TikTok Shop SKU ID for which submission failed. required: - sku_id SuggestBrandsRequest: type: object properties: product_title: type: string description: The product title used to recommend brands. category_id: type: string description: TikTok Shop category ID. Optional. description: type: string description: The product description. Optional. images: type: array items: $ref: "#/components/schemas/DiagnoseAndOptimizeProductRequestSizeChartImage" description: Product images. Optional. The recommendation service currently uses the first image. required: - product_title SuggestBrandsResponse: 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/SuggestBrandsResponseData" SuggestBrandsResponseData: type: object properties: brands: type: array items: $ref: "#/components/schemas/SuggestBrandsResponseDataBrand" description: Recommended brands in recommendation order. Empty when no recommendations are available. SuggestBrandsResponseDataBrand: type: object properties: id: type: string description: Brand ID. is_authorized: type: boolean description: Whether the brand is authorized for the shop. False if authorization status is absent. name: type: string description: Brand name. Suggestion: type: object properties: seo_words: type: array items: $ref: "#/components/schemas/SeoWord" description: The SEO keyword suggestions if `diagnoses.field` is "TITLE". smart_texts: type: array items: $ref: "#/components/schemas/SmartText" description: The intelligent text suggestions for titles and descriptions. images: type: array items: $ref: "#/components/schemas/DiagnoseAndOptimizeProductResponseDataDiagnosisSuggestionImage" description: The optimized main image. Only the first image in the main image set will be optimized. SupplementarySkuImage: type: object properties: uri: type: string description: |- The URI of the image. Obtain this URI by uploading the images through the [Upload Product Image API](6509df95defece02be598a22) with `use_case=ATTRIBUTE_IMAGE`. required: - uri Table: type: object properties: headers: type: array items: $ref: "#/components/schemas/Header" description: Ordered header definitions. Provide 1 to 20 headers. rows: type: array items: $ref: "#/components/schemas/TableRow" description: Rows of the size chart. Provide 1 to 45 rows. required: - headers - rows TableRow: type: object properties: cells: type: array items: $ref: "#/components/schemas/TableRowCell" description: Cells aligned by index with `table.headers`. Each row must contain exactly one cell for every header. required: - cells TableRowCell: type: object properties: value: type: string maxLength: 32 description: "Cell value. Maximum length: 32 characters." required: - value TargetCollaborationConflict: type: object properties: creator_user_open_id: type: string description: Creator Open ID. [More details](https://partner.tiktokshop.com/docv2/page/3obfokj6) product_id: type: string description: The product identifier. Tax: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). Template: type: object properties: id: type: string description: The size chart template ID. required: - id TextArea: type: object properties: align_type: type: string description: "The text alignment type. Enum values: `LEFT`, `CENTER`, `RIGHT`." colors: type: array items: type: string description: A list of text colors available for consumers to choose from, using hexadecimal color values such as `#FFFFFF`. default_text: type: string description: Optional default text displayed in this area. If the consumer does not customize this area, the default text may be used. fonts: type: array items: type: string description: A list of font keys available for consumers to choose from, based on the platform-supported font library. max_text_length: type: integer format: int64 description: The maximum number of characters allowed for consumer text input. Threshold: type: object properties: minimum_follower_count: type: integer format: int64 description: The creator must have a follower count greater than or equal to this value to be eligible to request the sample. minimum_gmv: type: integer format: int64 description: The creator must have the GMV in the past 30 days greater than this value to be eligible to request the sample. avg_ec_video_views: type: integer format: int64 description: The creator must have an average number of e-commerce video views in the past 30 days greater than or equal to this value to be eligible to request the sample. category_ids: type: array items: type: string description: |- A list of product first-level category IDs. Use this to limit participating creators: for each creator, sort their GMV over the past 30 days by first-level product category. If the GMV of one of the categories is among the top three, the creator is eligible to participate in the event. No restriction by default. For example, if a creator's top three categories are [{Cellphone_ID}, {Furniture_ID}, {Food_ID}], and the value of tehis parameter is `[{Food_ID}]`, the creator is qualified for open collaboration. predicted_fulfillment_rank: type: string description: |- The creators whose predicted rate of posting a shoppable video or LIVE after receiving a sample. - ALL. All creators regardless of the rate. - LOW. The creators whose rate is above or equal to low. - MEDIUM. The creators whose rate is above or equal to medium. - HIGH. The creators whose rate is high. Time: type: object properties: create_time: $ref: "#/components/schemas/CreateTime" description: Filter based on creation time. update_time: $ref: "#/components/schemas/UpdateTime" description: Filter based on last update time. TokopediaMirrorStatusChangeWebhook: type: object properties: type: type: integer const: 35 description: The ID of the webhook type. tts_notification_id: type: string description: The ID of this webhook notification. seller_open_id: type: string description: The open_id of the seller. For more information, refer to [Authorization overview](authorization-overview-202407). timestamp: type: integer format: int64 description: The time when this webhook is triggered. Unix timestamp. data: $ref: "#/components/schemas/TokopediaMirrorStatusChangeWebhookData" required: - type TokopediaMirrorStatusChangeWebhookData: type: object properties: tts_shop_id: type: string description: The shop ID in TikTok Shop. update_time: type: integer format: int64 description: The time when the change occurred. Unix timestamp. mirror_status: type: string description: |- The shop mirroring status: - MIRRORED - ROLLED_BACK - CANCELED TrackingStatusUpdateRequest: type: object properties: country: type: string description: Order Country. order_id: type: string description: TikTok Shop order ID. external_tracking_url: type: string description: Service provider's track URL / official website link. tracks: type: array items: $ref: "#/components/schemas/TrackingStatusUpdateRequestTrack" description: Trajectory node array; maximum number of entries per single request [50], processing results are returned one by one within the array. That is, in the interface, a maximum of 50 tracks can be postbacked per order at a time. provider_id: type: string description: The logistics provider ID, which is the one filled in when placing an order or uploading a tracking number, must be consistent with it. required: - country - order_id - tracks - provider_id TrackingStatusUpdateRequestTrack: type: object properties: action_code: type: integer format: int64 description: "The standard trajectory node code must belong to the allowlist. See the below action code. The action code is limited, for the list of available enumerations, please refer to the documentation: https://partner.tiktokshop.com/docv2/page/1cjht3qx" occur_time: type: integer format: int64 description: Actual Trajectory Occurrence Time. Unix timestamp GMT (UTC+00:00). The unit is milliseconds. description: type: string description: The original trajectory description of the caller. failed_reason: type: string description: "Exception causes, details are listed below. See the below reason code. The reason code is limited, for the list of available enumerations, please refer to the documentation: https://partner.tiktokshop.com/docv2/page/1cjht3qx" proof_url: type: string description: Third-party tracking proof links or credentials. location: $ref: "#/components/schemas/TrackingStatusUpdateRequestTrackLocation" description: Location fields such as city, state, province, country, latitude and longitude; tracking_no: type: string description: The waybill number used when placing an order. If there is no tracking code, fill in the invoice id instead. And it may change in split shipment, it may change in different track in this scene. required: - action_code - occur_time - description - tracking_no TrackingStatusUpdateRequestTrackLocation: type: object properties: country: type: string description: country. state: type: string description: state. city: type: string description: city. zip_code: type: string description: zip code/post code. TrackingStatusUpdateResponse: 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/TrackingStatusUpdateResponseData" TrackingStatusUpdateResponseData: type: object properties: track_results: type: array items: $ref: "#/components/schemas/TrackingStatusUpdateResponseDataTrackResult" description: The trajectory node array, where the field in each element of the array indicates which trajectory it is. The `code` and `message` fields describe whether the trajectory has been received; if not, they represent the corresponding error code and error description. TrackingStatusUpdateResponseDataTrackResult: type: object properties: action_code: type: integer format: int64 description: The standard trajectory node code must belong to the allowlist. See the below action code. occur_time: type: integer format: int64 description: Actual Trajectory Occurrence Time. Unix timestamp GMT (UTC+00:00). The unit is milliseconds. description: type: string description: The original trajectory description of the caller. code: type: integer format: int64 description: The success or failure status of the trace corresponding to this action code, see the below error code message: type: string description: The success or failure messages returned in the trace corresponding to this action code. Reasons of failure will be described in the message. tracking_no: type: string description: The waybill number used when placing an order. If there is no tracking code, fill in the invoice id instead. And it may change in split shipment, it may change in different track in this scene. UnboxingCaseList: type: object properties: unbox_sku: type: string description: Unboxed sku code associated with the actual unboxed item. unbox_sku_type: type: string enum: - NORMAL - GIFT description: |- Indicates if the unboxed sku is a gift item Enumerations: NORMAL or GIFT UncombinePackagesRequest: type: object properties: order_ids: type: array items: type: string description: TikTok Shop order ID. Indicate the orders that need to be removed from the package. Please make sure the orders belong to the package. UncombinePackagesResponse: 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/UncombinePackagesResponseData" UncombinePackagesResponseData: type: object properties: packages: type: array items: $ref: "#/components/schemas/Package" description: The packages created after the specified orders are removed from the original combined package. UnitsSoldRange: type: object properties: minimum_amount: type: integer format: int64 description: The lowest number of units sold. maximum_amount: type: integer format: int64 description: The highest number of units sold. formatted_range: type: string description: The formatted range of minimum number of units sold to maximum number of units sold over the lifetime of the creator account. UpcomingAuthorizationExpirationWebhook: type: object properties: type: type: integer const: 7 description: The ID of the webhook type. shop_id: type: string description: The identification of the shop timestamp: type: integer format: int64 description: The time when the notification is pushed, represented as a Unix timestamp (seconds). tts_notification_id: type: string description: The ID of the notification. data: $ref: "#/components/schemas/UpcomingAuthorizationExpirationWebhookData" description: The object contains business parameters related to the specific notification type. required: - type UpcomingAuthorizationExpirationWebhookData: type: object properties: message: type: string expiration_time: type: string UpdateAgentSettingsRequest: type: object properties: can_accept_chat: type: boolean description: |- Whether the shop owner's customer service account can accept auto-assigned chats. - `true`: The agent receives auto-assigned chats and can also manually select chats to respond to. - `false`: The agent receives only manually assigned chats. For a shop with only one customer service agent, set this field to `true`; `false` is rejected. When using the IM API, `true` is recommended. required: - can_accept_chat UpdateAgentSettingsResponse: 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/UpdateAgentSettingsResponseData" UpdateAgentSettingsResponseData: type: object properties: {} UpdateConversationStatusRequest: type: object properties: action: type: string description: |- update conversation status. e.g. -STARRED star this conversation -UNSTARRED un star this conversation -ARCHIVED archived this invitation required: - action UpdateConversationStatusResponse: 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/UpdateConversationStatusResponseData" UpdateConversationStatusResponseData: type: object properties: {} UpdateFBTGoodsInfoRequest: type: object properties: update_goods_dto: $ref: "#/components/schemas/UpdateFBTGoodsInfoRequestUpdateGoodsDto" description: |- Goods information to update. Update behavior is field-specific; this object is neither a uniform partial patch nor a full replacement. Shared fields: - `tts_goods_id`: Identifies the goods record to update; it is not mutable. - `goods_name`, `goods_image_url`, `return_handling_method`, and `dimension_and_weight_base_info`: Replace their stored values. - `reference_code`: If omitted or empty, it is reset to the system-generated fallback. - `barcode_infos`: Replaces the existing barcode set. The FBT system barcode is preserved or added, and existing non-system barcodes omitted from the request are deleted. Removal of a barcode with an inbound record is rejected. - `is_hazmat`: `false` clears existing hazmat information. `true` requires valid `hazmat_info`. Optional extended fields: - `is_sioc` and `sioc_attribute`: `is_sioc` controls Ships in Own Container (SIOC) management. If `is_sioc` is omitted, no SIOC state or attribute update is requested, and `sioc_attribute` alone is ignored. - `goods_safety_attributes`: Omitted fragile, liquid, or sharp subfields retain their stored values. A changed value for a locked subfield causes the request to fail; resubmitting the same locked value is a no-op. Supplied editable values are updated. Do not send explicit `null`; the public schemas for these fields are non-nullable. UpdateFBTGoodsInfoRequestUpdateGoodsDto: type: object properties: tts_goods_id: type: string description: Identifier for goods generated by the Fulfilled by TikTok system. goods_name: type: string description: Name of the goods. goods_image_url: type: string description: Image URL for the goods. reference_code: type: string description: Reference code for the goods. barcode_infos: type: array items: $ref: "#/components/schemas/BarcodeInfo" description: barcode info list return_handling_method: type: string enum: - RESTOCK_SELLABLE_DISPOSE_UNSELLABLE - DISPOSAL_WITHOUT_INSPECTION - RETURN_WITHOUT_INSPECTION - RESTOCK_SELLABLE_RETURN_UNSELLABLE description: |- Return handling method stored for the FBT customer return service. This field is required on every update request. Possible values: - RESTOCK_SELLABLE_DISPOSE_UNSELLABLE - DISPOSAL_WITHOUT_INSPECTION - RETURN_WITHOUT_INSPECTION - RESTOCK_SELLABLE_RETURN_UNSELLABLE dimension_and_weight_base_info: $ref: "#/components/schemas/UpdateFBTGoodsInfoRequestUpdateGoodsDtoDimensionAndWeightBaseInfo" description: dimension and weight info is_hazmat: type: boolean description: whether is hazmat goods hazmat_info: $ref: "#/components/schemas/HazmatInfo" description: Hazmat information used when `is_hazmat` is `true`. is_lot_code: type: boolean description: |- if the product requires lot management based on FBT category rule TRUE:this product requires lot control FALSE:this product does not require lot control is_expiration_management: type: boolean description: Whether the goods require expiration management. shelf_life_attribute_info: $ref: "#/components/schemas/ShelfLifeAttributeInfo" description: Shelf-life attributes for the goods. is_sioc: type: boolean description: whether sioc sioc_attribute: $ref: "#/components/schemas/SiocAttribute" description: sioc info bulky_item_attribute: $ref: "#/components/schemas/UpdateFBTGoodsInfoRequestUpdateGoodsDtoBulkyItemAttribute" description: bulky item info goods_safety_attributes: $ref: "#/components/schemas/GoodsSafetyAttribute" description: safety attribute info required: - tts_goods_id - goods_name - goods_image_url - return_handling_method - dimension_and_weight_base_info - is_hazmat - is_lot_code - is_expiration_management UpdateFBTGoodsInfoRequestUpdateGoodsDtoBulkyItemAttribute: type: object properties: is_bulky_item_accessories: type: boolean description: whether the goods is bulky accessories UpdateFBTGoodsInfoRequestUpdateGoodsDtoDimensionAndWeightBaseInfo: type: object properties: weight_value: type: string description: Weight of the goods in the specified weight_unit. length_value: type: string description: Length of the goods in the specified dimension_unit. width_value: type: string description: Width of the goods in the specified dimension_unit. height_value: type: string description: Height of the goods in the specified dimension_unit. weight_unit: type: string enum: - MILLIGRAM - GRAM - KILOGRAM - POUND - OUNCE description: |- Weight unit. Possible values: - MILLIGRAM - GRAM - KILOGRAM - POUND - OUNCE dimension_unit: type: string enum: - MILLIMETER - CENTIMETER - METER - FOOT - INCH description: |- Dimension unit. Possible values: - MILLIMETER - CENTIMETER - METER - FOOT - INCH required: - weight_value - length_value - width_value - height_value - weight_unit - dimension_unit UpdateFBTGoodsInfoResponse: 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/UpdateFBTGoodsInfoResponseData" UpdateFBTGoodsInfoResponseData: type: object properties: update_result_info: $ref: "#/components/schemas/UpdateFBTGoodsInfoResponseDataUpdateResultInfo" description: Goods update result information. UpdateFBTGoodsInfoResponseDataUpdateResultInfo: type: object properties: tts_goods_id: type: string description: Identifier for goods generated by Fulfilled by TikTok system is_success: type: boolean description: Whether the goods update succeeded. fail_reason: type: string description: Reason the goods update failed. UpdateGlobalInventoryRequest: type: object properties: global_skus: type: array items: $ref: "#/components/schemas/UpdateGlobalInventoryRequestGlobalSku" description: A non-empty list of global SKUs whose inventory quantities you want to set. required: - global_skus UpdateGlobalInventoryRequestGlobalSku: type: object properties: id: type: string description: The global SKU ID in TikTok Shop. inventory: type: array items: $ref: "#/components/schemas/UpdateGlobalInventoryRequestGlobalSkuInventory" description: The inventory quantities to set for this global SKU, with one entry for each global warehouse to update. Existing global warehouses omitted from this array retain their current quantities. required: - id - inventory UpdateGlobalInventoryRequestGlobalSkuInventory: type: object properties: global_warehouse_id: type: string description: The ID of the global warehouse where the SKU is stored. The warehouse must be enabled and belong to this shop or seller. Retrieve this value from [Get Global Product](6509e2b0bace3e02b7490c96) or [Get Global Seller Warehouse](650aa3f0defece02be6e5ffb). quantity: type: integer format: int64 description: The number of inventory units to set for this global SKU in the specified global warehouse. Must be 0 or greater. required: - global_warehouse_id - quantity UpdateGlobalInventoryResponse: 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/UpdateGlobalInventoryResponseData" UpdateGlobalInventoryResponseData: type: object properties: {} UpdateGoodsSKURelationsRequest: type: object properties: operate_goods_sku_relation_list: type: array items: $ref: "#/components/schemas/UpdateGoodsSKURelationsRequestOperateGoodsSkuRelationList" description: List of goods and SKU relations to bind or unbind. operation_type: type: string enum: - BIND - UN_BIND x-enum-descriptions: - bind the listed SKUs to the goods - unbind the listed SKUs from the goods . description: "Operation type for the goods-SKU relation. Possible values: BIND (bind the listed SKUs to the goods); UN_BIND (unbind the listed SKUs from the goods)." required: - operate_goods_sku_relation_list - operation_type UpdateGoodsSKURelationsRequestOperateGoodsSkuRelationList: type: object properties: tts_goods_id: type: string description: Identifier for goods generated by Fulfilled by TikTok system tts_sku_ids: type: array items: type: string description: Identifiers of the TikTok Shop SKUs to bind to or unbind from the specified FBT goods. required: - tts_goods_id - tts_sku_ids UpdateGoodsSKURelationsResponse: 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/UpdateGoodsSKURelationsResponseData" UpdateGoodsSKURelationsResponseData: type: object properties: operate_goods_sku_relation_info: $ref: "#/components/schemas/UpdateGoodsSKURelationsResponseDataOperateGoodsSkuRelationInfo" description: Results of the requested bindings or unbindings between TikTok Shop SKUs and FBT goods. UpdateGoodsSKURelationsResponseDataOperateGoodsSkuRelationInfo: type: object properties: operate_result_list: type: array items: $ref: "#/components/schemas/UpdateGoodsSKURelationsResponseDataOperateGoodsSkuRelationInfoOperateResultList" description: Goods-SKU relation results, including the goods ID, SKU ID, success status, and failure reason when applicable. UpdateGoodsSKURelationsResponseDataOperateGoodsSkuRelationInfoOperateResultList: type: object properties: tts_goods_id: type: string description: Identifier for goods generated by Fulfilled by TikTok system tts_sku_id: type: string description: Identifier for SKU generated by TikTok Shop system is_success: type: boolean description: Whether the goods-SKU relation operation succeeded. fail_reason: type: string description: Reason the goods-SKU relation operation failed. UpdateInboundOrderTrackingRequest: type: object properties: order_id: type: string description: |- The numeric identifier of the inbound order to update tracking information for. **Note:** Provide the numeric sequence only; do not include the "IBR" prefix (e.g., use `123456` instead of `IBR123456`). parcel_tracking_info: type: array items: $ref: "#/components/schemas/UpdateInboundOrderTrackingRequestParcelTrackingInfo" description: Carton-level parcel tracking information for the inbound order, including carton number, logistics provider name, and tracking number. required: - order_id UpdateInboundOrderTrackingRequestParcelTrackingInfo: type: object properties: provider_name: type: string description: |- The `provider_name` field must contain exactly one of the following strings. * `FEDEX` (Federal Express) * `UPS` (United Parcel Service) * `DHL` (DHL Express) * `USPS` (United States Postal Service) * `OTHER` (All other logistics providers) **Note:** Input must match the uppercase string exactly (e.g., `"provider_name": "FEDEX"`). tracking_number: type: string description: The tracking number to associate with this carton. It must not be empty or contain only whitespace, and it may contain only ASCII letters, digits, spaces, and hyphens. After spaces and hyphens are removed, 8 to 40 letters or digits must remain. carton_number: type: string description: The carton number of an existing carton in this inbound order. After leading and trailing whitespace is removed, this value is matched to the carton whose tracking information is created or replaced. required: - provider_name - tracking_number - carton_number UpdateInboundOrderTrackingResponse: 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/UpdateInboundOrderTrackingResponseData" UpdateInboundOrderTrackingResponseData: type: object properties: {} UpdateInventoryRequest: type: object properties: skus: type: array items: $ref: "#/components/schemas/UpdateInventoryRequestSku" description: A list of Stock Keeping Units (SKUs) used to identify distinct variants of the product. required: - skus UpdateInventoryRequestSku: type: object properties: id: type: string description: |- The SKU ID generated by TikTok Shop. One product can contain multiple SKU IDs. **Note**: - The SKU ID must belong to a product that is not in `FREEZE` or `DELETED` status. - If you are updating multiple SKUs, all the SKU IDs must belong to the same product. inventory: type: array items: $ref: "#/components/schemas/UpdateInventoryRequestSkuInventory" description: |- SKU inventory information. **Note**: You must include all warehouse IDs assigned to this SKU, along with the respective quantity. Do not omit any or add unrelated warehouses. required: - id - inventory UpdateInventoryRequestSkuInventory: type: object properties: warehouse_id: type: string description: |- The ID of the warehouse where the SKU is stored. Retrieve this value from the [Get Product API](https://partner.tiktokshop.com/docv2/page/6509d85b4a0bb702c057fdda). **Note**: Optional if there is only 1 warehouse. Otherwise, please provide this ID. quantity: type: integer format: int64 minimum: 1 maximum: 99999 description: |- The total SKU quantity available in the warehouse. Valid range: [1, 99,999] Note: This quantity specifically refers to the in-stock inventory that can be shipped immediately. backorder_quantity: type: integer format: int64 description: |- The `backorder_quantity` is automatically converted to `quantity` when in-stock inventory is sold out. Its fulfillment follows the specified `handling_time`. **Note**: - Provide `backorder_quantity` and `handling_time` together. - If `backorder_quantity` is omitted, the existing backorder quantity remains unchanged. handling_time: type: integer format: int64 description: The estimated number of working days needed for a backorder to be shipped. Provide `handling_time` and `backorder_quantity` together. All warehouses for the same SKU must use the same `handling_time`. required: - quantity UpdateInventoryResponse: 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/UpdateInventoryResponseData" UpdateInventoryResponseData: type: object properties: errors: type: array items: $ref: "#/components/schemas/UpdateInventoryResponseDataError" description: Inventory update errors for individual SKU and warehouse combinations. A successful top-level response can still include this list when individual updates fail, so inspect it before treating all updates as successful. UpdateInventoryResponseDataError: 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/UpdateInventoryResponseDataErrorDetail" description: The details of the main error. UpdateInventoryResponseDataErrorDetail: type: object properties: sku_id: type: string description: The ID of the SKU where the error occurred. extra_errors: type: array items: $ref: "#/components/schemas/UpdateInventoryResponseDataErrorDetailExtraError" description: A list of secondary errors or issues related to the main error. UpdateInventoryResponseDataErrorDetailExtraError: type: object properties: warehouse_id: type: string description: The ID of the warehouse where the error occurred. code: type: integer format: int64 description: The secondary error code. message: type: string description: The secondary error message. UpdateOrderShippingInfoRequest: type: object properties: tracking_number: type: string minLength: 4 maxLength: 50 description: The shipment tracking number provided by the carrier. It must contain 4 to 50 characters consisting only of letters, numbers, hyphens (`-`), underscores (`_`), periods (`.`), or slashes (`/`). shipping_provider_id: type: string description: Identifies the carrier that will deliver the package. Please call [Get Shipping Providers API](https://partner.tiktokshop.com/docv2/page/650aa48d4a0bb702c06d85cd?external_id=650aa48d4a0bb702c06d85cd#Back%20To%20Top) to retrieve the available shipping provider(s). required: - tracking_number - shipping_provider_id UpdateOrderShippingInfoResponse: 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/UpdateOrderShippingInfoResponseData" UpdateOrderShippingInfoResponseData: type: object properties: {} UpdatePackageDeliveryStatusRequest: type: object properties: packages: type: array items: $ref: "#/components/schemas/UpdatePackageDeliveryStatusRequestPackage" description: The packages to update. Provide at least one package. required: - packages UpdatePackageDeliveryStatusRequestPackage: type: object properties: id: type: string description: The package ID. delivery_type: type: string enum: - DELIVERY_SUCCESS - DELIVERY_FAILED - UPDATE_POD x-enum-descriptions: - The package has been successfully delivered. - The package could not be delivered successfully. - Updates the attachment for a package that has already been delivered. description: |- Delivery status of the package. Possible values for in-store pick up: - `DELIVERY_SUCCESS`: The package has been successfully delivered. Possible values for SOF (Seller Own Fleet): - `DELIVERY_SUCCESS`: The package has been successfully delivered. - `DELIVERY_FAILED`: The package could not be delivered successfully. - `UPDATE_POD`: Updates the attachment for a package that has already been delivered. fail_delivery_reason: type: string enum: - INVALID_ADDRESS - UNABLE_RECEIVE - UNABLE_CONTACT_BUYER - BUYER_REFUSED - DELAY_DELIVERY - PACKAGE_LOST - PACKAGE_DAMAGE - FORCE_MAJEURE - OTHER x-enum-descriptions: - The buyer shipping address is invalid. - The buyer is currently unable to receive the delivery. - Unable to contact the buyer. - The buyer has refused to receive the product. - Delay in delivery. - The package is lost. - The package is damaged. - An unforeseeable event of force majeure has occurred. - Other reason. description: |- Delivery failure reasons. When `delivery_type = DELIVERY_FAILED`, this field is required. For other delivery types, this field is not required. Possible values: - `INVALID_ADDRESS`: The buyer shipping address is invalid. - `UNABLE_RECEIVE`: The buyer is currently unable to receive the delivery. - `UNABLE_CONTACT_BUYER`: Unable to contact the buyer. - `BUYER_REFUSED`: The buyer has refused to receive the product. - `DELAY_DELIVERY`: Delay in delivery. - `PACKAGE_LOST`: The package is lost. - `PACKAGE_DAMAGE`: The package is damaged. - `FORCE_MAJEURE`: An unforeseeable event of force majeure has occurred. - `OTHER`: Other reason. file_type: type: string description: |- Attachment type: - `IMG` - `PDF` file_url: type: string description: |- Attachment URL. The seller can use the [Upload Delivery File](https://partner.tiktokshop.com/docv2/page/650aa6e04a0bb702c06dcd34?external_id=650aa6e04a0bb702c06dcd34#Back%20To%20Top) and [Upload Delivery Image](https://partner.tiktokshop.com/docv2/page/650aa70d0fcef602bf32772f?external_id=650aa70d0fcef602bf32772f) APIs to generate the URL. The attachment will be used by TikTok Shop to verify the package delivery. verification_code: type: string description: The verification code required for order pickup. required: - id - delivery_type UpdatePackageDeliveryStatusResponse: 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/UpdatePackageDeliveryStatusResponseData" UpdatePackageDeliveryStatusResponseData: type: object properties: errors: type: array items: $ref: "#/components/schemas/BatchShipPackagesResponseDataError" description: Package-level failures from the batch request. Each entry identifies the affected package and contains the returned failure code and message fields. Check this list even when the top-level response code is `0`. UpdatePackageShippingInfoRequest: type: object properties: shipping_info_list: type: array items: $ref: "#/components/schemas/ShippingInfoList" description: |- "Only supports uploading multiple tracking numbers for split-shipment in 3PL single item scenarios (non-virtual bundle) (This function is only support for whitelist sellers； If you are not on the allowlist, it is recommended to contact AM to apply) For other scenarios, only one tracking number can be uploaded at a time." required: - shipping_info_list UpdatePackageShippingInfoResponse: 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/UpdatePackageShippingInfoResponseData" UpdatePackageShippingInfoResponseData: type: object properties: {} UpdatePriceRequest: type: object properties: skus: type: array items: $ref: "#/components/schemas/UpdatePriceRequestSku" description: A list of Stock Keeping Units (SKUs) used to identify distinct variants of the product. required: - skus UpdatePriceRequestSku: type: object properties: id: type: string description: |- The SKU ID generated by TikTok Shop. One product can contain multiple SKU IDs. **Note**: - The SKU ID must belong to a product with the `ACTIVATE` status. - If you are updating multiple SKUs, all the SKU IDs must belong to the same product. price: $ref: "#/components/schemas/PartialEditProductRequestSkuPrice" description: SKU pricing information. list_price: $ref: "#/components/schemas/ListPrice" description: |- The SKU's list price information. This is equivalent to the manufacturer's suggested retail price (MSRP), or the recommended retail price (RRP). Applicable only for the US market. **Note**: This value may appear as the strikethrough price on the product page. However, whether the strikethrough price is shown and the amount shown are subject to the audit team's review and decision based on various pricing information. external_list_prices: type: array items: $ref: "#/components/schemas/ExternalListPrice" description: |- The SKU list price (e.g. MSRP, RRP) or original price information on external ecommerce platforms. Applicable only for selected sellers in the US market. **Note**: This value may appear as the strikethrough price on the product page. However, whether the strikethrough price is shown and the amount shown are subject to the audit team's review and decision based on various pricing information. required: - id - price UpdatePriceResponse: 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/UpdatePriceResponseData" UpdatePriceResponseData: type: object properties: {} UpdatePromotionActivityProductsRequest: type: object properties: products: type: array items: $ref: "#/components/schemas/UpdatePromotionActivityProductsRequestProduct" description: The items to add to the list or the existing items in the list of promotion activity to edit. The length must not exceed `300`. activity_id: type: string description: |- A unique ID that identifies activities. You cannot update the products in `DEACTIVATED` or `EXPIRED` activities. benefit_product_ids: type: array items: type: string description: IDs of benefit products to add to or update in a Buy More Save More (BMSM) or Buy X Get Y (BXGY) activity. Omitting this field or passing an empty array leaves the activity's existing benefit products unchanged; it does not remove them. After the update, the activity can contain at most 100 benefit products. exclude_product_ids: type: array items: type: string description: "For a SHOP-level Buy More Save More (BMSM) or Buy X Get Y (BXGY) activity, these are the IDs of products to add to or update in the exclusion list. Omitting this field or passing an empty array leaves existing excluded products unchanged; it does not remove them. Maximum: 100 IDs per request." required: - activity_id UpdatePromotionActivityProductsRequestProduct: type: object properties: id: type: string description: TikTok Shop product ID activity_price_amount: type: string description: Deal price in the product's currency. Specify this field when `product_level==PRODUCT` and `activity_type` is `FIXED_PRICE` or `FLASHSALE`. Do not specify it when `activity_type==DIRECT_DISCOUNT` or when `product_level==VARIATION`. discount: type: string description: |- Discount value. If the product is 10% off, the value is `10`. You must specify the value when `product_level==PRODUCT` and `activity_type==DIRECT_DISCOUNT`; and you must not specify it when it's not. quantity_limit: type: integer format: int64 description: |- The quantity limit of the products involved in the activity. The range is `[1, 99]`, or you can use `-1` for unlimited. If you are updating the value of an existing product, the value cannot be less than the current value. When `product_level==VARIATION`, you must specify `-1`. quantity_per_user: type: integer format: int64 description: |- Limit of product purchase per buyer. The range is `[1, 99]`, or you can use `-1` for unlimited. If you are updating the value of an existing product, the value cannot be less than the current value. When `product_level==VARIATION`, you must specify `-1`. skus: type: array items: $ref: "#/components/schemas/UpdatePromotionActivityProductsRequestProductSku" description: |- The SKUs to add to the list or to edit. The number of the SKUs across all products must not exceed 300 in an API call. For a product-discount or flash-deal activity with `product_level==VARIATION`, every product must contain at least one SKU. For those activity types with `product_level==PRODUCT`, specify `[]`. required: - id - quantity_limit - quantity_per_user UpdatePromotionActivityProductsRequestProductSku: type: object properties: id: type: string description: SKU ID activity_price_amount: type: string description: Deal price in the SKU's currency. Specify this field when `product_level==VARIATION` and `activity_type` is `FIXED_PRICE` or `FLASHSALE`. Do not specify it when `activity_type==DIRECT_DISCOUNT`. discount: type: string description: |- Discount value. If the SKU is 10% off, the value is `10`. You must specify this value when `product_level==VARIATION` and `activity_type==DIRECT_DISCOUNT`. Do not specify it when `activity_type` is `FIXED_PRICE` or `FLASHSALE`. quantity_limit: type: integer format: int64 description: The quantity limit of the SKU involved in the activity. The range is `[1, 99]`, or you can use `-1` for unlimited. If you are updating the value of an existing SKU, the value cannot be decreased. quantity_per_user: type: integer format: int64 description: Limit of SKU purchase per buyer. The range is `[1, 99]`, or you can use `-1` for unlimited. If you are updating the value of an existing SKU, the value cannot be decreased. required: - id - quantity_limit - quantity_per_user UpdatePromotionActivityProductsResponse: 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/UpdatePromotionActivityProductsResponseData" UpdatePromotionActivityProductsResponseData: type: object properties: activity_id: type: string description: A unique ID that identifies different activities. title: type: string description: Activity name set by the merchant. update_time: type: integer format: int64 description: The time when the response was generated, as a Unix timestamp in seconds (UTC). status: type: string enum: - DRAFT - NOT_START - ONGOING - EXPIRED - DEACTIVATED - NOT_EFFECTIVE x-enum-descriptions: - Promotion activities with this status are not available to TikTok users. - Promotion activities with this status are not available to TikTok users until the set activity start time. - Promotion activities with this status are available to TikTok users. - Promotion activities with this status are not available to TikTok users because it has expired. - The activity has been deactivated by the seller and is not available to TikTok users. - The activity is terminated by the platform and is not available to TikTok users. description: |- Activity status. Possible values: - DRAFT: Promotion activities with this status are not available to TikTok users. - NOT_START: Promotion activities with this status are not available to TikTok users until the set activity start time. - ONGOING: Promotion activities with this status are available to TikTok users. - EXPIRED: Promotion activities with this status are not available to TikTok users because it has expired. - DEACTIVATED: The activity has been deactivated by the seller and is not available to TikTok users. - NOT_EFFECTIVE: The activity is terminated by the platform and is not available to TikTok users. total_count: type: integer format: int64 description: |- The number of items in this request. When `product_level==PRODUCT`, this is the number of products. When `product_level==VARIATION`, this is the total number of SKUs across all products. When `product_level==SHOP`, this value is `0`. IDs in `benefit_product_ids` and `exclude_product_ids` are not included. UpdatePromotionActivityRequest: type: object properties: title: type: string description: "Activity name. The name must be unique. Maximum length: 50 Unicode characters for a flash-sale activity; 50 characters for a shipping-discount activity; 100 Unicode characters for a fixed-price, direct-discount, BMSM, BXGY, or GWP activity." duration_type: type: string description: |- The activity schedule mode. - For BMSM, BXGY, and GWP activities, set this field to `NORMAL` and provide the scheduled `begin_time` and `end_time`. - For a shipping-discount activity, use `NORMAL` for a scheduled activity or `INDEFINITE` for an activity without a scheduled end. When this field is omitted for a shipping-discount update, it defaults to `NORMAL`. For `INDEFINITE`, set both `begin_time` and `end_time` to `0`. - This field is not processed when updating a fixed-price, direct-discount, or flash-sale activity. begin_time: type: integer format: int64 description: Activity start time as a Unix timestamp in seconds. For an INDEFINITE shipping-discount activity, set this field to 0. For a fixed-price, direct-discount, flash-sale, BMSM, BXGY, or GWP activity with a normal schedule, use a future time when the activity is upcoming; if it is ongoing, use its existing start time because that value cannot be changed. end_time: type: integer format: int64 description: Activity end time as a Unix timestamp in seconds. For an INDEFINITE shipping-discount activity, set this field to 0. For a normal-schedule fixed-price, direct-discount, flash-sale, BMSM, BXGY, or GWP update, end_time must be at least 600 seconds after begin_time. product_level: type: string description: |- The promotion's product scope. You must provide this field when updating a BMSM, BXGY, GWP, or shipping-discount activity. - PRODUCT: Applies to a product and all of its SKUs. Use this value for GWP; BMSM, BXGY, and shipping-discount also support it. - VARIATION: Applies only to specified SKUs. It is not supported for BMSM, BXGY, GWP, or shipping-discount updates. - SHOP: Applies to all products in the shop. It is supported for BMSM, BXGY, and shipping-discount, but not GWP. This field is not processed for fixed-price, direct-discount, or flash-sale updates. For an ongoing BMSM or BXGY activity, keep its existing PRODUCT or SHOP scope. participation_limit: type: array items: $ref: "#/components/schemas/UpdatePromotionActivityRequestParticipationLimit" description: The buyer participation limit. For BMSM, BXGY, and GWP updates, provide exactly one entry. If a BMSM or BXGY activity is ongoing, keep its existing participation limit unchanged. discount: $ref: "#/components/schemas/Discount" description: Discount information. target_user_info: $ref: "#/components/schemas/UpdatePromotionActivityRequestTargetUserInfo" description: The promotion's target-user configuration. For an ongoing BMSM or BXGY activity, keep the existing target-user setting unchanged and include that existing value in the request. auction_support_type: type: string enum: - ALL - EXCLUDE_AUCTION x-enum-descriptions: - Supports both standard and auction products. - Excludes auction products. description: |- Determines whether a shipping-discount activity supports auction products. This field is not processed for other activity types. Possible values: - `ALL`: Supports both standard and auction products. - `EXCLUDE_AUCTION`: Excludes auction products. When omitted for a shipping-discount update, defaults to `ALL`. required: - title - begin_time - end_time UpdatePromotionActivityRequestParticipationLimit: type: object properties: type: type: string description: |- Determines whether the promotion limits how many orders each buyer can receive the benefit from. - `BUYER_NO_LIMIT`: Buyers can receive the benefit across multiple orders. - `BUYER_LIMIT_ONLY_ONE`: Each buyer can receive the benefit for no more than one order. required: - type UpdatePromotionActivityRequestTargetUserInfo: type: object properties: user_type: type: string enum: - ALL_USER - SHOP_NEW_CUSTOMER - SHOP_EXISTING_CUSTOMER - SHOP_REPEAT_CUSTOMER description: |- Possible enumerations are: `ALL_USER` `SHOP_NEW_CUSTOMER` `SHOP_EXISTING_CUSTOMER` `SHOP_REPEAT_CUSTOMER` UpdatePromotionActivityResponse: 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/UpdatePromotionActivityResponseData" UpdatePromotionActivityResponseData: type: object properties: activity_id: type: string description: A unique ID that identifies different activities. title: type: string description: Activity name set by the seller. Returned on successful fixed-price, direct-discount, flash-sale, BMSM, GWP, and BXGY updates. Not returned on successful shipping-discount updates. update_time: type: integer format: int64 description: Last update time as a Unix timestamp in seconds. UpdateShopWebhookRequest: type: object properties: address: type: string maxLength: 255 description: |- The HTTP or HTTPS webhook URL used to receive the event data. Max length: 255 characters event_type: type: string enum: - ORDER_STATUS_CHANGE - RECIPIENT_ADDRESS_UPDATE - PACKAGE_UPDATE - PRODUCT_STATUS_CHANGE - SELLER_DEAUTHORIZATION - UPCOMING_AUTHORIZATION_EXPIRATION - CANCELLATION_STATUS_CHANGE - RETURN_STATUS_CHANGE - NEW_CONVERSATION - NEW_MESSAGE - PRODUCT_INFORMATION_CHANGE - PRODUCT_CREATION - PRODUCT_CATEGORY_CHANGE - NEW_MESSAGE_LISTENER - INVOICE_STATUS_CHANGE - PRODUCT_AUDIT_STATUS_CHANGE - REVERSE_STATUS_UPDATE x-enum-descriptions: - Triggers on each order status update, from new order placement through all subsequent status changes. See [Order Status change](650300b8a57708028b430b4a). - Triggers when the recipient's address is updated. See [Receipient address update](650301af5a12ff0294ea3bf9). - Triggers when a package is updated (e.g., combined, split, or address changed). See [Package update](650955cabace3e02b73cc886). - Triggers when product audit results are updated. See [Product status change](650956aff1fd3102b90b6261). - Triggers when a seller is deauthorized to inform developers and avoid misunderstandings about platform authorization issues. See [Seller deauthorization](65095746defece02be4d749d). - Triggers 30 days before authorization expiration, with daily notifications at 0:00 until re-authorization is completed. See [Upcoming authorization expiration](6509579c0fcef602bf11312c). - Triggers when an order's cancellation status changes. See [Cancellation status change](65030150746462028285f657). - Triggers when an order's return status changes. See [Return status change](65030162bb2a4d028d50cc51). - Triggers when a customer service agent joins or leaves a conversation. See [New conversation](6614330bfe9fdc02e002abfd). - Triggers when a new message is sent in a customer service conversation. See [New Message](66143486ef8a1202dc323258). - Triggers when changes to a product's title, description, main images, or attributes go live. See [Product information change](65d6f41411a60f02dc1cf8bf). - Triggers when a new product is created. See [Product creation](663c98b566828e02e4515580). - Triggers when the category of a product is changed. See [Product category change](668764a371f16d02eef1f393). - Triggers when a creator sends a message to the seller. See [New message listener](6790b76eb59cf9030997b783). - Triggers when the status of an invoice upload changes after using the [POST Upload Invoice](67b542559a140004b343984f) endpoint. See [Invoice Status Change](67b68ca185619104a6772e5d). - Triggers when the product audit status changes. See [Product audit status change](67b5c6cba42623049abe5062). - Triggers when buyer raises cancellation, refund only, or return & refund requests that need the seller to accept or reject. See [Reverse Status Update](https://partner.tiktokshop.com/doc/page/63fd7459715d622a338c5437). description: |- The topic of the webhook event. Possible values: - `ORDER_STATUS_CHANGE`: Triggers on each order status update, from new order placement through all subsequent status changes. See [Order Status change](650300b8a57708028b430b4a). - `RECIPIENT_ADDRESS_UPDATE`: Triggers when the recipient's address is updated. See [Receipient address update](650301af5a12ff0294ea3bf9). - `PACKAGE_UPDATE`: Triggers when a package is updated (e.g., combined, split, or address changed). See [Package update](650955cabace3e02b73cc886). - `PRODUCT_STATUS_CHANGE`: Triggers when product audit results are updated. See [Product status change](650956aff1fd3102b90b6261). - `SELLER_DEAUTHORIZATION`: Triggers when a seller is deauthorized to inform developers and avoid misunderstandings about platform authorization issues. See [Seller deauthorization](65095746defece02be4d749d). - `UPCOMING_AUTHORIZATION_EXPIRATION`: Triggers 30 days before authorization expiration, with daily notifications at 0:00 until re-authorization is completed. See [Upcoming authorization expiration](6509579c0fcef602bf11312c). - `CANCELLATION_STATUS_CHANGE`: Triggers when an order's cancellation status changes. See [Cancellation status change](65030150746462028285f657). - `RETURN_STATUS_CHANGE`: Triggers when an order's return status changes. See [Return status change](65030162bb2a4d028d50cc51). - `NEW_CONVERSATION`: Triggers when a customer service agent joins or leaves a conversation. See [New conversation](6614330bfe9fdc02e002abfd). - `NEW_MESSAGE`: Triggers when a new message is sent in a customer service conversation. See [New Message](66143486ef8a1202dc323258). - `PRODUCT_INFORMATION_CHANGE`: Triggers when changes to a product's title, description, main images, or attributes go live. See [Product information change](65d6f41411a60f02dc1cf8bf). - `PRODUCT_CREATION`: Triggers when a new product is created. See [Product creation](663c98b566828e02e4515580). - `PRODUCT_CATEGORY_CHANGE`: Triggers when the category of a product is changed. See [Product category change](668764a371f16d02eef1f393). - `NEW_MESSAGE_LISTENER`: Triggers when a creator sends a message to the seller. See [New message listener](6790b76eb59cf9030997b783). - `INVOICE_STATUS_CHANGE`: Triggers when the status of an invoice upload changes after using the [POST Upload Invoice](67b542559a140004b343984f) endpoint. See [Invoice Status Change](67b68ca185619104a6772e5d). - `PRODUCT_AUDIT_STATUS_CHANGE`: Triggers when the product audit status changes. See [Product audit status change](67b5c6cba42623049abe5062). - `REVERSE_STATUS_UPDATE`: Triggers when buyer raises cancellation, refund only, or return & refund requests that need the seller to accept or reject. See [Reverse Status Update](https://partner.tiktokshop.com/doc/page/63fd7459715d622a338c5437). required: - address - event_type UpdateShopWebhookResponse: 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/UpdateShopWebhookResponseData" UpdateShopWebhookResponseData: type: object properties: {} UpdateStockOperationSettingsRequest: type: object properties: seller_id: type: string description: Identifies the seller whose settings are being modified. sku_ids: type: array items: type: string maxItems: 500 description: List of specific SKU IDs. Up to 500 SKUs in a batch. stock_operation_setting: $ref: "#/components/schemas/UpdateStockOperationSettingsRequestStockOperationSetting" description: The canceled-order auto-restock configuration to apply to the specified SKUs. required: - seller_id UpdateStockOperationSettingsRequestStockOperationSetting: type: object properties: enable_auto_restock: type: boolean description: |- Controls automatic inventory replenishment after a seller-fulfilled (FBM) order is canceled. When at least one SKU is supplied, omitting `stock_operation_setting` or `enable_auto_restock` uses `false`. - `true`: Enable automatic replenishment for the specified SKUs. - `false`: Disable automatic replenishment for the specified SKUs. UpdateStockOperationSettingsResponse: 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/UpdateStockOperationSettingsResponseData" UpdateStockOperationSettingsResponseData: type: object properties: stock_operation: $ref: "#/components/schemas/UpdateStockOperationSettingsResponseDataStockOperation" description: The update result of stock operation UpdateStockOperationSettingsResponseDataStockOperation: type: object properties: failed_sku_ids: type: array items: type: string description: Update inventory rule failed SkuID list success_sku_ids: type: array items: type: string description: List of SkuIDs that successfully updated inventory rules UpdateTargetCollaborationRequest: type: object properties: name: type: string description: The name of the target collaboration. end_time: type: string description: The end time of the target collaboration, as a Unix timestamp in seconds. products: type: array items: $ref: "#/components/schemas/UpdateTargetCollaborationRequestProduct" description: |- The information about the products provided by the seller for target collaboration with creators in the target collaboration. The maximum number of products is 100. When a product is deleted from the product list, if the deleted product has been added to the showcase by the creator, it will take effect at 0:00 the next day, otherwise it will take effect immediately. creator_user_open_ids: type: array items: type: string description: The list of Creators' TikTok User Open IDs invited in the target collaboration. The maximum number of creators is 50. [More details](https://partner.tiktokshop.com/docv2/page/3obfokj6) seller_contact_info: $ref: "#/components/schemas/UpdateTargetCollaborationRequestSellerContactInfo" description: Contact information for the seller in the target collaboration. free_sample_rule: $ref: "#/components/schemas/FreeSampleRule" description: The free sample rules set by the seller in the target collaboration. required: - name - end_time - products - creator_user_open_ids - seller_contact_info - free_sample_rule UpdateTargetCollaborationRequestProduct: type: object properties: id: type: string description: The product identifier. commission_rate: type: integer format: int64 description: |- The desired commission rate for the target collaboration. The value is measured in ten thousandths. For example, 3587 means the commission fee equals 35.87% of the original price. The range is [100, 8000]. Increasing product commissions will take effect immediately, while reducing product commissions will take effect at 00:00 the next day if the current product has been added to the showcase by a creator, otherwise it will take effect immediately. target_ad_commission_rate: type: integer format: int64 description: |- The commission rate applies only to orders generated from ads. If a creator’s video is used as an ad without this rate being set, the resulting orders will instead earn either: - The Shop Ads commission you configured in open collaboration, or - The standard commission defined in this invitation. The commission rate is specified in increments of 1/10,000. For example, 1000 stands for 0.1 or 10%. required: - id - commission_rate UpdateTargetCollaborationRequestSellerContactInfo: type: object properties: email: type: string description: Seller's email contact information phone_number: type: string description: The phone number of the seller. whatsapp: type: string description: The phone number used by the seller to register for WhatsApp. telegram: type: string description: The seller's Telegram username or phone number. line: type: string description: The phone number used by the seller to register for the Line app required: - email UpdateTargetCollaborationResponse: 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/UpdateTargetCollaborationResponseData" UpdateTargetCollaborationResponseData: type: object properties: target_collaboration_conflicts: type: array items: $ref: "#/components/schemas/TargetCollaborationConflict" description: A list of creators and products with target collaboration conflicts that caused target collaboration update failure. update_failed: $ref: "#/components/schemas/UpdateTargetCollaborationResponseDataUpdateFailed" description: Describe which fields were not updated successfully. UpdateTargetCollaborationResponseDataUpdateFailed: type: object properties: remove_creator_open_ids: type: array items: type: string description: The list of creators' TikTok User Open IDs that have not been successfully removed. More details:https://partner.tiktokshop.com/docv2/page/3obfokj6 remove_product_ids: type: array items: type: string description: The list of product ids that have not been successfully removed. add_creator_open_ids: type: array items: type: string description: The list of creators' TikTok User Open IDs that have not been successfully added. More details:https://partner.tiktokshop.com/docv2/page/3obfokj6 add_products: $ref: "#/components/schemas/UpdateTargetCollaborationResponseDataUpdateFailedAddProduct" description: The list of products that have not been successfully added. change_commissions: $ref: "#/components/schemas/UpdateTargetCollaborationResponseDataUpdateFailedChangeCommission" description: The list of commission information that has not been successfully changed. end_time: type: integer format: int64 description: The end time of the target collaboration, which has not been successfully updated. seller_contact_info: $ref: "#/components/schemas/SellerContactInfo" description: Contact information for the seller in the target collaboration which has not been successfully updated. name: type: string description: The name of the target collaboration. invalid_product_id_list: type: array items: type: string description: The list of product id that caused the update to fail. invalid_open_id_list: type: array items: type: string description: The list of open id that caused the update to fail. UpdateTargetCollaborationResponseDataUpdateFailedAddProduct: type: object properties: id: type: string description: The product identifier. commission_rate: type: integer format: int64 description: The desired commission rate for the target collaboration. The desired commission rate is expressed in hundredths of a percent. For example, 3587 is a commission rate of 35.87%. This value must be a minimum of 1000. UpdateTargetCollaborationResponseDataUpdateFailedChangeCommission: type: object properties: product_id: type: string description: The product identifier. commission_rate: type: integer format: int64 description: The desired commission rate for the target collaboration. The desired commission rate is expressed in hundredths of a percent. For example, 3587 is a commission rate of 35.87%. This value must be a minimum of 1000. UpdateTheBlindBoxOpeningResultsRequest: type: object properties: main_order_id: type: string description: The unique identifier for a TikTok Shop order. blind_box_results: type: array items: $ref: "#/components/schemas/UpdateTheBlindBoxOpeningResultsRequestBlindBoxResult" description: When using the legacy result shape, provide unboxing results for one or more blind-box line items in the specified order. blind_batch_box_results: type: array items: $ref: "#/components/schemas/UpdateTheBlindBoxOpeningResultsRequestBlindBatchBoxResult" description: Unboxing batch results for line items under orders. UpdateTheBlindBoxOpeningResultsRequestBlindBatchBoxResult: type: object properties: order_line_id: type: string description: The TikTok Shop line item ID of the blind box in the specified order to which this batch unboxing result belongs. blind_box_order_line_list: type: array items: $ref: "#/components/schemas/UpdateTheBlindBoxOpeningResultsRequestBlindBatchBoxResultBlindBoxOrderLineList" description: Unboxing results for line items under orders. on batch box version UpdateTheBlindBoxOpeningResultsRequestBlindBatchBoxResultBlindBoxOrderLineList: type: object properties: blind_result_product_id: type: string description: The TikTok Shop product ID revealed for this item in the batch unboxing result. blind_result_sku_id: type: string description: The TikTok Shop SKU ID revealed for this item in the batch unboxing result. blind_open_time: type: integer format: int64 description: Unix timestamp in milliseconds indicating when the blind box was opened. product_type: type: string enum: - NORMAL - GIFT x-enum-descriptions: - A normal unboxed product. - A gift unboxed product. description: |- Unboxing product type. Possible values: - `NORMAL`: A normal unboxed product. - `GIFT`: A gift unboxed product. UpdateTheBlindBoxOpeningResultsRequestBlindBoxResult: type: object properties: order_line_id: type: string description: The TikTok Shop line item ID for the blind box in the specified order. blind_result_product_id: type: string description: The TikTok Shop product ID revealed by opening the blind box. blind_result_sku_id: type: string description: The TikTok Shop SKU ID revealed by opening the blind box. blind_open_time: type: integer format: int64 description: Unix timestamp in milliseconds indicating when the blind box was opened. UpdateTheBlindBoxOpeningResultsResponse: 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/UpdateTheBlindBoxOpeningResultsResponseData" UpdateTheBlindBoxOpeningResultsResponseData: type: object properties: {} UpdateTime: type: object properties: min_unix_time_inclusive: type: integer format: int64 description: Inclusive lower bound (Unix seconds). max_unix_time_exclusive: type: integer format: int64 description: Exclusive upper bound (Unix seconds). UploadFileInitRequest: type: object properties: file_name: type: string description: The name of the file to upload for this upload session. file_type: type: string description: The type of file to upload. Currently, only video is supported. file_size: type: integer format: int64 description: file size, bytes total_chunk_count: type: integer format: int64 description: The total number of upload chunks. Must be greater than 0. For files of 5 MiB (5,242,880 bytes) or less, set this value to 1. target_path: type: string description: After the video is uploaded, use this interface to bind the video resource to the specific material required: - file_name - file_type - file_size - total_chunk_count - target_path UploadFileInitResponse: 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/UploadFileInitResponseData" UploadFileInitResponseData: type: object properties: upload_url: type: string description: The URL provided by platform where the file can be uploaded. upload_token: type: string description: The upload token used when uploading the file to the returned upload URL. UploadImageForBuyerMessagesRequest: type: object properties: data: type: string format: binary contentMediaType: application/octet-stream description: The format of the image must be jpg, gif, webp, or png. The size of the image must not exceed 10MB. required: - data UploadImageForBuyerMessagesResponse: 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/UploadImageForBuyerMessagesResponseData" UploadImageForBuyerMessagesResponseData: type: object properties: url: type: string description: Image URL width: type: integer format: int64 description: Width of the uploaded image in pixels. height: type: integer format: int64 description: Height of the uploaded image in pixels. UploadInvoiceRequest: type: object properties: invoices: type: array items: $ref: "#/components/schemas/UploadInvoiceRequestInvoice" description: The list of invoices to upload. When `invoices` is provided, include 1 to 500 items. UploadInvoiceRequestInvoice: type: object properties: package_id: type: string description: The TikTok Shop package ID, retrieved from [Search Package](650aa592bace3e02b75db748). order_ids: type: array items: type: string description: The list of TikTok Shop order IDs, retrieved from [Get Order List](650aa8094a0bb702c06df242). file_type: type: string enum: - XML description: |- The invoice file format. Possible values: - `XML` file: type: string description: |- Base64 encoding of the invoice file to upload. Max file size: 1MB required: - package_id - order_ids - file_type - file UploadInvoiceResponse: 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/UploadInvoiceResponseData" UploadInvoiceResponseData: type: object properties: errors: type: array items: $ref: "#/components/schemas/UploadInvoiceResponseDataError" description: Invoice-level upload errors. This list may be returned even when the top-level `code` is `0`; each entry identifies the affected package and order IDs. UploadInvoiceResponseDataError: type: object properties: code: type: integer format: int64 description: The error code. message: type: string description: The error message. detail: $ref: "#/components/schemas/UploadInvoiceResponseDataErrorDetail" description: The details of the error. UploadInvoiceResponseDataErrorDetail: type: object properties: package_id: type: string description: The package ID where the error occurred. order_ids: type: array items: type: string description: The order IDs where errors occurred. UploadMessageImageRequest: type: object properties: data: type: string format: binary contentMediaType: application/octet-stream description: The format of the image must be jpg, gif, webp, or png. The size of the image must not exceed 10MB. Zero-byte files are rejected. required: - data UploadMessageImageResponse: 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/UploadMessageImageResponseData" UploadMessageImageResponseData: type: object properties: url: type: string description: Image URL width: type: integer format: int64 description: Image width in pixels. height: type: integer format: int64 description: Image height in pixels. UploadMessageImageV2Request: type: object properties: data: type: string format: binary contentMediaType: application/octet-stream description: The format of the image must be jpg, gif, webp, or png. The size of the image must not exceed 10MB. required: - data UploadMessageImageV2Response: 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/UploadMessageImageV2ResponseData" UploadMessageImageV2ResponseData: type: object properties: url: type: string description: Image Url width: type: integer format: int64 description: Image width in pixels. height: type: integer format: int64 description: Image height UploadProductFileRequest: type: object properties: data: type: string format: binary contentMediaType: application/octet-stream description: |- The local file to be uploaded. **Note**: - Supported formats: PDF, MP4, MOV, MKV, WMV, WEBM, AVI, 3GP, FLV, MPEG - Zero-byte files are rejected. - Max PDF size: 20 MB - Max video size: 100 MB - Video aspect ratio: 9:16 to 16:9 **Recommendations for product videos**: - Aspect ratio: 1:1 - Resolution: HD 720p or higher - Duration: 20 - 60 seconds name: type: string description: |- The name of the file, including the file extension (e.g. `certification.pdf`) **Note**: - Do not use additional periods, except the one preceding the file extension. - Do not begin the name with symbols. - Do not include spaces. required: - data - name UploadProductFileResponse: 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/UploadProductFileResponseData" UploadProductFileResponseData: type: object properties: id: type: string description: |- The file ID generated by TikTok Shop. Pass this value when creating or editing a product to associate the file with the product. url: type: string description: The URL to access and view the file. name: type: string description: The name of the file. format: type: string enum: - PDF - MP4 - MOV - MKV - WMV - WEBM - AVI - 3GP - FLV - MPEG description: |- The format of the file. Possible values: PDF, MP4, MOV, MKV, WMV, WEBM, AVI, 3GP, FLV, MPEG UploadProductImageRequest: type: object properties: data: type: string format: binary contentMediaType: application/octet-stream description: |- The local image file to be uploaded. **Note**: - Supported formats: JPG, JPEG, PNG, WEBP, HEIC, BMP - Zero-byte files are rejected. - Max size: 10MB - Dimensions: [100x100 px, 20000x20000 px] - For `use_case=MAIN_IMAGE`, the dimensions must be between 300x300 px and 4000x4000 px. - For `use_case=SIZE_CHART_IMAGE`, the dimension must be at least 1024 px on the shorter side. use_case: type: string enum: - MAIN_IMAGE - ATTRIBUTE_IMAGE - DESCRIPTION_IMAGE - CERTIFICATION_IMAGE - SIZE_CHART_IMAGE - CUSTOMIZATION_IMAGE x-enum-descriptions: - An image displayed in the product image gallery. - An image that represents a product variant (e.g. color). - An image used within the product description. - An image to provide supporting information to meet TikTok Shop requirements for listing restricted products (e.g., images of certifications, product packaging, labeling). - An image that displays the product's measurement details. - Images used for POD product customization, such as background images, mask images, or default images configured for customizable areas. These images are used to render or preview consumer-customizable product content. description: |- The usage scenario of the image. Possible values: - MAIN_IMAGE: An image displayed in the product image gallery. - ATTRIBUTE_IMAGE: An image that represents a product variant (e.g. color). - DESCRIPTION_IMAGE: An image used within the product description. - CERTIFICATION_IMAGE: An image to provide supporting information to meet TikTok Shop requirements for listing restricted products (e.g., images of certifications, product packaging, labeling). - SIZE_CHART_IMAGE: An image that displays the product's measurement details. - CUSTOMIZATION_IMAGE: Images used for POD product customization, such as background images, mask images, or default images configured for customizable areas. These images are used to render or preview consumer-customizable product content. **Note**: Images for use cases `MAIN_IMAGE` and `ATTRIBUTE_IMAGE` that do not fit within the 3:4 to 4:3 aspect ratio range will be automatically converted to 1:1. required: - data UploadProductImageResponse: 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/UploadProductImageResponseData" UploadProductImageResponseData: type: object properties: uri: type: string description: |- The URI to identify the image in API requests and responses. Pass this value when creating or editing a product to associate the image with the product. url: type: string description: |- The URL to access and view the image. Use this URL in product descriptions by embedding it within an HTML `` tag. height: type: integer format: int64 description: The height of the image after aspect ratio adjustment. width: type: integer format: int64 description: The width of the image after aspect ratio adjustment. use_case: type: string enum: - MAIN_IMAGE - ATTRIBUTE_IMAGE - DESCRIPTION_IMAGE - CERTIFICATION_IMAGE - SIZE_CHART_IMAGE - CUSTOMIZATION_IMAGE description: |- The usage scenario specified during upload. Possible values: - MAIN_IMAGE - ATTRIBUTE_IMAGE - DESCRIPTION_IMAGE - CERTIFICATION_IMAGE - SIZE_CHART_IMAGE - CUSTOMIZATION_IMAGE UploadProofOfDeliveryFileRequest: type: object properties: data: type: string format: binary contentMediaType: application/octet-stream description: |- PDF file data to be uploaded to TikTok Shop. Prerequisites： - Only `PDF` file format is supported. - Original file size must not exceed 10MB. name: type: string description: The name of the uploaded file. The file name must include the file type. required: - data - name UploadProofOfDeliveryFileResponse: 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/UploadProofOfDeliveryFileResponseData" UploadProofOfDeliveryFileResponseData: type: object properties: url: type: string description: The URL returned from uploading the file that can be directly opened in a browser. name: type: string description: The name of the file. UploadProofOfDeliveryImageRequest: type: object properties: data: type: string format: binary contentMediaType: application/octet-stream description: |- The image file to upload as binary data in this multipart/form-data field. Requirements: - Format: `JPG`, `JPEG`, or `PNG`. - Resolution: between 100 x 100 and 20,000 x 20,000 pixels. - File size: no more than 5 MB. required: - data UploadProofOfDeliveryImageResponse: 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/UploadProofOfDeliveryImageResponseData" UploadProofOfDeliveryImageResponseData: type: object properties: url: type: string description: The URL returned from uploading the image that can be directly opened in a browser. height: type: integer format: int64 description: |- The image height returned from uploading the image. This height refers to the processed image height, not the original image height. Units: pixels. width: type: integer format: int64 description: |- The image width returned from uploading the image. This width refers to the processed image width, not the original image width. Units: pixels. UploadReturnShippingInformationRequest: type: object properties: return_shipping_label: type: string format: binary contentMediaType: application/octet-stream description: Return shipping label. return_qr_code: type: string format: binary contentMediaType: application/octet-stream description: Return QR code. tracking_number: type: string description: The return shipping tracking number provided by the seller to the buyer. return_provider_id: type: string description: The return shipping provider ID provided by the seller to the buyer. required: - tracking_number - return_provider_id UploadReturnShippingInformationResponse: 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/UploadReturnShippingInformationResponseData" UploadReturnShippingInformationResponseData: type: object properties: {} UploadShoppablePhotoFileRequest: type: object properties: data: type: string format: binary contentMediaType: application/octet-stream description: |- The local image file to upload. Requirements: - Supported formats: JPG, JPEG, PNG, WEBP, HEIC, BMP - Zero-byte files are rejected. - Maximum file size: 10 MiB (10,485,760 bytes). - Aspect ratio: 9:16 to 16:9 required: - data UploadShoppablePhotoFileResponse: 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/UploadShoppablePhotoFileResponseData" UploadShoppablePhotoFileResponseData: type: object properties: photo_file: $ref: "#/components/schemas/UploadShoppablePhotoFileResponseDataPhotoFile" description: Photo Info UploadShoppablePhotoFileResponseDataPhotoFile: type: object properties: photo_uri: type: string description: In [Post Shoppable Photos], use this photo URI to fill photo_file_uris field UploadShoppableVideoFileRequest: type: object properties: data: type: string format: binary contentMediaType: application/octet-stream description: |- The local file to be uploaded. Note： - For files larger than 10 MB, use the [Large File Uploads](https://partner.tiktokshop.com/docv2/page/wfi3nz36). - Supported formats: MP4, MOV, MKV, WMV, WEBM, AVI, 3GP, FLV, MPEG - Max video size: 10 MB - Video aspect ratio: 9:16 to 16:9 Recommendations for product videos: - Resolution: 720p or higher - Duration: > 30 seconds required: - data UploadShoppableVideoFileResponse: 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/UploadShoppableVideoFileResponseData" UploadShoppableVideoFileResponseData: type: object properties: video_file: $ref: "#/components/schemas/UploadShoppableVideoFileResponseDataVideoFile" description: Video file information. UploadShoppableVideoFileResponseDataVideoFile: type: object properties: id: type: string description: The id from of the uploaded video file. md5: type: string description: Upload file md5 checksum UsageLimit: type: object properties: single_buyer_claim_limit: type: integer format: int64 description: The number of times a single buyer can claim the coupon. total_claim_limit: type: integer format: int64 description: The total number of claims allowed for the coupon across all buyers. redemption_limit: type: integer format: int64 description: The number of times that a claimed coupon can be redeemed across all buyers. (Only available in ID, MY, PH, TH, SG, VN regions.) Value: type: object properties: id: type: string description: The ID of a built-in product attribute value, retrieved from the [Get Attributes API](https://partner.tiktokshop.com/docv2/page/6509c5784a0bb702c0561cc8). name: type: string maxLength: 2000 description: |- A self-defined custom product attribute value if the built-in values do not satisfy your needs. The system will auto-generate an ID after listing. **Note**: - No duplicates allowed under the same attribute. - Max length: 2000 characters Video: type: object properties: id: type: string description: |- The ID of the product video. Use the [Upload Product File API](https://partner.tiktokshop.com/docv2/page/6509dffdc16ffe02b8dc10c5) to upload the video first and obtain the corresponding file ID. required: - id VideoAttributedGmv: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). VideoGmv: type: object properties: currency: type: string description: The currency code. amount: type: string description: The total video GMV associated with the creator. VideoIndirectGmv: type: object properties: amount: type: string description: Amount in the corresponding currency. currency: type: string description: Currency code (ISO 4217 standard). VideoPrecheckResultWebhook: type: object properties: type: type: integer const: 55 description: The ID of the webhook type. tts_notification_id: type: string description: The ID of the notification. creator_open_id: type: string description: The open_id of the creator. To get the value, see [Authorization overview](authorization-overview-202407). timestamp: type: integer format: int64 description: The UNIX timestamp when this webhook was triggered. data: $ref: "#/components/schemas/VideoPrecheckResultWebhookData" required: - type VideoPrecheckResultWebhookData: type: object properties: precheck_task_id: type: string description: ID of precheck task generated by TikTok Shop. result: type: string enum: - PASS - FAIL description: |- Possible enumerations: `PASS` `FAIL` issues: type: array items: $ref: "#/components/schemas/VideoPrecheckResultWebhookDataIssue" description: Only if the `result` is `FAIL` VideoPrecheckResultWebhookDataIssue: type: object properties: risk: type: string description: Risk type. suggestion: type: string description: Suggestions on how to fix the risk. Warning: type: object properties: message: type: string description: Warning information that needs attention. Review and address it when applicable. Its presence alone does not mean `check_result` is `FAILED`. WebhookEvent: oneOf: - $ref: "#/components/schemas/ActivityChangeWebhook" - $ref: "#/components/schemas/ActivityStatusChangeWebhook" - $ref: "#/components/schemas/AftersalesRequestStatusUpdateWebhook" - $ref: "#/components/schemas/AppealCompletedWebhook" - $ref: "#/components/schemas/CancellationStatusChangeWebhook" - $ref: "#/components/schemas/CombinedListingChangeWebhook" - $ref: "#/components/schemas/CreatorDeauthorizationWebhook" - $ref: "#/components/schemas/FBTInventoryUpdateWebhook" - $ref: "#/components/schemas/FBTMerchantOnboardingWebhook" - $ref: "#/components/schemas/GetFBTMCFOrderStatusWebhook" - $ref: "#/components/schemas/GlobalListingMethodChangeWebhook" - $ref: "#/components/schemas/GlobalReplicationStatusChangeWebhook" - $ref: "#/components/schemas/GoodsMatchWebhook" - $ref: "#/components/schemas/ImageTranslationCompletedWebhook" - $ref: "#/components/schemas/InboundFBTOrderStatusChangeWebhook" - $ref: "#/components/schemas/InventoryChangedByShopWebhook" - $ref: "#/components/schemas/InventoryStatusChangeWebhook" - $ref: "#/components/schemas/InvoiceStatusChangeWebhook" - $ref: "#/components/schemas/NewConversationWebhook" - $ref: "#/components/schemas/NewMessageListenerWebhook" - $ref: "#/components/schemas/NewMessageWebhook" - $ref: "#/components/schemas/OpportunityMatchingStatusChangeWebhook" - $ref: "#/components/schemas/OrderStatusChangeWebhook" - $ref: "#/components/schemas/PackageUpdateWebhook" - $ref: "#/components/schemas/ProductAuditStatusChangeWebhook" - $ref: "#/components/schemas/ProductCategoryChangeWebhook" - $ref: "#/components/schemas/ProductCreationWebhook" - $ref: "#/components/schemas/ProductInformationChangeWebhook" - $ref: "#/components/schemas/ProductPackageRecommendedWebhook" - $ref: "#/components/schemas/ProductStatusChangeWebhook" - $ref: "#/components/schemas/RMAStatusUpdateWebhook" - $ref: "#/components/schemas/RecipientAddressUpdateWebhook" - $ref: "#/components/schemas/RefundSuccessWebhook" - $ref: "#/components/schemas/ReturnStatusChangeWebhook" - $ref: "#/components/schemas/SKUStatusChangeWebhook" - $ref: "#/components/schemas/SampleApplicationStatusChangeWebhook" - $ref: "#/components/schemas/SellerDeauthorizationWebhook" - $ref: "#/components/schemas/ShoppableContentPostingWebhook" - $ref: "#/components/schemas/ShoppableVideoPrecheckTasksResultWebhook" - $ref: "#/components/schemas/SizeChartChangeWebhook" - $ref: "#/components/schemas/StrikethroughPriceExpiredWebhook" - $ref: "#/components/schemas/TokopediaMirrorStatusChangeWebhook" - $ref: "#/components/schemas/UpcomingAuthorizationExpirationWebhook" - $ref: "#/components/schemas/VideoPrecheckResultWebhook" Weight: type: object properties: value: type: string description: The numerical value of the package weight. unit: type: string enum: - GRAM - POUND description: |- The unit of measurement for the package weight. Available values: - `GRAM` - `POUND` parameters: ShopCipher: name: shop_cipher in: query required: true description: Identifies the shop. Obtain it from the Get Authorized Shops API. schema: type: string securitySchemes: accessToken: type: apiKey in: header name: x-tts-access-token description: Access token obtained through the TikTok Shop authorization flow. webhookSignature: type: apiKey in: header name: Authorization description: "Sent by TikTok Shop with every webhook: the lowercase hexadecimal HMAC-SHA256 of app_key followed by the raw request body, keyed with the app secret. Not a bearer token. Verify it against the raw body before parsing." x-tts-signing: params: - app_key - timestamp - sign algorithm: HMAC-SHA256 docs: https://partner.tiktokshop.com/docv2/page/678e3a4278f4c20311b8b57e x-tts-webhook-signing: header: Authorization algorithm: HMAC-SHA256 signedContent: app_key + raw request body key: app_secret encoding: lowercase hex docs: https://partner.tiktokshop.com/docv2/page/tts-webhooks-overview