Amazon Ads Conversions API: off-Amazon attribution

Context

Why Amazon Ads CAPI

Amazon DSP can influence customers before they ever reach your site: display, video, streaming TV, and retail media placements can create demand across Amazon-owned and third-party inventory. The measurement gap appears after the click or view. If your conversion signal depends only on a browser pixel, high-value outcomes can be lost to redirects, checkout domains, consent controls, ad blockers, and short-lived client storage.

Amazon Ads Conversions API closes part of that gap by letting TrackLayer send off-Amazon events from the server after your application confirms the action. Purchases, leads, subscriptions, add-to-cart actions, and account signups can carry click IDs, hashed identifiers, geography, timestamps, and value. That gives Amazon Ads a cleaner signal for attribution and optimization while giving your team an auditable event trail outside fragile browser-only tracking.

Requirements

Prerequisites

profile_id for the Amazon Ads account that owns the advertiser and campaign measurement configuration.

OAuth refresh_token generated through Login with Amazon authorization for the Ads API account you are sending as.

LWA client_id and client_secret stored as server secrets for refreshing short-lived access tokens.

AdsAPI app approved for Amazon Ads API access, with the correct region, scopes, and production status.

A TrackLayer event schema that maps commerce, lead, signup, and subscription actions into Amazon off-Amazon conversion names.

Build

Step-by-step setup

Step 1

Refresh the Ads API access token

Amazon Ads API requests use short-lived bearer tokens. Your worker should exchange the OAuth refresh_token for a fresh access token before sending events, cache the token until expiry, and keep LWA credentials out of browser code. A failed token refresh should stop the batch rather than creating partial attribution with missing advertiser context.

POST https://api.amazon.com/auth/o2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=Atzr|IwEBI...&
client_id=amzn1.application-oa2-client.xxxxx&
client_secret=amzn1.oa2-cs.v1.xxxxx

Step 2

Capture the click ID at collection time

When a visitor arrives from an Amazon Ads click, read amzn_click_id from the landing URL and persist it in a first-party cookie or server session. TrackLayer should attach that clickId to later backend events such as lead, checkout, subscription, and purchase. Do this before redirects or checkout domain changes remove the original query string.

const params = new URLSearchParams(window.location.search);
const clickId = params.get("amzn_click_id");

if (clickId) {
  document.cookie =
    "amzn_click_id=" + encodeURIComponent(clickId) +
    "; Path=/; Max-Age=7776000; SameSite=Lax; Secure";
}

Step 3

Build the off-Amazon event payload

Normalize TrackLayer events into Amazon's off-Amazon event shape. Use the original action time, not queue processing time. Send clickId when present, and include hashed email, hashed phone, or mobile advertising ID when consent and collection rules permit. For purchase events, include value and currency so reporting and optimization can distinguish high-value outcomes.

{
  "events": [
    {
      "name": "Purchase",
      "eventType": "PURCHASE",
      "eventActionSource": "WEBSITE",
      "timestamp": "2026-04-23T10:15:30Z",
      "clickId": "amzn1.click.abc123",
      "userInfo": {
        "hashedEmail": "f2d2f6b9...",
        "hashedPhone": "7a38c9e4...",
        "madid": "AEBE52E7-03EE-455A-B3C4-E57283966239",
        "countryCode": "US",
        "postalCode": "10001"
      },
      "value": {
        "amount": 129.95,
        "currencyCode": "USD"
      },
      "eventId": "ord_10492_purchase"
    }
  ]
}

Step 4

Post events to the Conversions API

Send events from a backend route or queue worker. The profile_id header selects the Amazon Ads profile, Authorization carries the bearer token, and the endpoint version pins the payload contract. Keep request and response logging focused on event IDs, status, and validation messages so sensitive identifiers are not exposed in logs.

POST https://advertising-api.amazon.com/offAmazonEvents/2023-11-13/events
Authorization: Bearer Atza|IwEBI...
Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxx
Amazon-Advertising-API-Scope: 1234567890
Content-Type: application/json

{
  "events": [
    {
      "name": "Lead",
      "eventType": "LEAD",
      "eventActionSource": "WEBSITE",
      "timestamp": "2026-04-23T10:17:00Z",
      "clickId": "amzn1.click.abc123",
      "userInfo": {
        "hashedEmail": "f2d2f6b9...",
        "countryCode": "US",
        "postalCode": "10001"
      },
      "eventId": "lead_9821"
    }
  ]
}

Step 5

Handle retries without duplicating conversions

Generate eventId once when TrackLayer receives the original action, then reuse it on every retry. Retry transport failures and 5xx responses with exponential backoff. Do not retry validation errors until the payload is fixed, and do not create new event IDs for the same purchase, lead, or signup just because a worker retried the request.

{
  "retryPolicy": {
    "retry": ["timeout", "429", "500", "502", "503", "504"],
    "doNotRetry": ["400", "401", "403", "422"],
    "idempotencyKey": "eventId",
    "maxAttempts": 5
  }
}

Schema

Required fields

Treat the Amazon event payload as a contract. TrackLayer should normalize event names, identifiers, geographic context, and value before the destination worker runs, then reject incomplete events before they reach Amazon Ads diagnostics.

Field	Requirement
name	Human-readable conversion name such as Purchase, Lead, Signup, Subscribe, or AddToCart.
eventType	Canonical event category used by Amazon Ads, for example PURCHASE, LEAD, SIGN_UP, PAGE_VIEW, or ADD_TO_CART.
eventActionSource	Where the action happened. Use WEBSITE for browser or server-confirmed site events, APP for app events, and keep it stable by event family.
timestamp	Original event time in ISO 8601 format. Preserve the moment the user action occurred, including replay and queue scenarios.
clickId	The amzn_click_id captured from the landing URL and stored first-party. Send when available for deterministic click attribution.
userInfo	Matching identifiers and context: hashedEmail, hashedPhone, madid, countryCode, and postalCode. Hash email and phone after normalization.
value	Revenue object for purchase or subscription value, usually amount plus currencyCode. Omit only for events with no monetary value.

Click ID

amzn_click_id cookie

Capture amzn_click_id on the first landing page and persist it in a first-party cookie with a practical attribution lifetime. Read the cookie when TrackLayer collects later server-confirmed actions, then attach it as clickId. The cookie should be scoped to the site, marked Secure and SameSite=Lax, and cleared or ignored when consent rules require it.

The important detail is timing. A user may click an Amazon ad, browse several pages, sign up, and buy after a payment redirect. If click ID capture happens only on the final conversion page, the identifier is often already gone.

Analytics

AMC integration

Amazon Marketing Cloud can use cleaner off-Amazon conversion streams to support path, audience, and incrementality analysis when your Ads account, datasets, and privacy thresholds allow it. Keep event names, event IDs, timestamps, and value fields stable so AMC queries can join media exposure, click, and conversion activity without destination-specific cleanup.

Validation

Testing

Send a controlled lead

Use one internal test profile, one known amzn_click_id, and one Lead event. Confirm the response accepts the event and logs the eventId you generated.

Validate purchase value

Send a small test purchase with amount, currencyCode, countryCode, postalCode, and hashed identifiers. Check that value formatting survives serialization.

Compare diagnostics against source events

Reconcile accepted, rejected, and retried events against TrackLayer source counts before using the stream for optimization or AMC reporting.

Diagnostics

Troubleshooting

401 invalid access token

Refresh the bearer token with the correct LWA client credentials and refresh_token, then retry with the new token.

403 profile scope mismatch

Confirm Amazon-Advertising-API-Scope equals the profile_id that can access the advertiser and that the app is approved for production Ads API use.

422 invalid userInfo

Normalize email and phone before SHA-256 hashing, include countryCode when postalCode is sent, and avoid blank identifier fields.

Low attributed conversions

Audit amzn_click_id cookie capture, consent filters, timestamp freshness, click ID lifetime, and whether events are firing after checkout redirects.

FAQ

Common questions

Is Amazon Ads CAPI only for Amazon store activity?

No. This guide focuses on off-Amazon events: actions that happen on your site or app after Amazon Ads media drives the user there.

Can I send events without amzn_click_id?

Yes, but click-level attribution will be weaker. Use hashed userInfo and geographic context when consent permits, and treat clickId capture as the primary path when the click ID is available.

Should email and phone be hashed?

Yes. Normalize first, then SHA-256 hash on the server. Do not send raw email or phone in the event payload or write hashed identifiers into client-visible logs.

Where should the integration run?

Run it from a backend route, queue worker, or TrackLayer destination worker. The browser can capture amzn_click_id, but Ads API authentication and event dispatch should stay server-side.

Next reads