For US Markets: Introducing room_id in Order APIs

stable本次发布有变化全部展示

来自 TikTok Shop 官方资料快照 · 2026-09-06 12:42:37

打开官方原文 ↗

当前资料结构化阅读页
固定快照已留存，可追溯
官方原文可核对

查看技术与溯源信息

平台 / profile: TikTok Shop / profile.tiktok.docs_api
语言: en-US
发布版本: cn-20260909-2
标签: zhuge/sourceplatform/tiktok_shopaudience/developercategory/api_doctopic/compliancetopic/developer

资料正文

§1 For US Markets: Introducing room_id in Order APIs

Effective date: July 8, 2026

§2 Overview

Overview

Starting July 8, 2026, TikTok Shop will add room_id to selected Order API responses so your app can identify the LIVE session where an order line item was created. This change applies to apps that integrate with Order APIs for US market, especially apps that help LIVE sellers sort, reconcile, and fulfill orders by LIVE session. This is a non-breaking enhancement. Existing integrations will continue to work if they do not read the new field.

§3 What is changing

What is changing

Today, LIVE sellers can use Seller Center to separate orders by LIVE session, but apps that rely on Order APIs cannot consistently map each order line item to the LIVE session where it was created. The new room_id field gives your app a native session attribution key in the order response.

Workflow area	Before July 8, 2026	Starting July 8, 2026
LIVE order attribution	Your app cannot identify the originating LIVE session from Order API response data alone.	Your app can read `room_id` to identify the LIVE session where the order line item was created.
Order sorting and reconciliation	Your app may need Seller Center analytics, manual mapping, or custom backend logic to group orders by LIVE session.	Your app can group order line items by `room_id` and reconcile them with Seller Center LIVE analytics.
Fulfillment workflow	LIVE sellers may need to separate fulfillment batches outside the API response.	Your app can use `room_id` as a fulfillment batching and reconciliation key for LIVE sellers.

§4 Affected APIs

Affected APIs

API	Endpoint	Version	Change
Get Order List	`POST /order/202309/orders/search`	`v202309`	Adds `room_id` in order line item response data.
Get Order Detail	`GET /order/202309/orders`	`v202309`	Adds `room_id` to help identify the LIVE session for order data returned by this API.
Get Order Detail	`GET /order/202507/orders`	`v202507`	Adds `room_id` to help identify the LIVE session for order data returned by this API.

§5 New field

New field

Field	Type	Example	Description
`room_id`	`string`	`7652884452049160991`	The unique ID of the LIVE session where the order line item was created. If the order line item was not created from a LIVE session, this field returns an empty string.

Use room_id as a session attribution key. Do not use it as an order ID, package ID, product ID, or SKU ID.

§6 How to integrate

How to integrate

Confirm that your app uses an affected Order API. Check whether your app calls POST /order/202309/orders/search, GET /order/202309/orders, or GET /order/202507/orders.
Keep the required authorization scope. Apps that already use these Order APIs should continue to use the Order Information scope.
Parse room_id from response data. Read room_id from the order line item data returned by the affected APIs. Treat the value as a string, even if the example value is numeric.
Handle empty values. If an order line item was not created from a LIVE session, room_id returns an empty string. Your app must not treat an empty value as an API error.
Group fulfillment data at the line item level. If an order contains multiple line items, use line item data when grouping by room_id. Do not assume that all line items in one order have the same LIVE session attribution.
Reconcile with Seller Center analytics. Use room_id to match the LIVE session ID shown in Seller Center analytics when sellers need session-level reporting or fulfillment reconciliation.
Test both LIVE and non-LIVE orders. Test one order line item created from a LIVE session and one order line item not created from a LIVE session. Confirm that your app handles both a populated room_id and an empty string.

§7 Timeline and enforcement

Timeline and enforcement

Date	Milestone	Developer action
July 8, 2026	`room_id` becomes available in the affected Order API responses.	Start reading `room_id` if your app supports LIVE seller order sorting, reconciliation, or fulfillment by session.
After July 8, 2026	Apps can gradually adopt `room_id`.	Update response parsing, internal data models, and seller-facing workflows when session-level attribution is needed.

§8 Non-compliance impact

Non-compliance impact

This release does not introduce a mandatory migration deadline, new request parameter, new enum value, or new error code. If your app does not adopt room_id, existing API calls will continue to work. However, your app will not be able to use native Order API data to separate LIVE orders by session, which may continue to require manual reconciliation or Seller Center-only workflows for LIVE sellers.

§9 FAQ

FAQ

§10 Which markets are affected?

Which markets are affected?

Only support the US market for the time being, other markets are in planning.

§11 Is this a breaking change?

Is this a breaking change?

No. This is an additive response field. Existing integrations will continue to work if they ignore room_id.

§12 Does my app need a new authorization scope?

Does my app need a new authorization scope?

Apps that already call the affected Order APIs should continue to use the Order Information scope.

§13 Can I use `room_id` to filter orders in the request?

Can I use `room_id` to filter orders in the request?

No. It does not add a new request filter or sort parameter for room_id.

这条内容对你有帮助吗？