Skip to main content

The StackAdapt Conversions API Program for Offline Conversions

The StackAdapt Conversions API Program for Offline Conversions enables advertisers to send offline conversion data to StackAdapt. StackAdapt performs attribution analysis on the impact of the advertiser’s StackAdapt campaign on offline conversions. This allows customers to understand how StackAdapt campaigns drive offline conversions and to find additional data to better optimize ad spend or customer experience.

Use this program to understand Sales Attribution and Lift Insights on the StackAdapt platform.

Note

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

  • The StackAdapt Conversions API Program for Offline Conversions was formerly known as "the StackAdapt Attribution Program".

Overview of Steps Involved

The following steps need to be performed for each campaign to enable the attribution analysis in StackAdapt:

  1. You send LiveRamp a sample conversion data file.

  2. You activate your campaigns on StackAdapt.

  3. LiveRamp creates an additional LiveRamp Connect account for the purpose of uploading your conversion data.

  4. You upload conversion data from the last 90 days to LiveRamp.

  5. LiveRamp matches your PII to RampIDs and sends it to StackAdapt along with your transaction data.

  6. You work with your StackAdapt representative to complete the process in order to access your attribution reports.

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

Format the Conversion Data File

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 conversions 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 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)

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

zip

Yes

Yes (if NAP is used as an identifier)

  • Zipcodes 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 hash 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

  • A category or segment that the transaction is in (for example, “Store Sales”).

transaction_timestamp

Yes

Yes

  • Corresponds to the date/time of transaction in UTC - (example “2017-02-07T13:25:00Z-0800" 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 h:mm:ss aa

    • MM,dd,yyyy h:mm:ss

    • MM/dd/yyyy HH:mm:ss

    • yyyy-MM-dd HH:mm:ss

    • yyyy-MM-dd'T'HH:mm:ss

    • yyyy-MM-dd HH:mm:ssZ

    • yyyy-MM-dd

transaction_amount

Yes

Yes

  • The transaction amount.

  • 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.

store_id

No

No

  • A unique ID that clients assign to each of their store locations.

  • Must not be longer than 64 characters.

  • Must not special characters (i,e., "<" or ">") or a URL.

quantity

No

No

  • The number of items purchased.

brand

No

No

  • The name of the brand.

region

No

No

  • The region where the transaction occurred (for example, “New York”).

  • Must use full state names (for example, “California” instead of “CA”).

department

No

No

  • The department for the product.

product_id

No

No

  • An alphanumeric value delineating a unique item in an order, such as a SKU or UPC. For example, if three socks are purchased in one transaction, you could have three transaction rows with different product IDs for each pair of socks but the same order ID.

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

product_name

No

No

  • Short name of the product.

product_category

No

No

  • Top-level category of the product.

product_subcategory

No

No

  • Subcategory of the product.

product_brand

No

No

  • Brand name of the product.

product_price

No

No

  • The product price.

  • Do not include currency symbols. (for example, “XX.XX”).

promo_code

No

No

  • Promotion code that was used for the purchase.(for example, “XX123”).

GTIN

No

No

  • Product GTIN.

custom_#

No

No

  • Can include up to 10 custom fields.

  • Custom field column headings must start with "custom_", followed by the field name. For example "custom_customer_type".

Header Row Example

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|

Conversion Data Examples

Alex|Chen|44 Main Street|#12|San Francisco|CA|94101|4371|alex@gmail.com|ac@ymail.com|||New Customer|2017- 02-07T13:25:00Z|99.99|5551234567|4152234123|USA|California|In-store|Bayfair Mall

Julian|Rogers|55 Mission Street||San Francisco|CA|94500|8435|julian@gmail.com||||Active Customer|2017- 03-07T15:15:00Z|127.18|5559994567

Send Conversion Data to LiveRamp

To set up the integration, send us a sample conversion data file. This file should contain at least 25 rows and each row should have values for the required fields (you can use placeholder data). Include all the possible transaction category values you plan on using in the “transaction_category” field and include only those values in subsequent files.

Once your campaign has started, send conversion data to LiveRamp at your preferred cadence. Files can be delivered at any cadence (daily, weekly, monthly, etc.), but do not send more than one file per day. LiveRamp’s preference is daily or weekly as this is a common requirement for other conversions programs.

Tip

Most customers automate this process to send files on a regular cadence.

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

Other optional conversion data (such as product data or quantity) can be included as well. See the “Format the Conversion Data File” section above for more information.

Make sure to also follow these additional guidelines:

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

  • Do not include transactions that exceed the lookback window. All transactions sent to LiveRamp must have been created in the last 90 days.

  • Do not include conversions with a conversion date in the future.

  • Do not include conversion data that has already been sent in a previous file.

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 the this program cannot be uploaded via Connect. We recommend either uploading via our SFTP server, or having us pull files from an S3 bucket or GCS bucket.

After uploading, contact your Customer Implementation specialist to confirm that you have uploaded conversion data. The Customer Implementation specialist will ensure that the file is processed, and will instruct you where to upload future files.

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 Connect (see "Check File Processing Status" for more information).

Most customers automate this process to send files on a regular cadence. Confirm your upload cadence with your Customer Implementation specialist.

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?

LiveRamp can receive conversion data files for this conversions program on a daily, weekly, or monthly basis, but we highly suggest automated daily delivery as it gives LiveRamp the greatest ability to match. If you prefer not to send daily files, the next best option is weekly delivery as this enables data to be reported within the same month.

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

Include all traceable offline transactions in your delivery. Do not include transactions with a transaction date in the future.

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:

LiveRamp's universal, pseudonymous identifier that is tied to devices in the LiveRamp Identity Graph.