Fav Icon START YOUR 7 DAY FREE TRIAL Fav Icon

API reference / Order API / Get Orders

Get Orders

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

Returns paid orders for the shop in the X-Shop-Id header, with the same P&L figures as the Kixmon dashboard: GMV with its breakdown, shipping cost, itemized TikTok fees, affiliate commission, and cost of goods. Cost amounts are returned as negative numbers, so net profit is a straight sum. Optional startDate and endDate filter by createTime.

For how the headers work, refer to Authentication.

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

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 Order status, for example COMPLETED.
startDateOptional integer Earliest create time, Unix seconds. Example: 1788220800.
endDateOptional integer Latest create time, Unix seconds. Example: 1789171199.
sortOptional string ASC or DESC. Defaults to DESC.
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?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?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",
    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 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.
gmv number Gross merchandise value
gmvBreakdown object GMV split by product sales, shipping, and discounts
grossSales number Gross sales
promos number Promo amount
costOfGoods number Cost of goods, sent as a negative amount
shippingCost object Shipping cost
tiktokFees object TikTok fees
affiliateCommission object Affiliate commission
products array Line items on the order
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",
        "gmv": 42.5,
        "gmvBreakdown": {
          "productSales": 40,
          "shippingFee": 4.5,
          "sellerDiscount": 2,
          "platformDiscount": 0
        },
        "grossSales": 40,
        "promos": -2,
        "costOfGoods": -8.5,
        "shippingCost": {
          "total": -3.4,
          "sellerShipping": -2.1,
          "tiktokShipping": -1.3,
          "fbt": 0
        },
        "tiktokFees": {
          "total": -3.1,
          "referralFeeAndTax": -2.4,
          "cofundedPromotionServiceFee": 0,
          "sellerSelfShippingServiceFee": 0,
          "smartPromotionFeeAndTax": 0,
          "campaignServiceFee": 0,
          "campaignResourceFee": 0,
          "managedServicePlanFee": 0,
          "cofundedPromotionCampaignPeriodFee": 0,
          "smartPromotionCampaignPeriodFee": 0,
          "transactionFee": -0.7,
          "otherFeeAndTax": 0
        },
        "affiliateCommission": {
          "total": -1.2,
          "shopAdsCommission": 0,
          "partnerCommission": 0,
          "commission": -1.2,
          "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