Deals - v2 (Legacy)

Glossary

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

Term

Abbreviation

Definition

Term

Abbreviation

Definition

 

 

 

 

 

 

API Endpoints

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.

 

Email: support@fmtc.co
Telephone: 512-430-4970

Contact Us | Terms of Service | Privacy Policy

Copyright © 2007 – 2022. FMTC, LLC. All Rights Reserved.