Automotive Offer Ads

This API is under limited availability. Please contact your Facebook representative to be included.

To set up automotive offer ads, you need a Facebook catalog. A catalog is a container of information about your products and where you can upload your inventory. You can use your catalog in different ways within the Facebook family of apps. In your inventory, each individual product represents a unique vehicle offer you want to promote in your campaign.

Facebook’s automotive offer ads leverage cross-device intent signals to automatically promote relevant vehicle offers on Facebook and Instagram. An automotive offers catalog consists of information about the offers, corresponding vehicles, and markets/regions where the offer is valid.

Use Commerce Manager to create and manage your catalogs. Learn more about Best Practices, Dynamic Ads.

Before You Start

Before you set up your catalog, we recommend these guidelines:

  • If you manage multiple catalogs for different businesses or want an agency to access your catalogs, you may need to set up Business Manager.

If you're using Commerce Manager as part of your application, you may be affected by a couple of security-related breaking changes. See Breaking Changes, 1/30/2018, Catalog Permissions.

To set up automotive offer ads, we recommend the following steps.

Step 1: Set Up Your Automotive Offers Catalog

Create Feed Files

To create a catalog, you should connect a data feed or upload data to Facebook. The data should contain all the required fields for the vehicles that you want to advertise. Automotive Offer Ads only require one product feed. See Reference - Automotive Offer Ads - Supported Fields.

We recommend that you ensure your feed format follows our recommended guidelines. See Reference - Automotive Offer Ads — Supported Formats.

Downloadable Sample Files

Download a CSV sample feed.
Download an Excel sample feed.
Download an XML sample feed.

Deep Links

Provide deep links in data feed following the App Links specification. Deep link information in data feed takes precedence over any information Facebook collects with App Links metadata with our web crawler.

If you already have deep link information from App Links, you do not need to specify this data. Facebook uses information from App Links to display the correct deep link. To display deep links in your ads see Dynamic Ads, Ad Template. Learn more about product deep links.

Create Catalog

Once your feed file is ready, create your catalog.

Step 2: Schedule Uploads

We highly recommend using scheduled feed uploads to automatically push the latest offer feed to Facebook instead of having to upload refreshed files manually.

You can make a POST request to the product_feeds edge from the following paths: /{product_catalog_id}/product_feeds

To add a schedule to the feed, you can provide the schedule parameter in the POST endpoint.

Example - Set Up a Schedule Upload

curl -X POST \
  -F 'name=Offer Feed' \
  -F 'schedule={"interval":"DAILY","url":"http://www.example.com/offer_feed.tsv","hour":"22"}' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<CATALOG_ID>/product_feeds

Example — Create Offer Feed

curl \
  -F 'name= offer feed' \
  -F 'access_token=<access_token>' \
  https://graph.facebook.com/<API_VERSION>/<catalog_id>/product_feeds

Example — Upload Local Offer Feed File

curl \
  -F "file=@offer_feed.csv;type=text/csv" \
  -F "access_token=<access_token>" \
  https://graph.facebook.com/<API_VERSION>/<offer_feed_id>/uploads

Step 3: Create Product Sets

After the offer feed is successfully uploaded, optionally create product sets to further filter your offers. A product set is a more granular set of items that you want to promote based on your campaign strategy when setting up a campaign.

Example—Create a Product Set that Contains Only Lease Offers

curl \
 -F 'name=lease offer set' \
 -F 'filter={"offer_type":{"eq":"lease"}}' \
 -F 'access_token=<ACCESS TOKEN>' \
 https://graph.facebook.com/<API_VERSION>/<CATALOG_ID>/product_sets

You can create product sets from the Commerce Manager UI or via the API. Learn more about Product Catalog Product Sets.

Step 4: Install the Facebook Pixel

The Facebook pixel is a snippet of JavaScript code that allows you to track visitor activity on your website. When a visitor interacts with the website, pixel events are fired in response to their actions. A pixel event is a very lightweight http(s) request sent from the visitor's browser to Facebook's servers together with some extra information about that event, such as the page url that the visitor is viewing, product id or price of the product etc. Therefore, to enable the tracking, you need to modify your website template to insert some JavaScript code in certain pages.

Properly setting up the pixel code is important for automotive offer ads because our machine learning algorithm relies on the visitor-product interaction data in the web site collected from the pixel code. Without these data, Dynamic Ads would not be able to make good recommendations to the potential customers with high probability to convert.

Standard Events to Use with the Pixel

You can set up the Facebook pixel using the defined standard events and parameter that sends specific signals to the offer.

Standard Pixel Events for Automotive Offer Ads


NameDescription

event_name

type: string

Required.

Predefined event names that allow you to capture intent from your audiences at an item level, and segment them. For automotive offer ads, only these four standard pixel events are available: ViewContent, Search, AddToWishlist, Lead.


Where to place these standard events:

  • ViewContent to track your VDP and vehicle offer/incentive page view.
  • Search for automotive offer search and search result pages.
  • AddToWishlist when someone saves, likes, or otherwise shows special interest in an offer on the website.
  • Lead to track lower funnel actions or hard leads (where contact info is submitted).

Besides standard events, you can define custom pixel events as needed.

Required and Recommended Parameters to Pass Back with Your Standard Pixel Events


NameDescription

content_type

type: string

Required.

Parameter that designates the type of product being advertised.

Example: vehicle_offer

content_ids

type: array of strings

Required for ViewContent, AddtoWishList, Lead. Recommended for Search.

These IDs need to match to vehicle_offer_id in the offers feed.

For ViewContent events, you should send the ID for the offer presented. For Search events, you might send an array of search results.

Examples: ['123', '456'], "12345", '['1234', '4567', '5678']'

dma_code

type: array of strings

Recommended.

The Designated Market Area (DMA) code, which the user looks at for offers.

Example: 502

make

type: array of strings

Recommended.

Make or brand of the vehicle.

Example: Endomoto

model

type: string

Recommended.

Model of the vehicle.

Example: EndoHatch

year

type: integer

Recommended.

Year the vehicle was launched in yyyy format.

Example: 2015

body_style

type: enum

Recommended.

Body style of the vehicle: CONVERTIBLE, COUPE, HATCHBACK, MINIVAN, TRUCK, SUV, SEDAN, VAN, WAGON, CROSSOVER, OTHER.

Example: SEDAN

trim

type: string

Recommended.

Max characters: 50

Trim of the vehicle.

Example: GE

price

type: string

Recommended.

Cost and currency of the vehicle. Format the price as the cost, followed by the ISO currency code, with a space between cost and currency.

Example: 13,999 USD

Learn more about the Facebook Pixel.

Content Type

  • content_type = vehicle_offerRequired. Used to match the onsite actions to the offer in the ad. This allows Facebook to measure the performance and further optimize your campaigns.

  • content_ids = An array of IDs of vehicle offers from the offers feed — Optional, but highly recommended for all events; however, only optional for the Search event. This field helps Facebook further measure and optimize your ads.

If you have an existing pixel, you can append your pixel code with a content_type vehicle_offer and add the following parameters:

Event NameRequired ParametersRecommend Parameters

Search

Recommended when searching for offers.

content_type

content_ids

  • make
  • model
  • year
  • price (example: 1234.99)
  • currency (example: USD)
  • postal_code
  • market_ids

ViewContent

Recommended when viewing an auto offer.

content_type

content_ids

content_ids

  • make
  • model
  • year
  • price (example: 1234.99)
  • currency (example: USD)
  • postal_code
  • market_ids

AddToWishlist

Recommended when saving, favoring, or starring an offer.

content_type

content_ids

content_ids

  • make
  • model
  • year
  • price (example: 1234.99)
  • currency (example: USD)
  • postal_code
  • market_ids

Lead

Recommended when completing registration and submitting a lead form.

content_type

content_ids

content_ids

  • make
  • model
  • year
  • price (example: 1234.99)
  • currency (example: USD)
  • postal_code
  • market_ids
<!-- vehicle offer id information not available-->
 
<!-- Facebook Pixel Code -->
<script>
!function(f,b,e,v,n,t,s){if(f.fbq)return;n=f.fbq=function(){n.callMethod?
n.callMethod.apply(n,arguments):n.queue.push(arguments)};if(!f._fbq)f._fbq=n;
n.push=n;n.loaded=!0;n.version='2.0';n.queue=[];t=b.createElement(e);t.async=!0;
t.src=v;s=b.getElementsByTagName(e)[0];s.parentNode.insertBefore(t,s)}(window,
document,'script','https://connect.facebook.net/en_US/fbevents.js');
 
fbq('init', '<FB_PIXEL_ID>'); // pixel id
fbq('track', "PageView");
fbq('track', 'ViewContent', {
                content_type: 'vehicle_offer',
                offer_types: ['lease', 'finance', 'cash'],
                make: 'Endomoto',
                model: 'EndoHatch'
                year: '2017',
                trim: 'GE'
});
 
</script>
<!-- End Facebook Pixel Code -->

Step 5: Build Your Audience

To build an audience of people who are interested in the offers, you need to set up the Facebook Pixel. See also Install the Facebook Pixel. The pixel should live on all webpages that track action relevant to your business use case. This helps Facebook to optimize your campaign to find the right audience.

For example:

  • To optimize towards offer detail page views, place the pixel on that page and set up the ViewContent pixel event.
  • To optimize towards a lead submission, place the pixel on the post submission page and set up the Lead pixel event. Learn more about standard events.

Make sure that you set up the pixels on all relevant pages, not just for the pages you're optimizing for.

Important: You need to send required parameters along with each pixel event, because a match needs to be made in the catalog to create a product audience.

Associate the Pixel or App to Your Catalog

Example — Via the API

curl \
  -F 'external_event_sources=["<PIXEL_ID>","<APP_ID>"]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/external_event_sources

Example — Via the UI

  1. Go to Business ManagerBusiness Settings.
  2. In the left pane, choose Data SourceCatalogs.
  3. Find and select your catalog, then click Associate Sources to associate pixel and app to the catalog.

Create Event Source Group

Event source groups allow advertisers and developers to map multiple sources of conversion data into a single object for use in measurement, analytics, targeting, and optimization.

Via the API

curl \
  -F 'name=name of your event group' \
  -F 'event_sources=["<PIXEL_ID>", "<APP_ID>"]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/event_source_groups

Via the UI

  1. Go to Business ManagerBusiness Settings.
  2. In the left pane, choose Data SourceEvent Source Groups.
  3. Click Add to create a new event source group.

Create Vehicle Offer Audience

curl \
  -F 'name=Viewed in Last 30 days' \
  -F 'subtype=CLAIM' \
  -F 'claim_objective=VEHICLE_OFFER' \
  -F 'content_type=vehicle_offer' \
  -F 'event_source_group=<EVENT_SOURCE_GROUP_ID>' \
  -F 'inclusions=[
  {        
      "event": "ViewContent",
      "retention": {"min_seconds":0,"max_seconds":2592000}
  },
  {
      "event": "Search",
      "retention": {"min_seconds":0,"max_seconds":2592000}
  },
  {
      "event": "AddToWishlist",
      "retention": {"min_seconds":0,"max_seconds":2592000}
  }
  ]' \
  -F 'exclusions=[{
      "event":"Lead",
      "retention": {"min_seconds":0,"max_seconds":2592000}
  }]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/customaudiences

Example — Capture an audience who has visited your vehicle pages belonging to a certain vehicle set

curl \
  -F 'name=Viewed vechicles in vehicle set in Last 30 days' \
  -F 'subtype=CLAIM' \
  -F 'claim_objective=VEHICLE_OFFER' \
  -F 'content_type=vehicle_offer' \
  -F 'event_source_group=<EVENT_SOURCE_GROUP_ID>' \
  -F 'rule={"vehicle_set_id":{"eq":"<VEHICLE_SET_ID>"}}' \
  -F 'inclusions=[
  {        
      "event": "ViewContent",
      "retention": {"min_seconds":0,"max_seconds":2592000}
  },
  {
      "event": "Search",
      "retention": {"min_seconds":0,"max_seconds":2592000}
  },
  {
      "event": "AddToWishlist",
      "retention": {"min_seconds":0,"max_seconds":2592000}
  }
  ]' \
  -F 'exclusions=[{
      "event":"Lead",
      "retention": {"min_seconds":0,"max_seconds":2592000}
  }]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/customaudiences

Step 6: Debug Your Automotive Feed (Optional)

Using the Product Feed Debug Tool, you can paste in a product feed, and validate the feed for errors and warnings.

To debug your automotive feed, in the catalog selection drop-down menu, select Vehicles.

This is helpful in the early stages of integrating automotive ads to discover whether the current feeds you may already have are supported by Facebook.