Catalog Batch API

Use this API 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 Catalog Batch 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

CREATE, UPDATE or DELETE

requests.retailer_id

string

The id of a product.

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

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

Learn more about product fields in this API Reference.

Product Deep Links

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

  • There's 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.

  • '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.
"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"
            }
          ],
          "condition": "new"
        }
      },
      {
        "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, see 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\""
        }
      ]
    }
  ]
}