TikTok - Cancel Order

Summary of changes:

The purpose of this page is to give good understanding of the flow, where seller can cancel the order before the order is shipped.

<v1.1>

Cancel Order

API Call: POST /return_refund/202309/cancellations

API Docs: https://partner.tiktokshop.com/docv2/page/650aecb64a0bb702c076b03d#Back To Top

All triggers, validations etc are as per the abstraction Refunds send general logic

<v1.3> We need to be picking orders on Orders > Status = Ready for Shipping or Partially Shipped (only for the products that are not shipped). </v1.3>

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

Example request:

{
  "cancel_reason": "ecom_order_delivered_refund_and_return_reason_wrong_product_seller",
  "order_id": "577087614418520388",
  "order_line_item_ids": [
    "577087614418716996"
  ],
  "skus": [
    {
      "quantity": 1,
      "sku_id": "1729386416015578024"
    }
  ]
}

Mapping:

We want to skip this if we are doing a full refund and not include the property in the payload in such case as we will use the sku_id | | skus | | | No | | We have to exclude this object if we are sending partial product refund. | | | quantity | | Yes | | We need to calculate this since we do not do refunds based on quantity in Hemi. This would be the count of Order Refund Row Line records | | | sku_id | | Yes | Product In Order > Item Order Line ID | |

Response example:

{
  "code": 0,
  "data": {
    "cancel_id": "4035319218955782461",
    "cancel_status": "CANCELLATION_REQUEST_SUCCESS"
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}

Mapping:

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 it in Order Errors table with Type = Refund Send . The errors need to be mapped as per below response codes and we will receive the code but want to store the message :

TikTok Refund Reasons

These reasons should be added in the Order Refund Reasons table for distinct marketplace TikTok. The reasons should be available in the dropdown menu from the refund panel. The refund reasons should be in a format [REFUND] - reason and cancellations should be [CANCELLATION] - reason. We want to store the reason id in the backend but display the reason name in the refund panel.

TikTok seem to have slightly different reasons for the different regions.The difference is that we need to add “_uk” at the end of most of the reason IDs that is for the UK region but there are some minor differencies in the reasons themselves. So we need to create a validation that will check the TikTok account region (I suggest we do this validation based on Account > Country) and then use the correct reason based on the region.

Return Order

This is a post shipment refund that is initiated from the seller on the behalf of the buyer. Do not confuse it with buyer initiated return.

API Call: POST /return_refund/202309/returns

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

We need to be picking orders on Orders > Status = Shipped or Partially Shipped.

All other triggers, validations etc are as per the abstraction Refunds send general logic

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

Example request:

{
  "currency": "USD",
  "handover_method": "DROP_OFF",
  "order_id": "576473917261320779",
  "order_line_item_ids": [
    "455764739172614518516"
  ],
  "refund_total": "10.5",
  "return_reason": "ecom_order_delivered_refund_reason_missing_product_seller",
  "return_type": "REFUND",
  "shipment_type": "PLATFORM",
  "skus": [
    {
      "quantity": 1,
      "sku_id": "1729386416015578024"
    }
  ]
}

Mapping:

We want to skip this if we are doing a full refund and not include the property in the payload in such case as we will use the sku_id | | refund_total | | | No | Order Payment Details > Total Amount | For Order Payment with Type = Refund | | return_reason | | | Yes | Order Payment Details > Reason | As per the reasons table above. | | return_type | | Which type to create:

• REFUND
• RETURN_AND_REFUND | Yes | Order Payment Details > Refund Type | We need to create a mapping. If we have Order Payment Details > Refund Type = Order Full Refund we send REFUND <v1.2>If we have Order Payment Details > Refund Type = Partial Refund we send REFUND If we have Order Payment Details > Refund Type = Items Full Refund we send REFUND</v1.2> If we have Order Payment Details > Refund Type = Return we send RETURN_AND_REFUND | | shipment_type | | | No | N/A | | | skus | | | No | | We have to exclude this object if we are sending partial line refund. | | | quantity | | Yes | | We need to calculate this since we do not do refunds based on quantity in Hemi. I suggest we calculate it based on the Order Refund Row > Amount but its up to devs to decide | | | sku_id | | Yes | Product In Order > Item Order Line ID | |

Example response :

{
  "code": 0,
  "data": {
    "return_id": "4035319218955782461",
    "return_status": "RETURN_OR_REFUND_REQUEST_PENDING"
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}

Response mapping :

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 it in Order Errors table with Type = Refund Send . 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>