Amazon Ads DSP Conversions API

Setup Guide

To set up Amazon Ads DSP Conversions API as a destination, you'll need to configure the following:

1. OAuth Authentication - Click the "Connect" button in the destination setup form to initiate the OAuth authentication flow. Log in with your Amazon Advertising account and grant Extract the required permissions.

2. Region - Select your Amazon Advertising API region:

   • NA (North America) - United States, Canada, Mexico, Brazil
   • EU (Europe) - UK, Germany, France, Italy, Spain, and other European markets
   • FE (Far East) - Japan, Australia, Singapore, and other Asia-Pacific markets

3. Profile ID - Select your Amazon Advertising profile from the dropdown. The profile corresponds to a specific marketplace and account.

4. Account ID - Your Amazon DSP advertiser account ID.

5. Advertiser ID (optional) - If different from Account ID, specify the Amazon Ads Advertiser ID used for API requests.

Conversion Definition Configuration

Amazon DSP requires a "Conversion Definition" to categorize the events you send. You can configure this in two ways:

Option 1: Single Conversion Definition

Use one conversion definition for all records in the sync. This is the simplest configuration when all your events represent the same type of conversion.

Option 2: Event Name Mapping

Map different event names to different conversion definitions. This allows you to send multiple event types in a single sync, each routed to its own conversion definition based on the event_name field.

---

For both options, you can either select an existing conversion definition from your Amazon DSP account, or create a new one by providing:

• conversion_definition_name - The name of the conversion definition.
• conversion_type - The type of conversion (e.g., OFF_AMAZON_PURCHASES, LEAD, PAGE_VIEW, etc.).
• source_type - The source of the conversion (e.g., WEBSITE, MOBILE_APP, OFFLINE).
• counting_method - How conversions are counted (e.g., EVERY, ONE_PER_CLICK).
• default_value - The default monetary value for conversions (defaults to 1.0).

If a conversion definition with the same name already exists, Extract will use the existing definition (after validating that the configuration matches).

Event Requirements

• Timestamp freshness - Events must have a timestamp within the last 7 days. Older events will be rejected.
• Match keys - At least one match key (user identifier) must be provided per event. Match key values must already be normalized and SHA-256 hashed according to Amazon's requirements.

Hashing and Normalization

warning

Unlike some other Conversions API destinations, Amazon Ads DSP requires you to hash and normalize identifiers before sending them to Extract. The matchKeys field must contain pre-hashed values.

Amazon Ads DSP expects identifiers to be:

1. Normalized according to Amazon's specifications (lowercase, trimmed, formatted)
2. SHA-256 hashed
3. Provided in the matchKeys array format

Refer to Amazon's Conversion API documentation for specific normalization requirements for each identifier type.

Data Contract Information

info

Your source dataset must be compatible with the parameter requirements of Amazon's DSP Conversions API. This includes adhering to the expected formats and field types. If your data does not meet these requirements, the sync may fail.

Note: Identifier values in matchKeys must already be normalized and SHA-256 hashed where Amazon requires hashing.

Loading ....

Troubleshooting

Common Errors

Error	Cause	Solution
timestamp must be within the last 7 days	Event timestamp is older than 7 days	Ensure your source data only includes recent events
matchKeys must contain at least one entry	No user identifiers provided	Add at least one match key (email, phone, etc.) to each event
No Amazon conversion definition mapping configured	Missing conversion definition for event name	Configure a default conversion definition or add a mapping for the event name
conversion_type is required	Using name-based definition resolution without required fields	Provide conversion_type, source_type, and counting_method when using conversion_definition_name