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.
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. All implementation details are described in this article.
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
Field | Description |
type: string | Required. |
type: boolean | When |
type: object | A JSON object containing fields and values for an item. |
type: string | CREATE, UPDATE, DELETE |
type: string | The advertiser-supplied |
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
:
Field | Description |
type: string | Product's name. Max size: 100. |
type: integer | The price multiplied by 100, for all currencies. |
type: string | Currency for the value specified. Use ISO 4217 for currency standards. |
type: string | Link to merchant's site where someone can buy the item. |
type: string | Link to item image used in the ad. |
type: string | Product's description. Max size: 5000. |
At least one of the following fields must be set in order to create valid product.
type: string | Product's brand. |
type: string | Global Trade Item Number can include |
type: string | Unique manufacturer ID for product. |
Optional fields in requests.data
:
type: array<string> | URLs for up to 20 different images |
type: string |
|
type: string | Group of people who are the same age or a similar age. Accepted values are |
type: object<> | Links to mobile apps. Array of objects per mobile platform |
type: string | Google product category (GPC) for the item. Use the category's taxonomy path or its ID number, listed here. |
type: string | Item color. Max size: 100. |
type: string | Item's condition: |
type: string | Additional information about item. Max size: 100. |
type: string | Additional information about item. Max size: 100. |
type: string | Additional information about item. Max size: 100. |
type: string | Additional information about item. Max size: 100. |
type: string | Additional information about item. Max size: 100. |
type: string | Gender for sizing. Values include |
type: string | Pattern or graphic print on an item. Max size: 100. |
type: string | Retailer-defined category for item. |
type: string | Advertisers can use to group products together. |
type: integer | The sale price multiplied by 100, for all currencies. |
type: string | End date and time for the sale. Example: |
type: string | Start date and time for the sale. Example: |
type: array<object> | Shipping information. Array of objects containing |
type: string | Size of item. Example: |
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
Parameter | Description |
type: string | Required. |
type: string | Unique handle of a batch request. |
type: boolean | When true the returned status will contain a list of item ids for which the requests failed |
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?
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?
- 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.
- Check the latest product data that you have sent to us - are they correct? Send the product again with the correct data.
- 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 😉