Catalog Batch API

This guide describes how to use the Catalog Batch API by use case:

  • For dynamic ads catalogs — 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.

  • For commerce catalogs — Use this API if you need to update product information more often then once an hour (otherwise use feed update). You can update multiple items in a single HTTP request. Currently creating products for checkout catalogs is not supported.


Catalog Batch API — Dynamic Ads

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.

4.0, 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, such as products, hotels, hotel rooms, flights, destination, home listings, vehicle, and vehicle offers.

4.0, 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.

4.0, 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.

applink

type:

object<>

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

"applink" : {"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\[applink\]\[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_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.

offer_price

type: string

Required for Daily Deals

Discounted price if the item is offered as a Daily Deal. Format price as the cost, followed by the 3-digit ISO currency code, with a space between cost and currency. The offer_price field value must be lower than the price field value by at least 15%.

Example: 9.99 USD.

offer_price_effective_date

type: string as two ISO-8601 timestamps

Required for Daily Deals

Start and end date and time for the deal, separated by slash.

Example: 2018-06-01T12:00-0300/2018-12-01T00:00-0300.

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.

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.

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.

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.

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.

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

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

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.

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.

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

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.

Catalog Batch API — Commerce

Use this API if you need to update product information more often then once an hour (otherwise use feed update). You can update multiple items in a single HTTP request. Currently creating products for checkout catalogs is not supported.

This Catalog Batch API consists of these endpoints:

Endpoint Description In This Doc

POST /{catalog_id}/items_batch

Sends a batch of requests for a catalog.

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}/items_batch) and make a GET call.

Get Batch Request Status

Send Product Updates

To 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. E-commerce value: PRODUCT_ITEM.

requests

object

A JSON object containing all requests.

requests.data

object

A JSON object containing fields and values for a product.

requests.method

string

CREATE, UPDATE, DELETE.

For more details, see API reference.

Limitations

  • 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

These product fields are supported for 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.

offer_price

type: string

Required for Daily Deals

Discounted price if the item is offered as a Daily Deal. Format price as the cost, followed by the 3-digit ISO currency code, with a space between cost and currency. The offer_price field value must be lower than the price field value by at least 15%.

Example: 9.99 USD.

offer_price_effective_date

type: string as two ISO-8601 timestamps

Required for Daily Deals

Start and end date and time for the deal, separated by slash.

Example: 2018-06-01T12:00-0300/2018-12-01T00:00-0300.

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.

size

type: string

Optional.

Size of item. Example: Small or XL.

title

type: string

Required.

Max size: 100.

Title of item.

The UPDATE method would also try to create items if they don't already exist.

Learn more about product fields in the API Reference.

Example

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": "UPDATE",
        "data": {
          "inventory": "156",
          "id": "retailer-2",
        }
      }
    ]
  }

Sample Response

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

Learn more about Adding Catalog Items with a Data Feed.

Get Batch Request Status

It is essential to review all errors from batch API requests handles as it is not guaranteed that changes were made to product items. You can also for testing purposes look up updated items using catalog filters.

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.

For more details, see API reference.

Example

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

{
    "data": [
        {
            "status": "finished",
            "errors_total_count": 1,
            "errors": [
                {
                    "line": 0,
                    "id": "retailer-2",
                    "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.