Facebook Catalog Batch API integration through ROI Hunter

If you have a catalog with a big amount of products and quickly-changing inventory, using product feeds might not be a viable option for you. Instead of using a product feed to update a catalog, it's possible to use Facebook's Catalog Batch API to send real-time information about the products that have changed via HTTP requests.

In order for you to use our features such (Image Templates, Dynamic Slideshows, Product Insights, etc.) with Catalog Batch API, we provide an endpoint where you send requests, we enhance products and forward them to Facebook.

NOTE: We don't support API integration combined with product feed source file (XML or CSV feed). Once the catalog is whitelisted for out API, it should not contain any other data source.

This article covers:

• Implementation

• CREATE method

• UPDATE method

• DELETE method

• Limitations

• Check batch request status

• Maintaining catalog quality

• Features

• FAQ

Implementation

ROI Hunter API is very similar to Facebook API, and it is mostly about changing the endpoint name. But there might be a few differences and specifics. All implementation details are described in this article. We highly recommend studying it carefully.

The endpoint for ROI Hunter is:

POST 
https://products-api.roihunter.com/api/v2/catalogs/{catalogFacebookId}/batch

Note: Endpoint /items_batch is deprecated, please use /batch endpoint.

You need an authorization token to send API requests. Contact us, and we will provide you with the token.

Payload

CREATE method

Use this method to add new products to the catalog. CREATE requests on products which already exist are accepted and converted to updates.

Required fields in requests.data:

At least one of the following fields must be set in order to create valid product.

Optional fields in requests.data:

Example request:

{
  "access_token": "<ACCESS_TOKEN>",
  "requests": [{
    "method": "CREATE",
    "retailer_id": "retailer_id_1",
    "data": {
      "applinks": {
        "ios": [{
          "url": "example-ios://example",
          "app_store_id": 123,
          "app_name": "app name"
        }],
        "android": [{
          "app_name": "app name",
          "package": "com.package.name",
          "url": "example-android://example"
        }]
      },
      "availability": "in stock",
      "brand": "Nike",
      "category": "t-shirts",
      "condition": "new",
      "currency": "USD",
      "description": "product description",
      "image_url": "http://www.images.example.com/t-shirts/1.png",
      "name": "product name",
      "price": 1000,
      "retailer_product_group_id": "product-group-1",
      "shipping": [{
        "shipping_country": "US",
        "shipping_region": "CA",
        "shipping_service": "service",
        "shipping_price_value": "10",
        "shipping_price_currency": "USD"
      }],
      "url": "http://www.images.example.com/t-shirts/1.png"
    }
  }]
} 

Example response (status code 200):

{
  "handles": [
    "Aczq4HLYFA8flS0gWr5YzLuShNtJnxFh5K4kLJQeY..."
  ]
}

Example response (status code 200) for request, which contains invalid product URL and unsupported extra field:

{
  "handles":[ 
    "Aczq4HLYFA8flS0gWr5YzLuShNtJnxFh5K4kLJQeY..."
  ],
  "validation_status": [
    {
      "retailer_id": "1",
      "errors": [
        {
          "message": "Product has the attribute 'URL' in unsupported format. Please make sure every product has a valid attribute 'URL' starting with one of: 'http://', 'https://', 'ftp://', 'sftp://'."
        }
      ],
      "warnings": [
        {
          "message": "The request contains unsupported product fields, which will be ignored. Ignored fields: {'some_field'}"
        }
      ]
    }
  ]
}

Example response (status code 200) for request, which was not forwarded to FB because there were no changes comparing to the previous state:

{
  "message": "There are no applicable requests in provided payload. No API calls to Facebook will be made."
}

Example response (status code 400) for request, which is missing method (CREATE/UPDATE/DELETE) in the data:

{
  "error": {
    "code": "request_invalid_data",
    "message": "Errors: required key not provided @ data['requests'][0]['method']",
    "severity": "critical"
  }
}

Example response (status code 400) for request, which exceeded API rate limit (you can ask Facebook to increase the API limits for you)

{
  "error": {
    "message": "Calls to this api have exceeded the rate limit. (613)"
  }
}

Example response (status code 500) for request, which failed unexpectedly

{
  "error": {
    "message": "An unexpected error has occurred. Please retry your request later."
  }
}

UPDATE method

Use this method to update values of existing products in catalog. This method doesn’t have any required fields, the only limitation is that at least one field to update must be sent.

Example update request:

{
  "access_token": "<ACCESS_TOKEN>",
  "requests": [
    {
      "method": "UPDATE",
      "retailer_id": "retailer_id_1",
      "data": {
        "price": 800
      }
    }
  ]
}

DELETE method

Use this method to delete products in catalog.

Example delete request:

{
  "access_token": "<ACCESS_TOKEN>",
  "requests": [
    {
      "method": "DELETE",
      "retailer_id": "retailer_id_1"
    }
  ]
}

Note: before starting with the ROI Hunter endpoint, you can test your implementation directly with Facebook API. This requires a Facebook access token. You can get one by selecting "Get Token" in Facebook Graph API Explorer.

Limitations

• Facebook limits the request param up to 5000 updates and up to 100 requests per hour for each catalog. If you are receiving errors about hitting the limits, please lower the number of requests or talk to your Facebook Client Partner and request limit increase. ROI Hunter has no power to affect this limitation defined by Facebook.

• Facebook also has a limitation on how big payload can be in terms of Bytes. In case of too big payload, Facebook will return error with status code 500 and response {"error":{"code":1,"message":"Please reduce the amount of data you're asking for, then retry your request"}} In such a case you need to make your payload smaller and try again.

Check Batch Request Status

A successful batch update returns handle, which can be used to check status of the update. To check the status use endpoint:

GET 
https://products-api.roihunter.com/api/v2/catalogs/{catalogFacebookId}
/check_batch_request_status

Parameters

Example response:

{
  "data": [
    {
      "handle": "Aczq4HLYFA8flS0gWr5YzLuShNtJnxFh5K4kLJQeY...",
      "status": "finished",
      "errors_total_count": 0,
      "errors": [],
      "warnings": []
    }
  ]
}

Maintaining catalog quality

There will always be the risk that some requests fail. As you're only communicating changes with Catalog Batch API (instead of always providing the whole state of your catalog as with feed files), there's the possibility that the Catalog on Facebook will start drifting apart from your actual inventory status. Thus, we recommend running full updates for all your products periodically, for example, once per day.

Features

ROI Hunter allows all its feed related features also for API catalogs. You can

• apply image templates, dynamic slideshows

• connect product insights from Google Analytics, Google shopping and even connecting the custom source with product data

• promote products dynamically filtered according

We recommend you to not change this kind of settings too frequently. Bear in mind that if you e.g. apply an image template, we have to re-upload the whole product inventory which can take even several hours based on the number of products and FB limits.

FAQ

How long does it take to process the request?

It takes about a second to forward the request to Facebook. But if you have also image templates applied on the catalog, it may take about a minute based on the count of created/updated products.

Even though we are constantly working on improvements, to ensure correct processing of API requests, you should set the request timeout to 300 seconds, what corresponds to global server time-out of the API.

Is there any limitation in number of requests?

ROI Hunter does not apply any limitation. We accept the limitation defined by Facebook for your Product catalog. The limits are specific per catalog. If you are receiving errors about hitting the limits, please lower the number of requests or talk to your Facebook Client Partner and request limit increase. ROI Hunter has no power to affect this limitation defined by Facebook.

What I need to check to make sure that my request passed properly and the product is in required state?

1. Check request response and its message.

2. Check batch request status.

How should I react to request issues?

If the request status code is 500, or the error message says Calls to this api have exceeded the rate limit. (613), you can re-try the same request later.

For any other error, you should edit your request accordingly to make it valid. The issues are described in the response message and in batch request status.

How to fix invalid product state (incorrect availability, price, image) for API integrated catalog?

1. Make sure that you follow this documentation and your requests are passing. Check the latest request containing the product. If you cannot find it, you can just send the same product again.

2. Check the latest product data that you have sent to us - are they correct? Send the product again with the correct data.

3. If re-sending did not help, please get in touch with us for detailed investigation. Please provide: Product Catalog ID, problematic product(s) ID(s), expected and actual value.

How can I check that the product is in requested state on Facebook?

You can check the products in Commerce Manager (former Catalog Manager) in Facebook Business Manager, but please keep in mind that the images displayed on this page might not be always up to date.

If you have access to Facebook Graph API, you can check the products also there. Details about Product Items can be seen in Facebook Developer documentation.

In this example, you can see a call to check product availability, price and images. The product can be filtered by retailer_id field.

https://graph.facebook.com/v8.0/<catalog_id>/products?fields=id,name,retailer_id,url,availability,price,sale_price,image_url,image_cdn_urls,additional_image_urls,additional_image_cdn_urls&filter={"retailer_id":{"eq":"4"}}

Here is an example response in Graph API explorer tool:

The fields image_url and additional_image_urls represent the images provided by you (or by ROI Hunter when the image template is applied).

image_cdn_urls and additional_image_cdn_urls represent images fetched to Facebook cache. If these fields are empty, Facebook has not fetched the current images yet (no Pixel or App event has not been fired for the product since the last update).

In case of any additional questions, feel free to reach out to our Support team for more info 😉