API reference / Ads API / Get Product Ads

Get Product Ads

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

Returns daily product-level advertising for the shop in the X-Shop-Id header. Each row includes the product info plus its advertising cost, using the same product-ads source as Product Orders on the Kixmon dashboard. startDate and endDate are required and filter by ads date.

For how the headers work, refer to Authentication.

GEThttps://api.kixmon.io/api/v1/product-ads

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
startDateRequired integer Earliest ads date, Unix seconds. Maximum range is 366 days. Example: 1756598400.
endDateRequired integer Latest ads date, Unix seconds. Maximum range is 366 days. Example: 1756684799.
sortOptional string ASC or DESC. Defaults to DESC when omitted. Sorted by date.
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/product-ads?startDate=1756598400&endDate=1756684799&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/product-ads?startDate=1756598400&endDate=1756684799&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/product-ads",
    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": 1756598400, "endDate": 1756684799, "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 Product ads on this page
date integer Ads date, Unix seconds
product object Product info
productId string TikTok product id
name string Product name
icon string Product image URL, or null
advertisingCost object Product advertising cost
total number Total advertising cost for this product on this day
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": [
      {
        "date": 1756598400,
        "product": {
          "productId": "1729382256910270000",
          "name": "Wireless earbuds",
          "icon": "https://example.com/earbuds.jpg"
        },
        "advertisingCost": {
          "total": 12.4
        }
      }
    ],
    "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.



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.

Get in Touch

©Kixmon LLC. All Rights Reserved.
Certified TikTok Shop Partner