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.
New 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
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 | |
Feed Format | Choose the feed format you would like returned. | format | format | |
Incremental Testing Parameter | Testing Parameter for incremental. | 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 | |
Merchant Deals | Return only deals from a particular merchant. | merchantids | merchantids | |
Category Deals | Return only deals from a particular category or categories. | categoryids | categoryids | |
Field Sorting | Field to order the results by. | sortby | sortby | |
Deal Types | Return only deals from of a particular type. | dealtype | **dealtypeid | |
Deal Countries | Return only deals from merchants with a particular Primary Country. | country | country | |
Network Deals | Return only deals from a particular network. | network | **networkid | |
Deleted Deals | Include deleted deals | deleted | Deprecated | |
Historical Deals | This option will return expired coupons and deals since your subscription began or up to two years worth of data. | 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 | |
Active Deals | Display only active deals. | active | active | |
Deal Limit | Limit the number of deals returned. | count | count | Deprecated |
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. | pod | Deprecated | |
Enable New Categories | This option is used to enable v2 categories on a per call basis. | v2categories | Deprecated | |
zipcode | Deprecated | Deprecated | ||
version | Deprecated | Deprecated | ||
level | Deprecated | Deprecated | ||
mode | Deprecated | Deprecated | ||
recent | Deprecated | Deprecated |
Output Parameters
Name | Description | Version 1 Field | Version 2 Field | Version 3 Field |
|---|---|---|---|---|
Deal Identifier | Our proprietary Deal ID. | CouponID | id | |
Merchant Name | Name of the merchant in the FMTC database. | MerchantName | merchant_name | |
Merchant Identifier | The ID assigned to the merchant by FMTC. | MerchantID | merchant_id | |
Master Merchant Identifier | Each unique merchant has an ID that is shared across all the networks a merchant is active on. | MasterMerchantID | master_merchant_id | |
Network Identifier | An FMTC assigned ID for the affiliate network associated with this merchant. | Network | network_id | |
Program Identifier | A Network assigned ID for the merchant that their program is on. | ProgramID | program_id | |
Label | Describes the coupon value or description of the deal. | Label | label | |
Custom Content Label | Short description of the deal in a custom format selected by the user. | CustomLabel | Future Update | |
Custom Content Description | Long Description of the deal in a custom format selected by the user. | CustomDescription | Future Update | |
Deal Code | If the offer requires the user to enter a code, it is in this field. | CouponCode | code | |
Image URL | Images are included when possible and are typically delivered with product offers and grocery coupons. | Image | image | |
Deal Start Date | Date the offer begins with start time. | StartDate | start_date | |
Deal End Date | Date the offer ends with end time. | 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 | AffiliateURL | affiliate_url | |
Direct URL | Unmonetized non-affiliate link that lands on the page associated with the offer. | DirectURL | direct_link | |
FreshReach® URL | Link that lands on the page associated with the offer and is monetized by FreshReach®. | 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. | FMTCURL | fmtc_url | |
Skimlinks URL | Link that lands on the page associated with the offer and is monetized by Skimlinks. | SkimlinksURL | skimlinks_url | |
SubAffiliate URL | Link that lands on the page associated with the offer and is monetized by a subaffiliate network. | SubAffiliateURL | subaffiliate_url | |
Tracking Pixels | Tracking pixel provided by the associated affiliate network when 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 | |
Original FMTC Categories | Categories the coupon or deal can be classified by, i.e. apparel, books, shoes, toys, etc. | Categories | Deprecated | |
Updated FMTC Categories | Categories the coupon or deal can be classified by, i.e. apparel, books, shoes, toys, etc. | 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 | types | |
Deal Status | The status should always be checked, and only "active" deals should be displayed. | Status | status | |
Deal Create Date | The date the offer was added to FMTC's database. | Created | created | |
Deal Update Date | When this deal was last modified by FMTC. | LastUpdated | last_update | |
Deal Sale Price | Discounted price of a product. Not included on all product deals. | SalePrice | sale_price | |
Deal Was Price | Original price of a product. Not included on all product deals. | WasPrice | was_price | |
Deal Dollar Off Amount | The system calculated dollar off savings when a sale product has "was" and "now" pricing. | DollarsOff | discount | |
Deal Percent Off Amount | The system calculated percent off savings when a sale product has "was" and "now" pricing. | PercentOff | percent | |
Deal Threshold Amount | The minimum amount a shopper must spend in order to qualify for an offer. | Threshold | threshold | |
FMTC Deal Rating | Deal Rankings are assigned to every offer. | Rank/Rating | rating | |
Star Ranking | This offer was flagged by an FMTC Data Engineer as being exceptionally valuable. | Starred | Deprecdted | |
Brand Name | List of brands related to this deal. | Brands | brands | |
Tiered Deal | This offer was flagged by an FMTC Data Processor as being a tiered deal. | nTieredDeal | tiered_deal | |
Network Link ID | This is the Network LinkID associated with this deal. | LinkID | link_id | |
Local Deal | Local Information about the deal, including address and zip code. | local | locations |
Merchants
You can find more information on each of the fields on the respective API pages.
Input Parameters
Name | Description | Version 1 Field | Version 2 Field | Version 3 Field |
|---|---|---|---|---|
Output Parameters
Name | Description | Version 1 Field | Version 2 Field | Version 3 Field |
|---|---|---|---|---|
Categories
You can find more information on each of the fields on the respective API pages.
Input Parameters
Name | Description | Version 1 Field | Version 2 Field | Version 3 Field |
|---|---|---|---|---|
Output Parameters
Name | Description | Version 1 Field | Version 2 Field | Version 3 Field |
|---|---|---|---|---|
Types
You can find more information on each of the fields on the respective API pages.
Input Parameters
Name | Description | Version 1 Field | Version 2 Field | Version 3 Field |
|---|---|---|---|---|
Output Parameters
Name | Description | Version 1 Field | Version 2 Field | Version 3 Field |
|---|---|---|---|---|
Logos
You can find more information on each of the fields on the respective API pages.
Input Parameters
Name | Description | Version 1 Field | Version 2 Field | Version 3 Field |
|---|---|---|---|---|
Output Parameters
Name | Description | Version 1 Field | Version 2 Field | Version 3 Field |
|---|---|---|---|---|
Network
You can find more information on each of the fields on the respective API pages.
Input Parameters
Name | Description | Version 1 Field | Version 2 Field | Version 3 Field |
|---|---|---|---|---|
Output Parameters
Name | Description | Version 1 Field | Version 2 Field | Version 3 Field |
|---|---|---|---|---|
Changes
You can find more information on each of the fields on the respective API pages.
Input Parameters
Name | Description | Version 1 Field | Version 2 Field | Version 3 Field |
|---|---|---|---|---|
Output Parameters
Name | Description | Version 1 Field | Version 2 Field | Version 3 Field |
|---|---|---|---|---|
New Fields
Deals
Input Parameters
networkid replaces network, moving from an string to an ID.
Output Parameters
coupon_code_on_page
code_verified_at
cascading_full_url
link_verified_at
meta
Merchants
Input Parameters
Output Parameters
Categories
Input Parameters
Output Parameters
Types
Input Parameters
Output Parameters
Logos
Input Parameters
Output Parameters
Networks
Input Parameters
Output Parameters
Changes
Input Parameters
Output Parameters
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.
page_size is a new field