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.
Version v1API Testing Tool
GEThttps://api.kixmon.io/api/v1/product-ads
Request
Header
| 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.
Resources
Features
Get in Touch
Emailanna@kixmonapp.com
Phone+1 3472959050
START YOUR 7 DAY FREE TRIAL