API reference / TikTok Shop / Shop browse flow

Shop browse flow

Execute an organic Shop tab → Mall → search → PDP browse sequence.

POSTapi.tikultra.com/v1/shop/browsePremium · 25 credits

Upstream: /api/v1/mall/shop_tab/algorithm/reach/get/api/v1/mall/homepage/bff/get/api/v2/shop/sdui_pdp/get
Access: Every plan
Runs on: LeanPool · android · tiktok · 47.5.41
Client: os, app_flavour, app_version overrides
Billing: Failed calls are free

Authorization & parameters

x-api-keyheader · stringrequired

Your API key. Create one in API keys.

Body

Send JSON with content-type: application/json.

keywordstring

Shop search keyword. For example mechanical keyboard.

product_idstring

Optional target product ID to inspect. For example 1729384756192837461.

regionstring

Two-letter country code for egress and storefront. For example US.

citystring

A city in that region. See the supported cities list. For example miami.

Client and egress

Optional. Leave them out to run as android · tiktok · 47.5.41 from the default LeanPool context. See Clients and versions.

osstring

android or ios. For example android.

app_flavourstring

Run as tiktok, lite, lite_coin, pro, studio, shop, tv, douyin. For example tiktok.

app_versionstring

A release of that app. Defaults to the current default for (os, app_flavour). For example 47.5.41.

regionstring

Two-letter country code for egress. For example US.

citystring

A supported city in that region. For example miami.

Response

A 200 returns JSON with stable field names. Every response carries x-credits-cost, x-credits-tier and x-credits-remaining.

Response fields

Key top-level and nested fields decoded from the mobile upstream payload:

status_codeinteger

Upstream TikTok mobile status code (0 indicates success).

regionstring

Two-letter ISO 3166-1 country code associated with the item or context.

citystring

City-level egress or location identifier.

keywordstring

Decoded keyword value.

steps_executedstring[]

Decoded steps executed value.

mall_bannersinteger

Decoded mall banners value.

matched_productsobject[]

List of matched products objects.

matched_products[].product_idstring

TikTok Shop product identifier.

matched_products[].titlestring

Decoded title value.

matched_products[].pricestring

Formatted and numeric price breakdown with currency.

matched_products[].currencystring

Decoded currency value.

matched_products[].sold_countinteger

Total sold count.

matched_products[].ratingnumber

Decoded rating value.

inspected_pdpobject

Structured inspected pdp metadata.

inspected_pdp.product_idstring

TikTok Shop product identifier.

inspected_pdp.seller_idstring

TikTok Shop merchant / seller identifier.

inspected_pdp.sku_countinteger

Total sku count.

inspected_pdp.in_stockboolean

Whether in stock is enabled or true.

took_msinteger

Gateway execution or signing latency in milliseconds.

log_pbobject

Upstream request trace envelope from the mobile gateway.

log_pb.impr_idstring

Upstream TikTok impression / trace identifier.

Errors

Errors return a JSON body with a stable code and cost 0 credits. See Errors and retries.

import os from tikultra import TikUltra with TikUltra(api_key=os.environ["TIKULTRA_KEY"], region="US", city="miami") as client: res = client.shop.browse(keyword="mechanical keyboard", product_id="1729384756192837461") print(res.credits_cost, res.data)

{ "status_code": 0, "region": "US", "city": "miami", "keyword": "mechanical keyboard", "steps_executed": [ "shop_tab_reach", "mall_homepage_bff", "ecom_search_pack", "sdui_pdp_inspect" ], "mall_banners": 3, "matched_products": [ { "product_id": "1729384756192837461", "title": "Low-profile mechanical keyboard 75% CNC Aluminum", "price": "79.99", "currency": "USD", "sold_count": 18204, "rating": 4.8 } ], "inspected_pdp": { "product_id": "1729384756192837461", "seller_id": "7495000000000000001", "sku_count": 2, "in_stock": true }, "took_ms": 1420, "log_pb": { "impr_id": "202611120200419F8E7D6C5B4A3210" } }