TikTok - Claims Handle

Summary of changes:

<v1.1>

The seller initiated refunds/cancellations/returns will be handled via the claims functionality in Hemi. The purpose of the page is to give a good understanding on how that will work.

Context

Cancel/Return/Refund, also referred to as 'post-transaction' or 'after-sales' can be initiated by a buyer or directly processed by a seller. TikTok Shop provides two APIs for sellers process these after-sales situations. The cancel API allows sellers to process a buyer order cancellation request as well as a direct seller order cancellation. The return API allows sellers to process a buyer order refund/ return & refund request.

General TikTok Cancel/Return/Refund API Overview ****https://partner.tiktokshop.com/docv2/page/650b2001bace3e02b76db38a

Picture 1: Pre-shipment

• Buyer initiates a cancellation request

Picture2: Post-shipment

• Buyer initiates a refund request

Picture 3: Post-shipment ( the flow is similar to the flow “pre-shipment“)

• Buyer initiates a return request

We will use “Search Cancellations“ and “Search Returns” API calls to get order_ids for which buyer has requested cancellation/refund. The order_ids should be stored in Order Claim with related status (Will be mapped into the mapping table below).

Per account we can set by default to Accept or Reject refund; In Account TikTok table we need to add additional options which will be Cancel Action Default, Return Action Default and Refund Only Action Default which will work as a default action if we would like to automatically accept or reject all claims for the specific account. If is “Accept“ , by default we accept the refund, if is “Reject“ , by default we reject the refund.

The different default action should work for claims with the following details

Claim type = Cancel + Marketplace type = ‘CANCEL’ OR ‘BUYER_CANCEL’ - Cancel Action Default

Claim type = Return + Marketplace type = ‘REFUND’ - Refund Only Action Default

Claim type = Return + Marketplace type = ‘RETURN_AND_REFUND’ - Return Action Default

We are able to reject or to confirm refund using separate API calls. Canceling or rejecting an order are irreversible actions. You cannot start again the order process for canceled and rejected orders. The refund request is per item line id and we can include each separate item as additional “refund“ node.

Search Cancellations

Retrieve one or more order cancellations.

API Call: POST /return_refund/202309/cancellations/search

API Docs: https://partner.tiktokshop.com/docv2/page/650ab68bc16ffe02b8f2ea41?external_id=650ab68bc16ffe02b8f2ea41#Back To Top

All validations,triggers etc are as per the Claims abstraction found here : Claims general management

We need to pass the shop_cipher as query property which was obtained with the Get Authorised Shops call found here TikTok - Authentication & Database structure

We want to incorporate this call with the last_date_run so we can be able to get only the new initiated requests.

Any records created with this call need to be with Order Claim > Type = Cancel

Example Call Body:

{
  "buyer_user_ids": "7494845267308415300",
  "cancel_ids": "577087614418520388",
  "cancel_status": "CANCELLATION_REQUEST_PENDING",
  "cancel_types": "CANCEL",
  "create_time_ge": 1690340825,
  "create_time_lt": 1690340825,
  "locale": "en-US",
  "order_ids": "577087614418520388",
  "update_time_ge": 1690340825,
  "update_time_lt": 1690340825
}

Mapping(N/A means we exclude it from the payload):

Example Response:

{
  "code": 0,
  "data": {
    "cancellations": [
      {
        "cancel_id": "4035318504086604100",
        "cancel_line_items": [
          {
            "cancel_line_item_id": "4035227913481196964",
            "order_line_item_id": "576468844534141348",
            "product_image": {
              "height": 200,
              "url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/004797ebfd8c4d3da2df1cc4bfdb0614~tplv-o3syd03w52-origin-jpeg.jpeg?from=4246405447",
              "width": 200
            },
            "product_name": "bundle No Heel Flat Heel Summer Winter Round Toe",
            "refund_amount": {
              "currency": "USD",
              "refund_shipping_fee": "5",
              "refund_subtotal": "1",
              "refund_tax": "3",
              "refund_total": "1.23",
              "retail_delivery_fee": "0.1"
            },
            "seller_sku": "YYAPC23078TRT30",
            "sku_id": "2729382476852921560",
            "sku_name": "1#, Standard"
          }
        ],
        "cancel_reason": "ecom_order_to_ship_canceled_reason_created_by_mistakes",
        "cancel_reason_text": "Order created by mistake",
        "cancel_status": "CANCELLATION_REQUEST_PENDING",
        "cancel_type": "REQUEST_CANCEL_REFUND",
        "create_time": 1690451136,
        "order_id": "577087614418520388",
        "refund_amount": {
          "currency": "USD",
          "refund_shipping_fee": "0.2",
          "refund_subtotal": "1",
          "refund_tax": "0.03",
          "refund_total": "1.23",
          "retail_delivery_fee": "0.1"
        },
        "role": "BUYER",
        "seller_next_action_response": [
          {
            "action": "SELLER_RESPOND_CANCEL",
            "deadline": 1690554680
          }
        ],
        "update_time": 1690451136
      }
    ],
    "next_page_token": "aDU2dHIzMlFhME5CUzJKUDhDdVJhTDM1WmJkeFVTVW9LTkRaSnNaZCtuWjJXVU5CSDhlaA==",
    "total_count": 100
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}

Mapping: New

• CANCELLATION_REQUEST_PENDING
• CANCELLATION_REQUEST_SUCCESS
• CANCELLATION_REQUEST_CANCELLED
• CANCELLATION_REQUEST_COMPLETE | Order Claim > Marketplace Status AND Order Claim > Status | We need to do mapping based on TikTok’s statuses : CANCELLATION_REQUEST_PENDING we set Order Claim > Status = Pending CANCELLATION_REQUEST_SUCCESS we set Order Claim > Status = Completed CANCELLATION_REQUEST_CANCELLED we set Order Claim > Status = Completed CANCELLATION_REQUEST_COMPLETE we set Order Claim > Status = Completed | | | | cancel_type | | | | Order Claim > Marketplace Type | | | | | create_time | | | | Order Claim > Marketplace Date | | | | | order_id | | | The identification of a TikTok order | N/A | This will be the value, which we have already saved in Orders > Marketplace Order ID. We need to use this one to find the order for which this claim is. | | | | refund_amount | | | | | | | | | | currency | | | N/A | | | | | | refund_shipping_fee | | | N/A | | | | | | | | | N/A | | | | | | refund_subtotal | | | N/A | | | | | | refund_tax | | | N/A | | | | | | refund_total | | | | | | | | | retail_delivery_fee | | | N/A | | | | | role | | | Order cancellation initiated by
• BUYER
• SELLER
• SYSTEM | Order Claim > Initiated By | | | | | seller_next_action_response | | | | N/A | | | | | | action | | | N/A | | | | | | deadline | | | N/A | | | | | update_time | | | | N/A | | | | next_page_token | | | | | N/A | | | | total_count | | | | | N/A | | | message | | | | | | N/A | | | request_id | | | | | | N/A | |

The successful response will be with code : 0 and message : Success . If we receive a different code than 0, this means there was an error and we want to be able to see the error in the notification center (Until this is done, we want to see the error when the cron is run with DEVMODDETRUE for now).The errors need to be mapped as per below response codes and we will receive the code but want to store the message:

After the claim has been received we can either approve or reject it. There are two separate calls for this.

Approve Cancellation

Claim type = Cancel

API Call : POST /return_refund/202309/cancellations/{cancel_id}/approve API Docs : https://partner.tiktokshop.com/docv2/page/650ab6eff1fd3102b92e6a92?external_id=650ab6eff1fd3102b92e6a92#Back To Top

We need to pass the shop_cipher as query property which was obtained with the Get Authorised Shops call found here TikTok - Authentication & Database structure

The cancel_id needs to be taken from the Order Claim > Marketplace ID as it would have been stored when the claim was created.

The validations are as per the claims abstraction. Claims general management

Example call :

https://open-api.tiktokglobalshop.com/return_refund/202309/cancellations/98001001/approve?app_key=123abc&sign=5361235029d141222525e303d742f9e38aea052d10896d3197ab9d6233730b8c&timestamp=1625484268&shop_cipher=ROW_RHkDDABBAAB8tKAVoAqsMTjsQZFLyNfY&idempotency_key=40b456b1-78e7-412d-9fe6-82181496e1bd

Response :

{
  "code": 0,
  "data": {},
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}

The successful response will be with code : 0 and message : Success . If we receive a different code than 0, this means there was an error and we need to store the error in Order Errors with Type = Claim Accept.The errors need to be mapped as per below response codes and we will receive the code but want to store the message:

Reject Cancellation

Claim type = Cancel

API Call : POST /return_refund/202309/cancellations/{cancel_id}/reject API Docs : https://partner.tiktokshop.com/docv2/page/650ab6df0fcef602bf34528f?external_id=650ab6df0fcef602bf34528f

We need to pass the shop_cipher as query property which was obtained with the Get Authorised Shops call found here TikTok - Authentication & Database structure

The cancel_id needs to be taken from the Order Claim > Marketplace ID as it would have been stored when the claim was created.

The validations are as per the claims abstraction.Claims general management

Example call body :

{
  "comment": "I have packed the products before cancellation request",
  "images": [
    {
      "height": 200,
      "image_id": "tos-maliva-i-o3syd03w52-us/57a1c8908fe74572861ea5e50887d8d1",
      "mime_type": "image/png",
      "width": 200
    }
  ],
  "reject_reason": "seller_reject_apply_product_has_been_packed"
}

Mapping(please note N/A means we exlcude it from the payload) :

Example Response :

{
  "code": 0,
  "data": {},
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}

The successful response will be with code : 0 and message : Success . If we receive a different code than 0, this means there was an error and we need to store the error in Order Errors with Type = Claim Reject.The errors need to be mapped as per below response codes and we will receive the code but want to store the message:

Search Returns

Retrieve one or more returns

API Call: POST /return_refund/202309/returns/search

API Docs: https://partner.tiktokshop.com/docv2/page/650ab69edefece02be70785b

All validations, triggers etc are as per the Claims abstraction found here : Claims general management

We need to pass the shop_cipher as query property which was obtained with the Get Authorised Shops call found here TikTok - Authentication & Database structure

We want to incorporate this call with the last_date_run so we can be able to get only the new initiated requests.

Records created with this call need to be with Order Claim > Type = Return OR Order Claim > Type = Exchange. We will store it as Exchange only if we have return_type = REPLACEMENT. Please note that we don’t have to save refunds for exchange claims.

Example call body:

{
  "arbitration_status": "IN_PROGRESS",
  "buyer_user_ids": "7493996903972308733",
  "create_time_ge": 1690340825,
  "create_time_lt": 1690340825,
  "locale": "en-US",
  "order_ids": "577686530908261117",
  "return_ids": "4035318504086604100",
  "return_status": "RETURN_OR_REFUND_REQUEST_PENDING",
  "return_types": "REFUND",
  "update_time_ge": 1690340825,
  "update_time_lt": 1690340825
}

Mapping(N/A means we exclude it from the payload) :

Example response :

{
  "code": 0,
  "data": {
    "next_page_token": "aDU2dHIzMlFhME5CUzJKUDhDdVJhTDM1WmJkeFVTVW9LTkRaSnNaZCtuWjJXVU5CSDhlaA==",
    "return_orders": [
      {
        "arbitration_status": "IN_PROGRESS",
        "can_buyer_keep_item": true,
        "create_time": 1690451136,
        "discount_amount": [
          {
            "currency": "USD",
            "product_platform_discount": "0.1",
            "product_seller_discount": "0.1",
            "shipping_fee_platform_discount": "0.1",
            "shipping_fee_seller_discount": "0.1"
          }
        ],
        "handover_method": "DROP_OFF",
        "next_return_id": "4035310341095393463",
        "order_id": "577686530908261117",
        "pre_return_id": "4035310341095393452",
        "refund_amount": {
          "buyer_service_fee": "0.1",
          "currency": "USD",
          "refund_shipping_fee": "0.2",
          "refund_subtotal": "1",
          "refund_tax": "0.03",
          "refund_total": "1.23",
          "retail_delivery_fee": "0.1"
        },
        "return_id": "4035318504086604100",
        "return_line_items": [
          {
            "order_line_item_id": "576473917261451851",
            "product_image": {
              "height": 200,
              "url": "https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/004797ebfd8c4d3da2df1cc4bfdb0614~tplv-o3syd03w52-origin-jpeg.jpeg?from=4246405447",
              "width": 200
            },
            "product_name": "(SP) [PROMO BUNDLING] NICE Tissue Facial 180s x 5 pcs",
            "refund_amount": {
              "buyer_service_fee": "0.1",
              "currency": "USD",
              "refund_shipping_fee": "0.2",
              "refund_subtotal": "1",
              "refund_tax": "0.03",
              "refund_total": "1.23",
              "retail_delivery_fee": "0.1"
            },
            "return_line_item_id": "4035227657962164811",
            "seller_sku": "PUTIH 1 TALI",
            "sku_id": "2729382476852921560",
            "sku_name": "1#, Standard"
          }
        ],
        "return_provider_id": "TH27014E9R5Q4G",
        "return_provider_name": "J&T Express",
        "return_reason": "ecom_order_to_ship_canceled_reason_created_by_mistakes",
        "return_reason_text": "Order created by mistake",
        "return_status": "RETURN_OR_REFUND_REQUEST_PENDING",
        "return_tracking_number": "213456789098765433456",
        "return_type": "REFUND",
        "role": "BUYER",
        "seller_next_action_response": [
          {
            "action": "SELLER_RESPOND_REFUND",
            "deadline": 1690554680
          }
        ],
        "shipment_type": "PLATFORM",
        "shipping_fee_amount": [
          {
            "buyer_paid_return_shipping_fee": "0.1",
            "currency": "USD",
            "platform_paid_return_shipping_fee": "0.1",
            "seller_paid_return_shipping_fee": "0.1"
          }
        ],
        "update_time": 1690453136
      }
    ],
    "total_count": 100
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}

Example mapping :

• REFUND: Seller will issue a returnless refund. The buyer is not required to send the items back to the seller.
• RETURN_AND_REFUND: Buyer is required to send the items back to the seller. The seller will need to review the condition of the returned items before a refund can be issued to the buyer.
• REPLACEMENT: The buyer requires the seller to replace the item(s) | Order Claim > Marketplace Type | | | | | role | | | | Order Claim > Initiated By | | | | | seller_next_action_response | | | | | | | | | | action | | | N/A | | | | | | deadline | | | N/A | | | | | shipment_type | | | | N/A | | | | | shipping_fee_amount | | | | | | | | | | buyer_paid_return_shipping_fee | | | N/A | | | | | | currency | | | N/A | | | | | | platform_paid_return_shipping_fee | | | N/A | | | | | | seller_paid_return_shipping_fee | | | N/A | | | | | update_time | | | | N/A | | | | total_count | | | | | N/A | | | message | | | | | | N/A | | | request_id | | | | | | N/A | |

The successful response will be with code : 0 and message : Success . If we receive a different code than 0, this means there was an error and we need to store the error in Order Errors with Type = Claim Download.The errors need to be mapped as per below response codes and we will receive the code but want to store the message:

After the claim has been received we can either approve or reject it. There are two separate calls for this :

Approve Return

Claim type = Return

API Call : POST /return_refund/202309/returns/{return_id}/approve API Docs : https://partner.tiktokshop.com/docv2/page/650ab6eff1fd3102b92e6a92?external_id=650ab6eff1fd3102b92e6a92#Back To Top

We need to pass the shop_cipher as query property which was obtained with the Get Authorised Shops call found here TikTok - Authentication & Database structure

The return_id needs to be taken from the Order Claim > Marketplace ID as it would have been stored when the claim was created.

The validations are as per the claims abstraction. Claims general management

Example Call Body :

{
  "buyer_keep_item": true,
  "decision": "APPROVE_REFUND"
}

Mapping (please note N/A means we exclude it from the payload):

If we have Marketplace Type = REFUND we then send “APPROVE_REFUND” If we have Marketplace Type = RETURN_AND_REFUND we then send “APPROVE_RETURN” If we have Marketplace Type = REPLACEMENT we send “APPROVE_REPLACEMENT” |

Example Response:

{
  "code": 0,
  "data": {},
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}

The successful response will be with code : 0 and message : Success . If we receive a different code than 0, this means there was an error and we need to store the error in Order Errors with Type = Claim Accept. The errors need to be mapped as per below response codes and we will receive the code but want to store the message:

After receiving the package we need to approve(push) the refund to the customer. In order to do this, we need to obviously push a refund and this is done by making the same call as above, however the only difference is the deicsion . When sending the actual refund we need to send a decision = “APPROVE_RECEIVED_PACKAGE”. This will be done through the refund panel. Once we have created a refund associated with the claim we need to make sure we are not sending a standard refund, but rather the same API call as above with different decision

Reject Return

Claim type = Return

API Call : POST /return_refund/202309/returns/{return_id}/reject API Docs : https://partner.tiktokshop.com/docv2/page/650ab6d14a0bb702c06faec4?external_id=650ab6d14a0bb702c06faec4#Back To Top

We need to pass the shop_cipher as query property which was obtained with the Get Authorised Shops call found here TikTok - Authentication & Database structure

The return_id needs to be taken from the Order Claim > Marketplace ID as it would have been stored when the claim was created.

The validations are as per the claims abstraction. Claims general management

Example call body :

{
  "comment": "I have reached an agreement with the buyer",
  "decision": "REJECT_RECEIVED_PACKAGE",
  "images": [
    {
      "height": 200,
      "image_id": "tos-maliva-i-o3syd03w52-us/57a1c8908fe74572861ea5e50887d8d1",
      "mime_type": "image/png",
      "width": 200
    }
  ],
  "reject_reason": "seller_reject_apply_package_has_not_exceeded_estimated_delivery_time"
}

Mapping (N/A means we exclude it from the payload):

If we have Marketplace Type = REFUND AND Marketplace Status = RETURN_OR_REFUND_REQUEST_PENDING we then send “REJECT_REFUND”

If we have Marketplace Type = RETURN_AND_REFUND AND Marketplace Status = RETURN_OR_REFUND_REQUEST_PENDING we then send “REJECT_RETURN” If we have Marketplace Type = REPLACEMENT AND Marketplace Status = REPLACEMENT_REQUEST_PENDING we send “REJECT_REPLACEMENT”

If we have Marketplace Type = REFUND AND Marketplace Status = BUYER_SHIPPED_ITEM we then send “REJECT_RECEIVE_PACKAGE”

If we have Marketplace Type = RETURN_AND_REFUND AND Marketplace Status = BUYER_SHIPPED_ITEM we then send “REJECT_RECEIVE_PACKAGE” | | images | | | N/A | | | | height | | N/A | | | | image_id | | N/A | | | | mime_type | | N/A | | | | width | | N/A | | | reject_reason | | | | <v1.2>Hardcoded as “reverse_reject_request_reason_4_uk” for now.</v1.2> |

Example Response :

{
  "code": 0,
  "data": {},
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}

The successful response will be with code : 0 and message : Success . If we receive a different code than 0, this means there was an error and we need to store the error in Order Errors with Type = Claim Reject.The errors need to be mapped as per below response codes and we will receive the code but want to store the message:

</v1.1>