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.
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.
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”. |
{
"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
} ...
]
}
}
}
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. |
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
{
"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
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
{
"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
© Copyright 2020 Koupon
All rights reserved