Search documentation...

K
ChangelogBook a demoSign up

Facebook Offline Conversions

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

Supported syncing

TypeDescriptionSupported Sync ModesAPI Reference
EventsSync conversion events to Facebook's (Meta) Offline Conversions APIInsertOffline Conversions API reference

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.

App creation in Facebook

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

App creation in Facebook

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

App creation in Facebook

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

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

App creation in Facebook

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

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

App creation in Facebook

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.

System user creation in Facebook

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

System user creation in Facebook

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

System user creation in Facebook

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

Token creation in Facebook

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

To ensure syncs send each event, your event model must use a truly unique primary key. See the events syncs documentation for more information.

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.

Event Set ID

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.

Hightouch sync configuration

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.

Hightouch sync configuration

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

Ready to get started?

Jump right in or a book a demo. Your first destination is always free.

Book a demoSign upBook a demo

Need help?

Our team is relentlessly focused on your success. Don't hesitate to reach out!

Feature requests?

We'd love to hear your suggestions for integrations and other features.

Last updated: Jul 17, 2023

On this page

Supported syncingSetup Offline Conversions APIConnect to Facebook Offline Conversions APISync configurationSyncing eventsTips and troubleshootingCommon errorsLive debuggerSync alerts

Was this page helpful?