Amazon Conversions API
The Amazon Conversions API destination sends off-Amazon conversion events to Amazon Ads using the server-side Events API, so purchases, sign-ups and other conversions that happen on your storefront can be attributed to and optimized against Amazon Ads campaigns.
This is a cloud-mode (server-side) destination only, which is how Amazon intends the Conversions API to be used: it exists for server-side and offline conversions, while browser-side measurement belongs to the Amazon Ad Tag (AAT) pixel on your storefront. Sending the same conversion through both surfaces without deduplication will double-count it.
This destination is built to match the Segment Amazon Conversions Api destination: the same conversion types, the same normalization and SHA-256 hashing of match keys, and messageId as the deduplication id. The Chord tracking-plan event names are mapped alongside Segment's, so a migration needs no per-event configuration.
Getting started
Amazon Ads authenticates with Login with Amazon (LWA). Because Chord CDP cannot run an interactive OAuth flow inside a destination, you supply the credentials of an LWA application that has already been authorized for your advertiser account:
- Amazon Advertiser ID. Your advertiser account ID, sent as the Amazon-Ads-AccountId header. Numeric; use the Amazon DSP CFID, not the Entity ID.
- LWA Client ID and LWA Client Secret from the Amazon Ads API section of the Amazon developer console.
- LWA Refresh Token, issued when your application was authorized for the advertiser account. Chord exchanges it for a one-hour access token and caches that token until it expires; the refresh token itself is never logged.
- Region. NA, EU or FE, matching the marketplace region of the advertiser account. Events sent to the wrong region are rejected.
Amazon supports Self-Service accounts only for this API. Managed Service and Manager accounts are not supported.
Warning: Before connecting destinations in the Chord CDP, please verify with all Destination owners that all non-Chord CDP configured destinations are disabled. Running external destinations alongside configured Chord CDP destinations can result in duplicate events downstream.
- Log into the Chord data platform.
- Navigate to the CDP.
- Click the "Add" button next to Destinations.
- Select Amazon Conversions API from the destination catalog.
- Enter the destination name, Region, Amazon Advertiser ID and the three LWA credentials.
- Set a Dataset Name now if you want one (see below); changing it later creates new conversion definitions.
- Click "Create" to connect.
Datasets
Amazon Ads groups uploaded events into datasets, which is how they appear in Amazon Ads Data Manager. Leaving Dataset Name empty puts everything in Amazon's Default_Events dataset.
Set the dataset name during initial setup. A dataset name must start with a letter, contain only letters, numbers, underscores or hyphens, and be 5–100 characters long. Changing it on a live destination creates new conversion definitions in Amazon, splitting your reporting history; treat it as immutable once events are flowing.
Event mapping
Amazon has a closed set of twelve conversion types. Chord maps its canonical event names onto them, using the same event names as the Segment destination plus the Chord tracking-plan aliases for the same actions:
Chord Event | Amazon Conversion Type |
|---|---|
Product Added | ADD_TO_SHOPPING_CART |
Application Submitted | APPLICATION |
Checkout Started | CHECKOUT |
Callback Started | CONTACT |
Lead Generated | LEAD |
Order Completed, Order Placed | OFF_AMAZON_PURCHASES |
Application Opened | MOBILE_APP_FIRST_START |
page events, Page Viewed | PAGE_VIEW |
Products Searched | SEARCH |
Signed Up, Account Created | SIGN_UP |
Subscription Created | SUBSCRIBE |
Any other track event | OTHER |
identify, group and other event types are skipped with an explicit log line.
Custom events
OTHER is a conversion type Amazon defines for "customer actions that don't fit the definition of the standard event types", so this destination is passthrough-capable: an event with no mapping is forwarded under its own name as OTHER rather than dropped. Turn Forward unmapped events as OTHER off to send only the mapped conversion events; skipped events are logged explicitly either way. See Custom Events.
Overriding the mapping
Use Event Mapping to send a specific event under a different conversion type, e.g. Subscription Renewed → OFF_AMAZON_PURCHASES. Only the twelve types above are valid; an event mapped to anything else is skipped with a log line rather than guessed at.
A conversion definition in Amazon Ads is identified by the event name, conversion type and event source together. Renaming events, changing Event Action Source, or remapping conversion types all create new definitions in Amazon. Settle these before you start sending production traffic.
Identity (Match Keys)
Amazon requires at least one match key per event, and every PII match key must be normalized and SHA-256 hashed. Chord does both before the request leaves the platform; plaintext PII is never sent. A value that already looks like a SHA-256 digest is passed through rather than hashed twice.
Amazon Match Key | Chord Source | Normalization before hashing |
|---|---|---|
properties.email > context.traits.email | Lowercase; keep alphanumerics plus ., @, +, - | |
PHONE | properties.phone / phone_number > traits | Digits only |
FIRST_NAME | properties.firstName / first_name > traits | Lowercase alphanumerics only |
LAST_NAME | properties.lastName / last_name > traits | Lowercase alphanumerics only |
ADDRESS | traits.address.street / address1 | Lowercase alphanumerics only |
CITY | traits.address.city > properties.city > properties.shipping_city | Lowercase alphanumerics only |
STATE | traits.address.state > properties.state > properties.shipping_state | Lowercase alphanumerics only |
POSTAL | traits.address.postalCode / zipcode > properties.postalCode > properties.shipping_zipcode | Lowercase, whitespace removed (punctuation kept for UK/CA formats) |
MAID | context.device.advertisingId / idfa / adid | Sent in the clear |
RAMP_ID | properties.rampId > traits > context.clientIds.rampId | Sent in the clear |
MATCH_ID | properties.matchId / match_id > traits > context.clientIds.matchId | Sent in the clear |
"Lowercase alphanumerics only" means ASCII: José is hashed as jos. This matches the Segment destination; we have not been able to confirm it against Amazon's own guideline, which requires an Amazon Ads login to read. The same applies to email: their guideline quotes it keeps only ., @ and -, but note that our code also keeps +.
Identifiers sent as numbers (a zip of 94107, a phone of 14155550132) are treated as their string form. Values that carry no matching signal are dropped rather than hashed: placeholders like n/a, unknown or test, an email without an @, and phone numbers with fewer than 7 digits or all one digit. A hash of n/a is the same for every brand that sends it, so it would match unrelated customers.
An event that carries no usable identifier cannot be attributed, so it fails with a non-retryable error rather than being sent and silently discarded by Amazon.
Match ID deserves a note: it is an opaque identifier of your own (a loyalty ID, an order reference) that Amazon correlates to users via the Amazon Ad Tag. If your storefront passes match_id to AAT, sending the same value here links offline and server-side conversions to the same customer journey without sharing hashed PII.
Event fields
Amazon Field | Chord Source | Notes |
|---|---|---|
eventDescription.name | event (page: name, else Page View) | Sent verbatim |
eventDescription.conversionType | See Event Mapping | |
eventDescription.eventSource | Event Action Source setting, else context.device.type | Uppercased. Device types Amazon does not accept (mobile, desktop) fall back to WEBSITE |
eventDescription.eventIngestionMethod | (hardcoded) SERVER_TO_SERVER | Required by Amazon for Conversions API events |
countryCode | properties.country > properties.shipping_country > context.locale > context.geo > address > Default Country Code | Locale forms (en-US, pt_BR) are reduced to the region subtag |
eventTime | timestamp, else receivedAt | ISO 8601 |
eventId | messageId | Amazon's clientDedupeId — see Deduplication |
value | properties.value > revenue > total > price | Sent for every conversion type |
currencyCode | properties.currency | OFF_AMAZON_PURCHASES only. Currencies outside Amazon's accepted list are omitted rather than rejected |
unitsSold | properties.quantity, else the sum of products[].quantity | OFF_AMAZON_PURCHASES only. Omitted when unknown — Amazon then defaults it to 1 |
customData | brand, category, productId + custom-mapped properties | See Custom attributes |
consent | See Consent | |
dataProcessingOptions | Limited Data Use setting or properties.dataProcessingOptions | |
Country code
Amazon requires an ISO 3166-1 alpha-2 country code on every event. Browser events usually carry context.locale or geo data; back-end events (Shopify webhooks, server-to-server ingest) often carry neither, which is what the Default Country Code setting is for — it defaults to US. Clear it if you would rather such events fail loudly than be attributed to the wrong country.
Custom attributes
Amazon's customData is a list of name/value pairs. Names accept letters, numbers and underscores; values are strings capped at 256 characters. Chord sends:
- brand, category and productId, resolved from the event's top-level properties and falling back to the first entry of products[]. These are the attributes Amazon uses for reporting, alongside attr1–attr10.
- Any property you have configured as a properties.* destination mapping in Hub, promoted into customData automatically. Names are sanitized (gift-note → gift_note) and nested values are JSON-stringified rather than dropped.
PII fields (email, phone, first/last name) are never promoted as plain custom attributes; they only ever leave as hashed match keys.
Consent
Amazon Field | Chord Source |
|---|---|
consent.geo.ipAddress | context.ip |
consent.amazonConsent.amznUserData / amznAdStorage | properties.amznUserData / amznAdStorage, or context.consent.* — GRANTED / DENIED (booleans accepted) |
consent.tcf | properties.tcf > context.consent.tcf |
consent.gpp | properties.gpp > context.consent.gpp |
In the EU region, Amazon requires at least one of these signals on every event. An EU-region event carrying none fails with a non-retryable error instead of being sent and rejected. In practice context.ip satisfies this for browser-originated events; back-end events need an explicit consent property.
Limited data use
Enabling Limited Data Use stamps every event with Amazon's LIMITED_DATA_USE data-processing option. Amazon does not process events marked this way for measurement or optimization, so enable it only where a privacy regime requires it. Individual events can opt in on their own by sending a dataProcessingOptions property containing LIMITED_DATA_USE.
Deduplication
messageId is sent as Amazon's clientDedupeId. For events sharing a dedupe id Amazon processes only the most recent one, which makes pipeline retries and replays safe.
Note that Amazon deduplicates across all event types, not per event type — two different conversions must not share a messageId.
Error handling
Condition | Behavior |
|---|---|
5xx or 429 from Amazon | Retried |
401 | The cached access token is discarded and the event retried with a freshly minted one |
403 | Not retried — the LWA application is not authorized for this advertiser, which a new token cannot fix |
Other 4xx | Not retried — a malformed event will not become valid on a resend |
207 with a per-event error entry | Treated as a failure, with Amazon's own error message. A 207 whose events all succeeded passes |
Missing match key, missing country code, missing EU consent | Not retried; the log line names the missing piece |
LWA credentials rejected (400/401 at the token endpoint) | Not retried — the Client ID, Secret or Refresh Token needs fixing |
Non-numeric Advertiser ID, or a Dataset Name outside Amazon's format | Not retried, and no request is made. The console form flags both when the destination is saved |
The access-token request is deliberately excluded from Live Events logging: it carries the client secret and refresh token in its body and returns the access token in its response.