Uploading Inventory

Send your vehicles to Marketplace

Listing used cars on Facebook Marketplace is currently a closed beta program.

Dealerships who want to list their used cars on Marketplace can sign up through one of our listing partners.

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.

Then, to be ready for production, you have to schedule an upload as 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. The data source for a catalog should be only one. The data source can be added from here: Then, you can add a new data source from "Vehicle data sources" section.

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

The following fields are required in all launched countries


NameTypeDescription

vehicle_id

string, max 100

Required.

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

vin

string

Required in some countries (¹).

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

make

string

Required.

Make or brand of the vehicle.
Example: Ford

model

string

Required.

Model of the vehicle. Example: Focus

year

int

Required.

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

transmission

enum

Required.

Transmission type of the vehicle. Options: AUTOMATIC, MANUAL, or OTHER

body_style

enum

Required.

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

fuel_type

enum

Required.

DIESEL, ELECTRIC, GASOLINE, FLEX, HYBRID, OR OTHER.

drivetrain

enum

Required.

Drivetrain of the vehicle. Expected values are: 4X2, 4X4, AWD, FWD, RWD, or OTHER.

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 or italics to format your description (max 5000 characters).
Example: Used 2017 Ford Focus 5DR HD SE in great condition, available now

image

array

(²)
Required.

Image data for this vehicle. You can provide up to 20 images for the vehicle.

You must provide at least two images.

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

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 units: MI or KM

url

url

Required.

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

title

string

Required.

Title of vehicle. This is relevant and specific to each vehicle, include keywords and variants, such as brand names, item areas, attributes, or condition.
Example: 2017 Ford Focus 5DR HD SE

price

string

Required.

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

New vehicles only(¹):

Online price

Example: 32000.00 USD

state_of_vehicle

enum

Required.

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

exterior_color

string

Required.

Vehicle exterior color.
Example: Red

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 dealership is 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.

fb_page_id

int

Required.

The Facebook Page ID for the dealership.

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. Must be a valid phone number format, and must include the country code. Examples: +13603453333, 001(360)345-3333. Required to display the "Call" button on a Marketplace listing.

dealer_communication_channel

enum

Required.

The method with which the dealer will be contacted by the user. Options: 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

Additional fields required or available only in specific countries

Some fields are specifically required by country laws or only available in specific countries.

(¹) VIN is required in all countries where Marketplace is available. In the following countries, Vehicle registration plate is required instead of VIN:

  • United Kingdom
  • France
  • Brazil
NameTypeDescription

vehicle_registration_plate

string

The vehicle's registration plate

CO2 emissions statement is mandatory in:

  • Germany.
NameTypeDescription

legal_disclosure_impressum_url

string

Url with statement of ownership and authorship (impressum)

vehicle_specifications

array

Specifications/features of the vehicle

In vehicle_specifications, type

string

The type of specification. Possible values are: CO2_emissions, gas_mileage_city, gas_mileage_highway, gas_mileage_combined Note: values are case-sensitive!

In vehicle_specifications, units

string

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

In vehicle_specifications, value

string

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

Carfax ID to show Carfax reports and MSRP for new cars are available only in:

  • USA.
NameTypeDescription

carfax_dealership_id

string

Optional

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

msrp

string

Optional
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

Optional fields


NameTypeDescription

chrome_id

int

Similar to autodata_id.

car_history_link

string

Link to a carfax report or other car history report

trim

string

Trim of the vehicle, such as "5DR HB SE"

tag (image tag)

string

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

interior_color

string

Vehicle interior color

condition

enum

Condition of the vehicle. Values expected are: EXCELLENT, GOOD, FAIR, POOR, OR OTHER.

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

availability

enum

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

stock_number

string

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

vehicle_type

string

The type of the vehicle. CAR_TRUCK is the default vehicle_type, if no type is specified. Other possible vehicle types are BOAT, COMMERCIAL, MOTORCYCLE, POWERSPORT, RV_CAMPER, TRAILER, OTHER

(²) 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>

Best Practices

  • Currently, Marketplace only supports used and certified pre-owned Vehicles. All vehicle mileage must be over 500 miles. Listings with less than 500 miles (or equivalent in km) will be rejected, unless they have a registration plate.

Images
  • Provide as many high quality photos as possible. Posts with at least 15-20 photos tend to perform the best.
  • Photos should be at 960x720 resolution or better
  • Please provide the following images: (1) Front 3/4 angle, (2) Cockpit, (3) Side, back, (4) interior, (5) dents, dings & excessive wear, (6) Engine (7) Wheels
  • Clearly show any damage or excessive wear
  • Only include images of the vehicle itself. Do not add any brand or dealership overlays or graphics.
  • Listings with less than 2 images will be rejected.

Communication
  • Respond quickly to messages: Fast response times are more likely to result in conversion to a store visit and limit user drop-off. We highly recommend the use of a third party chat provider.

Uploading Your Listings
  • Select one listing partner: Listing inventory through multiple partners will yield suboptimal results. Selecting one provider will enable you to attribute Marketplace to the correct provider and measure performance accordingly.
  • Upload your full inventory of pre-owned vehicles: To maximize your dealership’s presence on Marketplace, send 100% of your available used vehicle inventory across all price points.
  • Provide complete vehicle description: Provide as much information as you have available about each vehicle, including notation of any damages.
  • Provide proper contact information: Always include dealership phone number.

Scheduled Vehicles Feed Fetches
  • Facebook fetches vehicles feeds from your system on a schedule you define. There are two types of schedule you can define.
  • Update Schedule: The uploads would either create new items or update existing ones with the information provided in the feed file.
  • Replace Schedule: The uploads would result in a complete refresh operation on your feed - we delete vehicles not present in the file, update existing ones, and create new ones.

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.