What Is Amazon DSP CAPI?

Amazon DSP (Demand Side Platform) allows advertisers to programmatically buy display, video, and audio ads both on and off Amazon. The Conversion API (CAPI) 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

Event Scope: Full-Funnel Events

Capabilities

• Sends server-to-server conversion events to Amazon DSP
• Supports custom event mapping using Conversion Definition IDs
• Enables matching using hashed emails or user IDs
• Allows deduplication using client-defined message IDs

Considerations

• Conversion Definition IDs must be obtained from Amazon Ads
  • While you may reuse your existing conversion definitions for server-side events, we recommend creating new, clearly labeled off-Amazon conversions for testing and validation. This helps ensure that incoming events can be easily identified in the conversions dashboard, especially during initial setup or 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
• Events older than 7 days will be rejected

Limitations

• Cannot trigger Amazon-native tracking pixels or UI widgets

Prerequisites

Before setting up the Amazon DSP CAPI 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 CAPI 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 CAPI 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 Conversion Definition IDs

1. In your Amazon Ads account, go to Data Manager → Destinations
2. You can create a new off-Amazon conversion or copy an existing Conversion ID
3. These IDs must be mapped to specific events in your Amazon DSP CAPI starter kit

2. Add an Amazon DSP CAPI Integration

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

3. Configure Event Mapping

• MetaRouter provides all of the event mappings that Amazon DSP CAPI 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 CAPI 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

Products Searched

Product List Viewed

Product Clicked

Product Viewed

Product Added

Product Removed

Cart Viewed

Order Completed

Required & Recommended Identifiers

These identifiers must be mapped to Amazon DSP CAPI 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 CAPI 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 CAPI Documentation

• Getting Started with the Amazon Ads API
• Authorization
• Amazon DSP CAPI API Reference