Catalog Batch API

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

The API consists of two endpoints:

Send product updates

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

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

requests

Object

A JSON object containing all requests.

requests.method

string

Either CREATE, UPDATE or DELETE.

requests.retailer_id

string

The id of a product given by the retailer.

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 visit API reference.

Product fields that supported for CREATE and UPDATE method:

  • additional_image_urls
  • availability
  • age_group
  • applinks
  • brand
  • category
  • color
  • condition
  • currency
  • custom_label_0
  • custom_label_1
  • custom_label_2
  • custom_label_3
  • custom_label_4
  • description
  • gender
  • gtin
  • image_url
  • manufacturer_part_number
  • name
  • pattern
  • price
  • product_type
  • sale_price
  • sale_price_end_date
  • sale_price_start_date
  • shipping
  • size
  • url

Learn more about product fields in this API Reference.

You can use the applinks field to specify deep link information and it works in a similar way to Product Deep Links. Provide your deep link information in the JSON format shown below. Also note that there is a minor difference in the field names compared to the ones in Product Deep Links as each app type is a separate node and is enclosed in their respective fields. Also note that 'data[applinks][android]' is an array with only one value specified under it. This is the same case for other app types.

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

Example

curl \
https://graph.facebook.com/<API_VERSION>/<PRODUCT_CATALOG_ID>/batch \
-d @body.json \
-H "Content-Type: application/json"

  // body.json

  {
    "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",
          "currency": "USD",
          "description": "product description",
          "image_url": "http://www.images.example.com/t-shirts/1.png",
          "name": "product name",
          "price": "100",
          "url": "http://www.example.com/t-shirts/1.html",
          "shipping": [
            {
              "country": "US",
              "region": "CA",
              "service": "Air",
              "price_value": 10.5,
              "price_currency": "USD"
            }
          ]
        }
      },
      {
        "method": "UPDATE",
        "retailer_id": "retailer-3",
        "data": {
          "availability": "out of stock"
        }
      }
    ]
  }
  
  // Sample response
  
  {
    // Exactly one handle will be returned
    "handles": ["AczwaOW7j_EuQ5peV3kGq8X9qc7cDiv_kFrrHkdKuG7LkpkkqK5939wgdoduSQ45FGK5vKdVqOaSDJEun-fvbsR1kk8Rd53AZyD1WThSemo26Q"]
  }

Limitations

There are a few limitations that /{product_catalog_id}/batch has:

  • requests param can contain up to 5000 updates.
  • For each catalog you can make up to 100 calls per hour. If that's not enough for you please contact us.

Get the status of a request

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

https://graph.facebook.com/<API_VERSION>/<PRODUCT_CATALOG_ID>/check_batch_request_status?handle=<HANDLE>
Parameter Type Description

handle

string

Unique handle of a batch request

For more details visit API reference.

Example

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

// Sample response

{
  "data": [
    {
      "handle": "AczwaOW7j_EuQ5peV3kGq8X9qc7cDiv_kFrrHkdKuG7LkpkkqK5939wgdoduSQ45FGK5vKdVqOaSDJEun-fvbsR1kk8Rd53AZyD1WThSemo26Q",
      "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\""
        }
      ]
    }
  ]
}