CouponAPI CouponAPI Support Knowledgebase Developers
Coupon Feed API: Incremental Feed [Recommended]
Did you read below Articles for a solution?:

Coupon Feed API: Incremental Feed [Recommended]

With this method, you can build a script in PHP, Python, Java or NodeJS to sync your Website or App's Database with CouponAPI's Database.

An "Incremental Feed" is a set of changes that have happened in the CouponAPI Database since you last extracted the feed. This consists of 3 types of offers:

  1. New Offers that have got added after your last extract.
  2. Offers that were updated since your last extract.
  3. Offers that were recently suspended.

Since incremental feed only gives you the changes each time, this causes minimum load on your server.

However, before your enable your script to fetch & process incremental feeds, it is important that your server is initially in sync with the CouponAPI Database. You can do this easily by downloading a CSV full feed from your CouponAPI Account and manually uploading all existing offers to your server.

 

Flowchart

Below is a simple flowchart your script can follow to resync your server with latest feeds from CouponAPI:

Step 1: Clear Staging Table

Reset you staging table to make it ready for the process.

Why should you implement a Staging Table

Data volume of API response (even in case of incremental feeds) can sometimes be large. It is always a good practice to first save this data as-is in a temporary staging table in your database before beginning to process it. This allows you to also carry out any data sanitizations, filters, transformations and/or calculations based on input data.

Structure of the Staging Table

The structure of this staging table must be exactly like the API response i.e. each field in the response coupon object must become a column in the staging table. Ideally, this table should also not have any indexes, so that the insert statements execute as fast as possible.

Step 2: Call CouponAPI Incremental Feed

Call API to fetch offers that were added, updated or deleted since your last extract. You can get API details below.

Step 3: Save Offers in the response to your staging table

Insert all records from the API response as rows in your staging table. At this point, you can also implement any custom filters or transformations that you want to do on the data.

Step 4: Process each offer from the staging table

For each row in the staging table, do the following:

  • If status==’new’, then insert this coupon into your coupon table.
  • If status==’updated’, update all columns of this coupon in your coupon table.
  • If status==’suspended’, delete this coupon from your coupon table.
  • You may also choose to delete this row from the staging table at this stage

 

 

API Endpoint

GET  https://couponapi.org/api/getIncrementalFeed/

Sample Request

https://couponapi.org/api/getIncrementalFeed/?API_KEY=[YOUR_API_KEY]&last_extract=1675829196

Request Parameters

  • API_KEY (required) (string)
  • last_extract (optional) (epoch)
    • Possible Values: Valid UNIX Timestamp in seconds
    • Example: 1675829196
    • Default Value: Your last extract datetime in CouponAPI's records.
    • Explanation: If you are calling an ‘incremental’ feed, then Coupon API returns only the new, updated & deleted offers since your last extract. You can use this field to pass a custom value instead of using the last extract recorded by our system.
  • format (optional) (string)
    • Possible Values: csv, json
    • Default Value: csv
  • off_record (optional) (boolean)
    • Possible Values: 0,1
    • Default Value: 0
    • Explanation: Our system keeps a track of your API calls to understand which offers to send when an ‘incremental’ feed is called. If in case, you want to test the API while it is already being used on a live website, you can set this parameter to 1 in your test website. This way, your last extract time will not be updated in our system, and hence there will be no disturbance to your live website. Note that this call will still be counted in your daily limit.

Success Response:

  • result: (boolean) true
  • offers (array)
    • offer_id: (integer) A unique ID for the offer
    • title: (string) Heading of the offer
    • description: (string) Detailed description about the offer
    • code: (string) Coupon Code required to avail the offer. This field will be empty if coupon code is not required.
    • featured: (string) Possible Values: Yes, No
    • source: (string) The name of the Affiliate Network/Program from where this offer was fetched
    • url: (url) Final landing page of the offer. May be blank if not provided at source.
    • affiliate_link: (url) Affiliate Link required to monetize the offer.
    • image_url: (url) url of the image to use with this offer. May be blank if not provided at source.
    • brand_logo: (url) url of the store logo fetched from brandlogos.org (If you do not have a premium subscription, then this response will be blank)
    • type: (string) Possible Values: Code, Deals
    • store: (string) Unique store name. In most cases, this will be the primary domain name of the merchant promoting this offer.
    • merchant_home_page: (url) The homepage URL of the merchant promoting this offer.
    • categories: (string) List of categories to which this offer belongs. Please note, this will only include custom names added to the Category Mapping table in your account. If you have not mapped any custom category to the categories added for this offer by source, then this field will be blank in your response.
    • start_date: (date) Start date of the offer in yyyy-mm-dd format
    • end_date: (date) End date of the offer in yyyy-mm-dd format
    • status: (string) This field will contain the status of the offer in case of incremental feeds. It will be blank in case of full feed. Possible Values are "new", "updated" or "suspended".
    • primary_location: (string) List of Countries in which this offer is to be promoted. Usually mapped to the countries in this merchant has allowed the affiliate campaign.
    • rating: (integer) Numeric rating of the offer. Higher number signifies better rating.
    • label: (string) Short label for offer. (This feature is available only for premium plan subscribers)
    • language: (string) Language of the offer in ISO 639-1 format (2 char). (This feature is available only for premium plan subscribers)
    • deeplink: (string) The name of the Affiliate Network/Program via which the offer is monetized.
    • cashback_link: (url) Cashback affiliate link required to monetize the offer and has your affiliate network's sub id parameter.

Error Response:

  • result: (boolean) false
  • error: (string) Reason for failure

Sample Codes

PHP Code to process JSON Response Format (recommended)

<?php

// ========== CONFIG ==========
$API_KEY = '[YOUR_API_KEY]'; // Enter your API Key
$last_extract_datetime = ''; // Ideally, you should leave this blank. If you want to override last extract time stored in our system, then you can pass a date-time here.
$format = 'json';
$off_record= 0; // If set to true, system will not update your last extract time. This is useful for debugging pupose. Please note, this will still count in your API Usage limit

$last_extract = (empty($last_extract_datetime) ? '' : strtotime($last_extract_datetime));

// ========== CALL THE API TO GET JSON RESPONSE ==========
$feed = file_get_contents('https://couponapi.org/api/getIncrementalFeed/?API_KEY='.$API_KEY.'&last_extract='.$last_extract.'&format='.$format.'&off_record='.$off_record);

// ========== PROCESS JSON RESPONSE ==========
$response = json_decode($feed,true);
$offers = $response['offers'];

foreach($offers as $offer) {
    if($offer['status'] == 'new') {
        /*
            Write Code here to insert the offer in your database
        */
    } elseif($offer['status'] == 'updated') {
        /*
            Write Code here to update all fields in the offer
        */
    } elseif($offer['status'] == 'suspended') {
        /*
            Write Code here to delete the offer in your database
        */
    }
}

?>

PHP Code for Processing CSV Response Format

<?php 

// ========== CONFIG ==========
$API_KEY = '[YOUR_API_KEY]'; // Enter your API Key
$last_extract_datetime = ''; // Ideally, you should leave this blank. If you want to override last extract time stored in our system, then you can pass a date-time here.
$format = 'csv';
$off_record= 0; // If set to 1 (true), system will not update your last extract time. This is useful for debugging pupose. Please note, this will still count in your API Usage limit

$last_extract = (empty($last_extract_datetime) ? '' : strtotime($last_extract_datetime) );

// ========== CALL THE API TO GET CSV RESPONSE ==========
$csv_file = 'https://couponapi.org/api/getIncrementalFeed/?API_KEY='.$API_KEY.'&last_extract='.$last_extract.'&format='.$format.'&off_record='.$off_record;

// ========== PROCESS THE CSV FILE ==========
$offers = array();
$handle = fopen($csv_file, 'r');
$header = null;

while ($row = fgetcsv($handle)) {
    if($header === null) { // first row is header
        $header = $row;
        continue;
    }
    $offers[] = array_combine($header, $row);
}

foreach($offers as $offer) {
    if($offer['status'] == 'new') {
        /*
            Write Code here to insert the offer in your database
        */
    } elseif($offer['status'] == 'updated') {
        /*
            Write Code here to update all fields in the offer
        */
    } elseif($offer['status'] == 'suspended') {
        /*
            Write Code here to delete the offer in your database
        */
    }
}

?>

 

Article Details

Article ID:
59
Category:
Developers

Related articles