Sending Offline Events Using the Conversions API

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.

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:

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.

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. Please note that the Test Events tool only supports web and app events.

See Also

• Conversions API Overview
• Using the Conversions API
• Conversions API Parameters
• Best Practices

Business Help Center Articles

• Create a dataset during offline event set creation
• Best practices for offline events data
• How advertisers can use offline conversions
• How to view results of campaigns assigned to specific dataset
• How event deduplication works for offline events