...
| Table of Contents | ||||||
|---|---|---|---|---|---|---|
|
Change Log
...
2023-
...
10-
...
18
CHANGES
Updated the “Price” and “SalePrice” and how we are mapping the values from each of the networks.
UPDATES
...
UPDATES
Added a new parameter to the getMerchants call that will allow getting merchants by primary country.
Glossary
Here is the glossary of all terms that are used within this document.
Term | Abbreviation | Definition |
|---|---|---|
Cross Merchant Identifier | CMID | How FMTC matches products across networks and merchants. |
Global Trademark Identification Number | GTIN | An identifier for trade items, developed by GS1. Such identifiers are used to look up product information in a database (often by entering the number through a barcode scanner pointed at an actual product) which may belong to a retailer, manufacturer, collector, researcher, or other entity. |
Universal Product Code | UPC | The Universal Product Code is a barcode symbology that is widely used worldwide for tracking trade items in stores. UPC consists of 12 numeric digits that are uniquely assigned to each trade item. |
European Article Number | EAN | A standard describing a barcode symbology and numbering system used in global trade to identify a specific retail product type, in a specific packaging configuration, from a specific manufacturer. |
International Standard Book Number | ISBN | The International Standard Book Number is a numeric commercial book identifier which is intended to be unique. |
Manufacturer Part Number | MPN | The product identifier used to differentiate a product among other (similar) products from the same brand/manufacturer |
Stock Keeping Unit | SKU | It is a number (usually eight alphanumeric digits) that retailers assign to products to keep track of stock levels internally. |
API Endpoints
getProducts:
Description: Get products across all merchants. Can be used to get one product at a time, or multiple products.
getMerchants:
Description: Get all selected merchants and their relative product stats.
...
getProduct - http://services.fmtc.co/ProductFeed/Part3/getProducts?key=APIKEY&mode=getProduct&cmid=gtin-000022892287284
Returns one product from all merchants. One CMID product with multiple merchants, with different information depending on the merchant that has the product.
getProducts - http://services.fmtc.co/ProductFeed/Part3/getProducts?key=APIKEY&mode=getProducts
Returns multiple products based on request parameters and selected merchants. Multiple product (getProduct) objects with the different merchant information.
getMerchantProducts - http://services.fmtc.co/ProductFeed/Part3/getProducts?key=APIKEY&mode=getMerchantProducts&merchant=25831
Returns multiple products from one requested merchant, and based on request parameters. The merchant is required for this mode.
Request Parameters
Name | Value(s) | Description | Required | Default | Mode Available |
|---|---|---|---|---|---|
key | APIKEY | Your FMTC API key found in your FMTC account. | Yes | N/A, must always be provided |
|
mode | getProduct, getProducts or getMerchantProducts | The mode to run the product feed in. If not provided but a CMID value is sent, this is the mode set by internal programming. | No | getProducts |
|
cmid | String | The CMID of the product requested | Yes | N/A, must always be provided |
|
format | JSON or XML | The format the resulting product will be returned in. | No | JSON |
|
on-sale | 0 or 1 | 0 - Return products that are not on sale and on sale. 1 - Return products that are on sale. | No | 0 |
|
primary-image | 0 or 1 | 0 - Return products with or without a primary image. 1 - Return products with a primary image. | No | 0 |
|
fresh-reach | 0, 1, or 2 | For FreshReach® users (You must be signed up with FreshReach® through FMTC for this parameter to work correctly): Set the value to the following and you will get the following results: 0 - Return products with no FreshReach® links attached. 1 - Returns all products and FreshReach® links attached to products if applicable, determined by the merchant. 2 - Only products that are available through FreshReach®, determined by the merchant. | No | 0 |
|
limit | Integer | A limit to the number of products to be returned. The maximum allowed is 2,000. | No |
|
|
network | String or Array | The products will be limited to this network(s) only. It can either be a single network or an array of network names. | No | N/A - By Default, all networks will be considered. |
|
merchant | String or Array | The products will be limited to this merchant(s) only. It can be either a single merchant or an array of merchant names. You can also provide the merchant id(s) for a more precise limiting of merchants. You cannot use both ids and names. You must also select these merchants within your FMTC account. |
|
|
|
brand | String or Array | The products will be limited to this brand(s) only. It can be either a single brand or an array of brand names. | No | N/A, By Default, all brands will be considered. |
|
category | String or Array | The products will be limited to this category(s). It can be either a single category or an array of category names. | No | N/A, By Default, all categories will be considered. |
|
currency | USD, CAD, GBP, etc. | The currency that the price of the product is in. Can be any initialism related to currency. | No | N/A, By Default, all currencies will be considered. |
|
selected-merchants-only | 0 or1 | Sending in a value of 1 will limit the products to only merchants you have selected in your dashboard. | No | N/A, By Default, all merchants up to your limit will be considered. |
|
latest | 0 or1 | Limits the resulting products to only those that have been processed within a set time frame. The Default is 1. | No | 1 |
|
latest-time | String, Integer | The latest time that a product needs to exceed in order to be returned. This can be either a time string (-2 days) or a Unix time of the oldest date you are looking for. | No | “-24 hours” |
|
exclude-merchants | 0 or1 | Excludes products from the merchant(s) submited with the “merchant” parameter. These merchants do not need to be selected within your FMTC account. | No | 0 |
|
cursor | String | The cursor value provided by the API for pagination. Either provide the nextCursor for the next page or the backCursor for the previous page. | No | Empty. By Default, will start from the beginning. |
|
seed | brand, merchant, network, category, currency, 1 | The filter that you want to seed your request with. See Advanced Parameters below for more information about the seed parameter. | No | N/A, By Default, this will not be used unless specified. See Advanced Parameters below for more information about the seed parameter. |
|
stagger | 0 or1 | Tell the API that you would like the API to run your requests in smaller chunks and then sending back all the results. See Advanced Parameters below for more information. | No | N/A, By Default, this will not be used unless specified. See Advanced Parameters below for more information about the seed parameter. |
|
Implementation
How to use the getProducts endpoint.
...
Will use the getProduct mode.
Example Request
This example will get one product, across all merchants, based on CMID
Response Elements
Name | Description | Always Returned? |
|---|---|---|
product | The main element, stores of all the merchants selling the product | Yes |
merchant | An individual merchant that sells the requested product. Holds the product data relative to the merchant | No |
Merchant Elements
Name | Description |
|---|---|
CMID | An identifier that can be used across merchants. It can be one of four different identifiers, notated by a prefix. gtin- The GTIN number. |
ID | An identifier that is unique to the merchant (This is the SKU whenever possible, however, sometimes the SKU is either not unique or not provided. When needed, attributes of the product are appended to the front of the SKU to differentiate products.) |
Brand | The brand associated with the product. The brand names have been standardized to a set format. Please see the section below. If no Brand or Manufacture is given by the merchant, this is set to NO BRAND |
PrimaryCategory | The main category associated with the product. It is one of our top-level categories from FTMC. If no category is given by the merchant, this is set to NO CATEGORY |
Categories | All of the categories related to the product by the merchant. Separated by a ',' NOTE: Sometimes, the delineator is | or ~~, this is due to network inconsistencies and is being worked on. |
ProductName | The name of the product at this merchant |
MerchantName | The name of the merchant selling this version of the product |
MerchantID | The merchant's identification number. |
FeedName | The name of the feed that this product is related to. Generally the name of the Network the feed is part of. |
Available | Shows if the product is available at this merchant Possible values ● 1, the product is available ● 0, the product is not available |
Price | The price of the product at this merchant. This value can be null. This will occur when the Price is not provided by the merchant. |
SalePrice | The discounted price from the merchant. This price will be equal to or less than the price, if provided. This value can be null. This will occur when a Sale Price is not provided by the merchant. |
Currency | The currency that this merchant is selling the product in |
AffiliateUrl | The Affiliated URL of the product for this merchant. This URL will be either an affiliate URL with a place holder for an affiliate id or your affiliate id set within your FMTC account. The place holder is AFFILIATE_ID. |
Shipping | The shipping available for this product. The possible fields of this element are: ● Country ● Service ● Currency ● Price If no shipping is given by the merchant, this field is empty |
GroupID | The item_group_id from the google shopping fields if provided by the merchant. If the group id is not given by the merchant, this is set to NULL. |
GTIN | The Global Trade Item Number (UPC, EAN, etc). It will always be 15 numbers long to indicate that it needs to be processed. If it is not provided, this field is set to NULL. |
Description | The description of the product provided by the merchant |
ProductImage | A link to the image of the product provided by the merchant |
Other | A set of fields that are not standardized across products. This could include: color, size, dimensions, custom fields, etc. If this field is null or empty, this means the merchant has not put any additional values for the product. If a subfield is null or empty, that is the value provided from the merchant/network. FMTC does not change any of these values upon ingesting them into the feed. |
FreshReach | The FreshReach® URL for the merchant of the product. This will only be provided for users that provide their user key and if they are signed up for FreshReach®. Note: Not all FreshReach® merchants support DeepLinking. This link may go to the product page or the merchant's homepage. |
LastUpdate | The last time (as a Unix timestamp) the product was updated by the merchant that our system obtained. |
ProcessedTime | The last time (as a Unix timestamp) the product was confirmed by our system. |
Example Response - JSON
Here is an example of a JSON Response from the getProducts endpoint.
...
Will use the getProducts mode.
Example Request
This example will get multiple products, across all merchants, based on CMID
Response Elements
Name | Description | Always Returned? |
|---|---|---|
results | The results of the query. Contains products and cursors | Yes |
products | The products that match the query | Yes |
product | A product that matches the query. Contains merchants that sell the product | No |
merchant | The information about the product from the particular merchant. (see Merchant Elements above to learn about the elements contained in a merchant.) | No |
cursor | Contains the info about the cursor needed to the previous page or next page. | Yes |
hasBack | States if a previous page exists. (Either true or false) | Yes |
backCursor | The cursor to use in the query to the previous page | No |
hasNext | The cursor to use in the query to the next page. (Either true or false) | Yes |
nextCursor | The cursor to use in the query to the next page. | No |
Example Response JSON
| Code Block |
|---|
{
"results": {
"cursor": {
"hasBack": true,
"backCursor": "asdfjkl123",
"hasNext": true,
"nextCursor": "qwertyuio123"
},
"products": [
[
{
"CMID": "gtin-###############",
"ID": "123abcXYZ",
"MerchantId": "2902",
"FeedName": "Impact",
"Brand": "Brand",
"PrimaryCategory": "Clothing & Apparel",
"Categories": "Cat1, Cat2",
"ProductName": "Name",
"MerchantName": "Best-Buy-US",
"Available": "1",
"Price": "0.00",
"SalePrice": "0.00",
"Currency": "USD",
"AffiliateUrl": "https://example.com/client-affiliateid-test",
"Shipping": {
"Country": " US",
"Service": "Ground",
"Price": "0.00",
"Currency": "USD"
},
"GroupID": "ABC123",
"GTIN": "###############",
"Description": "Short Description",
"ProductImage": "https://example.com/is/image/",
"Other": {},
"FreshReach": "https://freshreach.co/freshreach/merchants/",
"LastUpdate": "1634251088",
"ProcessedTime": "1634251088"
}
]
]
}
} |
...
How to use the getMerchants API endpoint.
Request Parameters
Name | Value(s) | Description | Required |
|---|---|---|---|
key | APIKEY | Your FMTC API key found in your FMTC account. | Yes |
format | CSV, XML, JSON | The format the resulting product will be returned in. The default is JSON. | No |
country | String. Two-Letter Country Code | Return only merchants with a particular Primary Country. | No |
Response Elements
Name | Description | Always Returned? |
|---|---|---|
cName | The name of the merchant. | Yes |
nMerchantId | The FMTC Merchant Id. | Yes |
cNetwork | The Network that this version of the merchant belongs to. | Yes |
nProgramID | The Network’s Merchant Id. | Yes |
nProducts | The total products that this merchant has in the Product Feed as of the last update of the merchant. | Yes |
cLastUpdated | The date when the merchant was last updated by the Product Feed. | Yes |
bRelationshipExists | If an affiliate relationship exists between the user and the merchant, as determined by our Merchant Sync. | Yes |
cPrimaryCountry | The country the merchant is primarily targeting. | Yes |
Example Response JSON
| Code Block |
|---|
[
{
"cName": "Name",
"nMerchantId": "123",
"cNetwork": "NetwrokNetwork",
"nProgramID": "12345",
"nProducts": "99999",
"cLastUpdated": "yyyy-mm-dd",
"bRelationshipExists": "0",
"cPrimaryCountry": "US"
}
] |
Example Response XML
| Code Block | ||
|---|---|---|
| ||
<merchants>
<merchant>
<cName>Name</cName>
<nMerchantId>123</nMerchantId>
<cNetwork>Network</cNetwork>
<nProgramID>12345</nProgramID>
<nProducts>9999</nProducts>
<cLastUpdated>yyyy-mm-dd</cLastUpdated>
<bRelationshipExists>0</bRelationshipExists>
<cPrimaryCountry>US</cPrimaryCountry>
</merchant>
...
</merchants> |
Update Time
The database takes 15 6 hours to update from all of our networks. During this time, our database will be inaccurate however, most of the data will be correct or present from the previous day. For the most accurate data do not query the database between 5 7 PM ET/9 PM 12 AM UTC and 11 1 AM ET/3 PM 6 AM UTC.
However, some networks take less time than others, below is the average time frame for these networks to fill our database. Feel free to query products for these networks outside of the given times
Network | Update Time |
|---|---|
Awin | Start Time: |
7 PM ET/ |
12 AM UTC End Time: |
1 AM ET/ |
6 AM UTC | |
CJ Affiliate | Start Time: |
7 PM ET/ |
12 AM UTC End Time: |
1 AM ET/ |
6 AM UTC | |
Commission Factory | Start Time: |
7 PM ET/ |
12 AM UTC End Time: |
1 AM ET/ |
6 AM UTC | |
Impact | Start Time: |
7 PM ET/ |
12 AM UTC End Time: |
1 AM ET/ |
6 AM UTC | |
LinkConnector | Start Time: |
7 PM ET/ |
12 AM UTC End Time: |
1 AM ET/ |
6 AM UTC | |
PepperJam | Start Time: |
7 PM ET/ |
12 AM UTC End Time: |
1 AM ET/ |
6 AM UTC | |
Rakuten Advertising | Start Time: |
7 PM ET/ |
12 AM UTC End Time: |
1 AM ET/ |
6 AM UTC | |
ShareASale | Start Time: |
7 PM ET/ |
12 AM UTC End Time: |
1 AM ET/ |
6 AM UTC |
Advanced Parameters
The following parameters are meant for uses who are interested in using our product feed at a higher rate than the average users. Use them only if you are seeing long request times or require your requests to be completed at a faster rate due to timeout errors.
...
Errors will be returned in the format sent. If the format is not set or is not supported, the default is JSON.
Message | Description |
|---|---|
Invalid Access Key: #APIKEY | The API Key you provided was not matched to your FMTC account. Double-check that you have entered the correct id. |
Invalid Sale Filter. | The value provided for “on-sale” was invalid. The value should be either be 1 or 0. |
Invalid Primary Image Filter. | The value provided for “primary-image” was invalid. The value should be either be 1 or 0. |
Invalid FreshReach® Filter. | The value provided for “fresh-reach” was invalid. The value should be either 0, 1, or 2. |
You requested FreshReach® Products but you are not signed up for FreshReach®. | Your account does not have access to FreshReach®. Please double check your FMTC FreshReach® status. |
Invalid or Unsupported Format. | The value provided for “format” was invalid. The value should be either XML, JSON, or FILE. |
Invalid CMID #CMID | The CMID you provided is either not in a supported format or too long for our API to process. |
Invalid Limit Value. | The value provided for “limit” was invalid. The value should be a numeric value that is between 0 and 2,000 |
This functionality requires 1 merchant. | You have set the mode to getMerchantProducts but you have not provided a value for “merchant”. You need one merchant for this mode. |
This functionality allows for only 1 merchant. | You have set the mode to getMerchantProducts but you have provided multiple values for “merchant”. You can only provide one merchant for this mode. |
No matching networks found. | There are no products from the requested network in the API. |
No matching merchants found. If you are using your user key, make sure you have added the merchant to your selections. | Either there are no products for the merchant you are requesting or you have not selected the merchant within your dashboard. |
Invalid Stager Filter | The value set for stagger is invalid. Please confirm that is either 0 or 1. |
Invalid or Unsupported Seed | The value set for seed is invalid. Please confirm it is set to brand, merchant, network, category, currency, or 1. |
The parameter you set for your seed was not found. | If you have used another value than 1 for seed then you must also provide the corresponding parameter with the query. |
Invalid Exclude Merchants Filter | The value you provided for exclude-merchant was invalid. It must be 0 or 1. |
You cannot set your seed to merchants and set excluding to merchants. | You requested to excluding to merchants but are trying to use your merchant values as the seed. Try using a different seed such as brand. |
Exclude merchants is not supported for this mode. | The mode “getMerchantProducts” does not support excluding merchants. Try using getProducts. |
Invalid Latest Time String. | The value you provided for latest-time was invalid. It must be a valid date/time string or Unix timestamp. |
Invalid Latest Time String. The requested value cannot be in the future. | The value you provided for latest-time was determined to be in the future. Make sure you include the minus sign when submitting time strings for latest-time. Ex: “-2 days”. |
Frequently Asked Questions (FAQ)
...