Snapchat Marketing
Follow this guide to set up the Snapchat Marketing source connector.
Prerequisites
For Airbyte Cloud:
- A Snapchat Business account with access to the Snapchat Marketing API
For Airbyte Open Source:
- A Snapchat Business account with access to the Snapchat Marketing API
- Client ID
- Client Secret
- Refresh Token
Set up the connector
Step 1: Set up Snapchat
For Airbyte Open Source:
-
Create an OAuth2 app in the Snap Business Manager:
- Provide a
redirect_uri. If you don’t have an endpoint for the OAuth callback, use any valid URL. See this discussion for details. - Save the Client ID and Client Secret.
- Provide a
-
Get a refresh token through the OAuth2 authorization code flow:
-
Open the authorize link in your browser:
https://accounts.snapchat.com/login/oauth2/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=snapchat-marketing-api&state=wmKkg0TWgppW8PTBZ20sldUwerf-m -
Log in and authorise the app.
-
Copy the
codequery parameter from the redirect URL. -
Exchange the code for tokens:
curl -X POST \ -d "code={one_time_use_code}" \ -d "client_id={client_id}" \ -d "client_secret={client_secret}" \ -d "grant_type=authorization_code" \ -d "redirect_uri={redirect_uri}" \ https://accounts.snapchat.com/login/oauth2/access_token
Use the response’s
refresh_tokenwhen you configure the connector.See the Snapchat authentication documentation for more details.
-
Step 2: Set up the source connector in Airbyte
For Airbyte Cloud:
- Log into your Airbyte Cloud account.
- Select Sources from the left navigation bar. Then, select + new source in the top-right corner.
- Select Snapchat Marketing from the Source type dropdown. Then, enter a name for this connector.
- Select Authenticate your account.
- Log in and authorise access to your Snapchat account.
- (Optional) Enter a Start Date in
YYYY-MM-DDformat. Only data created on or after this date is synced. The default is2022-01-01.
:::tip
Start Date is required for every stats stream using start_time as a key. See the supported streams table below.
:::
- (Optional) Enter an End Date in
YYYY-MM-DDformat. Only data created on or before this date is synced. Leave it blank to sync through today. - (Optional) Choose the Action Report Time. This determines whether conversions are reported at the time of
conversion(default) orimpression. - (Optional) Choose the Swipe Up Attribution Window. Options:
1_DAY,7_DAY,28_DAY(default). - (Optional) Choose the View Attribution Window. Options:
none,1_HOUR,3_HOUR,6_HOUR,1_DAY(default),7_DAY. - (Optional) Enter Organization IDs to sync only specific organizations. Leave it blank to sync every organization available to the authenticated user.
- (Optional) Enter Ad Account IDs to sync only specific ad accounts. Leave it blank to include every ad account under the synced organizations.
- Select Set up source.
For Airbyte Open Source:
- Open the Airbyte UI.
- Select Sources from the left navigation bar. Then, select + new source in the top-right corner.
- Select Snapchat Marketing from the Source type dropdown. Then, enter a name for this connector.
- Enter the Client ID, Client Secret, and Refresh Token from Step 1.
- (Optional) Enter a Start Date in
YYYY-MM-DDformat. Only data created on or after this date is synced. The default is2022-01-01.
:::tip
Start Date is required for every stats stream using start_time as a key. See the supported streams table below.
:::
- (Optional) Enter an End Date in
YYYY-MM-DDformat. Only data created on or before this date is synced. - (Optional) Choose the Action Report Time. This determines whether conversions are reported at the time of
conversion(default) orimpression. - (Optional) Choose the Swipe Up Attribution Window. Options:
1_DAY,7_DAY,28_DAY(default). - (Optional) Choose the View Attribution Window. Options:
none,1_HOUR,3_HOUR,6_HOUR,1_DAY(default),7_DAY. - (Optional) Enter Organization IDs to sync only specific organizations. Leave it blank to sync every organization available to the authenticated user.
- (Optional) Enter Ad Account IDs to sync only specific ad accounts. Leave it blank to include every ad account under the synced organizations.
- Select Set up source.
Supported streams and sync modes
| Stream | Incremental | Key |
|---|---|---|
| AdAccounts | Yes | id |
| Ads | Yes | id |
| AdSquads | Yes | id |
| Campaigns | Yes | id |
| Creatives | Yes | id |
| Media | Yes | id |
| Organizations | Yes | id |
| Segments | Yes | id |
| AdAccounts_Stats_Hourly | Yes | id, granularity, start_time |
| AdAccounts_Stats_Daily | Yes | id, granularity, start_time |
| AdAccounts_Stats_Lifetime | No | id, granularity |
| Ads_Stats_Hourly | Yes | id, granularity, start_time |
| Ads_Stats_Daily | Yes | id, granularity, start_time |
| Ads_Stats_Lifetime | No | id, granularity |
| AdSquads_Stats_Hourly | Yes | id, granularity, start_time |
| AdSquads_Stats_Daily | Yes | id, granularity, start_time |
| AdSquads_Stats_Lifetime | No | id, granularity |
| Campaigns_Stats_Hourly | Yes | id, granularity, start_time |
| Campaigns_Stats_Daily | Yes | id, granularity, start_time |
| Campaigns_Stats_Lifetime | No | id, granularity |
Start Date and End Date filter records in the Organizations and Ad Accounts streams. They don’t control which organizations and ad accounts other streams read from. For example, the Ad Accounts stream excludes an ad account last updated before the Start Date. However, its campaigns and ad account stats are still synced. If a connection missed data for some organizations or ad accounts before version 1.6.11, refresh the affected streams to backfill their history.
Stats stream metrics
Stats streams flatten Snapchat’s nested stats object. This makes each metric a top-level field in the record.
Spend metrics are reported in micro-currency. Divide the value by 1,000,000 to convert it into whole currency units. This applies to spend, coupon_used_local, and coupon_used_usd. coupon_used_local uses the currency assigned to the ad account. coupon_used_usd is always in US dollars.
Coupon fields are available only in the Ads, AdSquads, and Campaigns stats streams. They were added in version 1.6.0-rc.1, the release candidate for 1.6.0. The three AdAccounts stats streams return only spend. Snapchat’s ad account stats endpoint rejects requests for any other metric.
Performance considerations
The Snapchat Marketing API limits requests to 20 per second for each app. It also limits requests to 10 per second for each access token. The connector automatically retries HTTP 429 responses with backoff.
Each page can contain up to 1,000 items.
Hourly stats stream granularity creates large data volumes and takes longer to sync. Daily granularity is recommended unless you need hour-level breakdowns.
IP allow list
If you use Airbyte Cloud and restrict your organization’s access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.
Changelog
Expand to review
| Version | Date | Pull Request | Subject |
|---|---|---|---|
| 1.6.12 | 2026-11-10 | 91723 | Update dependencies |
| 1.6.11 | 2026-11-05 | 89027 | Read every organization and ad account as a parent, so Start Date and End Date no longer empty the streams under them |
| 1.6.10 | 2026-11-04 | 90345 | Simplify error handler configuration with no change in behavior |
| 1.6.9 | 2026-11-03 | 90759 | Update dependencies |
| 1.6.8 | 2026-10-27 | 90055 | Update dependencies |
| 1.6.7 | 2026-10-21 | 89614 | Report not-found organization and ad account IDs as configuration errors with actionable messages |
| 1.6.6 | 2026-10-20 | 89417 | Update dependencies |
| 1.6.5 | 2026-10-13 | 88812 | Update dependencies |
| 1.6.4 | 2026-10-06 | 88076 | Update dependencies |
| 1.6.3 | 2026-09-29 | 87377 | Update dependencies |
| 1.6.2 | 2026-09-22 | 86830 | Update dependencies |
| 1.6.1 | 2026-09-15 | 85692 | Update dependencies |
| 1.6.0 | 2026-09-09 | 85759 | Promoted release candidate to GA |
| 1.6.0-rc.1 | 2026-08-24 | 76912 | Add coupon_used_local and coupon_used_usd spend fields to ads, ad squads, and campaigns stats streams |
| 1.5.47 | 2026-08-18 | 84742 | Update dependencies |
| 1.5.46 | 2026-08-11 | 84121 | Update dependencies |
| 1.5.45 | 2026-08-04 | 83618 | Update dependencies |
| 1.5.44 | 2026-07-28 | 83091 | Update dependencies |
| 1.5.43 | 2026-07-21 | 82576 | Update dependencies |
| 1.5.42 | 2026-07-14 | 82015 | Update dependencies |
| 1.5.41 | 2026-06-30 | 81242 | Update dependencies |
| 1.5.40 | 2026-06-23 | 80650 | Update dependencies |
| 1.5.39 | 2026-06-17 | 80208 | Fix OAuth re-authentication failure caused by masked client_id/client_secret in consent URL |
| 1.5.38 | 2026-06-16 | 80030 | Update dependencies |
| 1.5.37 | 2026-06-09 | 79506 | Update dependencies |
| 1.5.36 | 2026-06-02 | 78950 | Update dependencies |
| 1.5.35 | 2026-05-26 | 74289 | Add none option to view_attribution_window enum to support disabling view attribution tracking |
| 1.5.34 | 2026-04-28 | 76758 | Update dependencies |
| 1.5.33 | 2026-04-24 | 77006 | Promoted release candidate to GA |
| 1.5.33-rc.5 | 2026-04-23 | 76950 | Re-enable api_budget at 100/10s with concurrency 4 for tuning iteration 5 |
| 1.5.33-rc.4 | 2026-04-21 | 76875 | Revert to concurrency 4 without api_budget for tuning iteration 4 |
| 1.5.33-rc.3 | 2026-04-16 | 76416 | Increase api_budget from 80 to 100 calls per 10s for tuning iteration 3 |
| 1.5.33-rc.2 | 2026-04-13 | 76255 | Increase default_concurrency to 5 for tuning iteration 2 |
| 1.5.33-rc.1 | 2026-04-10 | 70866 | Add HTTPAPIBudget and concurrency_level for progressive rollout tuning |
| 1.5.32 | 2026-03-24 | 75098 | Update dependencies |
| 1.5.31 | 2026-03-10 | 74573 | Update dependencies |
| 1.5.30 | 2026-03-03 | 72736 | Update dependencies |
| 1.5.29 | 2026-02-24 | 73634 | fix(source-snapchat-marketing): add lookback_window P2D to mitigate UTC timezone mismatch (AI-Triage PR) |
| 1.5.28 | 2026-01-20 | 70672 | Update dependencies |
| 1.5.27 | 2025-11-25 | 70083 | Update dependencies |
| 1.5.26 | 2025-11-18 | 69489 | Update dependencies |
| 1.5.25 | 2025-10-29 | 68815 | Update dependencies |
| 1.5.24 | 2025-10-22 | 68591 | Add suggestedStreams |
| 1.5.23 | 2025-10-21 | 68234 | Update dependencies |
| 1.5.22 | 2025-10-14 | 67746 | Update dependencies |
| 1.5.21 | 2025-10-07 | 67447 | Update dependencies |
| 1.5.20 | 2025-09-30 | 66898 | Update dependencies |
| 1.5.19 | 2025-09-24 | 66264 | Update dependencies |
| 1.5.18 | 2025-09-09 | 65393 | Update dependencies |
| 1.5.17 | 2025-08-18 | 64940 | Re-release connector with fixed docker image entrypoint |
| 1.5.16 | 2025-08-11 | 63276 | Fix start time for stats streams |
| 1.5.15 | 2025-08-10 | 64480 | Update dependencies |
| 1.5.14 | 2025-07-26 | 63088 | Update dependencies |
| 1.5.13 | 2025-07-02 | 62488 | Fix end datetime to include today |
| 1.5.12 | 2025-06-28 | 60513 | Update dependencies |
| 1.5.11 | 2025-05-10 | 60113 | Update dependencies |
| 1.5.10 | 2025-05-04 | 59625 | Update dependencies |
| 1.5.9 | 2025-04-27 | 58395 | Update dependencies |
| 1.5.8 | 2025-04-12 | 57957 | Update dependencies |
| 1.5.7 | 2025-04-05 | 57412 | Update dependencies |
| 1.5.6 | 2025-03-29 | 56907 | Update dependencies |
| 1.5.5 | 2025-03-22 | 56300 | Update dependencies |
| 1.5.4 | 2025-03-08 | 55595 | Update dependencies |
| 1.5.3 | 2025-03-01 | 54546 | Update dependencies |
| 1.5.2 | 2025-02-15 | 54091 | Update dependencies |
| 1.5.1 | 2025-02-08 | 53569 | Update dependencies |
| 1.5.0 | 2024-11-26 | 44170 | Added Optional filters - Organization & Ad Account IDs |
| 1.4.2 | 2025-02-01 | 53083 | Update dependencies |
| 1.4.1 | 2025-01-25 | 52403 | Update dependencies |
| 1.4.0 | 2025-01-23 | 52110 | Make incremental per-partition streams concurrent |
| 1.3.7 | 2025-01-18 | 51999 | Update dependencies |
| 1.3.6 | 2025-01-11 | 51431 | Update dependencies |
| 1.3.5 | 2024-12-28 | 50796 | Update dependencies |
| 1.3.4 | 2024-12-21 | 50308 | Update dependencies |
| 1.3.3 | 2024-12-14 | 49414 | Update dependencies |
| 1.3.2 | 2024-11-05 | 48375 | Re-implement advanced_auth in connector spec |
| 1.3.1 | 2024-10-29 | 47837 | Update dependencies |
| 1.3.0 | 2024-10-15 | 46927 | Promoting release candidate 1.3.0-rc.1 to a main version. |
| 1.3.0-rc.1 | 2024-10-08 | 46570 | Migrate to Manifest-only |
| 1.2.12 | 2024-10-12 | 46800 | Update dependencies |
| 1.2.11 | 2024-10-05 | 46419 | Update dependencies |
| 1.2.10 | 2024-09-28 | 46106 | Update dependencies |
| 1.2.9 | 2024-09-21 | 45780 | Update dependencies |
| 1.2.8 | 2024-09-14 | 45477 | Update dependencies |
| 1.2.7 | 2024-09-07 | 45278 | Update dependencies |
| 1.2.6 | 2024-08-31 | 44998 | Update dependencies |
| 1.2.5 | 2024-08-24 | 44735 | Update dependencies |
| 1.2.4 | 2024-08-17 | 43859 | Update dependencies |
| 1.2.3 | 2024-08-12 | 43826 | Fixed the bug with the missing spend field to supported *_stats_* streams |
| 1.2.2 | 2024-08-10 | 43539 | Update dependencies |
| 1.2.1 | 2024-08-03 | 43174 | Update dependencies |
| 1.2.0 | 2024-07-31 | 42010 | Migrate to CDK v4.1.0 |
| 1.1.2 | 2024-07-27 | 42680 | Update dependencies |
| 1.1.1 | 2024-07-20 | 42366 | Update dependencies |
| 1.1.0 | 2024-07-16 | 42009 | Migrate to CDK v2.4.0 |
| 1.0.3 | 2024-07-13 | 41855 | Update dependencies |
| 1.0.2 | 2024-07-10 | 41547 | Update dependencies |
| 1.0.1 | 2024-07-09 | 40132 | Update dependencies |
| 1.0.0 | 2024-06-20 | 39507 | Migrate to low-code CDK and add incremental functionality to organizations |
| 0.6.2 | 2024-05-22 | 38574 | Update authenticator package |
| 0.6.1 | 2024-04-24 | 36662 | Schema descriptions |
| 0.6.0 | 2024-04-10 | 30586 | Add attribution_windows,action_report_time as optional configurable params |
| 0.5.0 | 2024-03-19 | 36267 | Pin airbyte-cdk version to ^0 |
| 0.4.0 | 2024-02-27 | 35660 | Add new fields to streams ads, adsquads, creatives, and media |
| 0.3.2 | 2024-02-12 | 35171 | Manage dependencies with Poetry. |
| 0.3.1 | 2024-02-12 | 35170 | Adopt the Airbyte Python base image |
| 0.3.0 | 2023-05-22 | 26358 | Remove deprecated authSpecification in favour of advancedAuth |
| 0.2.0 | 2023-05-10 | 25948 | Introduce new field in the Campaigns stream schema |
| 0.1.16 | 2023-04-20 | 20897 | Add missing fields to Basic Stats schema |
| 0.1.15 | 2023-03-02 | 22869 | Specified date formatting in specification |
| 0.1.14 | 2023-02-10 | 22808 | Enable default AvailabilityStrategy |
| 0.1.13 | 2023-01-27 | 22023 | Set AvailabilityStrategy for streams explicitly to None |
| 0.1.12 | 2023-01-11 | 21267 | Fix parse empty error response |
| 0.1.11 | 2022-12-23 | 20865 | Handle 403 permission error |
| 0.1.10 | 2022-12-15 | 20537 | Run on CDK 0.15.0 |
| 0.1.9 | 2022-12-14 | 20498 | Fix output state when no records are read |
| 0.1.8 | 2022-10-05 | 17596 | Retry 429 and 5xx errors when refreshing access token |
| 0.1.6 | 2022-07-21 | 14924 | Remove additionalProperties field from specs |
| 0.1.5 | 2022-07-13 | 14577 | Added stats streams hourly, daily, lifetime |
| 0.1.4 | 2021-12-07 | 8429 | Update titles and descriptions |
| 0.1.3 | 2021-11-10 | 7811 | Add oauth2.0, fix stream_state |
| 0.1.2 | 2021-11-08 | 7499 | Remove base-python dependencies |
| 0.1.1 | 2021-07-29 | 5072 | Fix bug with incorrect stream_state value |
| 0.1.0 | 2021-07-26 | 4843 | Initial release supporting the Snapchat Marketing API |