Using Coupons

Some restaurants may offer diners discounts or free items for ordering a certain value of food. Coupon information appears in multiple areas, depending on what stage of the ordering process the diner is in.

The lifecycle of a coupon looks like this:

• A diner finds a restaurant with once or more coupons.
• They order from that restaurant. If their order meets the minimum amount, then the discount applies to their order.
• Depending on the coupon type, either the cart reflects the discount or the restaurant is informed of the free item to provide.

This article will help you implement coupons in your ordering system, including how to tell what restaurants offer coupons, the types of coupons you'll find, how to attach them to a cart, and how to parse the coupon once it's part of a cart or order.

Finding Restaurants with Coupons

To find out if a restaurant offers a coupon, get restaurant information, then check for this value:

restaurant.has_coupons = true

If has_coupons is true, then you can find the coupons available in the restaurant_coupons array, which, like has_coupons is part of the restaurant object.

Types of Coupons

You'll find three different types of coupons in the restaurant_coupons array: flat discount, percentage discount, and free item.

Note that the example JSON objects are part of a larger response payload. For this article, we have removed the portion of the response not relevant to coupons.

Flat discount

Flat discount coupons provide an absolute dollar amount off of an order once it passes a cart minimum. In the API data, that translates to the cart subtracting restaurant.restaurant_coupons.amount.amount from the cart's diner_grand_total once the diner_subtotal exceeds restaurant.restaurant_coupons.minimum_cart_total.amount.

Here's an example of what this type of coupon looks like:

"restaurant_coupons":[  
         {  
            "id":"29076",
            "description":"When you spend $35 or more you will receive $5 off ",
            "amount":{  
               "amount":500,
               "currency":"USD"
            },
            "minimum_cart_total":{  
               "amount":3500,
               "currency":"USD"
            },
            "sequence":1,
            "combinable":false
         }
      ]

Percentage discount:

Percentage discount coupons reduce the diner's bill by a percentage amount off of an order once it passes a cart minimum. In the API data, that translates to the cart reducing the cart's diner_subtotal by restaurant.restaurant_coupons.percent once the diner_subtotal exceeds restaurant.restaurant_coupons.minimum_cart_total.amount.

You'll notice that this is similar to the flat discount coupon type, except that the discount is calculated on each cart subtotal (before fees, taxes, and tip) instead of being the same for every order.

Here's an example of what this type of coupon looks like:

"restaurant_coupons":[  
         {  
            "id":"37303",
            "description":"10% off any order over $10 ",
            "amount":{  
               "amount":0,
               "currency":"USD"
            },
            "percent":10,
            "minimum_cart_total":{  
               "amount":1000,
               "currency":"USD"
            },
            "sequence":1,
            "combinable":false
         }
      ]

Free item:

The free item coupon type gives diners something free after their cart passes a minimum amount. The API data doesn't give much information, just the minimum_cart_total needed to activate the coupon.

Once the coupon is activated, though, the item will not be added to the cart as a cart line. The restaurant will receive notification of the coupon. However, the data will not indicate which item will be included, just the description of the coupon.

Here's an example of what this type of coupon looks like:

"restaurant_coupons":[  
         {  
            "id":"30845",
            "description":" Purchase over $41 and receive a free dessert.",
            "amount":{  
               "amount":0,
               "currency":"USD"
            },
            "minimum_cart_total":{  
               "amount":4100,
               "currency":"USD"
            },
            "sequence":1,
            "combinable":false
         }
      ]

Applying Coupons to Carts

Once a diner qualifies for a specific coupon - their subtotal passes the cart minimum - you will need to apply the coupon to the cart. Note that, in our interfaces, we require the diner to actively apply the coupon; you can have the coupon apply automatically.

To apply a coupon, you need to call POST /carts/{cart_id}/coupons with the ID of the coupon that you want to apply and the ID of the restaurant to which it belongs.

Here's what that looks like:

POST /carts/OEEFAPu_Eee4V1ns-D6MfQ/coupons HTTP/1.1
Host: api-gtm.grubhub.com
Authorization: Bearer xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx
Content-Type: application/json

{
    "coupon_id":"13012",
    "restaurant_id":"262773"
}

This request will return a payload that looks like this:

{  
   "id":"hg_7oPu7EeetR8Mg9F3lmQ",
   "uri":"/carts/ZM8awfu7Eeeu2pdbc-tN2A/coupons/hg_7oPu7EeetR8Mg9F3lmQ",
   "already_exists":false
}

You can use GET or DELETE request methods on the uri value to retrieve coupon information or remove the coupon from the cart, respectively.

Locating Coupons on Carts and Orders

Once a coupon has been applied, it will show up in the cart and order data. Even though these use separate endpoints to retrieve information, they display the coupon information in the same format.

To find a coupon in cart data (as returned from GET /carts/{cart_id}), check the values in the array at carts.charges.coupons.

To find a coupon in the data for a completed order (as returned from GET /diners/{diner_id}/orders), check the values in the orders[n].charges.coupons array.

That array will look something like this:

"coupons":[  
         {  
            "id":"K_DlMPxqEeeiyJe7QBwjFQ",
            "coupon_id":"13012",
            "description":"Receive a free Vegetable Samosa with any order of $30 or more.",
            "amount":0,
            "restaurant_id":"262773",
            "minimum_amount":3000
         }
      ]