Fraud Blocker

Developer Guide

Getting Started

Integrating your point of sale, online ordering system, or order aggregation platform into Fresh KDS is fast and easy with our APIs, webhook events, and on-premise integration options. The backbone of the integration - sending orders to KDS screens - requires only a couple of API calls. Many of our partners have found success building on top of existing printer logic to develop a robust integration in a matter of weeks.

To get started contact us.

Terminology

The Fresh KDS API uses four key concepts:

  • Tokens - Every integration requires a token, which Fresh KDS provides. This is the key into the system. This token controls which resources you can access for a given brand. Each brand will require a separate token.
  • Brands - A brand is a collection of one or more locations of a restaurant. Depending on your system’s hierarchy a Fresh KDS brand may be the equivalent of a merchant or a business. Tokens are generated at the brand level.
  • Locations - A location represents an individual physical location of a kitchen. Generally speaking a food truck would be a single location even if it parks at different places to sell. Locations have subscriptions, which authorize them to register a certain number of KDS screens.
  • Devices - Also known as KDS screens, a device is the piece of hardware that receives and displays orders. This could be an iPad, Android tablet, or headless Android box connected to a monitor. Each device will be assigned a name, which typically describes its location in the restaurant - for example, Grill or Salad.

Authentication

Brand-level tokens are the key into the Fresh KDS system. You’ll need to generate a separate token for each brand your system is sending orders to.

Do not include these tokens in any code. They should be managed as secrets - for example getting pulled in from environmental variables or parameter stores. If your integration is going to be used by multiple clients you’ll need to implement token management to associate each token with the corresponding Fresh KDS brand.

A valid token is required for each request to the Fresh KDS API. It will be included in the request header:

x-integration-token: {token}

Get Brand Information

Once you have your brand-level integration token you’ll be able to make requests to get additional information about the setup and configuration of each brand. This information ranges from the basic information like location name and address to identifying information about an individual device at a location.

You might use this information as a one-off way to initialize a setup for your integration. Or you might use it on an ongoing basis as a way to interrogate the changing nature of a brand’s Fresh KDS setup. The location and device IDs are crucial to the integration process.

In order to get information about a location through the API the location must have an active Fresh KDS subscription.

You can access detailed information about a brand with a single request:

GET /integrators/kds-information

There are also endpoints that let you request a list of locations:

GET /integrators/kds-information/locations

And you can drill down further to get information on devices for a specific location:

GET /integrators/kds-information/locations/{locationId}/devices

Orders

Send an Order

Integrators send orders to Fresh KDS screens via the API millions of times a day. We’ve worked hard to make this vital part of the process as simple and easy as possible. Before sending an order you’ll need to make sure you have your authentication token and the location and device id(s) for the order. It only takes a single request to send an order to a KDS screen:

POST /integrators/kds-orders

While it only takes a single request to send an order, there are a few parameters and options that deserve a deeper explanation. First, you’ll use headers in your request to indicate which location and which device(s) need to receive this order. You have the option to specify a list of device IDs or pass in ‘all’ to send the order data to every active screen at the location.

Next, set a unique value for the id property. This id will identify the “block” that appears on the KDS screen. If you’re routing the same “block” to multiple screens you’ll use the same id for each request. However, if an order has multiple “blocks” - for example an appetizer course and an entree course that’s part of the same POS order but needs to be prepared separately - you’ll need to use a distinct id property for each course.

Finally, you’ll need to include the menu items for the order. Every request will include an array of items. You can provide details about an item including the modifiers, special instructions, quantity, and more. Each item should have a unique lineId so you can update the item later if necessary.

Sending this single request with the details of the order and the items in the order to a Fresh KDS device is all it takes to have the order show up at the appropriate station in the kitchen.

Update an Order

It’s not uncommon for customers to change their minds after they’ve already ordered. Fortunately, if your ordering system allows changes to existing orders you can communicate these updates to the kitchen in real time using the Fresh KDS update order route. This way the kitchen is always working off the most recent information.

To update an order you’ll need to know the id used in the original create order request. This value would have been returned in the API success response. You’ll also need to know the `lineId` values used in the original request.

You can also check to see if the order is still active on the KDS screens using the active order request:

GET /integrators/kds-orders/active

Once you’ve confirmed the order is still active you can make the update order request:

PUT /integrators/kds-orders

When making this request you’ll need to include all of the items, quantities, special instructions, and other details from the original order. For example, if the original order contained two menu items and you are adding a third the PUT request should include a total of three items in the item array - the first two with their original lineId values and the third with a new `lineId`. To update a menu item or its modifiers simply include the original `lineId` and replace the content with the new information.

In addition to making additions, deletions, and changes to menu items you can use the update order route to change an order’s type (i.e. change For Here to To Go), pick up time, or any other property.

Sending and updating orders are the two most basic and important steps in building your Fresh KDS integration. However, Fresh KDS offers a great deal more including customer messaging, cross screen communication, and curbside functionality. See the solutions section below for more details on how you can enable these powerful features for your customers by integrating with Fresh KDS.

Solutions

Routing

Fresh KDS does not natively support category or item-level routing. Fresh KDS supports order type routing, meaning each KDS screen can toggle on or off the order types that should be displayed. This allows integrators to send orders of all types to all screens and allows the locations to configure which order types should appear.

Category or item-level routing can be built in from the integrator’s side; many of our partners have done this successfully by building on top of their existing printer logic. While the send order route allows you to send an order to multiple screens in a single API call, this only applies if the items being sent to each screen are identical. If you are routing items from a single order to different screens you’ll need to make an API call for each combination of items. On each of these API calls you’ll want to use the same id so Fresh KDS is able to identify which “blocks” on each screen are associated with each other.

Messaging

Fresh KDS has the ability to send customers messages with information about their order. This premium feature is available in the United States and Canada via SMS messaging. There are three optional messaging triggers:

  • When orders are received on a screen
  • When orders are bumped/cleared from a screen
  • When orders are marked as “Ready” on the take out view

From the integrator’s perspective the only thing necessary to enable this feature is to set the phoneNumber and optInForSms properties when sending an order. The phoneNumber should be sent in E.164 format. If your customers have opted in to receive text messages then set optInForSms to true, otherwise set it to false. If optInForSms is false Fresh KDS will not send the customer messages, even if the screens are configured to do so.

Cross Screen Communication

There are two types of cross screen communication in Fresh KDS: multi-clear and send to next screen. Both types are easy to enable through the API or on-premise integration.

Multi-clear cross screen communication syncs item strike thoughts and order bumps between multiple screens. For this feature to work properly the screens must be able to identify which “blocks” and items in those blocks are the same. This is done by setting the same id property when routing order “blocks” to different screens. The items are matched by menu item and modifier names.

For example, suppose you have an order that contains a hamburger and a salad. You make three API calls to send the hamburger to the grill station, the salad to the salad station, and both items to the expo station. On each call you set the id to 12345. This will allow Fresh KDS to identify the order block as the same across all three screens. If the expo station is set up to multi-clear to the grill and salad station then when the user clears the order from expo it will also clear from the grill and salad stations.

The send to next screen option can be useful in kitchens with an assembly line model - for example, a pizza restaurant where the first station prepares the pizza and the second station cooks it. The KDS screen at the second station doesn’t need to know about the order until the pizza is prepped and handed off from the first station. As the integrator, you would simply send the order only to the first station’s KDS screen then allow Fresh KDS to handle the rest.

Curbside

Fresh KDS includes a number of features to help restaurants streamline curbside pick up. All of these features are available to integrators through the API.

The first thing you’ll need to do for curbside orders is set the mode property to CurbSide when sending the order to Fresh KDS. You’ll also want to include the vehicleModel and vehicleColor properties. These values will display on the Fresh KDS take out view to help the restaurant identify the customer’s car upon arrival.

Next, you’ll want to configure the arrival notifications. There are two methods for doing this - you can either provide an arrival URL when sending the order or you can allow Fresh KDS to generate the URL. We’ll cover both methods below.

Integrator Provides Arrival URL

If you already have customer arrival logic built into your platform you can simply supply the customerArrivedUrl value when sending the order to the KDS screens. Fresh KDS will append this URL to the Order Received and Order Ready customer messages. Note: Customer messaging is a premium feature and the KDS screen receiving the order must be configured to send messages. You can enable this feature without using Fresh KDS messaging if you provide the URL to your customer directly.

Once the customer clicks the link in the message you’ll need to handle the event and send a request to the customer arrival endpoint:

POST /integrators/kds-notifications/customer-arrived

On the take out view of the KDS screen this notification will move the order to the top of the queue and flash the arrival icon. For Fresh KDS to apply the notification to the right order you’ll need to include the same id used when creating the order.

Fresh KDS Provides Arrival URL

The other method for enabling curbside notifications is for Fresh KDS to generate the arrival URL, add that URL to the customer message, and then handle the event when the customer clicks the link. Using this method requires no additional information from the integrator, but it does require the KDS location to use the premium messaging feature. In the messaging set up the location can toggle on “send I’m Here link” which will automatically add the customer arrival URL to the message.

Non-Texting Options

The customer arrival endpoint will function for any order, even if there is no URL supplied or generated. This means you could build an integration that doesn’t require a customer interaction to trigger the arrival notification. For example, if you have GPS tracking capabilities in your platform you could use these to send the arrival notification when the customer is close to the restaurant. You can also use the estimated arrival time endpoint to send real-time updates of when to expect the customer:

POST /integrators/kds-notifications/estimated-arrival-update

The estimated arrival time, in minutes, will display on the order on the take out view of the KDS screen.

Third Party Delivery

Fresh KDS includes a couple of options related to third party delivery orders. The first is the originSource property when sending an order. The accepted values are DOORDASH, UBEREATS, and GRUBHUB. If provided, this value will display on the order in the KDS view so the kitchen knows which delivery service the order is from.

The second option is to pass the deliveryService object which includes properties for the delivery service name, order id, and driver contact phone number. These values will be displayed on the order in the take out view.

Webhooks

Fresh KDS includes webhooks for common events that occur within the KDS system. These real-time events allow integrators to receive information about the KDS system as it happens. Webhooks are configured at the brand-level in the Fresh KDS web portal.

Devices

  • Device Created - webhook is fired each time a new KDS screen is registered 

  • Device Updated - webhook is fired each time information about the KDS screen is changed

  • Device Deleted - webhook is fired each time a KDS screen is removed

Orders

  • KDS Order Created - webhook is fired each time a new order is created and includes order and item information; this webhook may be fired multiple times if the order is sent to different screens so you should be prepared to filter on the id value
  • KDS Order Bumped - webhook is fired each time an order is cleared from a KDS screen and includes order and item information

Use Cases

Some examples of how our partners have leveraged the webhooks include:

  • Triggering bump to print for a printer brand not currently natively supported by Fresh KDS
  • Funneling real-time order bump data into a BI tool or data warehouse for reporting
  • Updating order statuses in the POS for servers and cashiers to see

Cloud vs. On Premise Integration

In addition to the cloud API’s, it is possible to send orders to Fresh KDS screens across the local network at a restaurant location. This allows integrators to develop an integration that can function in “offline” mode without internet connectivity. See the On Premise Integration technical reference for more details.

There are several considerations when deciding how to integrate to Fresh KDS:

  • Offline capabilities - how important is the ability to operate offline to your customers? Kitchen display systems are a vital component of restaurant operations and therefore minimizing downtime is highly valuable. However, if your restaurants have reliable internet backup failovers and are at low risk for losing internet service then offline capabilities may be less important.
  • Engineering effort - while both integration types are straightforward your engineering team’s experience might make one option easier than the other. For example, if your team is familiar with TCP/UDP broadcast integrations from working with printers an on premise integration might be simpler to implement. If your team is more familiar with REST API’s the cloud route might be a better option.
  • Retry logic - one advantage of the cloud API approach is that Fresh KDS handles the retry logic with respect to deliverability of orders to the screens. This makes the integration a bit simpler from the integrator’s point of view. With the on premise integration you would need to handle the necessary retry logic to ensure all orders make it to the screens.
  • Functionality -  there are currently a couple of routes that only exist in the cloud API’s. These are the update order route, the customer arrival route, and the estimated arrival update route. If you plan to utilize these routes you will need to do so through the cloud API’s.

Can I use both?

You will need to pick one method for sending orders to the KDS screens - either cloud API or on premise. However, if you choose to send orders to the screens across the local network you can then augment them with the cloud API routes as long as you use the same `id` property to correctly identify the order.

Partner with us

Learn more about building an integration with Fresh KDS.

Simple API Integration

Restaurant/Kitchen Expertise

Helpful & Supportive Partnership

API Documentation