Skip to content
TikTok Shop Partner API

Search Seller Affiliate Orders

POST
/affiliate_seller/202410/orders/search

This API allows the partner to retrieve a list of affiliate orders (orders which are affiliate-commission eligible) generated by a seller, returning the order ID and the product ID. Using this, the partner can track their affiliate-conversions on behalf of a seller, using the order ID.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
shop_cipher
required
string

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

page_token
string

An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the next_page_token from a previous response. It is not needed for the first page.

page_size
required
integer format: int64
>= 1 <= 100

The number of results to be returned per page. Default: 20 Valid Range: [1-100]

Request Body

Section titled “Request Body”
Media typeapplication/json
object
create_time_lt

Filter orders created before this time, specified as a Unix timestamp in seconds. Use it with create_time_ge; the interval in a single request must not exceed three months. See create_time_ge for omitted-bound behavior.

integer format: int64
create_time_ge

Filter orders to show only those that are created on or after the specified date and time. Unix timestamp.

Note: create_time_ge and create_time_lt together constitute the creation time filter condition.

  • If create_time_ge is filled but create_time_lt is empty, create_time_lt will default to the current time.
  • If create_time_lt is filled but create_time_ge is empty, create_time_ge will default to the earliest shop time. If both are not specified, data from the last three months will be queried by default.
integer format: int64
program_id

Filter orders by the associated affiliate partner campaign ID.

string
Example
{
  "create_time_lt": 1722485856,
  "create_time_ge": 1719807456,
  "program_id": "73661290629"
}

Responses

Section titled “Responses”

200

Section titled “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
orders

The orders represented by the SKU-order records selected for this page, grouped by order ID. Pagination is applied before grouping, so orders can contain fewer objects than page_size, and SKU entries for the same order can appear on different pages. Aggregate SKU entries with the same order ID across all retrieved pages.

Array<object>
object
id

The order ID.

string
delivery_time

The date and time when the order was delivered. Unix timestamp.

integer format: int64
create_time

The Unix timestamp, in seconds, when the order was created.

integer format: int64
status

Deprecated. This field is not returned. Use each SKU’s settlement_status instead.

string
skus

The list of SKUs that are included in this order.

Array<object>
object
sku_id

The ID of your SKU

string
settlement_status

The current settlement status of the sku order. Possible options are:

  • Unknown: The status of the order is undefined. It might be updated later.
  • AWAITING PAYMENT：The order hasn’t been paid by customer yet, only estimated commission is available
  • To-SETTLE：The order is waiting for settlement, only estimated commission is available
  • SETTLED: The commission of the order is already settled.
  • INELIGIBLE: The order has been returned/refunded/canceled by the buyer, and no commission will be settled.
string
open_collaboration_id

The ID of the open collaboration in which the product is enrolled.

string
target_collaboration_id

The ID of the target collaboration in which the product is enrolled.

string
campaign_id

The ID of the TAP campaign in which the product is enrolled.

string
creator_username

The username of the creator attributed to the SKU order. This field is returned as an empty string for affiliate partner campaign orders.

string
price

The SKU selling price information.

object
amount

The SKU price in major units of the currency specified by currency, represented as a decimal string.

string
currency

The price currency code.

string
quantity

The number of units of the SKU in the order, including units that were later refunded.

integer format: int64
content_type

The content format of the creator content through which the order was created. Possible values:

  • SHOP
  • VIDEO
  • LIVE
  • PRE_LIVE
  • PROMOTION_PAGE
  • LINKSHARE
string
Allowed values: SHOP VIDEO LIVE PRE_LIVE PROMOTION_PAGE LINKSHARE
content_id

The content identifier.

string
product_id

The product ID in TikTok Shop.

string
commission_model

The commission model selected for the SKU order. Possible values:

  • Fixed commission: The fixed commission model is selected.
  • Tiered commission: The tiered commission model is selected; see commission_tier_setting for any available tier settings.
string
commission_tier_setting

For Tiered commission, the creator commission rates configured by the seller, expressed as percentages in ascending threshold order and separated by OR. Returns - when tiered commission does not apply or no tier is configured.

string
commission_rate

The commission rate established by the seller for creators involved in the collaboration, expressed in hundredths of a percent. For example, 1550 represents a commission rate of 15.50%. This value is returned only when the order is generated directly by the seller’s creator. For affiliate partner campaign orders, see partner_commission_rate.

string
partner_commission_rate

The commission rate established by the seller to be paid to affiliate partner involved in the collaboration, expressed in hundredths of a percent. For example, 1550 represents a commission rate of 15.50%.

string
shop_ads_commission_rate

The commission rate for orders generated through Shop Ads, expressed in hundredths of a percent. For example, 5000 represents 50.00%.

string
estimated_commission_base

The estimated total sales value before deducting any refunds, used as a base for calculating commission. Formula: selling price * order quantity

object
amount

The estimated commission base as a localized display string. It may include a currency symbol or code and region-specific decimal and grouping separators; see the sibling currency field for the currency code.

string
currency

The currency code.

string
estimated_paid_shop_ads_commission

The estimated Shop Ads commission that a seller will pay on sales. Formula: estimated commission base * Shop Ads commission rate

object
amount

The commission amount.

string
currency

The commission currency.

string
estimated_paid_commission

The estimated commission that the seller will pay on sales. Formula: estimated commission base * commission rate. This value is returned only when the order is generated directly by the seller’s creator. For affiliate partner campaign orders, see estimated_paid_partner_commission.

object
amount

The commission amount.

string
currency

The commission currency.

string
estimated_paid_partner_commission

The estimated commission that a seller will pay on sales to affiliate partner. Formula: estimated commission base * partner commission rate

object
amount

The commission amount.

string
currency

The commission currency.

string
actual_commission_base

The actual total sales value after deducting any refunds, used as a base for calculating commission. Formula: selling price * (order quantity - return/refund quantity)

object
amount

The actual commission base as a localized display string. It may include a currency symbol or code and region-specific decimal and grouping separators; see the sibling currency field for the currency code. For SETTLED orders, this contains the actual base when available; for REFUNDED orders, it is a localized zero value; for other statuses, it is an empty string.

string
currency

The currency code.

string
actual_paid_commission

The actual commission that the seller will pay on sales. Formula: actual commission base * commission rate. This value is returned only when the order is generated directly by the seller’s creator. For affiliate partner campaign orders, see actual_paid_partner_commission.

object
amount

The commission amount.

string
currency

The commission currency.

string
actual_paid_partner_commission

The actual commission that a seller will pay on sales to affiliate partner. Formula: actual commission base * partner commission rate

object
amount

The commission amount.

string
currency

The commission currency.

string
actual_paid_shop_ads_commission

The actual Shop Ads commission the seller will pay on sales. Formula: actual commission base * Shop Ads commission rate

object
amount

The commission amount.

string
currency

The commission currency.

string
estimated_cofunded_creator_bonus_amount

The portion of the estimated creator bonus that you co-fund in commission boost.

object
amount

The commission amount.

string
currency

The commission currency.

string
actual_cofunded_creator_bonus_amount

The portion of the actual creator bonus that you co-fund in commission boost.

object
amount

The commission amount.

string
currency

The commission currency.

string
refunded_quantity

Deprecated. This field is not returned. Use fully_return to determine whether the SKU order was fully returned or refunded.

integer format: int64
returned_quantity

Deprecated. This field is not returned. Use fully_return to determine whether the SKU order was fully returned or refunded.

integer format: int64
fully_return

Indicates whether the entire SKU order was returned or refunded. Possible values:

  • Yes: The full quantity was returned or refunded, so no commission is paid.
  • No: The full quantity was not returned or refunded.
string
Allowed values: Yes No
is_carousel

Indicates whether the SKU order is attributed to carousel content. Carousel content may involve a commission rate discount. Returns true for a carousel-attributed SKU order and false otherwise.

boolean
next_page_token

An opaque token for retrieving the next page. To keep the effective time filter fixed across pages, provide explicit create_time_ge and create_time_lt values in the first request. If this value is non-empty, pass it as page_token in the next request and reuse those exact time values and the same program_id value or omission. An empty string indicates that there is no next page.

string
total_count

The total number of sku orders that matches the query conditions.

integer format: int64
Example
{
  "code": 0,
  "data": {
    "orders": [
      {
        "id": "579125529499110202",
        "delivery_time": 1723748656,
        "create_time": 1722420186,
        "status": "COMPLETED",
        "skus": [
          {
            "sku_id": "1729791975232997145",
            "settlement_status": "SETTLED",
            "open_collaboration_id": "73661290629",
            "target_collaboration_id": "73661290629",
            "campaign_id": "73661290629",
            "creator_username": "exampleTikTokCreatorUsername",
            "price": {
              "amount": "1000",
              "currency": "VND"
            },
            "quantity": 1,
            "content_type": "LIVE",
            "content_id": "7493990579714164574",
            "product_id": "1729503179457070324",
            "commission_model": "Tiered commission",
            "commission_tier_setting": "3.0 OR 5.0",
            "commission_rate": "1000",
            "partner_commission_rate": "1000",
            "shop_ads_commission_rate": "5000",
            "estimated_commission_base": {
              "amount": "1000",
              "currency": "VND"
            },
            "estimated_paid_shop_ads_commission": {
              "amount": "1000",
              "currency": "VND"
            },
            "estimated_paid_commission": {
              "amount": "20000",
              "currency": "VND"
            },
            "estimated_paid_partner_commission": {
              "amount": "100",
              "currency": "USD"
            },
            "actual_commission_base": {
              "amount": "50000",
              "currency": "VND"
            },
            "actual_paid_commission": {
              "amount": "10000",
              "currency": "VND"
            },
            "actual_paid_partner_commission": {
              "amount": "20000",
              "currency": "VND"
            },
            "actual_paid_shop_ads_commission": {
              "amount": "20000",
              "currency": "VND"
            },
            "estimated_cofunded_creator_bonus_amount": {
              "amount": "100",
              "currency": "USD"
            },
            "actual_cofunded_creator_bonus_amount": {
              "amount": "100",
              "currency": "USD"
            },
            "refunded_quantity": 1,
            "returned_quantity": 1,
            "fully_return": "Yes",
            "is_carousel": false
          }
        ]
      }
    ],
    "next_page_token": "WzE2OTUxMTY2NTQ2OTMsNTc2NDczNDg5ODYxNDEyMDI1XQ==",
    "total_count": 10000
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}
DocsSDKsAPI Reference

Start here

Getting StartedConceptsAuthorizationWebhooksErrors

SDKs

Choose an SDK

OpenAPI

The spec