Facebook Offline Conversions

Measure how much your Facebook ads lead to real-world outcomes by syncing conversion and product data

Supported syncing

For more information about sync modes, refer to the sync modes docs.

Setup Offline Conversions API

To send offline events via Hightouch, you first need to create an app. You can follow these steps to do so:

1. In Facebook Business Manager, go to Business Settings and open the Apps tab under Accounts.

2. Click Add and select Create a new app ID.

3. Select Other as the use case for the app and click Next.

4. Select Business as the app type and click Next.

5. Add a descriptive name like "Hightouch Offline Events" as the app name and click Create app.

6. This takes you to the app overview page. Copy the App ID to connect it in the Business Manager.

7. Back in Facebook Business Manager and open the Apps tab.

8. Click Add and select Connect an app ID. Enter the app ID you previously copied and click Add app.

Next, you need to grant the app system user access. This lets your app send data to Facebook via the API. To create it:

1. In Business Settings, open the System Users tab under Users and click Add.

2. Enter a System user name and select Admin as the system user role. Click Create system user.

3. From the newly created user, click Generate New Token.

4. Select the app you previously connected and set the token expiration. We strongly recommend indefinite access so you don't need to regenerate the token every 60 days. For Available permissions, select ads_management. Click Generate token.

5. Copy and store the access token in a secure location as it won't be stored by Facebook.

Refer to Facebook's Offline Conversions API Reference for further information on prerequisites for using the API.

Connect to Facebook Offline Conversions API

Go to the Destinations overview page and click the Add destination button. Select Facebook Offline Conversions and click Continue. You can then authenticate Hightouch to Facebook Offline Conversions by entering the Access Token you previously generated into Hightouch.

Sync configuration

Once you've set up your Facebook Offline Conversions destination and have a model to pull data from, you can set up your sync configuration to begin syncing data. Go to the Syncs overview page and click the Add sync button to begin. Then, select the relevant model and the Facebook Offline Conversions destination you want to sync to.

Syncing events

First, enter the event set ID that you want to upload events to. You can find your event set ID from the set's setting's tab.

If you don't have an events set yet, you can create one following these instructions. Make sure the access token you entered has access to this set.

Enter an upload tag, for example, "monthly_uploads" to identify the events. Optionally, you can also enter a namespace identifier. The namespace identifier is the scope used to resolve extern_id or tpid. It can be another data set or data partner ID.

Event timestamp

You can optionally select a column that contains timestamps of when events occurred. If this field is empty, Hightouch uses the time the event arrives at the server. Hightouch syncs the timestamp as the event_time parameter the Conversions API requires.

If you select a column, it should be in ISO 8601 format. Hightouch automatically converts the data to the format Facebook expects.

Field mapping

Field mapping is where you can select which event parameters you want to send to the Offline Conversions API. The API expects the following parameters:

• event_name: Type of event. For example, ViewContent, Search, AddToCart, AddToWishlist, InitiateCheckout, etc.
• currency: Three-letter ISO currency code for this conversion event. Required for Purchase events. For example, USD
• value: Value of conversion event. Required for Purchase events. For example, 16.00.
• match_keys: a set of identifiers to match people for attribution. Examples include email, phone, db, etc. Note that these must be hashed.

The Facebook Offline API accepts strings and arrays of strings for match_keys. For example, you can use values like "jane@example.com" or ["jane@example.com", "john@example.com"] for match_keys.email. The API rejects comma-separated strings, for example, "jane@example.com, john@example.com". Ensure the mapped field is in the correct format.

Hashing

By default, Hightouch automatically hashes the following fields:

• email
• phone
• gender
• doby
• dobm
• dobd
• last name
• first name
• first initial
• city
• state
• zip
• country

If you want to turn hashing off, select No under Would you like Hightouch to automatically detect if your PII data requires hashing?.

Tips and troubleshooting

Common errors

If you encounter an error or question not listed below and need assistance, don't hesitate to reach out. We're here to help.

Event time is older than {...}. Old events can't be submitted

If you receive this error for an event that isn't as old as the error message suggests, it may be because of an incorrect format for the event_timestamp field. Make sure that timestamps are in ISO 8601 format, as described in the event timestamp section above.

Live debugger

Hightouch provides complete visibility into the API calls made during each of your sync runs. We recommend reading our article on debugging tips and tricks to learn more.

Sync alerts

Hightouch can alert you of sync issues via Slack, PagerDuty, SMS, or email. For details, please visit our article on alerting.