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
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 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.
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 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 |
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.
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 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.
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.
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.
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.
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.
"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
},