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

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

Field

Description

access_token

type: string

Required.

allow_upsert

type: boolean

When allow_upsert is false, update requests for items not existing in the catalog will not be completed. Otherwise, new items are created.

requests.data

type: object

A JSON object containing fields and values for an item.

requests.method

type: string

CREATE, UPDATE, DELETE

requests.retailer_id

type: string

The advertiser-supplied id of an item; not the FBID.

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

name

type: string

Product's name. Max size: 100.

price

type: integer

The price multiplied by 100, for all currencies.

currency

type: string

Currency for the value specified. Use ISO 4217 for currency standards.

url

type: string

Link to merchant's site where someone can buy the item.

image_url

type: string

Link to item image used in the ad.

description

type: string

Product's description. Max size: 5000.

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

brand

type: string

Product's brand.

gtin

type: string

Global Trade Item Number can include UPC, EAN, JAN, and ISBN. Max size: 70.

manufacturer_part_number

type: string

Unique manufacturer ID for product.

Optional fields in requests.data:

additional_image_urls

type: array<string>

URLs for up to 20 different images

availability

type: string

  • in stock - Item ships immediately.

  • out of stock - No plan to restock

  • available for order - Ships in 1–2 weeks.

  • discontinued

age_group

type: string

Group of people who are the same age or a similar age. Accepted values are newborn, infant, toddler, kids, adult.

applink

type: object<>

Links to mobile apps. Array of objects per mobile platform (ios, android, ...). Every object must contain platform-specific app properties, such as name or ID.

category

type: string

Google product category (GPC) for the item. Use the category's taxonomy path or its ID number, listed here.

color

type: string

Item color.

Max size: 100.

condition

type: string

Item's condition: new, refurbished, used.

custom_label_0

type: string

Additional information about item.

Max size: 100.

custom_label_1

type: string

Additional information about item.

Max size: 100.

custom_label_2

type: string

Additional information about item.

Max size: 100.

custom_label_3

type: string

Additional information about item.

Max size: 100.

custom_label_4

type: string

Additional information about item.

Max size: 100.

gender

type: string

Gender for sizing. Values include male, female, unisex.

pattern

type: string

Pattern or graphic print on an item.

Max size: 100.

product_type

type: string

Retailer-defined category for item.

retailer_product_group_id

type: string

Advertisers can use to group products together.

sale_price

type: integer

The sale price multiplied by 100, for all currencies.

sale_price_start_date

type: string

End date and time for the sale.

Example: 2014-12-01T00:00-0300

sale_price_end_date

type: string

Start date and time for the sale.

Example: 2014-11-01T12:00-0300

shipping

type: array<object>

Shipping information. Array of objects containing shipping_country, shipping_region, shipping_service, shipping_price_value and shipping_price_currency.

size

type: string

Size of item. Example: Small or XL.

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

access_token

type: string

Required.

handle

type: string

Unique handle of a batch request.

load_ids_of_invalid_requests

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?

  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 😉

Did this answer your question?