Add External Order References

POST

/order/202406/orders/external_orders

If you use an external order management system (OMS), its order and line item IDs may differ from the corresponding TikTok Shop IDs. Use this endpoint to attach external OMS references to up to 100 TikTok Shop orders. To update an existing reference, call the endpoint again with the same TikTok Shop order and OMS. Each order is processed independently. On a successful API response, references for orders not listed in data.errors are saved; use that list to identify per-order errors.

Authorizations

• accessToken

Parameters

Query Parameters

shop_cipher

required

string

Identifies the shop. Obtain it from the Get Authorized Shops API.

Request Body^required

Media typeapplication/json

object

orders

required

Orders for which to add or update external OMS references. Min count: 1. Max count: 100.

Array<object>

<= 100 items

object

id

required

The unique identifier for a TikTok Shop order.

string

external_order

required

Order information in your external order management system (OMS).

object

id

required

The corresponding order ID in your OMS.

string

platform

required

The alias of your OMS. Possible values:

• SHOPIFY
• WOOCOMMERCE
• BIGCOMMERCE
• MAGENTO
• SALESFORCE_COMMERCE_CLOUD
• CHANNEL_ADVISOR
• AMAZON
• ORDER_MANAGEMENT_SYSTEM
• WAREHOUSE_MANAGEMENT_SYSTEM
• ERP_SYSTEM

Notes:

• To attach information from multiple OMSs to the same order in TikTok Shop, call this API multiple times, each with the same TikTok Shop order and a different OMS.
• To edit the attached information for a TikTok Shop order, call the API with the same OMS.

string

Allowed values: SHOPIFY WOOCOMMERCE BIGCOMMERCE MAGENTO SALESFORCE_COMMERCE_CLOUD CHANNEL_ADVISOR AMAZON ORDER_MANAGEMENT_SYSTEM WAREHOUSE_MANAGEMENT_SYSTEM ERP_SYSTEM

line_items

required

Max count: 100.

Array<object>

<= 100 items

object

id

required

Line item ID in your OMS.

string

origin_id

required

Line item ID in TikTok Shop.

string

Example

{
  "orders": [
    {
      "id": "576461413038785752",
      "external_order": {
        "id": "676461413038785752",
        "platform": "SHOPIFY",
        "line_items": [
          {
            "id": "577086512123755123",
            "origin_id": "677086512123755123"
          }
        ]
      }
    }
  ]
}

Responses

200

Success

Media typeapplication/json

object

code

Status code; 0 means success.

integer format: int64

message

Success or failure message.

string

request_id

Request log ID.

string

data

object

errors

Per-order errors. Each item identifies a TikTok Shop order and its external OMS reference that could not be processed. On a successful API response, references for orders not listed here are saved even when this list is non-empty.

Array<object>

object

code

The machine-readable code for this per-order error.

string

message

A human-readable message describing this per-order error.

string

detail

The TikTok Shop order and external OMS reference associated with this per-order error.

object

order_id

The unique identifier for a TikTok Shop order.

string

external_order

The order information in your OMS.

object

id

The corresponding order ID in your OMS.

string

platform

The alias of your OMS.

string

Example

{
  "code": 0,
  "data": {
    "errors": [
      {
        "code": "36020001",
        "message": "Invalid order_id",
        "detail": {
          "order_id": "576461413038785752",
          "external_order": {
            "id": "676461413038785752",
            "platform": "SHOPIFY"
          }
        }
      }
    ]
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}