TikTok Shop

TikTok Shop order API: the fields that actually matter

The first time you pull an order off the TikTok Shop API you get a wall of JSON, and almost none of it is the thing you need. The fields that matter to a dropshipper are a short list, and knowing which ones they are saves you writing a parser around data you will never read.

This is that list, in the order you actually use them.

The identifiers you cannot lose

A TikTok order has more than one id, and they are not interchangeable. The order_id is the one the buyer sees and the one you quote in support. Underneath it, every line has its own order_line_id, and that is the unit fulfilment works on.

This matters more than it sounds. A two-item order is one order_id and two order_line_id values, and TikTok will treat those lines separately if they ship separately. If your sheet keys on the order id alone, a partial dispatch has nowhere to go.

• order_id - the buyer-facing reference, and your dedupe key
• order_line_id - the fulfilment unit, one per item per quantity
• buyer_uid - stable across orders, useful for spotting repeat buyers and repeat problems

The clock fields

Three timestamps decide whether you are late, and they are not the same thing.

create_time is when the order was placed. paid_time is when the money cleared, and that is usually the one your dispatch deadline counts from, not the creation time. rts_sla_time - ready to ship - is the deadline itself, expressed as an absolute timestamp rather than a duration.

That last one is the single most useful field in the payload and the one most integrations ignore. You do not have to calculate the deadline from a handling-time policy. TikTok tells you the exact moment you turn late. Put it in a column, sort by it, and your day has an order of work.

What you need to buy the item

The recipient address sits under recipient_address, and it is the block you will be copying into a supplier order. It arrives as structured fields plus a full_address convenience string. Use the structured fields if you are automating, because the convenience string concatenates in an order that is not always what the supplier form expects.

Be aware that TikTok masks parts of the address and the phone number on some regional storefronts until the order is confirmed. If you buy from the supplier before confirmation, you may be buying against a masked address.

What you need to know your margin

The money fields are where sellers get caught. payment.total_amount is what the buyer paid - it is not what you receive. Platform fees, any TikTok-funded discount, and the seller-funded portion of a promotion all sit in separate fields, and the settlement comes later still.

If your profit column subtracts your supplier cost from total_amount, that column is wrong, and it is wrong in the optimistic direction, which is the worst way for a number to be wrong. Treat the order payload as provisional revenue and reconcile against the settlement.

The fields you can safely ignore

A lot of the payload exists for TikTok Shop sellers who hold their own stock and use TikTok logistics. If you are buying from a supplier and shipping with your own tracking, the warehouse ids, the package-level fields and the label references are not for you.

Read the five things above into a row - order id, line ids, paid time, ready-to-ship deadline, address - and you have everything a dropshipping workflow consumes. The rest is for a different kind of seller.

---