Catalog Batch API

Use this API if you have large catalogs, such as a catalog containing millions of items with quickly changing inventory. You can create, update, and delete multiple items in a single HTTP request.

The Catalog Batch API consists of these endpoints:

Endpoint Description Versions Supported In This Doc

POST /{catalog_id}/batch

Sends a batch of requests (create, update, delete) for an e-commerce catalog.

3.3, 3.2, 3.1 and prior

Send Item Updates

POST /{catalog_id}/items_batch

Sends a batch of requests (create, update, delete) for a catalog.

3.3, 3.2

Send Item Updates

GET /{catalog_id}/check_batch_request_status

Checks the status of a batch request.

3.3, 3.2, 3.1 and prior

Get Batch Request Status

Send Item Updates - /{catalog_id}/batch

To create, update or delete items in your catalog, make an HTTP POST call to:

https://graph.facebook.com/<API_VERSION>/<CATALOG_ID>/batch?requests=<REQUESTS>
Parameter Type Description

allow_upsert

boolean

When allow_upsert is false, update requests for items not existing in the catalog will not be completed. Otherwise, new items are created.

requests

object

A JSON object containing all requests.

requests.data

object

A JSON object containing fields and values for an item.

  • When the method is CREATE, this object must contain all the required fields.
  • When the method is UPDATE, it can contain any fields.

requests.method

string

CREATE, UPDATE, DELETE

requests.retailer_id

string

The advertiser-supplied id of an item; not the FBID.

requests.data

object

A JSON object containing fields and values for an item.

  • When the method is CREATE, this object must contain all the required fields for an item.
  • When the method is UPDATE, it can contain any fields.

For more details, see the API reference.

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

Limitations - /{catalog_id}/batch

  • The requests param can contain up to 5,000 updates.
  • For each catalog, you can make up to 100 calls per hour. If that's not sufficient, please contact us.

Supported Fields - /{catalog_id}/batch

These fields are supported for CREATE and UPDATE methods.

Field Description Type Required

additional_image_urls

URLs for up to 9–10 different images

array<string>

N

availability

  • 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

string

Y

age_group

Accepted values are newborn, infant, toddler, kids, adult.

string

N

applinks

Links to mobile apps.

object<array>

N

category

Category of the item string.

string

N

category

Category type of the item.

string

Y

color

Item color. Max size: 100.

string

N

condition

Item's condition: new, refurbished, used.

string

Y

currency

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

string

Y

custom_label_0

Optional. Additional information about item. Max size: 100.

string

N

custom_label_1

Optional. Additional information about item. Max size: 100.

string

N

custom_label_2

Optional. Additional information about item. Max size: 100.

string

N

custom_label_3

Optional. Additional information about item. Max size: 100.

string

N

custom_label_4

Optional. Additional information about item. Max size: 100.

string

N

description

Short description for the item. Max size: 5000.

string

Y

gender

Options: male, female, unisex.

string

N

gtin

Global Trade Item Number can include UPC, EAN, JAN, and ISBN. Max size: 70.

string

N

image_url

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.

string

Y

manufacturer_part_number

Unique manufacturer ID for the item.

string

N

name

Title of item. Max size: 100.

string

Y

pattern

Pattern or graphic print on an item. Max size: 100.

string

N

price

Cost of the item.

string

Y

product_type

Retailer-defined category for item. Max size: 750.

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

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

string

N

sale_price

Discounted price if the item is on sale. Currency should be specified as the ISO 4217 currency code. Example: 9.99 USD.

string

N

sale_price_start_date

End date and time for the sale.

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

string

N

sale_price_end_date

Start date and time for the sale.

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

string

N

shipping

Shipping information

array<object>

N

size

Size of item. Example: Small or XL.

string

N

url

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

string

Y

Example - /{catalog_id}/batch

curl \
  -d @body.json \
  -H "Content-Type: application/json"
  {
    "access_token": "<ACCESS_TOKEN>",
    "item_type": "PRODUCT_ITEM",
    "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": [
               {
                  "shipping_country": "US",
                  "shipping_region": "CA",
                  "shipping_service": "service",
                  "shipping_price_value": "10",
                  "shipping_price_currency": "USD"
               }
          ],
          "condition": "new",
          "url":"http://www.images.example.com/t-shirts/1.png"
        }
      },
      {
        "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

You can use the applinks field to specify deep link information; it works in a similar way to Deep Links. Provide your deep link information in the JSON format shown below.

"applinks" : {"ios": [{"url":"example-ios://electronic","app_store_id":42,"app_name":"Electronic Example iOS"}],"iphone": [{"url":"example-iphone://electronic","app_store_id":43,"app_name":"Electronic Example iPhone"}],"ipad": [{"url":"example-ipad://electronic","app_store_id":44,"app_name":"Electronic Example iPad"}],"android": [{"url":"example-android://electronic","package":"com.electronic","class":"com.electronic.Example","app_name":"Electronic Example Android",}],"windows_phone": [{"url":"example-windows://electronic","app_id":"64ec0d1b-5b3b-4c77-a86b-5e12d465edc0","app_name":"Electronic Example Windows"}]}

There's a minor difference in the field names compared to the ones in Deep Links as each app type is a separate node and is enclosed in their respective fields.

'data\[applinks\]\[android\]' is an array with only one value specified under it. This is the same case for other app types.

We don't support iOS Universal Links.

Send Product Updates - /{catalog_id}/items_batch

To create, update or delete products in your catalog, make an HTTP POST call to:

https://graph.facebook.com/<API_VERSION>/<CATALOG_ID>/items_batch?requests=<REQUESTS>
Parameter Type Description

allow_upsert

boolean

When allow_upsert is false, update requests for items not existing in the catalog will not be completed. Otherwise, new items are created.

item_type

enum

The type of items in the request. Values: DESTINATION, FLIGHT, HOME_LISTING, HOTEL, HOTEL_ROOM, PRODUCT_ITEM, VEHICLE.

requests

object

A JSON object containing all requests.

requests.data

object

A JSON object containing fields and values for a product.

  • When the method is CREATE, this object must contain all the required fields for the specified item_type.
  • When the method is UPDATE, it can contain any fields.

requests.method

string

CREATE, UPDATE, DELETE

requests.data

object

A JSON object containing fields and values for a product.

  • When the method is CREATE, this object must contain all the required fields for a product.
  • When the method is UPDATE, it can contain any fields.

For more details, see API reference.

Limitations - /{catalog_id}/items_batch

  • The requests param can contain up to 5,000 updates.
  • For each catalog, you can make up to 100 calls per hour. If that's not sufficient, please contact us.

Supported Fields - PRODUCT_ITEM

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

FieldDescriptionTypeRequired

additional_image_urls

URLs for up to 9/10 different images

array<string>

N

age_group

Accepted values are newborn, infant, toddler, kids, adult.

string

N

applinks

Links to mobile apps.

object<array<object>>

N

availability

  • 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

string

Y

color

Item color. Max size: 100.

string

N

condition

Product condition: new, refurbished, or used.

string

Y

custom_label_0

Optional. Additional information about item. Max size: 100.

string

N

custom_label_1

Optional. Additional information about item. Max size: 100.

string

N

custom_label_2

Optional. Additional information about item. Max size: 100.

string

N

custom_label_3

Optional. Additional information about item. Max size: 100.

string

N

custom_label_4

Optional. Additional information about item. Max size: 100.

string

N

description

Short text describing product. Max size: 5000.

string

Y

gender

Options: male, female, unisex.

string

N

google_product_category

Predefined values (string or category ID) from Google's product taxonomy. Max size: 250. Example: Apparel & Accessories > Clothing > Dresses or 2271.

string

N

gtin

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

string

N

id

Product ID

string

Y

image_link

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.

string

Y

link

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

string

Y

manufacturer_part_number

Unique manufacturer ID for product.

string

N

pattern

Pattern or graphic print on a product. Max size: 100.

string

N

price

Cost of item and currency. Currency should follow ISO 4217 currency codes. Example: 9.99 USD.

string

Y

sale_price

Discounted price if the item is on sale. Currency should follow the ISO 4217 currency code. Example: 9.99 USD.

string

N

sale_price_effective_date

Start and end date and time for the sale, separated by slash. Example: 2014-11-01T12:00-0300/2014-12-01T00:00-0300.

string

N

shipping

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

string

N

size

Size of item. Example: Small or XL.

string

N

title

Title of item. Max size: 100

string

Y

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.

Example - 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"
        }
      },
      {
        "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.


Supported Fields - HOTEL

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

Field Description Type Required

address

Address of the hotel.

object<string>

Y

applink

Links to mobile apps.

object<string>

N

base_price

Base price of the hotel room per night. Required: Add the currency type to the price. Use ISO 4217 for currency standards. Example: USD for U.S. dollars.

string

Y

brand

Brand of the hotel chain.

string

N

description

Short description of the hotel. Max character limit: 5000.

string

Y

guest_rating

Guest ratings of the hotel.

array<object>

N

hotel_id

Unique ID for the hotel.

string

Y

image

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

array<object>

Y

latitude

Latitude location of the hotel.

string

Y

longitude

Longitude location of the hotel.

string

Y

loyalty_program

Loyalty program used for the hotel.

string

N

margin_level

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

string

N

name

Name of the hotel.

string

Y

neighborhood

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

array<string>

N

phone

Phone number with country code.

string

N

sale_price

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. Use ISO 4217 currency standards. Example: USD for U.S. dollars.

string

N

star_rating

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

string

N

url

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

string

Y

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

Example - 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"]
}

Supported Fields - HOTEL_ROOM

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

FieldDescriptionTypeRequired

base_price

Base price for 1 night. Currency should follow ISO 4217 currency codes. Example: 9.99 USD.

string

Y

description

Short text describing the room. Max size: 5000.

string

Y

hotel_retailer_id

Unique ID for hotel retailer.

string

Y

hotel_room_id

Unique ID for hotel.

string

Y

image

Images of the room.

array<object>

Y

name

Name of the room. Max size: 100.

string

Y

url

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

string

Y

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

Example - 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"]
  }

Supported Fields - FLIGHT

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

FieldDescriptionTypeRequired

description

Description of the flight. Max character limit: 5000.

string

N

destination_airport

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

string

Y

destination_city

Name of the destination city for the flight.

string

N

image

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.

array<object>

Y

origin_airport

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

string

Y

origin_city

Name of the origin city for the flight.

string

N

price

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.

string

N

url

Link to the website where you can book the flight.

string

N

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

Example - FLIGHT

curl \
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"]
  }

Supported Fields - DESTINATION

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

FieldDescriptionTypeRequired

applink

Links to mobile apps.

object<string>

N

address

Address of the hotel.

object<string>

Y

description

Short paragraph describing the destination. Max character limit: 5000.

string

N

destination_id

Unique ID for the destination. Max character limit: 100.

string

Y

image

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.

array<object>

Y

latitude

Latitude location of the destination.

string

Y

longitude

Latitude location of the destination.

string

Y

name

Name of the destination.

string

Y

neighborhood

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

array<string>

N

price

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

string

N

price_change

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""

string

N

type

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

array<string>

Y

url

Link to the website where you can book the destination.

string

Y

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

Example - 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"]
}

Supported Fields - HOME_LISTING

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

FieldDescriptionTypeRequired

applink

Links to mobile apps.

object<string>

N

address

Street address for the home listing.

object<string>

Y

availability

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

string

Y

available_dates_price_config

Price configurations.

array<object>

N

description

Short paragraph describing the home listing. Max character limit: 5000.

string

N

image

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.

array<object>

Y

latitude

Latitude location of the home listing.

string

N

longitude

Longitude location of the home listing.

string

N

listing_type

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.

string

N

name

Name of the home listing.

string

Y

neighborhood

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

array<object>

N

num_baths

Number of bathrooms.

string

N

num_beds

Number of bedrooms.

string

N

num_units

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

string

N

price

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.

string

Y

price_change

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""

string

N

property_type

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

string

N

url

Link to the website where you can view the listing.

string

Y

year_built

Year when the home was built.

string

N

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

Example - HOME_LISTING

curl \
  -d @body.json \
  -H "Content-Type: application/json"
  {
    "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"]
}

Supported Fields - VEHICLE

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

FieldDescriptionTypeRequired

address

Street address for the dealership.

object<string>

Y

body_style

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

string

Y

condition

Condition of the vehicle. Supported values: EXCELLENT, GOOD, FAIR, POOR, Other.

string

N

description

Short text describing the vehicle. Max size 5000.

string

Y

drivetrain

Drivetrain of the vehicle. Supported values: 4X2, 4X4, AWD, FWD, RWD, Other.

string

N

exterior_color

Exterior color of the vehicle.

string

Y

fuel_type

Fuel type of the vehicle. Supported values: DIESEL, ELECTRIC, GASOLINE, FLEX, HYBRID, OTHER.

string

N

image

Images for the vehicle.

array<object>

Y

latitude

Latitude location of the dealership.

string

Y

longitude

Longitude location of the dealership.

string

Y

make

Make or brand of the vehicle. Example: Ford

string

Y

mileage

For used vehicles, this is the mileage of the vehicle in kilometers or miles. For new vehicles, use ""zero"".

string

Y

model

Model of the vehicle. Example: Fusion

string

Y

price

Price/cost of the vehicle. The price is a number followed by the currency code ISO 4217 standards. Use ""."" as the decimal for the price.

string

Y

sale_price

Sale or special price for the vehicle.

string

N

state_of_vehicle

Current state of the vehicle. Supported values: NEW, USED, CPO (certified pre-owned).

string

N

title

Title of the vehicle. Max characters: 100.

string

Y

transmission

Transmission type of the vehicle. Supported values: Automatic or Manual.

string

N

url

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

string

Y

vehicle_id

Unique ID for item. Can be a variant for a vehicle. If there are multiple instances of the same ID, we ignore all instances.

string

Y

vin

Vehicle identification number.

string

N

year

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

string

Y

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

Example - 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"]
}

Get Batch Request Status - /{catalog_id}/check_batch_request_status

To get the status of a batch request, use a handle (returned from a call to {catalog_id}/batch) and make a GET call to:

https://graph.facebook.com/<API_VERSION>/<CATALOG_ID>/check_batch_request_status?handle=<HANDLE>
FieldDescriptionTypeRequired

handle

Unique handle of a batch request. Supported in Versions 3.1 and prior.

string

Y

For more details, see API reference.

Example - /{catalog_id}/check_batch_request_status

curl -G \
  -d 'handle=AczwaOW7j_EuQ5peV3kGq8X9qc7cDiv_kFrrHkdKuG7LkpkkqK5939wgdoduSQ45FGK5vKdVqOaSDJEun-fvbsR1kk8Rd53AZyD1WThSemo26Q'-d 'access_token=<ACCESS_TOKEN>'
  https://graph.facebook.com/<API_VERSION>/<CATALOG_ID>/check_batch_request_status

Sample Response - /{catalog_id}/check_batch_request_status

{
    "data": [
        {
            "status": "finished",
            "errors_total_count": 1,
            "errors": [
                {
                    "line": 0,
                    "id": "retailer-4",
                    "message": "Invalid value: Value passed at position 0 (id=retailer-199) is invalid: \"You cannot create a EntProductItem without required field Availability\""
                }
            ]
        }
    ]
}