Dynamic Ads for Automotive - Catalogs and Feeds

To promote your automotive inventory on Facebook, you need to share information about your automotive with Facebook. You do this by creating a automotive catalog and then filling it with automotive details.

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 advertise, which are listed below.

Auto Feed Specification

You can either have a single auto feed to represent all vehicles in your catalog or multiple auto feeds, where each feed represents a single dealership or a specific region's vehicles.

Required Fields for Vehicle Catalog Feed - Vehicle-Specific Details

All enum fields are case-insensitive.

NameTypeDescriptionCan use in Creative?Can be used as product set filter?

vehicle_id

String, max 100

Unique ID for item. Can be a variant for a vehicle. If there are multiple instances of the same ID, we ignore all instances.

Y

vin

String

VIN number of the vehicle. Note: VIN must be exactly 17 characters.

Y

Y

make

String

Make or brand of the vehicle, such as Ford

Y

Y

model

String

Model of the vehicle, such as Focus

Y

Y

year

int

Year the vehicle was launched in yyyy format, such as 2015

Y

Y

body_style

enum

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

Y

Y

description

String; max 5000 characters

Short text describing the vehicle

Y

exterior_color

String

Vehicle color. Ex: black, white, blue

Y

Y

image[0].tag[0]

String

Tag for first vehicle image. You can have multiple tags associated with an image. Follow this naming convention: image[0].tag[0], image[0].tag[1] .... image[1].tag[0], image[1].tag[1] ....

Y

image[0].url

String

The URL of the vehicle image. To use carousel ads, provide a square 1:1 aspect ratio images (600x600px). To show single vehicle ads, provide images with 1.91:1 aspect ratio image (1200x630px). If you have more than one vehicle image, follow this naming convention: image[1].url, image[2].url, and so on. You can provide up to 20 images for the vehicle. You must provide at least one image. Each image can be up to 4 MB in size.

mileage.value

int

Mileage of the vehicle in kms or miles, for used vehicles. Zero (0) for new vehicles.

Y

Y

mileage.unit

String

Mileage units: MI or KM

Y

url

url

Link to the external site where you can view destination page.

title

String

Title of vehicle, such as "2017 Ford Focus 5DR HD SE"; 500 characters (max).

Y

Y

price

String

Cost of vehicle and currency. Currency should follow ISO 4217 currency codes such as 13,999 USD.

Y

Y

state_of_vehicle

enum

Whether the vehicle is new or used. Values supported are: New, Used, or CPO (certified pre-owned).

Y

Required Fields for Vehicle Catalog Feed - Dealership (Vehicle Location) Specific Details

NameTypeDescriptionCan use in Creative?Can be used as product set filter?

address

object

Complete address for the dealership (vehicle location) that must be resolvable to its location.

addr1 (address object)

String

Street address of dealership, such as 675 El Camino Real.

city (address object)

String

City dealership is in, such as Palo Alto.

Y

Y

region (address object)

String

State, county, region, or province for dealership, such as California.

Y

Y

country (address object)

String

Country, such as United States

Y

longitude

float

Dealership's longitude, such as –122.148252.

latitude

float

Dealership's latitude.

Optional fields include:

NameTypeDescriptionCan use in Creative?Can be used as product set filter?

transmission

enum

Values accepted: automatic or manual.

Y

drivetrain

enum

Vehicle drivetrain. Expected values: 4X2, 4X4, AWD, FWD, RWD, Other.

Y

fuel_type

enum

Vehicle fuel type. Accepted values: Diesel, Electric, Flex, Gasoline, Hybrid, Other.

Y

trim

String

Trim of the vehicle, such as "5DR HB SE"; 50 characters (max).

Y

Y

tag (image tag)

String

String of image description. There can be multiple tags associated with an image, such as Exterior, Interior, StockImage.

interior_color

String

Vehicle interior color.

Y

condition

enum

Condition of the vehicle. Expected values: excellent, good, fair, poor, or other.

Y

sale_price

int

Sale price or special price.

Y

Y

date_first_on_lot

String

Date this vehicle first arrived at the dealer lot. Used to indicate age of the inventory.Should be in date format yyyy-mm-dd. E.g. 2018-09-05

Y

availability

enum

Vehicle availability: available or not available. Note: We will not show vehicles that are unavailable in the ad.

dealer_id

String

Alphanumeric identifier of the dealer; 100 characters (max).

Y

dealer_name

String

Name of dealer; 100 characters (max).

Y

Y

dealer_phone

string

Phone number of dealer.

postal_code, in address object

String

Postal code or zip code of dealer.

custom_label_0 (max size: 100)

String

Optional. Additional information about item.

Y

Y

Example

curl \
  -F 'name=catalog name' \
  -F 'access_token=<ACCESS TOKEN>' \
  -F 'vertical=vehicles' \
  https://graph.facebook.com/<VERSION>/<BUSINESS ID>/product_catalogs

Learn more about Dynamic Ads, Product Catalog.

Create Data Feed

Provide your feed in the correct format: CSV, TSV or XML. Once you create the feed file, you should host it at a URL for regular scheduled updates.

For example, a TSV file with tab delimiters looks like this:

vehicle_id title description url make model year mileage.value mileage.unit image[0].url image[0].tag[0] transmission fuel_type body_style drivetrain vin condition price address exterior_color sale_price availability date_first_on_lot state_of_vehicle latitude longitude i2 2017 Ford Fusion SE Ford Certified and 6-Speed Automatic. Turbocharged! Gasoline! http://www.example.com/test Ford Fusion 2017 1500 KM http://www.facebook.com/teapic.jpg Gym AUTOMATIC GASOLINE SEDAN FWD 1FADP5AU6DL536022 EXCELLENT 18000 USD {addr1: '550 Auto Center Dr', city: 'Watsonville', region: 'CA', postal_code: '96075', country: 'US'} white 16000 USD AVAILABLE 2018-02-21  NEW 52.35 42.10

Here is an example feed, with images as an array:

auto_listing_id title description url make model year mileage.value mileage.unit image transmission fuel_type body_style drivetrain vin condition price address exterior_color sale_price availability date_first_on_lot state_of_vehicle latitude longitude
"i2" 2017 Ford Fusion SE Ford Certified and 6-Speed Automatic. Turbocharged! Gasoline! http://www.example.com/test Ford Fusion 2017 1500 KM "[{""url"":""https://images.trvl-media.com/hotels/3000000/2260000/2250400/2250336/2250336_1_y.jpg""}]" AUTOMATIC GASOLINE SEDAN FWD 1FADP5AU6DL536022 EXCELLENT 18000 USD {addr1: '550 Auto Center Dr', city: 'Watsonville', region: 'CA', postal_code: '96075', country: 'US'} white 16000 USD AVAILABLE 2018-09-15 NEW 52.35 42.10

This sample feed is as XML:

<?xml version="1.0" encoding="UTF-8"?>
<listings>
    <title>Vehicles Feed</title>
    <link rel="self" href="http://www.example.com"/>
    <listing>
      <vehicle_id>SED1234</vehicle_id>
      <title>2017 Ford Fusion SE</title>
      <description>Ford Certified and 6-Speed Automatic. Turbocharged! Gasoline!</description>
      <url>http://www.example.com/test</url>
      <make>Ford</make>
      <image>
        <url>http://example.com/some.image_1.jpg</url>
        <tag>Exterior</tag>
      </image>
      <model>Fusion</model>
      <year>2017</year>
      <mileage>
        <value>10</value>
        <unit>MI</unit>
      </mileage>
      <drivetrain>FWD</drivetrain>
      <vin>1FADP5AU6DL536022</vin>
      <body_style>SEDAN</body_style>
      <fuel_type>GASOLINE</fuel_type>
      <transmission>AUTOMATIC</transmission>
      <condition>EXCELLENT</condition>
      <price>18000 USD</price>
      <address format="simple">
          <component name="addr1">550 Auto Center Dr</component>
          <component name="city">Watsonville</component>
          <component name="region">CA</component>
          <component name="postal_code">95076</component>
          <component name="country">US</component>
      </address>
      <latitude>52.35</latitude>
      <longitude>42.10</longitude>
      <exterior_color>white</exterior_color>
      <sale_price>16000 USD</sale_price>
      <availability>AVAILABLE</availability>
      <date_first_on_lot>2018-02-21</date_first_on_lot>
      <state_of_vehicle>NEW</state_of_vehicle>
      <dealer_id>ABC1234</dealer_id>
    </listing>
</listings>

You can have one or the other kind of feed: * A single vehicle feed to represent all vehicles in your catalog * Multiple vehicle feeds where each feed represents a single dealership or region's vehicles

Filter Vehicle Catalog to Vehicle Sets

Reference Docs

A vehicle set is a subset of your catalog. To set up Dynamic Ads for Automotive, you need to create at least vehicle set.

Vehicle sets are defined by filters that are applied to the Vehicle catalog. For example, you can create a vehicle set with all vehicles with a year later than 2015. Note: You can also create a vehicle set without any filters. In that case, the vehicle set contains all vehicles in your catalog.

Example: Create a vehicle set containing all the vehicles that manufactured in 2016

use FacebookAds\Object\ProductSet;
use FacebookAds\Object\Fields\ProductSetFields;

$vehicle_set = new ProductSet(null, <PRODUCT_CATALOG_ID>);

$vehicle_set->setData(array(
  ProductSetFields::NAME => 'Test Vehicle Set',
  ProductSetFields::FILTER => array(
    'year' => array(
      'eq' => 2016,
    ),
  ),
));

$ vehicle_set->create();

The filter parameter is made up of the following operators and data:

OperatorsThe type of filter

i_contains

Contains substring. Operator is case insensitive.

i_not_contains

Does not contain substring. Operator is case insensitive.

contains

Contains substring. Operator is case insensitive.

not_contains

Does not contain substring. Operator is case insensitive.

eq

Equal to. Operator is case insensitive.

neq

Not equal to. Operator is case insensitive.

lt

Less than. For numeric fields only.

lte

Less than or equal to. For numeric fields only.

gt

Greater than. For numeric fields only.

gte

Greater than or equal to. For numeric fields only.


Schedule Uploads

You should schedule feed uploads to automatically push the latest vehicle inventory data to Facebook instead of uploading refreshed files manually.

For details on how to schedule feed uploads, see Product Catalog - Schedule Product Feed Fetches.

See also Direct Upload Feed Reference, Update a Product, or Catalog Feed Debugger (Remember to select the correct catalog type; for example, “Vehicles”).


Product Feed Debug Tool

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 Dynamic Ads for Auto to discover whether the current feeds you may already have are supported by Facebook.