Catalog Batch API

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.

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