Use this guide as a reference of supported feed formats and fields to create automotive ads.
All enum fields are case-insensitive.
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.
Feed Format | Description & Guidelines | Sample Feed |
---|---|---|
CSV | Comma-separated value.
| |
TSV | Tab-separated value. See guidelines for CSV. | |
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 See Feed XML example. |
Example - TSV
file with tab delimiters
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
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>
"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/"
"{addr1: '1 Hacker Way', city: 'Menlo Park', region: 'CA', postal_code: '94025', country: 'US'}"
<?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 & 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>
The following supported fields are designed for items you add to your product catalog.
For localized catalogs, see supported fields for vehicle.
Name | Description | Use in Creative | Use as a product set filter |
---|---|---|---|
type: int | Required for Marketplace; NA for dynamic ads. Facebook page ID of the partner or dealership. Your catalog must be added to the allow list by your Facebook representative before you can send your page IDs. The page must be added to the allow list using the Business Manager before can be ingested. See Managing Permissions. | N | N |
type: string | Required for Marketplace & dynamic ads. 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. You can also use the VIN for both Example: | Y | Y |
type: string | Required for Marketplace & dynamic ads. Max characters: 500. Full name of vehicle. This is relevant and specific to each vehicle and it should contain what is set in Example: | Y | Y |
type: string | Required for Marketplace & dynamic ads. Max characters: 5000 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. Example: | Y | N |
type: url | Required for dynamic ads; Optional for Marketplace. Link to the external site where you can view the vehicle listing. | Y | N |
type: string | Required for Marketplace & dynamic ads. Make or brand of the vehicle. Example: | Y | Y |
type: string | Required for Marketplace & dynamic ads. Model of the vehicle. Example: | Y | Y |
type: int | Required for Marketplace & dynamic ads. Year the vehicle was launched in Example: | Y | Y |
type: int | Required for Marketplace & dynamic ads. For used vehicles, current mileage of the vehicle in kilometers ( Example: '1500' | Y | Y |
type: string | Required for Marketplace & dynamic ads. Mileage units: | Y | N |
type: string | Required for Marketplace & dynamic ads. Max items: 20 URL of the vehicle image. If you have more than one vehicle image, follow this naming convention:
Learn more about Marketplace Best Practices for images. | N | N |
Type: enum | Optional for Marketplace & dynamic ads. Transmission type of the vehicle: | N | Y |
Type: enum | Required for Marketplace & dynamic ads. Body style of the vehicle: | Y | Y |
Type: enum | Optional for Marketplace & and dynamic ads. Vehicle drivetrain. Supported values: | N | Y |
| Required for dynamic ads & Marketplace, some countries. Max characters: 17 Vehicle ID number (VIN) of the vehicle. You can also use the VIN for both Example: | Y | Y |
Type: string | Required for Marketplace & dynamic ads. 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: | Y | Y |
type: string | Required for Marketplace & dynamic ads. Vehicle color. Example: | Y | Y |
type: enum | Required for Marketplace & dynamic ads. Current state of the vehicle. Supported values: | N | Y |
type: enum | Optional for Marketplace & and dynamic ads. Vehicle fuel type. Supported values: | N | Y |
type: string | Optional for Marketplace & dynamic ads. Max items: 20 Tag appended to the image that shows what's in the image. There can be multiple tags associated with an image. Follow this naming convention:
Example: | N | Y |
type: string | Optional for Marketplace & and dynamic ads. String that describes the image. There can be multiple tags associated with an image. Example: | Y | N |
type: int | Optional for Marketplace; NA for dynamic ads. Similar to | N | N |
type: enum | Optional for Marketplace & and dynamic ads. Condition of the vehicle. Supported values: | N | Y |
type: integer | Optional for Marketplace & dynamic ads. Sale price or special price. Format the price as the cost, followed by the ISO currency code, with a space between cost and currency. Example: | Y | Y |
type: enum | Optional for Marketplace & dynamic ads. Vehicle availability: | N | Y |
type: string | Optional for dynamic ads amp; for Marketplace. Type of vehicle. Expected values: | N | Y |
type: string | Optional for dynamic ads and Marketplace. Max characters: 50 Trim of the vehicle. Example: | Y | Y |
type: string | Optional for dynamic ads and Marketplace. Max characters: 50 Vehicle interior color. | N | Y |
type: string | Optional for dynamic ads and Marketplace. Date when this vehicle first arrived at the dealer lot. Used to indicate inventory age. Use the Example: | N | Y |
Name | Description | Use in Creative | Use as a product set filter |
---|---|---|---|
type: string | Required for Marketplace & dynamic ads. Complete dealership physical address, formatted as:
The postal code is optional. Example: | N | N |
type: string | Required for Marketplace. City where the dealership is located. Example: | Y | Y |
type: string | Required for Marketplace. State, county, region, or province where the dealership is located. Example: | Y | Y |
type: string | Required for Marketplace. Country where the dealership is located. Example: | N | Y |
type: float | Required for dynamic ads & Marketplace. Latitude of the dealership location. Example: | N | N |
type: float | Required for dynamic ads amp; Marketplace. Longitude of the dealership location. Example: | N | N |
type: string | Optional for Marketplace. Postal code for dealership (outside the U.S. or zip code within the U.S.). Example: | N | N |
type: string | Optional for dynamic ads. Required for Marketplace. Max characters: 100 Alphanumeric ID of the dealership. | Y | Y |
type: string | Optional for dynamic ads. Required for Marketplace. Max characters: 100 Name of the dealership. | Y | Y |
type: string | Optional for dynamic ads. Required for Marketplace. Phone number of dealership. Phone number of the dealership. Requirements:
Example: | N | N |
type: enum | Optional for dynamic ads. Required for Marketplace. Method with which the dealer will be contacted by the user. Available values: 1) | N | N |
type: url | Optional for dynamic ads. Required for Marketplace. Link to the privacy URL of the dealer listing the vehicle. This should match the dealer of the Facebook page ID ( | N | N |
type: string | Optional for dynamic ads & Marketplace. Dealership's own designation of the car on their lot. The stock number is a way for the dealer to inventory specific vehicles. Example: | Y | Y |
type: string | Optional for Marketplace & dynamic ads. Max character limit: 100 Additional information about the vehicle you want to include. | Y | Y |
type: string | Optional for Marketplace & dynamic ads. Max character limit: 100 Additional information about the vehicle you want to include. | Y | Y |
type: string | Optional for Marketplace & dynamic ads. Max character limit: 100 Additional information about the vehicle you want to include. | Y | Y |
A feed can be in CSV, TSV, XML formats.
Example—TSV file, using tab as the delimiter
vehicle_offer_id market_name make model trim year offer_disclaimer offer_type amount amount_percentage amount_qualifier term_length term_qualifier downpayment downpayment_qualifier offer_description url image[0].url start_date end_date offer34220 market1234 MakeA ModelA E3 2017 *Available on approved credit to very well qualified customers lease USD 419 a month 36 months USD 0 due at signing. Expires 09/05/2017. Excludes official fees, taxes and dealer charges. No security deposit required. 10,000 mile/year limit. https://test123.com/offers1 http://www.test123.com/cm-img/facebook/offer1.jpg 2018-09-05 2018-12-31 offer34221 market1234 MakeB ModelB E4 2017 *Available on approved credit to very well qualified customers cash USD 1500 cash Expires 09/05/2017. https://test123.com/offers2 http://www.test123.com/cm-img/facebook/offer2.jpg 2018-09-05 2018-12-31 offer34222 market2345 MakeC ModelC E5 2017 *Available on approved credit to very well qualified customers finance 4.9 APR 60 months Expires 09/05/2017. Excludes official fees, taxes and dealer charges. https://test123.com/offers3 http://www.test123.com/cm-img/facebook/offer3.jpg 2018-09-05 2018-12-31
These feeds can be uploaded via the UI or API. If you prefer the UI, please provide your user ID and account ID, and we can add you to the allow list for access.
Name | Description | Product Set Filter | Can Use in Creative? |
---|---|---|---|
type: string | Required. Unique ID for the vehicle. that advertisers will use to identify an offer. This is also the same value that is passed under the Example: | Y | Y |
type: string | Required. Make or brand of the vehicle. Example: | Y | Y |
type: string | Required. Model of the vehicle. Example: | Y | Y |
type: integer | Required. Year the vehicle was launched in yyyy format. Example: | Y | Y |
type: enum | Required. Type of offer. Valid values: | Y | N |
type: string | Required. Title of the ad/offer. Example: | N | Y |
type: string | Required. Description of the offer. Example: | N | Y |
type: url | Required. Link to the external site where you can view the offer. | N | Y |
type: string | Required. Disclaimer associated with the offer. | N | N |
type: string | Required. URL of the vehicle image used in the ad creative. Note: To use carousel ads, provide square 1:1 aspect ratio images at 600x600px. To show single-vehicle ads, provide images with 1.91:1 aspect ratio image at 1200x630px. For more image ratio information, see Best Practices for Aspect Ratios. | N | N |
type: string | Optional. String that represents what's in the image. There can be multiple tags associated with an image, such as Lease Offer, Financing, and so on. | ||
type: string | Optional. String that represents what's in the image. We support multiple tags. Increment the | N | N |
type: string | Optional. String that represents what's in the image. You can upload more than 1 image by incrementing the digit n starting from 1 to 20. The value of | N | N |
type: string | Optional. String that represents what's in the image. We support multiple tags. Increment the | N | N |
type: string | Optional. String that represents what's in the image. There can be multiple tags associated with an image, such as Lease Offer, Financing, and so on. | N | N |
type: string | Recommended. Amount of the lease or cash offer. Format price as the cost, followed by the ISO currency code, with a space between cost and currency. Example: For a lease of $329/month or a cashback of $2000, the values that are | N | Y |
type: string | Recommended. Percentage value, if present in the offer. Sometimes the value is a percentage (example: | N | N |
type: string | Recommended. Qualifier for the amount dollar value or amount percentage. Valid values can be Example: | N | Y |
type: integer | Recommended. Duration for which the offer applies. If the offer is a lease of $329/mo for 3 years, then the value is Example: | N | Y |
type: enum | Recommended. Units for the term of the offer. Valid values are "months" or "years". Example: | N | Y |
type: string | Recommended. Down payment value at time of purchase or lease. Format price as the cost, followed by the ISO currency code, with a space between cost and currency. Example: Use | N | Y |
type: string | Recommended. Qualifier for the | Y | |
type: string | Recommended. Trim of the vehicle. Example: | N | Y |
type: string | Recommended MSRP of vehicle with currency. Format price as the cost, followed by the ISO currency code, with a space between cost and currency. Example: | N | N |
type: enum | Recommended. Body style of the vehicles. Valid values: | N | N |
type: string | Optional. Start date from which an offer is valid. Should be in date format yyyy-mm-dd. Example: | N | N |
type: string | Optional. End date after which an offer is valid. Should be in date format yyyy-mm-dd. Example: | N | N |
type: string | Optional. Name of market/designated market area (DMA). | Y | N |
type: array of strings | Required for regional offer. Optional for national offer. List of Designated Market Area (DMA) codes for the specific market provided in the following format ['502', '201'] ['516'...]. Note: This is for CSV format, see below example feeds for XML format. See DMA code standard. Leave empty for national offer. | Y | N |
curl \ -F 'name=catalog name' \ -F 'access_token=<ACCESS TOKEN>' \ -F 'vertical=vehicle_offers' \ https://graph.facebook.com/<API_VERSION>/<BUSINESS ID>/product_catalogs