Event

Spotify is an audio streaming platform whose advertising business, Spotify Ads, reaches listeners across music, podcasts, and audiobooks. The Spotify Conversions API (CAPI) is a server-to-server integration that lets you send conversion events directly to Spotify, without relying solely on a client-side pixel. Forwarding conversions server-side improves signal fidelity and attribution accuracy as browser tracking restrictions, cookie deprecation, and ad blockers continue to limit pixel-based measurement.

This integration is a server-side output only. Client-side forwarding via kit is not supported.

Prerequisites

To set up the Spotify event integration, you need:

• A Spotify Ads account with access to Spotify Ads Manager.
• Business Admin access in Ads Manager. Only a Business Admin can open the Events dashboard, create a Conversions API data source, and generate an access token. The Contributor and Viewer roles cannot.

• A Conversions API data source in Spotify Ads Manager, which provides two values:

  • A CAPI Connection ID: the UUID identifying your Conversions API data source.
  • A CAPI access token: the long-lived bearer token used to authenticate requests.

The Conversions API access token is separate from the token used by other Spotify Ads API endpoints. Spotify allows a maximum of three active tokens per Conversions API data source; delete an existing token before generating another.

Setup

1. Create a Spotify Conversions API data source

You must be a Business Admin in Ads Manager to complete this step.

1. Log in to Spotify Ads Manager.
2. Click the global navigation icon in the top left and select Events.
3. Click Connect data source and select Conversions API.
4. Name your integration and select the ad accounts to associate with it.
5. Click Generate token and copy the access token.
6. Copy the Connection ID, a UUID shown when the data source is created. To retrieve it later, open the data source and click View Instructions.

2. Create a Spotify output configuration

1. In mParticle, navigate to Data Platform > Setup > Outputs.
2. On the Event tab, click Add Output and select Spotify.
3. Enter a descriptive Configuration Name.
4. Enter your CAPI Connection ID: the UUID from your Spotify Conversions API data source.
5. Enter your CAPI Access Token: the bearer token generated for that data source. mParticle stores this value encrypted.
6. Click Save.

3. Connect a data input to Spotify

To connect an input:

1. In mParticle, navigate to Connections > Connect Outputs.
2. Select the input you want to connect.
3. Find Spotify in the output list and click Connect Output.
4. Select an Action Source: where the conversions on this connection occur. Choose Web, App, or Offline.
5. (Optional) Select a User Data Consent Mapping: the mParticle consent purpose whose state determines whether an event is opted out of Spotify retargeting.
6. Click Add Connection.

Supported platforms

• iOS
• Android
• Web
• tvOS
• Custom Feed (server-to-server)

Supported identities

Spotify requires at least one identifier on every conversion. mParticle builds the identifier set once per batch and attaches it to every event in that batch.

Supported user identities

Spotify Field	mParticle Identity Type	Processing
hashed_emails	Email	Trimmed, lowercased, and SHA-256 hashed before forwarding. Values that are already hashed are passed through unchanged.
hashed_phone_number	Mobile Number	Trimmed, lowercased, and SHA-256 hashed before forwarding. Values that are already hashed are passed through unchanged.

If the Mobile Number identity is not present, mParticle falls back through Phone Number 2, then Phone Number 3, and finally the $Mobile user attribute. The first non-empty value found is hashed and forwarded.

Supported device identities

Spotify Field	mParticle Identity Type	Processing
device_id	iOS Advertising ID (IDFA), Google Advertising ID (GAID), or iOS Vendor ID (IDFV)	Spotify accepts a single device ID. mParticle selects the first of these that is present, in the order listed, and SHA-256 hashes it before forwarding.
ip_address	Client IP address on the event batch	Forwarded unhashed.

Supported event types

mParticle forwards the following event types to Spotify:

• Commerce Event
• Screen View
• Custom Event (only when explicitly mapped, see below)

All supported event types are forwarded by default. This integration’s connection settings do not allow you to disable event forwarding for a specific event type, but you can disable event forwarding using Filters.

Spotify identifies conversions by a fixed set of event names rather than by your event’s own name. mParticle resolves every event to one of these twelve names:

• VIEW
• PRODUCT
• CHECK_OUT
• ADD_TO_CART
• PURCHASE
• LEAD
• SIGN_UP
• CUSTOM_EVENT_1 through CUSTOM_EVENT_5

Default event mappings

These events forward with no configuration:

mParticle Event	Spotify Event Name
Screen View	VIEW
Commerce Event: View Detail	PRODUCT
Commerce Event: Checkout	CHECK_OUT
Commerce Event: Add to Cart	ADD_TO_CART
Commerce Event: Purchase	PURCHASE

Commerce event subtypes without a default mapping, such as refund, remove from cart, and checkout option, are not forwarded unless you map them explicitly.

Mapping other events

Custom events are not forwarded unless you map them. Use Custom Mappings for your Spotify connection to map an event to one of the twelve Spotify event names. LEAD, SIGN_UP, and CUSTOM_EVENT_1 through CUSTOM_EVENT_5 have no default mapping and are available for any event you choose.

A custom mapping always takes precedence over the default mapping. If you map a Purchase commerce event to CUSTOM_EVENT_1, mParticle forwards it as CUSTOM_EVENT_1 rather than PURCHASE. Events mapped to a name outside the twelve Spotify accepts are not forwarded.

Event data mapping

Event fields

mParticle Field	Spotify Field	Notes
Event ID	event_id	mParticle’s unique identifier for the event.
Event timestamp	event_time	ISO 8601 UTC with milliseconds.
Resolved event name	event_name	See Supported event types.
Action Source connection setting	action_source	WEB, APP, or OFFLINE.
Currency code (Commerce Event)	event_details.currency
product_action.total_amount (Commerce Event)	event_details.amount
Product names (Commerce Event)	event_details.content_name	Comma-separated when the event has multiple products.
Product categories (Commerce Event)	event_details.content_category	Comma-separated when the event has multiple products.
Screen name (Screen View)	event_details.content_name	The name of the Screen View event.

event_details is omitted entirely when none of its four fields have a value.

For events forwarded through a custom mapping, event_details is built from the attributes you map to Currency, Amount, Content Name, and Content Category rather than from the event’s own commerce fields. All four are optional.

Custom flags

Custom Flag	Spotify Field	Notes
Spotify.EventSourceUrl	event_source_url	The URL where the conversion occurred. Must begin with http:// or https://; other values are dropped and a warning is logged.
Spotify.OptOutTargeting	opt_out_targeting	true or false. See Opt-out targeting.

Custom mappings

Custom Mappings are optional for commerce events and screen views, and required for custom events. Use them to select which Spotify event name an event maps to and to populate event_details. For general instructions, see Custom Mappings.

Data processing notes

• Delivery: Events are forwarded server-to-server in real time as batches arrive.
• PII hashing: Email addresses and phone numbers are trimmed, lowercased, and SHA-256 hashed before forwarding. Device IDs are SHA-256 hashed. IP addresses are forwarded unhashed.
• Multi-product events: When a commerce event contains more than one product, mParticle joins the product names into a single comma-separated content_name value and the categories into a comma-separated content_category value. One conversion event is sent per commerce event, not one per product.
• Rate limits: Spotify enforces a limit of 100 requests per second per CAPI connection ID. If you need this limit raised, contact your Spotify account team.
• Retries: mParticle retries requests that fail with a retryable error. Some errors are not retried.
• Sampling: Sampling is not available for this integration. All events matching a connection’s filters are forwarded.

Opt-out targeting

The opt_out_targeting field tells Spotify to use a conversion for attribution only, excluding it from retargeting. mParticle resolves it per event in this order:

1. If the mapped consent purpose is present on the user’s profile and consent is denied, or the Spotify.OptOutTargeting custom flag is true, mParticle sends true.
2. If the mapped consent purpose is granted, or the custom flag is false, mParticle sends false.
3. Otherwise, the field is omitted from the event.

You can map only one consent purpose per connection, and the mapped purpose cannot be empty. Saving a connection that violates either rule fails validation.

Configuration settings

Configuration settings authenticate mParticle with the Spotify Conversions API and are set at the output level.

Setting Name	Data Type	Required	Default Value	Description
CAPI Connection ID	string	Yes		The UUID of your Conversions API data source. Found in Spotify Ads Manager under Events > your Conversions API data source > View Instructions.
CAPI Access Token	string	Yes		The Conversions API access token generated in Spotify Ads Manager for the data source. Sent as a bearer token on every request. Stored encrypted by mParticle.

Connection settings

Connection settings are configured per connection and control how conversions from a given input are described to Spotify.

Setting Name	Data Type	Required	Default Value	Platform	Description
Action Source	string	Yes	Web	All	Where the conversions on this connection occur. One of Web, App, or Offline. Forwarded as action_source.
User Data Consent Mapping	string	No		All	The mParticle consent purpose that determines opt_out_targeting. When the purpose is on the user’s profile, denied consent opts the event out of Spotify retargeting. Only one purpose can be mapped.