GoTab Promo API Dependencies:

URL for GoTab to POST promo events to (e.g. myloyaltyplatform.com/gotab/events).

Authorization header value for your platform to confirm requests are coming from GoTab (optional).

Event Types:

Customer driven, sychronous events: INQUIRE and REDEEM

Asynchronous events: REVERSE

INQUIRE:

The inquire event will be triggered by the customer entering their promo code and hitting submit in the GoTab UI. The inquire event type will have a payload that includes the event_type: INQUIRE. It will also include the promo code entered by the customer as the lookup_value. If there are any items currently in the customers cart that are not paid for it will also include that.

{
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "example_auth_header_123",
    "x-api-key": "null"
  },
  "json": true,
  "body": {
    "tab_data": {
      "tab_id": "14165",
      "tab_uuid": "O2oFAC7fXeYNEWmmOBFZr_4S",
      "location_id": "1019",
      "name": "Austin Michael",
      "spots": null,
      "status": "PENDING",
      "total": 1166,
      "subtotal": 1100,
      "tax": 66,
      "balance_due": 1166,
      "created": "2025-04-01T11:00:53.247Z",
      "orders": [],
      "items": [],
      "adjustments": [],
      "payments": [],
      "customers": {},
      "tab_metadata": null
    },
    "event_type": "INQUIRE",
    "lookup_value": "PROMO_CODE_EXAMPLE",
    "location_id": "1019"
  }
}

In order to indicate that the promo code entered is valid we expect a 200 response with the associated offer:

{
 "loyalty_points": [],
  "offers": [
    {
      "name": "Offer Program Name",
      "offers": [
        {
          "offer_id": "12344",
          "name": "Free Drink",
          "description": "This is good for any free drink",
          "amount": 5,
          "type": "tab_discount",
          "exclusive_offer": false,
          "group_exclusive_offer": false,
          "auto_apply": true,
          "allow_partial_use": false
        }
      ]
    }
  ]
}

This is very similar to how we handle offers via our Loyalty API. The difference here is that we always expect the auto_apply property to be true for an offer associated with a promo code. You can include multiple offers in your response if there are multiple offers associated with a promo code in your system.

In order to indicate that the entered promo code is not valid please respond with a status code 404 and a JSON response that looks like the following. Please note that the message is up to you. If you want to indicate that the customer should take some specific action please do so, but keep it succinct. Mainly, just be aware that any message you include will end up as an alert in our UI.

{
"message": "Uh oh! Looks like this promo code has already been used."
}

For any other error please response with a 400 status code and an appropriate message.

REDEEM:

The REDEEM event type is an event that will be triggered automatically each time there is an INQUIRE event for the Promo API. The request will include the offer_id's that were supplied by your system in the response to the INQUIRE event. The response to the REDEEM event will indicate which selected offers are valid and should be applied as discounts to the customers tab, and which offers may no longer be valid (something may have changed betweetn the INQUIRE and REDEEM events).

Here's an example REDEEM event request:

{
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "",
    "x-api-key": "null"
  },
  "json": true,
  "body": {
    "selected_offers": ["12344"],
    "tab_data": {}, // same structure as other events
    "event_type": "REDEEM",
    "location_id": "1019"
  }
}

GoTab expects back a 200 status code with the below data structure as a response:

{
  "loyalty_points": [],
  "offers": {
    "rejected_offers": [],
    "valid_offers": [
      {
        "offer_id": "12344",
        "name": "Free Drink",
        "description": "This is a free drink offer (five dollars).",
        "amount": 5,
        "type": "tab_discount",
        "exclusive_offer": false,
        "group_exclusive_offer": false,
        "auto_apply": false,
        "allow_partial_use": false
      }
    ]
  }
}

REVERSAL:

The REVERSAL type event is an asynchronous event that will be triggered when an applied offer is voided off a tab or a tab with applied offers is fully refunded. At your discretion, this will serve as a way to make these offers available to applied again.

Here's an example request for a REVERSAL type event request:

{
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "example_auth_header_123",
    "x-api-key": "null"
  },
  "json": true,
  "body": {
    "reversed_offers": ["12344"],
    "event_type": "REVERSAL",
    "location_id": "1019"
  }
}

A 200 response to this will look like this:

{
  "reversal_id": 90909
}

A 4xx response to this request should look like this:

{
  "message": "Offer reversal failed for this reason."
}