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 to obtain more details about the product.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Identifies the shop. Obtain it from the Get Authorized Shops API.
The number of results to be returned per page. Valid range: [1-100]
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.
Request Body
Section titled “Request Body”object
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
Filter products by these seller SKU codes.
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_geis filled butcreate_time_leis empty,create_time_lewill default to the current time. - If
create_time_leis filled butcreate_time_geis empty,create_time_gewill default to the earliest shop time.
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.
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_geis filled butupdate_time_leis empty,update_time_lewill default to the current time. - If
update_time_leis filled butupdate_time_geis empty,update_time_gewill default to the earliest shop time.
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.
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 bothv1andv2category trees.
Filter products by their listing quality tier. Possible values:
- POOR
- FAIR
- GOOD
- EXCELLENT Default: Returns all Note: Available only for the US market.
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
statusvalue other thanALLwhen 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.
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.
Filter products by SKU IDs. Max count: 10
Filter products by their Subscribe and Save (SNS) status. Possible values:
- CONFIGURED
- ELIGIBLE
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.
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
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
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
Section titled “Responses”Success
object
Status code; 0 means success.
Success or failure message.
Request log ID.
object
The total number of products that meet the query conditions.
The list of products that meet the query conditions.
object
The product ID generated by TikTok Shop.
The product title.
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.
A list of Stock Keeping Units (SKUs) used to identify distinct variants of the product.
object
The SKU ID generated by TikTok Shop.
An internal code/name for managing SKUs, not visible to buyers.
SKU pricing information.
object
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
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.
Global sellers The SKU’s local display price shown on the product page before any discounts.
Starting bid price for auction product
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.
object
The ID of the warehouse where the SKU is stored. Retrieve details of the warehouse from the Get Warehouse List API.
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.
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.
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
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.
object
The price amount.
The currency. Possible values: USD
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.
object
The external ecommerce platform from which the price is sourced. Possible values:
- SHOPIFY_COMPARE_AT_PRICE: The compare_at_price in Shopify.
The price amount.
The currency. Possible values: USD
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.
object
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.
Information about the type of pre-sale order fulfillment and the corresponding timeframe.
handling_duration_daysis for fulfillment with an extended duration.release_dateis 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
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.
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.
Status information of the SKU.
object
The SKU status in TikTok Shop. Possible values:
- NORMAL
- DEACTIVATED
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.
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.
object
The type of fee. Possible values: PFAND
The fee amount. Valid range:
- PFAND: [0.00 - 6300.00]
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
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
The time when the product is created. Unix timestamp in seconds.
The time when the product is last updated. Unix timestamp in seconds.
The reasons why synchronizing of global product information to local products failed. Only applicable for cross-border sellers.
A flag indicating whether the product is not for sale. True: Not for sale. False: For sale.
Recommended categories for the product based on the product title, description, and images.
object
The ID of the recommended category.
The recommended category name in the requested locale.
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.
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.
object
The integrated platform name. Possible values:
- TOKOPEDIA
The product status in the integrated platform. Possible values:
- DRAFT
- PENDING
- FAILED
- ACTIVATE
- SELLER_DEACTIVATED
- PLATFORM_DEACTIVATED
- FREEZE
- DELETED
Product audit information for TikTok Shop.
object
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.
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.
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.
object
The product family ID.
A list of products that belong to the family.
object
The product ID.
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=trueto obtain full details of the draft.
Scheduled listing configuration for the product, including whether scheduled listing is enabled and the scheduled listing time.
object
Whether scheduled listing is enabled for this product.
The stored scheduled listing time, expressed as a Unix timestamp in milliseconds.
Product tag to identity special type product Possible values: AUCTION、LIVE_QUICK
The product’s sale format. Possible values: FIXED_PRICE, LIVE_AUCTION, FIXED_PRICE_AND_LIVE_AUCTION.
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.
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"}