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 as Image Templates, Dynamic Slideshows, Product Insights... with Catalog Batch API, we provide an endpoint where you send requests, we enhance products and forward them to Facebook.
Implementation
The implementation is very similar to what Facebook uses—only the endpoint is different. You can build your logic using Facebook's documentation. The endpoint in ROI Hunter is:
POST
https://products-api.roihunter.com/api/v2/catalogs/{catalogFacebookId}/batchNote: Endpoint /items_batch is deprecated an new endpoint /batch should be used instead.
Before you start let us know and we send you your Facebook access token whitelisted for the ROI Hunter APP. This token must be used when sending requests to our API.
PAYLOAD
CREATE Method
Use this method to add new products to the catalog. CREATE request on products which already exists are accepted and converted to updates.
Required fields: These fields must be sent on creation of each new product
At least one of the following fields must be set in order to create valid product.
Optional fields:
You can also send your own fields in payload and use our mapping feature to map those fields into the ones accepted by FB.
Example request:
{
"access_token": "<ACCESS_TOKEN>",
"requests": [
{
"method": "CREATE",
"retailer_id": "retailer_id_1",
"data": {
"availability": "in stock",
"brand": "Nike",
"category": "t-shirts",
"description": "product description",
"image_url": "http://www.images.example.com/t-shirts/1.png",
"name": "product name",
"price": 1000,
"currency": "USD",
"shipping": [
{
"shipping_country": "US",
"shipping_region": "CA",
"shipping_service": "service",
"shipping_price_value": "10",
"shipping_price_currency": "USD"
}
],
"condition": "new",
"Url": "http://www.images.example.com/t-shirts/1.png"
"retailer_product_group_id": "product-group-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.
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 it is not enough they can increase the limit. Contact us if you need it.
- 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.
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.
Bulk upload
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 eg. apply template we have to re-upload whole product inventory which can take even a few hours based on amount of products and FB limits.
Check Batch Request Status
A successful batch update will return handle which can be used to check the status of that specific update. To do so you can use endpoint:
GET
https://products-api.roihunter.com/api/v2/catalogs/{catalogFacebookId}/check_batch_request_statusParameters
Example response:
{
"data": [
{
"handle":"Acw3O7SQ8Vq9KT5qm8H0PVQDC96",
"status":"finished",
"errors_total_count": 0,
"errors": [],
"warnings": []
}
]
}
FAQ
How long does it take to process the request?
It takes less than a second for us to forward the request to Facebook. But if you have also image templates applied on the catalog it may take a few minutes based on the count of created/updated products.
Even though we are constantly working on improvements, to ensure you will get the result response from our API, you should set the timeout to 300s which is our API global time-out.
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.
In case of any additional questions, feel free to reach out to our Support team for more info 😉