Order API overview

Order API overview

Context

The Orders API helps you obtain information about orders.

You may programmatically GET an Order List, and GET the Order Details from a specific Order.

Additionally, you may also subscribe to the Order Status Webhook to be notified regarding order status changes.

Important Concepts

Order

An order is created when the buyer clicks on the Place Order button. Please note that when the order is created, the buyer has yet to make the payment, therefore the status of the order is UNPAID. Once an order is created, the seller should deduct or hold inventory from their inventory management system accordingly.

Order Structure

1. Order ID: An Order ID is a unique identifier for each Order that is created by a Buyer.
2. SKU ID: An order line contains 1 or more items of products of the same Stock Keeping Unit. Each SKU is identified by its unique SKU ID. A SKU can be thought of as a "variant".
3. Order Line Item id: Each single item in a line is identified by its unique order line item id.

Example- A buyer places an order for 5 products total: 2 Red Large T-shirts, 2 Red Medium T-shirts, and 1 size 10 black shoes:

Order	SKU	Line item
Order ID: 12345678	Red Large T Shirt	1x Red Large T Shirt (item 1)
		1x Red Large T Shirt (item 2)
	Red Medium t shirt	1x Red Medium t shirt (item 3)
		1x Red Medium t shirt (item 4)
	Size 10 Black Shoes	1 size 10 black shoes (item 5)

Order Status

Order Status Definition

Status	Description
UNPAID	The order has been placed but payment has been authorized.
ON_HOLD	After payment is completed for the order, the order transitions into the ON_HOLD status during the remorse period. The remorse period allows the buyer to cancel the order without seller approval. ON_HOLD orders are not allowed to be fulfilled.
AWAITING_SHIPMENT	Awaiting the seller to place a logistic order.
PARTIALLY_SHIPPING	One or more (but not all) items in the order have been shipped.
AWAITING_COLLECTION	The logistics order was placed. At least one item in the order is still waiting to be collected by the carrier.
IN_TRANSIT	All items have been collected by the carrier. At least one package is has yet to be delivered to the buyer.
DELIVERED	All items have been delivered to the buyer.
COMPLETED	The order has been completed. Completed orders can no longer be returned or refunded.
CANCELLED	The order has been canceled. The order can be canceled by the buyer, the seller, the TikTok SYSTEM, or a TikTok OPERATOR. * Buyer: Buyers can change their mind and cancel within 1 hour post purchase, known as 1-hour remorse. Past this period, Buyer can still request a cancellation, but it is subject to Seller approval. * Seller: Sellers can cancel an order, for example if they are out of stock of the product. * SYSTEM: Orders may be cancelled by the TikTok system automatically based on TikTok policies. For example, this can happen if a package is lost in transit, and TikTok detects that the tracking ID has not progressed for over 7 days. * OPERATOR: Orders may also be cancelled by TikTok customer service for a variety of reasons. For a comprehensive list of supported cancellation reasons, please visit this page.

Order Status Transitions

1. From UNPAID to ON_HOLD

Trigger: When the order is paid, the order status updates to ON_HOLD. Trigger initiator: Buyer Note:

For ON_HOLD orders, the recipient address and buyer information are not available via the Order API. From UNPAID to ON_HOLD 1. Trigger: When the order is paid, the order status updates to ON_HOLD. 2. Trigger initiator: Buyer 3. Note:

For ON_HOLD orders, the recipient address and buyer information are not available via the Order API. Note: 1. For ON_HOLD orders, the recipient address and buyer information are not available via the Order API.

2. From ON_HOLD to AWAITING_SHIPMENT

Trigger: After the remorse window(1 hour after payment), the order status changes to AWAITING_SHIPMENT. Trigger initiator: TiKTok Note: This step occurs automatically. From ON_HOLD to AWAITING_SHIPMENT 1. Trigger: After the remorse window(1 hour after payment), the order status changes to AWAITING_SHIPMENT. 2. Trigger initiator: TiKTok 3. Note: This step occurs automatically.

3. From AWAITING_SHIPMENT to PARTIALLY_SHIPPING

Trigger: When some item(s) in the order but not all have been shipped. Trigger initiator: Seller Note: only split shipments have this status. If the seller ships all item(s) in the order within one package, this status is skipped. From AWAITING_SHIPMENT to PARTIALLY_SHIPPING 1. Trigger: When some item(s) in the order but not all have been shipped. 2. Trigger initiator: Seller 3. Note: only split shipments have this status. If the seller ships all item(s) in the order within one package, this status is skipped.

4. From AWAITING_SHIPMENT or PARTIALLY_SHIPPING to AWAITING_COLLECTION

Scenario A(seller ships all items in one package) : AWAITING_SHIPMENT to AWAITING_COLLECTION

Trigger: Seller calls API to ship all the item(s) in the order. Trigger initiator: Seller

Scenario B(Seller split order to ship): PARTIALLY_SHIPPING to AWAITING_COLLECTION

Trigger: Seller calls API to ship the unshipped item in the order. Only all the items have been arranged shipment, then the order status will be updated to AWAITING_COLLECTION. Trigger initiator: Seller

Note: Once the seller arranges shipment, the buyer can not cancel request without seller approval. From AWAITING_SHIPMENT or PARTIALLY_SHIPPING to AWAITING_COLLECTION 1. Scenario A(seller ships all items in one package) : AWAITING_SHIPMENT to AWAITING_COLLECTION

Trigger: Seller calls API to ship all the item(s) in the order. Trigger initiator: Seller Scenario A(seller ships all items in one package) : AWAITING_SHIPMENT to AWAITING_COLLECTION 1. Trigger: Seller calls API to ship all the item(s) in the order. 2. Trigger initiator: Seller

2. Scenario B(Seller split order to ship): PARTIALLY_SHIPPING to AWAITING_COLLECTION

Trigger: Seller calls API to ship the unshipped item in the order. Only all the items have been arranged shipment, then the order status will be updated to AWAITING_COLLECTION. Trigger initiator: Seller Scenario B(Seller split order to ship): PARTIALLY_SHIPPING to AWAITING_COLLECTION 1. Trigger: Seller calls API to ship the unshipped item in the order. Only all the items have been arranged shipment, then the order status will be updated to AWAITING_COLLECTION. 2. Trigger initiator: Seller

3. Note: Once the seller arranges shipment, the buyer can not cancel request without seller approval.

4. From AWAITING_COLLECTION to IN_TRANSIT

Scenario A(Seller ships all items in one package)

Trigger: Once TikTok obtains the shipment tracking information of packages from the carrier system, the order status will be updated to IN_TRANSIT from AWAITING_COLLECTION. Trigger initiator: TikTok

Scenario B(Seller split order to ship)

Trigger: Once Tiktok obtains the shipment tracking information of all packages from the carrier system, the order status will be updated to IN_TRANSIT from AWAITING_COLLECTION.

Note: TikTok obtains shipment tracking information from various tracking data providers. Depending on the performance of the provider, the tracking information may be delayed. If the shipment tracking information delay is over 24 hours, please contact TikTok. From AWAITING_COLLECTION to IN_TRANSIT 1. Scenario A(Seller ships all items in one package)

Trigger: Once TikTok obtains the shipment tracking information of packages from the carrier system, the order status will be updated to IN_TRANSIT from AWAITING_COLLECTION. Trigger initiator: TikTok Scenario A(Seller ships all items in one package) 1. Trigger: Once TikTok obtains the shipment tracking information of packages from the carrier system, the order status will be updated to IN_TRANSIT from AWAITING_COLLECTION. 2. Trigger initiator: TikTok

2. Scenario B(Seller split order to ship)

Trigger: Once Tiktok obtains the shipment tracking information of all packages from the carrier system, the order status will be updated to IN_TRANSIT from AWAITING_COLLECTION. Scenario B(Seller split order to ship) 1. Trigger: Once Tiktok obtains the shipment tracking information of all packages from the carrier system, the order status will be updated to IN_TRANSIT from AWAITING_COLLECTION.

3. Note: TikTok obtains shipment tracking information from various tracking data providers. Depending on the performance of the provider, the tracking information may be delayed. If the shipment tracking information delay is over 24 hours, please contact TikTok.

4. From IN_TRANSIT to DELIVERED

Trigger: The package has been successfully delivered. Trigger initiator: TikTok From IN_TRANSIT to DELIVERED 1. Trigger: The package has been successfully delivered. 2. Trigger initiator: TikTok

7. From DELIVERED to COMPLETED.

Scenario A(Buyer requests refund or return)

Trigger: Buyers can initiate a multi-time return or refund request. Once the order amount is a full refund to the buyer, the order status will be updated to COMPLETED. Trigger initiator: Seller/TikTok

Scenario B(Seller initiate refund or return)

Trigger: Seller can initiate a multi-time return or refund. Once the order amount is a full refund to the buyer, the order status will be updated to COMPLETED. Trigger initiator: Seller

Scenario C(TikTok)

Trigger: Order available refund amount fully be refunded before the after-sales period is over. Trigger initiator: TikTok

Note: Different region and business mode (Local to Local or cross border modes) after-sales period is different. Please refer to the seller academy for applicable after-sales policies. From DELIVERED to COMPLETED. 1. Scenario A(Buyer requests refund or return)

Trigger: Buyers can initiate a multi-time return or refund request. Once the order amount is a full refund to the buyer, the order status will be updated to COMPLETED. Trigger initiator: Seller/TikTok Scenario A(Buyer requests refund or return) 1. Trigger: Buyers can initiate a multi-time return or refund request. Once the order amount is a full refund to the buyer, the order status will be updated to COMPLETED. 2. Trigger initiator: Seller/TikTok

2. Scenario B(Seller initiate refund or return)

Trigger: Seller can initiate a multi-time return or refund. Once the order amount is a full refund to the buyer, the order status will be updated to COMPLETED. Trigger initiator: Seller Scenario B(Seller initiate refund or return) 1. Trigger: Seller can initiate a multi-time return or refund. Once the order amount is a full refund to the buyer, the order status will be updated to COMPLETED. 2. Trigger initiator: Seller

3. Scenario C(TikTok)

Trigger: Order available refund amount fully be refunded before the after-sales period is over. Trigger initiator: TikTok Scenario C(TikTok) 1. Trigger: Order available refund amount fully be refunded before the after-sales period is over. 2. Trigger initiator: TikTok

4. Note: Different region and business mode (Local to Local or cross border modes) after-sales period is different. Please refer to the seller academy for applicable after-sales policies.

5. From UNPAID to CANCELLED

Scenario A(Buyer cancel the order)：

Trigger: Buyer cancel UNPAID status order. Trigger initiator: Buyer

Scenario B(TikTok cancel the order)：

Trigger: The buyer has not paid for the order within the specified time(different region has different setting). Trigger initiator: TikTok From UNPAID to CANCELLED 1. Scenario A(Buyer cancel the order)：

Trigger: Buyer cancel UNPAID status order. Trigger initiator: Buyer Scenario A(Buyer cancel the order)： 1. Trigger: Buyer cancel UNPAID status order. 2. Trigger initiator: Buyer

2. Scenario B(TikTok cancel the order)：

Trigger: The buyer has not paid for the order within the specified time(different region has different setting). Trigger initiator: TikTok Scenario B(TikTok cancel the order)： 1. Trigger: The buyer has not paid for the order within the specified time(different region has different setting). 2. Trigger initiator: TikTok

9. From ON_HOLD to CANCELLED

Scenario A(Buyer cancel the order)

Trigger: Buyer cancel order in remorse window. Trigger initiator: Buyer

Scenario B(Seller cancel the order)

Trigger: The seller cancels the order due to being out of stock. Trigger initiator: Seller

Note: The order status will only updated to 'CANCELLED' when all items in the order have been cancelled. From ON_HOLD to CANCELLED 1. Scenario A(Buyer cancel the order)

Trigger: Buyer cancel order in remorse window. Trigger initiator: Buyer Scenario A(Buyer cancel the order) 1. Trigger: Buyer cancel order in remorse window. 2. Trigger initiator: Buyer

2. Scenario B(Seller cancel the order)

Trigger: The seller cancels the order due to being out of stock. Trigger initiator: Seller Scenario B(Seller cancel the order) 1. Trigger: The seller cancels the order due to being out of stock. 2. Trigger initiator: Seller

3. Note: The order status will only updated to 'CANCELLED' when all items in the order have been cancelled.

4. From AWAITING_SHIPMENT to CANCELLED

Scenario A(Buyer cancel the order)

Trigger: Buyer initiates cancel request and seller accepts. Trigger initiator: Buyer

Scenario B(Seller cancel the order)

Trigger: Seller cancels the order due to being out of stock. Trigger initiator: Seller

Scenario C(TikTok cancel the order)

Trigger: TikTok cancels the order, because the seller doesn't arrange shipment before TikTok requires time. Trigger initiator: TikTok

Note: The order status will only updated to 'CANCELLED' when all items in the order have been cancelled. From AWAITING_SHIPMENT to CANCELLED 1. Scenario A(Buyer cancel the order)

Trigger: Buyer initiates cancel request and seller accepts. Trigger initiator: Buyer Scenario A(Buyer cancel the order) 1. Trigger: Buyer initiates cancel request and seller accepts. 2. Trigger initiator: Buyer

2. Scenario B(Seller cancel the order)

Trigger: Seller cancels the order due to being out of stock. Trigger initiator: Seller Scenario B(Seller cancel the order) 1. Trigger: Seller cancels the order due to being out of stock. 2. Trigger initiator: Seller

3. Scenario C(TikTok cancel the order)

Trigger: TikTok cancels the order, because the seller doesn't arrange shipment before TikTok requires time. Trigger initiator: TikTok Scenario C(TikTok cancel the order) 1. Trigger: TikTok cancels the order, because the seller doesn't arrange shipment before TikTok requires time. 2. Trigger initiator: TikTok

4. Note: The order status will only updated to 'CANCELLED' when all items in the order have been cancelled.

5. From PARTIALLY_SHIPPING to CANCELLED

Trigger: Buyer cancels the unshipped and Tiktok cancels the shipped item Trigger initiator: Buyer and Tiktok Note: The order status will only updated to 'CANCELLED' when all items in the order have been cancelled. From PARTIALLY_SHIPPING to CANCELLED 1. Trigger: Buyer cancels the unshipped and Tiktok cancels the shipped item 2. Trigger initiator: Buyer and Tiktok 3. Note: The order status will only updated to 'CANCELLED' when all items in the order have been cancelled.

12. From AWAITING_COLLECTION to CANCELLED

Scenario A(Seller cancels the order)

Trigger: Seller cancels the order. If order has been split, order status will update to CANCELLED when all the split order been canceled. Trigger initiator: seller

Scenario B(Tiktok cancels the order)

Trigger: Tiktok cancels the order because TikTok can not obtain shipment tracking information from various tracking data providers before TikTok requires time. If order has been split, order status will update to CANCELLED when all the split order been canceled. Trigger initiator: Tiktok

Note: Only the US market allows sellers to cancel order under AWAITING_COLLECTION status. The order status will only updated to 'CANCELLED' when all items in the order have been cancelled. From AWAITING_COLLECTION to CANCELLED 1. Scenario A(Seller cancels the order)

Trigger: Seller cancels the order. If order has been split, order status will update to CANCELLED when all the split order been canceled. Trigger initiator: seller Scenario A(Seller cancels the order) 1. Trigger: Seller cancels the order. If order has been split, order status will update to CANCELLED when all the split order been canceled. 2. Trigger initiator: seller

2. Scenario B(Tiktok cancels the order)

Trigger: Tiktok cancels the order because TikTok can not obtain shipment tracking information from various tracking data providers before TikTok requires time. If order has been split, order status will update to CANCELLED when all the split order been canceled. Trigger initiator: Tiktok Scenario B(Tiktok cancels the order) 1. Trigger: Tiktok cancels the order because TikTok can not obtain shipment tracking information from various tracking data providers before TikTok requires time. If order has been split, order status will update to CANCELLED when all the split order been canceled. 2. Trigger initiator: Tiktok

3. Note: Only the US market allows sellers to cancel order under AWAITING_COLLECTION status. The order status will only updated to 'CANCELLED' when all items in the order have been cancelled.

4. From IN_TRANSIT to CANCELLED

Trigger: Tiktok cancels the order. If order has been split, order status will update to CANCELLED when all the split order been canceled. Trigger initiator: Tiktok Note: this situation commonly occurs when the package is lost during transit or the buyer refuses to receive package. The order status will only updated to 'CANCELLED' when all items in the order have been cancelled. From IN_TRANSIT to CANCELLED 1. Trigger: Tiktok cancels the order. If order has been split, order status will update to CANCELLED when all the split order been canceled. 2. Trigger initiator: Tiktok 3. Note: this situation commonly occurs when the package is lost during transit or the buyer refuses to receive package. The order status will only updated to 'CANCELLED' when all items in the order have been cancelled.

14. From AWAITING_COLLECTION to COMPLETED

Trigger: Buyer initiates refund request and seller accept Trigger initiator: Buyer Note: Once the order amount is fully refunded, order status will change to COMPLETED. The order status will only updated to 'CANCELLED' when all items in the order have been cancelled. From AWAITING_COLLECTION to COMPLETED 1. Trigger: Buyer initiates refund request and seller accept 2. Trigger initiator: Buyer 3. Note: Once the order amount is fully refunded, order status will change to COMPLETED. The order status will only updated to 'CANCELLED' when all items in the order have been cancelled.

15. From IN_TRANSIT to COMPLETED

Scenario A(Buyer initiate refund request)

Trigger: Buyer initiates refund request and seller accepts. Trigger initiator: Buyer

Scenario B (Tiktok auto approve buyer refund request)

Trigger: Buyer initiates refund request. When the time exceeds the latest estimated delivery time, Tiktok will auto approve the buyer refund request. Trigger initiator: Tiktok

Note: Once the order amount is fully refunded, order status will change to COMPLETED. The order status will only updated to 'CANCELLED' when all items in the order have been cancelled. From IN_TRANSIT to COMPLETED 1. Scenario A(Buyer initiate refund request)

Trigger: Buyer initiates refund request and seller accepts. Trigger initiator: Buyer Scenario A(Buyer initiate refund request)

1. Trigger: Buyer initiates refund request and seller accepts.

2. Trigger initiator: Buyer

3. Scenario B (Tiktok auto approve buyer refund request)

Trigger: Buyer initiates refund request. When the time exceeds the latest estimated delivery time, Tiktok will auto approve the buyer refund request. Trigger initiator: Tiktok Scenario B (Tiktok auto approve buyer refund request)

1. Trigger: Buyer initiates refund request. When the time exceeds the latest estimated delivery time, Tiktok will auto approve the buyer refund request.

2. Trigger initiator: Tiktok

3. Note: Once the order amount is fully refunded, order status will change to COMPLETED. The order status will only updated to 'CANCELLED' when all items in the order have been cancelled.

Fulfillment Types and Delivery Options

Fulfillment Types

TikTok Shop offers two fulfillment types:

1. FULFILLMENT_BY_SELLER: The seller fulfills orders directly from their own warehouses. In this model, the seller is responsible for storing, packaging, and shipping the products to customers.
2. FULFILLMENT_BY_TIKTOK: The seller stocks their products in Tiktok's fulfillment centers. Tiktok is responsible for storing, picking, packing, and shipping the products to customers.

Shipping type

For FULFILLMENT_BY_SELLER, there are two shipping types:

1. TikTok Shipping: Tiktok provides shipping services. The seller obtains shipping labels from Tiktok.
2. Seller Shipping: The seller arranges shipping.

Recipient Address

Recipient Information Redaction

In the following scenarios, the recipient's address and personal information will be redacted.

1. Order fulfillment_type = FULFILLMENT_BY_TIKTOK
2. Order fulfillment_type = FULFILLMENT_BY_SELLER and shipping type = TikTok

Localized Recipient Address

Different countries may have different address hierarchy and naming conventions. To accommodate such differences, use 'district_info_list' to obtain address information expressed in the local address hierarchy and naming convention.

Order SLA (Service Level Agreement) Information

Currently, Tiktok shop has the following Service Level Agreement concept.

rts_sla: "RTS" is the abbreviation for Ready To Ship. RTS marks the time when the order status transitions to AWAITING_COLLECTION. rts_sla indicates the time period within which TikTok requires the seller to ship the order. If the order status has not transitioned to AWAITING_COLLECTION before rts_sla has passed, this constitutes a late dispatch, which will increase the seller's late dispatch rate.

tts_sla: "TTS" stands for Transfer To Ship. TTS marks the time when the order status transitions to IN_TRANSIT. tts_sla specifies the time period within which TikTok requires the packages to be collected by the carrier. If the order status has not transitioned to IN_TRANSIT before tts_sla has passed, this constitutes a late dispatch, which will increase the seller's late dispatch rate.

delivery_sla: The time period within which TikTok requires the packages to be delivered to the buyer.

cancel_order_sla: If the seller fails to complete the shipment by this time point, the order will be automatically canceled by the platform. TikTok might cancel the order, if the order doesn't arrange the shipment before rts_sla or the order can not obtain the tracking information before tts_sla. Policy details, please see the Seller Academy.

TikTok Shop Marketplace Policies

As a Marketplace, TikTok Shop imposes certain policies on sellers for the benefit of both buyers and sellers.

Cancel Policy

Buyer cancel order within 1-hour:

1. Buyers are able to cancel their order within one hour for no charge: this is known as the 1-hour remorse period. This is required for all shops. We simply recommend that sellers wait one hour before beginning fulfillment of the Order, and for all apps and services to implement this 1-hour remorse period. In markets where the ON_HOLD status is available, this 1-hour remorse window is the ON_HOLD status.

Buyer request cancel after 1-hour:

1. After 1-hour, buyer cancel request required to review by seller. The seller can accept or decline the cancel request.

Order Fulfillment SLA(Service Level Agreement) Policy

1. The seller should arrange shipment before rts_sla time.
2. The shipping service provider must update the tracking information of package collection before the tts_sla time.
3. If the Seller is not able to fulfill an Order with a valid shipping ID before cancel_order_sla, the Order will be cancelled and the Buyer refunded.

Frequently Asked Questions

1. How do I get order ID from?

To utilize the Orders API, you must subscribe to the Orders Webhook. Click here for more details How do I get order ID from? 1. To utilize the Orders API, you must subscribe to the Orders Webhook. Click here for more details

2. My item is partially out of stock. Can I ship only part of the Order?

Currently, we don't provide this functionality. If this is a must have requirement, reach out to our CST team and we will see if we can get you access to a beta API which may be able to address this. My item is partially out of stock. Can I ship only part of the Order? 1. Currently, we don't provide this functionality. If this is a must have requirement, reach out to our CST team and we will see if we can get you access to a beta API which may be able to address this.

3. Can I completely cancel an order?

Yes, you can call Cancel Order API to cancel order. Can I completely cancel an order? 1. Yes, you can call Cancel Order API to cancel order.

4. How do I ship a new order which is a replacement for an existing one (ie package lost)?

Currently, we don't have replacement functionality. If this is a must have requirement, please ask buyer to cancel the order and replace an order. How do I ship a new order which is a replacement for an existing one (ie package lost)? 1. Currently, we don't have replacement functionality. If this is a must have requirement, please ask buyer to cancel the order and replace an order.

5. How can I check the order line item information?

You can call Get Order Detail API to obtain it from line_items. How can I check the order line item information? 1. You can call Get Order Detail API to obtain it from line_items.

6. How can I know is the order fulfilled by Tiktok?

You can call Get Order Detail API to obtain it from fulfillment_type. How can I know is the order fulfilled by Tiktok? 1. You can call Get Order Detail API to obtain it from fulfillment_type.

7. How can I know the order shipping service offered by platform or seller?

You can call Get Order Detail API to obtain it from delivery_option_id. How can I know the order shipping service offered by platform or seller? 1. You can call Get Order Detail API to obtain it from delivery_option_id.

8. How can I know whether the order line item is gift?

You can call Get Order Detail API to obtain it from is_gift. How can I know whether the order line item is gift? 1. You can call Get Order Detail API to obtain it from is_gift.

9. Can a Buyer place an order from multiple shops?

Yes! Buyers can place an order from multiple shops at once. For example, if I buy some products from Shop A, and some products from Shop B, TTS will actually create 2 orders. Can a Buyer place an order from multiple shops? 1. Yes! Buyers can place an order from multiple shops at once. For example, if I buy some products from Shop A, and some products from Shop B, TTS will actually create 2 orders.

Is this content helpful?Helpful

Not Helpful

PreviousNext