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.

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 “Request Parameters” section. For more information about the deal resource, see the “Response” section.

At the very least, you will want to pass location parameters and also set exclude_soldout to “true” when making a Get Deals call.

If you make this call with no set parameters, 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 set exclude_soldout to “true” when making this call.

Request

GET /v1/deals?api_key={api_key}

Request Parameters

You provide the parameters as a JSON file. All parameter fields are optional. As you add a parameter, it is evaluated in a logical AND operation with any other paramaters to filter the results. For example, if the title parameter is set to “burger” and the state parameter is set to “in-flight”, the filtering returns only in-flight deals that have “burger” in the title.

Individual deal detail parameters

slug
Optional String Filter deals by a particular deal slug.
marketplace_slug
Optional String Filter deals by a particular marketplace deal slug.
title
Optional String Filter deals by title with this value (“burger” could return deals with titles “$20 off Bob’s Burgers”, “$10 off Burgermeister”, and so on).

State parameters

state
Optional String Filter deals in this workflow state (“in-flight”, “approved”, “submitted”, “landed”, “in-review”, “rejected”, “paused”, and “deleted”). The “in-flight” state is the most relevant state because it identifies deals currently available for purchase.
show_all
Optional Boolean Show deals in all workflow states (true only).

Category parameters

category
Optional String Filter deals by category with this value (“Foo” could return deals in the category “Food”).
subcategory
Optional String Filter deals by subcategory with this value (“Me” could return deals in the subcategories “Mexican”, “Mediterreanean”, and “Medical - Other”).

Merchant parameters

merchant
Optional String Filter deals by merchant name with this value (“burger” could return deals with merchants named “Bob’s Burger”, “Burgermeister”, and so on).

Price parameters

price_min
Optional Integer Filter the minimum deal price in cents (i.e., 100 equals one dollar).
price_max
Optional Integer Filter the maximum deal price in cents.

Location parameters

region
Optional String Filter deals by region slug, city/state, IP address, or zip code.
latitude
Optional String Filter deals by location (requires an additional longitude parameter).
longitude
Optional String Filter deals by location (requires an additional latitude parameter).
radius
Optional Float Filter deals within a circular radius around the required longitude and latitude values.

User parameters

user
Optional String Filter deals for a specific user (user slug or email address). Required: the scheduling parameter card_links_redeemed must be false, and the location parameter region must be specified.

Source parameters

suppliers
Optional Array Filter deals by supplier (a partner slug or set of comma-separated partner slugs).
vendors
Optional Array Filter deals by vendor (a vendor slug or set of comma-separated vendor slugs).

Inventory parameters

num_left
Optional Integer Filter deals by the quantity of inventory left.
exclude_soldout
Optional Boolean Filter deals that are not sold out (true only).

Scheduling parameters

runs_min
Optional Date Filter the minimum deal run date.
runs_max
Optional Date Filter the maximum deal run date.
card_links_redeemed
Optional Boolean Filter deals that are not card-linked (false only).

Request Example

New user account, new payment card, and a shipping address:

GET /v1/deals?api_key=1234567
{
  "region": "los-angeles",
  "exclude_soldout": "true"
}

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 (success or error)

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
slug
(Deprecated) _String Use id
deal_id
(Deprecated) String Use id
affinity_score
Float A value 0-5 which represents the overall desirability (quality) of the deal
campaign
String The name for tracking a group of deals used in a marketing campaign
category
String Broad deal type
current_price
Integer The current price 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)
ended
Boolean Flagged if the deal has ended
expires_at
Date The date and time that the deal voucher will expire (times are in timezone of deal’s region)
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
image_url
(Deprecated) String Relative URL for an image associated with the purchased deal
image_url_abs
String Absolute URL for an image associated with the purchased deal
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
low_down
(Deprecated) String: Use description1
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_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
offer_construct
String Readable description of the offer incentive(only for card-linked deals)
percent_fee
Integer The percent charged for running the deal (only for card-linked deals)
primary_image
Hash A list of deal images in different sizes. Each image is available in the following sizes: * _103, _135, _180, _198, _222, _300, _306, _316, _372, _400, _498, _640, _660, featured, large, medium, show, thumb, tiny, and xlarge * Each item has a hash with the dimensions and URL.
purchasable_number
Integer The quantity of units available to sell. This combines logic from max_per_user, and num_left
purchase_url
String The URL for deal purchase web page
region_id
String Region (region slug) in which the deal is available
region_name
String Human-readable region name
region_slug
(Deprecated) String Use region_id
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
situation
(Deprecated) String Use description2
soldout
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)
starting_price
(Deprecated) Integer Use current_price
state
String The current workflow state of the deal:
  • submitted - Base deal data has been entered and the deal is not available for purchase.
  • in-review - The deal needs approval to continue in the workflow and is not available for purchase.
  • rejected - The deal failed approval and is not available for purchase.
  • approved - The content is complete and the deal is ready to be run, but not yet available for purchase.
  • in-flight - The deal is available for purchase.
  • paused - The deal’s sale is halted and the deal is not currently available for purchase.
  • cancelled - The deal has been manually canelled and is no longer in flight
  • landed - The run window has passed and the deal is no longer available for purchase.
  • deleted - The deal has been removed.

subcategory
String More specific deal type
supplier_slug
String (Deprecated) Use supplier_id
supplier_id
String The slug for the deal’s sourcing supplier
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

Response Examples

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

Status: 200 OK
{
  "deals": [
    {
      "id": "la-1024-wsc-hair-studio-01-2",
      "slug": "la-1024-wsc-hair-studio-01-2",
      "deal_id": "la-1024-wsc-hair-studio-01-2",
      "affinity_score": null,
      "campaign": null,
      "category": "Activities",
      "category_id": 1,
      "combine_linked_offers": null,
      "current_price": 3900,
      "custom_data": {

      },
      "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",
      "ended": false,
      "expires_at": "2013-12-17T23:59:59-08:00",
      "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",
      "image_url": "/ugassets/deal/images/4/b/84555f69/medium.jpg",
      "image_url_abs": "http://hrugassets-staging.s3.amazonaws.com/ugassets/deal/images/4/b/84555f69/medium.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": {
            "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"
        }
      ],
      "lowdown": "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.",
      "max_linkage": null,
      "max_per_user": 11,
      "max_gift_per_user": 0,
      "maximum_allowance": null,
      "merchant_name": "1024 WSC Hair Studio 01",
      "min_spend": null,
      "num_left": 499,
      "num_qualifying": null,
      "number_sold": 0,
      "offer_construct": "",
      "percent_fee": null,
      "primary_image": {
        "xlarge": {
          "size": "xlarge",
          "dimensions": "(640x640>)",
          "url": "http://hrugassets-staging.s3.amazonaws.com/ugassets/deal/images/4/b/84555f69/xlarge.jpg"
        },
        "large": {
          "size": "large",
          "dimensions": "(520x352)",
          "url": "http://hrugassets-staging.s3.amazonaws.com/ugassets/deal/images/4/b/84555f69/large.jpg"
        },
        "medium": {
          "size": "medium",
          "dimensions": "(390x260)",
          "url": "http://hrugassets-staging.s3.amazonaws.com/ugassets/deal/images/4/b/84555f69/medium.jpg"
        },
        "tiny": {
          "size": "tiny",
          "dimensions": "(81x56)",
          "url": "http://hrugassets-staging.s3.amazonaws.com/ugassets/deal/images/4/b/84555f69/tiny.jpg"
        },
        "_103": {
          "size": "_103",
          "dimensions": "(103x68)",
          "url": "http://hrugassets-staging.s3.amazonaws.com/ugassets/deal/images/4/b/84555f69/_103.jpg"
        },
        "_198": {
          "size": "_198",
          "dimensions": "(198x130)",
          "url": "http://hrugassets-staging.s3.amazonaws.com/ugassets/deal/images/4/b/84555f69/_198.jpg"
        },
        "_222": {
          "size": "_222",
          "dimensions": "(222x148)",
          "url": "http://hrugassets-staging.s3.amazonaws.com/ugassets/deal/images/4/b/84555f69/_222.jpg"
        },
        "_306": {
          "size": "_306",
          "dimensions": "(306x204)",
          "url": "http://hrugassets-staging.s3.amazonaws.com/ugassets/deal/images/4/b/84555f69/_306.jpg"
        },
        "_316": {
          "size": "_316",
          "dimensions": "(316x211)",
          "url": "http://hrugassets-staging.s3.amazonaws.com/ugassets/deal/images/4/b/84555f69/_316.jpg"
        },
        "_372": {
          "size": "_372",
          "dimensions": "(372x246)",
          "url": "http://hrugassets-staging.s3.amazonaws.com/ugassets/deal/images/4/b/84555f69/_372.jpg"
        },
        "_400": {
          "size": "_400",
          "dimensions": "(400x265)",
          "url": "http://hrugassets-staging.s3.amazonaws.com/ugassets/deal/images/4/b/84555f69/_400.jpg"
        },
        "_498": {
          "size": "_498",
          "dimensions": "(498x332)",
          "url": "http://hrugassets-staging.s3.amazonaws.com/ugassets/deal/images/4/b/84555f69/_498.jpg"
        },
        "_640": {
          "size": "_640",
          "dimensions": "(640x426)",
          "url": "http://hrugassets-staging.s3.amazonaws.com/ugassets/deal/images/4/b/84555f69/_640.jpg"
        },
        "_660": {
          "size": "_660",
          "dimensions": "(660x330)",
          "url": "http://hrugassets-staging.s3.amazonaws.com/ugassets/deal/images/4/b/84555f69/_660.jpg"
        },
        "featured": {
          "size": "featured",
          "dimensions": "(548x362)",
          "url": "http://hrugassets-staging.s3.amazonaws.com/ugassets/deal/images/4/b/84555f69/featured.jpg"
        },
        "show": {
          "size": "show",
          "dimensions": "(615x409)",
          "url": "http://hrugassets-staging.s3.amazonaws.com/ugassets/deal/images/4/b/84555f69/show.jpg"
        },
        "thumb": {
          "size": "thumb",
          "dimensions": "(352x236)",
          "url": "http://hrugassets-staging.s3.amazonaws.com/ugassets/deal/images/4/b/84555f69/thumb.jpg"
        }
      },
      "purchasable_number": 11,
      "purchase_url": "https://homerun-f2.offerify.com/deal/la-1024-wsc-hair-studio-01-2/checkout",
      "region_id": "los-angeles",
      "region_name": "Los Angeles",
      "region_slug": "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",
      "situation": "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).",
      "soldout": false,
      "start_at": "2013-10-17T07:00:00Z",
      "starting_price": 3900,
      "state": "in-flight",
      "subcategory": "Bike Rentals",
      "subcategory_id": 18,
      "supplier_slug": "homerun",
      "tags": [
        "Adult",
        "Limited-time-only"
      ],
      "title": "1024 WSC Salon - Other - $39 for $100",
      "type": "daily-deal",
      "value": 10000
    },
    {
      "id": "den-621-rel-merchant-4",
      "slug": "den-621-rel-merchant-4",
      "deal_id": "den-621-rel-merchant-4",
      "affinity_score": null,
      "campaign": null,
      "category": "Activities",
      "category_id": 2,
      "combine_linked_offers": null,
      "current_price": 20,
      "custom_data": {

      },
      "description1": "",
      "description2": "",
      "end_at": "2014-01-01T06:59:59Z",
      "ended": false,
      "expires_at": "2013-11-20T13:25:14-07:00",
      "fine_print": "",
      "fine_print_legalese": "",
      "fixed_fee": null,
      "fulfillment_method": "printed",
      "highlights": null,
      "image_url": "generics/chameleon_medium.gif",
      "image_url_abs": "https://homerun-f2.offerify.com/images/generics/chameleon_medium.gif",
      "incentive_amount": null,
      "incentive_percentage": 15,
      "instructions": "",
      "locations": [
        {
          "address": {
            "region": "Colorado",
            "postal_code": "80234",
            "street": "7072 North Mariposa Court",
            "latitude": 39.923740387,
            "locality": "Westminster",
            "longitude": -105.003417969,
            "country": "United States"
          },
          "hours": "",
          "phone": ""
        }
      ],
      "lowdown": "",
      "max_linkage": 10,
      "max_per_user": 1,
      "max_gift_per_user": 0,
      "maximum_allowance": 9999999,
      "merchant_name": "6/21 rel merchant",
      "min_spend": 1,
      "num_left": null,
      "num_qualifying": 5,
      "number_sold": 0,
      "offer_construct": "15% off purchase",
      "percent_fee": 8,
      "primary_image": {
        "xlarge": {
          "size": "xlarge",
          "dimensions": "(640x640>)",
          "url": "https://homerun-f2.offerify.com/images/generics/chameleon_xlarge.gif"
        },
        "large": {
          "size": "large",
          "dimensions": "(520x352)",
          "url": "https://homerun-f2.offerify.com/images/generics/chameleon_large.gif"
        },
        "medium": {
          "size": "medium",
          "dimensions": "(390x260)",
          "url": "https://homerun-f2.offerify.com/images/generics/chameleon_medium.gif"
        },
        "tiny": {
          "size": "tiny",
          "dimensions": "(81x56)",
          "url": "https://homerun-f2.offerify.com/images/generics/chameleon_tiny.gif"
        },
        "_103": {
          "size": "_103",
          "dimensions": "(103x68)",
          "url": "https://homerun-f2.offerify.com/images/generics/chameleon__103.gif"
        },
        "_198": {
          "size": "_198",
          "dimensions": "(198x130)",
          "url": "https://homerun-f2.offerify.com/images/generics/chameleon__198.gif"
        },
        "_222": {
          "size": "_222",
          "dimensions": "(222x148)",
          "url": "https://homerun-f2.offerify.com/images/generics/chameleon__222.gif"
        },
        "_306": {
          "size": "_306",
          "dimensions": "(306x204)",
          "url": "https://homerun-f2.offerify.com/images/generics/chameleon__306.gif"
        },
        "_316": {
          "size": "_316",
          "dimensions": "(316x211)",
          "url": "https://homerun-f2.offerify.com/images/generics/chameleon__316.gif"
        },
        "_372": {
          "size": "_372",
          "dimensions": "(372x246)",
          "url": "https://homerun-f2.offerify.com/images/generics/chameleon__372.gif"
        },
        "_400": {
          "size": "_400",
          "dimensions": "(400x265)",
          "url": "https://homerun-f2.offerify.com/images/generics/chameleon__400.gif"
        },
        "_498": {
          "size": "_498",
          "dimensions": "(498x332)",
          "url": "https://homerun-f2.offerify.com/images/generics/chameleon__498.gif"
        },
        "_640": {
          "size": "_640",
          "dimensions": "(640x426)",
          "url": "https://homerun-f2.offerify.com/images/generics/chameleon__640.gif"
        },
        "_660": {
          "size": "_660",
          "dimensions": "(660x330)",
          "url": "https://homerun-f2.offerify.com/images/generics/chameleon__660.gif"
        },
        "featured": {
          "size": "featured",
          "dimensions": "(548x362)",
          "url": "https://homerun-f2.offerify.com/images/generics/chameleon_featured.gif"
        },
        "show": {
          "size": "show",
          "dimensions": "(615x409)",
          "url": "https://homerun-f2.offerify.com/images/generics/chameleon_show.gif"
        },
        "thumb": {
          "size": "thumb",
          "dimensions": "(352x236)",
          "url": "https://homerun-f2.offerify.com/images/generics/chameleon_thumb.gif"
        }
      },
      "purchasable_number": 1,
      "purchase_url": "https://homerun-f2.offerify.com/deal/den-621-rel-merchant-4/checkout",
      "region_id": "denver",
      "region_name": "Denver",
      "region_slug": "denver",
      "robotitle": "15% off purchase",
      "shipping_address_required": false,
      "show_url": "http://homerun-f2.offerify.com/deal/den-621-rel-merchant-4",
      "situation": "",
      "soldout": false,
      "start_at": "2013-07-23T06:00:00Z",
      "starting_price": 20,
      "state": "in-flight",
      "subcategory": "Comedy",
      "subcategory_id": 3,
      "supplier_slug": "homerun",
      "tags": [
        "Adult",
        "Limited-time-only"
      ],
      "title": "test_CLO_CSV_5",
      "type": "card-linked",
      "value": 100
    }
  ],
  "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:

404

error_type = “find_failed”
Parameter information provided is invalid.

Error Response Example

Status: 404 Not Found
{
  "status": "error",
  "error_type": "find_failed",
  "error_msg": "Unable to find"
}