Deals - v2 (Legacy)
Glossary
Here is the glossary of all terms that are used within this document.
Term | Abbreviation | Definition |
|---|---|---|
API Endpoints
getDeals
Description: Get normalized deals across all merchants.
Example Request: http://services.fmtc.co/v2/getDeals?key=APIKEY
getDeals
Downloading the getDeals feed will result in the fields listed below. You are welcome to use as much or as little of this information as you like when displaying the deals on your website. We encourage our subscribers to monitor the StartDate and EndDate fields as well as Status to ensure your deals are up-to-date and working for your users. Because our database is updated so frequently, we suggest you pull incremental data every 30 minutes and non-incremental data every couple of hours. A limit of 500 calls per day is strictly enforced.
Request Parameters
Name | Value(s) | Description | Required | Default |
|---|---|---|---|---|
key | APIKEY | API key for authentication, available on the API Keys & Calls page.(https://account.fmtc.co/cp/api_keys) | Yes | N/A, must always be provided |
incremental | 0, 1 | The system will always remember your last incremental download. Using this option will download only deals added, modified, or deleted since your last download. | No | 0 |
format | String XML, JSON, CSV, TAB, or PIPE | Choose the feed format you would like returned. | No | |
nosave | 0, 1 | This option is used for testing your incremental implementation. It prevents the incremental last download pointer from changing. | No | |
local | 0, 1 | This option will return only local deals from your selected merchants. Account level restrictions apply. | No | |
sincedate | Date (YYYY-MM-DDTH:M:S) | Only return items added or modified since this date. The time pasted will be treated as US Pacific Time. | No | |
activedatestart | Date (YYYY-MM-DD) | Display deals after this start after this date | No | No Limit |
activedateend | Date (YYYY-MM-DD) | Display deals that start before this date | No | No Limit |
expiredatestart | Date (YYYY-MM-DD) | Display deals that end after this date | No | No Limit |
expiredateend | Date (YYYY-MM-DD) | Display deals that end before this date | No | No Limit |
zipcode | US Zip Code (#####) | Display only local deals in this zip code. Requires local deals to be enabled on the account | No | No Limit |
merchantids | Number(s) | Return only deals from a particular merchant. If you do not specify a merchantids value deals will be returned from all of your selected merchants. | No | |
categoryids | String(s) | Return only deals from a particular category or categories. Use getCategories call for available categories. | No | |
sortby | String “merchant,” “added,” and “update” | Field to order you | No | merchantname |
dealtype | String(s) | Return only deals from of a particular type. Use getTypes call for available types. | No | |
country | String | Return only deals from merchants with a particular Primary Country. Value Format: A two-letter Country Code, or multiple Country Codes separated by commas. | No | |
network | String(s) | Return only deals from a particular network. | No | |
deleted | 0,1 | Include deleted deals, overridden by historical | No | 0 |
historical | 0, 1 | This option will return expired coupons and deals since your subscription began or up to two years worth of data. You must specify at least one merchantid with the historical parameter. | No | |
couponid | Number | Return only a single couponID. | No | |
activetoday | 0,1 | Retrieve deals that are active today (AKA they expire after today and begin before today) | No | 0 |
active | 0,1 | Display only active deals | No | 0 |
count | Number | Limit the number of deals returned. | No | 0 (Unlimited) |
view | 0,1 | Print results to the screen rather than forcing a download | No | 0 |
codes | 0,1 | Only return deals with coupon codes | No | 0 |
idplaceholder | String | Provide a placeholder value to replace with your affiliate ID | No | |
pod | Number | ID of the Pod (https://www.fmtc.co/features/pods/) consuming the feed. | No | |
v2categories | 0, 1 | This option is used to enable v2 categories on a per call basis. If V2 Categories is enabled on the Feed Settings (https://account.fmtc.co/cp/feed_settings) page this parameter is unnecessary. | No |
Implementation
Response Elements
Name | Description |
|---|---|
CouponID | Our proprietary coupon ID - especially useful in identifying deals that are delivered more than once because they have changed. |
MerchantName | Name of the merchant in the FMTC database. |
MerchantID | The ID assigned to the merchant by FMTC. |
MasterMerchantID | Each unique merchant has an ID that is shared across all the networks a merchant is active on. |
Network | The affiliate network associated with this merchant. |
ProgramID | The ID assigned to the merchant by the associated affiliate network. |
Label | A short description of the deal. |
CustomLabel | Only valid if Custom Content has been added to your FMTC Account. Short description of the deal in a custom format selected by the user. |
CustomDescription | Only valid if Custom Content has been added to your FMTC Account. Long Description of the deal in a custom format selected by the user. |
CouponCode | If the offer requires the user to enter a code, it is in this field. Any deal with a code will also contain "coupon" in the DealTypes field. |
Image | Images are included when possible and are typically delivered with product offers and grocery coupons. |
StartDate | Date the offer begins with start time (example: 2013-07-17T00:01:00-07:00). |
EndDate | Date the offer ends with end time (example: 2014-07-17T00:01:00-07:00). EndDate’s have the potential to be null from the networks, where the merchants do not fill out an expiration date. By default, FMTC will fill this value with a date of 2050-12-31T23:59:59. If you wish to not receive any expiration date, you can navigate to your Deal Feed Settings and check the following option: |
CustomEndDate | Only valid if Custom Content has been added to your FMTC Account. Customizable End Date for the offer. (example: 2015-07-17T00:01:00-07:00). |
AffiliateURL | The affiliate link containing your own affiliate ID that is used to go to the merchant's landing page and set the appropriate network cookie. It requires that you have inserted your affiliate IDs on the Manage Affiliate IDs page. NOTE: For deals marked "coupon" in the DealTypes field, this link may be required in order to activate the coupon. |
DirectURL | Unmonetized non-affiliate link that lands on the page associated with the offer. May be a homepage link or a deep link. |
FreshReachURL | Link that lands on the page associated with the offer and is monetized by FreshReach®. You must have a FreshReach® account to activate this field. |
FMTCURL | FMTC tracking URL. FMTC will determine if you should use the NetworkAffiliate URL or the Sub-Affiliate (FreshReach®/Skimlinks) URL depending on your relationship status with the merchant. |
SkimlinksURL | Link that lands on the page associated with the offer and is monetized by Skimlinks. You must have a Skimlinks account and provide us with your Skimlinks publisher ID to activate this field. |
SubAffiliateURL | Link that lands on the page associated with the offer and is monetized by a subaffiliate network. You must have an applicable account with one of the participating subaffiliate networks to activate this field. |
PixelHTML | Tracking pixel provided by the associated affiliate network when available. |
Restrictions | Any information the merchant provides regarding restrictions relating to how the coupon can or cannot be used. |
Categories | DEPRECATED. This is referencing the V1 Categories, which was replaced by CategoriesV2 field (below). |
CategoriesV2 | V2 Categories the coupon or deal can be classified by, i.e. apparel, books, shoes, toys, etc. |
DealTypes | Used to signify a offer's type, i.e. $ off, % off, category coupon,product coupon, free shipping, sale, category sale, product sale,rebate, etc. |
Status | The status should always be checked, and only "active" deals should be displayed (regardless of expiration date). The status is critical to tell if the deal is currently valid. Values may be: active - Deal is active, valid, and may be displayed; deleted - Deal was deleted - ignore other values and remove deal; suspended - The merchant was deactivated by FMTC, check your affiliation status; or expired - The deal expired normally. |
Created | The date the offer was added to FMTC's database. |
LastUpdated | When this deal was last modified by FMTC. |
SalePrice | Discounted price of a product. Not included on all product deals. |
WasPrice | Original price of a product. Not included on all product deals. |
DollarsOff | The system calculated dollar off savings when a sale product has "was" and "now" pricing. |
PercentOff | The system calculated percent off savings when a sale product has "was" and "now" pricing. |
Threshold | The minimum amount a shopper must spend in order to qualify for an offer. |
Rank/Rating | Deal Rankings are assigned to every offer. They can be used to aid in the placement of coupons and deals on your merchant pages based on offer value and potential of customer appeal. Rankings start at 1 (lowest value) and higher is better. |
Starred | This offer was flagged by an FMTC Data Engineer as being exceptionally valuable. |
Brands | List of brands related to this deal. Note: currently this field is only populated for grocery deals. |
nTieredDeal | This offer was flagged by an FMTC Data Processor as being a tiered deal. |
LinkID | This is the Network LinkID associated with this deal. |
Local Output:
Name | Description |
|---|---|
Local | Local deals have additional information included with business information, business locations and all available deal options. |
BusinessName | Name of the business offering the deal. |
BusinessUrl | Website of the business offering the deal. |
HTML | Deal HTML provided by the merchant. |
FinePrint | Terms and legal fine print for the deal. |
Location | Each business location has it's own record as described below. |
Address | Address of the business offering the deal. |
Address2 | Address of the business offering the deal. |
City | City the offer is valid in. |
State/Provence | State the offer is valid in. |
PostalCode | Postalcode the offer is valid in. |
Country | Country the offer is valid in. |
Region | Geographical location determined by the merchant to indicate what area the offer is valid in. |
Example Response - JSON
Here is an example of a JSON Response from the getDeals endpoint.
[
{
"nCouponID": 44052656,
"cMerchant": "Petco",
"nMerchantID": 40028,
"nMasterMerchantID": 657,
"cNetwork": "IR",
"cProgramID": "10290",
"cStatus": "active",
"cLabel": "Up to 50% off Your First Repeat Delivery Order of Blue Buffalo Products.",
"cImage": "",
"cCode": "",
"dtStartDate": "2021-12-03T00:00:00-08:00",
"dtEndDate": "2022-01-31T23:59:00-08:00",
"cLastUpdated": "2021-12-03T18:38:18-08:00",
"cCreated": "2021-12-03T18:38:18-08:00",
"cAffiliateURL": "https://petco.9zpg.net/c/ACTID/1189806/10290",
"cDirectURL": "https://www.petco.com/shop/en/petcostore/category/repeat-delivery-eligible-products/50-off-select-brands?cm_mmc=AFF|IMP|CCY|CCO|PM|0|rBfYNcTb52ivxnPcri3CBm|{IRPID}|{IRADID}|0|0",
"cFreshReachURL": "https://freshreach.co/click.php?c=44052656&m=40028&cid=FMTC&uid=9081&sid=0",
"cFMTCURL": "https://fmtc.co/44052656/c117cd8df8f45b133f2e26ff5cc53bfe",
"cPixelHTML": "",
"aTypes": [
"offer",
"percent",
"newcustomer"
],
"fSalePrice": "0.00",
"fWasPrice": "0.00",
"fDiscount": "0.00",
"nPercent": "50",
"fThreshold": "0.00",
"fRating": "9.500",
"bStarred": 0,
"nTieredDeal": "0",
"aBrands": [],
"aLocal": [],
"cRestrictions": "",
"cSkimlinksURL": "",
"cSubAffiliateURL": "https://freshreach.co/click.php?c=44052656&m=40028&cid=FMTC&uid=9081&sid=0",
"aCategories": [
"pets"
],
"nLinkID": 1189806
}
]Example Response - XML
Here is an example of an XML Response from the getDeals endpoint.
<?xml version="1.0" encoding="iso-8859-1" ?>
<deals>
<item>
<couponid>44052656</couponid>
<merchantname>Petco</merchantname>
<merchantid>40028</merchantid>
<mastermerchantid>657</mastermerchantid>
<network>IR</network>
<programid>10290</programid>
<label>Up to 50% off Your First Repeat Delivery Order of Blue Buffalo Products.</label>
<couponcode/>
<image/>
<startdate>2021-12-03T00:00:00-08:00</startdate>
<enddate>2022-01-31T23:59:00-08:00</enddate>
<affiliateurl>https://petco.9zpg.net/c/ACTID/1189806/10290</affiliateurl>
<skimlinksurl/>
<freshreachurl>https://freshreach.co/click.php?c=44052656&m=40028&cid=FMTC&uid=9081&sid=0</freshreachurl>
<directurl>https://www.petco.com/shop/en/petcostore/category/repeat-delivery-eligible-products/50-off-select-brands?cm_mmc=AFF|IMP|CCY|CCO|PM|0|rBfYNcTb52ivxnPcri3CBm|{IRPID}|{IRADID}|0|0</directurl>
<fmtcurl>https://fmtc.co/44052656/c117cd8df8f45b133f2e26ff5cc53bfe</fmtcurl>
<subaffiliateurl>https://freshreach.co/click.php?c=44052656&m=40028&cid=FMTC&uid=9081&sid=0</subaffiliateurl>
<pixelhtml/>
<restrictions/>
<categories>
<category>pets</category>
</categories>
<dealtypes>
<type>offer</type>
<type>percent</type>
<type>newcustomer</type>
</dealtypes>
<status>active</status>
<created>2021-12-03T18:38:18-08:00</created>
<lastupdated>2021-12-03T18:38:18-08:00</lastupdated>
<saleprice>0.00</saleprice>
<wasprice>0.00</wasprice>
<discount>0.00</discount>
<percent>50</percent>
<threshold>0.00</threshold>
<rating>9.500</rating>
<starred>0</starred>
<linkid>1189806</linkid>
<nTieredDeal>0</nTieredDeal>
</item>
</deals>Example Response - CSV
Here is an example of a CSV Response from the getDeals endpoint.
CouponID,MerchantName,MerchantID,Network,Label,CouponCode,Image,StartDate,EndDate,AffiliateURL,SkimlinksURL,DirectURL,Restrictions,Categories,DealTypes,Status,Created,LastUpdated,SalePrice,WasPrice,DollarsOff,PercentOff,Threshold,Rank,FreshReachURL,SubAffiliateURL
44052656,Petco,40028,IR,"Up to 50% off Your First Repeat Delivery Order of Blue Buffalo Products.",,,2021-12-03T00:00:00-08:00,2022-01-31T23:59:00-08:00,https://petco.9zpg.net/c/ACTID/1189806/10290,,https://www.petco.com/shop/en/petcostore/category/repeat-delivery-eligible-products/50-off-select-brands?cm_mmc=AFF|IMP|CCY|CCO|PM|0|rBfYNcTb52ivxnPcri3CBm|{IRPID}|{IRADID}|0|0,,pets,"offer,percent,newcustomer",active,2021-12-03T18:38:18-08:00,2021-12-03T18:38:18-08:00,0.00,0.00,0.00,50,0.00,9.500,https://freshreach.co/click.php?c=44052656&m=40028&cid=FMTC&uid=9081&sid=0,https://freshreach.co/click.php?c=44052656&m=40028&cid=FMTC&uid=9081&sid=0
Example Response - TAB
Here is an example of a TAB Response from the getDeals endpoint.
CouponID MerchantName MerchantID Network Label CouponCode Image StartDate EndDate AffiliateURL SkimlinksURL DirectURL Restrictions Categories DealTypes Status Created LastUpdated SalePrice WasPrice DollarsOff PercentOff Threshold Rank FreshReachURL SubAffiliateURL
44052656 Petco 40028 IR "Up to 50% off Your First Repeat Delivery Order of Blue Buffalo Products." 2021-12-03T00:00:00-08:00 2022-01-31T23:59:00-08:00 https://petco.9zpg.net/c/ACTID/1189806/10290 https://www.petco.com/shop/en/petcostore/category/repeat-delivery-eligible-products/50-off-select-brands?cm_mmc=AFF|IMP|CCY|CCO|PM|0|rBfYNcTb52ivxnPcri3CBm|{IRPID}|{IRADID}|0|0 pets offer,percent,newcustomer active 2021-12-03T18:38:18-08:00 2021-12-03T18:38:18-08:00 0.00 0.00 0.00 50 0.00 9.500 https://freshreach.co/click.php?c=44052656&m=40028&cid=FMTC&uid=9081&sid=0 https://freshreach.co/click.php?c=44052656&m=40028&cid=FMTC&uid=9081&sid=0
Example Response - PIPE
Here is an example of a PIPE Response from the getDeals endpoint.
CouponID|MerchantName|MerchantID|Network|Label|CouponCode|Image|StartDate|EndDate|AffiliateURL|SkimlinksURL|DirectURL|Restrictions|Categories|DealTypes|Status|Created|LastUpdated|SalePrice|WasPrice|DollarsOff|PercentOff|Threshold|Rank|FreshReachURL|SubAffiliateURL
44052656|Petco|40028|IR|"Up to 50% off Your First Repeat Delivery Order of Blue Buffalo Products."|||2021-12-03T00:00:00-08:00|2022-01-31T23:59:00-08:00|https://petco.9zpg.net/c/ACTID/1189806/10290||"https://www.petco.com/shop/en/petcostore/category/repeat-delivery-eligible-products/50-off-select-brands?cm_mmc=AFF|IMP|CCY|CCO|PM|0|rBfYNcTb52ivxnPcri3CBm|{IRPID}|{IRADID}|0|0"||pets|offer,percent,newcustomer|active|2021-12-03T18:38:18-08:00|2021-12-03T18:38:18-08:00|0.00|0.00|0.00|50|0.00|9.500|https://freshreach.co/click.php?c=44052656&m=40028&cid=FMTC&uid=9081&sid=0|https://freshreach.co/click.php?c=44052656&m=40028&cid=FMTC&uid=9081&sid=0