How to Integrate Retool with Pinterest Ads

Before setting up the Retool resource, you need a Pinterest Developer App with Marketing API access. Log in to the Pinterest Developer portal at app.pinterest.com/business/apps and click Create App. Fill in the app name (e.g., 'Retool Analytics'), description, and website URL. Enable the Marketing API access type — this requires your Pinterest business account to be verified and in good standing. In the App settings, navigate to the Authentication tab and configure OAuth 2.0: add the Redirect URI as https://login.retool.com/oauth/consumer (for Retool Cloud, or your self-hosted Retool URL + /oauth/consumer). Note your Client ID and Client Secret from the App Details page. Pinterest Marketing API requires the following OAuth scopes for ads management: ads:read (for campaign and ad data), catalogs:read (for shopping catalog data), and pins:read (for Pin analytics). If you need to create or modify campaigns from Retool, also request ads:write. Store your Pinterest credentials as Retool configuration variables: go to Retool Settings → Configuration Variables and create PINTEREST_CLIENT_ID and PINTEREST_CLIENT_SECRET (both marked as Secret).

Navigate to the Resources tab in your Retool instance and click Add Resource. Select REST API from the list of resource types. Name the resource 'Pinterest Ads API'. In the Base URL field, enter https://api.pinterest.com. Pinterest Marketing API endpoints use version prefixes — you'll include /v5/ in each query path rather than the base URL, giving you flexibility to use different API versions per query if needed. For Authentication, select OAuth 2.0 from the dropdown. Configure the OAuth fields as follows: - Grant Type: Authorization Code - Client ID: {{ retoolContext.configVars.PINTEREST_CLIENT_ID }} - Client Secret: {{ retoolContext.configVars.PINTEREST_CLIENT_SECRET }} - Authorization URL: https://www.pinterest.com/oauth - Access Token URL: https://api.pinterest.com/v5/oauth/token - Scope: ads:read catalogs:read pins:read (space-separated) - Access Token Lifespan: 86400 (24 hours for standard tokens) In the Default Headers section, add: Key = Content-Type, Value = application/json. Click Save Changes and then 'Connect OAuth account' to complete the OAuth flow. You'll be redirected to Pinterest's authorization page to grant the app access to your ads account.

Start by fetching the ad accounts available to your Pinterest user. Create a query named getAdAccounts, set Method to GET, and set the path to /v5/ad_accounts. This returns all ad accounts the authenticated Pinterest user has access to, including the ad account ID needed for all subsequent campaign queries. Create a Dropdown component named dropdown_adAccount and bind its options to {{ getAdAccounts.data.items.map(acc => ({ label: acc.name, value: acc.id })) }}. Configure getAdAccounts to run on page load. Next, create a query named getCampaigns to fetch campaigns for the selected ad account. Set Method to GET and path to /v5/ad_accounts/{{ dropdown_adAccount.value }}/campaigns. Add URL parameters: Key = campaign_status, Value = ACTIVE,PAUSED (comma-separated list). The response includes campaign IDs, names, objectives, status, and basic metadata. For campaign performance metrics, create getCampaignAnalytics with Method GET and path to /v5/ad_accounts/{{ dropdown_adAccount.value }}/campaigns/analytics. Add URL parameters: Key = campaign_ids, Value = {{ getCampaigns.data.items.map(c => c.id).join(',') }}, Key = start_date, Value = {{ dateRange.start.toISOString().split('T')[0] }}, Key = end_date, Value = {{ dateRange.end.toISOString().split('T')[0] }}, Key = columns, Value = SPEND_IN_DOLLAR,IMPRESSION_1,CLICKTHROUGH_1,CTR_2,CPC_IN_DOLLAR,TOTAL_CONVERSIONS,TOTAL_CONVERSION_VALUE_IN_MICRO_DOLLAR.

1// JavaScript transformer — merge campaign list with analytics data
2const campaigns = getCampaigns.data?.items || [];
3const analytics = getCampaignAnalytics.data || [];
4
5// Build analytics lookup by campaign ID
6const analyticsMap = {};
7analytics.forEach(item => {
8  const id = item.CAMPAIGN_ID;
9  if (!analyticsMap[id]) analyticsMap[id] = { spend: 0, impressions: 0, clicks: 0, conversions: 0, convValue: 0 };
10  const m = analyticsMap[id];
11  m.spend += parseFloat(item.SPEND_IN_DOLLAR || 0);
12  m.impressions += parseInt(item.IMPRESSION_1 || 0);
13  m.clicks += parseInt(item.CLICKTHROUGH_1 || 0);
14  m.conversions += parseInt(item.TOTAL_CONVERSIONS || 0);
15  m.convValue += parseFloat((item.TOTAL_CONVERSION_VALUE_IN_MICRO_DOLLAR || 0) / 1000000);
16});
17
18return campaigns.map(campaign => {
19  const a = analyticsMap[campaign.id] || {};
20  const spend = a.spend || 0;
21  const convValue = a.convValue || 0;
22  const clicks = a.clicks || 0;
23  const impressions = a.impressions || 0;
24  return {
25    id: campaign.id,
26    name: campaign.name || 'Unnamed',
27    status: campaign.status,
28    objective: campaign.objective_type || 'N/A',
29    spend: `$${spend.toFixed(2)}`,
30    impressions: impressions.toLocaleString(),
31    clicks: clicks.toLocaleString(),
32    ctr: impressions > 0 ? `${((clicks / impressions) * 100).toFixed(2)}%` : '0%',
33    cpc: clicks > 0 ? `$${(spend / clicks).toFixed(2)}` : 'N/A',
34    conversions: a.conversions || 0,
35    conv_value: `$${convValue.toFixed(2)}`,
36    roas: spend > 0 ? `${(convValue / spend).toFixed(2)}x` : 'N/A'
37  };
38});

Create queries to drill down from campaign-level to ad group and Pin-level performance. When a user selects a campaign row in the campaigns table, trigger ad group queries for that specific campaign. Create getAdGroups with Method GET and path /v5/ad_accounts/{{ dropdown_adAccount.value }}/ad_groups. Add URL parameter: Key = campaign_ids, Value = {{ table_campaigns.selectedRow.id }}. This returns all ad groups within the selected campaign. For ad group analytics, create getAdGroupAnalytics with Method GET and path /v5/ad_accounts/{{ dropdown_adAccount.value }}/ad_groups/analytics. Add URL parameters matching the campaigns analytics query but with ad_group_ids instead of campaign_ids. Create getAds to retrieve individual promoted Pins: Method GET, path /v5/ad_accounts/{{ dropdown_adAccount.value }}/ads, URL parameter: Key = campaign_ids, Value = {{ table_campaigns.selectedRow.id }}. This returns Pin-level data including the Pin ID and creative details. Add a second Table component named table_adGroups bound to the ad group analytics transformer output. Set its onRowClick event to trigger getAds filtered by the selected ad group ID. The resulting Pins table can show Pin thumbnail URLs (displayed using an Image column type in Retool's Table component) alongside impressions, clicks, and saves per Pin.

1// JavaScript transformer — format ad group analytics
2const adGroups = getAdGroups.data?.items || [];
3const analytics = getAdGroupAnalytics.data || [];
4
5const analyticsMap = {};
6analytics.forEach(item => {
7  const id = item.AD_GROUP_ID;
8  if (!analyticsMap[id]) analyticsMap[id] = {
9    spend: 0, impressions: 0, clicks: 0, conversions: 0
10  };
11  analyticsMap[id].spend += parseFloat(item.SPEND_IN_DOLLAR || 0);
12  analyticsMap[id].impressions += parseInt(item.IMPRESSION_1 || 0);
13  analyticsMap[id].clicks += parseInt(item.CLICKTHROUGH_1 || 0);
14  analyticsMap[id].conversions += parseInt(item.TOTAL_CONVERSIONS || 0);
15});
16
17return adGroups.map(group => {
18  const a = analyticsMap[group.id] || {};
19  const spend = a.spend || 0;
20  const impressions = a.impressions || 0;
21  const clicks = a.clicks || 0;
22  return {
23    id: group.id,
24    name: group.name || 'Unnamed',
25    status: group.status,
26    bid_type: group.bid_type || 'N/A',
27    budget: group.budget_in_micro_currency
28      ? `$${(group.budget_in_micro_currency / 1000000).toFixed(2)}`
29      : 'N/A',
30    spend: `$${spend.toFixed(2)}`,
31    impressions: impressions.toLocaleString(),
32    clicks: clicks.toLocaleString(),
33    ctr: impressions > 0
34      ? `${((clicks / impressions) * 100).toFixed(2)}%`
35      : '0%',
36    conversions: a.conversions || 0
37  };
38});

Build visualization components to surface performance trends over time. Pinterest's analytics endpoints return daily data points when queried with a date range, making them ideal for time-series charts. Create a query named getDailySpendTrend with the campaign analytics endpoint, but request granular=DAY data by adding URL parameter: Key = granularity, Value = DAY. This returns one row per campaign per day, which you can aggregate into a time-series format for Retool's Chart component. Create a JavaScript transformer that converts the daily analytics array into a format suitable for Retool's Chart: group data by date and calculate total spend, impressions, and clicks across all selected campaigns per day. Add a Chart component to your app. Set its data property to {{ dailySpendTransformer.data }}. Configure it as a Line chart with Date as the X-axis and Spend as the Y-axis. Add a second data series for Clicks on a secondary Y-axis to show the spend vs. engagement correlation over time. Add a date range picker (DateRange component) to control the analytics window. Wire it to both the getCampaignAnalytics and getDailySpendTrend queries via the URL parameters. Set both queries to trigger on change of the date range selector. For comparing performance across different time periods (e.g., current month vs. last month), create a second set of analytics queries with a separate date range and display both datasets in the same chart using different line colors.

1// JavaScript transformer — format daily analytics for line chart
2const dailyData = data || [];
3
4// Group by date
5const byDate = {};
6dailyData.forEach(item => {
7  const date = item.DATE; // YYYY-MM-DD format
8  if (!byDate[date]) {
9    byDate[date] = { date, spend: 0, impressions: 0, clicks: 0, conversions: 0 };
10  }
11  byDate[date].spend += parseFloat(item.SPEND_IN_DOLLAR || 0);
12  byDate[date].impressions += parseInt(item.IMPRESSION_1 || 0);
13  byDate[date].clicks += parseInt(item.CLICKTHROUGH_1 || 0);
14  byDate[date].conversions += parseInt(item.TOTAL_CONVERSIONS || 0);
15});
16
17// Sort by date and return array
18return Object.values(byDate)
19  .sort((a, b) => new Date(a.date) - new Date(b.date))
20  .map(row => ({
21    date: new Date(row.date).toLocaleDateString('en-US', { month: 'short', day: 'numeric' }),
22    spend: parseFloat(row.spend.toFixed(2)),
23    impressions: row.impressions,
24    clicks: row.clicks,
25    conversions: row.conversions,
26    ctr: row.impressions > 0
27      ? parseFloat(((row.clicks / row.impressions) * 100).toFixed(2))
28      : 0
29  }));