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. Used only for product items.

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. Used for a variety of different objects (product items, vehicles, hotels, flights, and so on.

3.3, 3.2

Send Item Updates

GET /{catalog_id}/check_batch_request_status

Checks the status of a batch request. Use a handle (returned from a call to {catalog_id}/batch) and make a GET call.

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

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.

applinks

type:

object<array>

Optional.

Links to mobile apps.

category

type: string

Optional.

Category of the item string.

category

type: string

Required.

Category type of the item.

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.

inventory

type: number

Optional.

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

manufacturer_part_number

type: string

Optional.

Unique manufacturer ID for the item.

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: string

Required.

Cost of the item.

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: string

Optional.

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

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.

Example - /{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": [
             {
                "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"
        "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

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:

FieldDescription

additional_image_urls

type:

array<string>

Optional.

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

applinks

type:

object<array<object>>

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. Options: male, female, unisex.

google_product_category

type: string

Optional.

Predefined values (string or category ID) from Google's product taxonomy. Max size: 250. 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.

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

sale_price

type: string

Optional.

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

sale_price_effective_date

type: string

Optional.

Start and end date and time for the sale, separated by slash. 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.

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


Supported Fields - 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.

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

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

For supported fields for the CREATE and UPDATE methods for type VEHICLE, see .

Supported fields are available for Vehicle and Dealership.

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

handle

type: string

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

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

Dispatched

The action was added to the queue.

Started

The action was started; some of the requests might have been updated.

Finished

The action was completed successfully; individual requests with errors were not saved.

Canceled

The action was manually canceled.

Error

During the execution of the action, an unexpected issue occurred; some of the requests might not have finished successfully.