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.

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.

ParameterDescription

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
    }

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