How to Integrate Bolt.new with TikTok Ads

TikTok's Marketing API access requires creating an app in TikTok's developer portal and applying for the Marketing API product within that app. The process has two phases: app creation (immediate) and API access approval (one to two weeks). Go to developers.tiktok.com and sign in with your TikTok for Business account. Click 'Create app' and fill in the required information: app name, description, website URL, and your intended use case. Under 'Products,' look for 'Marketing API' and click to add it. You will be prompted to describe your use case — be specific about building an analytics dashboard for your own TikTok Ads account. After submitting, TikTok's team reviews your application. The review typically takes five to ten business days. You receive an email notification when approved. While waiting, note your App ID (Client Key) and App Secret (Client Secret) from the app dashboard — you will need these for OAuth. Your TikTok Advertiser ID is different from your developer App ID. Find it in TikTok Ads Manager (ads.tiktok.com) — it is the numeric ID shown in the account selector dropdown or in the URL when viewing your account. The Advertiser ID format is a 19-digit number like `7012345678901234567`. Once API access is approved, your app is authorized to call Marketing API endpoints on behalf of TikTok for Business accounts that authorize it. Add your App ID, App Secret, and Advertiser ID to your Bolt project's .env file.

1// lib/tiktok.ts
2const TIKTOK_API_BASE = 'https://business-api.tiktok.com/open_api/v1.3';
3
4interface TikTokResponse<T> {
5  code: number;
6  message: string;
7  data?: T;
8  request_id?: string;
9}
10
11interface TikTokFetchOptions {
12  params?: Record<string, string>;
13  method?: 'GET' | 'POST';
14  body?: Record<string, unknown>;
15}
16
17export async function tiktokFetch<T = unknown>(
18  endpoint: string,
19  options: TikTokFetchOptions = {}
20): Promise<T> {
21  const accessToken = process.env.TIKTOK_ACCESS_TOKEN;
22  if (!accessToken) {
23    throw new Error('TIKTOK_ACCESS_TOKEN is not configured');
24  }
25
26  const url = new URL(`${TIKTOK_API_BASE}/${endpoint}`);
27  if (options.params) {
28    Object.entries(options.params).forEach(([k, v]) => url.searchParams.set(k, v));
29  }
30
31  const response = await fetch(url.toString(), {
32    method: options.method || 'GET',
33    headers: {
34      'Access-Token': accessToken,
35      'Content-Type': 'application/json',
36    },
37    body: options.body ? JSON.stringify(options.body) : undefined,
38  });
39
40  const result = await response.json() as TikTokResponse<T>;
41
42  if (result.code !== 0) {
43    throw new Error(`TikTok API error ${result.code}: ${result.message}`);
44  }
45
46  if (!result.data) {
47    throw new Error('TikTok API returned no data');
48  }
49
50  return result.data;
51}
52
53export function getTikTokAdvertiserId(): string {
54  const id = process.env.TIKTOK_ADVERTISER_ID;
55  if (!id) throw new Error('TIKTOK_ADVERTISER_ID is not configured');
56  return id;
57}

TikTok Marketing API uses OAuth 2.0 with a standard authorization code flow. The initial authorization requires redirecting the user to TikTok's consent screen on a deployed URL, since TikTok cannot redirect back to Bolt's WebContainer preview. The authorization URL is: `https://ads.tiktok.com/marketing_api/auth?app_id={APP_ID}&state={RANDOM_STATE}&redirect_uri={ENCODED_REDIRECT_URI}&rid={RID}`. The `rid` parameter is a unique identifier for the authorization request — generate a UUID. The redirect URI must exactly match one registered in your TikTok developer app settings. After the user authorizes, TikTok redirects to your callback URL with an `auth_code` parameter. Exchange this code for an access token by calling: `POST https://business-api.tiktok.com/open_api/v1.3/oauth2/access_token/` with a JSON body containing `app_id`, `auth_code`, and `secret`. Unlike most OAuth providers, TikTok Marketing API tokens have a fixed expiry of 24 hours and do not support refresh tokens in the traditional sense. Instead, you use a 'refresh access token' endpoint with your existing access token to extend it — but this extension only works while the token is still valid. If a token expires before being refreshed, the full authorization flow must be repeated. For a single-account dashboard (your own TikTok Ads account), a practical approach is to generate a new access token daily using an automated job or generate one manually for development. TikTok's Business API documentation also describes 'Long Term Tokens' available through a separate process for apps that need persistent access — contact TikTok's business support if you need non-expiring tokens for a production dashboard. For initial setup, deploy a minimal version of your app to get the redirect URI working, complete the OAuth flow, copy the access token to your .env, and proceed with building the dashboard.

1// app/api/tiktok/auth/callback/route.ts
2import { NextResponse } from 'next/server';
3
4export async function GET(request: Request) {
5  const { searchParams } = new URL(request.url);
6  const authCode = searchParams.get('auth_code');
7
8  if (!authCode) {
9    return NextResponse.json(
10      { error: 'No auth_code received from TikTok OAuth redirect' },
11      { status: 400 }
12    );
13  }
14
15  const appId = process.env.TIKTOK_APP_ID;
16  const appSecret = process.env.TIKTOK_APP_SECRET;
17
18  if (!appId || !appSecret) {
19    return NextResponse.json(
20      { error: 'TIKTOK_APP_ID or TIKTOK_APP_SECRET not configured' },
21      { status: 500 }
22    );
23  }
24
25  const response = await fetch(
26    'https://business-api.tiktok.com/open_api/v1.3/oauth2/access_token/',
27    {
28      method: 'POST',
29      headers: { 'Content-Type': 'application/json' },
30      body: JSON.stringify({
31        app_id: appId,
32        secret: appSecret,
33        auth_code: authCode,
34      }),
35    }
36  );
37
38  const result = await response.json() as {
39    code: number;
40    message: string;
41    data?: {
42      access_token: string;
43      advertiser_ids: string[];
44      expires_in: number;
45    };
46  };
47
48  if (result.code !== 0 || !result.data) {
49    return NextResponse.json(
50      { error: `Token exchange failed: ${result.message}` },
51      { status: 500 }
52    );
53  }
54
55  return NextResponse.json({
56    accessToken: result.data.access_token,
57    advertiserIds: result.data.advertiser_ids,
58    expiresIn: result.data.expires_in,
59    expiresAt: new Date(Date.now() + result.data.expires_in * 1000).toISOString(),
60    message: 'Add TIKTOK_ACCESS_TOKEN to your .env file. Token expires in 24 hours.',
61    envLine: `TIKTOK_ACCESS_TOKEN=${result.data.access_token}`,
62  });
63}

TikTok's Marketing API reports use a single reporting endpoint with a flexible dimension and metric system. Rather than separate endpoints per metric type, all performance data is requested from `GET /v1.3/report/integrated/get/` with advertiser_id, report_type, dimensions, metrics, and date range parameters. For campaign-level reporting, set `report_type=BASIC` and `dimensions=["campaign_id"]`. For ad group level, use `dimensions=["adgroup_id"]`. For ad level (individual creatives), use `dimensions=["ad_id"]`. Additional dimensions you can include: `stat_time_day` for daily breakdowns, `age`, `gender`, `country_code` for demographic breakdowns. Key metrics for a TikTok Ads dashboard: standard ad metrics — `spend`, `impressions`, `clicks`, `ctr`, `cpc`, `conversions`, `cpa`, `conversion_rate`. TikTok-specific video metrics — `video_play_actions` (total starts), `video_watched_2s`, `video_watched_6s`, `video_completion_rate` (percentage who watched the full ad), `average_video_play_per_user` (average seconds watched), `engaged_view` (3 second views). Engagement metrics — `likes`, `comments`, `shares`, `follows`, `profile_visits`. The hook rate (sometimes called 'thumb-stop rate') is calculated as `video_watched_2s / impressions` — it measures whether the opening seconds of the video stopped the scroll. A hook rate above 25% is generally considered strong; below 15% suggests the creative opening needs work. The hold rate is `video_watched_6s / video_watched_2s` — measuring retention after the initial hook. TikTok returns paginated data with a `page_info` object containing `total_page` and `page`. For most accounts, one page of 20-50 campaigns is sufficient. For agencies managing many campaigns, implement pagination. The metrics are returned in a `list` array where each item contains a `metrics` object and a `dimensions` object. Join the dimensions (campaign ID and name) with the metrics by matching on the campaign ID field.

1// app/api/tiktok/campaigns/route.ts
2import { NextResponse } from 'next/server';
3import { tiktokFetch, getTikTokAdvertiserId } from '@/lib/tiktok';
4
5interface TikTokReportItem {
6  metrics: {
7    spend: string;
8    impressions: string;
9    clicks: string;
10    ctr: string;
11    cpc: string;
12    conversions: string;
13    cpa: string;
14    video_play_actions: string;
15    video_watched_2s: string;
16    video_watched_6s: string;
17    video_completion_rate: string;
18  };
19  dimensions: {
20    campaign_id: string;
21    campaign_name?: string;
22  };
23}
24
25interface TikTokReportResponse {
26  list: TikTokReportItem[];
27  page_info: {
28    total_number: number;
29    page: number;
30    page_size: number;
31    total_page: number;
32  };
33}
34
35export async function GET(request: Request) {
36  const { searchParams } = new URL(request.url);
37  const advertiserId = getTikTokAdvertiserId();
38
39  const endDate = searchParams.get('endDate') || new Date().toISOString().split('T')[0];
40  const startDate = searchParams.get('startDate') ||
41    new Date(Date.now() - 30 * 86400000).toISOString().split('T')[0];
42
43  try {
44    const reportData = await tiktokFetch<TikTokReportResponse>(
45      'report/integrated/get/',
46      {
47        params: {
48          advertiser_id: advertiserId,
49          report_type: 'BASIC',
50          dimensions: JSON.stringify(['campaign_id']),
51          metrics: JSON.stringify([
52            'spend', 'impressions', 'clicks', 'ctr', 'cpc',
53            'conversions', 'cpa', 'video_play_actions',
54            'video_watched_2s', 'video_watched_6s', 'video_completion_rate',
55          ]),
56          start_date: startDate,
57          end_date: endDate,
58          page_size: '50',
59          page: '1',
60        },
61      }
62    );
63
64    const campaigns = (reportData.list || []).map((item) => {
65      const m = item.metrics;
66      const impressions = parseInt(m.impressions || '0', 10);
67      const watched2s = parseInt(m.video_watched_2s || '0', 10);
68
69      return {
70        id: item.dimensions.campaign_id,
71        name: item.dimensions.campaign_name || item.dimensions.campaign_id,
72        spend: parseFloat(m.spend || '0'),
73        impressions,
74        clicks: parseInt(m.clicks || '0', 10),
75        ctr: parseFloat(m.ctr || '0'),
76        cpc: parseFloat(m.cpc || '0'),
77        conversions: parseInt(m.conversions || '0', 10),
78        cpa: parseFloat(m.cpa || '0'),
79        videoStarts: parseInt(m.video_play_actions || '0', 10),
80        watched2s,
81        watched6s: parseInt(m.video_watched_6s || '0', 10),
82        completionRate: parseFloat(m.video_completion_rate || '0'),
83        hookRate: impressions > 0 ? (watched2s / impressions) * 100 : 0,
84      };
85    });
86
87    campaigns.sort((a, b) => b.spend - a.spend);
88
89    const totals = campaigns.reduce(
90      (acc, c) => ({
91        spend: acc.spend + c.spend,
92        impressions: acc.impressions + c.impressions,
93        clicks: acc.clicks + c.clicks,
94        conversions: acc.conversions + c.conversions,
95      }),
96      { spend: 0, impressions: 0, clicks: 0, conversions: 0 }
97    );
98
99    return NextResponse.json({ campaigns, totals, dateRange: { startDate, endDate } });
100  } catch (err) {
101    const message = err instanceof Error ? err.message : 'Failed to fetch TikTok campaigns';
102    return NextResponse.json({ error: message }, { status: 500 });
103  }
104}

TikTok Ads dashboards should surface video-specific engagement metrics that differentiate TikTok's performance model from other ad platforms. The most valuable TikTok-specific metrics are Hook Rate (percentage of impressions that resulted in at least 2 seconds of watch time, measuring opening effectiveness), Hold Rate (percentage who continued watching after the initial hook), Video Completion Rate (percentage who watched the full ad), and Average Watch Time. Organize the dashboard with this hierarchy: a summary header with total spend, total impressions, total conversions, and average hook rate; a video performance section showing the distribution of completion rates across campaigns; and a campaign table with both standard and TikTok-specific columns. For the campaign table, consider two tab views: 'Performance' (spend, impressions, clicks, CTR, conversions, CPA) and 'Creative' (video starts, hook rate, completion rate, watched 6s). This lets users switch between business outcome metrics and creative quality signals without overwhelming a single table with too many columns. Benchmarks to show in the dashboard: TikTok's industry average hook rate is 25-40% for well-optimized creatives; hold rate above 50% indicates strong content retention; video completion rate above 20% for in-feed ads is considered strong. Display these benchmarks as reference lines or annotations in your charts so users can immediately contextualize their performance. For the color-coded column indicators: hook rate above 30% = green, 15-30% = yellow, below 15% = red. CPA below account average = green, 1-2x average = yellow, above 2x = red. These visual signals help users immediately identify which campaigns need creative attention without manual comparison.

Outbound TikTok API calls work in Bolt's WebContainer preview for reading campaign analytics. The TikTok Pixel (for browser-side conversion tracking) and the OAuth redirect callback require deployment to a live HTTPS domain. Deploy to Netlify via Settings → Applications → Connect Netlify, or click Publish to deploy to Bolt Cloud. Add server-side environment variables: `TIKTOK_APP_ID`, `TIKTOK_APP_SECRET`, `TIKTOK_ACCESS_TOKEN`, and `TIKTOK_ADVERTISER_ID`. Add the client-side `NEXT_PUBLIC_TIKTOK_PIXEL_ID` for browser-side conversion tracking. The TikTok Pixel enables conversion tracking and powers TikTok's algorithm optimization. Without it, TikTok cannot optimize campaigns toward conversion events and ROAS data is unavailable. Install it by creating a `TikTokPixel` component using Next.js Script that loads TikTok's pixel JavaScript from `https://analytics.tiktok.com/i18n/pixel/events.js`, initializes with your Pixel ID, and fires a PageView event. Add the component to your root layout. For conversion events, use `ttq.track('CompletePayment', { content_id, content_type, currency, value })` for purchases and `ttq.track('SubmitForm')` for lead generation. TikTok also supports server-side events via the Events API at `https://business-api.tiktok.com/open_api/v1.3/pixel/track/` — the same access token used for Marketing API calls works for the Events API, making TikTok's server-side tracking easier to set up than platforms requiring separate API tokens. For the TikTok Pixel access token, note that it is different from the Marketing API access token. The Pixel token is specific to your pixel and is found in TikTok Ads Manager → Assets → Events → your pixel → Settings → Access token. The Marketing API access token (from OAuth) is used for campaign analytics calls.

1// components/TikTokPixel.tsx
2'use client';
3
4import Script from 'next/script';
5
6declare global {
7  interface Window {
8    ttq?: {
9      track: (event: string, params?: Record<string, unknown>) => void;
10      page: () => void;
11      identify: (params: Record<string, unknown>) => void;
12      load: (pixelId: string) => void;
13    };
14  }
15}
16
17export function TikTokPixel() {
18  const pixelId = process.env.NEXT_PUBLIC_TIKTOK_PIXEL_ID;
19  if (!pixelId) return null;
20
21  return (
22    <Script
23      id="tiktok-pixel"
24      strategy="afterInteractive"
25      dangerouslySetInnerHTML={{
26        __html: `
27          !function (w, d, t) {
28            w.TiktokAnalyticsObject=t;
29            var ttq=w[t]=w[t]||[];
30            ttq.methods=["page","track","identify","instances","debug","on","off","once","ready","alias","group","enableCookie","disableCookie"];
31            ttq.setAndDefer=function(t,e){t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}};
32            for(var i=0;i<ttq.methods.length;i++)ttq.setAndDefer(ttq,ttq.methods[i]);
33            ttq.instance=function(t){for(var e=ttq._i[t]||[],n=0;n<ttq.methods.length;n++)ttq.setAndDefer(e,ttq.methods[n]);return e};
34            ttq.load=function(e,n){var i="https://analytics.tiktok.com/i18n/pixel/events.js";
35              ttq._i=ttq._i||{};
36              ttq._i[e]=[];
37              ttq._i[e]._u=i;
38              ttq._t=ttq._t||{};
39              ttq._t[e]=+new Date;
40              ttq._o=ttq._o||{};
41              ttq._o[e]=n||{};
42              var o=document.createElement("script");
43              o.type="text/javascript",o.async=!0,o.src=i+"?sdkid="+e+"&lib="+t;
44              var a=document.getElementsByTagName("script")[0];
45              a.parentNode.insertBefore(o,a)};
46            ttq.load('${pixelId}');
47            ttq.page();
48          }(window, document, 'ttq');
49        `,
50      }}
51    />
52  );
53}