# Ads Spotify

> Set up Spotify Ads Manager with the Spotify Pixel, Ads API v3 OAuth, Conversions API, custom and lookalike audiences, and reporting diagnostics. Use when wiring Spotify page-view, lead, signup, checkout, purchase, or audience tracking, debugging missing conversions, or validating a small Ads API test.

- Skill: `pooriaarab/ads-spotify` (Agent Skill)
- Install (CLI): `npx skillmds@latest add pooriaarab/ads-spotify`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pooriaarab/ads-spotify/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: pooriaarab (https://skillmd.com/u/pooriaarab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pooriaarab/ads-spotify

---


# Spotify Ads

Spotify Ads Manager exposes Ads API v3 for campaign management, measurement, audiences, and reporting. It also provides a browser Pixel and a tagless Conversions API (CAPI). See the [Ads API overview](https://developer.spotify.com/documentation/ads-api) and [Ads API guides](https://developer.spotify.com/documentation/ads-api/guides).

Use [ad-conversion-hub](../ad-conversion-hub/SKILL.md) for the canonical event envelope, consent gate, identity rules, retry policy, and adapter contract.
Pair it with [ad-experiments](../ad-experiments/SKILL.md) for one-audience tests, seed sizing, PII-export authorization, and payment-provider truth.

## Account and access

Spotify requires a Spotify account and an Ads Manager account for Ads API use. Create a Spotify for Developers application, select Ads API, and accept the Ads API Terms with its client ID. Spotify says allowlisting can take up to one hour after terms acceptance. See the [Ads API Quickstart](https://developer.spotify.com/documentation/ads-api/quick-start).

Ads API authentication uses OAuth 2.0. The authorization request uses `https://accounts.spotify.com/authorize/` with `client_id`, `response_type=code`, and `redirect_uri`; exchange the code at `https://accounts.spotify.com/api/token`. The returned bearer token expires in one hour and includes a refresh token. See the [OAuth Quickstart](https://developer.spotify.com/documentation/ads-api/quick-start).

The Ads API uses `https://api-partner.spotify.com/ads/v3/` for management calls. The current documentation lists v3 as the most recent version and says v2 was sunset on August 5, 2025. See the [Ads API release notes](https://developer.spotify.com/documentation/ads-api).

Spotify documents no environment-variable names. Its examples use `<ACCESS_TOKEN>`, `<ADS_API_ACCESS_TOKEN>`, and `<CAPI_ACCESS_TOKEN>` placeholders. Map those values to the hub's server-only secret convention. See the [Quickstart](https://developer.spotify.com/documentation/ads-api/quick-start) and [CAPI guide](https://developer.spotify.com/documentation/ads-api/guides).

For a no-spend integration test, create an ad account with `test_account_type: "NO_DELIVERY_NO_BILLING"`. Spotify says test and production accounts use the same endpoint, and this field distinguishes them. See the [test-account guide](https://developer.spotify.com/documentation/ads-api/guides).

## Client-side Spotify Pixel

Create a Pixel with `POST /businesses/{business_id}/pixels`. Its required fields are `domain` and `name`; the domain accepts only HTTP or HTTPS schemes. The response returns the Pixel `id` and `integration_id`. See [Create pixel](https://developer.spotify.com/documentation/ads-api/reference/v3.0/createPixelInBusiness).

Use the code generated by Spotify Ads Manager or Spotify Ad Analytics. Spotify's technical guide loads `https://pixel.byspotify.com/ping.min.js`, configures the Pixel key, and calls `spdt('view')`. Install the base script before the end body tag on at least three pages; Spotify recommends every page. See the [Pixel installation guide](https://help.adanalytics.spotify.com/technical-pixel-docs).

```html
<script>
  (function(w, d) {
    var id = 'spdt-capture';
    if (!d.getElementById(id)) {
      w.spdt = w.spdt || function() { (w.spdt.q = w.spdt.q || []).push(arguments); };
      var e = d.createElement('script'); e.id = id; e.async = 1;
      e.src = 'https://pixel.byspotify.com/ping.min.js';
      d.getElementsByTagName('script')[0].parentNode.insertBefore(e, d.getElementsByTagName('script')[0]);
    }
    w.spdt('conf', { key: '<SPOTIFY_PIXEL_ID>' }); w.spdt('view');
  })(window, document);
</script>
```

Spotify's Pixel event scripts support Alias, Lead, Product, Add to cart, Checkout, and Purchase. Put an event script after the base script on the page where the action occurs. See [Pixel event scripts](https://help.adanalytics.spotify.com/technical-pixel-docs).

For purchase tracking, the documented Pixel fields include `value`, `currency`, `discount_code`, `order_id`, and `is_new_customer`. Spotify also documents optional `quantity` and `line_items` fields. See [Purchase event fields](https://help.adanalytics.spotify.com/technical-pixel-docs).

## Rule setup and event mapping

Create one measurement dataset for the sources that should report together. Create a CAPI integration with `POST /businesses/{business_id}/capi`, passing `name` and `dataset_id`. The response returns a `capi_connection_id`. See [Create CAPI Integration](https://developer.spotify.com/documentation/ads-api/reference/v3.0/createCapiIntegration) and [Create Dataset](https://developer.spotify.com/documentation/ads-api/reference/v3.0/createDataset).

Use the event spelling in Spotify's CAPI submission guide. The integration response model displays some received names without underscores, such as `CHECKOUT` and `ADDTOCART`; do not silently substitute those response labels when constructing requests. See the [CAPI request fields](https://developer.spotify.com/documentation/ads-api/guides) and [integration response fields](https://developer.spotify.com/documentation/ads-api/reference/v3.0/createCapiIntegration).

| Hub event | Spotify Pixel | Spotify CAPI | Send when |
|---|---|---|---|
| `page_view` | `view` | `VIEW` | A meaningful page loads. [Pixel](https://help.adanalytics.spotify.com/technical-pixel-docs) · [CAPI](https://developer.spotify.com/documentation/ads-api/guides) |
| `view_content` | `product` | `PRODUCT` | A product or plan is viewed. [Pixel](https://help.adanalytics.spotify.com/technical-pixel-docs) · [CAPI](https://developer.spotify.com/documentation/ads-api/guides) |
| `lead` | `lead` | `LEAD` | A qualified lead completes. [Pixel](https://help.adanalytics.spotify.com/technical-pixel-docs) · [CAPI](https://developer.spotify.com/documentation/ads-api/guides) |
| `signup` | No documented matching Pixel event | `SIGN_UP` | Account creation completes. [Pixel](https://help.adanalytics.spotify.com/technical-pixel-docs) · [CAPI](https://developer.spotify.com/documentation/ads-api/guides) |
| `begin_checkout` | `checkout` | `CHECK_OUT` | Checkout begins. [Pixel](https://help.adanalytics.spotify.com/technical-pixel-docs) · [CAPI](https://developer.spotify.com/documentation/ads-api/guides) |
| `purchase` | `purchase` | `PURCHASE` | The payment provider confirms the charge. [Pixel](https://help.adanalytics.spotify.com/technical-pixel-docs) · [CAPI](https://developer.spotify.com/documentation/ads-api/guides) |
| `refund` | No documented event | No documented event | Reconcile with payment truth. [Pixel events](https://help.adanalytics.spotify.com/technical-pixel-docs) · [CAPI event values](https://developer.spotify.com/documentation/ads-api/guides) |

The published Pixel event list and CAPI request values contain no refund event. Keep `refund` in first-party reconciliation only. See [Pixel events](https://help.adanalytics.spotify.com/technical-pixel-docs) and [CAPI event values](https://developer.spotify.com/documentation/ads-api/guides).

## Server-side conversions API

Create the CAPI connection in Ads Manager under **Events → Connect Data Source → Conversions API**, or create it through the Ads API. Spotify assigns a UUID `capi_connection_id` to the connection. See the [CAPI setup guide](https://developer.spotify.com/documentation/ads-api/guides) and [Create CAPI Integration](https://developer.spotify.com/documentation/ads-api/reference/v3.0/createCapiIntegration).

Generate the CAPI token in the same Ads Manager flow, or call `GET /businesses/{business_id}/capi/{capi_connection_id}/tokens` with the Ads API bearer token. Spotify says CAPI tokens differ from Ads API tokens, do not expire, and allow up to three active tokens. See [CAPI auth tokens](https://developer.spotify.com/documentation/ads-api/guides) and [Get CAPI Auth Token(s)](https://developer.spotify.com/documentation/ads-api/reference/v3.0/getCapiAuthTokens).

Send events to the documented endpoint:

```http
POST https://capi.spotify.com/capi-direct/events/
Authorization: Bearer <CAPI_ACCESS_TOKEN>
Content-Type: application/json
```

Use this request envelope:

```json
{
  "conversion_events": {
    "capi_connection_id": "<CAPI_CONNECTION_ID>",
    "events": [{
      "event_name": "PURCHASE",
      "event_id": "<CANONICAL_EVENT_ID>",
      "event_time": "2026-08-29T12:34:56.000Z",
      "user_data": {
        "hashed_emails": ["<SHA256_EMAIL>"],
        "hashed_phone_number": "<SHA256_PHONE>"
      },
      "event_details": {
        "currency": "USD",
        "amount": 100.0
      },
      "action_source": "WEB",
      "event_source_url": "https://example.com/confirmation"
    }]
  }
}
```

Spotify requires `capi_connection_id`, `event_name`, `event_id`, `event_time`, and `user_data`. The event time uses an ISO 8601 timestamp, and the guide recommends UTC. See the [CAPI request schema](https://developer.spotify.com/documentation/ads-api/guides).

The documented event names are `VIEW`, `PRODUCT`, `CHECK_OUT`, `ADD_TO_CART`, `PURCHASE`, `LEAD`, `SIGN_UP`, and `CUSTOM_EVENT_1` through `CUSTOM_EVENT_5`. Optional fields include `event_details`, `event_source_url`, `action_source`, and `opt_out_targeting`. See the [CAPI request fields](https://developer.spotify.com/documentation/ads-api/guides).

## Identity and consent

Spotify CAPI accepts IP address, device ID, hashed email, and hashed phone
identifiers. At least one identifier is required. Spotify recommends including
IP address and device ID when possible. See the [CAPI identity guidance](https://developer.spotify.com/documentation/ads-api/guides).

Normalize before hashing: trim and lowercase email, and reduce phone to
E.164 digits only (strip spaces, punctuation, and leading zeros, keep the
country code). Hash each with SHA-256 and send the result in `hashed_emails`
or `hashed_phone_number`; do not send raw values.
See the [CAPI best practices](https://developer.spotify.com/documentation/ads-api/guides).

Require the hub's measurement consent before sending Pixel or CAPI events.
Require its ad-data consent before sending identifiers or customer-list data.
The hub owns normalization, consent, retries, and deletion rules. See
[ad-conversion-hub](../ad-conversion-hub/SKILL.md).

Set `opt_out_targeting` to `true` when Spotify may use the event for attribution
but must not use it for retargeting. Spotify documents `WEB`, `APP`, and
`OFFLINE` as `action_source` values. See the [CAPI optional fields](https://developer.spotify.com/documentation/ads-api/guides).

## Click ID and first-party cookie

Spotify documents the Pixel first-party cookie as `__spdt`; `pdst` is the
legacy name. The FAQ says the cookie lasts 12 months and stores the Pixel ID.
It also says the Pixel can send events without storing or accessing that cookie
when first-party cookies are disabled. See the [Spotify Pixel FAQ](https://adshelp.spotify.com/HelpCenter/s/article/Spotify-Pixel-FAQs-AU?language=en_AU).

The Pixel and CAPI pages opened for this skill do not define a Spotify-owned click-ID query parameter or attribution-window value. Do not invent one. If the campaign supplies approved UTM or campaign-code values, capture them as your own first-party fields under the hub convention. See the [Pixel guide](https://help.adanalytics.spotify.com/technical-pixel-docs) and [CAPI guide](https://developer.spotify.com/documentation/ads-api/guides).

## Deduplication

Spotify's CAPI guide requires a unique `event_id` and recommends it when the
same event also arrives through the browser Pixel. Use the hub's stable event
ID for CAPI `event_id`. See the [CAPI request fields](https://developer.spotify.com/documentation/ads-api/guides).

Spotify's Pixel purchase script uses `order_id` for backend matching. Map the
same stable transaction identifier to Pixel `order_id` and CAPI `event_id` when
the purchase event represents one transaction. See [Pixel purchase fields](https://help.adanalytics.spotify.com/technical-pixel-docs)
and [CAPI deduplication guidance](https://developer.spotify.com/documentation/ads-api/guides).

Do not create a new ID on retry. Persist the dispatch record and let the hub's
retry policy govern transport failures. See [ad-conversion-hub](../ad-conversion-hub/SKILL.md).

## Audience and retargeting

Spotify supports custom and lookalike audiences. Create a customer-list upload with `POST /ad_accounts/{ad_account_id}/audiences/upload_url`; Spotify returns an audience ID and signed upload URL for a CSV. Then call Create Audience with that ID in `audience_ids`. See the [custom-audience guide](https://developer.spotify.com/documentation/ads-api/guides) and [Create Audience](https://developer.spotify.com/documentation/ads-api/reference/v3.0/createAudience).

Custom audience subtypes include `CUSTOMER_LIST`, `WEB_EVENT`, `AD_ENGAGEMENT`,
and `LIVERAMP`. Web-event audiences support lookback values of 30, 60, 90, or
180 days. Lookalike audiences use a `seed_audience_id`. See [Create Audience](https://developer.spotify.com/documentation/ads-api/reference/v3.0/createAudience).

Spotify says an uploaded audience can take up to three days to become
`BOOKABLE`. An audience in `LIVE` use cannot be deleted. Check status before
attaching it to an ad set. See the [custom-audience guide](https://developer.spotify.com/documentation/ads-api/guides).

## Ads Manager settings that override code

Set `aam_opt_in` deliberately on the Pixel. When it is false, Spotify says no
advanced-matching fields are used, even if `aam_fields` contains values. The
documented fields include `EMAIL`, `PHONE`, `FIRST_NAME`, `LAST_NAME`, `CITY`,
`STATE`, `ZIP`, `COUNTRY`, and `EXTERNAL_ID`. See [Create pixel](https://developer.spotify.com/documentation/ads-api/reference/v3.0/createPixelInBusiness).

Check `cookie_opt_in` on the Pixel or dataset. When false, Spotify says no
first-party cookies are used for tracking. See [Get pixel by ID](https://developer.spotify.com/documentation/ads-api/reference/v3.0/getPixelById)
and [Get Dataset](https://developer.spotify.com/documentation/ads-api/reference/v3.0/getDatasetById).

Attach the correct `dataset_id` to the Pixel and CAPI integration. The dataset
response exposes its Pixel, CAPI integration, event receipt state, and shared
ad accounts. See [Get Dataset](https://developer.spotify.com/documentation/ads-api/reference/v3.0/getDatasetById).

Keep `opt_out_targeting` aligned with the event's permitted use. A true value
allows attribution but excludes retargeting, according to Spotify's CAPI guide.
See the [CAPI optional fields](https://developer.spotify.com/documentation/ads-api/guides).

## Verification

First, verify request proof in redacted server logs. A successful HTTP response
shows transport acceptance; it does not by itself prove campaign attribution.

Next, call `GET /businesses/{business_id}/datasets/{dataset_id}/diagnostics`.
Request `DAILY` or `HOURLY` granularity and inspect `PIXEL` and `CAPI` data
sources, event counts, and `last_activity_ms`. See [Dataset diagnostics](https://developer.spotify.com/documentation/ads-api/reference/v3.0/getDiagnosticsByDatasetId).

For CAPI, call `GET /businesses/{business_id}/capi/{capi_connection_id}`.
Inspect `events_received` and each event type's `first_event_time`. See [Get CAPI Integration](https://developer.spotify.com/documentation/ads-api/reference/v3.0/getCapiIntegrationById).

For the Pixel, call `GET /businesses/{business_id}/pixels/{pixel_id}`.
Inspect configured events, historical events, `events_received`, and
`cookie_opt_in`. See [Get pixel by ID](https://developer.spotify.com/documentation/ads-api/reference/v3.0/getPixelById).

For campaign proof, call `GET /ad_accounts/{ad_account_id}/aggregate_reports`
with fields such as `PAGE_VIEWS`, `LEADS`, `PURCHASES`, and `REVENUE`. Spotify
also provides aggregate totals, insight reports, and asynchronous CSV reports.
See [Aggregate Report](https://developer.spotify.com/documentation/ads-api/reference/v3.0/getAggregateReport),
[Insight Report](https://developer.spotify.com/documentation/ads-api/reference/v3.0/getAudienceInsightReport),
and [CSV Report](https://developer.spotify.com/documentation/ads-api/reference/v3.0/createAsyncReport).

Reconcile platform totals with payment-provider succeeded charges and first-party
events. Investigate any mismatch by separating Pixel delivery, CAPI receipt,
audience readiness, and campaign attribution.

## Common pitfalls and security

- Use Ads API v3 management endpoints, not the sunset v2 surface. See the [Ads API release notes](https://developer.spotify.com/documentation/ads-api).
- Keep the short-lived Ads API bearer token separate from the long-lived CAPI token. See the [Quickstart](https://developer.spotify.com/documentation/ads-api/quick-start) and [CAPI guide](https://developer.spotify.com/documentation/ads-api/guides).
- Send the CAPI envelope under `conversion_events`; do not post to an invented `/conversions` endpoint. See the [CAPI setup guide](https://developer.spotify.com/documentation/ads-api/guides).
- Do not use raw email or phone values. Normalize, hash with SHA-256, and apply hub consent first. See [CAPI best practices](https://developer.spotify.com/documentation/ads-api/guides) and [ad-conversion-hub](../ad-conversion-hub/SKILL.md).
- Do not treat `events_received`, Pixel activity, or a report row as proof of payment. Reconcile with payment-provider truth.
- Do not assume a Spotify click ID or attribution window. The opened [Pixel](https://help.adanalytics.spotify.com/technical-pixel-docs) and [CAPI](https://developer.spotify.com/documentation/ads-api/guides) docs do not define one.
- Do not attach an audience while its status is `PROCESSING`, `EMPTY`, or `LEARNING`. Confirm `BOOKABLE` first. See [audience status](https://developer.spotify.com/documentation/ads-api/reference/v3.0/createAudience).
- Keep Ads API client secrets, bearer tokens, CAPI tokens, hashed identifiers, and audience files server-side. Never place them in browser bundles, URLs, logs, screenshots, or commits.
- Use HTTPS for event source URLs and vendor endpoints. Redact credentials and identifiers in diagnostics and support requests.

## Official sources checked (2026-08-29)

- [Ads API overview](https://developer.spotify.com/documentation/ads-api) · [Quickstart](https://developer.spotify.com/documentation/ads-api/quick-start) · [Guides](https://developer.spotify.com/documentation/ads-api/guides)
- [Create pixel](https://developer.spotify.com/documentation/ads-api/reference/v3.0/createPixelInBusiness) · [Get pixel](https://developer.spotify.com/documentation/ads-api/reference/v3.0/getPixelById) · [Pixel installation](https://help.adanalytics.spotify.com/technical-pixel-docs) · [Pixel FAQ](https://adshelp.spotify.com/HelpCenter/s/article/Spotify-Pixel-FAQs-AU?language=en_AU)
- [Create CAPI integration](https://developer.spotify.com/documentation/ads-api/reference/v3.0/createCapiIntegration) · [CAPI tokens](https://developer.spotify.com/documentation/ads-api/reference/v3.0/getCapiAuthTokens) · [Dataset diagnostics](https://developer.spotify.com/documentation/ads-api/reference/v3.0/getDiagnosticsByDatasetId)
- [Create audience](https://developer.spotify.com/documentation/ads-api/reference/v3.0/createAudience) · [Get dataset](https://developer.spotify.com/documentation/ads-api/reference/v3.0/getDatasetById) · [Aggregate report](https://developer.spotify.com/documentation/ads-api/reference/v3.0/getAggregateReport) · [Insight report](https://developer.spotify.com/documentation/ads-api/reference/v3.0/getAudienceInsightReport) · [CSV report](https://developer.spotify.com/documentation/ads-api/reference/v3.0/createAsyncReport)