Generic Feed Files API

Updated: Feb 9, 2026

This documentation provides guidance for uploading generic feeds to your catalog, specifically for promotions, navigation menu, shipping profiles and ratings and reviews. For guidance on uploading product feeds, refer to the Feed API documentation here.

Prerequisites

To use this API, you are required to have previously set up a commerce partner integration with Meta. You'll need a commerce_partner_integration_id to perform the requests.

Endpoint

Make a POST request to:

https://graph.facebook.com/{graph_api_version}/{commercePartnerIntegrationId}/file_update

{graph_api_version}: The Graph API version (for example, "v23.0")
{commercePartnerIntegrationId}: Your commerce_partner_integration_id retrieved from GET fbe_business/fbe_installs?fbe_external_business_id=<external_business_id>

Parameters

Field	Description
`access_token` type: `string`	Required A valid Graph API access token
`feed_type` type: `string`	Required. Type of feed file. Supported values: * `PROMOTIONS` – Promotions feed (typically a CSV file). Refer to the Promotions section for details. * `PRODUCT_RATINGS_AND_REVIEWS` – Product ratings and reviews. Refer to the Ratings and Reviews section for details. * `SHIPPING_PROFILES` – Shipping profiles feed. Refer to the Shipping Profiles section for details. * `NAVIGATION_MENU` – Navigation menu feed. Refer to the Navigation Menu section for details.
`update_type` type: `string`	Required. `create` or `update`. Set to `create` to indicate a new file upload.
`update_time` type: `integer`	Optional. Unix timestamp (for example, from `strtotime('now')`).
`file` type: `file`	The file to be uploaded or url (string): the location of the product feed to fetch.

Sample cURL request

curl -X POST \
  "https://graph.facebook.com/v20.0/{commercePartnerIntegrationId}/file_update" \
  -F "access_token=YOUR_ACCESS_TOKEN" \
  -F "feed_type=SHIPPING_PROFILES" \
  -F "update_type=create" \
  -F "update_time=$(date +%s)" \
  -F "file=@/path/to/your/facebook_shipping_profiles.csv"

Replace:

YOUR_ACCESS_TOKEN with your valid token.
{commercePartnerIntegrationId} with your integration ID (returned during Meta Business Extension onboarding)
/path/to/your/facebook_shipping_profiles.csv with the actual path to your feed file.

Response

{
  "success": true,
  "feed_id": {FEED_ID}
}

Feed types

Promotions (offers)

You can enhance your ads by providing offers and promotions.

Offer types supported:

Amount off
Free shipping
Buy X Get Y
Sale

Offer application:

Automatic (No Code): Applied automatically at checkout.
Public Code: Automatically applied; visible to all customers.
Secret Code: Manually entered by the customer at checkout

Scope:

Offers can apply to the entire shop, specific collections, or selected products

Purchase requirements:

Set minimum spend thresholds, quantity requirements, or create tiered offers.

Refer to this developer guide for more information about the feed file fields required for promotions and the different offer types

As a commerce partner, you can upload an offer feed directly using the generic feed files API endpoint for your client. You or your client may also use the Offers API, but uploading feeds is centralized via the generic feed files API for partners preferring a single endpoint. Note that the main difference between the two APIs is that the Offers API doesn't require a commerce_partner_integration_id to perform the requests.

Shipping profiles

Your shipping profile feed file should contain the following fields.

Field	Description
`shipping_profile_id` type: `string`	Required An identifier that can uniquely identify the shipping profile in our database. Should be deterministically generated by the mapping logic of the platform. Equivalent to a product's retailer ID
`name` type: `string`	Required. The name of the shipping profile. Not generally buyer-visible. More useful as a reference name if the seller comes to Commerce Manager.
`shipping_zones` type: `array of objects`	Optional. List of countries and the state information that the shipping profile applies to (where products can be shipped). `[{ "country": // country code (2-Letter ISO 3166-1 alpha-2 country codes), "states": // list of state ISO 3166-2 subdivision codes (does not include the country prefix) – example, "applies_to_entire_country": // this can be provided as an alternative to a list of states }]` Note: the param "states" is only supported for the United States at the moment
`shipping_rates` type: `array of objects`	Optional. List of shipping rates. This provides different combinations of shipping times and whether free shipping is provided. Example: `[{ "name": // a reference name for the rate, "has_free_shipping": // whether free shipping can be provided, "cart_minimum_for_free_shipping": // requires currency. note: we currently don't differentiate between pre and post discounted values "min_estimated_days_to_arrival": // optional "max_estimated_days_to_arrival": // optional }]` `has_free_shipping`: This field value should be in quotes. For example: 'true', 'false' `cart_minimum_for_free_shipping`: This field should be formatted as the amount, followed by the 3-digit ISO currency code, with a space between amount and currency. For example: the string `30.99 USD` represents $30.99. If `cart_minimum_for_free_shipping` is provided, `has_free_shipping` must be set to `true`.
`applicable_products` type: `array of strings`	Optional. List of product retailer IDs (ID field in product feed) that the shipping profile applies to. Platforms should create different profiles for distinct groups of products. Value is ignored if `applies_to_all_products` is set to 'true'
`applicable_products_filter` type: `JSON-encoded string`	Optional. Similar to `applicable_products` except that this allows the list to be dynamic – meaning you do not have to call the API every time a new item is applicable for the shipping profile. The format is the same as the product set's filter rule. For example, if you want this shipping profile to apply for all products with `internal_label` "tshirt", then the filter will be: `{'internal_label': {'eq': 'tshirt'}}`
`applies_to_all_products` type: `string (enum: "true" or "false")`	Required. If this is set, Meta ignores `applicable_products` and the shipping profile will be shown for all products.
`applies_to_rest_of_world` type: `string (enum: "true" or "false")`	Required. Whether the shipping profile is a worldwide shipping.

Ratings and reviews

To check the ratings and reviews feed data spec, refer to the Product Review Feed Schema developer guide.

Reviews ingestion behavior

Currently, ratings and reviews are only supported for a few countries (the country chosen when creating a Meta shop): the United States, Taiwan, and Korea. When reviews are uploaded, they undergo two checks before being ingested and displayed on Meta surfaces.

Shop Status
Reviews are only ingested if the shop status is visible in the past 2 days.
Product information matching
Reviews uploaded are only valid if the product information on Meta matches any of the following fields:
Product name
Product URL
GTIN (Global Trade Item Number)
MPN (Manufacturer Part Number)
SKUs (to be supported in the future)
- Send us the product item retailer ID in the SKUs fields, as this new matching field will be more accurate

An example ratings and reviews feed file:

aggregator,store.name,store.id,store.storeUrls,review_id,rating,title,content,created_at,reviewer.name,reviewer.reviewerID,reviewer.isAnonymous,product.name,product.url,product.productIdentifiers.skus
universal,NoahMultisite,1352794439398752,['https://exampleshop.com/noah/shop/'],21,5,,"Very comfortable t-shirt, happy with my purchase!",2025-01-09 18:30:43,user,1,FALSE,T-Shirt,https://exampleshop.com/noah/product/t-shirt/,['woo-tshirt']
universal,NoahMultisite,1352794439398752,['https://exampleshop.com/noah/shop/'],9,5,,Great beanie! Very simple.,2025-01-03 18:30:43,user,1,FALSE,Beanie,https://exampleshop.com/noah/product/beanie/,['woo-beanie']
universal,NoahMultisite,1352794439398752,['https://exampleshop.com/noah/shop/'],2,5,,Great hoodie! Love the logo!,2025-01-02 18:30:43,user,1,FALSE,Hoodie with Logo,https://exampleshop.com/noah/product/hoodie-with-logo/,['woo-hoodie-with-logo']

This data refers to the navigation menu that will be rendered on Meta's storefront. It's the hierarchy of product sets that you have on your website, for example: best sellers -> hats, pants, and shirts. Data must follow a JSON structure, where there's a root and items inside it.

Root Structure

{
  "navigation": [
    {
      "title": Root Title",
      "Partner_menu_handle": "Test Menu Handle",
      "partner_menu_id": "1",
      "items": [items],
    }
  ]
}

Parameters

Field	Description
`title` type: string	Name that will appear in the menu entry
`partner_menu_handle` type: string	Optional Externally unique handle of the menu in partner's system (for example, main menu or footer menu)
`partner_menu_id` type: string	Optional Externally unique ID of the menu in partner's system.
`Items` type: JSON object	The items that should be nested inside this menu entry.

Item Structure

{
  "title": "Test item Title",
  "resourceType": "collection",
  "retailerID": "2",
  "items": [items],
}

Parameters

Field	Description
`title` type: string	Name that will appear in the menu entry
`resourceType` type: string	The type of resource contained by the navigation menu item ("collection", "product" or "other")
`retailerID` type: string	Optional Retailer ID for this item (ID field in product feed).
`Items` type: JSON object	Optional the items that should be nested inside this menu entry.

Example JSON file

{
   "navigation": [
      {
         "items": [
            {
               "title": "Dresses",
               "resourceType": "collection",
               "retailerID": "women_dresses_collection_retailer_id"
            },
            {
               "title": "Shirts",
               "resourceType": "collection",
               "retailerID": "women_shirts_collection_retailer_id"
            }
         ],
         "title": "Women",
         "partner_menu_handle": "Women Menu Handle",
         "partner_menu_id": "1"
      }
   ]
}

Error handling

Users can determine if their upload session failed by following these steps:

Create an upload request and grab the feed_id field from the response.
Query the feed's upload sessions and grab the ID of the most recent one.
Query the upload session's errors

Getting the corresponding upload sessions

Endpoint

GET https://graph.facebook.com/{graph_api_version}/{feed_id}/uploads

{graph_api_version}: The Graph API version (for example, "v23.0")
{feed_id}: Your uploaded feed ID that is returned in the file upload response.

Request

curl -X GET -G \
 -d 'access_token=<ACCESS_TOKEN>' \
 https://graph.facebook.com/{GENERIC_FEED_ID}/uploads

Response

{
 "data": [
   {
     "id": "{UPLOAD_SESSION_ID}}",
     "start_time": "2019-07-15T12:38:36+0000",
     "end_time": "2019-07-15T12:38:47+0000"
   },
   {
     "id": "{UPLOAD_SESSION_ID}}",
     "start_time": "2019-07-13T12:31:36+0000",
     "end_time": "2019-07-13T12:32:47+0000"
   },
   {
     "id": "{UPLOAD_SESSION_ID}}",
     "start_time": "2019-07-12T22:14:00+0000",
     "end_time": "2019-07-12T23:38:47+0000"
   }
 ]
}

Getting an upload session's error samples

Endpoint

GET https://graph.facebook.com/{graph_api_version}/{upload_session_id}/errors?error_priority={error_priority}

{graph_api_version}: The Graph API version (for example, "v23.0")
{upload_session_id}: Upload session ID that can be retrieved from GET https://graph.facebook.com/{graph_api_version}/{feed_id}/uploads.
{error_priority} (optional): Can be "high", "medium" or "low" - makes the response only include errors of the corresponding priority.

Request

curl -X GET -G \
 -d 'access_token=<ACCESS_TOKEN>' \
 https://graph.facebook.com/{UPLOAD_SESSION_ID}/errors

Response

{
  "data": [
    {
      "id": "24915424364736197",
      "summary": "Recognised values for these fields include \"true\", \"false\". Update information in",
      "samples": {
        "data": [
          {
            "row_number": 2,
            "properties": {}
          }
        ]
      },
      "description": "The applies_to_rest_of_world information provided is invalid. Review for more details",
      "severity": "fatal"
    },
    {
      "id": "24845350181726183",
      "summary": "Wrong json format",
      "samples": {
        "data": [
          {
            "row_number": 2,
            "properties": {
              "applicable_products_filter": "FALSE",
              "applies_to_all_products": "true",
              "name": "\"United States (US)\"",
              "shipping_profile_id": "1-all_products"
            }
          }
        ]
      },
      "description": "Expected a json representation of a map",
      "severity": "warning"
    },
    {
      "id": "24534708579557013",
      "summary": "Invalid values",
      "samples": {
        "data": [
          {
            "row_number": 2,
            "properties": {}
          }
        ]
      },
      "description": "Values need to be correct for them to show in your shop and ads. Go to your original data source and check the values entered for each field. Then update them in the same way you created them.",
      "severity": "warning"
    },
    {
      "id": "24000545096286279",
      "summary": "Invalid values",
      "samples": {
        "data": [
          {
            "row_number": 2,
            "properties": {}
          }
        ]
      },
      "description": "Values need to be correct for them to show in your shop and ads. Go to your original data source and check the values entered for each field. Then update them in the same way you created them.",
      "severity": "warning"
    }
  ]
}

Manage Catalog Items

Facebook Account-Level Permissioning

Instagram Partnership Ads with a New Ad Creative

Threads Ads

Targeting Expansion

Managed Partner Ads: Integration

Managed Partner Ads API Guide

Generate an Access Token for the Admin System User

Quickstart

Generic Feed Files API ​

Prerequisites ​

Endpoint ​

Parameters ​

Sample cURL request ​

Response ​

Feed types ​

Promotions (offers) ​

Offer types supported: ​

Offer application: ​

Scope: ​

Purchase requirements: ​

Shipping profiles ​

Ratings and reviews ​

Reviews ingestion behavior ​

Navigation menu ​

Root Structure ​

Parameters ​

Item Structure ​

Parameters ​

Example JSON file ​

Error handling ​

Getting the corresponding upload sessions ​

Endpoint ​

Request ​

Response ​

Getting an upload session's error samples ​

Generic Feed Files API

Prerequisites

Endpoint

Parameters

Sample cURL request

Response

Feed types

Promotions (offers)

Offer types supported:

Offer application:

Scope:

Purchase requirements:

Shipping profiles

Ratings and reviews

Reviews ingestion behavior

Navigation menu

Root Structure

Parameters

Item Structure

Parameters

Example JSON file

Error handling

Getting the corresponding upload sessions

Endpoint

Request

Response

Getting an upload session's error samples