Ads and Commerce

Generic Feed Files API

Updated: Feb 9, 2026
Copy for LLM
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.

Prerequisites

To use this API, you must have already 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:
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
Required.
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 states parameter is currently only supported for the United States.
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 two 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
Required
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
Required
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
Required
Name that will appear in the menu entry
resourceType
type: string
Optional
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

You can determine if your upload session failed by following these steps:
  1. Create an upload request and grab the feed_id field from the response.
  2. Query the feed’s upload sessions and grab the ID of the most recent one.
  3. 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"
    }
  ]
}

See also