Spotify is a global audio streaming platform that connects advertisers with listeners across music and podcasts through its Ads Manager platform. Advertisers can build, target, and measure audio, video, and display campaigns to reach relevant audiences at scale. Spotify's Conversions API (CAPI) is a tagless attribution tool that lets advertisers pass online and offline conversion events directly to Spotify server-to-server. By transmitting event data directly, CAPI supports attribution and measurement that is resilient to browser and client-side tracking limitations.
Product Type: Advertising
Integration Type: Starter Kit
Event Source Type: Web and Mobile App
Event Scope: Full-Funnel Events
- Sends server-side conversion and engagement events directly to Spotify via the Conversions API.
- Supports batch delivery of events per request.
- Captures identifiers required for user matching, including IP address, hashed device ID, hashed email, and hashed phone number.
- Sets the event source (
WEB or APP) automatically based on the presence of device context.
- Supports full-funnel events including page and screen views, product views, add-to-cart, checkout, and purchase.
- At least one user identifier is required on every event. This integration sends IP address on all events, and adds hashed email and hashed phone number when available following an identify. Including both IP address and device ID where possible improves match rates.
- Hashed email, hashed phone, and device ID values are normalized by trimming and lowercasing before SHA-256 hashing.
- The device ID is sent only when a mobile advertising ID is available, which applies to mobile app traffic.
- A single invalid event causes Spotify to reject the entire batch, and the offending event is not identified in the response. Because the batch size is 10, up to nine valid events can be dropped alongside one bad event.
- The
event_time value must fall within the last 30 days and cannot be in the future. Events outside this window are rejected. Replays or backfills older than 30 days cannot be delivered and will cause the batch they are included in to fail.
- Purchase events require both a currency and a non-zero amount. An amount of zero is rejected, so orders with a zero total (such as fully discounted orders) will cause the batch to fail. The returned error may reference the currency even when the amount is the cause.
- The
content_category field must be a valid Google Product Taxonomy value; arbitrary category strings are rejected and will fail the batch. This field is not mapped by default. Add the mapping only for accounts whose catalog categories conform to Google Product Taxonomy.
- The CAPI access token is long-lived and does not expire. It is scoped to the organization and connection and is distinct from the Ads API OAuth token. Newly created tokens may return an authorization error for roughly 15 to 20 minutes after creation; wait for the token to become active rather than generating a new one.
- Allow at least 20 minutes for events to appear in the Ads Manager event activity graph.
- Events older than 30 days cannot be delivered under any circumstances.
- Purchase events with a zero amount are rejected by Spotify.
- The
content_category field is not mapped by default due to Google Product Taxonomy enforcement.
- Custom events (
CUSTOM_EVENT_1 through CUSTOM_EVENT_5) cannot be renamed while CAPI is in beta.
CAPI_CONNECTION_ID: Create a Connection ID in Ads Manager under Events, then Connect Data Source, then Conversions API. Submitting the form returns the Connection ID.CAPI_ACCESS_TOKEN: In Ads Manager under Events, then Connect Data Source, then Conversions API, select Generate Token. This long-lived token is distinct from the Ads API OAuth token.
- From the integration library, add a Spotify integration. Then, fill out the Connection Parameters:
| Connection Parameter | Description |
|---|
CAPI_CONNECTION_ID | Unique Connection ID (UUID) assigned to your data source, generated in Ads Manager. |
CAPI_ACCESS_TOKEN | Long-lived Bearer token used to authenticate CAPI event requests. |
- MetaRouter provides all of the event mappings that Spotify integrations typically require. You may add custom events, parameters, or mappings in accordance with Spotify's API documentation.
- In the Pipelines tab, add your Spotify integration.
- Select the correct integration revision.
- Click Add Integration to finalize deployment.
Global mappings will be applied to all events. If your parameter names do not match the Expected Inputs provided, you will need to overwrite the Inputs provided with your own.
| Output Key | Description | Expected Input |
|---|
event_id Required | String: Unique event identifier used for deduplication. | messageId |
event_time Required | String: ISO 8601 event timestamp; must be within the last 30 days and not in the future. | timestamp |
event_source_url | String: URL where the event occurred. | context.page.url |
action_source | String: Medium of the conversion; APP when device context is present, otherwise WEB. | Expression – returns 'APP' when context.device.type exists, else 'WEB' |
user_data.ip_address Required | String: Client IP address of the user. | context.ip |
user_data.device_id | String: SHA-256 hash of the mobile advertising ID; sent only when present. | Expression – hashes context.device.advertisingId after normalization |
user_data.hashed_emails | Array: SHA-256 hashed, normalized email address. | Expression – hashes traits.email after normalization |
user_data.hashed_phone_number | String: SHA-256 hashed, normalized phone number. | Expression – hashes traits.phone after normalization |
| Output Key | Description | Expected Input |
|---|
event_name Required | String: Vendor event name for a screen view. | Enrichment – 'VIEW' |
event_details.content_name | String: Name of the viewed screen. | properties.name |
| Output Key | Description | Expected Input |
|---|
event_name Required | String: Vendor event name for a page view. | Enrichment – 'VIEW' |
event_details.content_name | String: Title of the viewed page. | properties.title |
| Output Key | Description | Expected Input |
|---|
event_name Required | String: Vendor event name for add-to-cart activity. | Enrichment – 'ADD_TO_CART' |
event_details.content_name | String: Name of the added product. | properties.name |
event_details.amount | Float: Total value of the added product. | Expression – TOTAL_VALUE(input.properties) |
| Output Key | Description | Expected Input |
|---|
event_name Required | String: Vendor event name for a product view. | Enrichment – 'PRODUCT' |
event_details.content_name | String: Name of the viewed product. | properties.name |
event_details.currency | String: Currency code for the viewed product. | properties.currency |
event_details.amount | Float: Total value of the viewed product. | Expression – TOTAL_VALUE(input.properties) |
| Output Key | Description | Expected Input |
|---|
event_name Required | String: Vendor event name for checkout start activity. | Enrichment – 'CHECK_OUT' |
event_details.content_name | String: Order or transaction identifier. | properties.order_id |
event_details.currency | String: Currency code for the order. | properties.currency |
event_details.amount | Float: Total value of the products in the order. | Expression – TOTAL_VALUE(input.properties.products) |
| Output Key | Description | Expected Input |
|---|
event_name Required | String: Vendor event name for purchase activity. | Enrichment – 'PURCHASE' |
event_details.content_name | String: Order or transaction identifier. | properties.order_id |
event_details.currency | String: Currency code for the purchase; required for purchase events. | properties.currency |
event_details.amount | Float: Order revenue from the products array; must be non-zero for purchase events. | Expression – TOTAL_VALUE(input.properties.products) |
These identifiers must be mapped to Spotify in order for successful user matching to occur. Without these IDs, any events sent to Spotify may not be accurately reflected in reporting.
| Attribute | Example | Sync Injector Required? |
|---|
ip_address Required | 203.0.113.12 | No |
device_id Recommended | 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 | No |
hashed_emails Recommended | e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 | No |
hashed_phone_number Recommended | b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514 | No |
Use the event activity graph in the Ads Manager Events dashboard to confirm that conversion events are being received. Allow at least 20 minutes for events to appear. Because a single invalid event rejects the entire batch, review the dashboard to confirm expected event volume and types are arriving as anticipated.
Attribution should be validated using Spotify campaign reports, which reflect attributed conversions such as purchases and revenue against a live campaign. Note that end-to-end attribution can only be confirmed against an active Spotify campaign.
