What Is Amazon DSP Events?

Amazon DSP (Demand Side Platform) allows advertisers to programmatically buy display, video, and audio ads both on and off Amazon. The Events API for Amazon DSP enables advertisers to send conversion events directly from their servers to Amazon Ads, bypassing the need for browser-based tracking.

Product Type: Advertising

Integration Type: Starter Kit

Event Source Type: Web & Mobile Web

Event Scope: Full-Funnel Events

Capabilities

• Sends off-Amazon conversion and engagement events to Amazon Ads
• Supports batching of events for efficient delivery
• Enables hashed identifier-based matching for attribution
• Maps common commerce and content interaction events
• Respects user consent signals for ad storage and user data processing
• Supports conditional event delivery based on consent availability

Considerations

• matchKeys.values must be sent as an array, even when only one value is present, for events to be accepted
• eventDescription.eventIngestionMethod is set to SERVER_TO_SERVER and should not be changed
• consent.amazonConsent.amznUserData and consent.amazonConsent.amznAdStorage are required for events to appear in reporting and must align with your consent management setup
• Default consent mappings assume a standard OneTrust-style opt-out model and may need adjustment for your implementation
• Events are sent in batches, wrapped in an events array per request
• A conversion dataset name must be configured in Amazon Ads and mapped to eventDescription.dataSetName for events to be reported correctly
  • While you may reuse an existing conversion dataset for server-side events, we recommend creating new, clearly labeled datasets for testing and validation. This makes it easier to identify incoming events in the dashboard during setup and troubleshooting.
• Requires OAuth2 credentials and refresh token for authentication
• Conversion events must include at least a hashed email or user ID
  • Hashed email, hashed phone number, or another supported identifier is available for all conversions sent to the Conversions API. View the full list of supported parameters
• Events missing identity data will be dropped by the integration
• Amazon Ads may reject events that fall outside its supported event lookback window.

Limitations

• Cannot trigger Amazon-native tracking pixels or UI widgets
• Does not support on-Amazon conversions

Prerequisites

Before setting up the Amazon DSP Events integration, ensure the following:

• Access to a self-service advertiser account in the Amazon DSP
• Advertiser Audience Agreement has been accepted
  If you have not yet accepted the terms and conditions:
  1. Go to https://advertising.amazon.com and navigate to the Amazon DSP console
  2. Select your entity and advertiser
  3. Go to Events Manager from the left-hand menu
  4. You’ll be prompted to read and accept the Advertiser Audience Agreement Terms and Conditions
     • If you are not prompted, the terms have already been accepted

Starter Kit Setup Guide

1. Gather Credentials

To use the Amazon DSP Events integration, you must collect the following credentials:

Client ID & Client Secret

1. Go to https://developer.amazon.com
2. Navigate to Developer Console → Login with Amazon on the top navigation
3. If needed, create a new Security Profile
4. On the Security Profile, click Show Client ID and Client Secret
5. Save both for use in the Starter Kit

NOTE: Please ensure that your developer account has the campaign management scope enabled before proceeding. Use the Advanced Tool Center to view scopes assigned to your security profile.

Redirect URL Setup

1. Click the Manage icon next to your Security Profile

2. Under Web Settings, add your allowed return URLs

   Examples:

   • https://www.amazon.com
   • https://www.metarouter.io

Obtain Code

1. Navigate to the following URL in your browser:

https://www.amazon.com/ap/oa?scope=advertising::campaign_management&response_type=code&client_id=<CLIENT_ID>&state=State&redirect_uri=<REDIRECT_URL>

1. Replace the placeholders with your actual values.
2. After approval, copy the code value from the redirect URL.

Get Access & Refresh Tokens

1. Use the following cURL request in Postman to obtain your tokens:

curl --location 'https://api.amazon.com/auth/o2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=<STEP_1_CODE>' \
--data-urlencode 'redirect_uri=<REDIRECT_URI>' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>'

1. Replace:
   1. <STEP_1_CODE> with the code you got in Step 3
   2. <REDIRECT_URI> with your return URL
   3. <CLIENT_ID> and <CLIENT_SECRET> from Step 1
   4. Sample Response (truncated access token, please include the full token in your cURL): { "access_token": "**Atza|IwE…"**, "refresh_token": "Atzr|IwE…", "token_type": "bearer", "expires_in": 3600 }
2. Copy the Access Token and Refresh Token and save it for the next steps

Get Profile ID

1. Run the following request in Postman:

curl --location 'https://advertising-api.amazon.com/v2/profiles' \
--header 'Amazon-Advertising-API-ClientId: <CLIENT_ID>' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'

1. Replace <CLIENT_ID> and <ACCESS_TOKEN> with your values.
   1. Sample Response (truncated): [ { "profileId": **32312945...**, "countryCode": "US", "currencyCode": "USD", "timezone": "America/Los_Angeles", "accountInfo": { "marketplaceStringId": "ATV...", "id": "ENTITY1B...", "type": "agency", "name": "MetaRouter" } } ]
2. Save the value of the Profile ID, which is required in the Amazon DSP Events Starter Kit.

Get Advertiser ID

1. Log in to your Amazon Ads account → Administration → Accounts
2. Copy the numeric account ID under your account name.

Get Dataset Names

1. In your Amazon Ads account, go to Data Manager → Datasets
2. You can upload new Dataset names or copy an existing Dataset name
3. These names must be mapped to specific events in your Amazon DSP Events starter kit

2. Add an Amazon DSP Events Integration

From the integration library, add a Amazon DSP Events integration. Then, fill out the Connection Parameters:

3. Configure Event Mapping

• MetaRouter provides all of the event mappings that Amazon DSP Events integrations typically require. You may add custom events, parameters, or mappings in accordance with Amazon Ads API documentation.

4. Deploy to Pipeline

• In the Pipelines tab, add your Amazon DSP Events integration.
• Select the correct integration revision
• Click Add Integration to finalize deployment.

Event Mappings

Global

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.

Event Specific

Page

Checkout Started

Order Completed

Product Added

Product Removed

Product Clicked

Product List Viewed

Product Viewed

Cart Viewed

Products Searched

Required & Recommended Identifiers

These identifiers must be mapped to Amazon Ads Events in order for successful user matching to occur. Without these IDs, any events sent to Amazon Ads Events may not be accurately reflected in reporting.

Note:
In this starter kit, traits.email is used as the primary source to generate the required hashed email. If traits.email is not present, userId is used as a fallback input to generate the hashed email value that populates matchKeys. Events are only sent when one of these inputs is available.

These identifiers must be mapped to Amazon DSP Events in order for successful user matching to occur. Without these IDs, any events sent to Amazon Ads may not be accurately reflected in reporting.

Integration Validation

To validate events from the Amazon DSP Events integration, go to Data Manager > Destinations, click the name of your off-Amazon conversion, and check the conversions dashboard for incoming events.

Additional Amazon DSP Events Documentation

• Getting Started with the Amazon Ads API
• Authorization
• Amazon DSP Events API