Handling FreeGrub Codes

For those partners who we supply with FreeGrub codes, you'll need to implement a way to apply that amount to a diner's cart at order time. You will not be able to generate these codes; just apply codes that we supply to diners.

FreeGrub is a compensatory credit that the Grubhub care team supplies to a customer. They differ from the promotional codes that we send to customers. Those codes are restricted by brand, so cannot be used outside our primary sites.

These codes are single use, so once a diner uses a code on an order, the code cannot be used on another order. The Grubhub API "uses" a code once it has been applied to an order that has been sent for fulfillment.

To allow your diners to take advantage of an existing FreeGrub code, you'll need to a way to apply a code to a cart, then make the following API calls:

1. Trade the code for an entitlement ID.
2. Apply that entitlement ID to the cart as a payment.

Trade a Code for an Entitlement

The code itself does not (and should not) directly apply a credit to a diner's order. Instead, you'll need to retrieve an entitlement ID that you can then apply to a cart.

To get an entitlement, call GET /codes/entitlement/{code_text}. Here's an example of what that looks like:

GET /codes/entitlement/QYL24KF8J9FJ HTTP/1.1
Host: api-gtm.grubhub.com
Authorization: Bearer xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx

You can use the FreeGrub code above to test on pre-production servers. While the above example uses a production URL, it will not work on those servers. Unlike most codes, it can be used multiple times.

This returns the following payload:

{
    "entitlement_id": "dec44bf0-c0cb-11e7-a8e3-114443228a2b",
    "entitlement_type": "PROMO_CODE",
    "code_type": "PROMO_CODE",
    "description": "QA Test %",
    "code_text": "QYL24KF8J9FJ"
}

Apply the Entitlement to a Cart

Now that you have a code, you can apply the associated credit to the diner's current cart. You attach this like you would any other payment, using the /carts/{cart_id}/payments endpoint.

Unlike other payments, you should not include an amount - because FreeGrub codes can only be used once, you should apply the entire amount on a single order. Our cart algorithms will apply the fixed amount or percentage to the order automatically. Any remainder must be covered by another payment method.

The request to apply the entitlement should look something like this:

POST /carts/pWEXkMSeEee5bSscD6CayQ/payments HTTP/1.1
Host: api-gtm.grubhub.com
Authorization: Bearer xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx
Content-Type: application/json

{
    "payment_id": "dec44bf0-c0cb-11e7-a8e3-114443228a2b",
    "type": "PROMO_CODE"
}

On success, you'll get something like:

{
    "id": "SyXPMcSgEeeaLp-wzXuysQ",
    "uri": "/carts/pWEXkMSeEee5bSscD6CayQ/payments/SyXPMcSgEeeaLp-wzXuysQ",
    "already_exists": false
}

However, if the code has already been used, you'll get a 422 Validation error response code and the following payload:

  {
    "message_key": "CODE_MAX_CODE_USAGE_REACHED",
    "property": "payment_id"
  }

Other validation errors include the following message_key values:

• CODE_NOT_FOUND - Code does not exist in our database.
• CODE_MAX_CODE_USAGE_REACHED - Code has been used as many times as allowed, and can no longer be applied to carts.
• CODE_UNAVAILABLE - Code can not be used currently.
• CODE_EXPIRED - The code has expired, and can no longer be applied to carts.
• CODE_ORDER_MIN_NOT_MET - The cart has not yet reached the order minimum required by the code.
• CODE_NOT_COMBINABLE - This code cannot be combined with the codes already applied to the cart.