Ads News
Product Catalog Marketing API

Today we are announcing several new endpoints that enable you to manage catalogs in bulk and provide valuable insights. You can monitor the health of your catalogs via our API, and proactively track and resolve issues related to events and quality, receiving insights into any pixel and app events associated with a catalog.

Batch API

The Batch API makes it easier for advertisers to manage large catalogs. Advertisers can:

  • Send a batch of requests to create, update, or delete products from their catalog
  • Check the status of a batch request

Here's an example for batch requests:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$requests =  array(
    array(
        'method' => 'CREATE',
        'retailer_id' => 'retailer-product-id-123',
        'data' => array(
          'availability' => 'in stock',
          'brand' => 'Niky',
          'category' => 't-shirts',
          'currency' => 'USD',
          'description' => 'This is the product description.',
          'image_url' => 'http://www.images.example.com/t-shirts/1.png',
          'name' => 'My product name',
          'price' => '100',
          'url' => 'http://www.example.com/t-shirts/1.html',
        ),
    ),
);


$data = Api::instance()->call(
  '/'.<CATALOG_ID>.'/batch',
  RequestInterface::METHOD_POST,
  array('requests' => $requests))->getContent();
curl \
  -F 'requests=[ 
    { 
      "method": "CREATE", 
      "retailer_id": "retailer-product-id-123", 
      "data": { 
        "availability": "in stock", 
        "brand": "Niky", 
        "category": "t-shirts", 
        "currency": "USD", 
        "description": "This is the product description.", 
        "image_url": "http:\/\/www.images.example.com\/t-shirts\/1.png", 
        "name": "My product name", 
        "price": "100", 
        "url": "http:\/\/www.example.com\/t-shirts\/1.html" 
      } 
    } 
  ]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CATALOG_ID>/batch

You can request up to 500 changes per call. This can be a mix of CREATE, UPDATE and DELETE methods. See Using Products Batch API for more details.

Checks API

The Checks API allows advertisers to get information about the following pixel and app-event issues:

  • If all mandatory events for dynamic ads are sent.
  • If all mandatory fields are sent for each event.
  • If the number of events received for a pixel has declined in the last 24 hours.

Example of request, for a pixel:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$data = Api::instance()->call(
  '/' . <PIXEL_ID> . '/da_checks',
  RequestInterface::METHOD_GET)->getContent();
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<PIXEL_ID>/da_checks

This returns a list of checks and indicates if a pixel passed or failed them, as shown below:

{
  "data": [
    {
      "description": "Pixel hasn't sent some or any events for dynamic ads (ex: ViewContent, AddToCart, Purchase) at least once in the last 24 hours.",
      "key": "pixel_missing_dpa_event",
      "result": "failed",
      "title": "Pixel is not sending DPA events"
    },
    {
      "description": "Pixel events might be missing parameters some or all of the time.",
      "key": "pixel_missing_param_in_events",
      "result": "passed",
      "title": "Pixel missing parameter in DPA events"
    },
    {
      "action_uri": "https://www.facebook.com/ads/manage/pixels/?pixel_id=<PIXEL_ID>&m2w=1",
      "description": "The number of pixel events has dropped to less than half of the weekly average.",
      "key": "pixel_decline",
      "result": "passed",
      "title": "Decline in number of pixel events"
    }
  ]
}

The same checks are available for apps if you substitute <PIXEL_ID> for <APP_ID>. See Using the Checks API for details.

Quality API

Advertisers can use the Quality API to review issues impacting the quality of products in a catalog. Quality issues raise awareness about the accuracy, completeness and freshness of the data in a feed or catalog. This enables you to know:

  • If the fields such as brand, category, description and image are correctly included in your feed.
  • If you have fields with duplicate information.

Here's a sample request and response for quality issues at the catalog level:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$data = Api::instance()->call(
  '/' . <CATALOG_ID> . '/quality_issues',
  RequestInterface::METHOD_GET)->getContent();
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CATALOG_ID>/quality_issues

This returns an explicit description message together with a list of samples to illustrate the issue:

{
  "data": [
    {
      "description": "Accurate product descriptions help people better understand what the product is or does. They also allow us to advertise your products more efficiently.",
      "issue_type": "qualified_description",
      "property_names": [
      "description",
      ],
      "summary": "Content is too short",
      "count": 121,
      "samples": [
        {
        "id": "1111111111111111",
        "description": "Phone 19 inch",
        "retailer_id": "10"
        },
        {
        "id": "2222222222222222",
        "description": "Phone Tab A",
        "retailer_id": "100"
        },
        {
        "id": "333333333333333",
        "description": "Tablet X White",
        "retailer_id": "101"
        },
        {
        "id": "4444444444444444",
        "description": "Tablet Z Black",
        "retailer_id": "104"
        },
      ]
    },
  ],
}

See Getting feedback on the quality of your catalog and feed for more details about quality checks available.

Events API

Advertisers can use the Events API to view statistics about their pixel fires and app events from sources associated with a catalog. This information can be used to:

  • Track the total matched and unmatched content ids from pixel fires or app events for your catalog on a daily basis.
  • Identify failures on specific devices and event types.

You can make the following call:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$data = Api::instance()->call(
  '/' . <CATALOG_ID> . '/event_stats',
  RequestInterface::METHOD_GET)->getContent();
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CATALOG_ID>/event_stats

This returns an array of elements containing the number of matched and unmatched content ids per event type. Example of response (truncated):

{
  "data": [
    {
      "date_start": "2017-03-11",
      "date_stop": "2017-03-11",
      "event": "AddToCart",
      "event_source": {
        "id": "<PIXEL_ID>",
        "source_type": "PIXEL"
      },
      "total_matched_content_ids": 620,
      "total_content_ids_matched_other_catalogs": 4509,
      "total_unmatched_content_ids": 12503,
      "unique_matched_content_ids": 195,
      "unique_content_ids_matched_other_catalogs": 1010,
      "unique_unmatched_content_ids": 2079
    },
    {
      "date_start": "2017-03-11",
      "date_stop": "2017-03-11",
      "event": "Purchase",
      "event_source": {
        "id": "<APP_ID>",
        "source_type": "APP"
      },
      "total_matched_content_ids": 121,
      "total_content_ids_matched_other_catalogs": 139,
      "total_unmatched_content_ids": 1762,
      "unique_matched_content_ids": 79,
      "unique_content_ids_matched_other_catalogs": 111,
      "unique_unmatched_content_ids": 921
    },
    ...
  ]
}

You can also request statistics broken down by device type, e.g. desktop, mobile_iphone, mobile_android_phone, etc.

See Getting feedback on pixel and app events for more details about event statistics.