Product Feed - Upgrade Documentation

There are a few minor changes between the Beta Version of the Product Feed API and the Release Version of the Product Feed API.

Removal of Modes

We no longer allow for the setting of mode to pull in more products for individual merchants. The API endpoint should complete quickly without worrying about page size.

Beta URL	Release URL
services.fmtc.co/ProductFeed/Part3/getProducts.php?key=KEY&mode=getProducts	s3.fmtc.co/api/1/products?api_token=KEY
services.fmtc.co/ProductFeed/Part3/getProducts.php?key=KEY&merchant=23377&mode=getMerchantProducts	s3.fmtc.co/api/1/products?api_token=KEY&merchant_ids=23377
services.fmtc.co/ProductFeed/Part3/getProducts.php?key=KEY&cmid=gtin-0001234567890&mode=getProduct	s3.fmtc.co/api/1/products?api_token=KEY&cross_merchant_id=gtin-0001234567890

Removal of Advanced Parameters

We no longer allow the passing of seed or stagger values. The API endpoint should complete quickly without worrying about seeding or staggering results.

Product Count Differences

In the upgraded API system for the products endpoint, you may notice differences in the total product counts compared to the previous system. These variations are due to a combination of fixes addressing earlier system issues. Additionally, the new system should process data feeds faster than the legacy system, so products may be added or removed before they are processed in the legacy system. This means that the product counts in the new system are more accurate and reliable than those from the legacy system, providing a clearer and more up-to-date view of available products.

Brands API

We have now introduced the Brands API to allow you to pull in additional Brand information. This will enable us to give you the latest Brand information without slowing down the Products API. Before, we would provide the Brand name for you in the Brand field. Now, we provide a Brand ID in the brand_id field. Then you may look up the Brand in the Brands API and either use the Brand name related directly to that Brand or use the related Parent Brand. To help with the transition, we are also providing the element brand_object that will provide the name and the parent_id of the Brand. The parent_id is the ID of the original Brand we set for the Product (if it has changed) and can be looked up on the Brands API.

Before:

CODE

"products": [
  [
      {
          "CMID": "gtin-000000024513826",
          "ID": "BVEN-WK1-XS",
          "MerchantId": "57659",
          "FeedName": "CJ Affiliate",
          "Brand": "Bella Venice",
          "PrimaryCategory": "Uncategorized",
          "Categories": "sweaters & knits, cardigans",
          "ProductName": "Bella Venice Olivia Cardigan in Brown. - size XS (also in L, M, S)",
          "MerchantName": "REVOLVE",
          "Available": "1",
          "Price": "138.00",
          "SalePrice": "90.00",
          "Currency": "USD",
          "AffiliateUrl": "https://www.jdoqocy.com/click-AFFILIATE_ID-13237228?url=http%3A%2F%2Fwww.revolve.com%2Fcontent%2Fdeeplink%2Fwomens%2Fproduct%2FBVEN-WK1&sid=",
          "Shipping": {
              "Price": "0",
              "Service": "5-10DayAirmail",
              "Currency": "USD"
          },
          "GroupID": "",
          "GTIN": "000000024513826",
          "Description": "Bella Venice Olivia Cardigan in Brown. - size XS (also in L, M, S) Bella Venice Olivia Cardigan in Brown. - size XS (also in L, M, S) 70% polyester 25% rayon 5% spandex. Made in USA. Dry clean only. Front button loop closure. Scalloped trim. Midweight jersey fabric. BVEN-WK1. Olivia.",
          "ProductImage": "https://is4.revolveassets.com/images/p4/n/d/BVEN-WK1_V1.jpg",
          "Other": {
              "mpn": "Olivia",
              "tax": "",
              "size": "XS",
              "color": "Cheetah",
              "gender": "female",
              "age_group": "adult",
              "size_type": "regular",
              "mobile_link": "http://www.revolve.com/mobile/bella-venice-olivia-cardigan-in-cheetah/dp/BVEN-WK1/?d=F&currency=USD",
              "program_url": "http://www.REVOLVE.com",
              "size_system": "US",
              "catalog_name": "Revolve Domestic CJ",
              "last_updated": "2025-03-25T05:12:21.290-07:00",
              "product_type": "Sweaters & Knits >  Cardigans",
              "custom_label_0": "low margin",
              "custom_label_1": "sale",
              "custom_label_2": "need to push",
              "custom_label_3": "Bella Venice",
              "custom_label_4": "No",
              "impression_url": "https://www.ftjcfx.com/image-AFFILIATE_ID-13237228",
              "identifier_exists": "yes",
              "product_highlight": "[]",
              "additional_image_link": "https://is4.revolveassets.com/images/p4/n/d/BVEN-WK1_V2.jpg"
          },
          "LastUpdate": "1742911333",
          "ProcessedTime": "1742956510"
      }
  ],
]

After:

CODE

data": [
    {
        "id": 317,
        "cross_merchant_id": "gtin-000887276124391",
        "product_id": "sku7760401",
        "merchant_id": 37023,
        "merchant_object": {
          "id": 37023,
          "name": "AT&T Mobility"
        },
        "network_id": 3,
        "brand_id": 154,
        "raw_brand_name": "Samsung",
        "brand_object": {
          "id": 154,
          "name": "Samsung",
          "parent_id": 0
        },
        "primary_category_id": 99,
        "raw_categories": "electronics,communications,telephony,mobile phones",
        "label": "Samsung Gear S2 - Silver",
        "available": 1,
        "price": 99.99,
        "sale_price": 0,
        "currency_code": "USD",
        "raw_currency_string": "USD",
        "affiliate_url": "https://www.tkqlhce.com/click-ACTID-13664766?url=http%3A%2F%2Ftracking.searchmarketing.com%2Fclick.asp%3Faid%3D330002190000016701",
        "freshreach_url": "https://freshreach.co/click?m=37023&cid=FMTC&uid=9107&cpid=289",
        "image_link": "https://www.att.com/catalog/en/skus/images/samsung-gear%20s2-silver-100x160.jpg",
        "shipping_details": {
            "country": "US",
            "currency_code": "USD",
            "price": "0"
        },
        "gtin": "000887276124391",
        "description": "With elegant curves and premium finishes, the Samsung Gear S2 will turn heads. The intuitive circular face and bezel let you navigate effortlessly to get to what you need. Get more out of the moments in your day with Samsung Gear S2 and AT&T network. cell phones and smart phones on the AT&T 4G network.",
        "additional_details": {
            "program_url": "https://www.att.com/wireless/",
            "catalog_name": "AT&T Mobility Product Feed",
            "last_updated": "2025-03-18T09:10:24.081-07:00",
            "impression_url": "https://www.awltovhc.com/image-AFFILIATEID-13664766",
            "mobile_link": "https://m.att.com/shopmobile/devices/samsung/gear-s2.html#sku=sku7760401",
            "expiration_date": "2025-04-16T01:00:00.000-07:00",
            "google_product_category": "267",
            "product_type": "Electronics > Communications > Telephony > Mobile Phones",
            "identifier_exists": "yes",
            "condition": "new",
            "color": "Silver",
            "custom_label_0": "Everything Else",
            "custom_label_1": "Samsung",
            "custom_label_2": "Samsung Gear S2",
            "custom_label_3": "Catch All",
            "custom_label_4": "Catch All_spanish",
            "product_highlight": "[]"
        },
        "created_at": "2025-03-18T10:15:00+00:00",
        "updated_at": "2025-03-18T10:15:00+00:00",
        "processed_at": "2025-03-20T00:00:00+00:00"
    }
]

Child Brand IDs

We now map products to their child Brands rather than their parent Brands. This allows us to be more specific with which Brands are mapped to which Products with more accuracy. To learn about Child Brands and Parent Brands, view our Brands API documentation.

Response Formatting

The Products API has been simplified to return one product at a time rather than group identified products across multiple merchants. This has been done to speed up our API response times and lower response sizes. A simplified example is shown below.

Beta

Release

CODE

data [
    [ 
      {
        product1
        cmid: XYZ
      },
      {
        product3
        cmid: XYZ
      },
      {
        product5
        cmid: XYZ
      },
    ],
    [
      {
        product2
        cmid: 123
      },
      {
        product4
        cmid: 123
      },
      {
        product6
        cmid: 123
      }    
    ]
  ]

CODE

data [
  {
    product1
    cmid: XYZ
  },
  {
    product2
    cmid: 123
  },
  {
    product3
    cmid: XYZ
  },
  {
    product4
    cmid: 123
  },
  {
    product5
    cmid: XYZ
  },
  {
    product6
    cmid: 123
  },
]

URL Structure and Versioning

With the release of our latest version of the Product Feed API, we now offer a versioning structure to ensure data integrity in your system. To call any new version of the Product Feed API follow the following URL structure.

https://s3.fmtc.co/api/X.X.X/products

To learn more about versioning, read our API Versioning documentation.

Product Field Mappings

You can find more information on the Products API page.

Input Parameters

Name	Description	Beta Field	Version 1 Field The field has the same name, but is handled differently. See the New Fields** section.
API Key	API key for authentication.	key	api_token
Format	The format of the results.	format	format
Page Size	The number of products returned on each page	limit	page_size
Cursor	The value provided by the API for pagination.	cursor	cursor
Provide Latest	Limits results to only the latest products.	latest	latest
Latest Time	The amount of time to look back for products. A string in beta but a number of days in release.	latest-time	latest_days
On Sale Only	Limits results to only products on sale.	on-sale	only_on_sale
With Images Only	Limits results to only products with images.	primary-image	only_has_image_link
FreshReach^® Only	Limits results to products from FreshReach^® merchants only.	fresh-reach	only_freshreach
Cross Merchant ID	Returns only the products with the given CMID.	cmid	cross_merchant_id
Currency Code	Limits results to products with only the given currency code.	currency	currency_code
Network	Limits results to products from the given Network. The release version uses Network IDs	network	network_id
Merchant IDs	Limits results to products from the given Merchant(s).	merchant	merchant_ids
Categories	Limits results to products from the given Category(ies). The release version uses Category IDs.	category	category_ids
Brands	Limits results to products from the given Brand(s). The release version uses Brand IDs.	brand	brand_ids
Selected Merchants Only	Limits results to only selected merchants.	selected-merchants-only	**Deprecated
Exclude Merchants	A list of Merchants whose Products should be excluded from the results.	exclude-merchants	**Deprecated
Mode	Sets which mode to run the Product Feed algorithm in.	mode	**Deprecated
Stagger	Staggers the results to return results faster.	stagger	**Deprecated
Seed	Seeds data sets to return results faster.	seed	**Deprecated

Output Parameters

Name	Description	Beta Field	Version 1 Field
FMTC Product Identifier	Our proprietary Product ID.	Not Available	id
Cross Merchant Identifier	An ID to uniquely identify the product across Merchants	CMID	cross_merchant_id
Merchant Product Identifier	An ID from the Merchant, sent via the network.	ID	product_id
FMTC Merchant ID	The ID assigned to the merchant by FMTC.	MerchantId	merchant_id
FMTC Merchant Name	The name assigned to the merchant by FMTC.	MerchantName	merchant_object → name
FMTC Network Identifier	An FMTC assigned ID for the affiliate network associated with this merchant.	Not Available	network_id
FMTC Network Name	The name of the affiliate network associated with this merchant.	FeedName	**Deprecated
FMTC Brand Identifier	An FMTC assigned ID for the Brand associated with this product.	Not Available	brand_id
Brand Name	The name of the top-level Brand associated with this product.	Brand	**Deprecated
Brand Object	The full object of the Brand that can be found via the Brands API.	Not Available	brand_object
FMTC Primary Category ID	An FMTC assigned ID for the Primary Category of the Product.	Not Available	primary_category_id
Primary Category Name	An FMTC assigned name for the Primary Category of the Product.	PrimaryCategory	**Deprecated
Merchant Assigned Categories.	A list of categories provided by the merchant.	Categories	raw_categories
Product Label	A brief description or name of the product.	ProductName	label
Availability	If the product is available.	Available	available
Price	The base price of the Product.	Price	price
Sale Price	The price the Product is selling for.	SalePrice	sale_price
Currency Code	The Currency Code of the prices given in the Product	Not Available	currency_code
Currency String	The currency string given to us via the Merchant of the prices given in the Product.	Currency	raw_currency_string
Affiliate URL	The affiliate link containing your own affiliate ID	AffiliateUrl	affiliate_url
FreshReach® URL	Link that lands on the page associated with the offer and is monetized by FreshReach®.	FreshReach	freshreach_url
Shipping Information	An array of shipping details of a Product, if provided.	Shipping	shipping_details
Group ID	The ID of the group this Product belongs to.	GroupID	**Deprecated
Global Trade Item Number	The GTIN of the Product.	GTIN	gtin
Description	A longer description of the Product.	Description	description
Additional Details	An array of the remaining information provided by the Network and Merchant. The information in this array can vary from product metadata to custom fields, depending on the source Network.	Other	additional_details
Created Time	The time the product was first seen by our system.	Not Available	created_at
Last Updated	The time the Merchant’s Data Feed was last updated.	LastUpdate	updated_at
Last Processed	The time the product was last confirmed by our system as in the Merchant’s Data Feed.	ProcessedTime	processed_at

New Fields

Products

Output Parameters

New Field Name	Description
created_at	The first time a Product was seen by our system in the Merchant’s Data Feed.
currency_code	We attempt to translate the Currency String given by a Network into a standard ISO 4217 Currency Code.