User Guides
Send conversion events to 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.
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.
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
Add orchestration¶
An orchestration defines the relationship between query results and a destination, including the destination and the frequency at which an orchestration runs.
To add an orchestration
Open the Activations page, select the Orchestrations tab, and then click the Add orchestration button. This opens the Add orchestration dialog box.
From the Object type dropdown, select Query.
From the Object dropdown, select the query for which results is sent to Amazon Ads.
From the Destination dropdown, select a destination that is configured for sending data to Amazon Ads.
Verify all settings.
Set the workflow to Manual. You can change this to automatic later, after verifying the end-to-end workflow.
Click Save.
Run orchestration¶
Run the orchestration manually to validate that it works.
To run the orchestration
Open the Activations page, select the Orchestrations tab, and then open the menu for the Amazon Ads orchestration. Select Run.
The Status column for the orchestration updates to say “Waiting to start”, after which the notifications pane updates to include a notification that shows the current status.
When the orchestration has run successfully, the status is updated to “Completed”.
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 |