Marketplaces / TikTok Marketplace Integration / TikTok - Order management - OLD / TikTok - Get Orders - OLD

TikTok - Get Orders - OLD

Summary of changes:

Date	Version	Changes
24/06/2022	1.1	Some fields in mapping table changed;

Added more clarification for some fields into the mapping More info regarding AWAITING_COLLECTION = 112; UNPAID = 100; statuses added | | 27/06/2022 | 1.2 | changed the sign into the description part (<); | | 28/06/2022 | 1.3 | Mapping fields updated; | | 05/07/2022 | 1.4 | Mapping for Order note changed; Typo corrected in descriptive part ; | | 22/07/2022 | 1.5 | Discount Amount field updated with Discount Value as per comment | | 24/07/2022 | 1.6 | Payment method values corrected based on TikTok last requrements | | 26/07/2022 | 1.7 | SKU ID mapped to Product in Order > Item Order Line ID | | 03/08/2022 | 1.8 | Noted added on paid_time field based on Jira bug | | 17/08/2022 | 1.9 | paid_time field note updated | | 16/09/2022 | 2.0 | Mapping for region added (ров 60 & 61) | | 09/11/2023 | 2.1 | Added logic for item price calculation when there is a discount |

The purpose of Get Orders section is to describe in details how we will download orders from TikTok in Hemi & how we will enrich already downloaded orders.

Basically, to download orders, first we need to make “Get Order List“ API call. We will use this call in order to get the order_id. Immediately after this call, we need to perform “Get Order Details“ call and using the order_ids, returned from “Get Order List“ , we can get all related information for order, like shipping info, payment method info, products in order information, and all the other information, related to order (details described into Get Order details call). “Get Order List“ & “Get Order Details” API calls will be incorporated in one cron.

The first run will check for new orders in the last 90 days and afterwards we will get the date from last_date_run table and filter orders using parameter:

date_updated_from - {last_date_run - 2 hours}

When we download the order IDs (with ”Get Order List” API call) we need to check if the order already exist in Hemi, if not exist, we need to store all related information in Hemi and also- to download the order in Hemi on respectively statuses.

Order statuses:

TikTok status	Hemi Status	Hemi Notes
UNPAID = 100;	Pending	This is our status that means there is something still to be done with the order prior to it being ready for any fulfilment.
Before the order is paid buyer can cancel or it passed the payment deadline (24hours UK) the order will be auto cancelled;
AWAITING_SHIPMENT = 111;	Pending AND Ready For Shipping	For the first one hour, the status in Hemi will be “Pending“ because of the grace period in which client can cancel the order for free.
After this 1 hour, the status need to be updated to ““Ready for Shipping“. Now() - Orders>Order Paid Time > 1hour
AWAITING_COLLECTION = 112;	Incomplete	As we will implement merchant fulfillment method, there is no chance to receive this status, but to be on the safe side, this status will be mapped to Incomplete.
“Awaiting_Collection“ status is used only for Platform Logistic fullfilment method, which method is not part of the scope.
IN_TRANSIT = 121;	Shipped	If we download an order on status “In_Transit“, we need to make sure we will store the order in Hemi with respectively internal status, which will be “Shipped“
DELIVERED = 122;	Shipped	It is possible to download order on this status. If the order does not exist in Hemi, we should download it with the respectively status.
COMPLETED = 130;	Shipped	It is possible to download order on this status. If order does not exist in Hemi, we should download it with the respectively status.
CANCELLED = 140;	Canceled	If we download an order on status “Cancelled“, we need to make sure we will store the order in Hemi with respectively internal status, which will be “Canceled“

If the order not exist in Hemi, and order paid time is less than 1 hour (NOW() - Order Paid Time < 1 hour) we will download the order on status Awaiting Shipment and in Hemi the status will be “Pending“. ( Buyer has 1 hour grace period to cancel the order freely, thats why we need to verify the order paid time); Orders which are on status “pending“ will be picked by the next run of the cron, requirements will be verified, and only if the requirements are covered, the status will be changed to “Ready For Shipping“;

If the order not exist in Hemi, and order paid time is greater than 1 hour (NOW() - Order Paid Time > 1 hour) we will download the order on status “Ready For Shipping“. Before we set order to “RFS“ status, we need to make sure the order contain all crucial mandatory information from the MP, should have payment, should be checked for bundles, shipment cost should be broken down on all items, sellers and original prices (cost) added, taxes and fees applied as per our standard enrichment process you can find here: Order management general requirements

(we take care of bundles internally and use our standard logic for debundling).

If the order already exist, we need to check the status of the order and to check if the order status can be changed, according to order status on the marketplace. (detailed table with statuses is described above, under “Get Order List“ mapping).

If the order not exist in Hemi but its status is “In Transit“ , “Delivered“, “Completed“ оr “Cancelled“, we will download this order in Hemi and the order will be with the respectively status in Hemi (as per table with statuses above)

Get order list

We will use this API call to get the order_id and after this, will use this order_id to get all information, related to the order (GetOrderDetails)

API Call: POST /api/orders/search

API Docs: https://developers.tiktok-shops.com/documents/document/237434

Request parameters:

Parameter	Value	Required	Comment
update_time_from	int	N	1623812664
page_size	int32	Y	Use this field to specify the maximum number of orders to obtain in a single page. Must be 1-50.

Example query & body:

https://open-api.tiktokglobalshop.com/api/orders/search?app_key=12abcd&access_token=abc1c123-3128-aa17-125e-2d2d51ab814fa&sign=28212f44f16270f3583e5b812af4dad7e5c07bd4b09c9832ff320a66526afefc&timestamp=1628743416&shop_id=123456

{
    "update_time_from": 1633994716,
    "page_size":50
}

Example Response:

{
    "code": 0,
    "message": "Success",
    "request_id": "02162513320727800000000000000000000ffff0ae7f06c9f1968",
    "data": {
        "order_list": [
            {
                "order_id": "576463220456522968",
                "order_status": 100,
                "update_time": 1634106101
            },
            {
                "order_id": "576463220456260824",
                "order_status": 100,
                "update_time": 1634106101
            }
        ],
        "more": true,
        "next_cursor": "390r2hHJILRaASHiJeL3ARsZ2PL0Ms332p3iEvL+i+EgFfjY8RwqxfuyV/uvtie2g4DXwLUu1CUr6+YxpZl1LA=="
    }
}

Mapping:

Integration Field			Integration Notes	Hemi Mapping
`data`			object
	`order_list`		object[]	N/A
		`order_id`	string
Unique id, same order id represent for the same order in the system		Orders > Marketplace Order ID
		`order_status`	int 32	Orders > Order Status
		`update_time`	int 32
Unix timestamp		N/A
	`more`		bool
Whether has more orders in next page nor not		N/A
	`next_cursor`		string
Cursor used for searching for more info.		N/A

Get order details

In order to get order details we must use order_id from the above call. Both calls ( Get Order ID & Get Order Details) should be implemented into 1 cron.

API Call: POST /api/orders/detail/query

API Docs: https://developers.tiktok-shops.com/documents/document/237427

Request Parameter:

Parameter	Value	Required	Comment
`order_id_list`	string[]	Y	Recommend less than 20, Must be less than 50 .

Example request - query & body:

https://open-api.tiktokglobalshop.com/api/orders/detail/query?app_key=12abcd&access_token=abc1c123-3128-aa17-125e-2d2d51ab814fa&sign=28212f44f16270f3583e5b812af4dad7e5c07bd4b09c9832ff320a66526afefc&timestamp=1628743416
{
    "order_id_list":["576461413038785752"]
}

Example Response- New

{
  "code": 0,
  "data": {
    "order_list": [
      {
        "buyer_message": "abcde",
        "buyer_uid": "7021436810468230477\n",
        "cancel_order_sla": "1619621355\n",
        "cancel_reason": "Pricing error\n",
        "cancel_user": "SELLER\n",
        "create_time": "1619611561674",
        "delivery_option": "STANDARD",
        "ext_status": "101\n\n",
        "fulfillment_type": "0\n",
        "item_list": [
          {
            "product_id": "1729382476852921560\n",
            "product_name": "test cart 50 sku\n",
            "quantity": "5\n",
            "seller_sku": "X-123\n",
            "sku_cancel_reason": "",
            "sku_cancel_user": "",
            "sku_display_status": "",
            "sku_ext_status": 101,
            "sku_id": "2729382476852921560\n",
            "sku_image": "https://p19-oec-sg.ibyteimg.com/tos-maliva-i-o3syd03w52-us/12345670c5480408aa668",
            "sku_name": "white,128g\n",
            "sku_original_price": "5000\n",
            "sku_platform_discount": "500\n",
            "sku_rts_time": "",
            "sku_sale_price": "5000\n\n",
            "sku_seller_discount": "500\n",
            "sku_type": 0
          }
        ],
        "order_id": "576461413038785752",
        "order_line_list": [
          {
            "order_line_id": "",
            "sku_id": "2729382476852921560"
          }
        ],
        "order_status": 100,
        "order_status_old": "",
        "package_list": [
          {
            "package_id": "2882335594258860015\n"
          }
        ],
        "paid_time": 1619611563,
        "payment_info": {
          "currency": "IDR\n",
          "original_shipping_fee": 5000,
          "original_total_product_price": 5000,
          "platform_discount": 5000,
          "seller_discount": 5000,
          "shipping_fee": 5000,
          "shipping_fee_platform_discount": 5000,
          "shipping_fee_seller_discount": 5000,
          "sub_total": 5000,
          "taxes": 5000,
          "total_amount": 5000
        },
        "payment_method": "BANK_CARD",
        "receiver_address_updated": 0,
        "recipient_address": {
          "address_detail": "unit one building 8\n",
          "address_line_list": [
            "",
            ""
          ],
          "city": "Central Bangka Regency\n",
          "district": "Koba",
          "full_address": "Indonesia, Bangka Belitung Province, Central Bangka Regency, Koba, Arung Dalam, ",
          "name": "zay\n",
          "phone": "(+86)12345678980\n",
          "region": "Indonesia\n\n",
          "region_code": "ID",
          "state": "Bangka Belitung Province\n",
          "town": "Arung Dalam\n",
          "zipcode": "23683\n"
        },
        "rts_sla": "1619611688\n",
        "rts_time": 1619611563,
        "seller_note": "seller note",
        "shipping_provider": "TT Virtual express\n",
        "shipping_provider_id": "6617675021119438849\n",
        "split_or_combine_tag": "combined\n",
        "tracking_number": "JX12345",
        "tts_sla": "1619611761\n",
        "update_time": "1619621355\n\n"
      }
    ]
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}

Mapping:

	Integration Field			Integration Notes	Hemi Mapping
1	`order_list`
2		`buyer_message`		string
The note from buyer.		Order > Note
3		`buyer_uid`		string
Buyer User ID.		Order > Buyer User ID
4		`cancel_order_sla`			N/A
5		`cancel_reason`		string
The reason for sku cancelling action.		N/A	As per performed tests, when we call “Get Orders Details“ we do not receive this field. We can see this field once we call “GetReverseOrderList“, which will give us information regarding reasons.
6		`cancel_user`			N/A
7		`create_time`		string
Unix timestamp for ms.		Order > Order Created Time
8		`delivery_option`		string

The method of delivery. Available value: STANDARD/ EXPRESS/ ECONOMY/ SEND_BY_SELLER . Orders with STANDARD / EXPRESS / ECONOMY are platform logistics mode. Applicable region: cross-border & ID local Orders with SEND_BY_SELLER are merchant self-shipping mode. Applicable region: UK local STANDARD=1 EXPRESS=2 ECONOMY=3 SEND_BY_SELLER=4 | | Orders > Shipping Service | (Based on TikTok Seller Center Account settings, we will receive only Send_By_Seller option) | | 9 | | ext_status | | Sub-status of order status. Developer can ignore 0 and 101-104. 201, 202, 203 are the corresponding status for the scenario of buyer-request cancellation. Buyer-request cancellation can only be triggered by buyers BEFORE the order is arranged shipment(order_status=112). Buyers can only request return/refund AFTER Available value: UN_DEFINED = 0;RC_PROCESSING = 101; // Risk control in progressRC_APPROVED = 102; // Risk control approvedRC_AUTO_APPROVED = 103; // Risk control expired with no | | N/A | | | 10 | | fulfillment_type | | int Fulfillment type. Only orders with fulfillment type = 0 can be shipped by merchants. • FULFILLMENT_BY_MERCHANT = 0; • FULFILLMENT_BY_PLATFORM = 1; | | Orders > Marketplace Fulfillment Channel | (Based on Account settings) We will receive Fulfillment_By_Merchant = 0; Fulfillment_By_Platform = 1;

And we should create a mapping from integers to the text given in integration notes and save the text instead of numbers. We need to display following: Fulfillment by merchant; Fulfillment by platform;

Bank Transfer; Cash; Dana Wallet, Bank Card, OVO, Cash on Delivery, Go Pay, PayPal, ApplePay, ShopeePay, Klarna, Klarna Pay Now, Klarna Pay Overt Time, True Money, Rabbit Line Pay,Ibanking, Touch Go, Boost, Zalo Pay, Momo, Blik; ( without _ and the first letters to be uppercase)

Once we download an order, we should always create a payment record (we should always threat an order as paid, unless the status of order is ”Unpaid” ). As per abstraction: Order management general requirements

Additional Information:

Workflow steps

Outstanding specifics

We take care of bundles internally and use our standard logic for de-bundling.

Is this article helpful?

0 0 0