1 Glossary
2 API Endpoints
3 getDeals
- 3.1 Request Parameters
- 3.2 Implementation
  - 3.2.1 Response Elements
  - 3.2.2 Local Output:
  - 3.2.3 Example Response - JSON
  - 3.2.4 Example Response - XML
  - 3.2.5 Example Response - CSV
  - 3.2.6 Example Response - TAB
  - 3.2.7 Example Response - PIPE

Glossary

Here is the glossary of all terms that are used within this document.

Term	Abbreviation	Definition

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

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

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: ”Leave Expiration Date Field Blank For Unknown Expiration Date Deals”
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

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&amp;m=40028&amp;cid=FMTC&amp;uid=9081&amp;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&amp;m=40028&amp;cid=FMTC&amp;uid=9081&amp;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.

Example Response - PIPE

Here is an example of a PIPE Response from the getDeals endpoint.

FMTC Knowledge Base

Deals - v2 (Legacy)