Automotive Inventory Ads - Catalogs and Feeds

To promote your automotive inventory on Facebook, you need to share this information with Facebook. You do this by creating an 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.

Step 1: Specify Your Auto Inventory Catalog Feed

Supported fields are available for Vehicle and Dealership.

Auto Inventory Catalog Fields - Vehicle

All enum fields are case-insensitive.

NameDescriptionCan use in Creative?Can use as a product set filter?

vehicle_id

type: string

Required.

Max characters: 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. Example: 2017 Volvo XC90

Y

vin

type: string

Required

Max characters: 17 Vehicle identification number of the vehicle. Note: VIN must be exactly 17 characters. Example: 1FADP5AU6DL536022

Y

Y

make

type: string

Required.

Make or brand of the vehicle, such as Ford.

Y

Y

model

type: string

Required.

Model of the vehicle, such as Focus.

Y

Y

year

type: int

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

Y

Y

body_style

type: enum

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

Y

Y

description

type: string

Required.

Max characters: 5000

Short text describing the vehicle. Example: Used 2017 Volvo XC90 in great condition, available now.

Y

exterior_color

type: string

Required.

Vehicle color. Example: black, white, blue

Y

Y

image[0].tag[0]

type: string

Required.

Max items: 20 String of image description. There can be 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] ....

Example: Exterior, Interior, StockImage

Y

image[0].url

type: string

Required.

Max items: 20

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

type: int

Required.

Current mileage of the vehicle in kilometers (kms) or miles (MI), for used vehicles. Use zero (0) for new vehicles.

Y

Y

mileage.unit

type: string

Required.

Mileage units: MI or KM

Y

url

type: url

Required.

Link to the external site where you can view or purchase the vehicle.

title

type: string

Required. Max characters: 500.

Title of vehicle listing, such as 2017 Ford Focus 5DR HD SE.

Y

Y

price

type: string

Required.

Cost and currency of the vehicle. Example: USD 13,999.

Y

Y

vehicle_type

type: enum

Optional.

Type of vehicle. Expected values: car_truck (default if not supplied), boat, commercial, motorcycle, powersport, rv_camper, trailer, or other.

state_of_vehicle

type: enum

Required.

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

Y

drivetrain

type: enum

Optional.

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

fuel_type

type: enum

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

transmission

type: enum

Optional. Transmission type: Automatic or Manual.

Y

trim

type: string

Optional. Max characters: 50 Trim of the vehicle, such as 5DR HB SE.

Y

Y

interior_color

type: string

Optional. Max characters: 50 Vehicle interior color.

Y

condition

type: enum

Optional. Condition of the vehicle. Expected values: excellent, good, fair, poor, or other. Vehicle interior color.

Y

sale_price

type: integer

Optional. Sale price or special price.

Y

Y

date_first_on_lot

type: string

Optional.

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

Y

availability

type: string

Optional.

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

Auto Inventory Catalog Fields - Dealership (Vehicle Location)

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

address

type: object

Required.

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

address.addr1

type: string

Required.

Street address where the dealership is located. Example: 1110 El Camino Real.

address.city

type: string

Required.

City where the dealership is located, such as Palo Alto.

Y

Y

address.region

type: string

Required.

State, county, region, or province where the dealership is located, such as California.

Y

Y

addr.country

type: string

Required. Country where the dealership is located, such as United States.

Y

addr.postal_code

type: string

Optional.

Postal code for vehicle (outside the U.S. or zip code within the U.S.).

Y

dealer_id

type: string

Optional.

Max characters: 100

Alphanumeric identifier of the dealership.

Y

Y

dealer_name

type: string

Optional.

Max characters: 100

Name of dealership.

dealer_phone

type: string

Optional.

Phone number of dealer.

longitude

type: float

Optional.

Dealership's longitude, such as –122.148252.

latitude

type: float

Optional.

Dealership's latitude. Example: 37.4845

custom_label_0

type: string

Optional.

Max size: 100

Additional information about item.

Y

Y


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

Note: All parameters are optional.

Name Description Example

ios_url

Custom scheme for iOS app as URL

example-ios://electronic

ios_app_store_id

App ID for App Store

1234

ios_app_name

Name of app to display

Electronic Example iOS

iphone_url

Custom scheme for iPhone app as URL

example-iphone://electronic

iphone_app_store_id

App ID for App Store

5678

iphone_app_name

Name of app to display

Electronic Example iPhone

ipad_url

Custom scheme for iPhone app

example-ipad://electronic

ipad_app_store_id

App ID for App Store

9010

ipad_app_name

Name of app to display

Electronic Example iPad

android_url

Custom scheme for Android app as URL

example-android://electronic

android_package

Fully-qualified package name for intent generation

com.electronic

android_app_name

Name of app for display

Electronic Example Android

windows_phone_url

Custom scheme for Windows Phone app as URL

example-windows://electronic

windows_phone_app_id

App ID, as a GUID, for app store

ee728e01-7727-4168-9c8f-85c7eef40112

windows_phone_app_name

Name of app for display

Electronic Example Windows

For iOS, only provide iPhone or iPad app information if they are different from the general iOS app.

Example

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

Learn more about Dynamic Ads, Product Catalog.

Step 2: Create Data Feed

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.

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 have these available feed options:

  • 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

Step 3: 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.

You can download a sample feed (CSV, TSV, XML format) if you try to create an Auto catalog via Catalog Manager as shown below:

See also Direct Upload Feed Reference, Update a Product, or Catalog Feed Debugger.

Step 4: Debug your Automotive Feed

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 inventory ads to discover whether the current feeds you may already have are supported by Facebook.

Step 5: Create Vehicle Sets

Reference Docs

After catalog upload is set up and working properly, you can create vehicle sets.

A vehicle set is a subset of your catalog. 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, where 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.