Management Offer 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 available to a Client

To retrieve all offers for a specific Client, make an HTTP GET request to the following URL. This method will not respond to consumer specific offers, as that is handled by the Consumer Offers API.

Gethttp://management.kouponmedia.com/v2/offers/list

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.
storeid optional Include offers associated with one or more Store ids, separated by ‘,’.
channel optional Include offers with matching channel.
tags optional Include offers tagged with this specific string.
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
longitude optional The users’ current longitude
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
                }  ...
            ]
        }
    }
}

    

Updating Already Created Offer

This Management API is used to modify attributes of a specific offer. Currently the only supported attribute that can be modified is the "Reference Offer ID". The Reference Offer ID is a value that represents the same offer in a separate 3rd party system. The reason to use a reference offer ID is to ensure multiple systems all refer back to the same offer. A referenceId is required. NOTE: An empty string can be provided to un-provision the current Reference Offer Id from the given Offer. 

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.

Puthttp://management.kouponmedia.com/v2/offers/<offer_id>

PUT Body


{ "referenceOfferId": "12345" }
    

SUCCESS Response

    
{
  "version": "2",
}
    

FAILURE Response HTTP Status Code Descriptions

HTTP Status Code Description
400 Bad Request The API request is ill formed and not understood (i.e. invalid or missing required content).
401 UnAuthorized Unable to authenticate the API request to a valid Account.
403 Forbidden Given Offer Id does not belong to authenticated Account.
404 Not Found Given Offer Id is not recognized, or has been Archived or Expired.
500 Internal Server Error An error occurred internally on the server that prevented completion of the API operation.

Failure Response

    
{
  "version": "2",
"errorCode": String,
"errorMessage": String }