Uploading Inventory

Send your vehicles to Marketplace

Catalog setup

To set up a Marketplace Vehicles feed, you will need a product catalog and a feed of your inventory hosted at a location of your choice.

Your catalog is a structured data file with a list of cars that you would like to showcase on Marketplace. Each line of the file contains all information needed to create a Marketplace listing.

From your business manager/catalog manager (https://www.facebook.com/products/), create a new vehicles catalog.

Catalog publishing

To launch your catalog's vehicles on Marketplace, you would need to get approval from the Facebook Support team: contact your Facebook Partner Manager or reach out to commerce-partnerships@fb.com with the catalog's ID.

Automatic catalog publishing is in beta, not all partners currently have access

For partners who already have launched catalogs on Marketplace, it's possible to access a beta feature that allows to create and publish new catalogs from the Business Manager. Partners will have access to one new use case "Reach Vehicle Buyers on Marketplace":

Clicking on "Publish Catalog" will publish your catalog in Marketplace.



Scheduling upload

To be ready for production, you have to schedule an upload of data source, e.g. via FTP, or exposing your feed from an endpoint (e.g. www.partnersite.com/facebook_feed.xml). We recommend to set 1 daily upload in “replace” mode.

Supported Feed Formats

Provide your feed in one of these formats:

Feed Format Description & Guidelines Sample Feed

CSV

Comma-separated value.

  • The first row specifies the column header. Subsequent rows supply the corresponding values for each route.

  • Fields containing whitespace or commas should be enclosed in "double quotes". A double quote inside a double-quoted field must be escaped with two consecutive double quotes.

  • Nested or multi-value fields, such as image, can be represented using JSON-encoded values or by a set of "flattened" plain-text columns labeled using JSON-path syntax. Example: (image[0].url, image[0].tag[0], image[0].tag[1])

  • Both conventions can be used interchangeably in the same file.

Download > Right-click > Save Link As

TSV

Tab-separated value. See guidelines for CSV.

Download > Right-click > Save Link As

XML

Format typically generated by automated feed provider systems or web servers. A set of item XML nodes represents a product list and must begin with the <?xml declaration tag.

Download > Right-click > Save Link As

Feed Specs

Required fields


NameTypeDescription

vehicle_id

(string, max 100)

Required

Unique ID for vehicle. Must be unique in the whole catalog.

vin

(string)

Required in all countries, except Brazil, France and United Kingdom

VIN of the vehicle. Note: VIN must be exactly 17 characters and it isn't required for pre 1983 vehicles.

Example: 1FADP5AU6DL536022

vehicle_registration_plate

(string)

Required in Brazil, France and United Kingdom

The vehicle registration plate number.

title

(string)

Required

Title of vehicle. This is relevant and specific to each vehicle and it should contain what is set in fields year/ make/ model / trim.

Example: 2017 Ford Focus 5DR HD SE

year

(int)

Required
Required

Year the vehicle was launched in yyyy format.
Example: 2017

make

(string)

Required

Make or brand of the vehicle.
Example: Ford

model

(string)

Required

Model of the vehicle. Example: Focus

exterior_color

(string)

Required

Vehicle exterior color.
Example: Red

body_style

(enum)

Required

Body style of the vehicle.

Available values: CONVERTIBLE, COUPE, CROSSOVER, HATCHBACK, MINIVAN, TRUCK, SEDAN, SMALL_CAR, SUV, VAN, WAGON or OTHER.

Note: for cabriolet style use CONVERTIBLE, for MPV use MINIVAN, for saloon use SEDAN, for estate use WAGON.

drivetrain

(enum)

Required

Drivetrain of the vehicle.

Available values: 4X2, 4X4, AWD, FWD, RWD, or OTHER.

transmission

(enum)

Required

Transmission type of the vehicle.

Available values: AUTOMATIC, MANUAL, or OTHER

fuel_type

(enum)

Required

Available values: DIESEL, ELECTRIC, GASOLINE, FLEX, HYBRID, OR OTHER.

mileage.value

(int)

Required

Mileage of the vehicle in kms or miles, for used vehicles.

Vehicles on Marketplace must have over 500 miles/kms.

mileage.unit

(string)

Required

Mileage unit.

Available values: MI or KM

description

(string, max 5000)

Required

Short text describing the vehicle. Don't include promotional text or any links. Don't enter text in all capital letters. Use line breaks to format your description (max 5000 characters).
Example: Used 2017 Ford Focus 5DR HD SE in great condition, available now

image

(array

- check note)
Required

Vehicle picture. You must provide at least 2 images, up to max 20 images supported by vehicle.


Each image can be up to 4MB in size and should be 960x720px resolution or higher.

state_of_vehicle

(enum)

Required

Whether the vehicle is new or used. Available values: New, Used, or CPO (meaning certified pre-owned).

price

(string)

Required

Cost of vehicle and currency. Currency should follow ISO 4217 currency codes with a space between cost and currency.

Example: 32000.00 USD

fb_page_id

(int)

Required

The Facebook Page ID of the Partner or the Dealership.

Note: your product catalog must be whitelisted by Facebook before you can send us Facebook Page IDs for dealerships. The page must be whitelisted using the Business Manager before the listing will be ingested.

See

"Managing Permissions"

for more details.

dealer_id

(string)

Required

Alphanumeric identifier of the dealer

dealer_name

(string)

Required

Name of the dealer

dealer_phone

(string)

Required

Phone number of dealer, required to display the "Call" button on a Marketplace listing. Must be a valid phone number format, and must include the country code.

Examples: +13603453333, 001(360)345-3333

address

(object)

Required

A complete address for the dealership that must be resolvable to its location.
Example: 675 El Camino Real, Palo Alto, CA (United States)

In address, addr 1, or address 1

(string)

Required

Street address of dealership.
Example: 675 El Camino Real

In address, city

(string)

Required

City where the dealership is based in.
Example: Palo Alto

In address, region

(string)

Required

State, county, region or province for dealership.
Example: CA

In address, country

(string)

Required

Country.
Example: United States

In address, postal_code

(string)

Required

Postal code, or zipcode of dealer Example: 94025

latitude

(float)

Required

The latitude of the dealership.
Example: 48.148252.

longitude

(float)

Required

The longitude of the dealership.
Example: -122.148252.

dealer_communication_channel

(enum)

Required

The method with which the dealer will be contacted by the user.

Available values: CHAT or LEAD_FORM (LEAD_FORM is subject to regional availability: when not available, every listing will be forced to CHAT disregarding the value entered).

dealer_privacy_policy_url

(url)

Required

Link to the privacy URL of the dealer listing the vehicle. This should match the dealer of the FB Page ID above

url

(url)

Required

Link to the external site where you can view details. This is required by the Catalog, but not used in Marketplace.

Additional fields for specific countries

Some fields are specifically required by country laws or only available in specific countries. All of them are optional for not specified countries.

NameTypeDescription

legal_disclosure_impressum_url

(string)

Required in Germany, optional in other countries

Url with statement of ownership and authorship (impressum)

vehicle_specifications

(array)

CO2 emissions and fuel consumption are required in Germany, optional in other countries

Specifications/features of the vehicle

In vehicle_specifications, type

(string)

CO2 emissions and fuel consumption are required in Germany, all optional in other countries

The type of specification.

Available values: CO2_emissions, gas_mileage_city, gas_mileage_highway, gas_mileage_combined, engine_size, horse_power.

Note: those values are case-sensitive!

In vehicle_specifications, units

(string)

CO2 emissions and fuel consumption are required in Germany, all optional in other countries

The unit used to express the value of this specification. E.g.: "g/km", "l/100km"

In vehicle_specifications, value

(string)

CO2 emissions and fuel consumption are required in Germany, all optional in other countries

The value for this vehicle spec, e.g.: "5.60"

Optional fields

The following fields are optional, but it's highly suggested to fill them up if you have them available, because they improve the listing quality.

NameTypeDescription

vehicle_type

(string)

Strongly recommended in all countries

The type of vehicle. CAR_TRUCK is the default vehicle_type, if no type is specified.

Available values: BOAT, CAR_TRUCK, COMMERCIAL, MOTORCYCLE, POWERSPORT, RV_CAMPER, TRAILER, or OTHER.

trim

(string, max 50)

Strongly recommended in all countries

Trim of the vehicle.

Example: 5DR HB SE

condition

(enum)

Strongly recommended in all countries

Condition of the vehicle.

Available values: EXCELLENT, GOOD, FAIR, POOR, or OTHER.

interior_color

(string)

Strongly recommended in all countries

Vehicle interior color

features

(enum)

Strongly recommended in all countries

Vehicle features. Each feature must be listed separately and contain a value (required) as a free-text description of the feature, i.e. ABS.


It can also contain a type (optional) to be chosen from the list below:

Available values: abs_brakes, adaptive_cruise_control, air_conditioning, alarm, alloy_wheels, armored, aux_audio_input, backup_camera, blind_spot_alert, bluetooth, collision_avoidance, cruise_control, daytime_running_lights, dvd_player, fog_lights, hd_radio, heated_seats, heated_steering_wheel, hid_headlights, hill_start_assist, keyless_entry, keyless_start, lane_keep_assist, leather, led_headlights, moon_roof, mp3, navigation, night_view, panorama_roof, park_assist, power_door_locks, power_liftgate, power_seats, power_steering, power_windows, privacy_glass, rear_spoiler, remote_start, roof_rack, running_boards, satellite_radio, stability_control, surround_view_camera, telematics, third_row_seat, tilt_steering_wheel, tinted_windows, tire_pressure_monitor, tow_package, traction_control, ventilated_seats


CSV example:

[{"value": "ABS","type":"abs_brakes"}, {"value": "Park Assist","type":"park_assist"}]

XML example:

<features>
  <feature name="abs_brakes">ABS</feature>
  <feature name="park_assist">Park Assist</feature>
</features>

tag

(string)

Optional in all countries

A string that describes the image. There can be multiple tags associated with an image, such as "Exterior", "Interior", "StockImage"

stock_number

(string)

Optional in all countries

A unique number, in addition to VIN and vehicle_id specified by manufacturer

availability

(enum)

Optional in all countries

Vehicle availability.

Available values: available or not available.

Note: We will not show vehicles that are unavailable in the listing.

date_first_on_lot

(string)

Optional in all countries

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

Example: 2018-09-05

dealer_url

(url)

Optional in all countries

URL of the dealer listing the vehicle (not the aggregator).

carfax_dealership_id

(string)

Optional in US

Dealership id agreed between Carfax and a partner, enabling the dealer to show Carfax reports.

msrp

(string)

Optional in US
New vehicles only:

Manufacturer's suggested retail price of vehicle and currency. Currency should follow ISO 4217 currency codes with a space between cost and currency.

Example: 32000.00 USD

chrome_id

(int)

Optional in US

Similar to autodata_id.

(²) For image field, when using a CSV/TSV file, we support two different formats:

  1. Use an image header that looks like: image[0].url, image[1].url, etc.,
  2. or
  3. Use a JSON flatten string that looks like: "[{url:'https://images.com/1.jpg'},{url:'https://images.com/2.jpg'}]"

Feed CSV/TSV example

"vehicle_id","vehicle_registration_plate","vin","make","model","year","transmission","body_style","fuel_type","drivetrain","description","image[0].url", "image[1].url","image[2].url","mileage.value","mileage.unit","url","title","price","state_of_vehicle","exterior_color","address","latitude","longitude","trim","interior_colour","dealer_id","dealer_name","postal_code","dealer_phone","fb_page_id","dealer_communication_channel","dealer_privacy_policy_url"
"56345636","AB12CDE","YV1DZ8256F2693747","Volvo","XC60","2014","AUTOMATIC","OTHER","DIESEL","OTHER","Volvo XC60 2.4 TD D5 R-Design Lux Geartronic 5dr (Nav)","http://website.com/images/stock/car1.jpg","http://website.com/images/stock/car2.jpg","http://website.com/images/stock/car3.jpg","12950","MI","http://www.dealership.co.uk","Volvo XC60 2.4 TD D5 R-Design Lux Geartronic 5dr (Nav)","22495.00 GBP","Used","White","{""addr1"":""Sample Road"",""city"":""London"",""region"":""Greater London"",""postal_code"":""SW31 3EW"",""country"":""United Kingdom""}","52.7445867","-2.7337375","2.4 TD D5 R-Design Lux Geartronic 5dr (Nav)","Black","436456435347346","Dealer Group","SSW31 3EW","","3562564376375","CHAT","https://www.dealership.co.uk/site/privacy-and-legal/"
  

Address example for CSV/TSV:

"{addr1: '1 Hacker Way', city: 'Menlo Park', region: 'CA', postal_code: '94025', country: 'US'}"

Feed XML example

<?xml version="1.0" encoding="UTF-8"?>
<listings>
  <title>Sample Vehicles Feed</title>
  <link rel="self" href="https://www.example.com/dealers/cars/1234/?r=vddn" />
  <listing>
    <vehicle_id>3456553</vehicle_id>
    <title>Ford B-MAX ZETEC</title>
    <description>Adjustable Steering Column, Adjustable Steering Wheel, Air Bags, Air Conditioning, Alloy Wheels, Anti Lock Brakes, Bluetooth Preparation (Phone), CD Player, CD Radio, Driver Airbag, Electric & Heated Door Mirrors, Electric Windows, Electronic Stability Programme (ESP), Front Electric Windows, Front Fog Lights, Height Adjustable Drivers Seat, Passenger Airbag, Power Assisted Steering (PAS), Power Fold &amp; Heated DoorMirrors, Rear Parking Sensor, Remote Boot Release, Remote Central Locking, Solid Paint,LOW MILEAGE WITH A FULL FORD HISTORY, SUPPLIED FROM US,</description>
    <url>https://www.example.com/car-1234>
    <make>Ford</make>
    <image>
      <url>https://www.example.com/1234/image_1.jpg</url>
    </image>
    <image>
      <url>https://www.example.com/1234/image_2.jpg</url>
    </image>
    <image>
      <url>https://www.example.com/1234/image_3.jpg</url>
    </image>
    <model>B-MAX</model>
    <year>2015</year>
    <mileage>
      <value>15617</value>
      <unit>MI</unit>
    </mileage>
    <drivetrain>Other</drivetrain>
    <vin>1A2BCDEF3GH456789</vin>
    <body_style>OTHER</body_style>
    <fuel_type>Gasoline</fuel_type>
    <transmission>Manual</transmission>
    <price>9490 GBP</price>
    <address format="simple">
      <component name="addr1">Sample Road</component>
      <component name="city">Carland</component>
      <component name="region">North Test</component>
      <component name="country">United States of America</component>
      <component name="postal_code">12345</component>
    </address>
    <latitude>37.484419</latitude>
    <longitude>-122.148406</longitude>
    <exterior_color>White</exterior_color>
    <state_of_vehicle>Used</state_of_vehicle>
    <dealer_id>453356</dealer_id>
    <vehicle_registration_plate>AB12CD</vehicle_registration_plate>
    <fb_page_id>5636367576574</fb_page_id>
    <dealer_communication_channel>LEAD_FORM</dealer_communication_channel>
    <dealer_privacy_policy_url>https://www.example.com/privacy/</dealer_privacy_policy_url>
  </listing>
</listings>

Full error reporting / Catalog debugging

This functionality is in beta.

There is an API that allows you to download the full report of your catalog errors. Check the question "How can I see the full error list of my catalog?" in our FAQ list for more details.

Need help?

You can contact Facebook's Support team any time you have questions.

Contact us