API reference / Ads API / Get Shop Ads

Get Shop Ads

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

Returns one row per day of shop-level advertising for the shop in the X-Shop-Id header, using the same P&L advertising-cost breakdown as the Kixmon dashboard: spend minus ads credit. 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/shop-ads

Request

Properties	Type	Description
`X-App-Key`Required	string	App key created when REST APIs are enabled in Settings. Example: `km_your_app_key`.
`X-App-Secret`Required	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-Id`Required	string	The shop to query. Get this id from Get Shops.

Query

Properties	Type	Description
`startDate`Required	integer	Earliest ads date, Unix seconds. Maximum range is 366 days. Example: `1756598400`.
`endDate`Required	integer	Latest ads date, Unix seconds. Maximum range is 366 days. Example: `1756684799`.
`sort`Optional	string	`ASC` or `DESC`. Defaults to `DESC` when omitted. Sorted by date.
`page`Optional	integer	Page number. Defaults to 1.
`limit`Optional	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/shop-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/shop-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/shop-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	Shop ads days on this page
`date`	integer	Ads date, Unix seconds
`advertisingCost`	object	Advertising cost, same breakdown as P&L
`total`	number	Total advertising cost: spend minus ads credit
`spend`	number	Ads spend
`adsCredit`	number	Ads credit applied
`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,
        "advertisingCost": {
          "total": 96.47,
          "spend": 120,
          "adsCredit": 23.53
        }
      }
    ],
    "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.

Get Shop Ads

Request

Header

Query

Example

Response

Parameters

Example

Error Code

Resources

Features

Get in Touch