How to use FMTC’s Merchant Feed

Welcome back to Tech Corner, our monthly dive into FMTC technology. This article will explore the Merchant Feed, known as the “getMerchants” endpoint.

The getMerchants Feed contains information to help you map our merchants to your internal system, as well as provide you with robust data about the merchant — the kinds of products it sells, where it ships, and more. Only merchants you have selected will be included in this feed.

A basic call to the getMerchants endpoint looks like this:
https://services.fmtc.co/v2/getMerchants?key=<YOUR_API_KEY>

You can find your API Feed Access Key in your FMTC dashboard under Feed Management > API Keys and Calls. The API key is required for all calls to this endpoint. If it’s missing, you’ll get an error message.

A call with no additional parameters returns all merchants associated with your FMTC account. Data can be returned in five formats: JSON, XML, CSV, tab-separated values, and pipe-separated values. Our system will default to the format you specify in your feed settings, or you can pass us a format parameter. We recommend JSON and XML because they have the most complete information.

In the getMerchants API call, you will notice that all our merchants have two ID numbers: the “Merchant ID” and the “Master Merchant ID.” The “Merchant ID” is unique to each program coming from a network, while the “Master Merchant ID” is unique to the merchant regardless of the network. For example, if the merchant is a part of multiple networks, it will have a unique “Merchant ID” for each network and one common “Master Merchant ID.”

There are many fields returned in a getMerchants call. Some of the commonly used fields include:

● MerchantID – A unique ID for a merchant’s program in a given network, assigned by FMTC. We use this ID throughout our web interface and in the getDeals calls. Example values: 45871, 32145

● MasterMerchantID – The master ID of the merchant, assigned by FMTC. Example values: 123, 12784

● Name – Name of the merchant. Example values: “Acme Corporation,” “Wayne Enterprises”

● AffiliateURL – An affiliate link containing your affiliate ID that is used to go to the merchant’s landing page and set the appropriate network cookie. You need to input your affiliate ID in our dashboard under Relationships > Manage Network IDs to generate these links.

● Homepage – The direct, unmonetized non-affiliate link that lands on the merchant’s homepage.

● FMTCURL – FMTC tracking URL. FMTC will determine the link you should use depending on your relationship status with the merchant. FMTC will prioritize the links in the following order: the AffiliateURL, the SubaffiliateURL, and the DirectURL. FMTC’s Merchant Sync must be enabled and set up to work correctly.

● FreshreachURL – The merchant’s homepage URL monetized by FMTC’s FreshReach® program. It will appear if both the merchant and your account are FreshReach® enabled.

● SkimlinksURL – The merchant’s homepage URL monetized by Skimlinks. This must be enabled, and the Skimlinks Publisher ID must be provided.

● Status – The merchant’s status in the FMTC database. Examples:

– Active – This merchant is actively providing FMTC deals.

– Inactive – This merchant is currently offline in the network. Once they become active in the network again, the status will become active in FMTC.

– Deleted – This merchant is completely removed from FMTC’s system and does not feed us deals.

This API can be filtered with many parameters. A full list can be found in our documentation, but these are important to know:

● sincedate: Return only merchants that have been added or modified since this date. It is in a modified ISO 8601 format, omitting the time zone. For example: https://services.fmtc.co/v2/getMerchants?key=<YOUR_KEY_HERE>&sincedate=2021-12-13T18:00:00 will return all deals modified or created after December 13, 2021 at 6:00 PM. Please note, all our timestamps are in Pacific time.

● network: Give a comma-separated list of networks. Please use the slugs from the getNetworks endpoint. For example, https://services.fmtc.co/v2/getMerchants?key=<YOUR_KEY_HERE>&network=lc,pj will return deals for all merchants you’ve selected from LinkConnector and Pepperjam.

● merchantids: Ask for only selected merchants by ID. This endpoint will only provide merchants that you have selected in your dashboard. This parameter accepts a comma-separated list. For example, https://services.fmtc.co/v2/getMerchants?key=<YOUR_KEY_HERE>&merchantids=54385,43987 gives information about merchants #54385 and #43987.

Because our database is updated frequently, you can make incremental calls on our API. In general, FMTC recommends making an incremental call every 30 minutes and a full call every couple of hours. The first time you make an incremental call, you will get all data in the getMerchants Feed. After that, every call will only give you data that has changed, which makes the calls lightweight and quick.

There are two parameters that help with an incremental call. The first is “incremental”, which requires a value of 1. This tells our system that you want to make an incremental call. The second is “nosave”, which doesn’t change the pointer for an incremental call. This is useful for testing and debugging. An example incremental call is https://services.fmtc.co/v2/getMerchants?key=<YOUR_KEY_HERE>&incremental=1 while an example debugging incremental call is https://services.fmtc.co/v2/getMerchants?key=<YOUR_KEY_HERE>&incremental=1&nosave=1.

Need more detailed information about getMerchants? Our full API documentation can be found here.

As always, our team is ready to help you! If you have any questions or concerns, send us an email at [email protected]. And if you’d like to do some more reading, here are some other Tech Corner articles from FMTC:

● getDeals Deep Dive
● Get Deals and Get Merchants
● The Product Feed
● FreshReach® Deep Dive
● Rakuten API

– Matt Bowker