FMTC Knowledge Base
FMTC Knowledge Base
Breadcrumbs

Deals - 4.2.0

API Endpoints

Deals API

Using the Deals endpoint 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 start_date and end_date 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. Default format is JSON unless overridden by the format URL parameter or your account’s Deal Feed Settings.

What's New?

  • Major performance improvement for incremental polling. Calls using the sincedate parameter now return significantly faster. Recommended for any integration that polls for deal changes on a regular cadence.

Request Parameters

Name

Value(s)

Description

Required

Default

api_token

APIKEY

API key for authentication, available on the API Keys & Calls page

Yes

N/A, must always be provided

format

String XML, JSON, CSV, TAB, or PIPE

Choose the feed format you would like returned.

No

JSON

codesonly

0, 1

Limit to only deals with coupon codes.

No

0

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

null

categoryids

Number(s)

Return only deals from a particular category or categories. Use the Categories endpoint for available categories.

No

null

dealtypeids

Number

Return only deals of a particular type. Use the Types endpoint for available types.

No

null

advanced_deal_types

Number(s)

Return only deals of a particular advanced deal type. Comma-separated integers or array.

No

null

country

String

Return only deals from merchants with a particular Primary Country. A two-letter Country Code, or multiple Country Codes separated by commas.

No

null

networkid

Number

Return only deals from a particular network. Use the Networks endpoint for available networks.

No

null

local

0, 1

Return only local deals from your selected merchants. Account level restrictions apply.

No

0

zipcode

US Zip Code (#####)

Display only local deals in this zip code. Requires local deals to be enabled on the account.

No

null

active

0, 1

Display only active deals. 0 - both expired and currently active deals (excluding deleted). 1 - only currently active deals.

No

1

activetoday

0, 1

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

No

0

sincedate

Date (YYYY-MM-DD)

The date from which data will be retrieved. Returns all new, modified, deleted, and expired data since the provided date. NOTE: Will search for any deals that existed in the API before the date and return them, marked deleted to indicate they are no longer part of the active deal feed.

No

null

incremental

Number

The amount of time from the previous call. For example, setting this to 60 returns all changes in the past 60 minutes.

No

0

activedatestart

Date (YYYY-MM-DD)

Display deals that start after this date.

No

null

activedateend

Date (YYYY-MM-DD)

Display deals that start before this date.

No

null

expiredatestart

Date (YYYY-MM-DD)

Display deals that end after this date.

No

null

expiredateend

Date (YYYY-MM-DD)

Display deals that end before this date.

No

null

historical

0, 1

Return active, expired and deleted coupons and deals. Grabs from subscription start or up to two years of data. Requires at least one merchantid.

No

0

couponid

Number

Return only a single couponID.

No

null

sortby

String "merchant", "added", or "update"

Field to order the results by.

No

merchant

public_only

0, 1

Return only publicly available deals.

No

0

exclusive_only

0, 1

Return only exclusive deals available to the subscriber.

No

0

page_size

Number 1 – 150,000

Size of each page for the results of this call.

No

100


Implementation

Response Elements

Name

Description

id

Our proprietary coupon ID — useful in identifying deals delivered more than once because they have changed.

merchant_name

Name of the merchant in the FMTC database.

merchant_id

The ID assigned to the merchant by FMTC.

master_merchant_id

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

network_id

An FMTC assigned ID for the affiliate network associated with this merchant. Use the Networks endpoint for available networks.

program_id

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

label

Describes the coupon value or description of the deal.

code

If the offer requires the user to enter a code, it is in this field. Any deal with a code will also contain the Deal Type ID for "coupon" in the types field.

coupon_code_on_page

Automated FMTC has found the coupon code on the deal's landing page. NOTE: Potential for false positives if the code is a generic term used elsewhere on the page.

code_verified_at

The date the code was verified by FMTC, updated each time it is verified (example: 2014-07-17T00:01:00-07:00). NOTE: UTC time.

image

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

start_date

Date the offer begins with start time. NOTE: UTC time.

end_date

Date the offer ends with end time. NOTE: UTC time.

affiliate_url

The affiliate link containing your own affiliate ID, used to set the appropriate network cookie. Requires affiliate IDs to be inserted on the Manage Affiliate IDs page.

skimlinks_url

Link monetized by Skimlinks. Requires a Skimlinks account and publisher ID.

sovrn_url

Link monetized by Sovrn. Requires a Sovrn account and API key.

freshreach_url

Link monetized by FreshReach®. Requires a FreshReach® account.

direct_link

Unmonetized non-affiliate link landing on the page associated with the offer. May be a homepage or deep link.

fmtc_url

FMTC tracking URL — shortened. FMTC determines whether to use the Network Affiliate URL or the Sub-Affiliate URL depending on your merchant relationship.

cascading_full_url

Same destination as the FMTC URL but not shortened.

subaffiliate_url

Link monetized by a subaffiliate network. Requires an applicable account with one of the participating subaffiliate networks.

link_verified_at

The date the link was verified by FMTC, updated each time it is verified. NOTE: UTC time.

pixel_html

Tracking pixel provided by the associated affiliate network when available.

restrictions

Any information the merchant provides regarding restrictions.

categories

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

types

Used to signify a offer's type ($ off, % off, category coupon, product coupon, free shipping, sale, etc.). Array of IDs looked up via the Types endpoint.

status

The status should always be checked. Only "active" deals should be displayed (regardless of expiration date). Values: active, deleted, suspended, expired.

created

The date the offer was added to FMTC's database. NOTE: UTC time.

last_updated

When this deal was last modified by FMTC. NOTE: UTC time.

sale_price

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

was_price

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

discount

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

percent

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

threshold

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

rating

Deal Ranking assigned to every offer (1 = lowest).

brands

List of brands related to this deal. Currently populated for grocery deals only.

local

0 or 1 — whether the deal is a local deal.

tiered_deal

Flagged by an FMTC Data Processor as a tiered deal.

link_id

The Network LinkID associated with this deal.

locations

Array of local deal information (name, street_address, extended_address, locality, region, postal_code, country, latitude, longitude, link).

metadata

AI-derived information from the label field (currency, value, max_value, is_precent, old_price, new_price, price_trigger, coupon_code).

deal_types

Object containing deal type information. See Types endpoint for more.

exclusive

0 — publicly available; 1 — exclusive automated; 2 — exclusive manual.

links

Pagination links (first, last, prev, next). JSON/XML inline; CSV/TAB/PIPE in HTML link header.

meta

Information about the current endpoint call.

Example Response - JSON

Here is an example of a JSON Response from the Deals endpoint.

{
    "data": [
        {
            "id": 92,
            "merchant_name": "AreYouGame.com",
            "merchant_id": 13,
            "master_merchant_id": 13,
            "network_id": 3,
            "program_id": "247913",
            "status": "active",
            "label": "test",
            "image": null,
            "code": null,
            "start_date": "2022-05-06T20:50:11.000000Z",
            "end_date": "2072-05-08T23:59:59.000000Z",
            "last_updated": "2022-05-06T20:50:11.000000Z",
            "created": "2022-05-06T20:50:11.000000Z",
            "affiliate_url": "test.com",
            "direct_link": null,
            "freshreach_url": "https://freshreach.co/click.php?c=92&m=13&cid=FMTC&uid=9107&sid=4mtc",
            "skimlinks_url": "https://go.redirectingat.com/?id=1&xs=1&xcust=4mtc&url=https%3A%2F%2Fwww.areyougame.com%2F",
            "subaffiliate_url": "https://freshreach.co/click.php?c=92&m=13&cid=FMTC&uid=9107&sid=4mtc",
            "fmtc_url": "https://fmtc.co/92/",
            "cascading_full_url": "https://www.areyougame.com/",
            "link_verified_at": "2022-05-06T20:50:11.000000Z",
            "pixel_html": null,
            "types": [],
            "sale_price": "0.00",
            "was_price": "0.00",
            "discount": "0.00",
            "percent": 0,
            "threshold": null,
            "rating": null,
            "tiered_deal": null,
            "brands": null,
            "local": null,
            "restrictions": null,
            "categories": [],
            "link_id": "",
            "deal_types": {
                "shipping-type": [3, 4]
            },
            "exclusive": 0
        }
    ],
    "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/4.2.0/deals",
        "per_page": 100,
        "to": 100,
        "total": 1518
    }
}

Example Response - XML

Here is an example of an XML Response from the Deals endpoint.

<results>
    <data>
        <deal>
            <id>92</id>
            <merchant_name>AreYouGame.com</merchant_name>
            <merchant_id>13</merchant_id>
            <master_merchant_id>13</master_merchant_id>
            <network_id>3</network_id>
            <program_id>247913</program_id>
            <status>active</status>
            <label>test</label>
            <image/>
            <code/>
            <start_date/>
            <end_date>05/08/2072 23:59:59</end_date>
            <last_updated>2022-05-06 20:50:11</last_updated>
            <created>2022-05-06 20:50:11</created>
            <affiliate_url>test.com</affiliate_url>
            <direct_link/>
            <freshreach_url>https://freshreach.co/click.php?c=92&m=13&cid=FMTC&uid=9107&sid=4mtc</freshreach_url>
            <skimlinks_url>https://go.redirectingat.com/?id=1&xs=1&xcust=4mtc&url=https%3A%2F%2Fwww.areyougame.com%2F</skimlinks_url>
            <subaffiliate_url>https://freshreach.co/click.php?c=92&m=13&cid=FMTC&uid=9107&sid=4mtc</subaffiliate_url>
            <fmtc_url>https://fmtc.co/92/</fmtc_url>
            <cascading_full_url>https://www.areyougame.com/</cascading_full_url>
            <pixel_html/>
            <types/>
            <sale_price>0.00</sale_price>
            <was_price>0.00</was_price>
            <discount>0.00</discount>
            <percent>0</percent>
            <threshold/>
            <rating/>
            <tiered_deal/>
            <brands/>
            <local/>
            <restrictions/>
            <categories/>
            <link_id/>
            <deal_types>
                <shipping-type>
                    <shipping-type>3</shipping-type>
                    <shipping-type>4</shipping-type>
                </shipping-type>
            </deal_types>
            <exclusive>0</exclusive>
        </deal>
    </data>
    <links>
        <first>URL + &page=1</first>
        <last>URL + &page=16</last>
        <prev/>
        <next>URL + &page=2</next>
    </links>
    <meta>
        <current_page>1</current_page>
        <from>1</from>
        <last_page>16</last_page>
        <path>https://s3.fmtc.co/api/4.2.0/deals</path>
        <per_page>100</per_page>
        <to>100</to>
        <total>1518</total>
    </meta>
</results>

Example Response - CSV

Here is an example of a CSV Response from the Deals endpoint.

id,merchant_name,merchant_id,master_merchant_id,network_id,program_id,status,label,image,code,start_date,end_date,last_updated,created,affiliate_url,direct_link,freshreach_url,skimlinks_url,subaffiliate_url,fmtc_url,cascading_full_url,pixel_html,types,sale_price,was_price,discount,percent,threshold,rating,tiered_deal,brands,local,restrictions,categories,link_id
92,AreYouGame.com,13,13,3,247913,active,test,,,,2072-05-08T23:59:59.000000Z,2022-05-06T20:50:11.000000Z,2022-05-06T20:50:11.000000Z,test.com,,https://freshreach.co/click.php?c=92&m=13&cid=FMTC&uid=9107&sid=4mtc,https://go.redirectingat.com/?id=1&xs=1&xcust=4mtc&url=https%3A%2F%2Fwww.areyougame.com%2F,https://freshreach.co/click.php?c=92&m=13&cid=FMTC&uid=9107&sid=4mtc,https://fmtc.co/92/,https://www.areyougame.com/,,[],0.00,0.00,0.00,0,,,,,,,[],
93,AreYouGame.com,13,13,3,247913,active,"test label",,,,2072-05-08T23:59:59.000000Z,2022-05-06T21:05:11.000000Z,2022-05-06T20:51:13.000000Z,test.com,,https://freshreach.co/click.php?c=93&m=13&cid=FMTC&uid=9107&sid=4mtc,https://go.redirectingat.com/?id=1&xs=1&xcust=4mtc&url=https%3A%2F%2Fwww.areyougame.com%2F,https://freshreach.co/click.php?c=93&m=13&cid=FMTC&uid=9107&sid=4mtc,https://fmtc.co/93/,https://www.areyougame.com/,,[],0.00,0.00,0.00,0,,,,,,,[],
95,AreYouGame.com,13,13,3,247913,active,"test label 95",,,,2072-05-08T23:59:59.000000Z,2022-05-06T21:07:29.000000Z,2022-05-06T21:07:29.000000Z,test.com,,https://freshreach.co/click.php?c=95&m=13&cid=FMTC&uid=9107&sid=4mtc,https://go.redirectingat.com/?id=1&xs=1&xcust=4mtc&url=https%3A%2F%2Fwww.areyougame.com%2F,https://freshreach.co/click.php?c=95&m=13&cid=FMTC&uid=9107&sid=4mtc,https://fmtc.co/95/,https://www.areyougame.com/,,[],0.00,0.00,0.00,0,,,,,,,[],

Example Response - TAB

Here is an example of a TAB Response from the Deals endpoint.

id	merchant_name	merchant_id	master_merchant_id	network_id	program_id	status	label	image	code	start_date	end_date	last_updated	created	affiliate_url	direct_link	freshreach_url	skimlinks_url	subaffiliate_url	fmtc_url	cascading_full_url	pixel_html	types	sale_price	was_price	discount	percent	threshold	rating	tiered_deal	brands	local	restrictions	categories	link_id
92	AreYouGame.com	13	13	3	247913	active	test				2072-05-08T23:59:59.000000Z	2022-05-06T20:50:11.000000Z	2022-05-06T20:50:11.000000Z	test.com		https://freshreach.co/click.php?c=92&m=13&cid=FMTC&uid=9107&sid=4mtc	https://go.redirectingat.com/?id=1&xs=1&xcust=4mtc&url=https%3A%2F%2Fwww.areyougame.com%2F	https://freshreach.co/click.php?c=92&m=13&cid=FMTC&uid=9107&sid=4mtc	https://fmtc.co/92/	https://www.areyougame.com/		[]	0.00	0.00	0.00	0					[]	
93	AreYouGame.com	13	13	3	247913	active	"test label"				2072-05-08T23:59:59.000000Z	2022-05-06T21:05:11.000000Z	2022-05-06T20:51:13.000000Z	test.com		https://freshreach.co/click.php?c=93&m=13&cid=FMTC&uid=9107&sid=4mtc	https://go.redirectingat.com/?id=1&xs=1&xcust=4mtc&url=https%3A%2F%2Fwww.areyougame.com%2F	https://freshreach.co/click.php?c=93&m=13&cid=FMTC&uid=9107&sid=4mtc	https://fmtc.co/93/	https://www.areyougame.com/		[]	0.00	0.00	0.00	0					[]	
95	AreYouGame.com	13	13	3	247913	active	"test label 95"				2072-05-08T23:59:59.000000Z	2022-05-06T21:07:29.000000Z	2022-05-06T21:07:29.000000Z	test.com		https://freshreach.co/click.php?c=95&m=13&cid=FMTC&uid=9107&sid=4mtc	https://go.redirectingat.com/?id=1&xs=1&xcust=4mtc&url=https%3A%2F%2Fwww.areyougame.com%2F	https://freshreach.co/click.php?c=95&m=13&cid=FMTC&uid=9107&sid=4mtc	https://fmtc.co/95/	https://www.areyougame.com/		[]	0.00	0.00	0.00	0					[]

Example Response - PIPE

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

id|merchant_name|merchant_id|master_merchant_id|network_id|program_id|status|label|image|code|start_date|end_date|last_updated|created|affiliate_url|direct_link|freshreach_url|skimlinks_url|subaffiliate_url|fmtc_url|cascading_full_url|pixel_html|types|sale_price|was_price|discount|percent|threshold|rating|tiered_deal|brands|local|restrictions|categories|link_id
92|AreYouGame.com|13|13|3|247913|active|test||||2072-05-08T23:59:59.000000Z|2022-05-06T20:50:11.000000Z|2022-05-06T20:50:11.000000Z|test.com||https://freshreach.co/click.php?c=92&m=13&cid=FMTC&uid=9107&sid=4mtc|https://go.redirectingat.com/?id=1&xs=1&xcust=4mtc&url=https%3A%2F%2Fwww.areyougame.com%2F|https://freshreach.co/click.php?c=92&m=13&cid=FMTC&uid=9107&sid=4mtc|https://fmtc.co/92/|https://www.areyougame.com/||[]|0.00|0.00|0.00|0|||||||[]|
93|AreYouGame.com|13|13|3|247913|active|"test label"||||2072-05-08T23:59:59.000000Z|2022-05-06T21:05:11.000000Z|2022-05-06T20:51:13.000000Z|test.com||https://freshreach.co/click.php?c=93&m=13&cid=FMTC&uid=9107&sid=4mtc|https://go.redirectingat.com/?id=1&xs=1&xcust=4mtc&url=https%3A%2F%2Fwww.areyougame.com%2F|https://freshreach.co/click.php?c=93&m=13&cid=FMTC&uid=9107&sid=4mtc|https://fmtc.co/93/|https://www.areyougame.com/||[]|0.00|0.00|0.00|0|||||||[]|
95|AreYouGame.com|13|13|3|247913|active|"test label 95"||||2072-05-08T23:59:59.000000Z|2022-05-06T21:07:29.000000Z|2022-05-06T21:07:29.000000Z|test.com||https://freshreach.co/click.php?c=95&m=13&cid=FMTC&uid=9107&sid=4mtc|https://go.redirectingat.com/?id=1&xs=1&xcust=4mtc&url=https%3A%2F%2Fwww.areyougame.com%2F|https://freshreach.co/click.php?c=95&m=13&cid=FMTC&uid=9107&sid=4mtc|https://fmtc.co/95/|https://www.areyougame.com/||[]|0.00|0.00|0.00|0|||||||[]|