Operators Guide
Configure events for Amazon Ads¶
The Amazon Ads Conversion API (CAPI) lets your brand send server-side conversion events — such as purchases, leads, and sign-ups — to Amazon Ads. Amazon uses these events to measure return on ad spend (ROAS) across online and offline channels, attribute offline conversions to Amazon DSP campaigns, and enrich audiences with first-party customer data.
Send conversion events to Amazon Ads using the Amazon Ads Conversion API (CAPI) to measure return on ad spend (ROAS), attribute offline conversions to Amazon DSP campaigns, and enrich audiences with first-party data. Each row returned by your query is sent as a single conversion event carrying a conversion type, an event source, an event timestamp, a country code, and one or more customer identifiers.
Amperity hashes email and phone identifiers with SHA-256 before sending them; raw email and phone values never leave Amperity. A mobile advertising ID (maid) and an Amperity match ID (match_id) are sent as-is. See the Amazon Ads Events API documentation for more information.
Beta
The Amazon CAPI connector is currently in beta. Contact your Amperity representative to learn more.
Caution
The values for email and phone sent to Amazon Ads are SHA-256 hashed automatically by Amperity before sending. Do not use the TO_HEX() function with the email and phone fields for queries that return results for Amazon Ads.
Get details¶
Review the following details before configuring credentials for Amazon Ads and before configuring Amperity to send conversion events to Amazon Ads.
|
Credential settings Refresh token
|
|
|
Amazon Ads settings DSP Advertiser ID
|
|
|
Request properties
|
Configure credentials¶
Configure credentials for Amazon Ads before adding a destination.
An individual with access to Amazon Ads should use SnapPass to securely share “refresh token” details with the individual who configures Amperity.
To configure credentials for Amazon CAPI
|
From the Settings page, select the Credentials tab, and then click the Add credential button. |
|
In the Credentials settings dialog box, do the following: From the Plugin dropdown, select Amazon CAPI. Note Amperity provides two Amazon connectors. Select Amazon CAPI to send conversion events to the Amazon Ads Conversion API. Amazon Ads is a separate connector that sends first-party audiences to Amazon DSP. Assign the credential a name and description that ensures other users of Amperity can recognize when to use this destination. |
|
The settings that are available for a credential vary by credential type. For the “amazon-capi” credential type, configure settings, and then click Save. Refresh token
|
Add destination¶
Use a sandbox to configure a destination for Amazon Ads. Before promoting your changes, send a sample audience, and then verify the results in Amazon Ads. After verifying the end-to-end workflow, push the destination from the sandbox to production.
To add a destination
|
|
Open the Destinations tab to configure a destination for Amazon Ads. Click the Add Destination button to open the Destination dialog box. Enter the name of the destination and a description. For example: “Amazon Ads events” and “Send conversion events to Amazon Ads.”. |
|
|
Credentials allow Amperity to connect to Amazon Ads. The credential type is set automatically. You may use an existing credential or you may add a new one. Select an existing credential from the Credential dropdown. – or – Select Create a new credential from the Credential dropdown. This opens the Credential dialog box. |
|
|
In the “Destination settings” dialog box, assign the destination a name and description that ensures other users of Amperity can recognize when to use this destination. Configure business user access By default a destination is available to all users who have permission to view personally identifiable information (PII). Enable the Admin only checkbox to restrict access to only users assigned to the Datagrid Operator and Datagrid Administrator policies. Enable the PII setting checkbox to allow limited access to PII for this destination. Use the Restrict PII access policy option to prevent users from viewing data marked as PII anywhere in Amperity and from sending data to downstream workflows. |
|
Configure the following settings, and then click “Save”. DSP Advertiser ID
|
|
After configuring this destination users may use orchestrations to send query results Amazon Ads. |
|
Validate the audience with Amazon Ads by using a sample audience with a very small membership. For example: 10 or 100 members or the minimum audience size recommended by Amazon Ads. Send the sample audience to Amazon Ads and verify the sample audience is correct in Amazon Ads. Make adjustments if necessary. Only send full audiences after validation is complete. |
Build a query¶
Use a query to build a combination of data — typically from the Unified Transactions and Customer 360 tables — that returns one row per conversion event to send to Amazon Ads. Each row must include a conversion type, an event source, an event timestamp, a country code, and at least one customer identifier (email, phone, mobile advertising ID, or match ID). Adding more identifiers can improve the match rate, and you can include event attributes such as conversion value, currency, and units sold, which Amperity sends with each event.
Review the Conversion API parameters section for the columns your query must and may return, and the Supported conversion types and event sources section for the allowed conversion_type and event_source values.
Amazon accepts conversion events only from the past 21 days, so bound the query to a recent window that matches how often the orchestration runs; this also avoids re-sending the full transaction history. A query that returns a collection of recent purchase events for use in Amazon Ads is similar to:
1SELECT
2 'Purchase' AS event_name
3 ,'OFF_AMAZON_PURCHASES' AS conversion_type
4 ,'OFFLINE' AS event_source
5 ,ut.order_datetime AS event_time
6 ,c360.country AS country_code
7 ,c360.email AS email
8 ,c360.phone AS phone
9 ,ut.order_revenue AS value
10 ,ut.currency AS currency_code
11 ,ut.order_id AS event_id
12FROM Unified_Transactions ut
13LEFT JOIN Customer_360 c360 ON ut.amperity_id = c360.amperity_id
14WHERE ut.order_datetime > (CURRENT_DATE - interval '21' day)
15AND c360.email IS NOT NULL
Supported conversion types and event sources¶
conversion_type and event_source are required and must exactly match one of the values below. The values are case-sensitive and uppercase, so purchase or Offline are rejected. Rows with a missing or unrecognized conversion_type or event_source are not sent and are reported as failed.
Supported conversion_type values (12)
ADD_TO_SHOPPING_CART, APPLICATION, CHECKOUT, CONTACT, LEAD, MOBILE_APP_FIRST_START, OFF_AMAZON_PURCHASES, PAGE_VIEW, SEARCH, SIGN_UP, SUBSCRIBE, OTHER
Supported event_source values (6)
ANDROID, FIRE_TV, IOS, OFFLINE, WEBSITE, MEASUREMENT_PARTNER
Regional routing and consent¶
Amazon Ads serves the Conversion API from three regional hosts. Amperity routes each event to the correct host based on its country_code, so a single query can include events for customers in different regions.
Region |
Country codes |
|---|---|
North America |
BR, CA, MX, US |
Europe |
AE, BE, DE, EG, ES, FR, GB, IN, IT, NL, PL, SA, SE, TR, ZA |
Far East |
AU, JP, SG |
Provide country_code as an ISO 3166-1 alpha-2 code (for example, US or GB — use GB for Great Britain, because UK is not a valid code). Amperity trims and uppercases the value before matching. A country_code that is present but not one of the recognized codes above defaults to North America. A row with no country_code at all is dropped rather than routed (see Data validation).
DSP advertiser must be linked per region. A DSP Advertiser ID is valid only in the Amazon Ads region(s) it is provisioned in. Before sending a region’s events, Amperity confirms the configured DSP Advertiser ID is linked to a manager account in that region. If it is not, that region’s events are not sent — they are reported as failed with an explanatory message — while events for the other regions are still delivered. Confirm in Amazon Ads that the DSP Advertiser ID is linked to a manager account in every region you send events to.
Provide an explicit consent signal for EU customers. Amazon requires consent information on every event routed to the Europe host, and your query should always provide amzn_ad_storage, amzn_user_data, or consent_tcf for EU-routed rows so consent reflects an actual decision rather than a fallback. When none is provided, Amperity defaults both amzn_ad_storage and amzn_user_data to DENIED so the event is still accepted by Amazon — but this default exists for API compliance, not as a substitute for your own consent determination. Events routed to North America and Far East receive no default — consent is sent only when your query provides consent_tcf, amzn_ad_storage, or amzn_user_data.
Note
The European consent default applies to every country in Amazon’s Europe routing group above, not only to countries in the European Union. To send an explicit consent signal, populate amzn_ad_storage and amzn_user_data (each GRANTED or DENIED), or consent_tcf with an IAB TCF string.
Data validation¶
Amperity validates each row before sending and drops rows that Amazon Ads would reject, so that one invalid row does not cause an entire batch of events to be rejected. Dropped rows are reported as failed with the reason. A row is dropped when:
event_name, conversion_type, event_source, event_time, or country_code is missing.
conversion_type or event_source is not one of the supported values (see Supported conversion types and event sources).
event_time cannot be parsed as an ISO 8601 instant (for example,
2026-03-15T14:30:00Z).the row has no identifier — email, phone, maid, and match_id are all empty.
An optional value that cannot be used is dropped from that row individually, and the rest of the event is still sent. For example, an email that is not a valid email address is dropped (and reported) and the event is sent using its other identifiers; a non-numeric value is omitted.
Conversion API parameters¶
The following table describes each column Amperity sends to Amazon Ads. A query must return columns with the same name as listed in the “Amperity name” column; Amperity maps them to the Amazon Conversion API field names automatically.
Important
A query must return event_name, conversion_type, event_source, event_time, and country_code, plus at least one identifier column — email, phone, maid, or match_id. All other columns are optional.
Amperity name |
Amazon field |
Description |
|---|---|---|
event_name |
name |
Required A name for the conversion event. |
conversion_type |
conversionType |
Required The type of conversion. Must be one of the 12 supported values (see Supported conversion types and event sources). |
event_source |
eventSource |
Required Where the event originated. Must be one of the 6 supported values (see Supported conversion types and event sources). |
event_time |
eventTime |
Required When the event occurred, as a full ISO 8601 instant with a UTC offset (for example, |
country_code |
countryCode |
Required The customer’s ISO 3166-1 alpha-2 country code. Determines which Amazon Ads region receives the event (see Regional routing and consent). Amperity trims and uppercases the value; a value that is present but unrecognized routes to North America. A blank value is dropped (see Data validation). |
matchKeys (EMAIL) |
Optional An email address. Amperity applies SHA-256 hashing before sending. At least one of email, phone, maid, or match_id is required per row. |
|
phone |
matchKeys (PHONE) |
Optional A phone number. Amperity normalizes the number and applies SHA-256 hashing before sending. |
maid |
matchKeys (MAID) |
Optional A mobile advertising ID, sent as-is (not hashed). |
match_id |
matchKeys (MATCH_ID) |
Optional An Amperity-generated match identifier, sent as-is (not hashed). |
value |
value |
Optional A numeric conversion value for the event, rounded to two decimal places. |
currency_code |
currencyCode |
Optional The currency for value. Sent only when value is also provided. |
units_sold |
unitsSold |
Optional The number of units sold, as an integer from 1 to 9,999,999,999,999. Sent only when conversion_type is |
event_id |
eventId |
Optional A unique identifier for the event, passed through as-is. Amazon uses it to deduplicate events across ingestion sources (for example, the Amazon Ads Tag and CAPI). Provide a stable value, such as an order ID, so that events sent through more than one source are not double-counted. |
dataset_name |
dataSetName |
Optional The name of the Amazon dataset the event belongs to. |
consent_tcf |
consent.tcf |
Optional An IAB Transparency and Consent Framework (TCF) consent string. |
amzn_ad_storage |
consent.amazonConsent.amznAdStorage |
Optional A consent signal for advertising storage. Must be |
amzn_user_data |
consent.amazonConsent.amznUserData |
Optional A consent signal for user-data processing. Must be |
limited_data_use |
dataProcessingOptions |
Optional Set to |
Workflow actions¶
A workflow will occasionally show an error that describes what prevented a workflow from completing successfully. These first appear as alerts in the notifications pane. The alert describes the error, and then links to the Workflows tab.
Open the Workflows page to review a list of workflow actions, choose an action to resolve the workflow error, and then follow the steps that are shown.
|
|
You may receive a notifications error for a configured Amazon Ads destination. This appears as an alert in the notifications pane on the Destinations tab. 
If you receive a notification error, review the details, and then click the View Workflow link to open this notification error in the Workflows page. |
|
|
On the Workflows page, review the individual steps to determine which steps have errors that require your attention, and then click Show Resolutions to review the list of workflow actions generated for this error. 
|
|
|
A list of individual workflow actions are shown. Review the list to identify which action you should take. Some workflow actions are common across workflows and will often be available, such as retrying a specific task within a workflow or restarting a workflow. These types of actions can often resolve an error. In certain cases, actions are specific and are shown when certain conditions exist in your tenant. These types of actions typically must be resolved and may require steps that must be done upstream or downstream from your Amperity workflow. Amperity provides a series of workflow actions that can help resolve specific issues that may arise with Amazon Ads, including: |
|
|
Select a workflow action from the list of actions, and then review the steps for resolving that error. After you have completed the steps in the workflow action, click Continue to rerun the workflow. |
Note
If Amazon Ads rejects an entire batch of events, the workflow reports Amazon’s per-event error messages (up to 10 per batch) — review the field values returned by your query. Events older than 21 days are rejected by Amazon; filter your query to recent events. If the configured DSP Advertiser ID is not linked to a manager account in a region, that region’s events are reported as failed and skipped while the other regions are still delivered. If sends are rate limited, Amperity retries automatically; reduce the volume of events sent per orchestration if the limit persists.
Invalid credentials¶
The credentials that are defined in Amperity are invalid.
To resolve this error, verify that the credentials required by this workflow are valid.
Open the Credentials page.
Review the details for the credentials used with this workflow. Update the credentials for Amazon Ads if required.
Return to the workflow action, and then click Resolve to retry this workflow.
Note
A 401 or 403 response from Amazon Ads means the refresh token is expired, was revoked, or does not have permission to submit conversion events. Re-complete the Amazon Ads authorization flow to obtain a new refresh token, and then update the credential in Amperity. Refresh tokens issued after June 30, 2026 expire 365 days after the advertiser grants consent.