Skip to content
TikTok Shop Partner API

Edit Product

PUT
/product/202509/products/{product_id}

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 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 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, Update Inventory API, or the Update Price API.
  • 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).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
product_id
required
string

The product ID generated by TikTok Shop.

Query Parameters

Section titled “Query Parameters”
shop_cipher
required
string

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

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
save_mode

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.
string
Allowed values: AS_DRAFT LISTING
description
required

The product description in HTML format.

Note:

  • The content must conform to the HTML syntax. 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 <table> tags as images.
  • Max length: 10,000 characters.
  • Image guidelines: You must use TikTok Shop image URLs. Max 30 <img> 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.
string
<= 10000 characters
category_id
required

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 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.
string
brand_id

The ID of the brand of this product. Use the Get Brands API to get the list of available brands for a shop.

Note: Unauthorized brands won’t be displayed on TikTok Shop.

string
main_images
required

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 to change the background to white
Array<object>
<= 9 items
object
uri
required

The URI of the image. Obtain this URI by uploading the images through the Upload Product Image API with use_case=MAIN_IMAGE. You can use the returned URI directly, or process it through the Optimize Images API first and use the resulting URI.

string
skus
required

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.

Array<object>
object
id

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.
string
sales_attributes

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.
Array<object>
object
id

The ID of a built-in sales attribute, retrieved from Get Attributes API.

string
name

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
string
<= 20 characters
value_id

The ID of a built-in sales attribute value, retrieved from the Get Attributes API.

string
value_name

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.
string
<= 50 characters
sku_img

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.

object
uri
required

The URI of the image. Obtain this URI by uploading the images through the Upload Product Image API with use_case=ATTRIBUTE_IMAGE.

string
supplementary_sku_images

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.
Array<object>
object
uri
required

The URI of the image. Obtain this URI by uploading the images through the Upload Product Image API with use_case=ATTRIBUTE_IMAGE.

string
seller_sku

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
string
price

SKU pricing information.

Note: If you omit this object in the API request, the existing information will remain unchanged.

object
amount

Local sellers/Intra-EU sellers 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.

string
currency
required

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
string
Allowed values: BRL EUR GBP IDR JPY MXN MYR PHP SGD THB USD VND
sale_price

Global sellers 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.

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.
string
starting_bid_price

Starting bit price for auction product

string
external_sku_id

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

string
<= 999 characters
identifier_code

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.

object
code

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.
string
type

The type of identifier code. Possible values:

  • GTIN
  • EAN
  • UPC
  • ISBN
  • JAN
string
Allowed values: GTIN EAN UPC ISBN JAN
inventory

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.
Array<object>
object
warehouse_id
required

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.

string
quantity

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.

integer format: int64
>= 1 <= 99999
backorder_quantity

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.
integer format: int64
handling_time

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.

integer format: int64
combined_skus

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

Array<object>
object
product_id
required

The ID of the source product included in the virtual bundle.

string
sku_id
required

The ID of the source SKU included in the virtual bundle.

string
sku_count
required

The quantity of the source SKU included in the virtual bundle.

integer format: int64
sku_unit_count

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. The unit price would then be returned in the Get Product API.
string
external_urls

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

Array<string>
extra_identifier_codes

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.
Array<string>
pre_sale

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 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.
object
type

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.
string
Allowed values: PRE_ORDER MADE_TO_ORDER CUSTOM NONE
fulfillment_type

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.

object
handling_duration_days

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.
integer format: int64
release_date

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.

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.
integer format: int64
list_price

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.

object
amount
required

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.

string
currency
required

The currency. Possible values: USD

string
Allowed values: USD
external_list_prices

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.

Array<object>
object
source
required

The external ecommerce platform from which the price is sourced. Possible values:

  • SHOPIFY_COMPARE_AT_PRICE: The compare_at_price in Shopify.
string
Allowed values: SHOPIFY_COMPARE_AT_PRICE
amount
required

The price amount. Valid range: [0.01, 7600]

string
currency
required

The currency. Possible values: USD

string
Allowed values: USD
fees

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.

Array<object>
object
type

The type of fee. Possible values: PFAND

string
Allowed values: PFAND
amount

The fee amount. Valid range:

  • PFAND: [0.00 - 6300.00]
string
additional_attribute

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
string
Allowed values: SINGLE_USE REUSABLE NOT_APPLICABLE
sku_dimensions

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.
object
length
required

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.

string
width
required

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.

string
height
required

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.

string
unit
required

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.

string
sku_weight

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.
object
value
required

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
string
unit
required

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.

string
title
required

The product title. Title length:

  • DE, ES, FR, IE, IT, JP, UK, US: [1, 255]
  • BR, MX: [1, 300]
  • Other regions: [25, 255]
string
is_cod_allowed

A flag indicating whether to show the Cash On Delivery (COD) payment option during checkout. Use the Get Category Rules API 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.

boolean
certifications

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. Refer to TikTok Shop Restricted Products Policy for information on product category restrictions.

Array<object>
<= 10 items
object
id
required

The ID to identify the type of certification required for the product category. Retrieve this value from the Get Category Rules API.

string
images

A list of certification related images.

Array<object>
object
uri
required

The URI of the image. Obtain this URI by uploading the images through the Upload Product Image API with use_case=CERTIFICATION_IMAGE.

string
files

A list of certification related files.

Array<object>
object
id
required

The ID of the certification file. Use the Upload Product File API to upload the files first and obtain the corresponding file ID.

string
name
required

The name of the certification file, including the file extension.

string
format
required

The format of the certification file. Only PDF is supported.

string
expiration_date

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 to find out the requirements.

integer format: int64
package_weight

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, 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.
object
value
required

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
string
unit
required

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.

string
product_attributes

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 to avoid listing failure.

Array<object>
object
id
required

The ID of the product attribute, retrieved from the Get Attributes API.

string
values
required

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.

Array<object>
object
id

The ID of a built-in product attribute value, retrieved from the Get Attributes API.

string
name

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
string
<= 2000 characters
metric_standard_info

Defines the measurement template information used to describe the measurement standards and metric values configured for the product.

object
id

The unique ID of the measurement template. Use this ID to identify which measurement standard template applies to the product.

string
metric_value_module_infos

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.

Array<object>
object
id

The unique ID of a metric item within the measurement template. This ID identifies which metric the submitted value belongs to.

string
value

The seller-provided value for the specified metric item in the measurement template.

string
unit_id

Metric value module unit id.

string
size_chart

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 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.
object
image

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.
object
uri
required

The URI of the image. Obtain this URI by uploading the images through the Upload Product Image API with use_case=CERTIFICATION_IMAGE.

string
template

A TikTok Shop size chart template generated by the size chart tool in Seller Center > Manage Products > Bulk action > Batch manage size charts.

object
id
required

The size chart template ID.

string
package_dimensions

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.
object
length
required

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.

string
width
required

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.

string
height
required

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.

string
unit
required

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.

string
external_product_id

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

string
<= 999 characters
delivery_option_ids

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 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.
Array<string>
video

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
object
id
required

The ID of the product video. Use the Upload Product File API to upload the video first and obtain the corresponding file ID.

string
category_version

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
string
manufacturer_ids

A list of manufacturer IDs. Retrieve the IDs from the Search Manufacturers API.

Note: Applicable only for the EU market in certain categories. Use the Get Category Rules API to check the requirements.

Array<string>
responsible_person_ids

A list of responsible person IDs. Retrieve the IDs from the Search Responsible Persons API.

Note: Applicable only for the EU market in certain categories. Use the Get Category Rules API to check the requirements.

Array<string>
listing_platforms

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.
Array<string>
Allowed values: TOKOPEDIA TIKTOK_SHOP
shipping_insurance_requirement

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.

string
Allowed values: REQUIRED OPTIONAL NOT_SUPPORTED
is_pre_owned

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.

boolean
minimum_order_quantity

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.

integer format: int64
>= 1 <= 20
replicated_products

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.

Array<object>
object
region
required

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
string
Allowed values: DE ES FR GB ID IE IT JP MY PH SG TH US VN
skus

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.
Array<object>
object
id

The SKU ID generated by TikTok Shop. Provide this for existing SKUs.

string
seller_sku

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
string
price
required

The SKU’s local display price shown on the product page before any discounts.

object
currency
required

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
string
Allowed values: EUR GBP IDR JPY MYR PHP SGD THB USD VND
sale_price
required

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.

string
inventory

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.

Array<object>
object
warehouse_id

The warehouse ID. Retrieve this value from the Get Warehouse List API 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.

string
quantity

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.

integer format: int64
>= 1 <= 999999
inventory_mode

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.

string
subscribe_info_edit

All the editable Save and Subscribe promotion info associated with the given product.

object
subscribe_status

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.

string
discount_details

All of the Save and Subscribe discount details.

Array<object>
object
discount_level

An enum that communicated the type of discount:

  • REGULAR
  • FIRST_ORDER
  • RETENTION
string
discount_value

The value of the discount. A value of 10, would indicate a 10% discount.

integer format: int64
shipping_template_id

Identifier of the shipping template that will be bound to the product

string
scheduled_sale

Scheduled listing configuration for the product, including whether scheduled listing is enabled and the scheduled listing time.

object
is_enabled_scheduled_sale
required

Whether scheduled listing is enabled for this product. If true, schedule_sale_time must be provided.

boolean
schedule_sale_time
required

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.

integer format: int64
locale

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
string
Allowed 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

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.

boolean
search_terms

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.

Array<string>
key_product_features

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.

Array<string>
<= 5 items
inventory_mode

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.

string
product_tag_operations

Legacy operations for enabling or disabling the AUCTION product tag. If selling_format is provided, it takes precedence over this field.

Array<object>
object
product_tag
required

Possible values: AUCTION

string
Allowed values: AUCTION
enable
required

Whether to enable the specified product tag. Set to true to enable the AUCTION tag or false to disable it.

boolean
purchase_order_quantity_limit

Purchase quantity limits applied to each SKU of the product, including the maximum quantity per order and the cumulative quantity across orders.

object
maximum_order_quantity

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.

integer format: int64
cumulative_order_quantity

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

integer format: int64
selling_format

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.

string
Allowed values: FIXED_PRICE FIXED_PRICE_AND_LIVE_AUCTION
is_live_quick

False — NORMAL products true — LIVE_QUICK products. Only seller with the required permissions can creat LIVE_QUICK products. Default: false

boolean
is_blind_box

Whether the product is a blind box of lucky bag. For example: PopMart

boolean
Example
{
  "save_mode": "AS_DRAFT",
  "description": " <p>Please compare above detailed size with your measurement before purchase.</p>\n<ul> \n  <li>M-Size</li>\n  <li>XL-Size</li>\n</ul> \n<img src=\"https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/181595ea7d26489284b5667488d708c1~tplv-o3syd03w52-origin-jpeg.jpeg?from=1432613627\" width='100' height='100' />",
  "category_id": "600001",
  "brand_id": "7082427311584347905",
  "main_images": [
    {
      "uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
    }
  ],
  "skus": [
    {
      "id": "1729592969712207000",
      "sales_attributes": [
        {
          "id": "100089",
          "name": "Specification",
          "value_id": "1729592969712401100",
          "value_name": "XL",
          "sku_img": {
            "uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
          },
          "supplementary_sku_images": [
            {
              "uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
            }
          ]
        }
      ],
      "seller_sku": "Color-Red-XM001",
      "price": {
        "amount": "1.21",
        "currency": "USD",
        "sale_price": "1.21",
        "starting_bid_price": "2.3"
      },
      "external_sku_id": "1729592969712207012",
      "identifier_code": {
        "code": "12345678901234",
        "type": "GTIN"
      },
      "inventory": [
        {
          "warehouse_id": "7068517275539719942",
          "quantity": 999,
          "backorder_quantity": 888,
          "handling_time": 5
        }
      ],
      "combined_skus": [
        {
          "product_id": "1729582718312380123",
          "sku_id": "2729382476852921560",
          "sku_count": 2
        }
      ],
      "sku_unit_count": "100.00",
      "external_urls": [
        "https://example.com/path1",
        "https://example.com/path2"
      ],
      "extra_identifier_codes": [
        "00012345678905",
        "9780596520687"
      ],
      "pre_sale": {
        "type": "PRE_ORDER",
        "fulfillment_type": {
          "handling_duration_days": 7,
          "release_date": 1619611761
        }
      },
      "list_price": {
        "amount": "1",
        "currency": "USD"
      },
      "external_list_prices": [
        {
          "source": "SHOPIFY_COMPARE_AT_PRICE",
          "amount": "1",
          "currency": "USD"
        }
      ],
      "fees": [
        {
          "type": "PFAND",
          "amount": "1.01",
          "additional_attribute": "SINGLE_USE"
        }
      ],
      "sku_dimensions": {
        "length": "10",
        "width": "10",
        "height": "10",
        "unit": "CENTIMETER"
      },
      "sku_weight": {
        "value": "1.32",
        "unit": "KILOGRAM"
      }
    }
  ],
  "title": "Men's Fashion Sports Low Cut Cotton Breathable Ankle Short Boat Invisible Socks\n",
  "is_cod_allowed": false,
  "certifications": [
    {
      "id": "7182427311584347905",
      "images": [
        {
          "uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
        }
      ],
      "files": [
        {
          "id": "v09e40f40000cfu0ovhc77ub7fl97k4w",
          "name": "Certificate.pdf",
          "format": "PDF"
        }
      ],
      "expiration_date": 1741235456
    }
  ],
  "package_weight": {
    "value": "1.32",
    "unit": "KILOGRAM"
  },
  "product_attributes": [
    {
      "id": "100392",
      "values": [
        {
          "id": "1001533",
          "name": "Birthday",
          "metric_standard_info": {
            "id": "7678592839487784712",
            "metric_value_module_infos": [
              {
                "id": "7678592839487735560",
                "value": "2026",
                "unit_id": "7678592839484720903"
              }
            ]
          }
        }
      ]
    }
  ],
  "size_chart": {
    "image": {
      "uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
    },
    "template": {
      "id": "7267563252536723205"
    }
  },
  "package_dimensions": {
    "length": "10",
    "width": "10",
    "height": "10",
    "unit": "CENTIMETER"
  },
  "external_product_id": "172959296971220002",
  "delivery_option_ids": [
    "1729592969712203232"
  ],
  "video": {
    "id": "v09e40f40000cfu0ovhc77ub7fl97k4w"
  },
  "category_version": "v1",
  "manufacturer_ids": [
    "172959296971220002"
  ],
  "responsible_person_ids": [
    "172959296971220003"
  ],
  "listing_platforms": [
    "TIKTOK_SHOP"
  ],
  "shipping_insurance_requirement": "REQUIRED",
  "is_pre_owned": false,
  "minimum_order_quantity": 1,
  "replicated_products": [
    {
      "region": "US",
      "skus": [
        {
          "id": "1729592969712207001",
          "seller_sku": "Color-Red-XM002",
          "price": {
            "currency": "USD",
            "sale_price": "1.21"
          },
          "inventory": [
            {
              "warehouse_id": "7068517275539719942",
              "quantity": 999
            }
          ]
        }
      ],
      "inventory_mode": "SHARED"
    }
  ],
  "subscribe_info_edit": {
    "subscribe_status": "ENABLED",
    "discount_details": [
      {
        "discount_level": "REGULAR",
        "discount_value": 10
      }
    ]
  },
  "shipping_template_id": "7552764259994699538",
  "scheduled_sale": {
    "is_enabled_scheduled_sale": false,
    "schedule_sale_time": 1768899145000
  },
  "locale": "en-US",
  "auto_translate_enabled": false,
  "search_terms": [
    "sneakers",
    "running shoes",
    "athletic"
  ],
  "key_product_features": [
    "Breathable mesh upper",
    "Cushioned foam midsole"
  ],
  "inventory_mode": "SHARED",
  "product_tag_operations": [
    {
      "product_tag": "AUCTION",
      "enable": false
    }
  ],
  "purchase_order_quantity_limit": {
    "maximum_order_quantity": 2,
    "cumulative_order_quantity": 20
  },
  "selling_format": "FIXED_PRICE_AND_LIVE_AUCTION",
  "is_live_quick": false,
  "is_blind_box": false
}

Responses

Section titled “Responses”

200

Section titled “200”

Success

Media typeapplication/json
object
code

Status code; 0 means success.

integer format: int64
message

Success or failure message.

string
request_id

Request log ID.

string
data
object
product_id

The product ID generated by TikTok Shop.

string
skus

A list of Stock Keeping Units (SKUs) used to identify distinct variants of the product.

Array<object>
object
id

The SKU ID generated by TikTok Shop. One product can contain multiple SKU IDs.

string
seller_sku

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
string
sales_attributes

A list of attributes (e.g. size, color, length) that define each variant of a product.

Array<object>
object
id

The sales attribute ID. If you included the custom sales attribute name in the request, this is a newly generated ID.

string
value_id

The sales attribute value ID. If you included the custom sales attribute value name in the request, this is a newly generated ID.

string
external_sku_id

An external identifier used in an external ecommerce platform. This is used to associate the SKU between TikTok Shop and the external ecommerce platform.

string
fees

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.

Array<object>
object
type

The type of fee. Possible values: PFAND

string
Allowed values: PFAND
amount

The fee amount. Valid range:

  • PFAND: [0.00 - 6300.00]
string
additional_attribute

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
string
Allowed values: SINGLE_USE REUSABLE NOT_APPLICABLE
warnings

Warning information that the API caller needs to pay special attention to.

Array<object>
object
message

Warning information that needs attention. Review and address it when applicable. Its presence alone does not mean check_result is FAILED.

string
audit

Product audit information. Note: Applicable only to products listed on TikTok Shop. Not applicable for products listed only on Tokopedia.

object
status

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.
string
Allowed values: NONE AUDITING APPROVED
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"
}
DocsSDKsAPI Reference

Start here

Getting StartedConceptsAuthorizationWebhooksErrors

SDKs

Choose an SDK

OpenAPI

The spec