# Bite API

# 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](#section/Usage-Basics/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:
  | <div style="width:125px">Header</div> | 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

**2026-02-24**

- Updated definitions of openingHoursByFulfillmentMethod

**2025-07-23**

- Updated security for Bite API Token based requests

**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


Version: v2

## Servers

Sandbox
```
https://{sandboxApiSubDomain}.getbite.com/api
```

Variables:
- `sandboxApiSubDomain`: The sandbox subdomain that is provided for each integration partner.
Default: "YOUR_SANDBOX_SUB_DOMAIN"

## Security

### ApiKeySecurityScheme

This key will be provided to you when your sandbox is provisioned.

Type: apiKey
In: header
Name: x-bite-public-key

### BearerAuthSecurityScheme

This key will be provided to you when your sandbox is provisioned.

Type: http
Scheme: bearer

### BearerAuthApiTokenSecurityScheme

This token will be provided to you by Bite.

Type: http
Scheme: bearer

### CustomerAppScopeSecurityScheme

This key will be provided to you when your sandbox is provisioned.

Type: apiKey
In: header
Name: x-customer-app-scope

### CustomerTokenSecurityScheme

This token is returned by the Customer API upon a [successful login](#operation/CustomerLogin) or [change of password](#operation/CustomerChangePassword).

Type: apiKey
In: header
Name: x-customer-token

## Download OpenAPI description

[Bite API](https://documentation.getbite.com/_bundle/openapi/v2/bite-api-v2.yaml)

## Account Management

Customer account signup/login and other CRUD operations.

### Sign Up for a Customer Account

 - [POST /v2/customer/signup](https://documentation.getbite.com/openapi/v2/bite-api-v2/customeraccountmanagement/customersignup.md): Creates a new customer account that can be used for storing payment methods, delivery addresses and past orders.

### Log In to a Customer Account

 - [POST /v2/customer/login](https://documentation.getbite.com/openapi/v2/bite-api-v2/customeraccountmanagement/customerlogin.md): Logs into an existing customer account.

### Reset Password

 - [POST /v2/customer/reset-password](https://documentation.getbite.com/openapi/v2/bite-api-v2/customeraccountmanagement/customerresetpassword.md): 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.

### Change Password

 - [POST /v2/customer/change-password](https://documentation.getbite.com/openapi/v2/bite-api-v2/customeraccountmanagement/customerchangepassword.md): 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.

### Verify Customer Account

 - [POST /v2/customer/verify-account](https://documentation.getbite.com/openapi/v2/bite-api-v2/customeraccountmanagement/customerverifyaccount.md): Verify the email associated with the specified customer account.

### Get Customer Account

 - [GET /v2/customer](https://documentation.getbite.com/openapi/v2/bite-api-v2/customeraccountmanagement/customergetaccount.md): Returns the latest copy of the customer account.

### Update Customer Account

 - [PUT /v2/customer](https://documentation.getbite.com/openapi/v2/bite-api-v2/customeraccountmanagement/customerupdateaccount.md): Update some simple fields on the customer account such as name and phone number.

### Delete Customer Account

 - [DELETE /v2/customer](https://documentation.getbite.com/openapi/v2/bite-api-v2/customeraccountmanagement/customerdeleteaccount.md): Deletes the customer account and all associated payment methods, delivery addresses, push tokens, etc.

## Delivery Addresses

Management of saved delivery addresses on the customer account.

### Get Delivery Addresses

 - [GET /v2/customer/delivery-addresses](https://documentation.getbite.com/openapi/v2/bite-api-v2/customerdeliveryaddresses/customergetdeliveryaddresses.md): Returns the latest copy of all the saved delivery addresses associated with the customer's account.

### Create a New Delivery Address

 - [POST /v2/customer/delivery-addresses](https://documentation.getbite.com/openapi/v2/bite-api-v2/customerdeliveryaddresses/customercreatedeliveryaddress.md): Creates a new delivery address saved to the customer's account.

### Update a Delivery Address

 - [PUT /v2/customer/delivery-addresses/{deliveryAddressId}](https://documentation.getbite.com/openapi/v2/bite-api-v2/customerdeliveryaddresses/customerupdatedeliveryaddress.md): Update some simple fields on the specified delivery address.

### Delete a Delivery Address

 - [DELETE /v2/customer/delivery-addresses/{deliveryAddressId}](https://documentation.getbite.com/openapi/v2/bite-api-v2/customerdeliveryaddresses/customerdeletedeliveryaddress.md): Deletes the specified delivery address from the customer's account.

## Order History

Past orders associated with the customer account.

### Get Recent Orders for a Customer

 - [GET /v2/customer/orders](https://documentation.getbite.com/openapi/v2/bite-api-v2/customerorderhistory/customergetorders.md): Returns the most recent 20 orders that the customer has placed through the bite platform.

## Payment Methods

Management of saved payment methods on the customer account.

### Get Payment Methods

 - [GET /v2/customer/payment-methods](https://documentation.getbite.com/openapi/v2/bite-api-v2/customerpaymentmethods/customergetpaymentmethods.md): Returns the latest copy of all the saved payment methods associated with the customer's account.

### Update a Payment Method

 - [PUT /v2/customer/payment-methods/{paymentMethodId}](https://documentation.getbite.com/openapi/v2/bite-api-v2/customerpaymentmethods/customerupdatepaymentmethod.md): Update some simple fields on the specified payment method.

### Delete a Payment Method

 - [DELETE /v2/customer/payment-methods/{paymentMethodId}](https://documentation.getbite.com/openapi/v2/bite-api-v2/customerpaymentmethods/customerdeletepaymentmethod.md): Deletes the specified payment method from the customer's account.

## Push Tokens

Save mobile app push notification tokens on the customer account.

### Save a New Push Token

 - [POST /v2/customer/push-tokens](https://documentation.getbite.com/openapi/v2/bite-api-v2/customerpushtokens/customercreatepushtoken.md): Saves a new mobile app push notification token to the customer's account.

## Pick a Location

Endpoints for picking a location from which to order.

### Get All Locations

 - [GET /v2/locations](https://documentation.getbite.com/openapi/v2/bite-api-v2/locationspick/locationsgetall.md): 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.

### Search Locations

 - [GET /v2/locations/search](https://documentation.getbite.com/openapi/v2/bite-api-v2/locationspick/locationssearch.md): 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.

### Get Future Order Slots

 - [GET /v2/locations/{locationId}/future-order-slots](https://documentation.getbite.com/openapi/v2/bite-api-v2/locationspick/locationsgetfutureorderslots.md): Returns all the future order slots for which a guest could place an order at this location.

### Validate the Delivery Address at a Location

 - [POST /v2/locations/{locationId}/validate-delivery-address](https://documentation.getbite.com/openapi/v2/bite-api-v2/locationspick/locationsvalidatedeliveryaddress.md): Checks whether the specified address is within the delivery range of the location.

## Menu

Endpoints for getting the menu

### Get Menu

 - [GET /v2/menu](https://documentation.getbite.com/openapi/v2/bite-api-v2/menu/menuget.md): Returns the latest menu for the specified channel, time, fulfillment method, etc.

## Orders

Endpoints for ordering actions

### Create Order

 - [POST /v2/orders](https://documentation.getbite.com/openapi/v2/bite-api-v2/orders/ordercreate.md): 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.

### Get Order

 - [GET /v2/orders/{orderId}](https://documentation.getbite.com/openapi/v2/bite-api-v2/orders/orderget.md): Returns the latest order data along with its status

### Update Order

 - [PUT /v2/orders/{orderId}](https://documentation.getbite.com/openapi/v2/bite-api-v2/orders/orderput.md): Updates the current order.
If the order is closed then only the guestSurvey property can be updated.
Returns the updated order.

### Validate Order

 - [PUT /v2/orders/{orderId}/validate](https://documentation.getbite.com/openapi/v2/bite-api-v2/orders/ordervalidate.md): 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.

### Add Coupon

 - [POST /v2/orders/{orderId}/coupon](https://documentation.getbite.com/openapi/v2/bite-api-v2/orders/orderaddcoupon.md): 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.

### Remove Coupon

 - [DELETE /v2/orders/{orderId}/coupon](https://documentation.getbite.com/openapi/v2/bite-api-v2/orders/orderremovecoupon.md): 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.

### Set Tip Amount

 - [PUT /v2/orders/{orderId}/tip](https://documentation.getbite.com/openapi/v2/bite-api-v2/orders/orderputtip.md): 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.

### Close Order

 - [PUT /v2/orders/{orderId}/close](https://documentation.getbite.com/openapi/v2/bite-api-v2/orders/orderclose.md): Closes a fully paid order so that it can be sent to the kitchen for fulfillment.

### Send a Receipt for a Customer's Order.

 - [POST /v2/orders/{orderId}/receipt](https://documentation.getbite.com/openapi/v2/bite-api-v2/orders/ordersendguestreceipt.md): Returns success when it succeeds.

## Mobile App Config

Endpoints for getting the config bundle of a mobile app

### Retrieve Mobile App Config Bundle

 - [GET /v2/mobile-app-config](https://documentation.getbite.com/openapi/v2/bite-api-v2/mobileappconfig/mobileappconfigget.md): 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.

## Reporting

Endpoints for generating reports

### Generate an Orders Report

 - [GET /v2/reporting/orders/day/{date}](https://documentation.getbite.com/openapi/v2/bite-api-v2/reporting/reportingordersday.md): 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.

### Generate an Orders Report (Deprecated)

 - [POST /v2/reporting/orders/day](https://documentation.getbite.com/openapi/v2/bite-api-v2/reporting/reportingordersdaydeprecated.md): 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.

## 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. 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. Calculate the HMAC of the payload with the SHA256 hash function using the private key of the
   webhook.
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.


### Order Sent

 - [POST /v2/webhooks/order-sent](https://documentation.getbite.com/openapi/v2/bite-api-v2/webhooks/order-sent.md): 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.

### Order Updated

 - [POST /v2/webhooks/order-updated](https://documentation.getbite.com/openapi/v2/bite-api-v2/webhooks/order-updated.md): 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.