# Amazon Ads Conversion Export Integration

Amazon Ads Conversion API (CAPI) enables advertisers to send conversion events and customer actions directly from Treasure Data to Amazon Advertising for attribution and measurement purposes. This server-to-server integration bypasses browser limitations and provides more reliable conversion tracking.

The Amazon Ads Conversion Export integration supports Treasure Data users in sending conversion events with enhanced privacy compliance and improved attribution accuracy for Amazon DSP and Sponsored Ads campaigns.

## Prerequisites

- Basic knowledge of Treasure Data
- Basic knowledge of Amazon Ads campaign management and conversion tracking
- Access to Amazon Ads account with conversion API permissions
- Understanding of conversion events and attribution models


## Requirements and Limitations

- At least one customer identifier must be provided per event
- Maximum batch size: 500 events per request
- Events should be sent as close to real-time as possible for optimal attribution
- PII fields must be normalized and SHA-256 hashed according to Amazon's requirements; non-PII identifiers follow Amazon's field-specific requirements


## Static IP Address of Treasure Data Integration

If your security policy requires IP whitelisting, you must add Treasure Data's IP addresses to your allowlist to ensure a successful connection.

Please find the complete list of static IP addresses, organized by region, at the following [document](/apis/endpoints/ip-addresses-integrations-result-workers)

## Use Data Workbench to Create a Connection

In Treasure Data, you must create and configure the data connection before running your query. As part of the data connection, you provide authentication to access the integration.

### Create a New Authentication

Your first step is to create a new authentication with a set of credentials.

1. Select **Integrations Hub**.
2. Select **Catalog**.


![Integrations Hub Catalog](/assets/integrations-hub-catalog.8df5b5674fa8f3c15ebfcca865f1058fb541866c61483999cd59ddb6d527cf95.d34bb0cc.png)

1. Search for **Amazon Ads Conversion** in the Catalog; hover your mouse over the icon and select **Create Authentication**.


![Create Authentication](/assets/create-authentication.088df45cd7f66e73005fd2e9436ac7f52071fda1d7e65e11c9ce900bbf46867e.d34bb0cc.png)

The New Authentication modal displays.

1. Below the OAuth connection field, select the **Click here** link.
2. Log in to your Amazon account to approve OAuth access.
3. On the New Authentication modal, provide this information and select **Continue**.
4. Enter a name for the authentication, and select **Done**.


### Getting the Authentication ID

If you want to use this authentication with Treasure APIs or with the TD Toolbelt, you will need to get its Authentication ID.

To get the Authentication ID:

1. Navigate to **Integrations Hub > Authentications**.
2. Select the integration you want to use. The Edit Authentication modal displays.
3. In the browser address bar, at the end of the URL, note the Authentication ID.


## Define your Query

1. Navigate to **Data Workbench > Queries**.
2. Select **New Query**.
3. From the table drop-down menu, select the database you want to query.
4. Enter your query.


Here is a sample query:


```sql
SELECT   
  'Product Purchase'                AS event_name,              -- required
  'OFF_AMAZON_PURCHASES'            AS conversion_type,         -- required
  'WEBSITE'                         AS event_source,            -- required
  'US'                              AS country_code,            -- required
  purchase_time                     AS event_time,              -- required
  customer_email                    AS email,                   -- conditional (hashed)
  customer_phone                    AS phone,                   -- conditional (hashed)
  customer_first_name               AS first_name,              -- conditional (hashed)
  customer_last_name                AS last_name,               -- conditional (hashed)
  quantity                          AS units_sold,              -- conditional
  purchase_value                    AS value,                   -- optional
  'USD'                             AS currency_code,           -- optional
  order_id                          AS event_id,                -- optional
  product_category                  AS custom_field_1,          -- optional custom data
  customer_segment                  AS custom_field_2           -- optional custom data
FROM   
  conversion_events
WHERE
  TD_INTERVAL(purchase_time, '-1d', 'JST')
```

Here are the required and conditional fields for the query:

| Field | Required | Data Type | Hash Required | Description |
|  --- | --- | --- | --- | --- |
| event_name | Yes | STRING | No | The name of the conversion event |
| conversion_type | Yes | STRING | No | Must be one of: OFF_AMAZON_PURCHASES, ADD_TO_SHOPPING_CART, APPLICATION, CHECKOUT, CONTACT, LEAD, MOBILE_APP_FIRST_START, PAGE_VIEW, SEARCH, SIGN_UP, SUBSCRIBE, OTHER |
| event_source | Yes | STRING | No | Must be one of: ANDROID, FIRE_TV, IOS, OFFLINE, WEBSITE, MEASUREMENT_ATTRIBUTION_PARTNER |
| country_code | Yes | STRING | No | ISO 3166-1 alpha-2 country code (US, CA, JP, etc.) |
| event_time | Yes | STRING/LONG | No | ISO format (YYYY-MM-DDThh:mm:ssTZD) or Unix timestamp |
| email | Conditional | STRING | Yes | Customer email address (SHA-256 hashed) |
| phone | Conditional | STRING | Yes | Customer phone number with country code (SHA-256 hashed) |
| first_name | Conditional | STRING | Yes | Customer first name (SHA-256 hashed) |
| last_name | Conditional | STRING | Yes | Customer last name (SHA-256 hashed) |
| address | Conditional | STRING | Yes | Street address (SHA-256 hashed) |
| city | Conditional | STRING | Yes | City name (SHA-256 hashed) |
| state | Conditional | STRING | Yes | State/province (SHA-256 hashed) |
| postal | Conditional | STRING | Yes | Postal/zip code (SHA-256 hashed) |
| maid | Conditional | STRING | No | Mobile advertising ID |
| match_id | Conditional | STRING | No | Custom match identifier |
| units_sold | Conditional | LONG | No | Only for conversion_type is OFF_AMAZON_PURCHASES |
| value | No | STRING/LONG/DOUBLE | No | Conversion value (numeric) |
| currency_code | No | STRING | No | Only for conversion_type is OFF_AMAZON_PURCHASES. Must be one of: AED, AUD, BRL, CAD, CNY, DKK, EUR, GBP, INR, JPY, MXN, NOK, NZD, SAR, SEK, SGD, TRY, USD |
| event_id | No | STRING | No | Unique identifier for deduplication |
| partner | Conditional | STRING | No | Required if event_source is MEASUREMENT_ATTRIBUTION_PARTNER |
| amazon_ad_event_key | Conditional | STRING | No | Required if event_source is MEASUREMENT_ATTRIBUTION_PARTNER |


Customer Identifier Requirements
At least one customer identifier field (email, phone, first_name, last_name, address, city, state, postal, maid, or match_id) must be provided. Email or phone number is preferred for best matching accuracy.

## Specify the Result Export Target

Configure the conversion export settings to send events to Amazon Ads.

1. Using the Treasure Console, perform steps 1-4 from the "Define your Query" section above.
2. Select **Export Results**.
3. Select the integration you created for Amazon Ads Conversion.


The Export Results modal displays.

![Export Results Model Part 1](/assets/export-results-modal-1.a3f175f17f8d00d064e6443a2d926b61b058fc24ec6cc0dee0a92cb277b70e9c.d34bb0cc.png)

![Export Results Model Part 2](/assets/export-results-modal-2.5cee48b92b0260b172d582a23aef1a67169623a3435502015fe4ee95e92bb20c.d34bb0cc.png)

1. Enter your information into the fields:


| Field | Description | Note |
|  --- | --- | --- |
| Region | Amazon Ads API region for your account | Required. Options: North America (NA), Europe (EU), Far East (FE) |
| Advertiser ID | Your Amazon DSP Advertiser account ID | Required. Found in your Amazon Ads account settings |
| Dataset Name | Amazon dataset identifier (optional) | Optional. Used for organizing conversion data in Amazon's system |
| Custom Data | Field mappings for custom event data | Optional. Format: field_name: DATA_TYPE (STRING, INTEGER, TIMESTAMP) |
| Consent Type | Privacy consent framework to use | Optional. Options: TCF, GPP, ACS |
| Skip Invalid Records | Continue processing when encountering invalid data | Optional. If disabled, job stops on invalid records |
| Skip Error Batches | Continue processing when batch fails | Optional. If disabled, job stops on batch errors |


1. Select **Done**.


## Example Result


```
************* REPORT *************
2026-04-14 04:34:30.320 +0000 [INFO] (0017:task-0000): ************* REPORT *************
2026-04-14 04:34:30.320 +0000 [INFO] (0017:task-0000): Total records: 1, total skip records: 0, total batches: 1, total skip batches: 0
```

### (Optional) Schedule Query Export Jobs

You can use Scheduled Jobs with Result Export to periodically write the output result to a target destination that you specify.

Treasure Data's scheduler feature supports periodic query execution to achieve high availability.

When two specifications provide conflicting schedule specifications, the specification requesting to execute more often is followed while the other schedule specification is ignored.

For example, if the cron schedule is `'0 0 1 * 1'`, then the 'day of month' specification and 'day of week' are discordant because the former specification requires it to run every first day of each month at midnight (00:00), while the latter specification requires it to run every Monday at midnight (00:00). The latter specification is followed.

#### Scheduling your Job Using Treasure Console

1. Navigate to **Data Workbench > Queries**
2. Create a new query or select an existing query.
3. Next to **Schedule**, select None.
![](/assets/image2021-1-15_17-28-51.f1b242f6ecc7666a0097fdf37edd1682786ec11ef80eff68c66f091bc405c371.0f87d8d4.png)
4. In the drop-down, select one of the following schedule options:
![](/assets/image2021-1-15_17-29-47.45289a1c99256f125f4d887e501e204ed61f02223fde0927af5f425a89ace0c0.0f87d8d4.png)
| Drop-down Value | Description |
|  --- | --- |
| Custom cron... | Review [Custom cron... details](#custom-cron-details). |
| @daily (midnight) | Run once a day at midnight (00:00 am) in the specified time zone. |
| @hourly (:00) | Run every hour at 00 minutes. |
| None | No schedule. |


#### Custom cron... Details

![](/assets/image2021-1-15_17-30-23.0f94a8aa5f75ea03e3fec0c25b0640cd59ee48d1804a83701e5f2372deae466c.0f87d8d4.png)

| **Cron Value** | **Description** |
|  --- | --- |
| `0 * * * *` | Run once an hour. |
| `0 0 * * *` | Run once a day at midnight. |
| `0 0 1 * *` | Run once a month at midnight on the morning of the first day of the month. |
| "" | Create a job that has no scheduled run time. |



```
 *    *    *    *    *
 -    -    -    -    -
 |    |    |    |    |
 |    |    |    |    +----- day of week (0 - 6) (Sunday=0)
 |    |    |    +---------- month (1 - 12)
 |    |    +--------------- day of month (1 - 31)
 |    +-------------------- hour (0 - 23)
 +------------------------- min (0 - 59)
```

The following named entries can be used:

- Day of Week: sun, mon, tue, wed, thu, fri, sat.
- Month: jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec.


A single space is required between each field. The values for each field can be composed of:

div
| Field Value  | Example  | Example Description  |
|  --- | --- | --- |
| A single value, within the limits displayed above for each field. |  |  |
| A wildcard `'*'` to indicate no restriction based on the field. | `'0 0 1 * *'` | Configures the schedule to run at midnight (00:00) on the first day of each month. |
| A range `'2-5'`, indicating the range of accepted values for the field. | `'0 0 1-10 * *'` | Configures the schedule to run at midnight (00:00) on the first 10 days of each month. |
| A list of comma-separated values `'2,3,4,5'`, indicating the list of accepted values for the field. | `'0 0 1,11,21 * *'` | Configures the schedule to run at midnight (00:00) every 1st, 11th, and 21st day of each month. |
| A periodicity indicator `'*/5'` to express how often based on the field's valid range of values a schedule is allowed to run. | `'30 */2 1 * *'` | Configures the schedule to run on the 1st of every month, every 2 hours starting at 00:30. `'0 0 */5 * *'` configures the schedule to run at midnight (00:00) every 5 days starting on the 5th of each month. |
| A comma-separated list of any of the above except the `'*'` wildcard is also supported `'2,*/5,8-10'`. | `'0 0 5,*/10,25 * *'` | Configures the schedule to run at midnight (00:00) every 5th, 10th, 20th, and 25th day of each month. |


1. (Optional) You can delay the start time of a query by enabling the Delay execution.


### Execute the Query

Save the query with a name and run, or just run the query. Upon successful completion of the query, the query result is automatically exported to the specified destination.

Scheduled jobs that continuously fail due to configuration errors may be disabled on the system side after several notifications.

(Optional) You can delay the start time of a query by enabling the Delay execution.

## (Optional) Configure Export Results in Workflow

Within Treasure Workflow, you can specify the use of this integration to export conversion data.


```yaml
_export:
  td:
    database: td.database
   
+ amazon_ads_conversion_export_task:
  td>: export_conversions.sql
  database: ${td.database}
  result_connection: amazon_ads_conversion_auth
  result_settings:
    type: amazon_ads_conversion
    td_authentication_id: td_authentication_id
    region: NA
    advertiser_id: advertiser_id
    dataset_name: conversion_dataset
    custom_data: product_category:STRING,customer_segment:INTEGER
    consent_type: ACS
    amzn_ad_storage: GRANTED
    amzn_user_data: GRANTED
    limited_data_use: false
    skip_invalid_record: true
    skip_error_batch: false
```

## (Optional) Export Integration Using the CLI

You can also use the [TD Toolbelt](/tools/cli-and-sdks/quickstart) to export conversion events to Amazon Ads using the td query command with the --result option.

The data specified with the --result option is in JSON format:


```json
{
  "type": "amazon_ads_conversion",
  "td_authentication_id": "${authentication_id_from_td_console}",
  "region": "NA",
  "advertiser_id": "your_advertiser_id",
  "dataset_name": "conversion_dataset",
  "custom_data": "product_category:STRING,customer_segment:INTEGER",
  "consent_type": "ACS",
  "amzn_ad_storage": "GRANTED",
  "amzn_user_data": "GRANTED",
  "limited_data_use": false,
  "skip_invalid_record": true,
  "skip_error_batch": false
}
```

### Parameters

| Name | Description | Value | Default Value | Required |
|  --- | --- | --- | --- | --- |
| type | The destination of the export | "amazon_ads_conversion" |  | Yes |
| td_authentication_id | The authentication ID for Amazon Ads authentication in Treasure Console |  |  | Yes |
| region | Amazon Ads API region | "NA", "EU", "FE" | "NA" | Yes |
| advertiser_id | Your Amazon DSP Advertiser account ID |  |  | Yes |
| dataset_name | Amazon dataset identifier |  |  | No |
| custom_data | Custom field mappings | "field_name:DATA_TYPE,field_name2:DATA_TYPE" |  | No |
| consent_type | Privacy consent framework | "TCF", "GPP", "ACS" | Empty | No |
| tcf | TCF consent value |  |  | Yes if consent_type is "TCF" |
| gpp | GPP consent value |  |  | Yes if consent_type is "GPP" |
| amzn_ad_storage | Amazon ad storage consent | "GRANTED", "DENIED" |  | Yes if consent_type is "ACS" |
| amzn_user_data | Amazon user data consent | "GRANTED", "DENIED" |  | Yes if consent_type is "ACS" |
| limited_data_use | Enable limited data use processing | true, false | false | No |
| skip_invalid_record | Continue processing invalid records | true, false | false | No |
| skip_error_batch | Continue processing error batches | true, false | false | No |


### Usage Examples

Manual export:


```bash
td query \
--database ${database_name} \
--wait "SELECT * FROM ${conversion_table}" \
--type presto \
--result '{"type":"amazon_ads_conversion","td_authentication_id":"${auth_id}","region":"NA","advertiser_id":"${advertiser_id}","dataset_name":"conversions","skip_invalid_record":true}'
```

Scheduled export:


```bash
td sched:create \
conversions_to_amazon_ads '0 2 * * *' \
--database ${database_name} 'SELECT * FROM ${conversion_table}' \
--result '{"type":"amazon_ads_conversion","td_authentication_id":"${auth_id}","region":"NA","advertiser_id":"${advertiser_id}"}'
```

## Troubleshooting

### Common Issues

- **Authentication errors**: Verify OAuth permissions include conversion API access
- **Data validation errors**: Ensure all required fields are present and at least one customer identifier is provided
- **Hash format errors**: Customer PII must be properly normalized and SHA-256 hashed following Amazon's guidelines
- **Rate limiting**: Amazon enforces API rate limits; implement appropriate delays between batch uploads
- **Missing customer identifiers**: At least one of email, phone, or other PII fields must be provided per event


### Error Handling

| Error Type | Action | Retry |
|  --- | --- | --- |
| Missing required parameters | Fix configuration, job fails | No |
| Invalid data types | Fix query, job fails | No |
| HTTP 4xx errors | Check API documentation, job fails | No |
| HTTP 429/5xx errors | Job retries automatically | Yes |


## External References

- [Amazon Ads Conversion API Overview](https://advertising.amazon.com/API/docs/en-us/guides/conversions/01-overview)
- [Amazon Ads Events API Documentation](https://advertising.amazon.com/API/docs/en-us/guides/events/events#send-events)
- [Pass Customer Information through Conversions API](https://advertising.amazon.com/help/GH2LNLGJUCECRCK2)
- [Amazon Ads API Onboarding Guide](https://advertising.amazon.com/API/docs/en-us/guides/overview)