Powered by Redocly

Bite API (v2)

Download OpenAPI specification:Download

Introduction

Overview

Bite exposes online ordering functionality through a REST API which third party developers can use to create applications on top of the Bite platform.

Bite Nomenclature

Customers

A Bite "Customer" represents a full end-user account created on Bite's platform. Customers can be created with a Bite password or can be authenticated against a Single Sign-On provider such as Paytronix or Punchh. Bite Customers have the following features:

  • A single set of credentials could be used to create completely different accounts under different brands that Bite works with.
  • Storing credit cards on file so that they could be used for future purchases.
  • Access to the customer's favorite ordered items and recent order history.
  • Storing delivery addresses on file for future purchases.

After creating or authenticating a Bite Customer through the API, a unique authentication token will be returned which can be used to refer to that user from that moment on without the need to store their password in your application.

Usage Basics

Environments

A dedicated sandbox environment will be provisioned for each new third-party developer. All development and testing must be carried out through that environment. It will include both an API sandbox as well as Admin Portal sandbox so that test locations could be modified by the developers for the purposes of testing their integration with Bite. The Sandbox environment runs the same code as production. https://YOUR_SANDBOX_SUB_DOMAIN.getbite.com/api

The production environment endpoint is: [REDACTED]

All communication must be encrypted over TLS 1.2

Request/Response Basics

Headers and Status Codes

https://<environment_domain>/<API_version>/<resource>?[params]

  • Bite API expects both the request and the response bodies to encoded with JSON, so both the HTTP Accept and Content-Type headers should be set to application/json.
  • HTTP Status Codes will be returned as follows:
    • 200 OK - The requested operation completed successfully!
    • 400 Bad Request - An error occurred on the Bite side or on the POS side. Please reference the response body's "code" value in the Bite Error Codes documentation.
    • 403 Forbidden - Invalid API credentials or insufficient access to a resource or operation.
    • 500 Server Error - An unexpected error occurred. Please verify that your request is correctly formatted.
  • Every API call must include the following headers:
    Header
    		 Description Example
    x-md-api-version Must be set to 4 x-md-api-version: 4
    x-bite-org-id Must be set to the brand id that you are working with. This value will be provided along with the sandbox environment. x-bite-org-id: 5fa31dc97acd2f0031e023eb
    x-customer-app-scope Must be set to the brand's account scope. This value will be provided along with the sandbox environment. x-customer-app-scope: my-brand-scope
    Authorization Must be set to Bearer: API_TOKEN. The API_TOKEN will be provided along with the sandbox environment. Authorization: Bearer 2979c798-c901-4ceb-8478-3b26c24a998d
    User-Agent Unique user agent value that identifies the app. Please send this formatted as application_name/version. User-Agent: SomeApp/v1.2.3
    X-Device-Id Unique hardware identifier for the device. X-Device-Id: 993e0082-5bfd-4bbc-98ec-d13b50bbd54a

Response Structure

A success response structure will look as follows:

{
  success: true;
  data?: {...};
}

An error response structure will look as follows:

{
  success: false;
  code: number;
  message?: string;
  data?: {...};
}

Bite Error Codes

Any error response will contain an error code:

Code Meaning Suggested Action
60 Customer Password Already Used: The customer is trying to use a password they have previously used.
61 Customer Token Invalid: The token has been malformed or has expired. Maybe the customer needs to log out and log in again because they've changed their password.
62 Customer Account Not Verified: The customer resource being accessed requires a verified customer account.
63 Customer Account Disabled: The specified customer account has been disabled by one of the brand admins.
64 Customer Account Deleted: The specified customer account has been deleted by one of the brand admins.

Versioning and Compatibility

Please treat all IDs in the API as strings.

We will not remove properties from the current API version, but we do add new properties to return objects from time to time.

There is no guaranteed ordering of properties. We request that properties are accessed by name and not by index.

Please do not rely on error messages for logic. Error text may change periodically. Rather rely on error codes, which are guaranteed to not change.

Rate Limiting

Some API endpoints are protected through the use of rate limiting. The base rate limit can be found in the description of the API endpoint.

Information about the current usage can be found in the headers of the response:

  • Ratelimit-Limit: The amount of requests permitted
  • Ratelimit-Remaining: How many requests can be made in the interval
  • Ratelimit-Reset: How long, in seconds, until the rate-limit interval ends and the remaining amount of requests resets

The rate limit maximum is adjusted by the number of locations associated with the token. For example, if an API has a base rate limit of 50 requests per minute, then an organization with 10 locations may use the API endpoint 500 times per minute.

Changelog

2024-08-29

Added consentedToMarketing field to order

2024-01-22

  • Added section to ordered item schema

2024-01-03

  • More details regarding rate limiting

2023-11-07

  • Deprecated: POST /api/v2/reporting/orders/day
  • New Endpoint: GET /api/v2/reporting/orders/day/:date

2022-12-19

  • Updated rate limits of API calls
  • Reversed order of change log

2022-10-25

  • New endpoints:
    • POST /api/v2/reporting/orders/day
    • GET /api/v2/locations
  • Rate Limiting

2021-10-19

  • First Draft

Account Management

Customer account signup/login and other CRUD operations.

Sign Up for a Customer Account

Creates a new customer account that can be used for storing payment methods, delivery addresses and past orders.

SecurityApiKeySecurityScheme and CustomerAppScopeSecurityScheme
Request
header Parameters
x-md-api-version
required
string
Value: "4"
x-bite-org-id
required
string

The org ID you are working with.

x-bite-order-channel
required
string (OrderChannel)

The order channel you are working with.

Enum: "catering" "flash" "kiosk" "linebuster" "web"
Request Body schema: application/json
required
email
required
string <email> (PropertyEmail)

The email addressed used when the customer signed up for an account. Must a valid RFC email address.

password
required
string <password>

Password to be used to log into the customer account.

firstName
required
string (PropertyFirstName)

The customer's first name.

lastName
required
string (PropertyLastName)

The customer's last name.

phoneNumber
string (PropertyPhoneNumber)

The customer's phone number. Must be a valid phone number under the North American Numbering Plan. Must be formatted as a string of 10 digits.

orderId
string

The id of the order that was just placed by an anonymous guest. If specified, the new customer account will save this order to its order history.

Responses
200

Success!

Response Schema: application/json
message
required
string

A message informing the customer about any next steps, such as having to check their email in order to verify their account.

400

A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.

401

Invalid API credentials.

403

API credentials don't have sufficient access to operation.

500

An unexpected error occurred. Please verify that your request is correctly formatted.

post/v2/customer/signup
Request samples
application/json
{
  • "email": "user@example.com",
  • "password": "pa$$word",
  • "firstName": "string",
  • "lastName": "string",
  • "phoneNumber": "string",
  • "orderId": "string"
}
Response samples
application/json
{
  • "message": "string"
}

Log In to a Customer Account

Logs into an existing customer account.

SecurityApiKeySecurityScheme and CustomerAppScopeSecurityScheme
Request
header Parameters
x-md-api-version
required
string
Value: "4"
x-bite-org-id
required
string

The org ID you are working with.

x-bite-order-channel
required
string (OrderChannel)

The order channel you are working with.

Enum: "catering" "flash" "kiosk" "linebuster" "web"
Request Body schema: application/json
required
email
required
string (PropertyFirstName)

The customer's first name.

password
required
string <password>

The password associated with the customer's account.

Responses
200

Success!

Response Schema: application/json
token
required
string

The auth token that will be used to authenticate the customer going forward as part of the CustomerTokenSecurityScheme.

required
object (Customer)
400

A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.

401

Invalid API credentials.

403

API credentials don't have sufficient access to operation.

500

An unexpected error occurred. Please verify that your request is correctly formatted.

post/v2/customer/login
Request samples
application/json
{
  • "email": "string",
  • "password": "pa$$word"
}
Response samples
application/json
{
  • "token": "string",
  • "customer": {
    }
}

Reset Password

Reset password for an existing customer account identified by the email address. If the customer account is found, an reset password email will be sent so that the user can finish the password reset process. The response from the API is the same regardless of whether the account was found.

SecurityApiKeySecurityScheme and CustomerAppScopeSecurityScheme
Request
header Parameters
x-md-api-version
required
string
Value: "4"
x-bite-org-id
required
string

The org ID you are working with.

x-bite-order-channel
required
string (OrderChannel)

The order channel you are working with.

Enum: "catering" "flash" "kiosk" "linebuster" "web"
Request Body schema: application/json
required
email
required
string <email> (PropertyEmail)

The email addressed used when the customer signed up for an account. Must a valid RFC email address.

Responses
200

Success!

Response Schema: application/json
message
required
string

A message informing the customer about any next steps, such as having to check their email in order to finish the password reset process.

400

A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.

401

Invalid API credentials.

403

API credentials don't have sufficient access to operation.

500

An unexpected error occurred. Please verify that your request is correctly formatted.

post/v2/customer/reset-password
Request samples
application/json
{
  • "email": "user@example.com"
}
Response samples
application/json
{
  • "message": "string"
}

Change Password

Change the password for the specified customer account using one of two ways. Either the resetToken is provided from a password reset email, or the logged in customer provides their current password.

SecurityApiKeySecurityScheme and CustomerAppScopeSecurityScheme
Request
header Parameters
x-md-api-version
required
string
Value: "4"
x-bite-org-id
required
string

The org ID you are working with.

x-bite-order-channel
required
string (OrderChannel)

The order channel you are working with.

Enum: "catering" "flash" "kiosk" "linebuster" "web"
Request Body schema: application/json
required
resetToken
string

A token acquired during the password reset process.

currentPassword
string <password>

The current password used to access the customer account.

newPassword
required
string <password>

The new password to be used for the customer account.

newPasswordRepeat
required
string <password>

The copy of the new password.

Responses
200

Success!

Response Schema: application/json
token
required
string

The auth token that will be used to authenticate the customer going forward. The token issued previously will not be accepted anymore.

400

A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.

401

Invalid API credentials.

403

API credentials don't have sufficient access to operation.

500

An unexpected error occurred. Please verify that your request is correctly formatted.

post/v2/customer/change-password
Request samples
application/json
{
  • "resetToken": "string",
  • "currentPassword": "pa$$word",
  • "newPassword": "pa$$word",
  • "newPasswordRepeat": "pa$$word"
}
Response samples
application/json
{
  • "token": "string"
}

Verify Customer Account

Verify the email associated with the specified customer account.

SecurityApiKeySecurityScheme and CustomerAppScopeSecurityScheme
Request
header Parameters
x-md-api-version
required
string
Value: "4"
x-bite-org-id
required
string

The org ID you are working with.

x-bite-order-channel
required
string (OrderChannel)

The order channel you are working with.

Enum: "catering" "flash" "kiosk" "linebuster" "web"
Request Body schema: application/json
required
verifyToken
required
string

A token acquired during the signup process.

Responses
200

Success!

Response Schema: application/json
message
required
string

A message informing the customer about any next steps.

400

A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.

401

Invalid API credentials.

403

API credentials don't have sufficient access to operation.

500

An unexpected error occurred. Please verify that your request is correctly formatted.

post/v2/customer/verify-account
Request samples
application/json
{
  • "verifyToken": "string"
}
Response samples
application/json
{
  • "message": "string"
}

Get Customer Account

Returns the latest copy of the customer account.

SecurityApiKeySecurityScheme and CustomerAppScopeSecurityScheme and CustomerTokenSecurityScheme
Request
header Parameters
x-md-api-version
required
string
Value: "4"
x-bite-org-id
required
string

The org ID you are working with.

x-bite-order-channel
required
string (OrderChannel)

The order channel you are working with.

Enum: "catering" "flash" "kiosk" "linebuster" "web"
Responses
200

Success!

Response Schema: application/json
required
object (Customer)
400

A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.

401

Invalid API credentials.

403

API credentials don't have sufficient access to operation.

500

An unexpected error occurred. Please verify that your request is correctly formatted.

get/v2/customer
Request samples 
Response samples 
application/json
{
  • "customer": {
    }
}
Update Customer Account
Update some simple fields on the customer account such as name and phone number.


SecurityApiKeySecurityScheme and CustomerAppScopeSecurityScheme and CustomerTokenSecurityScheme 
Request 
header Parameters
x-md-api-version
required
string
 Value: "4"  
x-bite-org-id
required
string
The org ID you are working with.


 
x-bite-order-channel
required
string (OrderChannel) 
The order channel you are working with.


 Enum: "catering" "flash" "kiosk" "linebuster" "web"  
Request Body schema: application/json
required
firstName
string (PropertyFirstName) 
The customer's first name.


 
lastName
string (PropertyLastName) 
The customer's last name.


 
phoneNumber
string (PropertyPhoneNumber) 
The customer's phone number. Must be a valid phone number under the North American Numbering Plan. Must be formatted as a string of 10 digits.


 
Responses 
200
Success!


Response Schema: application/json
required
object (Customer) 
 
400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


put/v2/customer
Request samples 
application/json
{
  • "firstName": "string",
  • "lastName": "string",
  • "phoneNumber": "string"
}
Response samples 
application/json
{
  • "customer": {
    }
}
Delete Customer Account
Deletes the customer account and all associated payment methods, delivery addresses, push tokens, etc.


SecurityApiKeySecurityScheme and CustomerAppScopeSecurityScheme and CustomerTokenSecurityScheme 
Request 
header Parameters
x-md-api-version
required
string
 Value: "4"  
x-bite-org-id
required
string
The org ID you are working with.


 
x-bite-order-channel
required
string (OrderChannel) 
The order channel you are working with.


 Enum: "catering" "flash" "kiosk" "linebuster" "web"  
Responses 
200
Success!


400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


delete/v2/customer
Request samples 
Delivery Addresses
Management of saved delivery addresses on the customer account.


Get Delivery Addresses
Returns the latest copy of all the saved delivery addresses associated with the customer's account.


SecurityApiKeySecurityScheme and CustomerAppScopeSecurityScheme and CustomerTokenSecurityScheme 
Request 
header Parameters
x-md-api-version
required
string
 Value: "4"  
x-bite-org-id
required
string
The org ID you are working with.


 
x-bite-order-channel
required
string (OrderChannel) 
The order channel you are working with.


 Enum: "catering" "flash" "kiosk" "linebuster" "web"  
Responses 
200
Success!


Response Schema: application/json
required
Array of objects (CustomerDeliveryAddress) 
 
400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


get/v2/customer/delivery-addresses
Request samples 
Response samples 
application/json
{
  • "deliveryAddresses": [
    ]
}
Create a New Delivery Address
Creates a new delivery address saved to the customer's account.


SecurityApiKeySecurityScheme and CustomerAppScopeSecurityScheme and CustomerTokenSecurityScheme 
Request 
header Parameters
x-md-api-version
required
string
 Value: "4"  
x-bite-org-id
required
string
The org ID you are working with.


 
x-bite-order-channel
required
string (OrderChannel) 
The order channel you are working with.


 Enum: "catering" "flash" "kiosk" "linebuster" "web"  
Request Body schema: application/json
required
line1
required
string (PropertyLine1) 
 
line2
string (PropertyLine2) 
 
city
required
string (PropertyCity) 
 
state
string (PropertyState) 
 
postalCode
required
string (PropertyPostalCode) 
 
phoneNumber
required
string (customer-delivery-address_PropertyPhoneNumber) 
 
deliveryInstructions
string (PropertyDeliveryInstructions) 
 
nickname
string (PropertyNickname) 
The nickname for the saved delivery address


 
isDefault
boolean
If this value is set to true, then the previously default delivery address on this customer's account will no longer be default.


 
Responses 
200
Success!


Response Schema: application/json
required
object (CustomerDeliveryAddress) 
 
400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


post/v2/customer/delivery-addresses
Request samples 
application/json
{
  • "line1": "string",
  • "line2": "string",
  • "city": "string",
  • "state": "string",
  • "postalCode": "string",
  • "phoneNumber": "string",
  • "deliveryInstructions": "string",
  • "nickname": "string",
  • "isDefault": true
}
Response samples 
application/json
{
  • "deliveryAddress": {
    }
}
Update a Delivery Address
Update some simple fields on the specified delivery address.


SecurityApiKeySecurityScheme and CustomerAppScopeSecurityScheme and CustomerTokenSecurityScheme 
Request 
path Parameters
deliveryAddressId
required
string
The ID of the delivery address that's being worked on.


 
header Parameters
x-md-api-version
required
string
 Value: "4"  
x-bite-org-id
required
string
The org ID you are working with.


 
x-bite-order-channel
required
string (OrderChannel) 
The order channel you are working with.


 Enum: "catering" "flash" "kiosk" "linebuster" "web"  
Request Body schema: application/json
required
line1
string (PropertyLine1) 
 
line2
string (PropertyLine2) 
 
city
string (PropertyCity) 
 
state
string (PropertyState) 
 
postalCode
string (PropertyPostalCode) 
 
phoneNumber
string (customer-delivery-address_PropertyPhoneNumber) 
 
deliveryInstructions
string (PropertyDeliveryInstructions) 
 
nickname
string (PropertyNickname) 
The nickname for the saved delivery address


 
isDefault
boolean
If this value is set to true, then the previously default delivery address on this customer's account will no longer be default.


 
Responses 
200
Success!


Response Schema: application/json
required
object (CustomerDeliveryAddress) 
 
400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


put/v2/customer/delivery-addresses/{deliveryAddressId}
Request samples 
application/json
{
  • "line1": "string",
  • "line2": "string",
  • "city": "string",
  • "state": "string",
  • "postalCode": "string",
  • "phoneNumber": "string",
  • "deliveryInstructions": "string",
  • "nickname": "string",
  • "isDefault": true
}
Response samples 
application/json
{
  • "deliveryAddress": {
    }
}
Delete a Delivery Address
Deletes the specified delivery address from the customer's account.


SecurityApiKeySecurityScheme and CustomerAppScopeSecurityScheme and CustomerTokenSecurityScheme 
Request 
path Parameters
deliveryAddressId
required
string
The ID of the delivery address that's being worked on.


 
header Parameters
x-md-api-version
required
string
 Value: "4"  
x-bite-org-id
required
string
The org ID you are working with.


 
x-bite-order-channel
required
string (OrderChannel) 
The order channel you are working with.


 Enum: "catering" "flash" "kiosk" "linebuster" "web"  
Responses 
200
Success!


400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


delete/v2/customer/delivery-addresses/{deliveryAddressId}
Request samples 
Order History
Past orders associated with the customer account.


Get Recent Orders for a Customer
Returns the most recent 20 orders that the customer has placed through the bite platform.


SecurityApiKeySecurityScheme and CustomerAppScopeSecurityScheme and CustomerTokenSecurityScheme 
Request 
header Parameters
x-md-api-version
required
string
 Value: "4"  
x-bite-org-id
required
string
The org ID you are working with.


 
x-bite-order-channel
required
string (OrderChannel) 
The order channel you are working with.


 Enum: "catering" "flash" "kiosk" "linebuster" "web"  
Responses 
200
Success!


Response Schema: application/json
required
Array of objects
 
400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


get/v2/customer/orders
Request samples 
Response samples 
application/json
{
  • "orders": [
    ]
}
Payment Methods
Management of saved payment methods on the customer account.


Get Payment Methods
Returns the latest copy of all the saved payment methods associated with the customer's account.


SecurityApiKeySecurityScheme and CustomerAppScopeSecurityScheme and CustomerTokenSecurityScheme 
Request 
header Parameters
x-md-api-version
required
string
 Value: "4"  
x-bite-org-id
required
string
The org ID you are working with.


 
x-bite-order-channel
required
string (OrderChannel) 
The order channel you are working with.


 Enum: "catering" "flash" "kiosk" "linebuster" "web"  
Responses 
200
Success!


Response Schema: application/json
required
Array of objects (CustomerPaymentMethod) 
 
400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


get/v2/customer/payment-methods
Request samples 
Response samples 
application/json
{
  • "paymentMethods": [
    ]
}
Update a Payment Method
Update some simple fields on the specified payment method.


SecurityApiKeySecurityScheme and CustomerAppScopeSecurityScheme and CustomerTokenSecurityScheme 
Request 
path Parameters
paymentMethodId
required
string
The ID of the payment method that's being worked on.


 
header Parameters
x-md-api-version
required
string
 Value: "4"  
x-bite-org-id
required
string
The org ID you are working with.


 
x-bite-order-channel
required
string (OrderChannel) 
The order channel you are working with.


 Enum: "catering" "flash" "kiosk" "linebuster" "web"  
Request Body schema: application/json
required
nickname
string (customer-payment-method_PropertyNickname) 
The nickname for the saved payment method


 
isDefault
boolean
If this value is set to true, then the previously default payment method on this customer's account will no longer be default.


 
Responses 
200
Success!


Response Schema: application/json
required
object (CustomerPaymentMethod) 
 
400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


put/v2/customer/payment-methods/{paymentMethodId}
Request samples 
application/json
{
  • "nickname": "string",
  • "isDefault": true
}
Response samples 
application/json
{
  • "paymentMethod": {
    }
}
Delete a Payment Method
Deletes the specified payment method from the customer's account.


SecurityApiKeySecurityScheme and CustomerAppScopeSecurityScheme and CustomerTokenSecurityScheme 
Request 
path Parameters
paymentMethodId
required
string
The ID of the payment method that's being worked on.


 
header Parameters
x-md-api-version
required
string
 Value: "4"  
x-bite-org-id
required
string
The org ID you are working with.


 
x-bite-order-channel
required
string (OrderChannel) 
The order channel you are working with.


 Enum: "catering" "flash" "kiosk" "linebuster" "web"  
Responses 
200
Success!


400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


delete/v2/customer/payment-methods/{paymentMethodId}
Request samples 
Push Tokens
Save mobile app push notification tokens on the customer account.


Save a New Push Token
Saves a new mobile app push notification token to the customer's account.


SecurityApiKeySecurityScheme and CustomerAppScopeSecurityScheme and CustomerTokenSecurityScheme 
Request 
header Parameters
x-md-api-version
required
string
 Value: "4"  
x-bite-org-id
required
string
The org ID you are working with.


 
x-bite-order-channel
required
string (OrderChannel) 
The order channel you are working with.


 Enum: "catering" "flash" "kiosk" "linebuster" "web"  
Request Body schema: application/json
required
token
required
string
A unique token that can be used to send a push notification to the customer's mobile app.
This token has to valid for given notification service that it's meant to be used with.
iOS tokens must be only contain 64 hexadecimal characters.
Android tokens can only contain alpha-numeric characters along with the following special characters: -_:.


 
notificationService
required
string
The service that has to be used to send a push notification to the customer's mobile app.


 Enum: "Android" "iOS"  
urlScheme
required
string
The custom url scheme that the customer's mobile app registered with the OS.


 
Responses 
200
Success!


400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


post/v2/customer/push-tokens
Request samples 
application/json
{
  • "token": "string",
  • "notificationService": "Android",
  • "urlScheme": "string"
}
Pick a Location
Endpoints for picking a location from which to order.


Get All Locations
Returns all the locations that are available to the bearer token.
Requires an API token with the "Locations" or "Reporting" scope.
The base rate limit of an organization with one location is 75 requests per 10 minutes.


SecurityBearerAuthSecurityScheme 
Request 
query Parameters
page
integer <int32>   >= 0 
 
limit
integer <int32>   [ 1 .. 50 ] 
 
header Parameters
x-md-api-version
required
string
 Value: "4"  
Responses 
200
Success!


Response Schema: application/json
success
boolean
 
Array of objects
 
400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


429
Too many requests within too short of a time frame. Refer to response headers.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


get/v2/locations
Request samples 
Response samples 
application/json
{
  • "success": true,
  • "data": [
    ]
}
Search Locations
Returns all the locations that match the search query. If one of the fulfillment methods is delivery, then locations that won't deliver to the specified address will be filtered out of the search results.
You must provide either the address or the lat/long parameters.


SecurityApiKeySecurityScheme 
Request 
query Parameters
fulfillmentMethods
required
Array of integers <int32>  (fulfillment-method_FulfillmentMethod)   non-empty 
The user's chosen fulfillment methods for their order. Only locations that support one of these methods will be returned.


    

  • Web only:
      

    • 20 - In-Store Pickup
      • 

    • 21 - Dine In
      • 

    • 22 - Curbside Pickup
      • 

    • 23 - Outpost
      • 

    • 24 - Delivery
      • 

    

    • 

  • Catering only:
      

    • 30 - In-Store Pickup
      • 

    • 31 - Dine In
      • 

    • 32 - Curbside Pickup
      • 

    • 33 - Outpost
      • 

    • 34 - Delivery
      • 

    

    • 



 
lat
number <float> 
The user's geo-coordinates (latitude). This will be used to find the closest store.


 
long
number <float> 
The user's geo-coordinates (longitude). This will be used to find the closest store.


 
address
string
A Google Maps Places API-formatted address string. This will be used either to find the closest pickup store or as the delivery address, depending on the specified fulfillment method.


 
showDraftLocations
boolean
Set to true if you want to see draft locations in an otherwise live org. This should be only used for testing new locations in a non-prod environment or through a special flag activated on certain users' accounts.


 
page
integer <int32>   >= 0 
 
limit
integer <int32>   [ 1 .. 50 ] 
 
header Parameters
x-md-api-version
required
string
 Value: "4"  
x-bite-org-id
required
string
The org ID you are working with.


 
x-bite-order-channel
required
string (OrderChannel) 
The order channel you are working with.


 Enum: "catering" "flash" "kiosk" "linebuster" "web"  
Responses 
200
Success!


Response Schema: application/json
required
Array of objects
 
400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


get/v2/locations/search
Request samples 
Response samples 
application/json
{
  • "locations": [
    ]
}
Get Future Order Slots
Returns all the future order slots for which a guest could place an order at this location.


SecurityApiKeySecurityScheme 
Request 
path Parameters
locationId
string
The location ID from which delivery is being ordered.


 
query Parameters
fulfillmentMethod
required
integer <int32>  (fulfillment-method_FulfillmentMethod) 
The user's chosen fulfillment methods for their order. Future order slots will be returned for this fulfillment method.


    

  • Web only:
      

    • 20 - In-Store Pickup
      • 

    • 21 - Dine In
      • 

    • 22 - Curbside Pickup
      • 

    • 23 - Outpost
      • 

    • 24 - Delivery
      • 

    

    • 

  • Catering only:
      

    • 30 - In-Store Pickup
      • 

    • 31 - Dine In
      • 

    • 32 - Curbside Pickup
      • 

    • 33 - Outpost
      • 

    • 34 - Delivery
      • 

    

    • 



 
outpostId
string
The ID of the outpost from which the guest wants to pick up the food.


 
orderedItemsLeadTime
integer <int32> 
The lead time that has been calculated for the guest's order purely based on the cart contents. This value is only meant to be provided if the API rejects the order at validation time due to the chosen future order slot being in the past. In that case, the client needs to provide an expected order lead time so slots that are too early won't be shown.
If provided, the API will filter out any time slots by which the order would not be ready.


 
header Parameters
x-md-api-version
required
string
 Value: "4"  
x-bite-org-id
required
string
The org ID you are working with.


 
Responses 
200
Success!


Response Schema: application/json
required
Array of objects
A list of both available and unavailable future order slots grouped by day.


 
400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


get/v2/locations/{locationId}/future-order-slots
Request samples 
Response samples 
application/json
{
  • "futureOrderSlots": [
    ]
}
Validate the Delivery Address at a Location
Checks whether the specified address is within the delivery range of the location.


SecurityApiKeySecurityScheme 
Request 
path Parameters
locationId
string
The location ID from which delivery is being ordered.


 
header Parameters
x-md-api-version
required
string
 Value: "4"  
x-bite-org-id
required
string
The org ID you are working with.


 
Request Body schema: application/json
required
fulfillmentMethod
required
integer <int32>  (fulfillment-method_FulfillmentMethod) 
Fulfillment Method:


    

  • Web only:
      

    • 20 - In-Store Pickup
      • 

    • 21 - Dine In
      • 

    • 22 - Curbside Pickup
      • 

    • 23 - Outpost
      • 

    • 24 - Delivery
      • 

    

    • 

  • Catering only:
      

    • 30 - In-Store Pickup
      • 

    • 31 - Dine In
      • 

    • 32 - Curbside Pickup
      • 

    • 33 - Outpost
      • 

    • 34 - Delivery
      • 

    

    • 



 
required
object (delivery-address_DeliveryAddress) 
 
Responses 
200
Success!


Response Schema: application/json
canDeliver
required
boolean
True if the specified address is within the delivery range of the location; false otherwise.


 
400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


post/v2/locations/{locationId}/validate-delivery-address
Request samples 
application/json
{
  • "fulfillmentMethod": 0,
  • "address": {
    }
}
Response samples 
application/json
{
  • "canDeliver": true
}
Menu
Endpoints for getting the menu


Get Menu
Returns the latest menu for the specified channel, time, fulfillment method, etc.


SecurityBearerAuthSecurityScheme 
Request 
query Parameters
fulfillmentMethod
integer <int32>  (fulfillment-method_FulfillmentMethod) 
The user's chosen fulfillment method for their order.


 
time
integer <int64>  (PickupAt) 
The Unix timestamp for the ready time of a future order. ASAP orders will not have this property. If this is a pickup order, then this will denote the time by which the order is ready to be picked up from the store. If this is a delivery order, then this will denote the time by which the order should be delivered.


 
outpostId
string (OutpostId) 
If this is an outpost pickup order, then outpostId is required.
The ID of the outpost that this order should be delivered to for the guest to pick up.


 
header Parameters
x-md-api-version
required
string
 Value: "4"  
x-bite-org-id
required
string
The org ID you are working with.


 
x-bite-location-id
required
string
The location ID you are working with.


 
Responses 
200
Success!


Response Schema: application/json
required
object (Location) 
 
required
object (Appearance) 
 
required
object (MenuStructure) 
 
required
Array of objects (MenuSection)   non-empty 
 
required
Array of objects (MenuItem)   non-empty 
 
required
Array of objects (ModGroup)   non-empty 
 
Array of objects (Mod)   non-empty 
 
400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


429
Too many requests within too short of a time frame. Refer to response headers.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


get/v2/menu
Request samples 
Response samples 
application/json
{
  • "location": {
    },
  • "appearance": {
    },
  • "menuStructure": {
    },
  • "menuSections": [
    ],
  • "menuItems": [
    ],
  • "modGroups": [
    ],
  • "mods": [
    ]
}
Orders
Endpoints for ordering actions


Create Order
Creates a new order on Bite.


Idempotency can be achieved by providing a clientId property. If an order with the specified clientId already exists at this location on Bite, then the existing order will be returned and no new order will be created.


SecurityBearerAuthSecurityScheme 
Request 
header Parameters
x-md-api-version
required
string
 Value: "4"  
x-bite-location-id
required
string
The location ID you are working with.


 
Request Body schema: application/json
required
required
object
 
object (LoyaltyAuthData) 
Each of the properties below is required by different loyalty integrations that Bite has.
The exact value of this object will be provided in the response from the /v2/orders/loyalty/auth endpoint.


 
Responses 
200
Success!


Response Schema: application/json
required
object (Order) 
 
400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


429
Too many requests within too short of a time frame. Refer to response headers.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


post/v2/orders
Request samples 
application/json
{
  • "order": {
    },
  • "loyaltyAuthData": {
    }
}
Response samples 
application/json
{
  • "order": {
    }
}
Get Order
Returns the latest order data along with its status


SecurityBearerAuthSecurityScheme 
Request 
path Parameters
orderId
required
string
The ID of the order that's being worked on.


 
header Parameters
x-md-api-version
required
string
 Value: "4"  
x-bite-org-id
required
string
The org ID you are working with.


 
x-bite-location-id
required
string
The location ID you are working with.


 
Responses 
200
Success!


Response Schema: application/json
required
object (Order) 
 
orderState
required
string
Current state of this order


 Enum: "unsent" "sending-to-pos" "sent-to-pos" "in-progress" "completed" "cancelled" "delivery-in-progress" "delivered"  
possibleSuccessfulOrderStates
required
Array of strings  non-empty 
All the possible successful states this order could have. For example, each order needs to be sent to the POS, but only delivery orders need to end up at the delivered state.


Items Enum: "sending-to-pos" "sent-to-pos" "in-progress" "completed" "delivery-in-progress" "delivered"  
required
object (StoreInfo) 
 
required
Array of objects (Transaction) 
 
required
Array of objects (Transaction) 
 
400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


429
Too many requests within too short of a time frame. Refer to response headers.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


get/v2/orders/{orderId}
Request samples 
Response samples 
application/json
{
  • "order": {
    },
  • "orderState": "unsent",
  • "possibleSuccessfulOrderStates": [
    ],
  • "location": {
    },
  • "transactions": [
    ],
  • "successfulTransactions": [
    ]
}
Update Order
Updates the current order.
If the order is closed then only the guestSurvey property can be updated.
Returns the updated order.


SecurityBearerAuthSecurityScheme 
Request 
path Parameters
orderId
required
string
The ID of the order that's being worked on.


 
header Parameters
x-md-api-version
required
string
 Value: "4"  
x-bite-location-id
required
string
The location ID you are working with.


 
Request Body schema: application/json
required
required
object
A list of fields that can be updated on the order after it's been created.


 
Responses 
200
Success!


Response Schema: application/json
required
object (Order) 
 
400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


429
Too many requests within too short of a time frame. Refer to response headers.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


put/v2/orders/{orderId}
Request samples 
application/json
{
  • "order": {
    }
}
Response samples 
application/json
{
  • "order": {
    }
}
Validate Order
Validates the order on the POS, checks if any items are 86d, and calculates order totals.
The order must be unclosed, and must not have had any payments applied to it.


SecurityBearerAuthSecurityScheme 
Request 
path Parameters
orderId
required
string
The ID of the order that's being worked on.


 
header Parameters
x-md-api-version
required
string
 Value: "4"  
x-bite-location-id
required
string
The location ID you are working with.


 
Responses 
200
Success!


Response Schema: application/json
queuePath
required
string
This is the endpoint that needs to be polled to check on the status of the order after validation has been requested.


 
400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


429
Too many requests within too short of a time frame. Refer to response headers.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


put/v2/orders/{orderId}/validate
Request samples 
Response samples 
application/json
{
  • "queuePath": "string"
}
Add Coupon
Add a coupon to the current order.
The order must be validated, unclosed, and must not have had any payments applied to it.
Returns the updated order with the new totals that reflect the applied coupon.


SecurityBearerAuthSecurityScheme 
Request 
path Parameters
orderId
required
string
The ID of the order that's being worked on.


 
header Parameters
x-md-api-version
required
string
 Value: "4"  
x-bite-location-id
required
string
The location ID you are working with.


 
Request Body schema: application/json
required
couponCode
required
string
 
Responses 
200
Success!


Response Schema: application/json
required
object (Order) 
 
400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


429
Too many requests within too short of a time frame. Refer to response headers.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


post/v2/orders/{orderId}/coupon
Request samples 
application/json
{
  • "couponCode": "string"
}
Response samples 
application/json
{
  • "order": {
    }
}
Remove Coupon
Removes the applied coupon from the current order.
The order must be validated, unclosed, and must not have had any payments applied to it.
Returns the updated order with the new totals that reflect the removed coupon.


SecurityBearerAuthSecurityScheme 
Request 
path Parameters
orderId
required
string
The ID of the order that's being worked on.


 
header Parameters
x-md-api-version
required
string
 Value: "4"  
x-bite-location-id
required
string
The location ID you are working with.


 
Responses 
200
Success!


Response Schema: application/json
required
object (Order) 
 
400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


429
Too many requests within too short of a time frame. Refer to response headers.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


delete/v2/orders/{orderId}/coupon
Request samples 
Response samples 
application/json
{
  • "order": {
    }
}
Set Tip Amount
Set a tip amount on the current order.
If tipTotal is zeo, then this call will remove any existing tip from the order.
After the tip is applied or removed, the order might be revalidated based on the POS configuration.
The order must be validated, unclosed, and must not have had any payments applied to it.
Returns the updated order with the new totals that reflect the new tip amount.


SecurityBearerAuthSecurityScheme 
Request 
path Parameters
orderId
required
string
The ID of the order that's being worked on.


 
header Parameters
x-md-api-version
required
string
 Value: "4"  
x-bite-location-id
required
string
The location ID you are working with.


 
Request Body schema: application/json
required
required
object
 
Responses 
200
Success!


Response Schema: application/json
required
object (Order) 
 
400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


429
Too many requests within too short of a time frame. Refer to response headers.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


put/v2/orders/{orderId}/tip
Request samples 
application/json
{
  • "order": {
    }
}
Response samples 
application/json
{
  • "order": {
    }
}
Close Order
Closes a fully paid order so that it can be sent to the kitchen for fulfillment.


SecurityBearerAuthSecurityScheme 
Request 
path Parameters
orderId
required
string
The ID of the order that's being worked on.


 
header Parameters
x-md-api-version
required
string
 Value: "4"  
x-bite-location-id
required
string
The location ID you are working with.


 
Request Body schema: application/json
required
object (LoyaltyAuthData) 
Each of the properties below is required by different loyalty integrations that Bite has.
The exact value of this object will be provided in the response from the /v2/orders/loyalty/auth endpoint.


 
Responses 
200
Success!


Response Schema: application/json
required
object (Order) 
 
required
Array of objects (Transaction) 
 
queuePath
string
If provided, this is the endpoint that needs to be polled to check on the status of the order after it has been closed.
The queuePath will be provided if this order is ready to be sent to the POS at close time (e.g. ASAP orders as opposed to future orders).


 
400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


429
Too many requests within too short of a time frame. Refer to response headers.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


put/v2/orders/{orderId}/close
Request samples 
application/json
{
  • "loyaltyAuthData": {
    }
}
Response samples 
application/json
{
  • "order": {
    },
  • "successfulTransactions": [
    ],
  • "queuePath": "string"
}
Send a Receipt for a Customer's Order.
Returns success when it succeeds.


SecurityBearerAuthSecurityScheme and CustomerAppScopeSecurityScheme and CustomerTokenSecurityScheme 
Request 
path Parameters
orderId
required
string
The ID of the order that's being worked on.


 
header Parameters
x-md-api-version
required
string
 Value: "4"  
x-bite-org-id
required
string
The org ID you are working with.


 
Request Body schema: application/json
required
email
required
string <email>  (PropertyEmail) 
The email addressed used when the customer signed up for an account. Must a valid RFC email address.


 
Responses 
200
Success!


400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


429
Too many requests within too short of a time frame. Refer to response headers.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


post/v2/orders/{orderId}/receipt
Request samples 
application/json
{
  • "email": "user@example.com"
}
Mobile App Config
Endpoints for getting the config bundle of a mobile app


Retrieve Mobile App Config Bundle
Returns all the settings necessary for a mobile app to run.
Requires an API token with the "Mobile App" scope.
The base rate limit of an organization with one location is 75 requests per 10 minutes.


SecurityApiKeySecurityScheme 
Request 
header Parameters
x-md-api-version
required
string
 Value: "4"  
Responses 
200
Success!


Response Schema: application/json
orgId
required
string
Org ID that this mobile app will use.


 
orderChannels
required
Array of strings (OrderChannel)   non-empty 
The order channels that the mobile app could place orders for. Currently limited to web.


Items Enum: "catering" "flash" "kiosk" "linebuster" "web"  
fulfillmentMethods
required
Array of integers <int32>  (fulfillment-method_FulfillmentMethod)   non-empty 
The fulfillment methods that the mobile app should offer to the user.


 
Array of objects (HomeScreenImage)   non-empty 
A list of images to be shown on the home screen of the mobile app.


 
object
Contact information that can be used to contact the brand about any issues with the ordering experience.


 
Array of objects (Link)   non-empty 
A list of links to display in the sidebar of the app (e.g. Privacy Policy, Terms of Service).


 
Array of objects (Link)   non-empty 
A list of policy links to display within the app (e.g. Privacy Policy, Terms of Service).


 
Array of objects  non-empty 
A list of links to the brand's social media accounts to display within the app (e.g. Twitter, IG).


 
400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


429
Too many requests within too short of a time frame. Refer to response headers.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


get/v2/mobile-app-config
Request samples 
Response samples 
application/json
{
  • "orgId": "string",
  • "orderChannels": [
    ],
  • "fulfillmentMethods": [
    ],
  • "homeScreenImages": [
    ],
  • "contactUsInfo": {
    },
  • "sidebarLinks": [
    ],
  • "policyLinks": [
    ],
  • "socialMediaLinks": [
    ]
}
Reporting
Endpoints for generating reports


Generate an Orders Report
Returns a report with detailed information about the orders of a given day at a specified location.
Requires an API token with the "Reporting" scope.
The base rate limit of an organization with one location is 75 requests per 10 minutes.


SecurityApiKeySecurityScheme 
Request 
path Parameters
date
required
string
The date of the orders to retrieve in a YYYY-MM-DD format


 
 Example:  2023-07-21
query Parameters
newerThan
string
The order ID of the last order returned in the previous page of results


 
 Example:  newerThan=654b3c2d537fd6b2dab2a2cc
header Parameters
x-md-api-version
required
string
 Value: "4"  
x-bite-location-id
required
string
The location ID you are working with.


 
Responses 
200
Success!


Response Schema: application/json
success
required
boolean
 
required
object
 
400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


429
Too many requests within too short of a time frame. Refer to response headers.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


get/v2/reporting/orders/day/{date}
Request samples 
Response samples 
application/json
{
  • "success": true,
  • "data": {
    }
}
Generate an Orders Report (Deprecated)
This API endpoint is deprecated and will be removed in a future release.
Returns a report with detailed information about the orders of a given day at a specified location.
Requires an API token with the "Reporting" scope.
The base rate limit of an organization with one location is 75 requests per 10 minutes.


SecurityApiKeySecurityScheme 
Request 
header Parameters
x-md-api-version
required
string
 Value: "4"  
Request Body schema: application/json
required
locationId
required
string (PropertyId) 
The Bite ID of the location.


 
date
required
string
The date of the orders to retrieve in a YYYY-MM-DD format


 
page
integer <int32>   >= 0 
 
limit
integer <int32>   [ 1 .. 50 ] 
 
Responses 
200
Success!


Response Schema: application/json
success
required
boolean
 
required
Array of objects (OrderExternalFirstParty) 
 
400
A Bite error occurred. Please reference the response body's "code" value in the Bite Error Codes documentation.


401
Invalid API credentials.


403
API credentials don't have sufficient access to operation.


429
Too many requests within too short of a time frame. Refer to response headers.


500
An unexpected error occurred. Please verify that your request is correctly formatted.


post/v2/reporting/orders/day
Request samples 
application/json
{
  • "locationId": "0123456789abcdef01234567",
  • "date": "2023-07-21",
  • "page": 1,
  • "limit": 25
}
Response samples 
application/json
{
  • "success": true,
  • "data": [
    ]
}
Webhooks
Webhooks can be used to notify non-Bite systems of events happening at Bite.
They can be configured by Bite employees at the organization level.
They use pre-defined location groups to determine which locations the webhooks are active at.


Webhook Request Body
The webhook request body is composed of these top-level properties:


    

  • event: A key indicating which event triggered this webhook to be sent.
    • 

  • data: The payload of the webhook. This field may not exist if the webhook has no payload.
    • 



Bite Signatures
Bite Webhooks are sent with a signature in the x-bite-signature header that allow you to verify
that the request was sent by Bite.


The x-bite-signature header is composed of two parts, the timestamp and the signature.
The timestamp (prefixed by t=) is the epoch time when the webhook was sent from the Bite server.
The signature (prefixed by v=) is the hex encoded HMAC SHA256 hash of the webhook.


Here is an example of a x-bite-signature header:


t=1650064620000,v=cbb9af052e4e9bfe061e3fa76aadf047b022e6d189a73f047181ea7d0c40f51b



The timestamp value can be used to determine when the request was sent and ignore any old requests
which may be part of a replay attack.


Verify Signature
To verify the signature, you will need the private key associated with the webhook.
This will be provided by a Bite employee after the webhook is configured.


    

  1. Extract the timestamp and signature values from the header. Do not include the prefix.
    

    2. 

  2. Construct the payload to sign following this schematic:
{{timestamp}}.{{request_body}}
    

    ex:
Consider a webhook with a x-bite-signature header of t=1650064620000,v=... and the following
request body:
    

    { event: 'order-sent', data: { someKey: 'Some Value' } }

    

    The resulting payload will be:
    

    1650064620000.{ event: 'order-sent', data: { someKey: 'Some Value' } }

    

    3. 

  3. Calculate the HMAC of the payload with the SHA256 hash function using the private key of the
webhook.
    

    4. 

  4. Compare the HMAC you calculated with the signature extracted from the x-bite-signature header.
Ensure that the values are identical to verify that the request was generated by a Bite server.
    

    5. 



Order SentWebhook 
Returns details of an order immediately after the order has closed and been sent to the POS integrations.
If the location does not have any POS integrations, the webhooks will still send a response after the order is closed.
At the discretion of the organization, this webhook can be configured to include item and transaction data.


Request 
Request Body schema: application/json
event
required
string
 Value: "order-sent"  
required
object (OrderExternal) 
 
Responses 
200
Indicate that the webhook was received successfully.


Request samples 
application/json
{
  • "event": "order-sent",
  • "data": {
    }
}
Order UpdatedWebhook 
Returns details of an existing order immediately after they have been modified.
This webhook is not sent on creation of the order.
At the discretion of the organization, this webhook can be configured to include item and transaction data.


Request 
Request Body schema: application/json
event
required
string
 Value: "order-updated"  
required
object (OrderExternal) 
 
Responses 
200
Indicate that the webhook was received successfully.


Request samples 
application/json
{
  • "event": "order-updated",
  • "data": {
    }
}
Embedding Bite in a 3rd Party Mobile App
Overview
It's possible for customers to embed the Bite ordering experience in their own proprietary mobile app. The intended use-case is to offer a seamless food ordering experience as part of a bigger application that does not require the user to leave the mobile app to go to a browser on their phone.


One critical integration that makes this feature attractive is the ability to preload a Bite website with the user information that is already available to the mobile app. This can be some information about the user such as their name or loyalty card number. Alternatively, this could be a set of methods of payment. Bite will make use of that information and the ordering experience will appear as if the guest has logged in on Bite.


Session Info Schema
version must be always set to 2


loyaltyAuthValues are used to authenticate the guest into the loyalty program


cards are used to pass in any possible saved payment methods


validAt is a unix timestamp (in ms) that represents the time at which the token was generated by the mobile app


{
  version: 2,
  loyaltyAuthValues: {
    method: 'auth-token' | 'card-number';
    value: string;
  }[];
  cards: {
    cardNumber: string;
    cardName: string;
  }[];
  validAt: number
}



Session Token Generation
The session token is an encrypted representation of the session info that can be safely passed in a query string parameter of a Bite web ordering url.
Generation steps:


    

  1. Construct the SessionInfo object as described above.
    2. 

  2. Set validAt to be the current time (as a unix timestamp in milliseconds). For security purposes, the sessionToken must include the timestamp at which it was generated so Bite could verify that it was generated within 15 seconds of receiving the request. The purpose of this measure is to avoid replay attacks.
    3. 

  3. Stringify it.
    4. 

  4. Encrypt the resulting string with the secret key using the AES-256-ECB algorithm.
    5. 

  5. Encode the resulting string with base64.
    6. 



Method of Use
    

  1. The customer and Bite will exchange a secret key that will be used to encrypt the session info object.
    2. 

  2. When a user of the mobile app clicks on a button or link that is meant to directly lead to the Bite ordering website in a WebView, the mobile app has to build the session info object, generate it (as described above), and include it in the sessionToken query string parameter when loading the Bite ordering website (e.g. https://order.yourdomain.com/location123?sessionToken=XXX).
    3. 

  3. Bite servers will then decrypt the token into the session, verify that it is recent, and securely pass the session info to the front end so that it could authenticate the guest into the loyalty program or show saved payment methods.
    4.