Deem Offers API Documentation

Quick Start

Deem Offers provides an API for integrating deals with your existing platform and services. Follow these three simple steps to get a fully functional Deem Offers API implementation up and running:

  1. Authentication
  2. Get Deals
  3. Execute Purchases

In order to use the Deem Offers API, you must be an approved Deem Offers partner with access to your Deem Offers Admin site. If you are not a Deem Offers partner, or you can’t log into your Deem Offers Admin site, please contact support.

Step 1: Authentication

To use the Deem Offers API, you must first get your partner API key from your Deem Offers Admin website. Keep this private key secret. You will provide this key with every API call you make. Here is an example of how your requests will look:

GET /v1/deals?api_key={api_key}

To learn more about authentication, see Authentication.

Step 2: Get Deals

The next step after getting your API key is to request available deals to display on your internet surface (your website, your emails, or your mobile app). To get a set of available San Francisco deals with inventory that is not currently sold out, make the following request:

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

This request returns a set of deal resources containing all of the information you need to display deals on your internet surface, including the deal title, availability dates, inventory quantity, purchase limits, images, and additional attributes. The response looks like this:

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
    }
  ],
  "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\""
}

For more information about the Get Deals call, see Get Deals.

Step 3: Execute Purchases

After displaying deals on your internet surfaces, you are ready to execute a purchase for a purchaser. This purchase can be made with one simple call that includes the following: * user information * payment information * deal information * shipping information (if needed)

The purchase request looks like this:

POST /v1/purchases/full.json
{
  "deal_id": "a-50-for-100-worth-of-dining-1",
  "quantity": 1,
  "user": {
    "email": "help@developer.offerengine.com",
    "password": "pass123",
    "password_confirmation": "pass123",
    "first_name": "Hank",
    "last_name": "Rearden"
  },
  "credit_card": {
    "number": "424242424242424",
    "verification_value": 123,
    "month": 1,
    "year": 2014,
    "zip_code": "90210"
  },
  "shipping_address": {
    "address_one": "501 Howard St",
    "address_two": "#2000",
    "postal_code": "94105",
    "city": "San Francisco",
    "state": "CA",
    "country": "US"
  }
}

When the purchase executes successfully, you receive a response similar to this:

Status: 200 OK
{
  "status": "success",
  "purchase": {
    "id": "34063ec2",
    "purchase_id": "34063ec2",
    "deal_type": "daily-deal",
    "deal_id": "la-1024-wsc-hair-studio-01-2",
    "price": 3900,
    "amount": 0,
    "number_bought": 0,
    "payment_state": "charged",
    "fulfillment_state": "fulfilled",
    "created_at": "Fri Dec 16 19:11:15 UTC 2011",
    "user_id": "ABC123",
    "credit_card_id": "2342f8073e",
    "deal": {
      "id": "a-50-for-100-worth-of-dining-1",
      "deal_id": "a-50-for-100-worth-of-dining-1",
      "title": "$50 for $100 worth of Dining",
      "type": "daily-deal",
      "image_url": "deals/generic_medium.gif",
      "image_url_abs": "http://d2x9dz1etb1m98.cloudfront.net/deals/generic_medium.gif"
    },
    "coupons": [
      {
        "id": "a21c5452d8",
        "expires_at": null,
        "created_at": "Fri Dec 16 19:14:55 UTC 2011",
        "qr_code_url": "http://domain/coupon/qr_code/ab231c9e",
        "qr_code": "apaosidnqw4tdsdpqi45jf091835ukdfq3-40695.kfmdg-q09i6m'ldfi8nqk6",
        "state": "valid",
        "redemption_code": null,
        "redeemed_at": null,
        "print_url": "http://domain/coupons/a21c5452d8/print"
      }
    ]
  }
}

For more information about purchasing deals, see Execute Purchases.

Additional Requests

Additional requests – such as getting deals from specific locations or regions, managing user sessions, getting user information, creating targted emails, and getting statistical information – are included with the Deem Offers API. The additional calls are not necessary to provide Deem Offers deals to your customers, but you may find them useful. To learn more about additional requests, see Additional Calls.