How to Integrate Bolt.new with Reddit Ads

Reddit Ads API access requires two separate steps: creating an OAuth app at the Reddit developer portal, and separately requesting Ads API access through Reddit's business help center. This two-step requirement trips up most developers who assume creating a developer app is sufficient. First, go to reddit.com/prefs/apps and scroll to the bottom. Click 'Create App' or 'Create another app.' Choose the app type: select 'web app' for production use (supports OAuth 2.0 with refresh tokens), or 'script' for personal use with a single Reddit account (simpler but limited to your own account). Give your app a name and description. For the redirect URI, enter `https://localhost:3000/auth/callback` for initial setup — you will update this to your production URL after deployment. Copy your app's client ID (shown below the app name, looks like a random string) and generate a client secret (click 'edit' on the app to see the secret). These are your OAuth 2.0 credentials. Second, request Ads API access at business.reddithelp.com/helpcenter/s/contactsupport. Select 'Advertiser' as your issue type and explain your use case. Reddit manually reviews API access requests, with approval typically taking three to seven business days. While waiting for API access approval, you can build the dashboard frontend and API route structure using mock data. Once approved, Reddit will email your Ads account ID (format: `t2_xxxxxxxx`) and confirm your app has been granted Ads API permissions. Add your credentials to Bolt's .env file to proceed.

1// lib/reddit.ts
2const REDDIT_ADS_BASE = 'https://ads-api.reddit.com/api/v2.1';
3
4interface RedditFetchOptions {
5  params?: Record<string, string>;
6  method?: 'GET' | 'POST' | 'PATCH' | 'DELETE';
7  body?: Record<string, unknown>;
8}
9
10export async function redditFetch<T = unknown>(
11  endpoint: string,
12  options: RedditFetchOptions = {}
13): Promise<T> {
14  const accessToken = process.env.REDDIT_ACCESS_TOKEN;
15  if (!accessToken) throw new Error('REDDIT_ACCESS_TOKEN is not configured');
16
17  const url = new URL(`${REDDIT_ADS_BASE}/${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      'User-Agent': 'BoltApp/1.0',
30    },
31    body: options.body ? JSON.stringify(options.body) : undefined,
32  });
33
34  if (!response.ok) {
35    const errorText = await response.text();
36    throw new Error(`Reddit Ads API error ${response.status}: ${errorText}`);
37  }
38
39  return response.json() as Promise<T>;
40}
41
42export async function refreshRedditToken(): Promise<string> {
43  const credentials = Buffer.from(
44    `${process.env.REDDIT_CLIENT_ID}:${process.env.REDDIT_CLIENT_SECRET}`
45  ).toString('base64');
46
47  const response = await fetch('https://www.reddit.com/api/v1/access_token', {
48    method: 'POST',
49    headers: {
50      Authorization: `Basic ${credentials}`,
51      'Content-Type': 'application/x-www-form-urlencoded',
52      'User-Agent': 'BoltApp/1.0',
53    },
54    body: new URLSearchParams({
55      grant_type: 'refresh_token',
56      refresh_token: process.env.REDDIT_REFRESH_TOKEN || '',
57    }),
58  });
59
60  const data = await response.json() as { access_token?: string; error?: string };
61  if (data.error || !data.access_token) {
62    throw new Error(`Token refresh failed: ${data.error}`);
63  }
64  return data.access_token;
65}

Reddit uses OAuth 2.0 for all Ads API access. The token flow depends on your app type. For 'script' apps (single Reddit account access), you can use the password grant to obtain tokens without a redirect flow — ideal for building personal or internal dashboards without deploying first. For 'web app' type (multi-user access), you need the authorization code flow with a redirect URI, which requires a deployed URL. For script apps: send a POST request to `https://www.reddit.com/api/v1/access_token` with Basic Auth using your client ID and secret, and a body with `grant_type=password`, `username=your-reddit-username`, and `password=your-reddit-password`. The response includes `access_token` (valid for one hour) and a `refresh_token` for renewal. For web apps (multi-user): construct an authorization URL pointing to `https://www.reddit.com/api/v1/authorize` with query params `client_id`, `response_type=code`, `state=random-string`, `redirect_uri=your-deployed-url/auth/callback`, `duration=permanent`, and `scope=ads:read ads:write`. After the user approves, Reddit redirects to your callback URL with a `code` parameter. Exchange this code for tokens via a POST to the token endpoint. The `duration=permanent` parameter is critical — it requests a refresh token that lets you obtain new access tokens indefinitely without re-authorization. For the refresh token obtained during initial setup, add it to your .env as `REDDIT_REFRESH_TOKEN`. When the access token expires (after one hour), your API route calls the refresh endpoint using the client credentials and refresh token to obtain a new access token. Build this refresh logic directly into your API routes so token expiry is handled transparently without manual intervention.

1// app/api/reddit/refresh/route.ts
2import { NextResponse } from 'next/server';
3
4export async function POST() {
5  const clientId = process.env.REDDIT_CLIENT_ID;
6  const clientSecret = process.env.REDDIT_CLIENT_SECRET;
7  const refreshToken = process.env.REDDIT_REFRESH_TOKEN;
8
9  if (!clientId || !clientSecret || !refreshToken) {
10    return NextResponse.json(
11      { error: 'Reddit credentials not configured' },
12      { status: 500 }
13    );
14  }
15
16  const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
17
18  const response = await fetch('https://www.reddit.com/api/v1/access_token', {
19    method: 'POST',
20    headers: {
21      Authorization: `Basic ${credentials}`,
22      'Content-Type': 'application/x-www-form-urlencoded',
23      'User-Agent': 'BoltApp/1.0',
24    },
25    body: new URLSearchParams({
26      grant_type: 'refresh_token',
27      refresh_token: refreshToken,
28    }),
29  });
30
31  const data = await response.json() as {
32    access_token?: string;
33    expires_in?: number;
34    error?: string;
35  };
36
37  if (!response.ok || data.error) {
38    return NextResponse.json(
39      { error: data.error || 'Token refresh failed' },
40      { status: 401 }
41    );
42  }
43
44  return NextResponse.json({
45    accessToken: data.access_token,
46    expiresIn: data.expires_in,
47  });
48}

Reddit's Ads API organizes campaigns in a three-level hierarchy: Campaigns (top-level objectives), Ad Groups (targeting and bidding), and Ads (creatives). Performance data is fetched via dedicated reporting endpoints rather than embedded in the campaign objects themselves. This separation means you typically need two API calls: one to fetch campaigns list and one to fetch their performance metrics. The campaigns endpoint is `GET /accounts/{account_id}/campaigns` and returns campaign metadata including name, status, objective, and budget configuration. The reporting endpoint for performance metrics is typically `GET /accounts/{account_id}/reports` with date range and breakdown parameters. Key metrics available include impressions, clicks, conversions, spend, CPM, CPC, CTR, and video views for video ads. Reddit Ads has unique metrics that differ from other platforms. The `ecpm` (effective CPM) reflects actual auction-clearing prices, and Reddit also provides `video_watched_75_percent` and `video_complete_views` for video creatives. The `reddit_engagement` metric counts post upvotes, comments, and shares that organic Reddit users take on your promoted posts — a metric unique to the platform that reflects content quality beyond click performance. For date ranges, the reporting API accepts ISO 8601 date strings for `start_time` and `end_time`. The granularity parameter controls whether you get aggregated totals or daily breakdowns — use `TOTAL` for summary cards and `DAY` for trend charts. A practical detail: Reddit's Ads API returns monetary values in microdollars (1,000,000 microdollars = $1.00). Divide all spend values by 1,000,000 before displaying them. This is different from Meta's API (which uses dollars as strings) and Stripe (which uses cents).

1// app/api/reddit/campaigns/route.ts
2import { NextResponse } from 'next/server';
3import { redditFetch } from '@/lib/reddit';
4
5interface RedditCampaign {
6  id: string;
7  name: string;
8  status: string;
9  objective: string;
10  daily_budget_in_cents?: number;
11  total_budget_in_cents?: number;
12}
13
14interface RedditReportRow {
15  id: string;
16  impressions: number;
17  clicks: number;
18  spend: number; // microdollars
19  ecpm: number;
20  ecpc: number;
21  ctr: number;
22  conversions?: number;
23}
24
25export async function GET(request: Request) {
26  const { searchParams } = new URL(request.url);
27  const startDate = searchParams.get('startDate') ||
28    new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
29  const endDate = searchParams.get('endDate') ||
30    new Date().toISOString().split('T')[0];
31
32  const accountId = process.env.REDDIT_ACCOUNT_ID;
33  if (!accountId) {
34    return NextResponse.json({ error: 'REDDIT_ACCOUNT_ID is not configured' }, { status: 500 });
35  }
36
37  try {
38    const [campaignsData, reportsData] = await Promise.all([
39      redditFetch<{ data: RedditCampaign[] }>(
40        `accounts/${accountId}/campaigns`,
41        { params: { limit: '100' } }
42      ),
43      redditFetch<{ data: RedditReportRow[] }>(
44        `accounts/${accountId}/reports`,
45        {
46          params: {
47            entity: 'campaign',
48            fields: 'impressions,clicks,spend,ecpm,ecpc,ctr,conversions',
49            date_start: startDate,
50            date_end: endDate,
51            granularity: 'TOTAL',
52          },
53        }
54      ),
55    ]);
56
57    const metricsMap = new Map<string, RedditReportRow>();
58    (reportsData.data || []).forEach((row) => {
59      metricsMap.set(row.id, row);
60    });
61
62    const campaigns = (campaignsData.data || []).map((campaign) => {
63      const metrics = metricsMap.get(campaign.id);
64      return {
65        id: campaign.id,
66        name: campaign.name,
67        status: campaign.status,
68        objective: campaign.objective,
69        dailyBudget: campaign.daily_budget_in_cents
70          ? campaign.daily_budget_in_cents / 100
71          : null,
72        impressions: metrics?.impressions ?? 0,
73        clicks: metrics?.clicks ?? 0,
74        spend: metrics ? metrics.spend / 1_000_000 : 0,
75        cpm: metrics ? metrics.ecpm / 1_000_000 : 0,
76        cpc: metrics ? metrics.ecpc / 1_000_000 : 0,
77        ctr: metrics?.ctr ?? 0,
78        conversions: metrics?.conversions ?? 0,
79      };
80    });
81
82    campaigns.sort((a, b) => b.spend - a.spend);
83
84    const totals = campaigns.reduce(
85      (acc, c) => ({
86        spend: acc.spend + c.spend,
87        impressions: acc.impressions + c.impressions,
88        clicks: acc.clicks + c.clicks,
89        conversions: acc.conversions + c.conversions,
90      }),
91      { spend: 0, impressions: 0, clicks: 0, conversions: 0 }
92    );
93
94    return NextResponse.json({ campaigns, totals, dateRange: { startDate, endDate } });
95  } catch (err) {
96    const message = err instanceof Error ? err.message : 'Failed to fetch Reddit campaigns';
97    return NextResponse.json({ error: message }, { status: 500 });
98  }
99}

Reddit Ads dashboards benefit from surfacing community-specific context that standard ad platform dashboards omit. Beyond the usual spend, clicks, and CTR metrics, Reddit advertisers care about which subreddit communities drove the best performance and how organic Reddit engagement (upvotes, comments) on promoted posts compares across creatives. For the dashboard layout, organize it as: a top summary row with total spend, total clicks, average CTR, and total conversions; a campaign table with sortable columns; and a secondary section showing performance by subreddit community when ad group data is available. The community breakdown is where Reddit Ads insight differs most from other platforms — seeing that r/personalfinance converts at 3x the rate of r/news for your financial product is the kind of insight that reshapes your entire targeting strategy. For date range selection, Reddit's API accepts specific ISO date strings, so build a date range picker with presets (Last 7 days, Last 30 days, Last 90 days) that compute the correct ISO strings. Use the same pattern as the Facebook Ads dashboard for the React date picker component — this consistency makes users comfortable across your multi-platform analytics app. For the campaign status display, Reddit campaigns have statuses including ACTIVE, PAUSED, COMPLETED, DRAFT, and SCHEDULED. Color-code these clearly: green for ACTIVE, yellow for PAUSED, gray for COMPLETED, and blue for SCHEDULED. The DRAFT status indicates campaigns that have been created but not yet submitted for review — these are important to surface separately since they are not yet spending. Charts that work well for Reddit Ads: a horizontal bar chart ranking campaigns by spend (same as other ad platforms), a scatter plot comparing CTR vs CPC to identify efficient subreddit targeting, and a conversion funnel chart from impressions to clicks to conversions.

During development in Bolt's WebContainer, outbound calls to Reddit's Ads API work correctly for fetching campaign data. The constraint is OAuth 2.0 callback handling — when you build a multi-user app where different advertisers can connect their Reddit Ads accounts, the OAuth redirect URL must point to a stable HTTPS server. Bolt's WebContainer preview URL (`webcontainer-api.io` subdomain) changes and cannot receive the OAuth callback reliably. Deploy to Netlify via Settings → Applications → Connect Netlify, or click Publish to deploy to Bolt Cloud. After deployment, you will have a stable URL like `https://your-app.netlify.app`. Update your Reddit developer app at reddit.com/prefs/apps to add the production redirect URI: `https://your-app.netlify.app/api/reddit/auth/callback`. In your hosting dashboard (Netlify environment variables or Bolt Cloud secrets), add the production values: `REDDIT_CLIENT_ID`, `REDDIT_CLIENT_SECRET`, `REDDIT_ACCESS_TOKEN`, `REDDIT_REFRESH_TOKEN`, and `REDDIT_ACCOUNT_ID`. These should be your production credentials, not the development placeholders from your .env file. For building a SaaS product where multiple advertisers connect their Reddit Ads accounts, you need a proper token storage system. Each user's access token and refresh token must be stored in your database (Supabase or similar), associated with their user ID, and retrieved per-request. The single-token approach in .env only works for single-account access. Build the multi-tenant flow after validating the single-account integration works end-to-end in production.

1# Production environment variables — add in Netlify Dashboard or Bolt Cloud Secrets
2# Never commit these values to your git repository
3
4REDDIT_CLIENT_ID=your_client_id_here
5REDDIT_CLIENT_SECRET=your_client_secret_here
6REDDIT_ACCESS_TOKEN=your_access_token_here
7REDDIT_REFRESH_TOKEN=your_refresh_token_here
8REDDIT_ACCOUNT_ID=t2_your_account_id
9
10# Redirect URI registered in Reddit developer app settings:
11# https://your-app.netlify.app/api/reddit/auth/callback