Fav Icon START YOUR 7 DAY FREE TRIAL Fav Icon

API reference / Order API / Get Orders by Product

Get Orders by Product

Required headers: X-App-Key X-App-Secret X-Shop-Id

Returns paid orders for the shop in the X-Shop-Id header, with each order carrying a products array. GMV, TikTok fees, shipping, and cost of goods are broken down per product, so you can attribute profit to individual products and SKUs within a multi-item order. Cost amounts are returned as negative numbers.

For how the headers work, refer to Authentication.

Version v1API Testing Tool
GEThttps://api.kixmon.io/api/v1/orders-by-product

Request

Properties Type Description
X-App-KeyRequired string App key created when REST APIs are enabled in Settings. Example: km_your_app_key.
X-App-SecretRequired string App secret created when REST APIs are enabled in Settings. Store it on your server only — never send it from a browser or mobile app.
X-Shop-IdRequired string The shop to query. Get this id from Get Shops.

Query

Properties Type Description
orderNumberOptional string Filter by order number. Example: 576482910375629184.
orderTypeOptional string SETTLED, UNSETTLED, or DRAFT.
sampleOrderOptional string YES or NO.
statusOptional string Filter by order status, for example COMPLETED or CANCELLED.
startDateOptional integer Earliest create time, Unix seconds. Maximum range is 366 days. Example: 1788220800.
endDateOptional integer Latest create time, Unix seconds. Maximum range is 366 days. Example: 1789171199.
sortOptional string ASC or DESC. Defaults to DESC when omitted. Sorted by create time.
productIdOptional string Filter by TikTok product id. Example: 1729384756102938.
nameOptional string Filter by product name. Example: serum.
skuIdOptional string Filter by SKU id. Example: 1729384756102940.
skuNameOptional string Filter by SKU name or seller SKU. Example: SERUM-30ML.
pageOptional integer Page number. Defaults to 1.
limitOptional integer Results per page. Defaults to 10, maximum 100.

Dates are Unix timestamps in seconds. The range between startDate and endDate can be at most 366 days.

Example

curl 'https://api.kixmon.io/api/v1/orders-by-product?startDate=1788220800&endDate=1789171199&page=1&limit=10' \
  -H "X-App-Key: $KIXMON_APP_KEY" \
  -H "X-App-Secret: $KIXMON_APP_SECRET" \
  -H "X-Shop-Id: $KIXMON_SHOP_ID"
const res = await fetch("https://api.kixmon.io/api/v1/orders-by-product?startDate=1788220800&endDate=1789171199&page=1&limit=10", {
  headers: {
    "X-App-Key": process.env.KIXMON_APP_KEY,
    "X-App-Secret": process.env.KIXMON_APP_SECRET,
    "X-Shop-Id": process.env.KIXMON_SHOP_ID,
  },
});
const data = await res.json();
import os, requests

resp = requests.get(
    "https://api.kixmon.io/api/v1/orders-by-product",
    headers={
        "X-App-Key": os.environ["KIXMON_APP_KEY"],
        "X-App-Secret": os.environ["KIXMON_APP_SECRET"],
        "X-Shop-Id": os.environ["KIXMON_SHOP_ID"],
    },
    params={"startDate": 1788220800, "endDate": 1789171199, "page": 1, "limit": 10},
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response

Parameters

Properties Type Description
success boolean true when the request succeeds
data object Response payload
items array Orders on this page
id string Kixmon Order id
orderNumber string TikTok order number
createTime integer Order create time, Unix seconds
paidTime integer Order paid time, Unix seconds
cancelTime integer Order cancel time, Unix seconds, or null
status string Specific order status. Available values:

  • UNPAID: The order has been placed, but payment has not been completed.
  • ON_HOLD: The order has been accepted and is awaiting fulfillment. The buyer may still cancel without the seller’s approval. If order_type=PRE_ORDER, the product is still awaiting release so payment will only be authorized 1 day before the release, but the seller should start preparing for the release.
  • AWAITING_SHIPMENT: The order is ready to be shipped, but no items have been shipped yet.
  • PARTIALLY_SHIPPING: Some items in the order have been shipped, but not all.
  • AWAITING_COLLECTION: Shipping has been arranged, but the package is waiting to be collected by the carrier.
  • IN_TRANSIT: The package has been collected by the carrier and delivery is in progress.
  • DELIVERED: The package has been delivered to the buyer.
  • COMPLETED: The order has been completed, and no further returns or refunds are allowed.
  • CANCELLED: The order has been cancelled.
orderType string SETTLED, UNSETTLED, or DRAFT
sampleOrder string YES or NO
shippingType string The delivery method. Available values:

  • TIKTOK: Shipping service provided by TikTok. The seller should obtain a shipping label from TikTok.
  • SELLER: Seller provides shipping, including through 3rd party fulfillment providers on behalf of the seller.
  • TIKTOK_DIGITAL: TikTok delivers virtual goods directly to buyers. There is no action needed.
  • IN-STORE PICKUP: Buyer pickup the goods directly at seller location. Available for SEA market only.
fulfillmentType string Fulfillment type. Only orders with fulfillment type can be shipped by sellers. Available values:

  • FULFILLMENT_BY_SELLER: a method where sellers fulfill orders directly from their own inventory, without using TikTok’s fulfillment centers. In this model, the seller is responsible for storing, packaging, and shipping the products to customers.
  • FULFILLMENT_BY_TIKTOK: a service offered by TikTok where sellers can send their products to TikTok’s fulfillment centers. TikTok then takes care of storing, picking, packing, and shipping the products to customers.
  • FULFILLMENT_BY_DILAYANI_TOKOPEDIA: a method where Tokopedia GoTo Logistics provides warehousing and logistics services to sellers and charges a fee for the service.
products array Products on the order, each with its own P&L figures
productId string TikTok product id
name string Product name
skuId string SKU id
skuName string SKU name
sellerSku string Seller SKU
icon string Product image URL, or null
gmv number Gross merchandise value for this product
gmvBreakdown object GMV split by product sales, shipping, and discounts
grossSales number Gross sales for this product
promos number Promo amount, sent as a negative amount
costOfGoods number Cost of goods, sent as a negative amount
shippingCost object Shipping cost for this product
tiktokFees object TikTok fees for this product
affiliateCommission object Affiliate commission for this product
pagination object Pagination details
page integer Current page number
limit integer Results per page
total integer Total matching results
totalPages integer Total number of pages

Example

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "6601bb...",
        "orderNumber": "5760000000000000000",
        "createTime": 1710000000,
        "paidTime": 1710000300,
        "cancelTime": null,
        "status": "COMPLETED",
        "orderType": "SETTLED",
        "sampleOrder": "NO",
        "shippingType": "TIKTOK",
        "fulfillmentType": "FULFILLMENT_BY_TIKTOK",
        "products": [
          {
            "productId": "1729382256910270000",
            "name": "Wireless earbuds",
            "skuId": "1729382256910270001",
            "skuName": "Black",
            "sellerSku": "EARBUD-BLK",
            "icon": "https://example.com/earbuds.jpg",
            "gmv": 21.25,
            "gmvBreakdown": {
              "productSales": 20,
              "shippingFee": 2.25,
              "sellerDiscount": 1,
              "platformDiscount": 0
            },
            "grossSales": 20,
            "promos": -1,
            "costOfGoods": -4.25,
            "shippingCost": {
              "total": -1.7,
              "sellerShipping": -1.05,
              "tiktokShipping": -0.65,
              "fbt": 0
            },
            "tiktokFees": {
              "total": -1.55,
              "referralFeeAndTax": -1.2,
              "cofundedPromotionServiceFee": 0,
              "sellerSelfShippingServiceFee": 0,
              "smartPromotionFeeAndTax": 0,
              "campaignServiceFee": 0,
              "campaignResourceFee": 0,
              "managedServicePlanFee": 0,
              "cofundedPromotionCampaignPeriodFee": 0,
              "smartPromotionCampaignPeriodFee": 0,
              "transactionFee": -0.35,
              "otherFeeAndTax": 0
            },
            "affiliateCommission": {
              "total": -0.6,
              "shopAdsCommission": 0,
              "partnerCommission": 0,
              "commission": -0.6,
              "cofundedCreatorBonus": 0,
              "deposit": 0,
              "refund": 0,
              "partnerShopAdsCommission": 0
            }
          },
          {
            "productId": "1729382256910270002",
            "name": "Charging case",
            "skuId": "1729382256910270003",
            "skuName": "White",
            "sellerSku": "CASE-WHT",
            "icon": "https://example.com/case.jpg",
            "gmv": 21.25,
            "gmvBreakdown": {
              "productSales": 20,
              "shippingFee": 2.25,
              "sellerDiscount": 1,
              "platformDiscount": 0
            },
            "grossSales": 20,
            "promos": -1,
            "costOfGoods": -4.25,
            "shippingCost": {
              "total": -1.7,
              "sellerShipping": -1.05,
              "tiktokShipping": -0.65,
              "fbt": 0
            },
            "tiktokFees": {
              "total": -1.55,
              "referralFeeAndTax": -1.2,
              "cofundedPromotionServiceFee": 0,
              "sellerSelfShippingServiceFee": 0,
              "smartPromotionFeeAndTax": 0,
              "campaignServiceFee": 0,
              "campaignResourceFee": 0,
              "managedServicePlanFee": 0,
              "cofundedPromotionCampaignPeriodFee": 0,
              "smartPromotionCampaignPeriodFee": 0,
              "transactionFee": -0.35,
              "otherFeeAndTax": 0
            },
            "affiliateCommission": {
              "total": -0.6,
              "shopAdsCommission": 0,
              "partnerCommission": 0,
              "commission": -0.6,
              "cofundedCreatorBonus": 0,
              "deposit": 0,
              "refund": 0,
              "partnerShopAdsCommission": 0
            }
          }
        ]
      }
    ],
    "pagination": { "page": 1, "limit": 10, "total": 1, "totalPages": 1 }
  }
}

Error Code

HTTP status Code Description
400 INVALID_REQUEST A header or query parameter is invalid.
401 MISSING_CREDENTIALS X-App-Key or X-App-Secret is missing.
401 INVALID_CREDENTIALS App key or app secret is wrong.
403 FEATURE_UNAVAILABLE REST APIs are not on the current plan.
404 SHOP_NOT_FOUND Shop not found or not available for this app key.
429 RATE_LIMITED More than 60 requests were sent in one minute for this app key, or the IP limit was reached. Wait, then retry.
500 INTERNAL_ERROR An unexpected error occurred. Retry later.



K
KIXMON
Tiktok Shop Partner

Kixmon makes it so easy to know your numbers. See all hidden costs, track every penny, and avoid profit headaches—it’s all at your fingertips.

Resources

Features

Get in Touch

©Kixmon LLC. All Rights Reserved.
Certified TikTok Shop Partner
Terms & Conditions · Privacy Policy · Delete Account