TikTok Shop API Reference

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

id

string

An internal identifier for the TikTok Shop

name

string

The TikTok Shop name

cipher

string

An encrypted token used to securely identify a shop in API requests. There is no need for decryption on the receiving end

code

string

The TikTok Shop code, which is also displayed on Seller Center

region

string

The region of the shop

seller_type

string

The type of seller. Possible values: - CROSS_BORDER: Cross border sellers with multiple shops in different countries. - LOCAL: Local sellers with only 1 shop

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

address

string

The webhook URL used to receive the event data

create_time

timestamp

The time when the webhook was created

event_type

string

The topic of the webhook event. Possible values: - 'ORDER_STATUS_CHANGE': Triggers on each order status update, from new order placement through all subsequent status changes. See [Order Status change](650300b8a57708028b430b4a). - 'RECIPIENT_ADDRESS_UPDATE': Triggers when the recipient's address is updated. See [Receipient address update](650301af5a12ff0294ea3bf9). - 'PACKAGE_UPDATE': Triggers when a package is updated (e.g., combined, split, or address changed). See [Package update](650955cabace3e02b73cc886). - 'PRODUCT_STATUS_CHANGE': Triggers when product audit results are updated. See [Product status change](650956aff1fd3102b90b6261). - 'SELLER_DEAUTHORIZATION': Triggers when a seller is deauthorized to inform developers and avoid misunderstandings about platform authorization issues. See [Seller deauthorization](65095746defece02be4d749d). - 'UPCOMING_AUTHORIZATION_EXPIRATION': Triggers 30 days before authorization expiration, with daily notifications at 0:00 until re-authorization is completed. See [Upcoming authorization expiration](6509579c0fcef602bf11312c). - 'CANCELLATION_STATUS_CHANGE': Triggers when an order's cancellation status changes. See [Cancellation status change](65030150746462028285f657). - 'RETURN_STATUS_CHANGE': Triggers when an order's return status changes. See [Return status change](65030162bb2a4d028d50cc51). - 'NEW_CONVERSATION': Triggers when a customer service agent joins or leaves a conversation. See [New conversation](6614330bfe9fdc02e002abfd). - 'NEW_MESSAGE': Triggers when a new message is sent in a customer service conversation. See [New Message](66143486ef8a1202dc323258). - 'PRODUCT_INFORMATION_CHANGE': Triggers when changes to a product's title, description, main images, or attributes go live. See [Product information change](65d6f41411a60f02dc1cf8bf). - 'PRODUCT_CREATION': Triggers when a new product is created. See [Product creation](663c98b566828e02e4515580). - 'PRODUCT_CATEGORY_CHANGE': Triggers when the category of a product is changed. See [Product category change](668764a371f16d02eef1f393). - 'NEW_MESSAGE_LISTENER': Triggers when a creator sends a message to the seller. See [New message listener](6790b76eb59cf9030997b783). - 'INVOICE_STATUS_CHANGE': Triggers when the status of an invoice upload changes after using the [POST Upload Invoice](67b542559a140004b343984f) endpoint. See [Invoice Status Change](67b68ca185619104a6772e5d). - 'PRODUCT_AUDIT_STATUS_CHANGE': Triggers when the product audit status changes. See [Product audit status change](67b5c6cba42623049abe5062). - 'REVERSE_STATUS_UPDATE': Triggers when buyer raises cancellation, refund only, or return & refund requests that need the seller to accept or reject. See [Reverse Status Update](https://partner.tiktokshop.com/doc/page/63fd7459715d622a338c5437)

update_time

timestamp

The time when the webhook was last updated

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

id

string

The payment ID

amount_currency

string

The exchange currency code in ISO 4217 format

amount_value

bigdecimal

The final payment amount

bank_account

string

The seller's bank account number masked, revealing only the last 4 digits for privacy

create_time

timestamp

The time when the payment was initiated in TikTok Shop

exchange_rate

bigdecimal

The exchange rate, displayed with six decimal places

paid_time

timestamp

The time when the payment was successfully processed

payment_amount_before_exchange_currency

string

The original currency code in ISO 4217 format

payment_amount_before_exchange_value

bigdecimal

The original payment amount.

reserve_amount_currency

string

The original currency code in ISO 4217 format

reserve_amount_value

bigdecimal

The reserved amount

settlement_amount_currency

string

The original currency code in ISO 4217 format

settlement_amount_value

bigdecimal

The settlement amount

status

string

The payment status, indicating whether payment has been transferred to the seller's bank account. Possible values:

• PAID: Payment has been transferred to the seller.

• FAILED: Payment transfer failed.

• PROCESSING: Payment is currently being processed

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

payment_status

optional

string

Filter statements based on the payment status. Possible values: - PAID: Payment has been transferred to the seller. - FAILED: Payment transfer failed. - PROCESSING: Payment is currently being processed. Default: All statuses are returned

statement_time_ge

optional

timestamp

Filter statements to show only those that are generated on or after the specified date and time

statement_time_lt

optional

timestamp

Filter statements to show only those that are generated before the specified date and time

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

id

string

The statement ID

adjustment_amount

bigdecimal

The adjustment amount. For more details about the reason for adjustment, refer to the [Get Statement Transactions API](https://partner.tiktokshop.com/docv2/page/650a6749defece02be67da87)

currency

string

The currency code in ISO 4217 format

fee_amount

bigdecimal

The fees charged by TikTok Shop at the time of order settlement. An order is deemed settled a certain number of days after delivery (varies by region) if no returns or refunds are pending. **Note**: Shipping-related costs are excluded, except for local sellers in the SEA region, where they are included

net_sales_amount

bigdecimal

The final revenue amount after seller discounts are deducted. Applicable only for local sellers outside the SEA region.

payment_id

string

The payment ID

payment_status

string

The payment status, indicating whether payment has been transferred to the seller's bank account. Possible values: - PAID: Payment has been transferred to the seller. - FAILED: Payment transfer failed. - PROCESSING: Payment is currently being processed

revenue_amount

bigdecimal

The final revenue amount at the time of order settlement. Applicable for all regions except UK and US

settlement_amount

bigdecimal

The settlement amount.

shipping_cost_amount

bigdecimal

The shipping fees. Applicable only for local sellers outside the SEA region.

statement_time

timestamp

The time when the statement was generated

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

search_time_ge

optional

timestamp

Filter statements to show only those that are generated on or after the specified date and time. Unix timestamp. Note:statement_time_ge and statement_time_lt together constitute the creation time filter condition. - If statement_time_ge is filled but statement_time_lt is empty, statement_time_lt will default to the current time. - If statement_time_lt is filled but statement_time_ge is empty, statement_time_ge will default to 20250101

search_time_lt

optional

timestamp

The search range's end time

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

id

string

The transaction ID

adjustment_id

string

The adjustment ID if the transaction is an adjustment. Each transaction can only be associated with an order ID or an adjustment ID

adjustment_order_id

string

The order ID associated with the adjustment, if any

currency

string

The three-digit currency code in ISO 4217 format

est_adjustment_amount

bigdecimal

The sum of the estimated adjustment amount

est_fee_tax_amount

bigdecimal

The estimated total fees and taxes charged by TikTok Shop. Shipping-related costs are excluded. This is equivalent to the sum of all contributory amounts in 'fee_tax_breakdown'

est_revenue_amount

bigdecimal

The sum of the estimated revenue amount

est_settlement_amount

bigdecimal

The sum of the estimated settlement amount

est_shipping_cost_amount

bigdecimal

The estimated shipping costs, please note that when order hasn't been delivered, no complete shipping cost can be provided. This is equivalent to the sum of all contributory amounts in 'shipping_cost_breakdown'

estimated_settlement

string

Estimated settlement time for this transaction. Possible return value: - x days after delivery: when order hasn't been delivered and only rough settlement policy been provided - Unix timestamp: when order has been delivered and detailed settlement time been calculated out

fee_tax_breakdown_fee_affiliate_ads_commission_amount

bigdecimal

The commission for eligible orders from ads

fee_tax_breakdown_fee_affiliate_commission_amount

bigdecimal

The commission amount charged to the seller for payment to the creator

fee_tax_breakdown_fee_affiliate_commission_before_pit_amount

bigdecimal

The affiliate ads commission paid to a creator before any personal income tax withholding. Applicable only for SEA markets

fee_tax_breakdown_fee_affiliate_partner_commission_amount

bigdecimal

The commission amount for purchases through affiliate partner links

fee_tax_breakdown_fee_bonus_cashback_service_fee_amount

bigdecimal

The service fee charged for participation in the bonus cashback program

fee_tax_breakdown_fee_credit_card_handling_fee_amount

bigdecimal

The handling fee charged when the buyer pays with a credit card

fee_tax_breakdown_fee_live_specials_fee_amount

bigdecimal

The service fee charged for participation in the [LIVE Specials Programme]

fee_tax_breakdown_fee_mall_service_fee_amount

bigdecimal

The service fee charged for using TikTok Shop Mall

fee_tax_breakdown_fee_pit_withheld_from_ads_commission_amount

bigdecimal

The creator's personal income tax withholding amount, deducted from the affiliate ads commission. Sellers are responsible for declaration and remittance to the tax authority, as well as providing finalized personal income tax documentation to creators. Applicable only for SEA markets

fee_tax_breakdown_fee_platform_commission_amount

bigdecimal

The commission amount charged by the platform

fee_tax_breakdown_fee_referral_fee_amount

bigdecimal

The referral fee charged for processing successful orders. Applicable only for the US

fee_tax_breakdown_fee_refund_administration_fee_amount

bigdecimal

The 20% refund administration fee deducted from the total refunded referral fee amount

fee_tax_breakdown_fee_retail_delivery_fee_amount

bigdecimal

The final retail delivery fee for deliveries in Colorado, US. For more information, see [Colorado Retail Delivery Fee FAQ](https://seller-us.tiktok.com/university/essay?knowledge_id=2459780628350762&default_language=en&identity=1). Formula: retail_delivery_fee_payment + retail_delivery_fee_refund

fee_tax_breakdown_fee_retail_delivery_fee_payment_amount

bigdecimal

The retail delivery fee for deliveries in Colorado, US. For more information, see [Colorado Retail Delivery Fee FAQ](https://seller-us.tiktok.com/university/essay?knowledge_id=2459780628350762&default_language=en&identity=1)

fee_tax_breakdown_fee_retail_delivery_fee_refund_amount

bigdecimal

The retail delivery fee subsidy by the platform for losses due to returns, refunds, or other issues in Colorado, US

fee_tax_breakdown_fee_sfp_service_fee_amount

bigdecimal

The service fee charged for participation in the [Seller Free Shipping Programme]

fee_tax_breakdown_fee_transaction_fee_amount

bigdecimal

The transaction fee charged for processing successful orders

fee_tax_breakdown_tax_customs_clearance_amount

bigdecimal

The fees charged by logistic suppliers for customs clearance services. Applicable only for cross-border shop orders

fee_tax_breakdown_tax_customs_duty_amount

string

The customs duties, a type of tax on cross-border goods collected by governments. Applicable only for cross-border shop orders

fee_tax_breakdown_tax_gst_amount

bigdecimal

The goods and services tax (GST) collected and remitted to the tax authority by the platform for low-value goods imported into Singapore, effective January 1, 2023

fee_tax_breakdown_tax_import_vat_amount

bigdecimal

The import VAT, a tax paid on goods bought in one country and imported into another. Applicable only for cross-border shop orders

fee_tax_breakdown_tax_sales_tax_amount

bigdecimal

The final sales tax to be paid by the customer for the product and delivery. Formula: sales_tax_payment_amount - sales_tax_refund_amount

fee_tax_breakdown_tax_sales_tax_payment_amount

bigdecimal

The expected sales tax to be paid by the customer for the product and delivery

fee_tax_breakdown_tax_sales_tax_refund_amount

bigdecimal

The sales tax amount returned to the customer in the event of a refund

fee_tax_breakdown_tax_sst_amount

bigdecimal

The sales and service tax (SST) collected and remitted to the tax authority by the platform for low-value goods imported into Malaysia, effective January 1, 2024

fee_tax_breakdown_tax_vat_amount

bigdecimal

The VAT paid by the platform on the seller's behalf. Applicable only for cross-border shop orders

order_create_time

timestamp

The creation time of the order

order_delivery_time

timestamp

The delivery time of the order

order_id

string

The order ID. Each transaction can only be associated with an order ID or an adjustment ID

revenue_breakdown_cod_service_fee_amount

bigdecimal

The cash on delivery service fees charged to buyers. Applicable only for Saudi Arabia

revenue_breakdown_refund_cod_service_fee_amount

bigdecimal

The refund for cash on delivery service fees. Applicable only for Saudi Arabia

revenue_breakdown_refund_subtotal_before_discount_amount

bigdecimal

The total price of all refunded items before any seller discounts. This is equivalent to the shop's gross sales refund

revenue_breakdown_seller_discount_amount

bigdecimal

The total amount of discounts funded by the seller, including: - Seller promotions (Product Discount, Flash Deal, Buy More Save More, Voucher and Bundle Deal) - Seller's portion of a co-funded voucher discount in co-funding campaigns - Seller discounts during a campaign

revenue_breakdown_seller_discount_refund_amount

bigdecimal

Discounts returned to the sellers due to returns or refunds

revenue_breakdown_subtotal_before_discount_amount

bigdecimal

The total price of all order items before any seller discounts and platform discounts are deducted. This is equivalent to the shop's gross sales

shipping_cost_breakdown_actual_shipping_fee_amount

bigdecimal

The actual shipping fee calculated based on the weight/dimensions measured by the carrier. For details, check ' shipping_cost_breakdown.supplementary_component'

shipping_cost_breakdown_customer_paid_shipping_fee_amount

bigdecimal

The actual shipping fee borne by the customer, calculated based on the product weight uploaded by the seller

shipping_cost_breakdown_exchange_shipping_fee_amount

bigdecimal

The shipping fee paid by the seller for the delivery of goods exchange. Applicable only for Indonesia

shipping_cost_breakdown_replacement_shipping_fee_amount

bigdecimal

The shipping fee paid by the seller for the delivery of goods replacement. Applicable only for Indonesia

shipping_cost_breakdown_return_shipping_fee_amount

bigdecimal

The shipping fee paid by the seller for the delivery of returns

shipping_cost_breakdown_shipping_fee_discount_amount

bigdecimal

The shipping fee subsidies and incentives provided by the platform. This includes all subsidies regardless of fulfillment channels or policies. For details, check ' shipping_cost_breakdown.supplementary_component'

shipping_cost_breakdown_shipping_insurance_fee_amount

string

The shipping insurance fee incurred by the seller for purchasing additional TikTok shipping insurance services

shipping_cost_breakdown_signature_confirmation_fee_amount

bigdecimal

The fee incurred for packages requiring signature confirmation services

shipping_cost_breakdown_supplementary_component_customer_shipping_fee_offset_amount

bigdecimal

The fee to offset TikTok Shop Shipping Incentive or customer-paid shipping fee, resulting in a net charge of $0 to the seller. Applicable only for the US

shipping_cost_breakdown_supplementary_component_fbm_shipping_cost_amount

bigdecimal

The shipping fee incurred by the seller for using TikTok Shipping. This is part of 'actual_shipping_fee_amount'

shipping_cost_breakdown_supplementary_component_fbt_fulfillment_fee_amount

bigdecimal

The shipping and warehouse fulfillment fee incurred by the seller for orders fulfilled by TikTok (FBT). This is part of 'actual_shipping_fee_amount'. Applicable only for the US

shipping_cost_breakdown_supplementary_component_fbt_shipping_cost_amount

bigdecimal

The shipping fee incurred by the seller for orders fulfilled by TikTok (FBT). This is part of 'actual_shipping_fee_amount'. Applicable for all regions except the US

shipping_cost_breakdown_supplementary_component_platform_shipping_fee_discount_amount

bigdecimal

The shipping fee discount provided in accordance with a campaign policy.. This is part of 'shipping_fee_discount_amount'

shipping_cost_breakdown_supplementary_component_promo_shipping_incentive_amount

bigdecimal

The additional shipping incentive that the seller will receive if the seller signed up for the Co-Funded Free Shipping Program from 2024/08/26 to 2024/12/31. A negative amount indicates a reversal of incentives due to order refunds attributed to the seller's responsibility. This is part of 'shipping_fee_discount_amount'

shipping_cost_breakdown_supplementary_component_seller_shipping_fee_discount_amount

bigdecimal

The shipping fee discount provided by sellers

shipping_cost_breakdown_supplementary_component_shipping_fee_subsidy_amount

bigdecimal

The shipping fee subsidy funded by the platform for seller shipping. This is part of 'shipping_fee_discount_amount'. - Positive amount represents a subsidy received by the seller. - Negative amount represents a subsidy that the seller must return to TikTok Shop

status

string

The transaction status. Only supports 'UNSETTLED'

type

string

The transaction type. Standard transactions - 'ORDER': A transaction related to an order settlement. - If the transaction is an adjustment, it returns one of the following values: Platform-related adjustments - 'CHARGE_BACK': Charges returned to a payment card after a customer has successfully disputed an item on their account statement or transactions report. - 'CUSTOMER_SERVICE_COMPENSATION': Extra compensation or compensation paid to a customer after the after-sales period by customer service. - 'DEDUCTIONS_INCURRED_BY_SELLER': Deduction arising from customer dissatisfaction as a result of the seller's responsibility. This includes issues such as fraud, empty packages, items that do not match the product display page, or items of lower value than advertised. - 'GMV_PAYMENT_FOR_ADS': Amount used to pay for your advertisement if you are enabled "auto pay ads with shop GMV", or to pay for Tiktok Promote ads orders. - 'PLATFORM_COMMISSION_ADJUSTMENT': Adjustment when there are differences in the platform commission paid by the seller. - 'PLATFORM_COMMISSION_COMPENSATION': Compensation paid to the seller when there are differences in the platform commission paid by the seller. - 'PLATFORM_PENALTY': Penalty imposed for a violation of TikTok Shop policies (the corresponding amount has been deducted from the seller's account). For details, please refer to the email notification sent to the seller. - 'PROMOTION_ADJUSTMENT': Adjustment when a seller takes part in a platform promotion and there are differences between the promotion price and the actual amount paid by the seller. - 'REBATE': A discount on referral fees offered by TikTok Shop to eligible sellers. - 'PLATFORM_COMPENSATION': Compensation paid to the seller after the seller successfully appealed for a customer dispute. - 'PLATFORM_REIMBURSEMENT': Reimbursement paid by TikTok Shop for an order refunded under TikTok's refund without return policy (the seller is not responsible). Logistics-related adjustments - 'FBT_WAREHOUSE_SERVICE_FEE': Amount charged by TikTok Fulfillment Portal (Pipak) for warehousing-related bills incurred by the seller under the Fulfilled by TikTok (FBT) service. - 'LOGISTICS_REIMBURSEMENT': Reimbursement paid by TikTok Shop for an order refunded due to logistics-related issues (e.g. lost or damaged order). - 'SHIPPING_FEE_ADJUSTMENT': Adjustment when there are differences or mistakes with the shipping fee paid by the seller. - 'SHIPPING_FEE_COMPENSATION': Compensation given to sellers due to differences between the actual shipping fee and the pre-paid shipping fee. - 'SHIPPING_FEE_REBATE': Shipping fee rebate provided to the seller as part of their participation in a platform campaign. - 'SAMPLE_SHIPPING_FEE': Fees charged for sending samples using the TikTok logistics provider. Miscellaneous adjustments 'OTHER_ADJUSTMENT': Adjustment for other reasons

unsettled_reason

string

Reason for why transaction is pending for settlement

types

required

string

The type of transaction. Possible values: - WITHDRAW - the action of the seller to receive the settlement amount to the bank card through the action of withdrawal - SETTLE - the platform settles the amount to the seller - TRANSFER - platform subsidies or deductions due to platform policies - REVERSE - withdrawal failure due to incorrect bank card

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

create_time_ge

optional

timestamp

Unix timestamp representing the start of transactions time range one wants to request

create_time_lt

optional

timestamp

Unix timestamp representing the end of transactions time range one wants to request

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

id

string

A unique transaction id generated by TTS for the withdrawal

amount

bigdecimal

Withdraw amount

create_time

timestamp

Withdraw create time

currency

string

The three-digit currency code in ISO 4217 format.

status

string

The processing status of the withdrawal indicates whether the withdrawal is transferred

type

string

WITHDRAW - the action of the seller to receive the settlement amount to the bank card through the action of withdrawal, SETTLE - the platform settles the amount to the seller, TRANSFER - platform subsidies or deductions due to platform policies, REVERSE - withdrawal failure due to incorrect bank card

goods_ids

optional

string

Identifier for goods generated by Fulfilled by TikTok system, maximum length 100. Filter the goods information to display only those with specific goods IDs. Note: When 'goods_ids', 'reference_codes', 'sku_ids', or 'product_ids' include two or more values, the result will return the intersection of the goods information. For example, if the input includes both 'goods_ids' and 'sku_ids', it will return only the goods that meet both the 'goods_ids' and 'sku_ids' criteria. If requested with all criteria empty, it will return a 'page_size' number of goods defined by the merchant, sorted by creation time, with the latest first

product_ids

optional

string

Identifier for product generated by TikTok Shop system, maximum length 100. Filter the goods information to display only those with specific product IDs

reference_codes

optional

string

Identifier for goods defined by merchant, maximum length 100. Filter the goods information to display only those with specific reference codes

shop_cipher

optional

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

sku_ids

optional

string

Identifier for Stock Keeping Unit (SKU) generated by TikTok Shop system, maximum length 100. Filter the goods information to display only those with specific SKU IDs

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

id

string

The identifier for goods generated by Fulfilled by TikTok system

name

string

The goods name

barcodes

string

A list of detailed information for goods barcodes

image_url

string

The goods image url

lot_expiration_info_addresses_address_line_1

string

The detail address line 1

lot_expiration_info_addresses_address_line_2

string

The detail address line 2, additional address information(optional)

lot_expiration_info_addresses_address_line_3

string

The detail address line 3, additional address information(optional)

lot_expiration_info_addresses_city

string

Warehouse address city

lot_expiration_info_addresses_district

string

Warehouse address district or county

lot_expiration_info_addresses_name

string

The name of the contact person

lot_expiration_info_addresses_phone_number

bigdecimal

The phone number of the contact person

lot_expiration_info_addresses_postal_code

string

Warehouse address postal code (also known as zip code)

lot_expiration_info_addresses_region_code

string

Warehouse country or region code in two-character ISO 3166-1 alpha-2 format

lot_expiration_info_addresses_state

string

Warehouse address state or province

lot_expiration_info_expiration_alert_days

integer

The goods alert days before expired, represent the period of time before platform send expiration reminder alerts to the merchant

lot_expiration_info_handling_method

string

The handling method for expired inventory. Possible values: - TURN_INTO_DEFECTIVE_INVENTORY - RETURN_TO_SUPPLIER - DISPOSE

lot_expiration_info_inbound_cutoff_days

integer

The goods inbound cutoff days before expiration, represent the time period before the product's expiration when the warehouse will no longer accept inbound shipments.

lot_expiration_info_is_expiration_management

boolean

A flag indicating whether the goods is under expiration managment. True: Under expiration managment. False: Not under expiration managment

lot_expiration_info_is_lot_control

boolean

A flag indicating whether the goods is under lot control. True: Under lot control. False: Not under lot control. Note: Lot code and expiration date management information is mandatory for these [product categories](https://bytedance.us.larkoffice.com/sheets/OoT2sKH7jhykXCtHEseuzkGYsod) according to Fulfilled by TikTok guidelines

lot_expiration_info_return_cycle

string

The return cycle applied when the handling method is set to RETURN_TO_SUPPLIER. In this case, the automatic creation of exit inventory orders will follow one of return cycle rules. Possible values: - ONCE_A_WEEK - ONCE_A_MONTH - ONCE_A_QUARTER

lot_expiration_info_sales_cutoff_days

integer

The goods sales cut off days before expired, represent the period of time before expiration in which the goods will no longer be available for sale

lot_expiration_info_shelf_life_days

integer

The goods shelf life days input by merchant, represent the total number of days the product remains usable or sellable from the time it is manufactured until its expiration

merchant_declaration_info_dimension_height

bigdecimal

Height value, up to three decimal places

merchant_declaration_info_dimension_length

bigdecimal

Length value, up to three decimal places

merchant_declaration_info_dimension_unit

string

Dimension unit. Possible values: - MILLIMETER - CENTIMETER - METER - FOOT - INCH - MICROMETER

merchant_declaration_info_dimension_width

bigdecimal

Width value, up to three decimal places

merchant_declaration_info_weight_unit

string

Weight unit. Possible values: - MILLIGRAM - GRAM - KILOGRAM - POUND - OUNCE

merchant_declaration_info_weight_value

bigdecimal

Weight value, up to three decimal places

reference_code

string

The identifier for goods defined by merchant

warehouse_confirmation_info_dimension_height

string

Height value verified by warehouse, up to three decimal places

warehouse_confirmation_info_dimension_length

bigdecimal

Length value verified by warehouse, up to three decimal places

warehouse_confirmation_info_dimension_unit

string

Dimension unit. Possible values: - MILLIMETER - CENTIMETER - METER - FOOT - INCH - MICRO

warehouse_confirmation_info_dimension_width

string

Width value verified by warehouse, up to three decimal places

warehouse_confirmation_info_weight_unit

string

Weight unit. Possible values: - MILLIGRAM - GRAM - KILOGRAM - POUND - OUNCE

warehouse_confirmation_info_weight_value

string

Weight value verified by warehouse, up to three decimal places

ids

required

string

A list of inbound order IDs needs to be queried. The API will return the inbound order information for these IDs. Note: The inbound ID consists of a series of numbers without the "IBR" prefix. You can get the value in 'data.inbound_order_id' in [Inbound FBT order status change](6708f866a88d1103246fed6a) webhook or in 'data.inventory_records.order.id' in the response of [Search FBT Inventory Record](670d584ba83c5f030f3071e4)

shop_cipher

optional

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

id

string

The identifier for inbound order generated in Fillfilled by TikTok system

actual_arrive_time

timestamp

The actual arrival time

carriers

string

A list of carrier information

create_time

timestamp

The time when the inbound order created

expect_arrive_time

timestamp

The expected arrival time provided by merchant

merchant_id

string

The identifier of the merchant in Fulfilled by TikTok system

merchant_name

string

The merchant name

order_operation_logs

string

A list of inbound order operation history

ship_time

timestamp

The time when the inbound order shipped

type

string

The inbound order type. Possible values: - REPLENISHMENT

warehouse_fbt_warehouse_id

string

The Identifier for warehouse generated by Fulfilled by TikTok system

warehouse_name

string

The Fulfilled by TikTok warehouse name

warehouse_type

string

The Fullfilled by TikTok warehouse type. Possible values: - PLATFORM_WAREHOUSE

warehouse_warehouse_ids

string

The identifier for warehouse generated by TikTok Shop system, will have the relationship with 'fbt_warehouse_id'

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

fbt_warehouse_ids

optional

string

The identifiers for warehouses generated by Fulfilled by TikTok system. If specificed, it will only show inventory records belonging to those warehouses, otherwise, all warehouses subscribed by merchant will be returned

goods_ids

optional

string

The identifiers for goods generated by Fulfilled by TikTok system, maximum length 100. If specificed, it will only show inventory information belonging to those goods, otherwise, all goods with non-zero inventory will be returned. Note: This API only allows either 'goods_ids' or 'sku_ids', and returns results that satisfy all specified criteria

sku_ids

optional

string

A list of identifiers for Stock Keeping Units(SKUs) generated by TikTok Shop, maximum length 100. Filter inventory information to display only those belonging to the goods matched with specified SKUs. Refer to note in 'goods_ids' for more usage information

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

fbt_warehouse_id

string

The identifier for warehouse generated by Fulfilled by TikTok system

goods_id

string

The identifier for goods generated by Fulfilled by TikTok system

goods_name

string

The goods name

goods_reference_code

string

The identifier for goods defined by the merchant, commonly used to reference the ID from the merchant's other order management systems

in_transit_quantity

integer

The number of goods units currently en route to the warehouse. The inventory includes inbound replenishments, customer returns, unsuccessful delivery returns, etc

on_hand_detail_available_quantity

integer

The number of units available for sale. Note: The number does not include reserved units

on_hand_detail_reserved_quantity

integer

The number of units reserved for customer orders or return to supplier shipment

on_hand_detail_total_quantity

integer

The total number of units physically in the Fulfilled by TikTok warehouse, excluding those in transit. This total is the sum of 'available_quantity', 'reserved_quantity', and 'unfulfillable_quantity'

on_hand_detail_unfulfillable_quantity

integer

The number of units that are currently unavailable for sale

create_time_ge

optional

timestamp

Filter inventory record creation time to show only those that are created on or after the specified date and time

create_time_le

optional

timestamp

Filter inventory record creation time to show only those that are created on or before the specified date and time

fbt_warehouse_ids

optional

string

The identifiers for warehouses generated by Fulfilled by TikTok system. If specificed, it will only show inventory records belonging to those warehouses, otherwise, all warehouses subscribed by merchant will be returned

goods_ids

optional

string

The identifiers for goods generated by Fulfilled by TikTok system, maximum length 100. If specificed, it will only show inventory records belonging to those goods, otherwise, all goods with non-zero inventory will be returned

shop_cipher

optional

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

changed_quantity

integer

The change in the number of units is calculated as the 'final_on_hand_quantity' - 'initial_on_hand_quantity'

create_time

timestamp

The time when the inventory record is created, Unix timestamp in seconds

fbt_warehouse_id

string

The identifier for warehouse generated by Fulfilled by TikTok system

final_on_hand_quantity

integer

The number of goods units physically in the Fulfilled by TikTok warehouse after current inventory change, excluding those in transit

goods_id

string

The identifier for goods generated by Fulfilled by TikTok system

goods_name

string

The goods name

goods_reference_code

string

The identifier for goods defined by merchant

initial_on_hand_quantity

integer

The number of goods units physically in the Fulfilled by TikTok warehouse before current inventory change, excluding those in transit

inventory_goods_type

string

The type of goods in current inventory record. Possible values: - NORMAL - DEFECTIVE

order_id

string

The identifier for order generated by Fulfilled by TikTok system

order_type

string

The type of order. Possible values: - INBOUND_ORDER - RETURN_TO_SUPPLIER_ORDER - DISPOSAL - INVENTORY_STATUS_ADJUSTMENT_ORDER - CONSIGN_ORDER - INVENTORY_COUNT_ORDER - FAILED_DELIVERY - CUSTOMER_RETURN - INVENTORY_QUANTITY_ADJUSTMENT_ORDER - OUTBOUND_TRANSFER_ORDER - FROZEN_ORDER

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

region_code

string

The country or region codes follow the two-character ISO 3166-1 alpha-2 format

shop_cipher

optional

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

name

string

The Fulfilled by TikTok warehouse name, e.g.TikTok_Eastvale(CA)

fbt_warehouse_id

string

The identifier for warehouse generated by Fulfilled By TikTok system

logistics_services

string

A list of logistics service information related to the current warehouse

subscribed

boolean

A flag indicating whether the warehouse is subscribed. True: Subscribed. False: Not subscribed

type

string

The Fulfilled by TikTok warehouse type. Possible values: - PLATFORM_WAREHOUSE

warehouse_ids

string

The identifier for warehouse generated by TikTok Shop system, will have the relationship with 'fbt_warehouse_id'

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

id

string

A set of pre-generated package IDs after calling the Search Draft Package API. These package IDs will be used when the package combine is confirmed

order_ids

string

List of order IDs for this package

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

order_ids

required

string

Query list of TikTok Shop order IDs

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

can_split

boolean

Whether an order can be split: - 'true': The order can be split into multiple packages. - 'false': The order cannot be split into multiple packages

must_split

boolean

Whether an order must be split: - true: The order must be split into multiple packages. - false: The order does not have to be split into multiple packages

must_split_reasons

string

The reason why the order must be split. Only return this field when must_split = true

order_id

string

TikTok Shop order ID

reason

string

The reason why the order cannot be split. Only return this field when 'can_split = false'

create_time_ge

optional

timestamp

Filter the packages to show only those that are created after (or at) the specified date and time

create_time_lt

optional

timestamp

Filter the packages to show only those that are created before the specified date and time

package_status

optional

string

Possible values: - 'PROCESSING': Package has been arranged by seller. Waiting for carrier to collect the parcel. - 'FULFILLING': Package has been collected by carrier and in transit. - 'COMPLETED': Package has been delivered. - 'CANCELLED': Package has been canceled. Normally, the package is canceled due to the package being lost or damaged

shop_cipher

optional

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

update_time_ge

optional

timestamp

Filter the packages to show only those that are updated after (or at) the specified date and time

update_time_lt

optional

timestamp

Filter the packages to show only those that are updated before the specified date and time

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

id

string

Package ID

create_time

timestamp

Package creation time

order_line_item_ids

string

The order line item ID contained in the package.

orders

string

The response list of TikTok Shop orders.

shipping_provider_id

string

Package shipping provider ID

shipping_provider_name

string

Package shipping provider

status

string

Possible values: - 'PROCESSING': Package has been arranged by seller. Waiting for carrier to collect the parcel. - 'FULFILLING': Package has been collected by carrier and in transit. - 'COMPLETED': Package has been delivered. - 'CANCELLED': Package has been canceled. Normally, the package is canceled due to the package being lost or damaged

tracking_number

string

Package tracking number

update_time

timestamp

Package latest update time

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

package_id

required

string

TikTok Shop package ID

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

can_drop_off

boolean

Whether this package be dropped off at a drop-off location

can_pickup

boolean

Whether this package supports door-to-door collection

can_van_collection

boolean

Specific to UK. Use this field to determine whether van collection is available

drop_off_point_url

string

View package drop-off locations via provided URL

pickup_slots

string

Time slot for door-to-door collection

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

package_id

required

string

TikTok Shop package ID.

document_type

required

string

Available document types: - 'SHIPPING_LABEL': Returns the shipping label in PDF format by default. - 'PACKING_SLIP': Returns the packing slip in PDF format by default. - 'SHIPPING_LABEL_AND_PACKING_SLIP': Returns both the shipping label and the packing slip for the package, both in PDF format by default. - 'SHIPPING_LABEL_PICTURE': Returns the shipping label in PNG format. - 'HAZMAT_LABEL': Returns the hazmat label in PDF format by default. You must only use this value when there are hazmat items in the package. When you use the value, 'document_size' is fixed to A4, and you don't need to specify 'document_size'. - 'INVOICE_LABEL': For Brazil market only, document_size is fixed to A6, and you don't need to specify 'document_size'. Returns the invoice label in PDF format by default

document_format

optional

string

The format of the shipping document. Possible values: - PDF (Default) - ZPL (Only for BR market) **Note**: Not applicable for 'SHIPPING_LABEL_PICTURE' document type

document_size

optional

string

Use this field to specify the size of the document to obtain. This parameter is only applicable to shipping labels, picking slips, and packing slips that are in the PDF format. It is not applicable for hazmat labels as these are fixed to A4. If you specify 'SHIPPING_LABEL_PICTURE' for the 'document_type', any value specified in the 'document_size' will be ignored. Possible values: - 'A6' (Default) - 'A5'

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

doc_url

string

The URL of the shipping label and packing slip generated for the specified package. The URL is valid for 24 hours

tracking_number

string

The package tracking number from the shipping carrier.

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

id

string

Global warehouse ID, a unique and immutable primary key, used for all global warehouse logistics

name

string

Global warehouse name. This name is not unique across the TikTok Shop system

ownership

string

Possible values: - SELLER: Warehouse owned by the seller. - PLATFORM_COOPERATION: Warehouse owned by TikTok Shop.

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

id

string

The warehouse ID, a unique and immutable primary key, used for all warehouse logistics

name

string

Warehouse name. This name is not unique across the TikTok Shop system

address_address_line1

string

The first line of the warehouse address, like street name and street number. Note: - For Brazilian market, this represents the neighborhood or district. - For the JP market, this represents the district (Chome), block (Banchi), building number (Go)

address_address_line2

string

The second line of the warehouse address, like flat, apartment, or suit. Note: For the Brazilian market, this represents the street name

address_address_line3

string

This represents the street number. If it's 's/n', it means null. Note: Available only in the Brazilian market

address_address_line4

string

This represents supplement information, like flat, apartment, or suit (optional). Note: Available only in the Brazilian market

address_city

string

Warehouse city

address_contact_person

string

Warehouse contact person name

address_distict

string

Warehouse district

address_first_name

string

Kanji first name Applicable only for the JP market

address_first_name_local_script

string

Hiragana or Katakana first name Applicable only for the JP market

address_full_address

string

The combined warehouse address, including the street address and other address information such as apartment number, building, floor..etc (optional)

address_geolocation_latitude

bigdecimal

The latitude of the address

address_geolocation_longitude

bigdecimal

The longitude of the address

address_last_name

string

Kanji last name Applicable only for the JP market

address_last_name_local_script

string

Hiragana or Katakana last name Applicable only for the JP market

address_phone_number

string

Warehouse phone number

address_postal_code

string

Warehouse address postal code (also known as zip code)

address_region

string

Warehouse region

address_region_code

string

Warehouse region code

address_state

string

Warehouse state or province

address_town

string

Warehouse town

effect_status

string

Possible values: - ENABLED: All products in stock are available for sale. - DISABLED: All products in stock are unavailable for sale. - RESTRICTED: The warehouse is either on "holiday mode" or "order limit mode." All products in stock are unavailable for sale. -Holiday mode: When the seller cannot fulfill an order from a warehouse, the seller can turn on holiday mode for the warehouse in seller center. - Order limit mode: When the seller violates TikTok Shop policies, TikTok Shop will limit the order volume that can be fulfilled by a warehouse

entity_id

string

The warehouse entity ID, used to associate physical information of a warehouse, different warehouses may be associated with the same entity

is_default

boolean

The default warehouse. If a product is listed with no designated warehouse, the default warehouse will be used

sub_type

string

Possible values: - DOMESTIC_WAREHOUSE: The warehouse is in the same country as the target market and the seller. - CB_OVERSEA_WAREHOUSE: For cross-border sellers, a local warehouse in the target market. - CB_DIRECT_SHIPPING_WAREHOUSE: For cross-border sellers, a warehouse in the seller's base country, e.g., Mainland China or Hong Kong

type

string

Possible values: - SALES_WAREHOUSE: Warehouse for shipping products. - RETURN_WAREHOUSE: Warehouse for receiving returned products. You can have the same warehouse for both shipping and receiving returns, but they will have different warehouse IDs with the same address

warehouse_id

required

string

The warehouse ID

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

scope

optional

string

Specify the scope of delivery options to retrieve. - 'WAREHOUSE': Returns all delivery options currently active for the warehouse. By default, orders will be shipped based on these options. - 'PRODUCT': Returns the delivery options that can be assigned directly to a product. Use this if you want to enable custom delivery options for a product, overriding the default warehouse options. Only 'delivery_options.id' and 'delivery_options.name' will be included in the response when this is specified. Default: 'WAREHOUSE'

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

id

string

Delivery option ID

name

string

Delivery option name

description

string

Delivery option description

dimension_limit_max_height

integer

Maximum height limit

dimension_limit_max_length

integer

Maximum length limit

dimension_limit_max_width

integer

Maximum width limit

dimension_limit_unit

string

The unit of measurement for the dimensions, with possible values: - CM - INCH

platform

string

The platform on which the delivery option is available Possible values: - TIKTOK_SHOP - TOKOPEDIA

type

string

Delivery option type. This is an enumerated type with values: - STANDARD - EXPRESS - ECONOMY - SEND_BY_SELLER

weight_limit_max_weight

integer

Maximum weight limit

weight_limit_min_weight

integer

Minimum weight limit

weight_limit_unit

string

The unit of measurement for the weight, with possible values: - GRAM - POUND

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

buyer_user_id

optional

string

Buyer user ID

create_time_ge

optional

timestamp

Filter orders to show only those that are created on or after the specified date and time

create_time_lt

optional

timestamp

Filter orders to show only those that are created before the specified date and time

is_buyer_request_cancel

optional

boolean

Whether the buyer has initiated an order cancellation request

order_status

optional

string

Specific order status. Available values: - 'UNPAID': The order has been placed, but payment has not been completed - 'ON_HOLD': The order has been accepted and is awaiting fulfillment. The buyer may still cancel without the seller's approval. If 'order_type=PRE_ORDER', the product is still awaiting release so payment will only be authorized 1 day before the release, but the seller should start preparing for the release - 'AWAITING_SHIPMENT': The order is ready to be shipped, but no items have been shipped yet - 'PARTIALLY_SHIPPING': Some items in the order have been shipped, but not all - 'AWAITING_COLLECTION': Shipping has been arranged, but the package is waiting to be collected by the carrier - 'IN_TRANSIT': The package has been collected by the carrier and delivery is in progress - 'DELIVERED': The package has been delivered to the buyer - 'COMPLETED': The order has been completed, and no further returns or refunds are allowed - 'CANCELLED': The order has been cancelled

shipping_type

optional

string

The delivery method. - 'TIKTOK': Shipping service provided by TikTok. The seller should obtain a shipping label from TikTok. - 'SELLER': Seller provides shipping, including through 3rd party fulfillment providers on behalf of the seller

update_time_ge

optional

timestamp

Filter orders to show only those that are updated on or after the specified date and time

update_time_lt

optional

timestamp

Filter orders to show only those that are updated before the specified date and time

warehouse_ids

optional

string

Filter orders by pickup/sales warehouse IDs. Applicable only if the multi-warehouse feature is enabled. Max count: 100

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

id

string

TikTok Shop order ID

auto_combine_group_id

string

An identifier assigned to orders from the same customer during a LIVE session to facilitate combined order shipping when "auto-combination" is activated in Seller Center

buyer_email

string

The anonymized email address of the buyer. It is not recommended to send messages directly to this email address. If you need to contact the buyer, please go to the TikTok Shop Seller Center - Buyer Messages page

buyer_message

string

The note from the buyer

cancel_order_sla_time

timestamp

The automatic cancellation time for orders specified by the platform

cancel_reason

string

The cancellation reason. Please visit [our list of cancel reasons](https://partner.tiktokshop.com/docv2/page/67e61eee427345048595487d) for more information

cancel_time

timestamp

The time an order's status was updated to 'CANCELLED'

cancellation_initiator

string

Cancellation request initiator. Available values: - 'SELLER' - 'BUYER' - 'SYSTEM'

collection_due_time

timestamp

If the order hasn't updated its status to 'IN_TRANSIT' before this time, the order will be canceled by TikTok Shop

collection_time

timestamp

The time an order's status has been updated to 'IN_TRANSIT'

commerce_platform

string

The platform where the order was placed. Possible values: - 'TIKTOK_SHOP' - 'TOKOPEDIA' **Note**: Available only in the Indonesia market

consultation_id

string

An ID to identify the corresponding ePharmacy consultation. Applicable only if an ePharmacy consultation was initiated. Not applicable if the prescription was provided by the customer through an image upload

cpf

string

CPF (invoice number), used to issue an invoice. **Note**: Only available in the Brazil market

cpf_name

string

Name belonging to the CPF number for the Brazil market.

create_time

timestamp

The date and time that the order was created

delivery_due_time

timestamp

If the order hasn't updated its status to 'DELIVERED' before this time, the order will be automatically canceled by TikTok Shop

delivery_option_id

string

Delivery option ID is mapped to seller configured logistics templates ID

delivery_option_name

string

Delivery option name. For display purposes only. Available values: - 'Economy Shipping' - 'Standard Shipping' - 'Express Shipping'

delivery_option_required_delivery_time

timestamp

Order should be delivered before this time

delivery_sla_time

timestamp

Order should arrive by this date to be considered on-time and to avoid late delivery penalties

delivery_time

timestamp

The time an order's status changed to 'DELIVERED'

delivery_type

string

Indicates whether it is a Pick-Up Drop-Off (PUDO) location. The PUDO location is selected by the buyer when placing orders. Available values: - 'HOME_DELIVERY': not a PUDO location - 'COLLECTION_POINT': a PUDO location

exchange_source_order_id

string

If the order is an exchange order, this field returns the original order's order ID, from which the exchange order was generated. Returned only if is_exchange_order = true. Note: Only available in US and UK

fast_delivery_program

string

A badge presented on the merchandise to tell the buyer that the seller participates in the fast delivery program, such that the order should arrive in a promised time period. Possible values: - '3_DAY_DELIVERY' Not returned if order did not meet fast delivery program requirements. Note: Applicable only for the US market

fast_dispatch_sla_time

timestamp

The latest collection time to gain incentives of NDD (Next Day Delivery) project

fulfillment_priority_level

integer

Fulfillment priority value that can be used to prioritize shipping (only available in SEA) 100 = Instant 200 = Sameday 8 Hours 300 = Sameday 400 = Next Day Delivery 500 = Express 600 = Standard 700 = Economy 800 = Cargo

fulfillment_type

string

Fulfillment type. Only orders with fulfillment type can be shipped by sellers. Available values: - 'FULFILLMENT_BY_SELLER': a method where sellers fulfill orders directly from their own inventory, without using TikTok's fulfillment centers. In this model, the seller is responsible for storing, packaging, and shipping the products to customers. - 'FULFILLMENT_BY_TIKTOK': a service offered by TikTok where sellers can send their products to TikTok's fulfillment centers. TikTok then takes care of storing, picking, packing, and shipping the products to customers. - 'FULFILLMENT_BY_DILAYANI_TOKOPEDIA': a method where Tokopedia GoTo Logistics provides warehousing and logistics services to sellers and charges a fee for the service

handling_duration_days

bigdecimal

The number of days

handling_duration_type

string

Indicates if the duration is calculated in calendar days or business days. Possible values: - 'CALENDAR_DAY': Represents consecutive days, including weekends and holidays. - 'BUSINESS_DAY': Represents business days, excluding weekends and public holidays. Default: 'BUSINESS_DAY'

has_updated_recipient_address

boolean

Whether the recipient address has been updated or changed

is_buyer_request_cancel

boolean

Whether the buyer has a pending cancellation request

is_cod

boolean

This option is for sellers that accept cash payment on delivery (COD). Buyers will pay in cash upon receiving the package. Default: FALSE Only applicable to countries where COD is supported

is_exchange_order

boolean

When TRUE, this is an exchange order. Note: Only available in US and UK

is_on_hold_order

boolean

Indicates whether the order has been changed to or will be updated to 'ON_HOLD' status

is_replacement_order

boolean

Whether this is a replacement order

is_sample_order

boolean

Use this field to determine whether the order is a sample order

need_upload_invoice

string

Whether an invoice needs to be uploaded and uploaded status (only for Brazil market). - UNKNOWN: Currently unable to confirm whether an invoice is needed - NEED_INVOICE: This order requires an invoice and the invoice has not been uploaded yet - NO_NEED: This order does not require an invoice - INVOICE_UPLOADED: The invoice for this order has been uploaded and verified. If the order is split, it will be marked as "uploaded" once any sub-order's invoice is uploaded. - INVOICE_PROCESSING: The invoice for this order is currently being uploaded/cancelled. Please wait for the final result and do not repeat the operation

order_type

string

The order type. Possible values based on region: **All regions** - 'NORMAL': An item that is in stock and available for immediate purchase and fulfillment. - 'ZERO_LOTTERY': An order placed during a lottery event in TikTok LIVE. **US** - 'PRE_ORDER': An advance order for items that are not yet available or released. Fulfillment starts on a specific date in the future. - 'MADE_TO_ORDER': An order for items that are produced only after the order is received. Fulfillment starts after the product is produced. - 'BACK_ORDER': An order for items that are out of stock but expected to be restocked. Fulfillment starts after the product is restocked. Returns an empty value for standard orders or other types that don't fall into the above categories

packages

string

List of packages included in this order

paid_time

timestamp

The date and time that the order was paid

payment_buyer_service_fee

bigdecimal

A service fee is charged on every transaction made. The charge is applied from the fifth order onwards and collected directly from customers during checkout. Only available in the Indonesia market

payment_currency

string

Currency for payment

payment_handling_fee

bigdecimal

A fee charged to the buyer to cover the additional processing, handling, and/or installment costs associated with the chosen payment method

payment_item_insurance_fee

bigdecimal

The cost incurred by the buyers for coverage against defects or damage to the product after purchase. **Note**: Only available in the US and Indonesia markets

payment_item_insurance_tax

bigdecimal

The tax paid on the insurance purchased by buyers. Note: Only applicable in US market

payment_method_name

string

Payment method name, for display purposes

payment_original_shipping_fee

bigdecimal

Shipping fee before discount

payment_original_total_product_price

bigdecimal

Total original price of the products (VAT included for cross-border shops). For the US market, this is pre-tax total amount

payment_platform_discount

bigdecimal

Product discount by platform

payment_product_tax

bigdecimal

The tax on the total item price

payment_retail_delivery_fee

bigdecimal

Retail delivery fee (RDF). **Note**: Only available in the US market

payment_seller_discount

bigdecimal

Product discount by seller

payment_shipping_fee

bigdecimal

Buyer paid shipping fee. 'shipping_fee = original_shipping_fee - shipping_fee_seller_discount - shipping_fee_platform_discount' For the US market, this is pre-tax total amount

payment_shipping_fee_cofunded_discount

bigdecimal

Shipping fee discount provided by seller, eligible for co-funded reimbursement upon order delivery, based on Co-Funded Free Shipping program terms. **Note**: This will be 0 for orders that did not meet minimum order value for co-funded reimbursement. In this case, refer to 'shipping_fee_seller_discount' for the shipping discount the buyer received

payment_shipping_fee_platform_discount

bigdecimal

Shipping fee discount provided by platform

payment_shipping_fee_seller_discount

bigdecimal

Shipping fee discount provided by seller for an order that will not qualify for co-funded reimbursement. **Note**: If an order meets the minimum order value for co-funded reimbursement, this will be 0. In this case, refer to 'shipping_fee_cofunded_discount' for the shipping discount the buyer received

payment_shipping_fee_tax

bigdecimal

The tax on the shipping price

payment_shipping_insurance_fee

bigdecimal

The cost incurred by the buyer for coverage against loss or damage to goods during transit. **Note**: Only available in the Indonesia market

payment_small_order_fee

bigdecimal

Small order fee for TH (**Thailand market only**). Small order fee means that the platform will set a minimum order spending amount. When the order amount is lower than the minimum order spending amount, the user needs to pay a small order fee to meet the platform minimum spending amount. e.g. Minimum order spending amount is 100, order amount is 80. So the small order fee will be 20

payment_sub_total

string

Buyer paid sub-total of all the SKUs in the order. 'sub_total = original_total_product_price - seller_discount - platform_discount' For the US market, this is pre-tax total amount

payment_tax

bigdecimal

Buyer paid total taxes for the order. Applicable to both cross-border shops and the US market

payment_total_amount

bigdecimal

Buyer paid total payment. 'total_amount = sub_total + shipping_fee + taxes + retail_delivery_fee'

pick_up_cut_off_time

timestamp

To avoid LDR, you must ensure the package is picked up by this time. Only applicable in South East Asia regions.

recipient_address_address_detail

string

Full recipient detailed address

recipient_address_address_line1

string

The first line of the street address

recipient_address_address_line2

string

The second line of the street address

recipient_address_address_line3

string

The third line of the street address. Usually only for the Brazilian market

recipient_address_address_line4

string

The fourth line of the street address. Usually only for the Brazilian market

recipient_address_delivery_preferences_drop_off_location

string

Drop-off location selected by the recipient

recipient_address_district_info

string

'district_info' is unavailable under 'UNPAID' and 'ON_HOLD' statuses

recipient_address_first_name

string

Recipient first name. If the recipient first and last names are not provided separately, this parameter will have the same value as the 'name' parameter.

recipient_address_first_name_local_script

string

Recipient first name in katakana. **Note**: Applicable only for the JP market

recipient_address_full_address

string

Complete recipient address information

recipient_address_last_name

string

Recipient last name. If the recipient first and last names are not provided separately, this parameter will be empty.

recipient_address_last_name_local_script

string

Recipient last name in katakana. **Note**: Applicable only for the JP market

recipient_address_name

string

Recipient name. **Note**: If this order uses platform logistics, the recipient name will be desensitized

recipient_address_phone_number

string

Recipient telephone number. **Note**: If this order uses platform logistics, the phone number will be desensitized

recipient_address_post_town

string

Post town of the address Note: Available only in UK market

recipient_address_postal_code

string

The postal code that can be used by seller for shipping. For the US market, this refers to the ZIP Code

recipient_address_region_code

string

Region code

recommended_shipping_time

timestamp

Recommended time to ship based on the each LSP service type (only available in SEA)

release_date

timestamp

The date on which order handling starts and the status of the order changes to ['AWAITING_SHIPMENT'](https://partner.tiktokshop.com/docv2/page/650b1b4bbace3e02b76d1011). Applicable only if the 'order_type' is 'PRE_ORDER'

replaced_order_id

string

The order Id for the order that is being replaced. Returned only if 'is_replacement_order = true'

request_cancel_time

timestamp

Buyer request cancellation time

rts_sla_time

timestamp

The latest shipping time specified by the platform

rts_time

timestamp

The time sellers shipped the order (called [Ship Package API](https://partner.tiktokshop.com/docv2/page/650aa4f1defece02be6e7cb1) successfully)

seller_note

string

The seller note from TikTok Shop Seller Center

shipping_due_time

timestamp

If the order hasn't updated its status to 'AWAITING_COLLECTION' before this time, the order will be automatically canceled by TikTok Shop

shipping_provider

string

The name of the current shipping provider

shipping_provider_id

string

The ID of the current shipping provider

shipping_type

string

Delivery method. Available values: - 'TIKTOK': Shipping service provided by TikTok. The seller should obtain shipping label from TikTok. - 'SELLER': Seller provides shipping, including through 3rd party fulfillment providers on behalf of the seller

split_or_combine_tag

string

Indicates whether the order is combined or split: - 'COMBINED' - 'SPLIT' This field will be used in future fulfillment APIs

status

string

Specific order status. Available values: - 'UNPAID': The order has been placed, but payment has not been completed. - 'ON_HOLD': The order has been accepted and is awaiting fulfillment. The buyer may still cancel without the seller's approval. If 'order_type=PRE_ORDER', the product is still awaiting release so payment will only be authorized 1 day before the release, but the seller should start preparing for the release. - 'AWAITING_SHIPMENT': The order is ready to be shipped, but no items have been shipped yet. - 'PARTIALLY_SHIPPING': Some items in the order have been shipped, but not all. - 'AWAITING_COLLECTION': Shipping has been arranged, but the package is waiting to be collected by the carrier. - 'IN_TRANSIT': The package has been collected by the carrier and delivery is in progress. - 'DELIVERED': The package has been delivered to the buyer. - 'COMPLETED': The order has been completed, and no further returns or refunds are allowed. - 'CANCELLED': The order has been cancelled

tracking_number

string

Tracking number. Available after the package has been shipped

tts_sla_time

timestamp

The latest collection time specified by the platform

update_time

timestamp

Time of order status change

user_id

string

Buyer user ID

warehouse_id

string

Seller warehouse ID

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

order_id

optional

string

Order ID

table_orders

optional

string

A table that contains columns id (orders id) and update_time (e.g. output of the procedure tiktok_shops.Orders)

buyer_user_id

optional

string

Buyer user ID

create_time_ge

optional

timestamp

Filter orders to show only those that are created on or after the specified date and time

create_time_lt

optional

timestamp

Filter orders to show only those that are created before the specified date and time

is_buyer_request_cancel

optional

boolean

Whether the buyer has initiated an order cancellation request

order_status

optional

string

Specific order status. Available values: - 'UNPAID': The order has been placed, but payment has not been completed. - 'ON_HOLD': The order has been accepted and is awaiting fulfillment. The buyer may still cancel without the seller's approval. If 'order_type=PRE_ORDER', the product is still awaiting release so payment will only be authorized 1 day before the release, but the seller should start preparing for the release. - 'AWAITING_SHIPMENT': The order is ready to be shipped, but no items have been shipped yet. - 'PARTIALLY_SHIPPING': Some items in the order have been shipped, but not all. - 'AWAITING_COLLECTION': Shipping has been arranged, but the package is waiting to be collected by the carrier. - 'IN_TRANSIT': The package has been collected by the carrier and delivery is in progress. - 'DELIVERED': The package has been delivered to the buyer. - 'COMPLETED': The order has been completed, and no further returns or refunds are allowed. - 'CANCELLED': The order has been cancelled

shipping_type

optional

string

The delivery method. - 'TIKTOK': Shipping service provided by TikTok. The seller should obtain a shipping label from TikTok. - 'SELLER': Seller provides shipping, including through 3rd party fulfillment providers on behalf of the seller.

update_time_ge

optional

timestamp

Filter orders to show only those that are updated on or after the specified date and time

update_time_lt

optional

timestamp

Filter orders to show only those that are updated before the specified date and time

warehouse_ids

optional

string

Filter orders by pickup/sales warehouse IDs. Applicable only if the multi-warehouse feature is enabled. Max count: 100

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

order_id

string

TikTok Shop order ID

cod_fee

bigdecimal

COD fee charged by shipping aggregators. For regions outside of Saudi Arabia, the value is '0.00'

cod_fee_net_amount

bigdecimal

COD fee charged by shipping aggregators including tax. For regions outside of Saudi Arabia, the value is '0.00'

currency

string

Currency Type. Three-letter code, see [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html)

net_price_amount

bigdecimal

Price after tax

payment

bigdecimal

Payment of the order from the buyer. Calculation: 'sku_sale_price' + 'shipping_sale_price' + 'tax_amount' + 'small_order_fee'

shipping_fee_deduction_platform

bigdecimal

Shipping discount covered by the platform

shipping_fee_deduction_platform_voucher

string

Shipping discount covered by the platform voucher: '1010000': PLATFORM_NEW_USER, '1020000': SELLER_SKU_PRICE '1030000': PLATFORM_FREE_SHIPPING

shipping_fee_deduction_seller

bigdecimal

Shipping discount covered by the seller

shipping_list_price

bigdecimal

Original shipping price

shipping_sale_price

bigdecimal

Promotional shipping price Calculation: shipping_list_price - shipping_fee_deduction -shipping_fee_deduction_platform

sku_gift_net_price

string

Original sku list price of the gift product from the seller including tax

sku_gift_original_price

string

Original sku list price of the gift product from the seller

sku_list_price

string

Total MSRP price of the products

sku_sale_price

string

Total promotional sale price of the products. Calculation: 'sku_list_price' - 'subtotal_deduction_seller' - 'subtotal_deduction_platform'

subtotal

bigdecimal

Total promotional sale price of the products including tax. Calculation: 'sku_sale_price' + 'subtotal_tax_amount'

subtotal_deduction_platform

bigdecimal

Platform provided price discount on the product

subtotal_deduction_seller

bigdecimal

Seller provided price discount on the product

subtotal_tax_amount

bigdecimal

Total tax amount on the product

tax_amount

bigdecimal

Total tax amount. Calculation: subtotal_tax_amount + shipping_fee_tax (in TaxDetail) + cod_fee_tax (TaxDetail)

tax_rate

bigdecimal

Tax rate

total

bigdecimal

Total number of the original price of the order. Calculation: 'sku_list_price' + 'shipping_list_price'

voucher_deduction_platform

string

Type of the platform-providing discount on the product. Possible values: '1010000': PLATFORM_NEW_USER, '1020000': SELLER_SKU_PRICE', '1030000': PLATFORM_FREE_SHIPPING

voucher_deduction_seller

string

Type of the seller-providing discount on the product. Possible values: '1010000': PLATFORM_NEW_USER, '1020000': SELLER_SKU_PRICE, '1030000': PLATFORM_FREE_SHIPPING'

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

audit_status

optional

string

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

create_time_ge

optional

timestamp

Filter products to show only those that are created on or after the specified date and time

create_time_le

optional

timestamp

Filter products to show only those that are created on or before the specified date and time

listing_platforms

optional

string

Filter products by the listing platforms. Possible values: - TOKOPEDIA - TIKTOK_SHOP Default: Return all products regardless of their listing platform. Applicable only for sellers that migrated from Tokopedia. **Note**: - You must also specify a 'status' value other than 'ALL' when filtering by listing platforms. Returning all statuses is not supported. - If you pass in one platform, the search will return products that are listed on that platform, including those that are listed on both platforms. - If you pass in '["TIKTOK_SHOP", "TOKOPEDIA"]', only products listed on both platforms will be returned, not those listed on just one

listing_quality_tiers

optional

string

Filter products by their listing quality tier. Possible values: - POOR - FAIR - GOOD Default: Returns all **Note**: Available only for the US market

return_draft_version

optional

boolean

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'

seller_skus

optional

string

Filter products by these seller SKU codes

sku_ids

optional

string

Filter products by SKU IDs. Max count: 10

sns_filter

optional

string

Filter products by their Subscribe and Save (SNS) status. Possible values: - CONFIGURED - ELIGIBLE

status

optional

string

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

update_time_ge

optional

timestamp

Filter products to show only those that are updated on or after the specified date and time

update_time_le

optional

timestamp

Filter products to show only those that are updated on or before the specified date and time

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

id

string

The product ID generated by TikTok Shop

title

string

The product title

audit_pre_approved_reasons

string

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

audit_status

string

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

create_time

timestamp

The time when the product is created

has_draft

boolean

A flag to indicate if the product has a draft. - true: It has a draft. - false: It does not have a draft. Use Get Product with 'return_draft_version=true' to obtain full details of the draft

integrated_platform_statuses

string

The current status of the product on platforms that are natively integrated with TikTok Shop (e.g. TOKOPEDIA). **Note**: For Indonesia sellers, if you did not set the listing platform as 'TOKOPEDIA' when creating or editing a product, this will be omitted

is_not_for_sale

boolean

A flag indicating whether the product is not for sale. True: Not for sale. False: For sale

listing_quality_tier

string

The current quality tier of this product listing. The quality tier of a product listing depends on the quality of the content in its product fields such as the title, image, attributes etc. Possible values: - POOR - FAIR - GOOD **Note**: Available only for the US market

product_families

string

The **live** product family that this product belongs to. A product family is a virtual group of products that share common characteristics (such as flavor, version, or size), allowing them to appear as selectable variations on the product page. **Note**: - Applicable only for US local sellers. - Omitted if this product does not belong to any product family

product_families_products

string

A list of products that belong to the family

product_sync_fail_reasons

string

The reasons why synchronizing of global product information to local products failed. Only applicable for cross-border sellers

recommended_categories

string

Recommended categories for the product based on the product title, description, and images

sales_regions

string

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

status

string

The product status in TikTok Shop. Possible values: - 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

update_time

timestamp

The time when the product is last updated

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

category_id

required

string

The ID of the category of this product. It must be a leaf category

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

id

string

The ID of the built-in attribute

name

string

The name of the built-in attribute

is_customizable

boolean

A flag to indicate if the product attribute value can be customized by sellers when creating or editing a product. Applicable only if 'type=PRODUCT_PROPERTY'

is_multiple_selection

boolean

A flag to indicate if multiple values can be provided for a product attribute when creating or editing a product. Applicable only if 'type=PRODUCT_PROPERTY'

is_requried

boolean

A flag to indicate if the product attribute is always required when creating or editing a product. - true: The attribute is always required. - false: The attribute is not required, or required only if certain conditions are met. Refer to 'requirement_conditions' for the specific requirements. Applicable only if 'type=PRODUCT_PROPERTY'

requirement_conditions

string

A list of conditions that determine if the product attribute is required based on the seller's inputs for other attributes. If any of the conditions is met, the attribute is required; otherwise, it is optional. For example, there's a condition that states that the "Battery type" attribute is required if the seller selects the value "Batteries" for the attribute "Contains Batteries or Cells?". For more scenario-based guidance on using this parameter, refer to the [Solution Guide - CAT-PRE-HAZMAT](https://partner.tiktokshop.com/openlearn/guide/usecase?parent_id=7256668359046153985). Applicable only if 'type=PRODUCT_PROPERTY' and 'is_requried=false'

type

string

The attribute type. Possible values: - SALES_PROPERTY: Indicates sales attributes that define product variants. - PRODUCT_PROPERTY: Indicates product attributes that describe the product as a whole

value_data_format

string

The supported data type and structure of the attribute value for free-form entries, such as strings, integers, or positive decimals. Applicable only for **conditional (cascading) attributes**, not for standard attributes. Possible values: - POSITIVE_INT_OR_DECIMAL: Positive integers or decimal numbers

values

string

A list of selectable values for the attribute

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

brand_name

optional

string

Filter results to include brand names that begin with the specified value

category_id

optional

string

Specify a category ID to show the availability of **authorized brands** in the category. **Note**: Specify this value to obtain an accurate list of brands that you can use in a category

is_authorized

optional

boolean

Filter results by the brand authorization status. Possible values: - 1: Returns only authorized brands - 0: Returns all brands

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

id

string

The brand ID

name

string

The brand name

authorized_status

string

A status to indicate whether the seller has obtained prior authorization to sell goods bearing the brand's trademark, name, or logo. Possible values: - UNAUTHORIEZD - AUTHORIZED **Note**: If the brand is unauthorized, check 'is_t1_brand' to determine if you can use it during product creation

brand_status

string

The availability of an **authorized brand** in the requested category. Possible values: - AVAILABLE - UNAVAILABLE **Note**: Not applicable if you did not specify the category ID, or the brand is unauthorized

is_t1_brand

boolean

A flag to indicate whether the brand is a T1 brand, which refers to internationally renowned brands that may have compliance risks and require sellers to obtain brand authorization. **Note**: - You cannot create products with unauthorized T1 brands. - You can create products with unauthorized non-T1 brands, **but** the brand information will not appear on the product display page. You can obtain authorization by submitting the required qualifications through TikTok Shop Seller Center > Qualification Center > Brand qualification

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

include_prohibited_categories

optional

boolean

A flag to indicate whether to include categories that are prohibited on TikTok Shop. Set this to 'true' to identify which are the product categories that you can't list on TikTok Shop in any circumstances. Applicable only for BR, MX, EU and SEA markets

keyword

optional

string

Filter categories by this keyword in 'local_name'

listing_platform

optional

string

Filter categories by the specified platform. Possible values: - TIKTOK_SHOP - TOKOPEDIA Default: TIKTOK_SHOP Applicable only for sellers that migrated from Tokopedia

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

id

string

The category ID

is_leaf

boolean

A flag to indicate if the category is a leaf category. **Note**: You can only create or edit products that belong to a leaf category

local_name

string

The name of the category in the country where the shop operates

parent_id

string

The parent category ID. For the root category, the parent ID is '0'

permission_statuses

string

The shop's permission status for this category. Possible values: - 'AVAILABLE': You have the permission to create products in this category. - 'INVITE_ONLY': This is a restricted category and you do not have permission to use it. Submit an application through the Qualification Center on TikTok Shop Seller Center to gain access. In Seller Center, 'INVITE_ONLY' is also known as "restricted". - 'NON_MAIN_CATEGORY': This category is out of scope for this shop, and you do not have permission to use it. Contact your account manager for assistance. - 'PROHIBITED': This category is prohibited on TikTok Shop. Do not attempt to list products in this category as they will be rejected during audit. Applicable only for BR, MX, EU and SEA markets

category_id

required

string

The ID of the category. It must be a leaf category.

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

id

string

The ID of the built-in attribute

name

string

The name of the built-in attribute

is_customizable

boolean

A flag to indicate if the product attribute value can be customized by sellers when creating or editing a product. Applicable only if 'type=PRODUCT_PROPERTY'.

is_multiple_selection

boolean

A flag to indicate if multiple values can be provided for a product attribute when creating or editing a product. Applicable only if 'type=PRODUCT_PROPERTY'

is_requried

boolean

A flag to indicate if the product attribute is required **globally** when creating or editing a product. - true: The attribute is required in all regions. - false: The attribute is required only in some regions, or if certain conditions are met. Refer to 'required_regions' and 'requirement_conditions' for the specific requirements. Applicable only if 'type=PRODUCT_PROPERTY'

optional_regions

string

The markets where the attribute is purely optional, or required only under certain conditions. Refer to 'requirement_conditions' for details on markets with conditional requirements. Possible values: - DE: Germany - ES: Spain - FR: France - GB: United Kingdom - ID: Indonesia - IT: Italy - IE: Ireland - JP: Japan - MY: Malaysia - PH: Philippines - SG: Singapore - TH: Thailand - US: United States - VN: Vietnam - MX: Mexico Applicable only if 'is_requried=false'

required_regions

string

The markets where the attribute is required, without conditions. Possible values: - DE: Germany - ES: Spain - FR: France - GB: United Kingdom - ID: Indonesia - IT: Italy - IE: Ireland - JP: Japan - MY: Malaysia - PH: Philippines - SG: Singapore - TH: Thailand - US: United States - VN: Vietnam - MX: Mexico Applicable only if 'is_requried=false'

type

string

The attribute type. Possible values: - SALES_PROPERTY: Indicates sales attributes that define product variants. - PRODUCT_PROPERTY: Indicates product attributes that describe the product as a whole

values

string

A list of selectable values for the attribute

keyword

optional

string

Filter categories by this keyword in 'local_name'

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

id

string

The category ID

is_leaf

boolean

A flag to indicate if the category is a leaf category. **Note**: You can only create or edit products that belong to a leaf category

local_name

string

The name of the category

parent_id

string

The parent category ID. For the root category, the parent ID is '0'

permission_statuses

string

The shop's permission status for this category. Possible values: - AVAILABLE: You have the permission to create products in this category. - NON_MAIN_CATEGORY: This category is out of scope for this seller, and you do not have permission to use it. Contact your account manager for assistance

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

inventory_rules

string

A list of inventory allocation rules for all warehouses linked to the shop

inventory_rules_associated_warehouses

string

The list of markets where inventory from this warehouse is shared or dynamically allocated. **Note**: Applicable only for 'SHARED' and 'DYNAMIC' management modes

listing_methods

string

The methods at which sellers can list products in this shop. Possible values: - GLOBAL_PUBLISHING: Create a global product, then publish it to target local markets. - LOCAL_REPLICATION: Create local product, then replicate it to other target local markets

create_time_ge

optional

timestamp

Filter global products to show only those that are created on or after the specified date and time

create_time_le

optional

timestamp

Filter global products to show only those that are created on or before the specified date and time

seller_skus

optional

string

Filter global products by these seller SKU codes

status

optional

string

Filter global products by their status. Possible values: - PUBLISHED - UNPUBLISHED - DRAFT - DELETED

update_time_ge

optional

timestamp

Filter global products to show only those that are updated on or after the specified date and time

update_time_le

optional

timestamp

Filter global products to show only those that are updated on or before the specified date and time

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

id

string

The global product ID in TikTok Shop

title

string

The product title

create_time

timestamp

The time when the product is created

skus

string

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

status

string

The status of the product. Possible values: - PUBLISHED - UNPUBLISHED - DRAFT - DELETED

update_time

timestamp

The time when the product is last updated

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

translation_task_ids

optional

string

The image translation task IDs for retrieving translation results. Max count: 20

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

id

string

The ID to identify the image translation task

fail_reason

string

The reason why the translation task failed. Possible values: - Invalid image URI. - Internal processing error, please try calling this endpoint again. - This image can't be translated. Try a different image

original_image_uri

string

The URI of the original image

original_image_url

string

The URL of the original image

status

string

The translation result. Possible values: - PROCESSING: Translation is underway and has not yet completed. - COMPLETED: Translation has completed and results are ready. - FAILED: Translation did not complete due to an error

target_language

string

The target language to translate the image into. Possible values: - de-DE - en-IE - es-ES - fr-FR - it-IT

translated_image_uri

string

The URI of the translated image

translated_image_url

string

The URL of the translated image

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

product_ids

required

string

The product IDs for which you want to optimize the information. - Max IDs: 20 - The product must be live (status: 'ACTIVATE')

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

id

string

The product ID

suggestions

string

The suggestions for each product field

suggestions_items

string

The list of optimized text

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

product_ids

required

string

The product IDs for which you want to obtain SEO suggestions. - Max IDs: 20 - The product must be live ('ACTIVATE' status)

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

id

string

The product ID

seo_words

string

The list of SEO keyword suggestions for the product title

ids

optional

string

Filter size charts by size chart template IDs. Max: 50 IDs

keyword

optional

string

Filter size charts by size chart template name or by key words in the template name. If both 'ids' and 'keyword' are provided, 'ids' takes priority

locales

optional

string

The BCP-47 locale codes for displaying the size charts. Default: The default locale of your shop. Possible values: - de-DE - en-GB - en-IE - en-US - es-ES - es-MX - fr-FR - id-ID - it-IT - ja-JP - ms-MY - pt-BR - th-TH - vi-VN - zh-CN

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

images

string

The list of images included in a size chart

template_id

string

The size chart template ID

template_name

string

The size chart template name

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

order_ids

optional

string

CSV list of the unique identifier for a TikTok Shop order

initiate_aftersale_user

optional

string

The type of user you would like to check aftersale options for. Possible values: SELLER, BUYER. Default: SELLER

table_orders

optional

string

A table that contains columns id or order_id and update_time (e.g. output of the procedure tiktok_shops.Orders)

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

order_id

string

TikTok Shop order ID

eligible

boolean

Use this field to recognize whether an item is eligible for an aftersale request: - TRUE - FALSE

ineligible_code

integer

The reason code for an ineligible aftersale request

ineligible_reason

string

The reason for an ineligible aftersale request

order_line_items_ids

string

IDs of order line items

request_type

string

Aftersale request type. Possible values: - CANCEL - RETURN - RETURN_AND_REFUND

sku_id

string

SKU ID

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

buyer_user_ids

optional

string

List of TikTok Shop buyer user IDs

cancel_ids

optional

string

List of order cancellations IDs

create_time_ge

optional

timestamp

Filter cancellations to show only orders that have been created after a specified date and time

create_time_lt

optional

timestamp

Filter cancellations to show only orders that have been created before a specified date and time

order_ids

optional

string

List of TikTok Shop order IDs

update_time_ge

optional

timestamp

Filter cancellations to show only orders that have been updated after a specified date and time

update_time_lt

optional

timestamp

Filter cancellations to show only orders that have been updated before a specified date and time

cancel_types

optional

string

CSV list of order cancellation types. Possible values: - CANCEL: Cancel by seller or system. - BUYER_CANCEL: Cancel by buyer. Need to be approved by seller or system

cancel_status

optional

string

CSV list of order cancellation statuses. Possible values: CANCELLATION_REQUEST_PENDING, CANCELLATION_REQUEST_SUCCESS, CANCELLATION_REQUEST_CANCEL, CANCELLATION_REQUEST_COMPLETE

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

cancel_id

string

The identifier of a specific order cancellation

cancel_reason

string

Order cancellation reason

cancel_reason_text

string

Order cancellation reason, localized to another language. You can change language using the locale field in the request parameter

cancel_status

string

Order cancellation status. Possible values: - CANCELLATION_REQUEST_PENDING - CANCELLATION_REQUEST_SUCCESS - CANCELLATION_REQUEST_CANCELLED - CANCELLATION_REQUEST_COMPLETE

cancel_type

string

Order cancellation type. Possible values: - CANCEL: Cancel by seller or system. - BUYER_CANCEL: Cancel by buyer. Need to be approved by seller or system.

create_time

timestamp

Order cancellation create time

order_id

string

TikTok Shop order ID. Contains multiple order line item IDs

refund_amount_buyer_service_fee

bigdecimal

Only for the ID market. Platform will charge the buyer a service fee depending on the scenario.

refund_amount_currency

string

Refund currency

refund_amount_refund_shipping_fee

bigdecimal

Shipping fee refund amount to the buyer

refund_amount_refund_subtotal

bigdecimal

Subtotal refund amount to the buyer

refund_amount_refund_tax

bigdecimal

Tax refund amount to the buyer

refund_amount_refund_total

bigdecimal

Total refund amount to the buyer

refund_amount_retail_delivery_fee

bigdecimal

Retail delivery fee takes effect once platform GMV exceeds $500,000 USD, according to Colorado (US) compliance rules

role

string

Order cancellation initiator. Possible values: - BUYER - SELLER - SYSTEM

seller_next_action_response

string

Seller's next action and deadline

update_time

timestamp

Order cancellation update time

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

return_or_cancel_id

required

string

The unique identifier for an order return or cancellation

table_returns

optional

string

A table that contains columns return_id and update_time (e.g. output of the procedure tiktok_shops.ReturnAndRefund_Returns)

table_cancellations

optional

string

A table that contains columns cancel_id and update_time (e.g. output of the procedure tiktok_shops.ReturnAndRefund_Cancellations)

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

name

string

The reason name of a seller rejection

text

string

The corresponding text to the reason name, localized based on the locale input parameter

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

return_id

optional

string

A unique identifier for a TikTok Shop return request

table_returns

optional

string

A table that contains columns return_id and update_time (e.g. output of the procedure tiktok_shops.ReturnAndRefund_Returns)

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

return_id

string

TikTok Shop return ID

create_time

timestamp

The creation time for the return

description

string

Description of the return record

event

string

The type of order event. In this case, it will always be ORDER_RETURN

images

string

Images provided by the seller or buyer. You can use the role field to differentiate whether the images are from the seller or buyer

note

string

A note provided by the seller or buyer. You can use the role field to differentiate whether the note is from the seller or buyer

reason_text

string

The corresponding text for a return reason, localized based on the locale input parameter.

role

string

The role that initiated the order return request. Possible values: - BUYER - SELLER - OPERATOR: If the order is canceled by the customer service agent manually, then the cancel initiator will be 'OPERATOR'. - SYSTEM: If the order is automatically canceled due to a policy reason, then the cancel initiator will be 'SYSTEM'

shop_cipher

required

string

Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response

create_time_ge

optional

timestamp

Filter returns to show only those that are created on or after the specified date and time

create_time_lt

optional

timestamp

Filter returns to show only those that are created before the specified date and time

update_time_ge

optional

timestamp

Filter returns to show only those that are updated on or after the specified date and time

update_time_lt

optional

timestamp

Filter returns to show only those that are created before the specified date and time

order_ids

optional

string

CSV list of TikTok Shop order IDs

return_ids

optional

string

CSV list of return IDs

buyer_user_ids

optional

string

CSV list of TikTok Shop buyer user IDs

return_types

optional

string

CSV list of return types. Available values: REFUND, RETURN_AND_REFUND, REPLACEMENT

return_status

optional

string

CSV list of return status. Available values: - RETURN_OR_REFUND_REQUEST_PENDING: Buyer has initiated a return or refund request. The request is pending review by seller or system. - REFUND_OR_RETURN_REQUEST_REJECT: The return or refund request was rejected. - AWAITING_BUYER_SHIP: The return request was approved. The seller is waiting for the buyer to ship the approved items to the seller. If the buyer doesn't ship the items to the seller before the deadline, the platform will close the request. - BUYER_SHIPPED_ITEM: Buyer has shipped the approved items to seller. - REJECT_RECEIVE_PACKAGE: Seller inspected the returned items and rejected the return request. - RETURN_OR_REFUND_REQUEST_SUCCESS: The return/refund request was successful. The buyer will be refunded. - RETURN_OR_REFUND_REQUEST_CANCEL: The request has been cancelled by the buyer or system. - RETURN_OR_REFUND_REQUEST_COMPLETE: The return/refund was processed successfully. The buyer has been refunded. - AWAITING_BUYER_RESPONSE: Seller offer another return type to the buyer, and waiting buyer response. Seller proposed return type can check the seller_proposed_return_type

seller_proposed_return_type

optional

string

CSV list of seller proposed return types. Available values: PARTIAL_REFUND

arbitration_status

optional

string

CSV list of arbitration statuses. Available values: - IN_PROGRESS: The TikTok Shop platform operator is processing arbitration. Platform may request additional information from the seller. - SUPPORT_BUYER: The platform operator supports buyer. - SUPPORT_SELLER: The platform operator supports seller. - CLOSED: Arbitration is closed

preview

optional

boolean

Preview only, don't write into table

target_table

optional

string

Table name to save the data to

label

optional

string

Multi-tenancy label

arbitration_status

string

List of arbitration statuses. Available values: - 'IN_PROGRESS': The TikTok Shop platform operator is processing arbitration. Platform may request additional information from the seller. - 'SUPPORT_BUYER': The platform operator supports buyer. - 'SUPPORT_SELLER': The platform operator supports seller. - 'CLOSED': Arbitration is closed

buyer_rejected_partial_refund

boolean

Only return this field when seller initiated the partial refund. Available values: - 'TRUE': Buyer reject the seller partial refund offer. - 'FALSE': Buyer accept the seller partial refund offer or awaiting buyer response

can_buyer_keep_item

boolean

Whether buyer can keep the item(s) in a return or replacement process

combined_return_id

string

If 'is_combined_return' is 'true', this field will return the 'combined_return_id' associated with the combined return

create_time

timestamp

Return create time

handover_method

string

The handover method buyer chooses to use when returning item(s) to seller using platform's shipping service. - 'DROP_OFF': buyer will drop off the item(s) at courier - 'PICKUP': buyer is scheduling a pick up service offered by the courier

is_combined_return

boolean

This field will return true if the buyer is asking to combine multiple returns into one return package

next_return_id

string

The next return ID the current return order is edited to

order_id

string

TikTok Shop order ID. Contains multiple order line item IDs

partial_refund_amount

bigdecimal

The partial refund amount offered by seller. Note: only seller proposed partial refund will return this field

partial_refund_currency

string

Partial refund currency

pre_return_id

string

The previous return ID the current return order is edited from

refund_amount_buyer_service_fee

bigdecimal

Buyer service fee

refund_amount_currency

string

Refund currency

refund_amount_refund_shipping_fee

bigdecimal

Shipping fee refund

refund_amount_refund_subtotal

bigdecimal

Subtotal refund amount. This is the total price of all items returned.

refund_amount_refund_tax

bigdecimal

Tax fee refund

refund_amount_refund_total

bigdecimal

Total refund amount

refund_amount_retail_delivery_fee

bigdecimal

Retail delivery fee takes effect once platform GMV exceeds 500,000 USD, according to US Colorado states' compliance rules.

return_id

string

The identifier of a specific return

return_method

string

Return method: - 'SELLER_SHIPPED': Seller offers the return shipping service. - 'BUYER_SHIPPED': Buyer offers the return shipping service. - 'PLATFORM_SHIPPED': TikTok Shop offers the return shipping service

return_provider_id

string

The provider ID of parcel when buyer returns the items

return_provider_name

string

The provider name of parcel when buyer returns the item(s)

return_reason

string

Reason for return

return_reason_text

string

Reason for return, in localized text. You can change language using the locale request parameter.

return_shipping_document_type

string

The type of return shipping document selected by the buyer. Available values: - 'SHIPPING_LABE'L - 'QR_CODE'

return_status

string

Return status. Available values: - 'RETURN_OR_REFUND_REQUEST_PENDING': Buyer has initiated a return or refund request. The request is pending review by seller or platform. - 'REFUND_OR_RETURN_REQUEST_REJECT': The return or refund request was rejected. - 'AWAITING_BUYER_SHIP': The return request was approved. The seller is waiting for the buyer to ship the approved items to the seller. If the buyer doesn't ship the items to the seller before the deadline, the platform will close the request. - 'BUYER_SHIPPED_ITEM': Buyer has shipped the approved items to seller. - 'REJECT_RECEIVE_PACKAGE': Seller inspected the returned items and rejected the return package. - 'RETURN_OR_REFUND_REQUEST_SUCCESS': The return/refund request was approved. The buyer will be refunded. - 'RETURN_OR_REFUND_REQUEST_CANCEL': The request has been cancelled by the buyer or system. - 'RETURN_OR_REFUND_REQUEST_COMPLETE': The return/refund was processed successfully. The buyer has been refunded. - 'REPLACEMENT_REQUEST_PENDING': Buyer has initiated a replacement request. The request is pending review by seller. - 'REPLACEMENT_REQUEST_REJECT': Seller reject the buyer replacement request. - 'REPLACEMENT_REQUEST_REFUND_SUCCESS': Buyer's replacement request was resolved by refund due to insufficient inventory. - 'REPLACEMENT_REQUEST_CANCEL': Buyer canceled the replacement request. - 'REPLACEMENT_REQUEST_COMPLETE': Seller has approved the buyer's replacement request, platform will generate a new order for seller to fulfill. - 'AWAITING_BUYER_RESPONSE': Seller offer another return type to the buyer, and waiting buyer response. Seller proposed return type can check the 'seller_proposed_return_type'.

return_tracking_number

string

The tracking number of parcels when buyer returns the item(s)

return_type

string

Return type. Available values: - 'REFUND': Seller will issue a refund without return. The buyer is not required to send the item(s) back to the seller. - 'RETURN_AND_REFUND': Buyer is required to send the item(s) back to the seller. The seller will need to review the condition of the returned item(s) before a refund can be issued to the buyer. - 'REPLACEMENT': The buyer requires the seller to replace the item(s)

return_warehouse_address_full_address

string

The full return warehouse address

role

string