Ensure that you never serve another irrelevant advertisement with Amazon Ads
Supported syncing
| Sync type | Description | Supported sync modes | API reference |
|---|---|---|---|
| Segment | Sync first-party and third-party data from any source to Amazon Ads DSP and AMC audiences | Add | Manage audiences ↗ |
| Events V2 | Sync data from any source to Amazon Ads as conversion events | Insert | Send conversion events ↗ |
| Events (deprecated) | Sync data to Amazon Ads DSP as offline conversion events using Amazon's legacy events endpoint | Insert | Upload conversion events ↗ |
For more information about sync modes, refer to the sync modes docs.
Connect to Amazon Ads
Go to the Destinations overview page and select Add destination. Select Amazon Ads and select Continue. You can then authenticate Hightouch to Amazon Ads.
For the Authentication method, select Log in to Amazon Ads and log in to your Amazon Ads account. After you authenticate, Hightouch redirects you back to complete setup with these fields:
- Region — The Amazon API region that covers your marketplaces.
- Ad account ID — Your advertiser account ID.
- Manager account ID — Required to sync to Ads Data Manager audiences. To find it, select your manager account name in the top-right corner of the Amazon Ads console; the console labels it Partner ID. It begins with
amzn1.ads1.ma1.
Sync configuration
Once you've set up your Amazon Ads destination and have a model to pull data from, you can set up your sync configuration to begin syncing data. Go to the Syncs overview page and select Add sync. Then, select the relevant model and the Amazon Ads destination you want to sync to.
Segment
Sync data from any source to Amazon Ads audiences.
Choose an audience type
You can sync to first-party data or third-party data based on the type of audience.
- First-party data — Sync hashed user data to audiences.
- Third-party data (DSP) — Sync external identifiers such as MAIDs and cookie IDs.
Choose an audience system (first-party data)
Amazon deprecated its legacy AMC Advertiser Audience API in favor of Ads Data Manager. For first-party data audiences, choose which system the sync uses:
- Ads Data Manager (recommended) — Amazon's current audience system. Hightouch creates an audience dataset, shares it to Amazon DSP, and syncs members into it.
- Legacy AMC audience — Use this only to sync to an audience created under the legacy API. Legacy audience IDs are numeric.
The choice is fixed once the sync creates its audience. Audiences created under one system can't be written to through the other.
Existing first-party audience syncs continue to run on the legacy API without any changes. To move an audience to Ads Data Manager, create a new sync using the Ads Data Manager option, then point your DSP campaigns at the new audience.
Set up Ads Data Manager audiences
Before creating an Ads Data Manager sync:
- Your Amazon Ads account must accept the Ads Data Manager terms of service. Amazon prompts for acceptance the first time someone opens Ads Data Manager (Data & events > Data manager) in the Amazon Ads console.
- The destination's Manager account ID field must be set. See Connect to Amazon Ads.
When creating the sync, you can create a new audience or select an existing Ads Data Manager dataset from the dropdown. For new audiences, configure:
- Marketplace — The Amazon marketplace the audience is created in. The audience is shared to Amazon DSP in this marketplace.
- Country code — The ISO 3166-1 alpha-2 country code for the members in the audience.
- Retain hashed identifiers — Optional. When enabled, Amazon retains hashed data for 90 days and refreshes identity tokens.
Ads Data Manager dataset names only allow letters, numbers, hyphens, and underscores. Hightouch automatically replaces other characters in your audience name with underscores when creating the dataset. The audience name shown in Amazon DSP is unchanged.
Audience expiration (TTL), audience fees, and connection IDs are features of the legacy API and don't apply to Ads Data Manager audiences.
Configure record matching
To match rows from your model to an audience in Amazon Ads, select a model column and corresponding Amazon Ads field. For third-party data audiences, you can match on any of the following fields:
- Cookie ID
- Mobile Advertising ID
- External ID
For first-party data audiences, you can match on any of the following fields:
- Phone
- City
- State
- First name
- Last name
- Address
- External ID
For Ads Data Manager audiences, the External ID must be an opaque identifier such as a user ID from your database. Amazon rejects the entire batch if the External ID contains personal data such as an email address. Include at least one strong identifier (email or phone) so Amazon can resolve members.
Events V2
Sync data from any source to Amazon Ads as conversion events using Amazon's current events API.
Configure event name and timestamp
Select the model columns that provide the event name and the event timestamp.
Configure record matching
Select the model columns to use as match keys. You can use any of the following fields:
- Phone
- First name
- Last name
- Address
- City
- State
- Postal
- MAID
- Ramp ID
- Match ID
Map fields
Map your model columns to Amazon Ads event fields. You can also map up to 13 custom data fields with a type of String, Integer, or Timestamp.
Under Advanced, you can lower the rows per batch. The default and maximum is 500.
Events (deprecated)
Amazon deprecated the legacy events endpoint in favor of the newer events API. Use Events V2 for new syncs.
Sync data from any source to Amazon Ads as offline conversion events using Amazon's legacy events endpoint.
Create a conversion definition in Amazon Ads
Before syncing events with the legacy endpoint, you need to create a conversion definition in Amazon Ads. See the Amazon Ads API documentation for more information. You can create a conversion definition using the Amazon Ads UI or API.
To create a conversion definition using the Amazon Ads API, use the endpoint documented here.
To create a conversion definition using the Amazon Ads UI, follow these steps:
- Sign in to Amazon Ads.
- Go to Data & events > Events and choose your advertiser account when prompted.
- Go to the Conversions tab and select Add conversion.
After creating a conversion definition, you can select it in the sync configuration.
Configure record matching
For events, you can use any of the following fields as identifiers in Amazon Ads:
- Phone
- City
- State
- Address
- Postal
- MAID
- First name
- Last name
See the Amazon Ads API documentation for more information on required fields for event syncing.
Map fields
Hightouch lets you sync event properties via field mapping.
Handling PII and hashing
By default, Hightouch normalizes and hashes first-party user data fields with SHA-256 before sending them to Amazon Ads.
You can turn off automatic hashing in the sync configuration. When you do, you're responsible for normalizing and hashing data according to Amazon Ads' requirements before it reaches Hightouch.
Tips and troubleshooting
For Hightouch platform error codes related to Amazon Ads, see Error codes: Amazon Ads.
Matched users count
Below only applies to the Segment sync type.
Hightouch retrieves the audience metadata from Amazon Ads in real-time. The matched number displayed in Hightouch should reflect what you see in Amazon Ads. Note that the matched numbers are approximated to maintain privacy thresholds. Hightouch takes the matched count to calculate a match rate for your sync, where applicable. The calculation breakdown:
matched_user_count / # of rows queried in the latest sync runThe match rate is not calculated when:
- syncing to an existing segment because the total number of records to ever be uploaded to the segment is unknown
- removed users from your model is not removed in Amazon Ads because the matched user count would be inflated in the calculation
Common causes for low match rates:
- Your audience model is too small. Most ad platforms do not display the matched number unless there's at least one thousand matched users to maintain privacy thresholds.
- The upload is still processing. We recommend waiting at least 72 hours from the first sync run for numbers to settle.
- Your data isn’t cleaned or hashed properly. Hightouch normalizes and hashes your data according to destination requirements, but it’s still good to make sure that the data is as clean as possible. Note that Hightouch cannot clean your data if you opt to hash it yourself. In that case, ensure you follow the data cleaning requirements forAmazon Ads.
Common errors
If you encounter an error or question not listed below and need assistance, don't hesitate to . We're here to help.
Legacy audience IDs are numeric
Legacy AMC audience IDs are numeric. To sync to an Ads Data Manager dataset, select Ads Data Manager as the audience system instead.
Cause: An Ads Data Manager dataset name or ID was entered in the legacy audience ID field. Legacy AMC audience IDs are always numeric.
Solution: Select Ads Data Manager as the audience system and pick the dataset from the dropdown instead of entering it manually.
Manager account ID is missing
Ads Data Manager requires your Amazon manager account ID. Add it in this destination's settings (find it in the Amazon Ads console under Ads Data Manager).
Cause: The sync uses Ads Data Manager, but the destination has no manager account ID configured.
Solution: Select your manager account name in the top-right corner of the Amazon Ads console to find the ID; the console labels it Partner ID. It begins with amzn1.ads1.ma1. Add it to the destination's Manager account ID field.
Ads Data Manager terms not accepted
This Amazon Ads account has not accepted the Ads Data Manager terms and conditions. Accept them in the Amazon Ads console (Ads Data Manager), then re-run this sync.
Cause: Your Amazon Ads account hasn't accepted the Ads Data Manager terms of service.
Solution: Open Ads Data Manager (Data & events > Data manager) in the Amazon Ads console and accept the terms when prompted, then re-run the sync.
All records in this request are invalid
All records in this request are invalid. Fix the errors before resubmitting the request.
Cause: Amazon rejected every member in the batch. The most common cause is an External ID mapping that contains personal data such as an email address. It can also occur when members lack a strong identifier.
Solution: Map External ID to an opaque identifier such as a user ID, and include an email or phone identifier in the record matching configuration.
Dataset name already exists
An Ads Data Manager dataset named "..." already exists in this Amazon account and was not created by this sync. Rename this audience or remove the existing dataset in Ads Data Manager.
Cause: A dataset with the sync's audience name already exists in your Ads Data Manager account, and it wasn't created by this sync.
Solution: Give the audience a different name in the sync configuration, or remove the conflicting dataset in Ads Data Manager.
Invalid conversion definition ID
If you receive an error that the conversion definition ID is invalid on a legacy event sync, ensure that you have created a conversion definition in Amazon Ads and selected it in the sync configuration.
If you are using a column for the conversion definition ID, ensure that the column values match the numeric ID of the conversion definition in Amazon Ads, rather than its name.
Live debugger
Hightouch provides complete visibility into the API calls made during each of your sync runs. We recommend reading our article on debugging tips and tricks to learn more.
Sync alerts
Hightouch can alert you of sync issues via Slack, PagerDuty, SMS, or email. For details, please visit our article on alerting.