Skip to main content

The Amazon Conversions API Program for Offline Conversions

The Amazon Conversions API Program for Offline Conversions allows clients to send offline conversion data to Amazon Ads DSP events manager. This allows customers to understand how Amazon campaigns drive offline conversions and provides an additional piece of data to help optimize ad spend or customer experience.

With the Amazon Conversions API Program, you can measure how your Amazon ads lead to real-world outcomes, such as in-store interactions, purchases, and more. To help you understand the effectiveness of your ad campaigns, Amazon matches your uploaded offline events with metrics from people who have interacted (viewed or clicked) your Amazon ad campaigns, both on and off Amazon properties, through orders in Amazon DSP.

Use this to:

  • Track offline conversion activity, and measure and evaluate your Amazon ad campaigns, both on and off Amazon properties.

  • Measure the offline return on your ad spend.

  • Optimize your overall Amazon ads strategy based on non-Amazon conversion signals, including media, creative, path to purchase.

  • Refine audience strategy across Amazon properties based on the above results.

The Amazon Conversions API Program for Offline Conversions is an Amazon paid program, so there is no cost for brands and advertisers.

Note

Amazon must approve all program participants. Contact your LiveRamp or Amazon representative to find out about getting approved for the Amazon Conversions API Program for Offline Conversions.

Overview of Steps Involved

The following steps need to be performed to enable the attribution analysis and in-flight optimization in Amazon:

  1. You log into your Amazon Ads DSP account and create conversions definitions for each event type you would like to track.

  2. You upload a sample conversion data file to LiveRamp.

  3. You provide your Amazon Entity ID, Amazon Account ID, and Amazon Conversions Definition IDs to your LiveRamp technical representative.

  4. You grant LiveRamp the ability to deliver data to your Amazon Ads DSP account by activating an Amazon Conversions API destination account in LiveRamp Connect (based on your respective region), which includes performing OAuth authorization.

  5. You activate your campaign.

  6. You upload your daily conversion data.

  7. LiveRamp matches the PII to RampIDs and delivers matched data to Amazon via their Conversions API.

  8. Once results are available, typically within 24 hours from upload/delivery, you view the results within Amazon's Campaign Manager.

See the appropriate sections below for more information on performing these steps.

Amazon Requirement

Advertisers must have a self-service account. Managed service accounts will be supported in 2H 2024.

Accept the Terms and Conditions in the Amazon DSP Console

Advertisers must accept the Conversion tracking terms and conditions (T&Cs) in the Amazon DSP Console.

To accept the T&Cs:

  1. In the Amazon DSP console, go to Campaign Manager > Events manager > Conversions tab.

  2. On the Conversion tracking terms and conditions dialog, click Agree and continue to accept. If the T&Cs dialog does not display, this means the T&Cs have already been accepted.

    1. For information, see Advertiser Audience Agreement.

Create Conversion Definition IDs in the Amazon DSP Console

To create conversions definition IDs:

  1. In the Amazon DSP console, go to Campaign Manager > Events manager > Add conversion.

  2. Select Conversions API and click Next.

  3. Fill in the form (repeat for each event).

    1. Conversion name: Advertiser-defined conversion name - (required)

    2. Source types: Website, Offline, iOS, Android, Fire TV - (required)

    3. Conversion types - (required)

      • Possible values:

        • Add to shopping cart

        • Application

        • Checkout

        • Contact

        • Lead

        • Off-Amazon purchases

        • Other

        • Page View

        • Search

        • SignUp

        • Subscribe

      • The request schema is the same for all conversion types

    4. Default conversion value - (optional)

      • This value is only used when a value is not provided on the event.

    5. Count method - (optional)

      • 'Count every conversion' setting will process every conversion received.

      • 'Count only the first conversion', will process only the first conversion per user per 24 hours.

      • Subsequent events from the same user within a 24 hour window will not be processed.

      • Default is to 'count every conversion'.

  4. Conversion definitions are generated and each will have an assigned identifier.

The resulting conversion definitions will each be assigned an ID, also referred to as the conversionDefinitionId.

Provide Conversion Categories to LiveRamp

Once you’ve created your Conversion Definition IDs in the Amazon DSP, provide your LiveRamp Implementation Manager with a list of the Conversion Definitions IDs mapped to the transaction_category values in your conversion file.

Note

  • The values you provide in the transaction_category field in the files you upload are used to map to the Conversions Definition IDs.

  • Multiple transaction_category values can be mapped to one Conversion Definition ID.

Mapping Example:

transaction_category Value

Conversions Definition IDs

In Store

12345

New Customer

54321

Existing Customer

23456

Activate an Amazon Conversions API Destination Account

To distribute offline conversions data, an Amazon user who has Amazon DSP (a Campaign Manager with full access or an Admin) will need to activate an Amazon CAPI - Offline destination account in Connect.

During destination account activation, you will need to perform OAuth authorization for that destination account, either by selecting an existing OAuth connection or by creating a new connection. This grants LiveRamp access to your Amazon DSP Account in order to deliver data to your account.

Follow the general instructions in "Activate a New Destination Account", performing these additional steps:

  1. Remove the end date to leave the end date open ended.

  2. Contact your Amazon account ID.

  3. In the Destination Account Name field, pick a unique and memorable name for this account. We'll suggest one for you but you can use any name you wish as long as it is less than 50 characters in length.

  4. To use one of your existing Amazon OAuth connections, select it from the OAuth Connection drop-down list and click Validate OAuth Connection.

  5. To create a new OAuth connection and validate that connection:

    1. From the OAuth Connection drop-down list, select + New Amazon OAuth Connection.

    2. From the new window that opens with Amazon's sign in or login screen, enter your credentials and then click Sign in.

  6. Click Validate OAuth Connection.

Format the File

Before sending your sample data or your conversion data to LiveRamp, make sure to strictly follow the guidelines listed below:

Note

Caution

If an uploaded file does not meet these requirements, you will need to reformat the file until it is formatted correctly.

  • Headers must be included in the exact order as listed below and must match exactly.

  • This program uses our Measurement Enablement Workflow. Make sure to follow our Product Limits and Guidelines for Measurement Enablement workflow files (such as a maximum of 500,000,000 rows per file and a maximum uncompressed file size of 50 GB).

  • Fields must not have leading or trailing white space.

  • Your conversion data file must use one of our allowed delimiters (commas, tabs, or pipes), and be one of our allowed file types (.csv, .tsv, .psv, or .txt).

  • Include all of the required columns listed below.

  • Unless values are required for a field, fields can be left blank if there is no data for the given row (do not include “N/A” or “null”).

  • The file must be rectangular. That is every row must have the same number of delimiters and columns of data.

Tip

To download an Excel file template that contains all possible columns and formatting instructions, click here.

After transferring your data into the file template, be sure to delete the row with the formatting instructions and save the file in one of our allowed file types (.csv, .tsv, .psv, or .txt) before uploading.

Once the file has been formatted correctly, upload the file to LiveRamp. See the “Upload the File” section below for more information.

Note

Once you set up the file format for an existing attribution program feed, try to keep the file format (such as the column headers or the column order) the same for all subsequent files. If you change the file format for an existing feed, create a support case before uploading the new file to ensure your existing attribution feeds are not impacted. For more information, see "Changing the Format of an Existing File".

List of All File Columns

See the table below for a list of columns and formatting instructions:

Field Name

Column Required?

Values Required?

Notes

first_name

Yes

Yes (if name and postal address (NAP) is used as an identifier)

last_name

Yes

Yes (if NAP is used as an identifier)

address_1

Yes

Yes (if NAP is used as an identifier)

address_2

Yes

No

  • Include values in this column if you have additional street address info for a given row.

city

Yes

Yes (if NAP is used as an identifier)

state

Yes

Yes (if NAP is used as an identifier)

  • Must be a two-character, capitalized abbreviation ("CA", not "California" or "Ca").

zip

Yes

Yes (if NAP is used as an identifier)

  • ZIP codes can be in 5-digit format or 9-digit format (ZIP+4).

email_1

Yes

Yes (if email address is used as an identifier)

  • Can be plaintext or one of our allowed has types (SHA-256, MD5, or SHA-1).

  • If you have multiple emails for a consumer, send your best one in the “email_1” column.

email_2

Yes

No

  • Can be plaintext or one of our allowed hash types (SHA-256, MD5, or SHA-1).

email_3

Yes

No

  • Can be plaintext or one of our allowed hash types (SHA-256, MD5, or SHA-1).

email_4

Yes

No

  • Can be plaintext or one of our allowed hash types (SHA-256, MD5, or SHA-1).

transaction_category

Yes

Yes

  • Enter a free text "transaction category" value in this field for each transaction row, such as something like "store sales".

    Note: These transaction category values will be mapped to the definition IDs above. Do not provide the definition IDs as the value, as they will not work with other programs.

transaction_timestamp

Yes

Yes

  • Corresponds to the date/time of transaction in UTC - (example “2017- 02-07T13:25:00Z” - should be the time the conversion happened in UTC).

  • Standard formats:

    • yyyy-MM-dd

    • yyyy-MM-dd'T'HH:mm:ss'Z'-0000 (for example, 2021-06-04T10:01:00Z-0000)

  • Additional formats:

    • MM/dd/yyyy hh:mm:ss aa

    • MM/dd/yyyy HH:mm:ss

    • yyyy-MM-dd HH:mm:ss

    • yyyy-MM-ddTHH:mm:ss

    • yyyy-MM-dd HH:mm:ss+z

    • yyyy-MM-ddTHH:mm:ss+z

transaction_amount

Yes

Yes

  • Do not include any (currency) symbols.

  • Format required: XXX.XX

phone_1

Yes

Yes (if phone number is used as an identifier)

  • Do not include any hyphens or parentheses.

  • Can be plaintext or SHA-1 hashed.

  • If you have multiple phone numbers for a consumer, send your best one in the “phone_1” column.

phone_2

Yes

No

  • Do not include any hyphens or parentheses.

  • Can be plaintext or SHA-1 hashed.

order_id

Yes

Yes

  • A unique ID (such as a transaction ID) that corresponds to the order that the particular item belongs to (this is often referred to as an “ordinal”). If the value is not unique, a partner may deduplicate some of these events when ingesting your conversion data.

  • To measure item-level events, the value will need to be a unique value for each item within a basket. LiveRamp recommends using the concatenated value of the order ID + product SKU. For example, if the  order ID is “123” and SKU is “456”, the “order_id” value would be “123456”.

  • Do not include special characters, currency symbols, or commas.

quantity

No

No

  • The number of items purchased.

data_processing_options

Yes

Yes

  • Enter a value of "LDU" if a transaction is tied to where a person has opted out of the sale of data or that the business has opted to have Amazon process data as a service provider.

  • Enter the value "non-ldu" to indicate that LiveRamp should upload data to Amazon with the LDU mode disabled.

Header Row Example

The headers shown below are all required.

first_name|last_name|address_1|address_2|city|state|zip|email_1|email_2|email_3|email_4|transaction_category|transaction_timestamp|transaction_amount|phone_1|phone_2|order_id| data_processing_options

Conversion Data Examples

Alex|Chen|44 Main Street|#12|San Francisco|CA|94100|alex@gmail.com|ac@ymail.com|||In-store|2014-03-31|99.99|4157892314|4156438224|58239|LDU

Julian|Roodiger|55 Mission Street||San Francisco|CA|94500|julian@gmail.com||||Offline|2014-03-30|55.55|4159032427|4157823435|67324|non-ldu

Send Conversion Data to LiveRamp

If you’re not currently using another LiveRamp Conversions API program (such as Bing or Yelp), we will need you to send us sample conversion data to set up the integration.

Caution

Most platforms require that at least 1,000 unique transaction events be uploaded over a 28-day period.

Conversion Data Guidelines

Each conversion data record must include at least one PII identifier (name and postal address, email, or phone) and the required conversion data:

  • Transaction category

  • Transaction timestamp

  • Transaction amount

  • Order ID

Conversion data should be uploaded within 7 days of the conversion.

Upload the File

Upload conversion data files using LiveRamp’s SFTP server or your SFTP server.

You can also have us pull files from an AWS S3 bucket or GCS bucket. See “Getting Your Data Into LiveRamp” for more information.

Caution

Files for this conversions program cannot be uploaded via Connect.

Note

For future uploads, you do not have to email LiveRamp to confirm that you have uploaded data assuming headers have not changed or additional columns have not been added.

Once the file is uploaded, information on file processing status can be viewed in LiveRamp Connect (see "Check File Processing Status" below for more information).

After Amazon has ingested the conversion data, you will see your attribution report within Amazon DSP.

Check File Processing Status

You can check the status of the files you've uploaded on the Files page in Connect. See "Check the Status of an Uploaded File" for complete instructions.

Note

  • Once you've uploaded a file, it can take up to 20 minutes before the file appears associated with the appropriate audience(s) on the Files page. If the file does not appear after at least 20 minutes, create a support case.

  • Files for this program use our Measurement Enablement workflow, and so the column headings that display on the Files page will look different from the ones that display for files that use our Activation workflow.

FAQs

At what cadence should I send my conversion data files?

Send conversion data files to LiveRamp daily or at the latest every 3 days. This is required in order to support Amazon's 14 day attribution window.

What conversion data should I include in my conversion data file?

  • Include all traceable offline transactions in your delivery. Do not include online transaction data.

  • Avoid sending duplicate transactions (transactions already sent to LiveRamp). If you send daily files, only include transactions that occurred on that day. If you send weekly or monthly files, only send transactions that occurred since the previous file was sent.

  • Do not include transactions with a transaction date in the future.

In this section: