Skip to content
TikTok Shop Partner API

Partial Edit Global Product

PUT
/product/202509/global_products/{global_product_id}/partial_edit

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.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
global_product_id
required
string

The global product ID generated by TikTok Shop.

Request Body

Section titled “Request Body”
Media typeapplication/json
object
title

The product title. Title length:

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

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

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

Note: Refer to TikTok Shop Academy for information on product category restrictions.

string
brand_id

The ID of the brand of this product.

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

string
main_images

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

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.

Array<object>
object
id

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

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.

integer format: int64
seller_sku

An internal code/name for managing SKUs, not visible to buyers.

  • Valid length: 1-50 characters
  • Format: Text without spaces
string
>= 1 characters <= 50 characters
price

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

The price amount. Max: 99,999,999.99

string
currency
required

The currency. Possible values:

  • USD: Applicable for global sellers
  • EUR: Applicable for intra-EU sellers
string
Allowed values: USD EUR
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 Global Attributes API.

string
name

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

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

string
value_name

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

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.

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
inventory

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.

Array<object>
<= 50 items
object
global_warehouse_id
required

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.

string
quantity
required

The SKU quantity available in the warehouse. Valid range: [1, 99,999]

integer format: int64
>= 1 <= 99999
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
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 Global Attributes API. The unit price would then be returned in the Get Global Product API.
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>
external_global_sku_id

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

string
<= 999 characters
sale_prices

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

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

The price amount. Refer to Product Pricing for the allowed price ranges in each market.

string
package_weight

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

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. 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 Global 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
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 may lead to additional shipping fees.
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
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. 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.

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
size_chart

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 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
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
manufacturer

(Deprecated: This field is deprecated and will be removed in a future API version. Use manufacturer_ids instead.)

The product manufacturer’s details.

object
name

The name of the manufacturer.

string
address

The address of the manufacturer.

string
phone_number

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.

string
email

The email address of the manufacturer.

string
manufacturer_ids

A list of manufacturer IDs. Retrieve the IDs from the Search Manufacturers API. 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 to check the requirements.

Array<string>
responsible_person_ids

A list of responsible person IDs. Retrieve the IDs from the Search Responsible Persons API. 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 to check the requirements.

Array<string>
category_version

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
string
Allowed values: v2 v1
external_global_product_id

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

string
<= 999 characters
Example
{
  "title": "Men's Fashion Sports Low Cut Cotton Breathable Ankle Short Boat Invisible Socks",
  "description": " ",
  "category_id": "600001",
  "brand_id": "7082427311584347905",
  "main_images": [
    {
      "uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
    }
  ],
  "skus": [
    {
      "id": "1782427311584347905",
      "global_quantity": 999,
      "seller_sku": "Color-Red-XM01",
      "price": {
        "amount": "1.32",
        "currency": "USD"
      },
      "sales_attributes": [
        {
          "id": "100089",
          "name": "Specification",
          "value_id": "1729592969712207000",
          "value_name": "XL",
          "sku_img": {
            "uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
          }
        }
      ],
      "inventory": [
        {
          "global_warehouse_id": "7068517275539719942",
          "quantity": 999
        }
      ],
      "identifier_code": {
        "code": "10000000000000",
        "type": "GTIN"
      },
      "sku_unit_count": "1",
      "extra_identifier_codes": [
        "12345678901234"
      ],
      "external_global_sku_id": "1234567890",
      "sale_prices": [
        {
          "region": "US",
          "amount": "100"
        }
      ]
    }
  ],
  "package_weight": {
    "value": "1.99",
    "unit": "KILOGRAM"
  },
  "certifications": [
    {
      "id": "7182427311584347905",
      "images": [
        {
          "uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
        }
      ],
      "files": [
        {
          "id": "v09ea0g40000cj91373c77u3mid3g1s0",
          "name": "SNI.PDF",
          "format": "PDF"
        }
      ]
    }
  ],
  "package_dimensions": {
    "length": "10",
    "width": "10",
    "height": "10",
    "unit": "CENTIMETER"
  },
  "product_attributes": [
    {
      "id": "100392",
      "values": [
        {
          "id": "1001533",
          "name": "Birthday"
        }
      ]
    }
  ],
  "size_chart": {
    "image": {
      "uri": "tos-maliva-i-o3syd03w52-us/c668cdf70b7f483c94dbe"
    },
    "template": {
      "id": "7267563252536723205"
    }
  },
  "video": {
    "id": "v09e40f40000cfu0ovhc77ub7fl97k4w"
  },
  "manufacturer": {
    "name": "Sample Manufacturer Name",
    "address": "123W 106th St, New York, NY, USA, 10025",
    "phone_number": "+1-2124108036\n",
    "email": "samplemanufacturer101@outlook.com"
  },
  "manufacturer_ids": [
    "67726293bf1eb1e92401a"
  ],
  "responsible_person_ids": [
    "67726293bf1eb1e92401a"
  ],
  "category_version": "v1",
  "external_global_product_id": "123456789"
}

Responses

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
global_skus

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

Array<object>
object
id

The global 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.

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_global_sku_id

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

string
<= 999 characters
publish_results

Results of syncing the changes in the edited product to markets where it is published.

Array<object>
object
region

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

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 to track subsequent audit status changes and completion.
  • FAILED: Synchronization of the global product to the local shop was unsuccessful.
string
Allowed values: SUCCESS FAILED
fail_reasons

The list of errors that occurred.

Array<object>
object
message

The error message.

string
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"
}
DocsSDKsAPI Reference

Start here

Getting StartedConceptsAuthorizationWebhooksErrors

SDKs

Choose an SDK

OpenAPI

The spec