Skip to main content
Skip table of contents

Updating To the Latest Version

This document serves as a comprehensive guide for upgrading to the newest API endpoint. It outlines step-by-step instructions, best practices, and troubleshooting tips to ensure a smooth transition. By following this guide, you will be equipped with the necessary knowledge to leverage the full potential of the updated API features, enhancing your application's performance and compatibility.


Deal Count Differences

In the upgraded API system for the deals endpoint, you may notice differences in the total deal counts compared to the previous system. These variations are due to a combination of fixes addressing earlier system errors and the introduction of new validation rules that ensure all deals are properly verified before being returned. Additionally, we've changed how deleted deals are handled; they are no longer returned by default and will only be included if the incremental or sincedate parameters are used in the API call. This means that the deal counts in the new system are more accurate and reliable than those from the legacy system, providing a clearer and more up-to-date view of available deals.


URL Structure

FMTC offers access to seven Deal API Endpoints. The URL structure and access methods for each endpoint are detailed below, along with their alignment. Two distinct URLs are utilized; the services.fmtc.co endpoint encompasses Versions 1 and 2, whereas the s3.fmtc.co endpoint contains the latest Version 3 endpoints."

Version 1

https://services.fmtc.co/ENDPOINT_NAME

Version 2

https://services.fmtc.co/v2/ENDPOINT_NAME

Version 3

https://s3.fmtc.co/api/v3/ENDPOINT_NAME

You will want to replace the ENDPOINT_NAME with the corresponding Endpoint Name in the columns listed below.

API Call

Description

Version 1 Endpoint Name

Version 2 Endpoint Name

Version 3 Endpoint Name

Deals

To ensure standardized deals from all merchants, establish clear and consistent criteria for deal offerings.

getDeals

getDeals

deals

Merchants

To gather details about all the merchants within our system, you can start by collecting information such as their names, contact details, products or services offered, business locations, and any relevant transaction data. This will help in creating a comprehensive database of merchant information.

getMerchants

getMerchants

deals-merchants

Categories

To retrieve information about the categories supported by FMTC.

getCategories

getCategories

categories

Types

To retrieve information about the deal types supported by FMTC.

getTypes

getTypes

deals-types

Logos

Use the available Merchant logos for your selected merchants with the sizes of 88x31 and 120x60.

getLogos

getLogos

logos

Network

To retrieve information about the networks supported by FMTC.

getNetworks

getNetworks

networks

Changes

Retrieve comprehensive information regarding modifications made to a specific deal.

getChanges

getChanges

deal-changes


Field Mappings

You can find more information on each of the fields on the respective API pages.

Deals - v2 (Legacy)

Deals - 3.0.0

Deals

Input Parameters

Name

Description

Version 1 Field

Version 2 Field

Version 3 Field

** The field has the same name, but is handled differently. See the New Fields section.

API Key

API key for authentication.

key

key

api_token

Incremental

Will download only deals added, modified, or deleted since your last download/call.

Not Available

incremental

**incremental

Feed Format

Choose the feed format you would like returned.

Not Available

format

format

Incremental Testing Parameter

Testing Parameter for incremental.

Not Available

nosave

Deprecated

Local Only Deals

Return only local deals from your selected merchants

local

local

local

Deals Since the Provided Date

The date from which data will be retrieved. The data returned will include all new data, modified data, deleted data, and expired data since the provided date.

sincedate

sincedate

sincedate

Deals Active Start Date

Display deals after this start after this date

activedatestart

activedatestart

activedatestart

Deals Active End Date

Display deals that start before this date

activedateend

activedateend

activedateend

Deals Expire Start Date

Display deals that end after this date

expiredatestart

expiredatestart

expiredatestart

Deals Expire End Date

Display deals that end before this date

expiredateend

expiredateend

expiredateend

Local Deals Zip Code

Display only local deals in this zip code.

zipcode

zipcode

zipcode

Merchant Deals

Return only deals from a particular merchant.

merchantids

merchantids

merchantids

Category Deals

Return only deals from a particular category or categories.

categoryids

categoryids

categoryids

Field Sorting

Field to order the results by.

sortorder

sortby

sortby

Deal Types

Return only deals from of a particular type.

dealtype

dealtype

**dealtypeid

Deal Countries

Return only deals from merchants with a particular Primary Country.

country

country

country

Network Deals

Return only deals from a particular network.

network

network

**networkid

Deleted Deals

Include deleted deals

deleted

deleted

Deprecated

Historical Deals

This option will return expired coupons and deals since your subscription began or up to two years worth of data.

Not Available

historical

historical

Single Deal

Return only a single couponID.

couponid

couponid

couponid

Active Deals for Today

Retrieve deals that are active today (AKA they expire after today and begin before today)

activetoday

activetoday

activetoday

Active Deals

Display only active deals.

active

active

active

Deal Limit

Limit the number of deals returned.

count

count

Deprecated

Print

Print results to the screen rather than forcing a download

view

view

Deprecated

Coupon Code Deals

Limit to only deals with coupon codes

codes

codes

codesonly

Apply Different Affiliate ID

Provide a placeholder value to replace with your affiliate ID

idplaceholder

idplaceholder

Deprecated

Deal Pods

ID of the Pod.

Not Available

pod

Deprecated

Enable New Categories

This option is used to enable v2 categories on a per call basis.

Not Available

v2categories

Deprecated

Output Parameters

Name

Description

Version 1 Field

Version 2 Field

Version 3 Field

Deal Identifier

Our proprietary Deal ID.

CouponID

CouponID

id

Merchant Name

Name of the merchant in the FMTC database.

MerchantName

MerchantName

merchant_name

Merchant Identifier

The ID assigned to the merchant by FMTC.

MerchantID

MerchantID

merchant_id

Master Merchant Identifier

Each unique merchant has an ID that is shared across all the networks a merchant is active on.

Not Available

MasterMerchantID

master_merchant_id

Network Identifier

An FMTC assigned ID for the affiliate network associated with this merchant.

Network

Network

network_id

Program Identifier

A Network assigned ID for the merchant that their program is on.

Not Available

ProgramID

program_id

Label

Describes the coupon value or description of the deal.

Label

Label

label

Custom Content Label

Short description of the deal in a custom format selected by the user.

Not Available

CustomLabel

Future Update

Custom Content Description

Long Description of the deal in a custom format selected by the user.

Not Available

CustomDescription

Future Update

Deal Code

If the offer requires the user to enter a code, it is in this field.

CouponCode

CouponCode

code

Image URL

Images are included when possible and are typically delivered with product offers and grocery coupons.

Image

Image

image

Deal Start Date

Date the offer begins with start time.

StartDate

StartDate

start_date

Deal End Date

Date the offer ends with end time.

EndDate

EndDate

end_date

Custom Content End Date

Custom End Date selected by the user.

CustomEndDate

Future Update

Affiliate URL

The affiliate link containing your own affiliate ID

Link

AffiliateURL

affiliate_url

Direct URL

Unmonetized non-affiliate link that lands on the page associated with the offer.

DierctLink

DirectURL

direct_link

FreshReach® URL

Link that lands on the page associated with the offer and is monetized by FreshReach®.

Not Available

FreshReachURL

freshreach_url

FMTC URL

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. This will be a shortened URL.

Not Available

FMTCURL

fmtc_url

Skimlinks URL

Link that lands on the page associated with the offer and is monetized by Skimlinks.

Not Available

SkimlinksURL

skimlinks_url

SubAffiliate URL

Link that lands on the page associated with the offer and is monetized by a subaffiliate network.

Not Available

SubAffiliateURL

subaffiliate_url

Tracking Pixels

Tracking pixel provided by the associated affiliate network when available.

Not Available

PixelHTML

pixel_html

Deal Restrictions

Any information the merchant provides regarding restrictions relating to how the coupon can or cannot be used.

Restrictions

Restrictions

restrictions

Original FMTC Categories

Categories the coupon or deal can be classified by, i.e. apparel, books, shoes, toys, etc.

Categories

Categories

Deprecated

Updated FMTC Categories

Categories the coupon or deal can be classified by, i.e. apparel, books, shoes, toys, etc.

Not Avialable

CategoriesV2

categories

FMTC Deal Types

Used to signify a offer's type, i.e. $ off, % off, category coupon, product coupon, free shipping, sale, category sale, product sale, rebate, etc.

DealTypes

DealTypes

types

Deal Status

The status should always be checked, and only "active" deals should be displayed.

Status

Status

status

Deal Create Date

The date the offer was added to FMTC's database.

Created

Created

created

Deal Update Date

When this deal was last modified by FMTC.

LastUpdated

LastUpdated

last_update

Deal Sale Price

Discounted price of a product. Not included on all product deals.

Not Available

SalePrice

sale_price

Deal Was Price

Original price of a product. Not included on all product deals.

Not Available

WasPrice

was_price

Deal Dollar Off Amount

The system calculated dollar off savings when a sale product has "was" and "now" pricing.

Not Available

DollarsOff

discount

Deal Percent Off Amount

The system calculated percent off savings when a sale product has "was" and "now" pricing.

Not Available

PercentOff

percent

Deal Threshold Amount

The minimum amount a shopper must spend in order to qualify for an offer.

Not Available

Threshold

threshold

FMTC Deal Rating

Deal Rankings are assigned to every offer.

Not Available

Rank/Rating

rating

Star Ranking

This offer was flagged by an FMTC Data Engineer as being exceptionally valuable.

Not Available

Starred

Deprecdted

Brand Name

List of brands related to this deal.

Not Available

Brands

brands

Tiered Deal

This offer was flagged by an FMTC Data Processor as being a tiered deal.

Not Available

nTieredDeal

tiered_deal

Network Link ID

This is the Network LinkID associated with this deal.

Not Available

LinkID

link_id

Local Deal

Local Information about the deal, including address and zip code.

Country

local

locations

Merchants

You can find more information on each of the fields on the respective API pages.

Merchants - v2 (Legacy)

Merchants - 3.0.0

Input Parameters

Name

Description

Version 1 Field

Version 2 Field

Version 3 Field

** The field has the same name, but is handled differently. See the New Fields section.

API Key

API key for authentication.

key

key

api_token

Incremental

Will download only deals added, modified, or deleted since your last download/call.

incremental

incremental

incremental

Feed Format

Choose the feed format you would like returned.

format

format

format

Merchant Deals

Return only specific merchants .

merchantids

merchantids

merchantids

Merchant Countries

Return only merchants with a particular Primary Country.

Not Available

country

country

Premium Merchants

Return selected premium merchants.

Not Available

preferred

premium

All Merchants

Return all merchants

all

all

Deprecated

Print

Print results to the screen rather than forcing a download

view

view

Deprecated

Deactivated Merchants

Include deactivated merchants

Not Available

deactivated

Deprecated

Apply Different Affiliate ID

Provide a placeholder value to replace with your affiliate ID

idplaceholder

idplaceholder

Deprecated

Print Format

Same as view, except for JSON and CSV

Not Available

plain-text

Deprecated

Incremental Testing Parameter

Testing Parameter for incremental.

nosave

nosave

Deprecated

Network Merchants

Return only deals from a particular network.

network

network

**networkid

Merchant Network ID

Return only merchants from a particular network.

Not Available

programid

programid

Deals Since the Provided Date

The date from which data will be retrieved. The data returned will include all new data, modified data, deleted data, and expired data since the provided date.

Not Available

sincedate

sincedate

Deleted Merchants

Include deleted merchants

Not Available

deleted

Deprecated

Version 2 Categories

This option is used to enable v2 categories on a per call basis.

Not Available

v2categories

Deprecated

Output Parameters

Name

Description

Version 1 Field

Version 2 Field

Version 3 Field

Merchant Identifier

The ID assigned to the merchant by FMTC.

MerchantID

MerchantID

id

Master Merchant Identifier

Each unique merchant has an ID that is shared across all the networks a merchant is active on.

Not Available

MasterMerchantID

master_merchant_id

Original Skimlinks ID

This field contains one associated SkimlinksIDs.

Not Available

SkimlinksID

Deprecated

Updated Skimlinks IDs

This field contains all of the associated SkimlinksIDs.

Not Available

SkimlinksIDs

skimlinks_id

Merchant Name

Name of the merchant in the FMTC database.

MerchantName

MerchantName

name

Network Name

Name of the network in the FMTC database.

Network

Network

Deprecated

Network Identifier

An FMTC assigned ID for the affiliate network associated with this merchant.

NetworkID

NetworkID

network_id

Program Identifier

A Network assigned ID for the merchant that their program is on.

Not Available

ProgramID

program_id

Network Information

Details on locating the merchant on the network.

NetworkNotes

NetworkNotes

network_notes

Multi-Network Merchant

Signifies if the merchant is available on more than one network.

DualMerchant

DualMerchant

Deprecated

Multi-Network Merchant

Signifies if the merchant is available on more than one network.

RelatedMerchants

RelatedMerchants

dual_merchants

Affiliate URL

The affiliate link containing your own affiliate ID

Link

AffiliateLink

affiliate_url

Skimlinks URL

Link that lands on the page associated with the offer and is monetized by Skimlinks.

Not Available

SkimlinksURL

skimlinks_url

FreshReach® URL

Link that lands on the page associated with the offer and is monetized by FreshReach®.

Not Available

FreshReachURL

freshreach_url

FMTC URL

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. This will be a shortened URL.

Not Available

FMTCURL

fmtc_url

Merchant Homepage

The merchant's homepage URL.

homepage

homepageurl

homepage

Merchant Status

The status of a merchant in the FMTC database.

Status

Status

status

Merchant Selection Status

Indicates if a merchant is among your selected merchants.

Not Available

SelectedStatus

selected_status

Network Relationship

Indicates if you are approved at the network for this specific merchant.

Not Available

RelationshipStatus

relationship_status

Merchant Primary Country

The country the merchant is primarily targeting.

PrimaryCountry

PrimaryCountry

primary_country

Merchant Ship-To Countries

The country or countries the merchant will ship to.

Not Available

ShiptoCountries

shiptocountries

Merchant APOFPO Availability

Indicates if a merchant ships to APO/FPO (overseas military) addresses.

APOFPO

APOFPO

ap_fpo_shipping

Merchant Primary Category

Primary category of merchandise the merchant sells.

Not Available

PrimaryCategory

primary_category

Merchant Secondary Categories

Subcategories of merchandise the merchant sells.

Not Available

Subcategories

Deprecated

Updated FMTC Categories

Categories the coupon or deal can be classified by, i.e. apparel, books, shoes, toys, etc.

Categories

CategoriesV2

categories

Merchant Payment Availability

Indicates if a merchant accepts special payment types like Paypal.

Not Available

SpecialPaymentOptions

Deprecated

Merchant Mobile Certification

Indicates the affiliate cookie will track on a mobile device.

Not Available

MobileCertified

mobile_certified

Merchant Logos

Contains information about the logo files that are returned in the getLogos call.

Not Available

Logos

Deprecated

Merchant Custom Logos

Custom logo that was added by you (if any).

Not Available

CustomLogo

Deprecated

Merchant Custom Descriptions

Custom description that was added by you (if any).

Not Available

CustomDescription

Deprecated

FMTC Addition

Indicates the date the merchant was added to FMTC's database.

Not Available

Added

created

FMTC Last Update

Indicates the last time a merchant's information was changed.

LastUpdated

LastUpdated

last_updated

Name

Merchant Representative Name (when available)

Not Available

cRepName

rep_name

Email

Merchant Representative Email (when available)

Not Available

cRepEmail

rep_email

Phone Number

Merchant Representative Phone (when available)

Not Available

cRepPhone

rep_phone

Categories

You can find more information on each of the fields on the respective API pages.

Categories - v2 (Legacy)

Categories - 3.0.0

Input Parameters

Name

Description

Version 1 Field

Version 2 Field

Version 3 Field

API Key

API key for authentication.

key

key

api_token

Feed Format

Choose the feed format you would like returned.

format

format

format

New Categories

Whether to return the v1 Categories or v2.

Not Available

v2

Deprecated

Print

Print results to the screen rather than forcing a download

Not Available

view

Deprecated

Output Parameters

Name

Description

Version 1 Field

Version 2 Field

Version 3 Field

Category URL

The unique slug assigned to the network.

FilterValue

Slug

slug

Category Name

The human readable name of the network

CategoryName

Name

name

Category Parent

The numerical ID of the parent category.

Parent

ParentID

parent_id

FMTC Category ID

The unique numerical ID assigned to the category

Not Available

CategoryID

id

Restricted Category

Flag value indicating if the category is a restricted-content category.

Not Available

Restricted

restricted

Types

You can find more information on each of the fields on the respective API pages.

Types - v2 (Legacy)

Types - 3.0.0

Input Parameters

Name

Description

Version 1 Field

Version 2 Field

Version 3 Field

API Key

API key for authentication.

key

key

api_token

Feed Format

Choose the feed format you would like returned.

format

format

format

New Deal Types

Whether to return the v1 Deal Types or v2.

Not Avialable

v2

Deprecated

Output Parameters

Name

Description

Version 1 Field

Version 2 Field

Version 3 Field

Deal Type URL

The unique slug assigned to the network.

FilterValue

Slug

slug

Deal Type Name

The human readable name of the network

CategoryName

Name

name

Logos

You can find more information on each of the fields on the respective API pages.

Logos - v2 (Legacy)

Input Parameters

Name

Description

Version 1 Field

Version 2 Field

Version 3 Field

API Key

API key for authentication.

key

key

api_token

Incremental

Will download only deals added, modified, or deleted since your last download/call.

incremental

incremental

Deprecated

Logo Sizes

Specific Logo sizes for each of the merchants

size

size

size

Merchant Deals

Return only deals from a particular merchant.

merchantids

merchantids

merchantids

Deals Since the Provided Date

The date from which data will be retrieved. The data returned will include all new data, modified data, deleted data, and expired data since the provided date.

Not Available

sincedate

sincedate

Full Logos

Return all logos of selected merchants

complete

complete

complete

Output Parameters

The response will be a zip file containing all of the logos. The logo files will have the filename with the FMTC Merchant ID.

Network

You can find more information on each of the fields on the respective API pages.

Network - v2 (Legacy)

Networks - 3.0.0

Input Parameters

Name

Description

Version 1 Field

Version 2 Field

Version 3 Field

API Key

API key for authentication.

key

key

api_token

Incremental

Will download only deals added, modified, or deleted since your last download/call.

incremental

incremental

Deprecated

Feed Format

Choose the feed format you would like returned.

format

format

format

Output Parameters

Name

Description

Version 1 Field

Version 2 Field

Version 3 Field

Network URL

The unique slug assigned to the network.

ID

Slug

slug

Network Name

The human readable name of the network

NetworkName

Name

name

Network Countries

The two-letter country codes for the countries that the network supports.

Not Available

Countries

countries

Changes

You can find more information on each of the fields on the respective API pages.

Changes - v2 (Legacy)

Input Parameters

Name

Description

Version 1 Field

Version 2 Field

Version 3 Field

API Key

API key for authentication.

key

key

api_token

Incremental

Will download only deals added, modified, or deleted since your last download/call.

Not Available

incremental

Deprecated

Feed Format

Choose the feed format you would like returned.

Not Avialable

format

format

Single Deal

Return only a single couponID.

coupondid

couponid

dealId

Output Parameters

Name

Description

Version 1 Field

Version 2 Field

Version 3 Field

Deal Change ID

The FMTC unique ID assigned to the change.

ChangeID

ChangeID

id

FMTC Deal ID

The FMTC unique ID assigned to the deal.

CouponID

CouponID

deal_id

Change Timestamp

Date this particular deal has changed

Date

Date

date

Deal Type Change

The particular value that has been changed.

Type

Type

type

New Deal Value

The most recent updated value.

NewValue

NewValue

new_value

Old Deal Value

The previous value before the update.

OldValue

OldValue

old_value


New Fields

Deals

Input Parameters

If you are using the network parameter, you will not want to use the networkid. The Networks are now done by ID instead of name. You can get the ID for the network through the Networks API call.

Output Parameters

New Field Name

Description

coupon_code_on_page

Automated FMTC has found the coupon code on the deal’s landing page.

code_verified_at

The date that the code was verified by FMTC.

cascading_full_url

This will direct to the same location as the FMTC URL. The difference is that this URL is not shortened.

link_verified_at

The date that the link was verified by FMTC.

meta

The information about the current endpoint call.

Categories

Input Parameters

slug parameter has been introduced to return only the corresponding categories instead of all the categories.

Types

Input Parameters

slug parameter has been introduced to return only the corresponding deal types instead of all the categories.

Output Parameters

id has been added for each Deal Type. You can use these as references in other API calls so you do not need to rely on the name.

Networks

Input Parameters

networkidhas been added for each network. You can use these as references in other API calls so you do not need the rely on the name.

Output Parameters

id for the network to be used across other FMTC API calls.


Pagination

Offset pagination is a method used in software development to manage and navigate through large datasets efficiently. It works by dividing the data into discrete chunks or 'pages', which can be loaded separately. This technique allows users to view a subset of results at a time, reducing the load on the database and improving response times. The process involves two key parameters: 'page_size' which specifies the number of records to return in a single page, and 'page' which indicates the starting point from which to return records. By adjusting these parameters, users can navigate through data in a controlled and scalable manner.

CODE
"links": {
    "first": URL + "&page=1",
    "last": URL + "&page=16",
    "prev": null,
    "next": URL + "&page=2"
    },
    "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 16,
    "path": "https://s3.fmtc.co/api/v3/deals",
    "per_page": 100,
    "to": 100,
    "total": 1518
    },

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.