tiktok-ads-kit

Typed, quirk-aware TikTok Marketing API client for TypeScript. Campaign management, reporting, pixels, Spark ads, automated rules — with the API's sharp edges absorbed so you don't rediscover them in production.

npm install tiktok-ads-kit

import { createTikTokAds } from "tiktok-ads-kit";

const tiktok = createTikTokAds({
  accessToken: process.env.TIKTOK_ACCESS_TOKEN!,
  advertiserId: process.env.TIKTOK_ADVERTISER_ID!,
});

const campaigns = await tiktok.getCampaigns();
const report = await tiktok.getReport({
  dataLevel: "AUCTION_CAMPAIGN",
  dimensions: ["campaign_id"],
  startDate: "2026-01-01",
  endDate: "2026-01-28",
});

Why this exists

The official SDK is autogenerated and faithfully exposes every quirk of the raw API. This kit encodes the lessons you'd otherwise learn one production incident at a time:

| Quirk | What the kit does | |---|---| | Errors arrive as HTTP 200 with code !== 0 in the body | Parsed and thrown with the real message; transport failures (non-JSON, 5xx) get distinct errors | | Two incompatible filtering formats — entity endpoints take {campaign_ids: [...]}, report endpoints take [{field_name, filter_type, filter_value}] | Each method uses the right one; you pass campaignIds: string[] | | Smart+ campaigns reject standard update endpoints ("This API does not support Upgraded Smart Plus ads") and need /smart_plus/... twins with targeting nested under targeting_spec | Updates fall back automatically | | stat_time_day reports cap at 30-day spans; pixel event stats at 28 days | Documented on the methods; chunk longer windows yourself | | Video info lookups cap at 60 ids per call | Chunked automatically | | All report metric values are strings | Typed honestly as Record<Metric, string> | | Spark ads reference an organic post via tiktok_item_id + identity, not a video_id; their covers come from /identity/video/info/ | getPostInfo() resolves video posters and carousel covers | | Smart+ "ads" are auto-generated variants of one container ad — individually unpausable | Surfaced in docs so you don't fight it |

API surface

Reads: getAdvertiserInfo · getCampaigns · getAdGroups · getAds · getVideoInfo · getPostInfo · getReport · getAudienceReport · getRegionNames · getPixels · getPixelEventStats · getRules

Writes: updateEntityStatus · updateAdGroupBudget · updateAdGroupAgeGroups · updateAdGroupSchedule · createCampaign · createAdGroup (paused by default) · createSparkAd · createRule · uploadVideo

Safety defaults: ad groups are created DISABLEd (you flip them live explicitly), and nothing is cached — bring your own caching layer.

Sandbox

createTikTokAds({
  accessToken,
  advertiserId,
  baseUrl: "https://sandbox-ads.tiktok.com/open_api/v1.3",
});

Related

next-pixels — the other direction: events from your site into TikTok/Meta (pixel + CAPI + first-touch attribution). The two meet at the ttclid.

License

MIT