API Reference
Start typing to search…

Promo Webhook

A webhook for partners to add promos

This webhook is used to receive information about checkouts of restaurants with you listed as a Partner, and for you to provide promo discounts.

You can set your webhook URL in Bbot Owner's Panel -> Manage API Access -> Promo Webhook URL

Example Payload

{
  "event_type": "pricecheck",
  "restaurant_id": "ecde3351-606c-4971-ab5a-792bccb0e5e2",
  "table_id": "b8032110-6bb9-4d7f-b875-75f8da64e356",
  "fulfillment_method": "driver_delivery",
  "checkout_id": "df744d21-0a6b-444d-9f0b-39c9506af848",
  "cart_items_pretax_cents_this_restaurant": 3582,
  "guest_id": "test@test.com", 
  "guest_email_is_verified": false,
  "guest_phone": "5555555555",
  "guest_phone_is_verified": false,
  "cart_items_this_restaurant": [
    {
      "mods": [
        {
          "mods": [],
          "menuItemId": "b80330d7-9abd-40f9-8c88-b006d4308267",
          "name_for_owner": "Èclairs",
          "sku": "",
          "pretax_cents": 92,
          "tax_cents": 8,
          "menu_item_class": "addon",
          "tags": [],
          "report_category": "other"
        }
      ],
      "menuItemId": "b80328d4-d5ff-4676-a224-22e7014a0d14",
      "name_for_owner": "Ceviche",
      "sku": "",
      "pretax_cents": 1102,
      "tax_cents": 98,
      "menu_item_class": "food",
      "tags": [],
      "report_category": "food",
      "line_item_id": "38654715",
      "qty": 3
    }
  ],
  "cart_items_other_restaurants": [],
  "prompts_to_guest": [
    {
      "prompt_id": "example_bbot_0",
      "prompt_type": "label",
      "text": "This is a label",
      "size": ""
    }
  ]
}
AttributeTypeDescription
event_typestringType of event that triggered this webhook call. In this case, always pricecheck
restaurant_idstringThe ID of the restaurant
table_idstringThe ID of the guest's table (tables are also called "Location Codes" or "Delivery Locations" in the Bbot UI)
fulfillment_methodstringThe fulfillment method of the order. One of [patron_pickup, server_delivery, runner_with_cc, robot_delivery, driver_delivery, runner_nofeedback, pickup_nofeedback, catering]
checkout_idstringThe ID of this checkout session for this user. It persists until the checkout is finally successful.
cart_items_pretax_cents_this_restaurantintThe total pretax amount of the checkout for this restaurant
cart_items_this_restaurantList:CartItemA JSON of the items in the checkout for this restaurant
cart_items_other_restaurantsList:CartItemA JSON of the items in this checkout for other restaurants also associated with the Partner (you)
prompts_to_guestList:PromptThe full list of prompts_to_guest that was given to us previously by all Partners associated with the checkout, including any customer responses
guest_idstringUnique ID of the guest in Bbot's system. For anonymous users, this represents a browser session. For logged-in users, it represents an email address.
guest_emailstringEmail address of the guest, if available
guest_email_is_verifiedbooleanWhether we have verified the email address of the guest to be valid. Currently always false.
guest_phonestringPhone number of the guest, if available
guest_phone_is_verifiedbooleanWhether we have verified the phone number of the guest to be valid. Currently always false.

Each Partner’s webhook url must respond with a set of prompts for the guest, and/or a set of discounts. Currently only one discount is allowed. If a textinput prompt is provided, but no applybutton is provided, then an applybutton will be added.

📘

Note about refunds

In Bbot, discounts are always distributed among individual items, with the effect of changing the item’s final purchase price. If a discounted item is refunded, discount on other items in the order will not be affected.

Response to Bbot

📘

Note about discounts

If distribution_among_line_items is not provided, Bbot will automatically distribute the discount among all items, weighted by the items' pretax price. You can spread a $5 discount among items, but negative discount is not currently supported.

If you are tracking a gift card balance and want to add funds back onto it when a gift card purchase is refunded, then the individual items of the purchase must be tracked via our refunds webhook.

Example Response to Bbot

{
  "prompts_to_guest": [
    {
      "prompt_id": "example_bbot_0",
      "prompt_type": "label",
      "text": "This is a label",
      "size": ""
    },
    {
      "prompt_id": "example_bbot_1",
      "prompt_type": "textinput",
      "heading": "",
      "value": ""
    }
  ],
  "discounts": [
    {
      "name_for_guest": "Just Because Discount",
      "total_cents_to_add": -100,
    }
  ]
}
AttributeTypeDescription
prompts_to_guestList:PromptPrompts to be displayed to the guest during checkout
discountsList:DiscountDiscounts to be included in the checkout

Prompt Object

AttributeTypeDescription
prompt_typestringThe type of prompt; label, textinput, multiselect_group or applybutton
prompt_idstringThe ID of the prompt. Must be unique amongst all prompts, not just yours.
textstringThe text of the prompt. Is only used for prompt_type label.
sizestringThe size of the prompt. Is only used for prompt_type label.
valuestringThe placeholder of the prompt. Is only used for prompt_type textinput.
headingstringThe heading of the prompt. Is only used for prompt_type textinput.
buttontextstringThe text of the prompt. Is only used for prompt_type applybutton.
min_selectableintThe minimum number of choices that must be selected. Is only used for multiselect_group.
max_selectableintThe maximum number of choices that must be selected. Is only used for multiselect_group.
choicesList:ChoiceThe choices that may be selected. Is only used for multiselect_group. Note: If min_selectable and max_selectable are both 1, the choices appear as a radio group, otherwise they appear as checkboxes

Choice Object

AttributeTypeDescription
selectedbooleanWhether or not a choice is selected.
contentsstringThe label for the choice

Discount Object

AttributeTypeDescription
total_cents_to_addintTotal amount of the discount to be added. Must be negative.
name_for_gueststringName of the discount to be displayed to the guest during checkout
distribution_among_line_itemsList:DiscountDistributionHow the discount is to be distributed among items in the cart. Optional.

DiscountDistribution Object

AttributeTypeDescription
cents_to_addintAmount of the discount to be added to this particular line item. Sum of all cents_to_add must add up to total_cents_to_add. Must be negative.
line_item_idstringID of the item to be discounted.

Example in Python

@api_view(['POST'])
def fakePartnerPromoWebhook(request):
  payload = request.data
  prompts_to_guest = json.loads(payload.get('prompts_to_guest'))
  prompt_response = list(filter(lambda prompt: prompt['prompt_id'] == 'bbot_1', prompts_to_guest))
  if (not prompt_response) or (prompt_response[0]['value'] != '4' if prompt_response[0]['prompt_type'] == 'textinput' else prompt_response[0]['text'] != 'Bbot Promo Applied'):
    return JsonResponse({
      'prompts_to_guest': [
        {
          'prompt_id':   'bbot_0',
          'prompt_type': 'label',
          'text':        'What is 2+2?',
          'size':        ''
        },
        {
          'prompt_id':   'bbot_1',
          'prompt_type': 'textinput',
          'heading':     '',
          'value':       ''
        }
      ],
      'discounts': None
    })
  else:
    return JsonResponse({
      'prompts_to_guest': [
        {
          'prompt_id':   'bbot_1',
          'prompt_type': 'label',
          'text':        'Bbot Promo Applied',
          'size':        '',
        }
      ],
      'discounts': [
        {
          'name_for_guest': 'Good at Math Discount',
          'total_cents_to_add': -100,
          'distribution_among_line_items': [
            {
              'line_item_id': 'b6bf90d5-9376-4143-a822-12ae1bbee68d',
              'cents_to_add': -100
            }
          ]
        }
      ]
    })

Updated over 3 years ago

Updated over 3 years ago