Skip to content
TikTok Shop Partner API

Search Creator Affiliate Orders

POST
/affiliate_creator/202410/orders/search

Search affiliate orders attributed to the authenticated creator. The response includes order and SKU details, order status, content attribution, commission rates, and estimated or actual commission amounts for tracking affiliate conversions.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
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_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.
integer format: int64
create_time_lt

Filter orders to show only those created before the specified time, expressed as a Unix timestamp in seconds. Refer to the notes in create_time_ge for more usage information.

integer format: int64
Example
{
  "create_time_ge": 1719807456,
  "create_time_lt": 1728443155
}

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 order resource.

Array<object>
object
id

The order identifier.

string
create_time

The time when the order was created, as a Unix timestamp in seconds (UTC).

integer format: int64
delivery_time

The time when the order was delivered, as a Unix timestamp in seconds (UTC).

integer format: int64
status

The current status of the order. Possible options are:

  • UNSPECIFIED: The status of the order is undefined. It might be updated later.
  • AWAITING PAYMENT：The order hasn’t been paid 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.
  • REFUNDED: The order has been returned/refunded/canceled by the buyer, and no commission will be settled.
  • FROZEN: Possible fraud has been detected regarding the order. The commission will be unfrozen after the fraud is resolved.
string
skus

A list of SKUs associated with the order.

Array<object>
object
id

The SKU identifier.

string
campaign_id

The campaign identifier associated with the order.

string
open_collaboration_id

The open collaboration identifier associated with the order.

string
target_collaboration_id

The target collaboration identifier associated with the order.

string
product_name

The product name in the TikTok Shop.

string
product_id

The product identifier.

string
price

An object representing the localized price of the product.

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
shop_name

The name of the TIkTok Shop in which the product is offered for sale.

string
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 for the creator content through which the order was created.

string
quantity

The quantity of this SKU in the order, including refunded units.

integer format: int64
commission_rate

The total commission rate for this SKU, equal to the sum of the standard commission rate, shop ads commission rate, bonus rate, and reward rate. It is expressed in hundredths of a percent; the percent sign (%) is not included. For example, 3000 represents a 30% commission.

integer format: int64
commission_tier_setting

Between Seller & Creator percentagecommission. When tiering commission model applied, will return each tier’s commission rate seller set.

string
commission_model

The commission model used for the order. Possible values:

  • Fixed commission
  • Tiered commission
string
commission_bonus_rate

The commission bonus rate associated with the collaboration. It is expressed in hundredths of a percent; the percent sign (%) is not included. For example, 3000 represents a 30% commission.

integer format: int64
estimated_commission_base

An object representing the estimated base commission at the time of order creation.

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
standard_commission_rate

The standard affiliate commission rate associated with the collaboration. It is expressed in hundredths of a percent; the percent sign (%) is not included. For example, 3000 represents a 30% commission.

integer format: int64
shop_ads_commission_rate

The commission rate received by a creator for a sale associated with a specific piece of content. It is expressed in hundredths of a percent; the percent sign (%) is not included. For example, 3000 represents a 30% commission.

integer format: int64
estimated_bonus_commission

An object representing the estimated bonus commission, calculated by multiplying the estimated commission base by the commission bonus rate.

object
amount

When available, the estimated bonus commission amount 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_standard_commission

An object representing the estimated standard affiliate commission, calculated by multiplying the estimated commission base by the standard_commission_rate.

object
amount

Commission amount without a currency symbol. Use the sibling currency field to identify the currency.

string
currency

Type of currency use

string
estimated_shop_ads_commission

An object representing the estimated shop ads commission, calculated by multiplying the estimated commission base by the shop_ads_commission_rate

object
amount

The estimated shop ads commission amount 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_commission

The creator’s total estimated commission earnings for this SKU after applicable additions and deductions.

object
amount

The estimated commission amount 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
actual_commission

Represents the final earnings of this sku, calculated by multiplying the actual commission base by the total commission rate, and then deducting the taxes or revenue sharing with the agency amount.

object
amount

The actual commission amount 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. An empty string means that no actual commission value is available.

string
currency

The currency code.

string
actual_bonus_commission

An object representing the actual bonus commission, calculated by multiplying the actual commission base by the commission bonus rate.

object
amount

The actual bonus commission amount 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
actual_commission_base

An object representing the actual commission base, calculated by multiplying the product sale price by the number of products sold, subtracting returned and refunded orders.

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_standard_commission

An object representing the actual standard affiliate commission, calculated by multiplying the commission base by the standard_commission_rate.

object
amount

Commission amount without a currency symbol. Use the sibling currency field to identify the currency.

string
currency

Type of currency use

string
actual_shop_ads_commission

An object representing the actual shop ads commission, calculated by multiplying the commission base by the shop_ads_commission_rate.

object
amount

When available, the actual shop ads commission amount 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
returned_quantity

The returned quantity for this SKU in the order.

integer format: int64
refunded_quantity

The refunded quantity for this SKU in the order.

integer format: int64
tag

A field for storing user-defined metadata for tracking purposes.

string
creator_commission_reward_rate

The commission reward rate that an affiliate partner allocates to the creator. It is expressed in hundredths of a percent; the percent sign (%) is not included. For example, 1000 represents 10%.

integer format: int64
estimated_creator_commission_reward_fee

Estimated creator commission reward fee.

object
amount

When available, the estimated creator commission reward fee 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
actual_creator_commission_reward_fee

Actual creator commission reward fee.

object
amount

When available, the actual creator commission reward fee 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
isr

Only for Mexico creator, platform collected related revenue taxes on behalf of government based on regulation.

object
amount

The actual isr amount.

string
currency

The currency code.

string
iva

Only for Mexico creator, platform collected related revenue taxes on behalf of government based on regulation.

object
amount

The actual iva amount.

string
currency

The currency code.

string
pit

Only for VN/TH/PH/ID creators, sellers collect related withholding taxes based on regulation.

object
amount

The actual pit amount.

string
currency

The currency code.

string
shared_with_partner

The amount of the creator’s after-tax revenue shared with the affiliated institution under the applicable fee agreement.

object
amount

The actual shared with partner amount.

string
currency

The currency code.

string
trace_info

Extra information for tracing purposes.

object
id

When trace_info.type is GENERAL, this is the {eid} provided in sharing_link; when trace_info.type is SPECIFIC, this is the publisher_id.

string
type

For the orders coming from the sharing links for specific publishers, the value is SPECIFIC; for the orders coming from the general sharing links, the value is GENERAL.

string
last_update_time

The time when the record was last updated, as a Unix timestamp in seconds (UTC).

integer format: int64
is_carousel

Carousel content may involve a commission rate discount. Returns true when the order is attributed to carousel content.

boolean
next_page_token

An opaque token used to retrieve the next page of results. Specify create_time_ge and create_time_lt in the first request and reuse the same values for every page. Pass a non-empty returned token as page_token in the next request. An empty value indicates the last page; stop requesting additional pages.

string
total_count

The total number of SKU orders that match the search criteria. page_size limits SKU-order rows before they are grouped into orders; because one order can contain multiple SKUs, the number of returned order objects can be less than page_size. Use next_page_token to continue pagination.

integer format: int64
Example
{
  "code": 0,
  "data": {
    "orders": [
      {
        "id": "789078671231123124",
        "create_time": 1685548800,
        "delivery_time": 1685548800,
        "status": "SETTLED",
        "skus": [
          {
            "id": "1729793769377925388",
            "campaign_id": "73661290629",
            "open_collaboration_id": "73661290629",
            "target_collaboration_id": "73661290629",
            "product_name": "black_suit",
            "product_id": "1729793769377859852",
            "price": {
              "amount": "Rp9.900",
              "currency": "IDR"
            },
            "shop_name": "TestCase idl2l",
            "content_type": "LIVE",
            "content_id": "7493990579714164574",
            "quantity": 2,
            "commission_rate": 1000,
            "commission_tier_setting": "3.0 OR 5.0",
            "commission_model": "Tiered commission",
            "commission_bonus_rate": 1000,
            "estimated_commission_base": {
              "amount": "Rp9.900",
              "currency": "IDR"
            },
            "standard_commission_rate": 5000,
            "shop_ads_commission_rate": 5000,
            "estimated_bonus_commission": {
              "amount": "Rp1.00",
              "currency": "IDR"
            },
            "estimated_standard_commission": {
              "amount": "Rp8.000",
              "currency": "IDR"
            },
            "estimated_shop_ads_commission": {
              "amount": "Rp8.000",
              "currency": "IDR"
            },
            "estimated_commission": {
              "amount": "Rp1.980",
              "currency": "IDR"
            },
            "actual_commission": {
              "amount": "Rp1.900",
              "currency": "IDR"
            },
            "actual_bonus_commission": {
              "amount": "Rp2.000",
              "currency": "IDR"
            },
            "actual_commission_base": {
              "amount": "Rp9.900",
              "currency": "IDR"
            },
            "actual_standard_commission": {
              "amount": "Rp5.000",
              "currency": "IDR"
            },
            "actual_shop_ads_commission": {
              "amount": "Rp5.000",
              "currency": "IDR"
            },
            "returned_quantity": 1,
            "refunded_quantity": 0,
            "tag": "test-01",
            "creator_commission_reward_rate": 1000,
            "estimated_creator_commission_reward_fee": {
              "amount": "250",
              "currency": "IDR"
            },
            "actual_creator_commission_reward_fee": {
              "amount": "100",
              "currency": "IDR"
            },
            "isr": {
              "amount": "100",
              "currency": "MXN"
            },
            "iva": {
              "amount": "100",
              "currency": "MXN"
            },
            "pit": {
              "amount": "100",
              "currency": "IDR"
            },
            "shared_with_partner": {
              "amount": "100",
              "currency": "IDR"
            },
            "trace_info": {
              "id": "15678763",
              "type": "SPECIFIC"
            },
            "last_update_time": 1685548800,
            "is_carousel": false
          }
        ]
      }
    ],
    "next_page_token": "b2Zmc2V0PTEw",
    "total_count": 10
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}
DocsSDKsAPI Reference

Start here

Getting StartedConceptsAuthorizationWebhooksErrors

SDKs

Choose an SDK

OpenAPI

The spec