Skip to main content

​
Overview

Connecting Snapchat Ads lets the dashboard:
  • Create, update, pause, resume, and delete campaigns and ad squads (Snap’s term for ad sets).
  • Upload image and video media into the connected ad account and bind them into creatives.
  • Create and manage ads that reference a creative plus an ad squad.
  • Pull spend, impressions, swipes, and conversion metrics from the campaign stats endpoint.
  • Run creative experiments by rotating multiple ad squads under one campaign.
The integration uses the Snap Marketing API v1 with OAuth 2.0 authentication and refresh tokens.

​
Prerequisites

Before connecting, make sure you have:
  1. An active Snapchat Business account with at least one organization and one ad account.
  2. The role of Admin or Campaign Manager on the ad account so OAuth can mint tokens with write scope.
  3. An OAuth 2.0 application configured for the dashboard’s redirect URI. The client_id and client_secret are set on the platform side as SNAPCHAT_ADS_CLIENT_ID and SNAPCHAT_ADS_CLIENT_SECRET.

​
OAuth scope

The connection requests a single scope: 
snapchat-marketing-api
This scope covers all read and write operations on campaigns, ad squads, ads, creatives, media, and stats.

​
Connect

  1. Open the Paid UA → Integrations page in the dashboard.
  2. Click Connect on the Snapchat Ads tile.
  3. Sign in with the Snap account that has access to your organization’s ad accounts.
  4. Approve the requested scope.
  5. After redirect, the dashboard exchanges the auth code for tokens and probes /me/organizations followed by /organizations/{id}/adaccounts to confirm access and capture the ad account ids.
Access tokens are rotated automatically before expiry using the refresh token.

​
What happens behind the scenes

OperationAPI endpoint
List organizations the user can accessGET /me/organizations
List ad accounts under an organizationGET /organizations/{id}/adaccounts
Create / list campaignsPOST / GET /adaccounts/{id}/campaigns
Update / pause / resume campaignPUT /adaccounts/{id}/campaigns (body wrapped in { campaigns: [...] })
Delete campaignDELETE /campaigns/{id}
Create / update ad squadsPOST / PUT /adaccounts/{id}/adsquads
Create / update adsPOST / PUT /adaccounts/{id}/ads
Upload mediaPOST /adaccounts/{id}/media
Create creativePOST /adaccounts/{id}/creatives
Pull statsGET /campaigns/{id}/stats?granularity=DAY&fields=...
Snap wraps create / update bodies in collection arrays ({ campaigns: [...] }, { adsquads: [...] }, { ads: [...] }, { creatives: [...] }, { media: [...] }). The integration handles this transparently. Every write request carries an Idempotency-Key HTTP header so retries do not produce duplicate resources, even if the platform connection drops mid-request.

​
Budget conversion

Snap budgets are stored in micro-currency (1 USD = 1,000,000 micros). The dashboard sends USD values in its DTOs and converts to micros (Math.round(amount_usd * 1_000_000)) before the request lands. Pause / resume operations send { status: 'PAUSED' | 'ACTIVE' }.

​
Rate limiting

Requests are throttled per (client_id, ad_account_id) using a sliding window built on Redis. The default budget is 50 requests per second per ad account. If the platform reports HTTP 429, the request is automatically retried with exponential backoff. If Redis is unavailable, the rate limiter fails closed and the request is reported as a quota error to the autonomous-growth runner — preventing accidental over-quota fan-out under outage.

​
Reporting

Metrics are pulled hourly (or on demand) from /campaigns/{id}/stats with granularity=DAY and the standard Snap field set (spend, impressions, swipes, view_completion, conversion_purchases). Spend is converted from native currency to USD on ingestion. The native currency, the FX rate used, and the local-currency spend are kept alongside the USD value for downstream analytics.

​
Experiments (multi-ad-squad rotation)

The dashboard maps experiment variants onto multiple ad squads under a single campaign, with each variant carrying its own targeting and creative reference. The control variant ships active; treatments ship paused until the experiment runner toggles them. Per-variant performance is read back from the stats endpoint with breakdown=adsquad_id.

​
Dry-run mode

While integrating with Snap, write operations are guarded by an environment flag so they can be exercised end-to-end without touching the production ad account. With SNAPCHAT_ADS_LIVE_MODE unset, every write returns a synthetic mock id; the network is never reached. Set SNAPCHAT_ADS_LIVE_MODE=true once you are ready to push real campaign mutations.

​
Disconnect

Click Disconnect on the integration tile. The OAuth refresh token is removed from the dashboard. To fully revoke access, also remove the third-party app authorisation from your Snapchat Business connected-apps list.

​
Troubleshooting

  • “Snapchat Ads /me returned 401” — the OAuth token has been revoked or has expired without a valid refresh token. Re-connect the integration.
  • “Snapchat Ads create_campaign: 429 — …” — your ad account’s per-second API quota was breached. The dashboard backs off automatically; if the error persists, lower campaign-mutation frequency.
  • “webhooks not supported on snapchat_ads” — Snap’s Marketing API does not expose webhooks. State changes (ad disapproved, daily cap hit, account suspended) are detected via the hourly metrics-sync job.
  • Synthetic / mock ids returned in production — the platform is running in dry-run mode. Ask your administrator to set SNAPCHAT_ADS_LIVE_MODE=true.
  • creative_id references a missing creative — Snap’s ad references creatives by id. Make sure to upload media first (upload_media), then create the creative (create_creative), and finally create the ad with the resulting creative_id bound on it.