Deem Offers API Documentation

Get Deals

The Get Deals call returns a set of applicable deal resources based on the filtering parameters you pass in your request. You can request a broad list of available deals or very specific highly targeted deals to provide to your users.

You must specify in the request the attributes you want returned in the JSON response for each deal. You may specify all available fields or a subset of fields that you need.. You may specify any, or all of the attributes available. See the “Specifying attributes to be returned” for an example and see the “Response” section for a list of all possible values.

Returned results will be sorted in descending order by deal end date. If you would like the results sorted differently, you may also specify the sort order for deals returned within the JSON response. You can find the sort options in the “Specifying sort order” section.

Each deal has a number of attributes you can use to filter the Get Deals request – the price point, the amount of inventory, the merchant, the deal title, the run date, the location, and so on. You can find all of the possible filtering parameters in the “Specifying filters” section. For more information about the deal resource, see the “Response” section.

If you make this call with no filters, Get Deals returns a list of all “in-flight” (currently active) deals across all geographical regions – including deals that are sold out and deals that are not sold out. To avoid retrieving sold-out deals, we recommend that you pass filters=sold_out=false when making this call.

Request

GET /api/v3/deals

Specifying attributes to be returned

You provide the attributes to be included in the query string with the key word “fields”. The list of attributes to be returned should be a comma separated list of fields. Some fields (like images include multiple sub-fields that can be returned. For these, you must specify which sub-fields to return inside a set of square brackets [].

GET https://username:password@api.offers.deem.com/api/v3/deals?fields=id,title,price,region,type,images[small,large]

Specifying sort order

You specify the sort order in the query string with the key word “sort”. Ascending(asc) and Descending(desc) order can be indicated in parentheses.

GET https://username:password@api.offers.deem.com/api/v3/deals?sort=start_at(desc)&fields=id,title,price,region,type,images[small,large]

Specifying filters

You specify filtering in the query string with the key word “filter”.

GET https://username:password@api.offers.deem.com/api/v3/deals?filter=region[san-francisco,phoenix],sold_out[false],price>1500&fields=id,title,price,region,type,images[small,large]

As you add a parameter to the filter with a comma(,), it is evaluated with a logical AND operation with any other parameter to filter the results.

Individual deal filter parameters

Category parameters

category
Optional String : Filter deals by category. Deals can be returned in the category “foo” using ?filter=category[foo]. Deals can be returned in multiple categories using ?filter=category[foo,bar].
subcategory
Optional String : Filter deals by subcategory. Deals can be returned in the subcategory “foo” using ?filter=subcategory[foo]. Deals can be returned in multiple subcategories using ?filter=subcategory[foo,bar].

Price parameters

price
Optional Integer : Filter the deal price in cents (i.e., 100 equals one dollar). Can be used in conjunction with “<”, “>”, “=” and combinations thereof using for instance ?filter=price>=1500. Multiple exact price matches can be selected using ?filter=price[1300,1500].

Location parameters

region
Optional String : Filter deals by region_id. Can be used in conjunction with “[]”. To select all deals from multiple regions, use ?filter=region[san-francisco,atlanta].
region_city
Optional String : Filter deals by city within two character state. Should be nested within “[]”. Use?filter=region_city[san%20francisco,ca]. To select deals from multiple region cities, nest the selection array within an outer array. Use ?filter=region_city[[san%20francisco,ca],[los%20angeles,ca]].
lat_long
Optional String : Filter deals by location using latitude, longitude and radius in miles. Use ?filter=lat_long[123.1112,-321.1132,5].

Inventory parameters

sold_out
Optional Boolean : Filter deals that are either sold_out or not sold_out. Use ?filter=sold_out[false] to select deals that are not sold_out.

Response

The response includes the HTTP status of the request along with the associated response data provided in a JSON file.

Response Attributes

The response JSON file contains a list of deal resources that meet the request filter parameters.

Status attributes

status
String State of the request (error) only present when an error has occurred

Deal attributes

A list of deal resources with all associated deal attributes for each deal in the result set:

id
String Unique identifier for purchased deal
campaign
String The name for tracking a group of deals used in a marketing campaign
category
String Broad deal type
category_id
String Unique identifier for category the deal is in
cost
Integer The cost of the deal in cents
description1
String Primary description of the deal
description2
String Secondary description of the deal
end_at
Date The date and time that the deal will no longer be available to purchase (times are in UTC)
expires_at
Date If set, the date and time that the deal voucher will expire (times are in timezone of deal’s region)
expiration_days
Integer If set, the number of days after which a voucher will expire.
fine_print
String Specific details and restrictions associated with the deal
fine_print_legalese
String Legal Specifics details and restrictions associated with the deal (fulfillment_method=’printed’ only)
fixed_fee
Integer The fee charged for running the deal in cents (only for card-linked deals)
fulfillment_method
String How the consumer redeems the deal:
  • redemptioncoded - A purchase grants the customer a code which is provided by a merchant that can be redeemed on the merchant’s website.
  • printed - A user pays for and prints out a physical coupon to bring to a store to redeem for a discount on goods or services.
  • shipped - The purchase is shipped to the customer
highlights
String Additional important details about the deal
images
Hash A list of deal images in different sizes. Each image is available in the following sizes: * large, medium, small, and tiny * Each item points to the images URL.
incentive_amount
Integer A flat amount of discount in cents that a user gets for using this deal (only for card-linked deals)
incentive_percentage
Integer The percent discount a user gets for using this deal (only for card-linked deals)
instructions
String Usage details for the deal
locations
Array The physical locations associated with the deal
max_linkage
Integer Number of users that can link to deal (only for card-linked deals)
max_per_user
Integer The maximum quantity available to purchase by a user
max_gift_per_user
Integer How many gifts each user is allowed to buy
maximum_allowance
Integer The maximum value of a deal purchase (only for card-linked deals)
merchant_id
String Unique identifier for the merchant offering the deal
merchant_name
String Name of the merchant of the deal
min_spend
Integer The minimum value of a purchase to qualify for the deal (only for card-linked deals)
num_left
Integer The quantity of units left for purchase
num_qualifying
Integer Number of qualifying purchases required to trigger redemption (only for card-linked deals)
number_sold
Integer The quantity of units sold of this deal
percent_fee
Integer The percent charged for running the deal (only for card-linked deals)
purchase_url
String The URL for deal purchase web page
redemption_url
String The URL a purchaser will redeem the coupon/redemption code
region_id
String Unique identifier for region in which the deal is for sale
region_name
String Human-readable region name
robotitle
String The deal title for affiliate feeds
shipping_address_required
Boolean Flagged if a shipping address is required to purchase this deal
show_url
String The URL for the deal details web page
sold_out
Boolean Flagged if the deal has sold out of inventory
start_at
Date The date and time that the deal was first available to purchase (times are in UTC)
state
String The current workflow state of the deal:
  • in-flight - The deal is available for purchase. (This is the only state returned by the API)
subcategory
String More specific deal type
supplier_id
String Unique identifier for supplier of the deal
tags
Array An array of the tags associated with this deal
title
String Title of the purchased deal
type
String Type of the purchased deal
Daily Deal:
The Daily Deal is a prepaid voucher which is in-flight on a partner site for a short period of time. :
On-going:
A long-running prepaid voucher deal which is in-flight on partner sites for more than 15 days. :
Affiliate:
A a deal that can be claimed by a consumer for free. The consumer can click the Claim this deal button to obtain a coupon code. :
Affiliate deals do not have actual purchases or vouchers associated with them. A user claims an affiliate deal which: :
a) exposes a redeemable code.
OR
b) redirects the user to a co-marketed website. :
Card-linked Offers:
A card-linked offer (CLO) is an offer linked to a payment card. The user links an offer to his or her card without having to pay anything. When the user buys the product or service from the qualifying merchant, the offer is applied to the transaction immediately, reducing the card charge, or is applied as a credit to the card.
value
Integer The value of the deal in cents

Pagination attributes

next_page
String The URL for the next page of deals.

Response Examples

Filter deals by the “los_angeles” region with two deals returned:

Status: 200 OK
{
  "deals": [
    {
      "id": "la-1024-wsc-hair-studio-01-2",
      "campaign": null,
      "category": "Activities",
      "category_id": "activities",
      "cost": 7000,
      "description1": "Complete cocktail and bartending how-to's. With National Bartenders School, you'll have your choice of six locations across Southern California to choose from. Each location recreates an actual bar, with all the equipment and tools you'll be using on the job. Over the course of 40 hours, you'll get to know your Tom Collins from your Shirley Temples. This deal includes all the books, registration fees and certification required to get you behind an actual bar. And with their job placement assistance, you'll be doing your best Sam Malone impression quicker than it takes to mix a Mai Tai.",
      "description2": "Do you prefer go to bed when the roosters are crowing as opposed to waking up with them? Night owls have a reason to give a hoot with today's deal: $199 for a two-week bartending course at National Bartenders School (a $495 value).",
      "end_at": "2013-10-25T06:59:59Z",
      "expires_at": "2013-12-17T23:59:59-08:00",
      "expiration_days": null,
      "fine_print": "Must be 18 or older with valid ID - Limit 1 voucher per person - By appointment/reservation only - Valid only at participating locations - Classes subject to availability - Valid at West Los Angeles, Hollywood, Orange County, Long Beach, Canyon Country and Riverside locations only - Call the location of the school you wish to take the course at to schedule your appointment for orientation",
      "fine_print_legalese": "Redeemable vouchers have two values: (1) Amount Paid; and (2) Promotional Value. The Amount Paid means the amount paid by you to purchase the voucher. Amount Paid does not expire unless the voucher is redeemed or refunded. The Promotional Value means the additional value beyond the Amount Paid. The Amount Paid for this Voucher is $39.00. This amount does not expire. The Promotional Value of this Voucher is $61.00. Promotional Value will expire on 12/17/2013 unless prohibited by law.",
      "fixed_fee": null,
      "fulfillment_method": "printed",
      "highlights": "Complete cocktail how-to's Choice of six locations 40 hours of instruction",
      "images": {
        "tiny": "https://d2x9dz1etb1m98.cloudfront.net/ugassets/deal/images/b/5/ff54ac03/tiny.jpg",
        "small": "https://d2x9dz1etb1m98.cloudfront.net/ugassets/deal/images/b/5/ff54ac03/tiny.jpg",
        "medium": "https://d2x9dz1etb1m98.cloudfront.net/ugassets/deal/images/b/5/ff54ac03/medium.jpg",
        "large": "https://d2x9dz1etb1m98.cloudfront.net/ugassets/deal/images/b/5/ff54ac03/large.jpg"
      },
      "incentive_amount": null,
      "incentive_percentage": null,
      "instructions": "The Amount Paid for this Voucher is $39. This amount does not expire. The Promotional Value of this Voucher is $61. This amount will expire on the referenced expiration date. This Voucher is redeemable starting 2012-11-12. This Voucher is transferable. This voucher has two values: (1) Amount Paid; and (2) Promotional Value. The Amount Paid means the amount paid by you to purchase the voucher. Amount Paid does not expire unless the voucher is redeemed or refunded. The Promotional Value means the additional value beyond the Amount Paid. Promotional Value will expire on the expiration dates unless prohibited by law.",
      "locations": [
        {
          "address": {
            "address_id": "8a23af0847",
            "region": "CA",
            "postal_code": "90057",
            "street": "671 la fayette park place",
            "latitude": 34.060428619,
            "locality": "los angeles",
            "longitude": -118.283882141,
            "country": "US"
          },
          "hours": "",
          "phone": "8887187201"
        }
      ],
      "max_linkage": null,
      "max_per_user": 11,
      "max_gift_per_user": 0,
      "maximum_allowance": null,
      "merchant_id": "a5b03069dd",
      "merchant_name": "1024 WSC Hair Studio 01",
      "min_spend": null,
      "num_left": 499,
      "num_qualifying": null,
      "number_sold": 0,
      "percent_fee": null,
      "purchase_url": "https://homerun-f2.offerify.com/deal/la-1024-wsc-hair-studio-01-2/checkout",
      "region_id": "los-angeles",
      "region_name": "Los Angeles",
      "robotitle": "$39 for $100 of 1024 WSC Salon - Other at 1024 WSC Hair Studio 01",
      "shipping_address_required": false,
      "show_url": "http://homerun-f2.offerify.com/deal/la-1024-wsc-hair-studio-01-2",
      "soldout": false,
      "start_at": "2013-10-17T07:00:00Z",
      "starting_price": 3900,
      "state": "in-flight",
      "subcategory": "Bike Rentals",
      "supplier_id": "homerun",
      "tags": [
        "Limited-time-only"
      ],
      "title": "1024 WSC Salon - Other - $39 for $100",
      "type": "daily-deal",
      "value": 10000
    },
    {
      "id": "den-621-rel-merchant-4",
      "campaign": null,
      "category": "Activities",
      "category_id": "activities",
      "cost": 7000,
      "description1": "",
      "description2": "",
      "end_at": "2014-01-01T06:59:59Z",
      "expires_at": "2013-11-20T13:25:14-07:00",
      "expiration_days": null,
      "fine_print": "",
      "fine_print_legalese": "",
      "fixed_fee": null,
      "fulfillment_method": "printed",
      "highlights": null,
      "images": {
        "tiny": "https://d2x9dz1etb1m98.cloudfront.net/ugassets/deal/images/b/5/ff55ac03/tiny.jpg",
        "small": "https://d2x9dz1etb1m98.cloudfront.net/ugassets/deal/images/b/5/ff55ac03/tiny.jpg",
        "medium": "https://d2x9dz1etb1m98.cloudfront.net/ugassets/deal/images/b/5/ff55ac03/medium.jpg",
        "large": "https://d2x9dz1etb1m98.cloudfront.net/ugassets/deal/images/b/5/ff55ac03/large.jpg"
      },
      "incentive_amount": null,
      "incentive_percentage": 15,
      "instructions": "",
      "locations": [
        {
          "address": {
            "address_id": "8a23af0847",
            "region": "Colorado",
            "postal_code": "80234",
            "street": "7072 North Mariposa Court",
            "latitude": 39.923740387,
            "locality": "Westminster",
            "longitude": -105.003417969,
            "country": "United States"
          },
          "hours": "",
          "phone": ""
        }
      ],
      "max_linkage": 10,
      "max_per_user": 1,
      "max_gift_per_user": 0,
      "maximum_allowance": 9999999,
      "merchant_id": "a5b03069dd",
      "merchant_name": "6/21 rel merchant",
      "min_spend": 1,
      "num_left": null,
      "num_qualifying": 5,
      "number_sold": 0,
      "percent_fee": 8,
      "purchase_url": "https://homerun-f2.offerify.com/deal/den-621-rel-merchant-4/checkout",
      "region_id": "denver",
      "region_name": "Denver",
      "robotitle": "15% off purchase",
      "shipping_address_required": false,
      "show_url": "http://homerun-f2.offerify.com/deal/den-621-rel-merchant-4",
      "sold_out": false,
      "start_at": "2013-07-23T06:00:00Z",
      "state": "in-flight",
      "subcategory": "Comedy",
      "subcategory_id": "comedy",
      "supplier_id": "homerun",
      "tags": [
        "Limited-time-only"
      ],
      "title": "test_CLO_CSV_5",
      "type": "card-linked",
      "value": 10000
    }
  ],
  "next_page": "\"https://api.offers.deem.com//api/v3/deals?fields=tags%2Cincentive_percentage%2Crobotitle%2Ccategory%2Ctitle%2Cstate%2Cprice%2Cregion%2Ctype%2Cimages%5Bsmall%2Clarge%5D&filter=lat_long%5B34.0936203%2C-118.377601624%2C5%5D%2Ccategory%5BShopping2%5D&page=2&per_page=100\""
}

Filter deals by the “restaurants” category with no deals returned:

Status: 200 OK
{
  "deals": [

  ],
  "next_page": "\"https://api.offers.deem.com//api/v3/deals?fields=tags%2Cincentive_percentage%2Crobotitle%2Ccategory%2Ctitle%2Cstate%2Cprice%2Cregion%2Ctype%2Cimages%5Bsmall%2Clarge%5D&filter=lat_long%5B34.0936203%2C-118.377601624%2C5%5D%2Ccategory%5BShopping2%5D&page=2&per_page=100\""
}

Error Responses

Responses provided for failed requests:

400

status = “error”
message = “Bad request syntax”
errors = {“query_string”:”fields= isd is not recognised as a valid field for inclusion in this JSON response”}}
Parameter information provided is invalid.

Error Response Examples

Status: 
{
  "status": "error",
  "message": "Bad request syntax",
  "errors": "{\"query_string\":\"fields= isd is not recognized as a valid field for inclusion in this JSON response\"}},"
}
Status: 
{
  "status": "error",
  "message": "Bad request syntax",
  "errors": "{\"query_string\":\"sort= value is not allowed as a sorting option\"}},"
}