How to Integrate Bolt.new with Facebook Ads

Go to developers.facebook.com and click 'My Apps' in the top-right, then 'Create App.' Select 'Other' as the use case, then 'Business' as the app type. Give your app a name, enter a contact email, and optionally associate it with a Business Manager. Click 'Create App' to complete creation. Once your app is created, you land on the App Dashboard. Click 'Add Product' and find 'Marketing API' — click 'Set Up.' This adds the Marketing API product to your app. In the left sidebar, you will now see Marketing API under your app's products. For development, the fastest way to get an access token is the Graph API Explorer. Go to developers.facebook.com/tools/explorer. At the top right, select your app from the dropdown. Click 'Generate Access Token' — this opens a permissions dialog. Select the permissions you need: `ads_read` for reading campaign data, `ads_management` for creating and modifying campaigns. Click 'Generate Access Token' and approve the permissions in the popup. The resulting token is a User Access Token that expires in one to two hours. For a long-lived token, click the information icon next to the token and select 'Extend Access Token' — this exchanges it for a 60-day token. For production use, you need a System User token (created in Business Manager under Users → System Users), which does not expire and does not require a logged-in Facebook user. Go to your Business Manager → Settings → Users → System Users → Create System User, then generate a token for that system user with the required permissions and assign it to your ad account. Copy the access token and your Ad Account ID (format: `act_XXXXXXXXXX`, found in Ads Manager URL or Business Manager). You will add both to your Bolt project's .env file.

1// lib/meta.ts
2const META_BASE_URL = 'https://graph.facebook.com/v20.0';
3
4interface MetaFetchOptions {
5  params?: Record<string, string>;
6  method?: 'GET' | 'POST' | 'DELETE';
7  body?: Record<string, unknown>;
8}
9
10export async function metaFetch<T = unknown>(
11  endpoint: string,
12  options: MetaFetchOptions = {}
13): Promise<T> {
14  const accessToken = process.env.META_ACCESS_TOKEN;
15  if (!accessToken) throw new Error('META_ACCESS_TOKEN is not configured');
16
17  const url = new URL(`${META_BASE_URL}/${endpoint}`);
18  if (options.params) {
19    Object.entries(options.params).forEach(([key, value]) => {
20      url.searchParams.set(key, value);
21    });
22  }
23
24  const response = await fetch(url.toString(), {
25    method: options.method || 'GET',
26    headers: {
27      Authorization: `Bearer ${accessToken}`,
28      'Content-Type': 'application/json',
29    },
30    body: options.body ? JSON.stringify(options.body) : undefined,
31  });
32
33  const data = await response.json() as { error?: { message: string; code: number } } & T;
34
35  if (!response.ok || data.error) {
36    throw new Error(data.error?.message || `Meta API error: ${response.status}`);
37  }
38
39  return data;
40}

The Marketing API's insights endpoint returns performance metrics for any ad object. You can request insights on a campaign (which aggregates all ad sets and ads beneath it), an ad set, or an individual ad. The endpoint pattern is: `/{ad-object-id}/insights` with a `fields` parameter listing the metrics you want and a `date_preset` or `time_range` parameter controlling the date window. The most commonly needed fields for a campaign dashboard are: `campaign_name`, `campaign_id`, `objective`, `status`, `spend`, `impressions`, `clicks`, `reach`, `frequency`, `cpm`, `cpc`, `ctr`, `cpp`, `actions` (conversions), `cost_per_action_type`, and `purchase_roas`. The `purchase_roas` field is an array of objects with value strings — you need to parse the float from the first element. The `actions` field is also an array that you filter for the action type you care about (e.g., `omni_purchase`, `lead`). To get insights for all campaigns in an ad account at once, request them from the ad account node with a `level=campaign` parameter: `/{ad-account-id}/insights?level=campaign&fields=...`. This returns all campaigns in one paginated response rather than requiring individual requests for each campaign ID. Date presets supported include: `today`, `yesterday`, `last_7d`, `last_14d`, `last_30d`, `last_month`, `this_month`, `last_quarter`, `this_year`. For custom date ranges, use `time_range={since:'2024-01-01',until:'2024-01-31'}` as a JSON string in the query parameter. The response is paginated with a `paging.next` URL for subsequent pages — for most dashboards fetching the first page of up to 25 campaigns is sufficient. The API route should accept query parameters for the date range, and optionally for filtering by campaign status (ACTIVE, PAUSED, DELETED). Return the campaigns array with parsed numeric values — the API returns spend and ROAS as strings, which should be converted to numbers for chart rendering.

1// app/api/facebook/campaigns/route.ts
2import { NextResponse } from 'next/server';
3import { metaFetch } from '@/lib/meta';
4
5const INSIGHTS_FIELDS = [
6  'campaign_name',
7  'campaign_id',
8  'objective',
9  'status',
10  'spend',
11  'impressions',
12  'clicks',
13  'reach',
14  'cpm',
15  'cpc',
16  'ctr',
17  'purchase_roas',
18  'actions',
19  'cost_per_action_type',
20].join(',');
21
22interface MetaInsight {
23  campaign_id: string;
24  campaign_name: string;
25  objective: string;
26  status?: string;
27  spend: string;
28  impressions: string;
29  clicks: string;
30  reach: string;
31  cpm: string;
32  cpc: string;
33  ctr: string;
34  purchase_roas?: Array<{ action_type: string; value: string }>;
35  actions?: Array<{ action_type: string; value: string }>;
36}
37
38export async function GET(request: Request) {
39  const { searchParams } = new URL(request.url);
40  const datePreset = searchParams.get('datePreset') || 'last_30d';
41  const status = searchParams.get('status') || 'ACTIVE';
42
43  const adAccountId = process.env.META_AD_ACCOUNT_ID;
44  if (!adAccountId) {
45    return NextResponse.json({ error: 'META_AD_ACCOUNT_ID is not configured' }, { status: 500 });
46  }
47
48  try {
49    const data = await metaFetch<{ data: MetaInsight[] }>(
50      `${adAccountId}/insights`,
51      {
52        params: {
53          level: 'campaign',
54          fields: INSIGHTS_FIELDS,
55          date_preset: datePreset,
56          filtering: JSON.stringify([{ field: 'campaign.delivery_info', operator: 'IN', value: [status] }]),
57          limit: '50',
58        },
59      }
60    );
61
62    const campaigns = (data.data || []).map((insight) => ({
63      id: insight.campaign_id,
64      name: insight.campaign_name,
65      objective: insight.objective,
66      spend: parseFloat(insight.spend || '0'),
67      impressions: parseInt(insight.impressions || '0', 10),
68      clicks: parseInt(insight.clicks || '0', 10),
69      reach: parseInt(insight.reach || '0', 10),
70      cpm: parseFloat(insight.cpm || '0'),
71      cpc: parseFloat(insight.cpc || '0'),
72      ctr: parseFloat(insight.ctr || '0'),
73      roas: insight.purchase_roas?.[0]
74        ? parseFloat(insight.purchase_roas[0].value)
75        : null,
76      purchases: insight.actions?.find((a) => a.action_type === 'omni_purchase')
77        ? parseInt(insight.actions.find((a) => a.action_type === 'omni_purchase')!.value, 10)
78        : 0,
79    }));
80
81    campaigns.sort((a, b) => b.spend - a.spend);
82
83    const totals = campaigns.reduce(
84      (acc, c) => ({
85        spend: acc.spend + c.spend,
86        impressions: acc.impressions + c.impressions,
87        clicks: acc.clicks + c.clicks,
88        purchases: acc.purchases + c.purchases,
89      }),
90      { spend: 0, impressions: 0, clicks: 0, purchases: 0 }
91    );
92
93    return NextResponse.json({ campaigns, totals, datePreset });
94  } catch (err) {
95    const message = err instanceof Error ? err.message : 'Failed to fetch campaigns';
96    return NextResponse.json({ error: message }, { status: 500 });
97  }
98}

With the API route returning structured data, build the React dashboard components that display it. A well-designed Facebook Ads dashboard typically has three sections: a summary header with total spend, total ROAS, and date range; a top-level metrics bar with impressions, clicks, CTR, and CPM; and a data table or card grid showing individual campaign performance. For ROAS (Return on Ad Spend), calculate it as total purchase revenue divided by total ad spend. The Marketing API returns ROAS as a multiplier — a value of 3.5 means every dollar spent returned $3.50 in revenue. Display it as '3.5x' with green coloring for values above 2x and red for below 1x. For campaigns without purchase tracking (awareness or traffic objectives), ROAS will be null — handle this gracefully by showing 'N/A'. The date range picker should offer preset options (Last 7 days, Last 30 days, Last quarter, This year) that map to Meta's date_preset values. When the user changes the date range, the component re-fetches data by updating the query parameter on the API route call. For charts, Recharts works well in Bolt-generated Next.js projects. A bar chart comparing spend across campaigns, a line chart showing daily spend trend (requires a separate sparklines API call with time_increment=1), and a scatter plot of CPC vs CTR for identifying efficient campaigns are all high-value visualizations. For the spend trend, use the same insights endpoint but add `time_increment=1` to get daily breakdowns instead of aggregated totals.

Creating campaigns via the Marketing API requires the `ads_management` permission in addition to `ads_read`. The creation flow involves three sequential API calls: create a Campaign object (the top-level container with objective and spending limits), create an Ad Set (targeting, budget, schedule, and bidding), and create an Ad (the creative that users actually see). Each step depends on the ID returned by the previous step. For the Campaign, the key fields are `name`, `objective` (OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_TRAFFIC, OUTCOME_AWARENESS, OUTCOME_ENGAGEMENT, OUTCOME_APP_PROMOTION), `status` (PAUSED is safest for initial creation), and optionally `special_ad_categories` (required if running housing, employment, or credit ads). Set status to PAUSED initially so you can review the campaign before it starts spending. The Ad Set specifies where and when the campaign runs and how much it spends. Key fields: `campaign_id` (from the campaign just created), `name`, `daily_budget` or `lifetime_budget` (in cents, so $50/day = 5000), `start_time` and `end_time` (ISO 8601 format), `targeting` (an object specifying geo, age, interests, behaviors), `billing_event` (IMPRESSIONS is standard), and `optimization_goal` (OFFSITE_CONVERSIONS for purchase tracking, LINK_CLICKS for traffic). The targeting object has many fields. A minimal targeting object includes `geo_locations` (countries array, e.g., `{countries: ['US']}`), `age_min` (18-65), and `age_max` (18-65). Interest-based targeting uses `flexible_spec` with interest IDs that you look up via the Targeting Search API. For a working MVP, use broad targeting with just geo and age — detailed interest targeting can be added later. Important: the Meta Marketing API performs validation and may return errors for budget minimums (typically $1/day minimum), missing required fields, or campaigns in restricted categories. Always handle the error response and display Meta's error message directly — it is usually specific and actionable.

1// app/api/facebook/create-campaign/route.ts
2import { NextResponse } from 'next/server';
3import { metaFetch } from '@/lib/meta';
4
5export async function POST(request: Request) {
6  const adAccountId = process.env.META_AD_ACCOUNT_ID;
7  if (!adAccountId) {
8    return NextResponse.json({ error: 'META_AD_ACCOUNT_ID is not configured' }, { status: 500 });
9  }
10
11  const {
12    name,
13    objective = 'OUTCOME_TRAFFIC',
14    dailyBudgetCents = 500, // $5.00
15    targetCountries = ['US'],
16    ageMin = 18,
17    ageMax = 65,
18  } = await request.json();
19
20  try {
21    // Step 1: Create Campaign
22    const campaign = await metaFetch<{ id: string }>(
23      `${adAccountId}/campaigns`,
24      {
25        method: 'POST',
26        body: {
27          name,
28          objective,
29          status: 'PAUSED', // Always start paused
30          special_ad_categories: [],
31        },
32      }
33    );
34
35    // Step 2: Create Ad Set
36    const startTime = new Date();
37    startTime.setHours(startTime.getHours() + 1);
38
39    const adSet = await metaFetch<{ id: string }>(
40      `${adAccountId}/adsets`,
41      {
42        method: 'POST',
43        body: {
44          campaign_id: campaign.id,
45          name: `${name} - Ad Set`,
46          daily_budget: dailyBudgetCents,
47          billing_event: 'IMPRESSIONS',
48          optimization_goal: 'LINK_CLICKS',
49          bid_strategy: 'LOWEST_COST_WITHOUT_CAP',
50          targeting: {
51            geo_locations: { countries: targetCountries },
52            age_min: ageMin,
53            age_max: ageMax,
54          },
55          start_time: startTime.toISOString(),
56          status: 'PAUSED',
57        },
58      }
59    );
60
61    return NextResponse.json({
62      success: true,
63      campaignId: campaign.id,
64      adSetId: adSet.id,
65      message: `Campaign "${name}" created with status PAUSED. Add creatives before activating.`,
66    });
67  } catch (err) {
68    const message = err instanceof Error ? err.message : 'Campaign creation failed';
69    return NextResponse.json({ error: message }, { status: 500 });
70  }
71}

During development in Bolt's WebContainer, all outbound Marketing API calls work correctly — you can read campaign data and test the dashboard with real numbers. The one integration feature that requires deployment is webhook-based data: Lead Ads form submissions and real-time event notifications use Meta's webhook system, which sends POST requests to your server. Since the WebContainer cannot receive incoming connections, these webhooks only function after deployment. Deploy to Netlify via Settings → Applications → Connect Netlify, or use Bolt Cloud (click Publish). After deployment, go to your Netlify or Bolt Cloud dashboard and add environment variables: `META_ACCESS_TOKEN` and `META_AD_ACCOUNT_ID` with your production values. For production use with other users' ad accounts (building a multi-tenant dashboard), your Meta App must go through App Review. In Meta for Developers, under your app, go to App Review → Permissions and Features. Request the `ads_read` permission (and `ads_management` if you need write access). You must provide a screencast demonstrating your integration, a privacy policy URL, and a business verification. Meta typically completes review in two to four weeks. Without App Review, your app can only access data for users who have a role in your Meta App (developers, testers, admins). For a single-tenant dashboard (your own ad account only), App Review is not required. Use a System User token from Business Manager, which does not require any end-user OAuth flow and does not expire. This is the production-ready approach for internal tools and agency dashboards accessing specific accounts with explicit permission.

1# Environment variables to add in Netlify dashboard or Bolt Cloud
2# Settings → Environment Variables (Netlify) or Secrets (Bolt Cloud)
3
4META_ACCESS_TOKEN=EAAxxxxxxxxxxxxxxxxxx
5META_AD_ACCOUNT_ID=act_1234567890
6
7# Optional: restrict to specific ad account for security
8# NEXT_PUBLIC_APP_URL=https://your-app.netlify.app