Skip to main content

The Yelp Conversions API Program for Offline Conversions

The Yelp Conversions API program enables advertisers to send offline conversion data to Yelp. Yelp performs attribution analysis on the impact of that advertiser’s Yelp campaign on offline conversions. This allows customers to understand how Yelp campaigns drive offline conversions and to find additional data to better optimize ad spend or customer experience. See this one-pager for more information.

The Yelp Conversions API program is a Yelp-paid program, so there is no cost for brands and advertisers.

Note

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

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

Overview of Steps Involved

The following steps need to be performed to enable the attribution analysis in Yelp:

  1. You work with Yelp to start your Yelp ad campaign.

  2. You send offline (in store) conversion data with PII to LiveRamp.

  3. LiveRamp matches the PII to Yelp cookies and mobile device IDs, and then delivers matched data to Yelp.

  4. You request an attribution report with your desired settings.

  5. Yelp generates offline conversion report for the advertiser’s Yelp campaigns.

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

Send Conversion Data to LiveRamp

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

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 conversions with a conversion date in the future.

Format the File

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)

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

  • The conversion action for the transaction.

  • Options for this field:

    • "In-store"

    • "In-app"

    • "Online"

    • "Offline"

transaction_timestamp

Yes

Yes

  • Corresponds to the date/time of transaction.

  • Must be formatted using one of the options listed below:

    • YYYY-MM-DD

    • YYYY-MM-DDTHH:mm:SS

transaction_amount

Yes

Yes

  • Do not include any (currency) symbols, such as dollar signs ($).

  • Format required: XXX.XX

  • Only include USD amounts. If your transaction data contains international currency amounts, convert your amounts to USD prior to sending your data.

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.

property

No

No

The website property or merchant subcategory that the item was purchased from.

custom_fields

No

No

You can include up to 10 custom fields. Custom fields must be placed as the very last column(s) in the file. You must get approval from Yelp and share the details on what will be passed in these columns in advance.

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

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

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

Upload the File

After uploading the first file, email your LiveRamp technical account email alias to confirm that you have uploaded conversion data.

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.

Most customers automate this process to send files on a regular cadence. Contact LiveRamp (yelp@liveramp.com) if you have any questions.

FAQs

At what cadence should I send my conversion data files?

LiveRamp can receive conversion data files for the Yelp Conversions API 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 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.

How long until will it take after I upload my data before I can request a report from Yelp?

Yelp typically delivers reports on a monthly basis however you can work with your Yelp account team if you need more frequent reporting.

Allow up to 15 days from the time you upload the data to receive a report from Yelp.

In this section:

Personally identifiable information (such as name and postal, phone number, or email address) which, on its own or when combined with some other data, can be used to identify an individual.