Reference

Use this referencew to view the supported fields and respective examples for the POST /{catalog_id}/batch and POST [/{catalog_id}/items_batch endpoints.

Supported Fields - Send Item Updates - /{catalog_id}/batch

These fields are supported for CREATE and UPDATE methods.

Field Description

additional_image_urls

type:

array<string>

Optional.

URLs for up to 9–10 different images

availability

type: string

Required

Identifies availability status:

  • in stock - Item ships immediately.
  • out of stock - No plan to restock
  • preorder - Available in future.
  • available for order - Ships in 1–2 weeks.
  • discontinued

age_group

type: string

Optional.

Group of people who are the same age or a similar age. Accepted values are newborn, infant, toddler, kids, adult.

applink

type:

object<>

Optional.

Links to mobile apps.

category

type: string

Optional but recommended for dynamic ads (may contribute to improved ad performance). Optional for Instagram Shopping and Page shops, but required to enable onsite checkout on these channels (US only). Required for Marketplace (US only).

Google product category (GPC) for the item. Use the category's taxonomy path or its ID number, listed here.

If you use checkout on Instagram or Facebook (US only), an item's GPC affects its taxes and return policy. Learn more about the Google product category for catalog items, Ads Help Center.

Example: Apparel & Accessories > Clothing > Shirts & Tops or 212

color

type: string

Optional.

Max size: 100.

Item color.

condition

type: string

Required.

Item's condition: new, refurbished, used.

currency

type: string

Required.

Currency for the value specified. The Marketing API supports all of the currencies supported by ad accounts. Use ISO 4217 for currency standards.

custom_label_0

type: string

Optional.

Max size: 100.

Additional information about item.

custom_label_1

type: string

Optional.

Max size: 100.

Additional information about item.

custom_label_2

type: string

Optional.

Max size: 100.

Additional information about item.

custom_label_3

type: string

Optional.

Max size: 100.

Additional information about item.

custom_label_4

type: string

Optional.

Max size: 100.

Additional information about item.

description

type: string

Required.

Max size: 5000.

Short description for the item.

gender

type: string

Optional.

Gender for sizing. Values include male, female, unisex.

gtin

type: string

Optional.

Max size: 70.

Global Trade Item Number can include UPC, EAN, JAN, and ISBN.

image_url

type: string

Required.

Link to item image used in the ad. Provide proper image sizes.

For single-image, dynamic ads

  • Min image resolution requirement is 500px * 500px
  • Min aspect ratio requirement is is 4:5
  • Max aspect ratio requirement is 1:91:1.

If the image is outside this aspect ratio, Facebook crops it to be closest to either the minimum aspect ratio or the maximum aspect ratio depending on its original aspect ratio.

For carousel image, dynamic ads - Min image resolution requirement is 500px * 500px, and Facebook crops it to a 1:1 aspect ratio.

Recommendation: Avoid frequent changes of image url. Image URLs should not contain parameters, such as price or timestamp as these tend to frequently change.

inventory

type: number

Optional.

Integer that advertisers can use to store information about the inventory level.

name

type: string

Required.

Max size: 100.

Title of item.

pattern

type: string

Optional

Max size: 100.

Pattern or graphic print on an item.

price

type: integer

Required.

The price multiplied by 100, for all currencies. Example: 490 when used with USD denotes $4.90, and 49000 when used with JPY denotes ¥490.

product_type

type: string

Optional.

Max size: 750.

Retailer-defined category for item.

Example: in TSV Home & Garden > Kitchen & Dining > Appliances > Refrigerators.

Example: in XML product_type > Home & Garden > Kitchen & Dining > Appliances > Refrigerators > product_type.

retailer_product_group_id

type: string

Optional.

Accepts strings. Advertisers can use to group products together.

sale_price

type: integer

Optional.

Discounted price if the item is on sale. This is the sale price multiplied by 100, for all currencies. Example: 490 when used with USD denotes $4.90, and 49000 when used with JPY denotes ¥490.

sale_price_start_date

type: string

Optional.

End date and time for the sale.

Example: 2014-12-01T00:00-0300

sale_price_end_date

type: string

Optional.

Start date and time for the sale.

Example: 2014-11-01T12:00-0300

shipping

type:

array<object>

Optional.

Shipping information.

size

type: string

Optional.

Size of item. Example: Small or XL.

url

type: string

Required.

Link to merchant's site where someone can buy the item.

vendor_id

type: string

Optional.

The vendor-defined ID of a product item.

Sample Request - /{catalog_id}/batch

{
  "access_token": "<ACCESS_TOKEN>",
  "requests": [
    {
      "method": "DELETE",
      "retailer_id": "retailer-1"
    },
    {
      "method": "CREATE",
      "retailer_id": "retailer-2",
      "data": {
        "availability": "in stock",
        "brand": "Nike",
        "category": "t-shirts",
        "description": "product description",
        "image_url": "http://www.images.example.com/t-shirts/1.png",
        "name": "product name",
        "price": "10.00",
        "currency": "USD",
        "shipping": [
           {
              "country": "US",
              "region": "CA",
              "service": "service",
              "price_value": "10",
              "price_currency": "USD"
           }
        ],
        "condition": "new",
        "url":"http://www.images.example.com/t-shirts/1.png",
        "retailer_product_group_id": "product-group-1"
      }
    },
    {
      "method": "UPDATE",
      "retailer_id": "retailer-3",
      "data": {
        "availability": "out of stock",
      }
    }
  ]
}

Sample Response - /{catalog_id}/batch

One or more handles will be returned.

"handles": ["AczwaOW7j_EuQ5peV3kGq8X9qc7cDiv_kFrrHkdKuG7LkpkkqK5939wgdoduSQ45FGK5vKdVqOaSDJEun-fvbsR1kk8Rd53AZyD1WThSemo26Q"]
https://graph.facebook.com/<API_VERSION>/<CATALOG_ID>/batch

Supported Fields - Send Product Updates - /{catalog_id}/items_batch

For commerce catalogs — Use this API if you need to update product information more often than once an hour (otherwise, use the Feed API). You can update multiple items in a single HTTP request.

PRODUCT_ITEM

These product fields are supported for CREATE and UPDATE methods, for version 3.3 and 3.2:

FieldDescription

additional_image_link

type:

array<string>

Optional.

Link for up to 9–10 different images.

age_group

type: string

Optional.

Group of people who are the same age or a similar age. Accepted values are newborn, infant, toddler, kids, adult.

applink

type:

object<string>

Optional.

Links to mobile apps.

availability

type: string

Required.

Identifies availability status:

  • in stock - Item ships immediately
  • out of stock - No plan to restock
  • preorder - Available in future
  • available for order - Ships in 1–2 weeks
  • discontinued

color

type: string

Optional.

Max size: 100.

Item color.

condition

type: string

Required.

Product condition: new, refurbished, or used.

custom_label_0

type: string

Optional.

Max size: 100.

Additional information about item.

custom_label_1

type: string

Optional.

Max size: 100.

Additional information about item.

custom_label_2

type: string

Optional.

Max size: 100.

Additional information about item.

custom_label_3

type: string

Optional.

Max size: 100.

Additional information about item.

custom_label_4

type: string

Optional.

Max size: 100.

Additional information about item.

description

type: string

Required.

Max size: 5000.

Short text describing product.

gender

type: string

Optional.

Gender for sizing. Values include male, female, unisex.

google_product_category

type: string

Optional.

Max size: 250.

Predefined values (string or category ID) from Google's product taxonomy.

Example: Apparel & Accessories > Clothing > Dresses or 2271.

gtin

type: string

Optional.

Max size: 70.

Global Trade Item Number (GTIN) can include UPC, EAN, JAN, and ISBN.

id

type: string

Required.

Product ID

image_link

type: string

Required.

Link to item image used in the ad. Provide proper image sizes.

For single-image dynamic ads:

  • Min image resolution requirement is 500px*500px.
  • Min aspect ratio requirement is is 4:5.
  • Max aspect ratio requirement is 1:91:1. If the image is outside this aspect ratio, Facebook crops it to be closest to either the minimum aspect ratio or the maximum aspect ratio, depending on its original aspect ratio.

For carousel image, dynamic ads: Min image resolution requirement is 500px*500px, and Facebook crops it to a 1:1 aspect ratio.

inventory

type: object

Optional.

Integer that advertisers can use to store information about the inventory level.

item_group_id

type: string

Optional.

The advertiser-supplied ID of a product group; not the FBID. Accepts strings. Can be used by advertisers to group a variety of different objects (product items, vehicles, hotels, flights, and so on together.

link

type: string

Required.

Link to merchant's site where someone can buy the item.

manufacturer_part_number

type: string

Optional.

Unique manufacturer ID for product.

pattern

type: string

Optional.

Max size: 100.

Pattern or graphic print on a product.

price

type: string

Required.

Price of the item. Format price as the cost, followed by the 3-digit ISO currency code, with a space between cost and currency..

Example: 9.99 USD.

sale_price

type: string

Optional, but required to use the Overlay feature for dynamic ads.

Discounted price if the item is on sale. Format price as the cost, followed by the 3-digit ISO currency code, with a space between cost and currency.

Example: 9.99 USD, 25.00 EUR

sale_price_effective_date

type: string

Optional.

Start and end date and time for the sale, separated by a slash. Write the start and end dates as YYYY-MM-DD. Add a "T" after each date and then include the time. Write the time in a 24-hour format (0:00 to 23:59).

Example: 2014-11-01T12:00-0300/2014-12-01T00:00-0300.

shipping

type: string

Optional.

Blob with different prices for each country and region. Different regions are comma-separated. The format should be COUNTRY:STATE:SHIPPING_TYPE:PRICE.

Example: US:CA:Ground:9.99 USD, US:NY:Air:15.99 USD

size

type: string

Optional.

Size of item. Example: Small or XL.

title

type: string

Required.

Max size: 100.

Title of item.

The UPDATE method can also be used to create items if they don't already exist.

Learn more about product fields in the API Reference.

Sample Request - PRODUCT_ITEM

curl \
  -d @body.json \
  -H "Content-Type: application/json"

  {
    "access_token": "<ACCESS_TOKEN>",
    "item_type": "PRODUCT_ITEM",
    "requests": [
      {
        "method": "DELETE",
        "data": {
          "id": "retailer-1"
        }
      },
      {
        "method": "CREATE",
        "data": {
          "id": "retailer-2",
          "availability": "in stock",
          "brand": "Nike",
          "google_product_category": "t-shirts",
          "description": "product description",
          "image_link": "http://www.images.example.com/t-shirts/1.png",
          "title": "product name",
          "price": "10.00 USD",
          "shipping": [
               {
                  "shipping_country": "US",
                  "shipping_region": "CA",
                  "shipping_service": "service",
                  "shipping_price_value": "10",
                  "shipping_price_currency": "USD"
               }
          ],
          "condition": "new",
          "link":"http://www.images.example.com/t-shirts/1.png",
          "item_group_id": "product-group-1"
        }
      },
      {
        "method": "UPDATE",
        "data": {
          "availability": "out of stock",
          "id": "retailer-3",
        }
      }
    ]
  }

Sample Response - PRODUCT_ITEM

{
  // One or more handles will be returned"handles": ["AczwaOW7j_EuQ5peV3kGq8X9qc7cDiv_kFrrHkdKuG7LkpkkqK5939wgdoduSQ45FGK5vKdVqOaSDJEun-fvbsR1kk8Rd53AZyD1WThSemo26Q"]
}

Learn more about Adding Catalog Items with a Data Feed.


HOTEL

Product fields that are supported for the CREATE and UPDATE methods for type HOTEL, for Version 3.2:

FieldDescription

address

type:

object<string>

Required.

Address of the hotel.

applink

type:

Optional.

Links to mobile apps.

base_price

type: string

Required.

Base price of the hotel room per night. Add the currency type to the price. Format price as the cost, followed by the ISO currency code, with a space between cost and currency. Example: USD for U.S. dollars.

brand

type: string

Optional.

Brand of the hotel chain.

description

type: string

Required.

Max character limit: 5000.

Short description of the hotel.

guest_rating

type:

array<object>

Optional.

Guest ratings of the hotel.

hotel_id

type: string

Required.

Unique ID for the hotel.

image

type:

array<object>

Required.

URLs and tags for images that to use in the ads. Supports up to 20 multiple images. Tag is optional, when used. Should describe what's in the image. Example: "reception".

latitude

type: string

Required.

Latitude location of the hotel.

longitude

type: string

Required.

Longitude location of the hotel.

loyalty_program

type: string

Optional.

Loyalty program used for the hotel.

margin_level

type: string

Optional.

Indicator of the hotel's profitability; value from 1 to 10.

name

type: string

Required.

Name of the hotel.

neighborhood

type:

array<string>

Optional.

One or more neighborhood(s) for the hotel. Example: Soho or Las Vegas Strip. Max number of neigborhoods allowed: 20.

phone

type: string

Optional.

Phone number with country code.

sale_price

type: string

Optional.

Sale price per night in the hotel. Use this to advertise discounts off the regular hotel price. Required: Add the currency type to the price. Format price as the cost, followed by the ISO currency code, with a space between cost and currency. Example: USD for U.S. dollars.

star_rating

type: string

Optional.

Hotel star rating. Number should be between 1 and 5.

url

type: string

Required.

Link to the external website where you book the hotel room.

The UPDATE method can also be used to create items if they don't already exist.

Sample Request - HOTEL

curl \
  -d @body.json \
  -H "Content-Type: application/json"

  {
    "access_token": "<ACCESS_TOKEN>",
    "item_type": "HOTEL",
    "requests": [
      {
        "method": "DELETE",
        "data": {
          "hotel_id": "hotel-1"
        }
      },
      {
        "method": "CREATE",
        "data": {
          "hotel_id": "1234",
          "brand": "Premium_brand",
          "description": "A very nice hotel",
          "name": "The best hotel",
          "base_price": "100.00 USD",
          "longitude":"42.10",
          "latitude":"42.10",
          "address": {
              "addr1":"100 Main Street",
              "city":"North Pole",
              "region":"ABC",
              "country":"US",
              "postal_code":"11111"
          },
          "guest_rating" : [
            {
                "rating_system":"tripAdvisor",
                "score":"7.8",
                "number_of_reviewers":"300",
                "max_score":"10",
            },
            {
                "rating_system":"Yelp",
                "score":"5.1",
                "number_of_reviewers":"123",
                "max_score":"10",
            },
          ],
          "image": [
            {
                "url":"http://example.com/image_1.jpg",
                "tag": ['Swimming pool','Gym'],
            }
          ],
          "applink" : {
            "ios_url":"example-ios://electronic",
            "ios_app_store_id":"42",
            "ios_app_name":"Electronic Example iOS",
            "iphone_url":"example-iphone://electronic",
            "iphone_app_store_id":"43",
            "iphone_app_name":"Electronic Example iPhone",
            "ipad_url":"example-ipad://electronic",
            "ipad_app_store_id":"44",
            "ipad_app_name":"Electronic Example iPad",
            "android_url":"example-android://electronic",
            "android_package":"com.electronic",
            "android_class":"com.electronic.Example",
            "android_app_name":"Electronic Example Android",
            "windows_phone_url":"example-windows://electronic",
            "windows_phone_app_id":"64ec0d1b-5b3b-4c77-a86b-5e12d465edc0",
            "windows_phone_app_name":"Electronic Example Windows",
          },
          "loyalty_program":"Premium_program",
          "margin_level": "8",
          "phone":"+61 2-96027455",
          "star_rating":"4",
          "url":"http://www.images.example.com/t-shirts/1.png"
        }
      },
      {
        "method": "UPDATE",
        "data": {
          "base_price": "90.00 USD",
          "hotel_id": "hotel-3",
        }
      }
    ]
  }

Sample Response - HOTEL

{
  // One or more handles will be returned"handles": ["AczwaOW7j_EuQ5peV3kGq8X9qc7cDiv_kFrrHkdKuG7LkpkkqK5939wgdoduSQ45FGK5vKdVqOaSDJEun-fvbsR1kk8Rd53AZyD1WThSemo26Q"]
}

HOTEL_ROOM

These product fields are supported for the CREATE and UPDATE methods for type HOTEL_ROOM, for version 3.2.

FieldDescription

base_price

type: string

Required.

Base price for 1 night. Currency should follow ISO 4217 currency codes.

Example: 9.99 USD.

description

type: string

Required.

Max size: 5000.

Short text describing the room.

hotel_retailer_id

type: string

Required.

Unique ID for hotel retailer.

hotel_room_id

type: string

Required.

Unique ID for hotel.

image

type:

array<object>

Required.

Images of the room.

name

type: string

Required.

Max size: 100.

Name of the room.

url

type: string

Required.

Link to advertiser's site where someone can book the stay.

The UPDATE method can also be used to create items if they don't already exist.

Sample Request - HOTEL_ROOM

curl \
  -d @body.json \
  -H "Content-Type: application/json"

  {
    "access_token": "<ACCESS_TOKEN>",
    "item_type": "HOTEL_ROOM",
    "requests": [
      {
        "method": "DELETE",
        "data": {
          "hotel_retailer_id": "1234",
          "hotel_room_id": "room-1",
        }
      },
      {
        "method": "CREATE",
        "data": {
          "hotel_retailer_id": "1234",
          "hotel_room_id": "room-2",
          "description": "product description",
          "name": "product name",
          "base_price": "100 USD",
          "url": "http://www.example.com/t-shirts/1.html",
          "image": [
            {
                "url":"http://example.com/image_1.jpg",
                "tag": ['Swimming pool','Gym'],
            }
          ]
      },
      {
        "method": "UPDATE",
        "data": {
          "hotel_retailer_id": "1234",
          "hotel_room_id": "room-3",
          "base_price": "120 USD",
        }
      }
    ]
  }

Sample Response - HOTEL_ROOM

{
    // One or more handles will be returned"handles": ["AczwaOW7j_EuQ5peV3kGq8X9qc7cDiv_kFrrHkdKuG7LkpkkqK5939wgdoduSQ45FGK5vKdVqOaSDJEun-fvbsR1kk8Rd53AZyD1WThSemo26Q"]
  }

FLIGHT

These product fields are supported for the CREATE and UPDATE methods for type FLIGHT, for version 3.2.

FieldDescription

description

type: string

Optional.

Max character limit: 5000.

Description of the flight.

destination_airport

type: string

Required.

Destination airport for the flight. Should be written as an IATA code.

Example: SFO.

destination_city

type: string

Optional.

Name of the destination city for the flight.

image

type:

array<object>

Required.

URLs and tags for images to use in the ads. Supports up to 20 multiple images. Tag is optional, when used should describe what's in the image.

Example: seat

origin_airport

type: string

Required.

Origin airport for the flight. Should be written as an IATA code.

Example: SFO

origin_city

type: string

Optional.

Name of the origin city for the flight.

price

type: string

Optional.

Cost and currency of the flight. The price is a number followed by the currency code; use ISO 4217 standards. Use ""."" as the decimal for the price.

url

type: string

Optional.

Link to the website where you can book the flight.

The UPDATE method can also be used to create items if they don't already exist.

Sample Request - FLIGHT

curl \
  -d @body.json \
  -H "Content-Type: application/json"

  {
    "access_token": "<ACCESS_TOKEN>",
    "item_type": "FLIGHT",
    "requests": [
      {
        "method": "DELETE",
        "data": {
          "origin_airport": "BOS",
          "destination_airport": "JFK",
        }
      },
      {
        "method": "CREATE",
        "data": {
          "origin_airport": "BOS",
          "destination_airport": "SFO",
          "description": "Best Flight to SFO",
          "image": [
            {
                "url":"http://example.com/image_1.jpg",
                "tag": ['City'],
            },
            {
                "url":"http://example.com/some.image_2.jpg",
                "tag": ['Food'],
            }
          ],
          "price":"100.00 USD",
        }
      },
      {
        "method": "UPDATE",
        "data": {

Sample Response - FLIGHT

{
    // One or more handles will be returned"handles": ["AczwaOW7j_EuQ5peV3kGq8X9qc7cDiv_kFrrHkdKuG7LkpkkqK5939wgdoduSQ45FGK5vKdVqOaSDJEun-fvbsR1kk8Rd53AZyD1WThSemo26Q"]
  }

DESTINATION

These product fields are supported for the CREATE and UPDATE methods for type DESTINATION, for version 3.2.

FieldDescription

applink

type:

object<string>

Optional.

Links to mobile apps.

address

type:

object<string>

Required.

Address of the hotel.

description

type: string

Optional.

Max character limit: 5000.

Short paragraph describing the destination.

destination_id

type: string

Required.

Max character limit: 100.

Unique ID for the destination.

image

type:

array<object>

Required.

URLs and tags for images to use in the ads. Supports up to 20 multiple images. Tag is optional, when used should describe what's in the image.

Example: seat.

latitude

type: string

Required.

Latitude location of the destination.

longitude

type: string

Required.

Latitude location of the destination.

name

type: string

Required.

Name of the destination.

neighborhood

type:

array<string>

Optional.

Max number of neigborhoods allowed: 20. One or more neighborhood(s) for the destination.

Example: Soho or Las Vegas Strip.

price

type: string

Optional.

Lowest average cost and currency for the destination. Format the price as a number followed by the currency code; use ISO 4217 standards. Use ""."" as the decimal for the price.

price_change

type: string

Optional.

Price change. Can be used for building product sets and in the ad creative:

  • 0 - No price change
  • -10 - 10% price drop
  • 20 - 20% price increase.

Example: ""average price in NYC dropped by X"" or ""average price in NYC dropped""

type

type:

array<string>

Required.

Max number of destination types: 20. Type(s) of destination. A destination can have multiple types.

Example: park or beach

url

type: string

Required.

Link to the website where you can book the destination.

The UPDATE method can also be used to create items if they don't already exist.

Sample Request - DESTINATION

curl \
  -d @body.json \
  -H "Content-Type: application/json"

  {
    "access_token": "<ACCESS_TOKEN>",
    "item_type": "DESTINATION",
    "requests": [
      {
        "method": "DELETE",
        "data": {
          "destination_id": "destination-1"
        }
      },
      {
        "method": "CREATE",
        "data": {
          "destination_id": "123456789",
          "description": "My destination is the best.",
          "name": "The best destination",
          "price": "199.00 USD",
          "price_change": "-20",
          "longitude":"-122.4424",
          "latitude":"37.7712",
          "image": [
            {
                "url":"http://example.com/image_1.jpg",
                "tag": ['City','Package'],
            },
            {
                "url":"http://example.com/some.image_2.jpg",
                "tag": ['Tour','Landmark'],
            }
          ],
          "address": {
              "addr1":"1 Market Street",
              "city":"San Francisco",
              "region":"California",
              "country":"United States",
              "postal_code":"94117"
          },
          "applink" : {
            "ios_url":"example-ios://travelapp",
            "ios_app_store_id":"42",
            "ios_app_name":"Travel App iOS",
            "iphone_url":"example-iphone://travelapp",
            "iphone_app_store_id":"43",
            "iphone_app_name":"Travel App iPhone",
            "ipad_url":"example-ipad://travelapp",
            "ipad_app_store_id":"44",
            "ipad_app_name":"Travel App iPad",
            "android_url":"example-android://travelapp",
            "android_package":"com.travelapp",
            "android_class":"com.travelapp.Example",
            "android_app_name":"Travel App Android",
            "windows_phone_url":"example-windows://travelapp",
            "windows_phone_app_id":"64ec0d1b-5b3b-4c77-a86b-5e12d465edc0",
            "windows_phone_app_name":"Travel App Windows",
          },
          "type":["city","culture"],
          "neighborhood":["Mission","SoMa"],
          "url":"http://www.thebestdestination.com"
        }
      },
      {
        "method": "UPDATE",
        "data": {
          "price": "159.99",
          "destination_id": "destination-3",
        }
      }
    ]
  }

Sample Response - DESTINATION

{
  // One or more handles will be returned"handles": ["AczwaOW7j_EuQ5peV3kGq8X9qc7cDiv_kFrrHkdKuG7LkpkkqK5939wgdoduSQ45FGK5vKdVqOaSDJEun-fvbsR1kk8Rd53AZyD1WThSemo26Q"]
}

HOME_LISTING

These product fields are supported for the CREATE and UPDATE methods for type HOME_LISTING, for version 3.3 and 3.2.

FieldDescription

applink

type:

object<string>

Optional.

Links to mobile apps.

address

type:

object<string>

Required.

Street address for the home listing.

availability

type: string

Required.

Current availability of the home listing. Supported values: for_sale, for_rent, sale_pending, recently_sold, off_market, available_soon.

available_dates_price_config

type:

array<object>

Optional.

Price configurations.

description

type: string

Optional.

Max character limit: 5000.

Short paragraph describing the home listing.

image

type:

array<object>

Required.

URLs and tags for images to use in the ads. Supports up to 20 multiple images. Tag is optional, when used should describe what's in the image.

Example: pool.

latitude

type: string

Optional.

Latitude location of the home listing.

longitude

type: string

Optional.

Longitude location of the home listing.

listing_type

type: string

Optional.

Type of listing. Supported values: for_rent_by_agent, for_rent_by_owner, for_sale_by_agent, for_sale_by_owner, foreclosed, new_construction, new_listing.

name

type: string

Required.

Name of the home listing.

neighborhood

type:

array<object>

Optional.

Neighborhood for the home listing. Max number neighborhoods allowed: 20.

num_baths

type: string

Optional.

Number of bathrooms.

num_beds

type: string

Optional.

Number of bedrooms.

num_units

type: string

Optional.

Number of units available. Use only for apartments or condos available for rent/lease.

price

type: string

Required.

Cost and currency for the home listing. The price is a number followed by the currency code; use ISO 4217 standards. Use ""."" as the decimal for the price.

price_change

type: string

Optional.

Price change. Can be used for building product sets and in the ad creative:

  • 0 - No price change
  • -10 - 10% price drop
  • 20 - 20% price increase.

Example: ""average price in NYC dropped by X"" or ""average price in NYC dropped""

property_type

type: string

Optional.

Type of property. Supported values: apartment, condo, house, land, manufactured, other, townhouse.

url

type: string

Required.

Link to the website where you can view the listing.

year_built

type: string

Optional.

Year when the home was built.

The UPDATE method can also be used to create items if they don't already exist.

Sample Request - HOME_LISTING

{
  "access_token": "<ACCESS_TOKEN>",
  "item_type": "HOME_LISTING",
  "requests": [
    {
      "method": "DELETE",
      "data": {
        "home_listing_id": "home-listing-1"
      }
    },
    {
      "method": "CREATE",
      "data": {
        "home_listing_id": "12345678",
        "availability": "for_sale",
        "description": "An amazing listing",
        "name": "1 Hacker Way, Menlo Park, CA 94025",
        "price": "110000 USD",
        "longitude":"1.11414",
        "latitude":"-1.835003",
        "address": {
            "addr1":"1 Hacker Way",
            "city":"Menlo Park",
            "region":"California",
            "country":"United States",
            "postal_code":"94025"
        },
        "neighborhood":["Menlo Oaks"],
        "image": [
          {
              "url":"http://img10.naventcdn.com/avisos/18/00/52/30/31/52/1200x1200/63590918.jpg",
          },
        ],
        "listing_type": "for_sale_by_agent",
        "num_baths":"6",
        "num_beds":"5",
        "num_units":"1",
        "property_type":"house",
        "year_built":"2007",
        "available_dates_price_config" : [
          {
              "start_date":"2020-11-15",
              "end_date":"2020-12-15",
              "rate":"10000",
              "currency":"USD",
              "interval":"nightly",
          },
          {
              "start_date":"2020-11-15",
              "end_date":"2020-12-15",
              "rate":"50000",
              "currency":"USD",
              "interval":"weekly",
          },
        ],
        "applink" : {
          "ios_url":"example-ios://travelapp",
          "ios_app_store_id":"42",
          "ios_app_name":"Travel App iOS",
          "android_url":"example-android://travelapp",
          "android_package":"com.travelapp",
          "android_class":"com.travelapp.Example",
          "android_app_name":"Travel App Android",
        },
        "url":"http://www.example.com/link_to_listing"
      }
    },
    {
      "method": "UPDATE",
      "data": {
        "price": "100000 USD",
        "home_listing_id": "home-listing-3",
      }
    }
  ]
}

Sample Response - HOME_LISTING

{
  // One or more handles will be returned"handles": ["AczwaOW7j_EuQ5peV3kGq8X9qc7cDiv_kFrrHkdKuG7LkpkkqK5939wgdoduSQ45FGK5vKdVqOaSDJEun-fvbsR1kk8Rd53AZyD1WThSemo26Q"]
}

VEHICLE

For supported fields for the CREATE and UPDATE methods for type VEHICLE, see Auto Inventory Catalog Fields - Vehicle.

Supported fields are available for Vehicle and Dealership.

The UPDATE method can also be used to create items if they don't already exist.

Sample Request - VEHICLE

curl \
  -d @body.json \
  -H "Content-Type: application/json"

  {
    "access_token": "<ACCESS_TOKEN>",
    "item_type": "VEHICLE",
    "requests": [
      {
        "method": "DELETE",
        "data": {
          "vehicle_id": "vehicle-1"
        }
      },
      {
        "method": "CREATE",
        "data": {
          "vehicle_id": "i2 2017 Ford Fusion",
          "availability": "AVAILABLE",
          "make": "Ford",
          "model": "Fusion",
          "year": "2017",
          "mileage": {
            "value": "1500",
            "unit": "KM",
          },
          "image": [
            {
                "url":"http://www.facebook.com/teapic.jpg",
                "tag":["Car"],
            },
          ],
          "fuel_type":"gasoline",
          "body_style":"sedan",
          "drivetrain":"FWD",
          "vin":"1FADP5AU6DL536022",
          "condition":"EXCELLENT",
          "description": "Turbocharged! Gasoline!",
          "title": "SE Ford Certified and 6-Speed Automatic.",
          "price": "18000 USD",
          "exterior_color":"white",
          "sale_price":"16000 USD",
          "state_of_vehicle":"new",
          "longitude":"52.35",
          "latitude":"42.1",
          "address": {
              "addr1":"550 Auto Center Dr",
              "city":"Watsonville",
              "region":"CA",
              "country":"US",
              "postal_code":"96075"
          },
          "url":"http://www.example.com/test"
        }
      },
      {
        "method": "UPDATE",
        "data": {
          "price": "16000 USD",
          "vehicle_id": "vehicle-3",
        }
      }
    ]
  }

Sample Response - VEHICLE

{
  // One or more handles will be returned"handles": ["AczwaOW7j_EuQ5peV3kGq8X9qc7cDiv_kFrrHkdKuG7LkpkkqK5939wgdoduSQ45FGK5vKdVqOaSDJEun-fvbsR1kk8Rd53AZyD1WThSemo26Q"]
}

Supported Fields - Send Localized Items Batch - /{catalog_id}/localized_items_batch

See the list of supported fields and their respective descriptions for each field, for the /{catalog_id}/localized_items_batch endpoint:

See the full list of catalog-supported fields.

Learn More