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.

Prerequisites

Dataset

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:

Meta Pixel (website events)

App Events API (app events, including Facebook SDK for iOS or Android, mobile measurement partners (MMPs))

Offline Conversions API (Meta’s legacy API for offline events)

Messaging Events API (messaging events)

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.

Permissions

To implement a direct integration as an advertiser, please follow the instructions here for prerequisites and permissions.

To implement a partner platform integration, please follow the instructions here for prerequisites and permissions.

Configuration

1. Set Up Offline Event Parameters

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:

Advertisers need to send 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.

All required server event fields for Conversions API must be respected.

Customer information parameters (see below for appropriate list of parameters for offline and store events).

Custom data parameters (see below for appropriate list of parameters for offline and store events).

Optional parameter: the upload_tag parameter is still supported for offline event uploads for advertisers using legacy API for offline events.

Customer Information Parameters

The following list contains customer information parameters that are typically used for offline and store events:

Parameter names	Parameter	Hashing required
Email Address(es)	`email`	YES
Phone Number(s)	`phone`	YES
Gender	`gen`	YES
Date of Birth	`db`	YES
Last Name	`ln`	YES
First Name	`fn`	YES
City	`ct`	YES
US States	`st`	YES
Zip codes	`zip`	YES
Country	`country`	YES
Mobile Advertiser ID	`madid`	Do not hash The advertising ID from an Android device or the Advertising Identifier (IDFA) from an Apple device.
Third-party user id	`external_id`	Highly recommended
The lead id from Lead Ads	`lead_id`	Do not hash

Custom Data Parameters

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
`event_time` type: integer	Required The UNIX timestamp of the conversion event. Example: `'1456870055'`
`event_name` type: string	Required Type of event. Example: `ViewContent, Search, AddToCart, AddToWishlist, InitiateCheckout, AddPaymentInfo, Purchase, Lead, Other`
`store_data` type: JSON dictionary	Optional Store location data about conversion event. Example: `"store_data": { "store_page_id": 8576093908, // FBID "brand_page_id": 10236898932// FBID "store_code": "64CharacterAlphaNumericString" // String }`
`currency` type: string	Required Three-letter ISO currency code⁠ for this conversion event. Required for `Purchase` events. Example: `USD`
`value` type: double	Required Value of conversion event. Required for `Purchase` events. Example: `16.00`
`content_type` type: string	Optional Any valid Advantage+ catalog ads `content_type`. Example: `product`
`contents` type: JSON array	Optional. Required if you integrate your ads with catalog. Required: `id`, `quantity` Recommended: `price`, `brand`, `category` Required: `[ {id: "A", quantity: 1}, {id: "B", quantity: 2}, {id: "C", quantity: 1}]` Recommended: `[ {id: "A", quantity: 1, brand: "Brand_A", category: "", price: 10.0}]`
`custom_data` type: JSON dictionary	Optional. Information about this conversion event. Example: `{category: 'ICECREAM'}`
`order_id` 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: `ATN10001`, `123456`
`item_number` type: string	Optional. Unique identifier to distinguish events within the same order or transaction. Example: `1`, `a`

2. Sending Events

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

3. Set Up Deduplication

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.

4. Troubleshooting Events

You can use the Payload Helper tool to generate payload data:

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

Fill info for the events that will be sent to Meta

This will generate event payload, which can be used as a template for your Conversions API integration

Use the Test Events tool⁠ in Events Manager for testing your payload.

Sending Offline Events Using the Conversions API