TikTok - Ship Orders - OLD

Summary of changes:

• Described the case when we try to ship with a courier which is deleted on TikTok; • For ship package section : The validation from revision 1.1 added. The current validation was removed as per discussion • Added correct mapping in Ship Package table mapping; | | 05/07/2022 | 1.5 | Added more details for Ship package and Get Shipping providers; Some paragraphs were rearranged; | | 07/07/2022 | 1.6 | In Ship Package descriptive part “integer“ changed to “string“ , based on a comment and tests | | 13/07/2022 | 1.7 | Some paragraphs were rearranged | | 20/07/2022 | 1.8 | Some more explanations added for couriers; Old explanation was deleted; | | 05/08/2022 | 1.9 | updated and corrcted the logic for shipping provider | | 18/08/2022 | 2.0 | Removed the logic with shipping provider=1 from the beginning of the scope |

The purpose of this page is to give good understanding of the TikTok’s shippment logic.

To ship order on TikTok, first we should get & store all the available couriers for TikTok because is mandatory when shipping an order to push shipping_provider_id. We are not able to ship with provider which is not part of the TikTok shipping provider list!

TikTok ship orders, using package_ids. Each order has assigned one package_id, which need to be used for shipping.

As we will not integrate to “Split/Combine package“ API at this stage, we are able to ship the complete order (not support partial shipment!).

To ship the order we should have payment record for the order, order status to be on “Ready For Shipping“ & Shipment = Pending (waiting for information to be sent to the MP)

The shipment process is straight forward - we need to push the package_id, which we have received in “Get Order Details“ response, the shipping provider identifier (we get & store all available shipping providers, using “Get Shipping Provider“ API call) & tracking number.

• Get Shipping Provider

Use this API to get the shop's shipping providers' info for merchant self-shipping mode. Developer should select the available provider from this API for self-shipping!

Using this call, we will need to store the shipping carriers provided from TikTok - will be stored into Carriers table. We would want to map the shipping provider name but to send the shipping provider id to TikTok MPs.

As per follow up tests, we noticed TikTok couriers are less than initially provided. In order to cover the case, where TikTok will delete some of the couriers and if we have such case we are going to delete them from TikTok Couriers table. Note: Please see section “Ship Package“ for more information regarding how we will handle such case when we send shipping request!

****As per discussions with TT: If we would want to ship with carrier which is not part of the below list, will not see any logistics track about this order on the platform.

API Call: GET /api/logistics/shipping_providers

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

Example Request:

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

Example Response:

{
    "code": 0,
    "message": "Success",
    "request_id": "202205200946320102171342071B323AB7",
    "data": {
        "delivery_option_list": [
            {
                "delivery_option_id": "7031156220157232897",
                "delivery_option_name": "TT-Virtual-Hermes-GB-DS-sta",
                "item_dimension_limit": {
                    "height": 120,
                    "length": 120,
                    "width": 120
                },
                "item_weight_limit": {
                    "max_weight": 15000,
                    "min_weight": 0
                },
                "shipping_provider_list": [
                    {
                        "shipping_provider_id": "7021769596919088897",
                        "shipping_provider_name": "TT Virtual Hermes"
                    }
                ]
            },
            {
                "delivery_option_id": "7091146663229654785",
                "delivery_option_name": "TT-Virtual-SendBySeller-GB",
                "item_dimension_limit": {
                    "height": 0,
                    "length": 0,
                    "width": 0
                },
                "item_weight_limit": {
                    "max_weight": 0,
                    "min_weight": 0
                },
                "shipping_provider_list": [
                    {
                        "shipping_provider_id": "6582060798096031745",
                        "shipping_provider_name": "XDP Express"
                    },
                    {
                        "shipping_provider_id": "6599541761693270018",
                        "shipping_provider_name": "Hermes"
                    },
                    {
                        "shipping_provider_id": "6612827278487322626",
                        "shipping_provider_name": "EURODIS"
                    },
                    {
                        "shipping_provider_id": "6618402578756190210",
                        "shipping_provider_name": "FedEx UK"
                    },
                    {
                        "shipping_provider_id": "6639580521074524161",
                        "shipping_provider_name": "DHL UK"
                    },
                    {
                        "shipping_provider_id": "6641219975896514562",
                        "shipping_provider_name": "Yodel UK"
                    },
                    {
                        "shipping_provider_id": "6642328629463629826",
                        "shipping_provider_name": "Asendia UK"
                    },
                    {
                        "shipping_provider_id": "6649195729745887233",
                        "shipping_provider_name": "UK Mail"
                    },
                    {
                        "shipping_provider_id": "6651100160943357954",
                        "shipping_provider_name": "wnDirect"
                    },
                    {
                        "shipping_provider_id": "6652948552425406465",
                        "shipping_provider_name": "TrakPak"
                    },
                    {
                        "shipping_provider_id": "6654133961797746689",
                        "shipping_provider_name": "Parcel2Go"
                    },
                    {
                        "shipping_provider_id": "6655697308367273986",
                        "shipping_provider_name": "Tuffnells Pareces Expression"
                    },
                    {
                        "shipping_provider_id": "6655992354618769409",
                        "shipping_provider_name": "Cayman Islands Post"
                    },
                    {
                        "shipping_provider_id": "6656990260007813122",
                        "shipping_provider_name": "Guernsey Post"
                    },
                    {
                        "shipping_provider_id": "6657598289359323137",
                        "shipping_provider_name": "DPD UK"
                    },
                    {
                        "shipping_provider_id": "6658174162568658945",
                        "shipping_provider_name": "DX Delivery"
                    },
                    {
                        "shipping_provider_id": "6659096093869342722",
                        "shipping_provider_name": "TNT UK"
                    },
                    {
                        "shipping_provider_id": "6660329273143148545",
                        "shipping_provider_name": "RPD2man Deliveries"
                    },
                    {
                        "shipping_provider_id": "6667705672463351809",
                        "shipping_provider_name": "UPS UK"
                    },
                    {
                        "shipping_provider_id": "6671794738251726849",
                        "shipping_provider_name": "Royal Mail"
                    },
                    {
                        "shipping_provider_id": "6677632889187745793",
                        "shipping_provider_name": "Deltec Courier"
                    },
                    {
                        "shipping_provider_id": "6699476450581430274",
                        "shipping_provider_name": "Parcel Force"
                    },
                    {
                        "shipping_provider_id": "6723065376080412674",
                        "shipping_provider_name": "Arrow XL"
                    },
                    {
                        "shipping_provider_id": "6729403182511865858",
                        "shipping_provider_name": "Whistl"
                    },
                    {
                        "shipping_provider_id": "6760565269699084290",
                        "shipping_provider_name": "APC Overnight"
                    },
                    {
                        "shipping_provider_id": "6760607283098583042",
                        "shipping_provider_name": "Ascension Island Post"
                    },
                    {
                        "shipping_provider_id": "6760727669580627970",
                        "shipping_provider_name": "Panther UK"
                    },
                    {
                        "shipping_provider_id": "7028580010915006210",
                        "shipping_provider_name": "S.F Internatinal"
                    },
                    {
                        "shipping_provider_id": "7043804799275370241",
                        "shipping_provider_name": "DHL Parcel"
                    },
                    {
                        "shipping_provider_id": "7046331419286570753",
                        "shipping_provider_name": "GLS /CJ GLS"
                    },
                    {
                        "shipping_provider_id": "7046331959399679746",
                        "shipping_provider_name": "Amazon Logistics"
                    },
                    {
                        "shipping_provider_id": "7049196166784747269",
                        "shipping_provider_name": "Asendia US"
                    },
                    {
                        "shipping_provider_id": "7054506440005781254",
                        "shipping_provider_name": "An Post"
                    },
                    {
                        "shipping_provider_id": "7065143932472002310",
                        "shipping_provider_name": "4PX Express"
                    }
                ]
            }
        ]
    }
}

• Ship Package

To ship an order (package) we should have Shipment = Pending

In order to ship the package, we should push the package_id (which is received into Get Order Details response and stored in Order TikTok > Package ID) and the shipping provider ID we are going to ship with. The shipping provided id will be taken from the TikTok Couriers table; ;

At this stage, we will not integrate to “Split/Combine Packages“ API, and we need to make sure we are not able to ship partially on TikTok and we should ship the complete order (with all products in the order)

When we send shipping request and If chosen courier is deleted from TikTok list, and we try to ship with this courier, we will have an error in Order Shipment (Error message: The courier you want to ship with is not part of TikTok couriers anymore.) and we will not send shipping request for this order

If there are no preselected carriers into the table TikTok couriers, the error message will appear (Shipment Error, which error will describe there are no carriers selected)

Detailed explanation with example:

We get the courier name from Order Shipment > Courier OR Order > Shipping Carrier (this is the priority). And once we get the courier name, we have two paths to get the TT shipping provider ID.

First check: First we need to check in (Hemi) Couriers table (1513) for a match against the Courier > Name field. If we have a match, we check if there is a value in the mapping table (TikTok Couriers Mapping) in order to reach to the right TikTok Courier > Shipping Provider ID. If there is no match or no value in the mapping table, we go to the second check.

Second check: Here we will check directly in TikTok Couriers (20501) table for the chosen courier. The check here is done against the Shipping Provider Name column.

If there is no match on check 1 and check 2, we send shipping provider ID which is not part of TikTok list, there should be an error message, which need to indicate we should choose a courier from TikTok list (example error: You cannot ship with a courier which is not from TikTok list)

Validations to be done:

1. If table TikTok Couriers is empty - we save error for all shipments that TT couriers are not downloaded.

Note: If table TikTok Couriers Mapping is empty, we will just go to the second check every time.

API Call: POST /api/fulfillment/rts

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

Example Call:

{
  "package_id": "123456",
  "pick_up": {
    "pick_up_end_time": "Unix timestamp",
    "pick_up_start_time": "Unix timestamp"
  },
  "pick_up_type": "",
  "self_shipment": {
    "shipping_provider_id": "6965352555291346690",
    "tracking_number": "576460868968549926"
  }
}

In order to ship the package, we should push the package_id, which will be stored into Order TikTok > Package ID;

As we are not integrating to “Split/Combine Package“ APIs, we need to ship the complete order(not supporting partial shipment). If we try to ship partially, we will have Order Shipment on Error and there should be an error message(Partially Shipment is not supported) returned and stored into “ Order Error“ table.

Note: We are not able to ship order with status “Partially Shipped”.

We will use the validations, described in abstraction here: https://wearepentagon.atlassian.net/wiki/spaces/HEMI/pages/2075820405/Order+management+general+requirements#Ship

Mapping:

We would want to map the shipping provider name but to send the shipping provider id to TikTok MPs. Also, we would want to map the courier name from the seller to internal couriers against which we have preselected a value from TikTok Carriers. | | | tracking_number | For package with SEND_BY_SELLER as delivery_option(merchant self-shipping mode), developer needs to input tracking_number to call this API. | Y | Order Shipment > Tracking Number | |

Example response:

{
  "code": 0,
  "data": {
    "fail_packages": [
      {
        "fail_code": "",
        "fail_reason": "",
        "package_id": ""
      }
    ]
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}

Into the response, TT will return the failed package_id and the reason of the failure. In such case, we need to store the respectively error and will set Shipment = Error for the failed package ids.

Example Test call with different shipping provider id:

{
  "package_id": "1152952913230793112",
  "self_shipment": {
    "shipping_provider_id": "1",
    "tracking_number": "101010"
  }
}

Response of the test call:

   "code": 0,
    "message": "Success",
    "request_id": "2022052011201901021713420714367F5C",
    "data": null

Additional Information:

• Workflow steps