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": "[email protected]",
"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": ""
}
]
}
| Attribute | Type | Description |
|---|---|---|
| event_type | string | Type of event that triggered this webhook call. In this case, always pricecheck |
| restaurant_id | string | The ID of the restaurant |
| table_id | string | The ID of the guest's table (tables are also called "Location Codes" or "Delivery Locations" in the Bbot UI) |
| fulfillment_method | string | The fulfillment method of the order. One of [patron_pickup, server_delivery, runner_with_cc, robot_delivery, driver_delivery, runner_nofeedback, pickup_nofeedback, catering] |
| checkout_id | string | The ID of this checkout session for this user. It persists until the checkout is finally successful. |
| cart_items_pretax_cents_this_restaurant | int | The total pretax amount of the checkout for this restaurant |
| cart_items_this_restaurant | List:CartItem | A JSON of the items in the checkout for this restaurant |
| cart_items_other_restaurants | List:CartItem | A JSON of the items in this checkout for other restaurants also associated with the Partner (you) |
| prompts_to_guest | List:Prompt | The full list of prompts_to_guest that was given to us previously by all Partners associated with the checkout, including any customer responses |
| guest_id | string | Unique 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_email | string | Email address of the guest, if available |
| guest_email_is_verified | boolean | Whether we have verified the email address of the guest to be valid. Currently always false. |
| guest_phone | string | Phone number of the guest, if available |
| guest_phone_is_verified | boolean | Whether 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_itemsis 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,
}
]
}
Prompt Object
| Attribute | Type | Description |
|---|---|---|
| prompt_type | string | The type of prompt; label, textinput, multiselect_group or applybutton |
| prompt_id | string | The ID of the prompt. Must be unique amongst all prompts, not just yours. |
| text | string | The text of the prompt. Is only used for prompt_type label. |
| size | string | The size of the prompt. Is only used for prompt_type label. |
| value | string | The placeholder of the prompt. Is only used for prompt_type textinput. |
| heading | string | The heading of the prompt. Is only used for prompt_type textinput. |
| buttontext | string | The text of the prompt. Is only used for prompt_type applybutton. |
| min_selectable | int | The minimum number of choices that must be selected. Is only used for multiselect_group. |
| max_selectable | int | The maximum number of choices that must be selected. Is only used for multiselect_group. |
| choices | List:Choice | The 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
| Attribute | Type | Description |
|---|---|---|
| selected | boolean | Whether or not a choice is selected. |
| contents | string | The label for the choice |
Discount Object
| Attribute | Type | Description |
|---|---|---|
| total_cents_to_add | int | Total amount of the discount to be added. Must be negative. |
| name_for_guest | string | Name of the discount to be displayed to the guest during checkout |
| distribution_among_line_items | List:DiscountDistribution | How the discount is to be distributed among items in the cart. Optional. |
DiscountDistribution Object
| Attribute | Type | Description |
|---|---|---|
| cents_to_add | int | Amount 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_id | string | ID 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
}
]
}
]
})