Feed API Reference

Inventory should be uploaded to Facebook using a Product Catalog. For each product catalog, a product feed should be provided in one of the supported formats (CSV, TSV, RSS XML, ATOM XML).

In this section:

Uploading Inventory

You can create a Product Catalog manually in the Catalog Manager, or programmatically. Upload or configure your products using the Product Feed API.

The product feed will be used as the source of truth for updating product catalogs on Facebook, and fetched by Facebook periodically according to the configured interval. You should store the product feed ID, and use it to get upload status, errors and to change upload schedule.

Note: Catalogs do not currently support using the Batch API for CREATEs at this time. To create inventory programatically, use the Feed API.

POST https://graph.facebook.com/vX.X/{product-catalog-id}/product_feeds

Request

AttributeTypeRequiredDescription

name

string

Required

schedule

schedule

Required

schedule object

Read the Product Feed Schedule specification for more details.

AttributeTypeRequiredDescription

url

string

Required

interval

string

Required

hour

number

Optional

Scheduled feeds do not support uploads more frequently than once per hour. If you need to update inventory faster, please use the Catalog Batch API.

Response

{
  "id": 215042069082048
}

Handling Product Feed Upload Errors

Read the Product Feed Upload Errors documentation.

We recommend that you check catalog upload errors and warnings after each upload session. You can achieve this by going to the Diagnostics section of your Catalog Manager, or use the Feed API to request a sampling of errors and warnings. Start by first querying for recent upload sessions.

Request

GET https://graph.facebook.com/vX.X/{product-feed-id}/uploads

Sample Response

{
  "data": [
    {
      "id": "493476498092860",
      "start_time": "2019-07-15T12:38:36+0000",
      "end_time": "2019-07-15T12:38:47+0000"
    }
  ]
}

Then, use the value returned in the id field to retrieve a sampling of errors and warnings.

Request

GET https://graph.facebook.com/vX.X/{upload-session-id}/errors

Sample Response

A fatal severity here means the item cannot be ingested by Facebook; a warning severity means some recommended attributes are missing or malformed.

{
  "data": [
    {
      "id": 1510567479166488,
      "summary": "A required field is missing: price.",
      "description": "Products need to have prices to run in ads. Include a price for each product in your data feed file and upload it again. Prices must include cost and an ISO currency code (for example: 10 USD instead of $10 for American dollars).",
      "severity": "fatal",
      "samples": {
        "data": [
          {
            "row_number": 2,
            "retailer_id": "yj9bpbpub5t8t22kgbq6",
            "id": "1677559492523068"
          },
          {
            "row_number": 5,
            "retailer_id": "ujn33tvbyv2vmdpo7ecb",
            "id": "1529743440653137"
          }
        ]
      }
    },
    {
      "id": 275241589314958,
      "summary": "GTIN is incorrectly formatted",
      "description": "Check that the GTIN (Global Trade Identification Number) for each of your products is in the correct format. Accepted types include UPC, EAN, JAN, and ISBN.",
      "severity": "warning",
      "samples": {
        "data": [
          {
            "row_number": 4,
            "retailer_id": "bxwb1pho9o43uxjxikcg",
            "id": "538700559625644"
          }
        ]
      }
    }
  ]
}

Downloading a full Product Feed Errors Report

Getting a sampling of errors and warnings is often sufficient to fix most Product Feed Upload issues. However, you may need the full list of errors to do deeper analysis. To download a full list of errors and warnings, you must first query the most recent upload session (see section above).

You can request the full error report to be generated for a given upload session ID.

Request

POST https://graph.facebook.com/vX.X/{upload-session-id}/error_report

Response

{
  "success": true
}

In case the report is not ready, repeat the last call after a few seconds. You can then download the report itself.

Request

GET https://graph.facebook.com/vX.X/{upload-session-id}/?fields=error_report

Response

{
  "error_report": {
    "report_status": "WRITE_FINISHED",
    "file_handle": "{link-to-the-file-location}"
  },
  "id": "493476498092860"
}

You should find a URL that you can download (e.g with wget, curl, etc.). The downloaded file will contain the full error report.

If you get the error: "Cannot access an object not managed by the business owning this app", please make sure that the app you're using belongs to the business (Business Settings > Account > Apps).