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 and Ads API guides.

Use ad-conversion-hub for the canonical event envelope, consent gate, identity rules, retry policy, and adapter contract. Pair it with ad-experiments 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.

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.

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.

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 and CAPI guide.

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.

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.

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.

<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.

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.

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 and Create Dataset.

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 and integration response fields.

The published Pixel event list and CAPI request values contain no refund event. Keep refund in first-party reconciliation only. See Pixel events and CAPI event values.

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 and Create CAPI Integration.

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 and Get CAPI Auth Token(s).

Send events to the documented endpoint:

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

Use this request envelope:

{
  "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.

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.

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.

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.

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.

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.

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.

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 and CAPI guide.

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.

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 and CAPI deduplication guidance.

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.

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 and Create Audience.

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.

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.

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.

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 and Get Dataset.

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.

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.

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.

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.

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.

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, Insight Report, and CSV Report.

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.
• Keep the short-lived Ads API bearer token separate from the long-lived CAPI token. See the Quickstart and CAPI guide.
• Send the CAPI envelope under conversion_events; do not post to an invented /conversions endpoint. See the CAPI setup guide.
• Do not use raw email or phone values. Normalize, hash with SHA-256, and apply hub consent first. See CAPI best practices and ad-conversion-hub.
• 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 and CAPI docs do not define one.
• Do not attach an audience while its status is PROCESSING, EMPTY, or LEARNING. Confirm BOOKABLE first. See audience status.
• 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 · Quickstart · Guides
• Create pixel · Get pixel · Pixel installation · Pixel FAQ
• Create CAPI integration · CAPI tokens · Dataset diagnostics
• Create audience · Get dataset · Aggregate report · Insight report · CSV report