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 create a developer account in our sandbox environment.
The Fresh KDS API uses four key concepts:
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}
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
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.
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.
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.
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:
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.
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.
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.
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.
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.
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.
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.
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
Use Cases
Some examples of how our partners have leveraged the webhooks include:
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:
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.
Learn more about building an integration with Fresh KDS.
