Deem Offers API Documentation

Purchases

Get a purchase

This request retrieves a specific purchase object. It returns a representation of a specific purchase transaction and associated information.

Request

GET /purchases/<purchase_id>?api_key=<api_key>

Parameters

None

Request Example

GET /purchases/34063ec2.json?api_key=1234567

Response

Parameters

status
String State of this purchase (“success” or error type)
purchase_id
String Unique identifier for this purchase
deal_id
String Unique identifier for deal purchased
user_id
String Unique identifier for purchasing user
credit_card_id
String Unique identifier for credit card used to make this purchase

coupons

id
String Unique identifier for this purchase voucher
slug
String Unique identifier for this purchase voucher
deal_id
String Unique identifier for deal purchased
deal_type
String Type of deal purchased (<possible results>)
barcode
String Unique barcode used for purchase redemption
redemption_code
String Unique code used for purchase redemption
expires_at
String Date and time of purchase voucher expiration
created_at
String Date and time purchase was made
state
String State of the purchase (<possible results>)
qrcode_url
String URL for the qrcode image associated with the coupon
qrcode_base64
String Base64 encoded qrcode image associated with the coupon
redeemed_at
Optional String Date and time when purchase voucher was redeemed

Response Example

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

Create a purchase

This request creates a purchase for an existing user with a stored payment card. This operation will execute a purchase transaction for an existing user that already has a stored payment card.

POST /purchases

Parameters

deal_id
String ID of the deal for which you are purchasing inventory
quantity
Integer The number of deals you are purchasing for this purchase
user_id
String ID of the user who is making the purchase
credit_card_id
String ID of the payment card for which you are purchasing inventory
expected_price_per_unit
Integer The expected price
session_id (optional)
String The session ID that is associated with an affiliate

Response

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": null
  }
}

Reserve a purchase

Temporarily reserve inventory (for five minutes) for a purchase in order to process payment transactions. If the transaction succeeds, you would perform a checkout; otherwise, you would return the inventory.

POST /purchases/reserve

Parameters

deal_id
String ID of the deal for which you are reserving inventory
num_bought
Integer The number of deals you are reserving for this purchase

Response

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": "pending",
    "fulfillment_state": "reserved",
    "created_at": "Fri Dec 16 19:11:15 UTC 2011",
    "user_id": null,
    "credit_card_id": null,
    "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": [

    ]
  }
}

Claim a purchase

After inventory has been reserved for a purchase and payment processing is successful, you would use this requent with your reservation token (the response from the reserve call) to create a purchase record from your reservation – if the reservation is valid. If the reservation is invalid or expired, we will still attempt to create a purchase record; however, succes is not guaranteed because the deal might be sold out.

PUT /purchases/:purchase_id/claim

Parameters

user_id
String ID of the user for which you are reserving inventory

Response

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

Release a reserved purchase

If you have reserved inventory for a purchase but the payment processing failed, use this request to release the inventory of the purchase.

PUT /purchases/:purchase_id/release

Response

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": "pending",
    "fulfillment_state": "released",
    "created_at": "Fri Dec 16 19:11:15 UTC 2011",
    "user_id": null,
    "credit_card_id": null,
    "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": [

    ]
  }
}