The Conversions API is Meta’s recommended integration method for sending offline and physical store events to Meta for use in ad measurement, attribution, and targeting. This page details how to send offline events via a Conversions API direct or partner integration.
Offline events sent through the Conversions API must be associated with a dataset.
Datasets allow advertisers to connect and manage event data from web, app, store and business messaging event sources to the Conversions API. Datasets may show event data from any of these integrations that you choose to set up:
Datasets enable you to view all customer activities from a single interface. They also allow you to reduce the effort to build and maintain multiple API integrations.
In Events Manager, advertisers have different options to create a dataset depending on their starting point. Or you can create a brand new dataset in Events Manager by linking during offline event set creation or through an existing mobile app or during messaging event set creation information. Note that linking a dataset to an application is required before sending mobile app events to the Conversions API and only one application can be linked to a dataset. See more details and instructions here.
You can make the GET
call to https://graph.facebook.com/v16.0/{ads-pixel-id}/?fields=is_consolidated_container to detect if the advertiser’s dataset is consolidated and thus eligible for passing offline events using the Conversions API.
Advertisers can use the setup mentioned here and refer to the current set of parameters that can be sent over the Conversions API. For sending offline and store events, the following fields can be shared in the payload:
action_source
as physical_store
for all offline and store events. Note that this parameter is required for all server event types. By using the Conversions API, you agree that the action_source
parameter is accurate to the best of your knowledge.upload_tag
parameter is still supported for offline event uploads for advertisers using legacy API for offline events.The following list contains customer information parameters that are typically used for offline and store events:
Parameter names | Parameter | Hashing required |
---|---|---|
Email Address(es) |
| YES |
Phone Number(s) |
| YES |
Gender |
| YES |
Date of Birth |
| YES |
Last Name |
| YES |
First Name |
| YES |
City |
| YES |
US States |
| YES |
Zip codes |
| YES |
Country |
| YES |
Mobile Advertiser ID |
| Do not hash The advertising ID from an Android device or the Advertising Identifier (IDFA) from an Apple device. |
Third-party user id |
| Highly recommended |
The lead id from Lead Ads |
| Do not hash |
The following section contains common custom parameters used by offline and store events. For more custom data fields, please refer to the full list we accept for Conversions API in the following link.
Parameter | Description |
---|---|
type: integer | Required The UNIX timestamp of the conversion event. Example: |
| Required Type of event. Example: |
| Required Three-letter ISO currency code for this conversion event. Required for Example: |
| Required Value of conversion event. Required for Example: |
| Optional Any valid Advantage+ catalog ads Example: |
type: JSON array | Optional. Required if you integrate your ads with catalog. Required: Recommended: Required: Recommended: |
type: JSON dictionary | Optional. Information about this conversion event. Example: |
type: string | Optional. Unique identifier for each transaction or order in an offline event set. For example, for retail this can be a receipt ID. Example: |
type: string | Optional. Unique identifier to distinguish events within the same order or transaction. Example: |
To send new events, make a POST
request to the Conversions API from this path: https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN}
When you post to this edge, Meta creates new offline and store events. For more details, please refer to the following developer document.
Here is an overview of how the parameters fit into the overall schema in the payload:
curl -X POST \ -F 'data=[ { "event_name": "Purchase", "event_time": 1674000041, "user_data": { "em": [ "309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd" ], "ph": [ "254aa248acb47dd654ca3ea53f48c2c26d641d23d7e2e93a1ec56258df7674c4", "6f4fcb9deaeadc8f9746ae76d97ce1239e98b404efe5da3ee0b7149740f89ad6" ] }, "custom_data": { "currency": "usd", "value": 123.45, "contents": [{ "id": "product123", "quantity": 1 }] }, "action_source": "physical_store" } ]' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v15.0/<DATASET_ID>/events
We recommend uploading in real time or on a daily basis for optimal optimization results so that offline data can be effectively matched against the performance of any ads you're running.
The event_time
can be up to 7 days before you send an event to Meta. If any event_time
in data
is greater than 7 days in the past, we return an error for the entire request and process no events. For offline and physical store events with physical_store
as action_source
, you should upload transactions within 62 days of the conversion.
The data you upload is processed in real time so you can usually view results as soon as you add it. You can refer to the Help Center document about Best Practices for Offline events data.
Unlike deduplication set up across Conversions API and Meta Pixel events, offline events can be deduplicated against other offline events only. We support two methods of deduplication: order_id based or user based. The deduplication uses the combination of fields: dataset_id
, event_time
, event_name
, item_number
, and the key field based on method in the given event’s payload.
The default deduplication uses order_id with a combination of the fields above. If order_id is not present in the payload, the user based deduplication logic will be used.
For example, where there are two orders with identical event_time
, event_name
having the same order_id or same set of Customer Information Parameters without order_id, we will consider them duplicate events and take the first event. The user based deduplication method only works with the same Customer Information Parameters fields in the two payloads.
The maximum deduplication window is 7 days.
You can use the Payload Helper tool to generate payload data:
physical_store
action source when applicable. By using the Conversions API, you agree that the action_source
parameter is accurate to the best of your knowledge.Use the Test Events tool in Events Manager for testing. Please note that the Test Events tool only supports web and app events.