Offers API

Note: Every call made to the v2 API’s must be made via the signed URL process. Any request without a valid signature will be rejected.

Getting all offers

To retrieve a list of all offers that are available for a consumer, make an HTTP GET request to the following URL.
 
Consumers providing their current latitutude (lat) and longitude (lon) expand the amount of filtering that the GET Offers API can perform. Within Koupon Media there are store specific offers and global offers. Store specific offers are valid for only specific retail locations and contain store groups as a part of their offer defintion. Global offers are valid for specific retail locations and do not contain any store groups as a part of their offer definition.

Passing in a valid location (any lat/lon values other than 0,0) will return store specific offers and global offers. Passing in lat/lon values of 0,0 will only return global offers. Passing in no lat/lon values will return all offers (without any filtering).

This method should only be used if you would like to find all the offers that are available from a consumer. If you would like to retrieve a list of offers that are specific to a given client, use the Management API of Get List of Offers for a Specific Consumer.

Gethttp://consumer.kouponmedia.com/v2/<consumer_identity>/offers

Query Parameters

Parameter Required/Optional Description
fromdt optional Include offers active on or after this date.
todt optional Include offers active on or before this date.
publishedonly optional Filter Offers to those with a Published Date on or after the current date (“yes”) or not (“no”).
storeid optional Include offers associated with one or more Store ids, separated by ‘,’.
store_group optional Filter Offers to those associated with the given Store Group identifier.
channel optional Include offers with matching channel.
digital_property_code optional Include offers within the specified digital property
geo_radius optional Filter Offers to those associated with Stores located within the radius around the given lat/lon. Optional. Will be ignored if storeid also provided.
latitude optional The users’ current latitude. Passing in a lat & lon value of 0 will return all global offers.
longitude optional The users’ current longitude. Passing in a lat & lon value of 0 will return all global offers.
geo_gating optional Filter Offers to those with a geogating enabled, if value is “1”.

Example Response


{
  "code": 200,
  "message": "success",
  "version": "2",
  “Offers”: [
        { “is_active”: Boolean,
          “featured”: Boolean,
          “geogating”: Boolean,
          “is_multi”: Boolean,
          “clientid”: Number,
          “offerId”: ,
          “priority”: Number,
          “timer”: Number,
          “totalOffersPurchased”: Number,
          “totalOffersRemaining”: Number,
          “barcodeString”: String,
          “barcodeSymbology”: String,
          “barcodeType”: String,
          “channel”: String,
          “companyImage”: URLString,
          “doneMessage”: String,
          “errorMsg”: String,
          “offer”: “/offers/”,
          “offerDisclaimer”: String,
          “offerEnd”: “03-15-13 11:00:00 AM”,
          “offerInstructions”: String,
          “offerName”: String,
          “offerPublished”: “11-28-12 12:00:00 AM”,
          “offerStart”: “12-01-12 12:00:00 AM”,
          “offerSubtitle”: String,
          “offerTitle”: String,
          “offerType”: String,
          "visibility": String,
          “primaryImage”: URLString,
          “printImage”: URLString,
          “secondaryImage”: URLString,
          “tags”: String,
          “UPC”: URLString,
          “validDateDescription”: String,
          "print": { 
              “printImage”: URLString,
              "totalPrintLimit": Number,
              "totalPrintsRemaining": Number,
              "smsEnabled": Boolean,
              "printEnabled": Boolean,
              "printTitle": String,
              "printDescription": String,
              "printInstructions": String
          },
          "limitedStores:  Boolean,
          "validAtStores": [
                {  "id" : String,
                   "name" : String,
                   "address" : String,
                   "city" : String,
                   "state" : String,
                   "zip" : String,
                   "lat" : Double,
                   "lon" : Double,
                   "distance" : Double   }   ...
          ], 
          "consumerPOS": {
              "redemptionLimit":  Number,
              "redemptionCount":  Number
           },
          "smsEnabled" : Boolean,
          "emailEnabled" : Boolean,
          "passbookEnabled" : Boolean,
          "showNearbyStores" : Boolean,
          "storeListRadius" : Number,
          “brandColor”: String,
          "cpg":  {
              "cpgBrandId":  Number,
              "cpgId":  Number,
              "brandId":  String,
              "cpgName":  String,
              "brandName":  String,
              "isAdult":  Boolean,
              "adultClass":  String,
              "adultSubclass":  String,
              "identityScheme":  String,
              "warningAlgorithm":  String,
              "isAuthenticated":  Boolean,
              "isOriginatingOffer":  Boolean,
          },
          "displayStore":  {
               "id" : String,
               "name" : String,
               "address" : String,
               "city" : String,
               "state" : String,
               "zip" : String,
               "lat" : Double,
               "lon" : Double
          },
          "offerStyle":  String,
          "redirect":  {
              "channelCode":  String,
              "offerViewerURL":  String,
          },
          "nativeAd":  {
              "externalURL":  URLString
          },
          "loyaltyCard":  {
              "couponCode":  String
          }
        }  ...
    ],
    "summary": {
        "numCoupon":  Number,
        "numNativeAd":  Number,
        "numRedirect":  Number,
        "numLoyaltyCard":  Number,
        "tobacco": {
            "numOffersAvailable":  Number,
            "brands": [
                {
                      "cpgBrandId":  Number,
                      "brandName":  String,
                      "isAuthenticated":  Boolean,
                      "numOffersAvailable":  Number
                }  ...
            ]
        }
    }
}

Response keys

Key Description
geogating Will be true if Geogating is enabled for the Offer, false if not.
visibility The visibility of the Offer. If an Offer is configured as Triggered, this will be “private”; otherwise, it will be “public”.
primaryImage The primary Offer image for the Offer.
secondaryImage The additional Offer image for the Offer. Optional.
print Contains attributes of the Offer related to browser-based print.
print.printImage The coupon image with barcode, created from template, to print for the Offer. Optional.
print.totalPrintLimit The total number of prints of the Offer available for a single Consumer.
print.totalPrintsRemaining The number of prints the given Consumer has remaining. Calculated by subtracting the # of entries in the offers_printed table for the consumer/offer from the totalPrintLimit value.
print.smsEnabled Identifies whether the Offer is allowed to be sent as part of a bundled link via SMS in addition to printing (true) or not (false), based on configuration settings and past Consumer actions.
print.printEnabled Identifies whether the Offer is allowed to be printed (true) or not, based on configuration settings and past Consumer actions.
print.printTitle The print title for the Offer.
print.printDescription The print description for the Offer.
print.printInstructions The print instructions for the Offer.
limitedStores Will be true if the Offer is not valid to redeem at one or more of the Stores found within the given geo_radius (or storeid), false if valid at all Stores or if storeid and geo_radius filter options were not provided.
validAtStores An array of Store Locations within the given geo_radius (or storeid) that the Offer is valid to redeem at.  Array may be empty if Offer is valid at any Store or storeid and geo_radius filter options were not provided.
consumerPOS Contains attributes of the Offer related to Per-Consumer Redemption Limits.
consumerPOS.redemptionLimit The limit of POS redemptions a Consumer is allowed for the Offer.
consumerPOS.redemptionCount The number of POS redemptions the Consumer has actually executed.
smsEnabled Indicates whether SMS redemption is enabled for the Offer (true) or not (false).
emailEnabled Indicates whether Email redemption is enabled for the Offer (true) or not (false).
passbookEnabled Indicates whether this Offer is enabled for Passbook (true) or not (false).
showNearbyStores Indicates whether to show the nearby stores when displaying this Offer (true) or not (false).
storeListRadius The radius to be used when gathering nearby stores.  Only applicable if showNearbyStores is true.
brandColor A string representing the RGB color value for the Offer.
cpg Contains attributes about the CPG Brand associated with this Offer, if any.
cpg.cpgBrandId The Id of the CPG Brand associated with this Offer.  Optional.
cpg.cpgName The name of the CPG associated with this Offer.  Optional.
cpg.brandName The name of the CPG Brand associated with this Offer.  Optional.
cpg.isAdult Will be true if the Offer represents adult-oriented content for the CPG Brand, false if not.
cpg.adultClass The name of the Adult Class associated with this Offer, if isAdult is true.
cpg.adultSubclass The name of the Adult Subclass associated with this Offer, if isAdult is true.
cpg.identityScheme The name of the identity scheme of this Offer. Will be ‘provided’ or ’embedded’.
cpg.warningAlgorithm A JSON object string containing the image URL and parameters governing the display of the warning image. Optional.
cpg.isAuthenticated Returns true if the Consumer is currently authenticated for the CPG Brand, false if not or isAdult is false.
cpg.isOriginatingOffer Returns true if the Offer is an originating Offer published to the Offer Network.
displayStore Contains the configured information for the Store corresponding to the given display_store parameter, if provided. Optional.
offerStyle The Style of the Offer. One of “Coupon”, “LoyaltyCard”, “Native Ad”, or “Redirect”. Defaults to “Coupon” if not present.
redirect Contains attributes specific to an Offer Style of “Redirect”. Optional; will be null if not applicable.
redirect.channelCode The Code string of the Channel being redirected to.
redirect.offerViewerURL The Offer Viewer URL for the Redirect Channel.
nativeAd Contains attributes specific to an Offer Style of “Native Ad”. Optional; will be null if not applicable.
nativeAd.externalURL The URL to open when the Offer is clicked on in a List.
loyaltyCard Contains attributes specific to an Offer Style of “LoyaltyCard”. Optional; will be null if not applicable.
asdf loyaltyCard.couponCode The Coupon Code associated with the Offer, as defined by the Loyalty Card provider.
summary Contains summary information about the Offers in the List.
summary.numCoupon The number of active, live Coupon style Offers returned.
summary.numNativeAd The number of active, live Native Ad style Offers returned.
summary.numRedirect The number of active, live Redirect style Offers returned.
summary.numLoyaltyCard The number of active, live Loyalty Card style Offers returned.
summary.tobacco Contains summary information about Tobacco brand Offers, if any.
summary.tobacco.numOffersAvailable The number of active, live Offers for all Tobacco CPG Brands. This count may not be fully reflected in the Offers array due to CPG Brands that are not authenticated.
summary.tobacco.brands Array that contains summary information for each Tobacco CPG Brand associated with an active, live Offer. Will be empty if no active, live Offers for any Tobacco brands.
summary.tobacco.brands[x].cpgBrandId The Id of a CPG Brand which currently has one or more live, active Offers.
summary.tobacco.brands[x].brandName The name of the CPG Brand.
summary.tobacco.brands[x].isAuthenticated Returns true if the Consumer is currently authenticated for the CPG Brand, false if not.
summary.tobacco.brands[x].numOffersAvailable The number of active, live Offers for the CPG Brand. This count will not be reflected in the Offers array if isAuthenticated is false.

Getting single offer

To retrieve a single offer that is available for a specific consumer, make an HTTP GET request to the following URL while passing in the specific offerId desired

Gethttp://consumer.kouponmedia.com/v2/<consumer_identity>/offers/<offerId>

Example Response


{
  "code": 200,
  "message": "success",
  "version": "2",
  “Offers”: [
        { “is_active”: Boolean,
          “featured”: Boolean,
          “geogating”: Boolean,
          “is_multi”: Boolean,
          “clientid”: Number,
          “offerId”: ,
          “priority”: Number,
          “timer”: Number,
          “totalOffersPurchased”: Number,
          “totalOffersRemaining”: Number,
          “barcodeString”: String,
          “barcodeSymbology”: String,
          “barcodeType”: String,
          “channel”: String,
          “companyImage”: URLString,
          “doneMessage”: String,
          “errorMsg”: String,
          “offer”: “/offers/”,
          “offerDisclaimer”: String,
          “offerEnd”: “03-15-13 11:00:00 AM”,
          “offerInstructions”: String,
          “offerName”: String,
          “offerPublished”: “11-28-12 12:00:00 AM”,
          “offerStart”: “12-01-12 12:00:00 AM”,
          “offerSubtitle”: String,
          “offerTitle”: String,
          “offerType”: String,
          "visibility": String,
          “primaryImage”: URLString,
          “printImage”: URLString,
          “secondaryImage”: URLString,
          “tags”: String,
          “UPC”: URLString,
          “validDateDescription”: String,
          "print": { 
              “printImage”: URLString,
              "totalPrintLimit": Number,
              "totalPrintsRemaining": Number,
              "smsEnabled": Boolean,
              "printEnabled": Boolean,
              "printTitle": String,
              "printDescription": String,
              "printInstructions": String
          },
          "limitedStores:  Boolean,
          "validAtStores": [
                {  "id" : String,
                   "name" : String,
                   "address" : String,
                   "city" : String,
                   "state" : String,
                   "zip" : String,
                   "lat" : Double,
                   "lon" : Double,
                   "distance" : Double   }   ...
          ], 
          "consumerPOS": {
              "redemptionLimit":  Number,
              "redemptionCount":  Number
           },
          "smsEnabled" : Boolean,
          "emailEnabled" : Boolean,
          "passbookEnabled" : Boolean,
          "showNearbyStores" : Boolean,
          "storeListRadius" : Number,
          “brandColor”: String,
          "cpg":  {
              "cpgBrandId":  Number,
              "cpgId":  Number,
              "brandId":  String,
              "cpgName":  String,
              "brandName":  String,
              "isAdult":  Boolean,
              "adultClass":  String,
              "adultSubclass":  String,
              "identityScheme":  String,
              "warningAlgorithm":  String,
              "isAuthenticated":  Boolean,
              "isOriginatingOffer":  Boolean,
          },
          "displayStore":  {
               "id" : String,
               "name" : String,
               "address" : String,
               "city" : String,
               "state" : String,
               "zip" : String,
               "lat" : Double,
               "lon" : Double
          },
          "offerStyle":  String,
          "redirect":  {
              "channelCode":  String,
              "offerViewerURL":  String,
          },
          "nativeAd":  {
              "externalURL":  URLString
          },
          "loyaltyCard":  {
              "couponCode":  String
          }
        }  ...
    ],
    "summary": {
        "numCoupon":  Number,
        "numNativeAd":  Number,
        "numRedirect":  Number,
        "numLoyaltyCard":  Number,
        "tobacco": {
            "numOffersAvailable":  Number,
            "brands": [
                {
                      "cpgBrandId":  Number,
                      "brandName":  String,
                      "isAuthenticated":  Boolean,
                      "numOffersAvailable":  Number
                }  ...
            ]
        }
    }
}

Response code is the same as GET /<consumer_identity>/offers

Getting multiple offers

To retrieve a specific subset of offers that are available for a specific consumer, make an HTTP GET request to the following URL while passing in a comma separated list of offerId’s desired

Gethttp://consumer.kouponmedia.com/v2/<consumer_identity>/offers/<offerList>

Example Response


{
  "code": 200,
  "message": "success",
  "version": "2",
  “Offers”: [
        { “is_active”: Boolean,
          “featured”: Boolean,
          “geogating”: Boolean,
          “is_multi”: Boolean,
          “clientid”: Number,
          “offerId”: ,
          “priority”: Number,
          “timer”: Number,
          “totalOffersPurchased”: Number,
          “totalOffersRemaining”: Number,
          “barcodeString”: String,
          “barcodeSymbology”: String,
          “barcodeType”: String,
          “channel”: String,
          “companyImage”: URLString,
          “doneMessage”: String,
          “errorMsg”: String,
          “offer”: “/offers/”,
          “offerDisclaimer”: String,
          “offerEnd”: “03-15-13 11:00:00 AM”,
          “offerInstructions”: String,
          “offerName”: String,
          “offerPublished”: “11-28-12 12:00:00 AM”,
          “offerStart”: “12-01-12 12:00:00 AM”,
          “offerSubtitle”: String,
          “offerTitle”: String,
          “offerType”: String,
          "visibility": String,
          “primaryImage”: URLString,
          “printImage”: URLString,
          “secondaryImage”: URLString,
          “tags”: String,
          “UPC”: URLString,
          “validDateDescription”: String,
          "print": { 
              “printImage”: URLString,
              "totalPrintLimit": Number,
              "totalPrintsRemaining": Number,
              "smsEnabled": Boolean,
              "printEnabled": Boolean,
              "printTitle": String,
              "printDescription": String,
              "printInstructions": String
          },
          "limitedStores:  Boolean,
          "validAtStores": [
                {  "id" : String,
                   "name" : String,
                   "address" : String,
                   "city" : String,
                   "state" : String,
                   "zip" : String,
                   "lat" : Double,
                   "lon" : Double,
                   "distance" : Double   }   ...
          ], 
          "consumerPOS": {
              "redemptionLimit":  Number,
              "redemptionCount":  Number
           },
          "smsEnabled" : Boolean,
          "emailEnabled" : Boolean,
          "passbookEnabled" : Boolean,
          "showNearbyStores" : Boolean,
          "storeListRadius" : Number,
          “brandColor”: String,
          "cpg":  {
              "cpgBrandId":  Number,
              "cpgId":  Number,
              "brandId":  String,
              "cpgName":  String,
              "brandName":  String,
              "isAdult":  Boolean,
              "adultClass":  String,
              "adultSubclass":  String,
              "identityScheme":  String,
              "warningAlgorithm":  String,
              "isAuthenticated":  Boolean,
              "isOriginatingOffer":  Boolean,
          },
          "displayStore":  {
               "id" : String,
               "name" : String,
               "address" : String,
               "city" : String,
               "state" : String,
               "zip" : String,
               "lat" : Double,
               "lon" : Double
          },
          "offerStyle":  String,
          "redirect":  {
              "channelCode":  String,
              "offerViewerURL":  String,
          },
          "nativeAd":  {
              "externalURL":  URLString
          },
          "loyaltyCard":  {
              "couponCode":  String
          }
        }  ...
    ],
    "summary": {
        "numCoupon":  Number,
        "numNativeAd":  Number,
        "numRedirect":  Number,
        "numLoyaltyCard":  Number,
        "tobacco": {
            "numOffersAvailable":  Number,
            "brands": [
                {
                      "cpgBrandId":  Number,
                      "brandName":  String,
                      "isAuthenticated":  Boolean,
                      "numOffersAvailable":  Number
                }  ...
            ]
        }
    }
}

Response code is the same as GET /<consumer_identity>/offers