Master the art of managing your restaurant online

Tips, tutorials and data to help you make the most of’s restaurant tools. 101: API Walkthrough

Posted by David

[Part of Sam's series on how to use the API]

Alright lets cut to the chase and go through the flow of placing a food order. I will try to be framework/language agnostic and just talk from a high level perspective. There are a few steps you need to follow in order to go through placing an order. The exact order (pun intended) of these steps is not set in stone. They can be switched around a bit, but this is a fairly typical way to do it. Lets get started using guest order as an example.

Gather address information: You need to gather all of the necessary information about the user's address to determine which restaurants can deliver to them. This can be hard coded or stored in environment variables if you are making something for yourself. You can also prompt the user if you are making a web/mobile/cli app.

Call the delivery list endpoint: This will give you all of the restaurants that are delivering to the user's address. For each restaurant, you now have important information such as the name ("na"), address ("ad"), expected delivery time ("del"), minimum order cost ("mino"), and cuisine types ("cu"). Cuisine types include categories like "Italian" or "Thai." That stuff is all important, but the thing you need to continue with order placement is the restaurant ID (“rid”). So have your user select a restaurant or pick a random one for all I care (it is your app after all!), and save the rid for the next API call.

Call the restaurant details endpoint: This gives you access to the nitty gritty details of what the restaurant has to offer. It gives you the location based details and the cuisine types again. What you really want from this, though, is the menu! For the scope of what we are doing here, this might as well be called the "menu" endpoint. Here you can display the menu to the user and build a tray based on their actions or use your own magic to design it for them. This is probably where you’ll spend the bulk of your development time either in a UI or in magic. If you need a recap on how to deal with menus, here you go. [link to menu 101]

Collect credit card info: This is something you also could have done when collecting the user's address info, but people are used to entering their credit card info at a some sort of "checkout" phase.

Call the fee endpoint: This is something you want to do so you can tell your users how much extra money they are being charged in whatever type of delivery fees exist for this restaurant. You’ll send the restaurant id, time (this usually defaults to ASAP), subtotal of their tray so far and delivery address.

Call the guest order endpoint and PLACE THE ORDER: Now the moment of truth has arrived! You can now take all of this information you have been gathering, and put it to use in one final, truly epic API call. And I mean epic! This one is a doozy to type out, and you will probably make some typos. Send the tray string along with the email, phone number, delivery address info, billing address info, credit card info, etc in the body of the post request (or the params object or regular function parameters depending on which API wrapper you are using), and an order will be placed! A confirmation will be sent to your user's email. Make sure you look through the response object to make sure no errors occured!

Debug what just broke: Your first (or second, or third...or more) order will not go through due to something you missed. You might have typed one of the field names incorrectly in the API call. Look at the error message, and try to gather any valuable information about what just went wrong. Go through the last few steps over again, and double check your code. Once that is fixed, it is time to fire up that post request. Lets get this party started!

Party like it's 1999!: Once your first guest order goes through on the test servers, and you are done thoroughly testing your app, get ready to place some real food orders! Order as much food as you can afford, and invite me over for a couple of beers to celebrate your awesome new hack!

"Wrap"ping Up

If you don't feel like having to deal with all of that header setting nonsense of using REST APIs, you should check out our various API wrappers! I especially like the Swift API wrapper because I built it the day after the language was released, but that's another fun story.


Please check out the other 101 posts:

API Overview

API Walkthrough

Dealing With The Menu

Test vs Production 101: Dealing With The Menu

Posted by David

[Part of Sam's series on how to use the API]

The menu structure (you get this from the Restaurant Details endpoint) is fairly complicated, at least compared to what you would expect. Putting together an order than is both valid and complete enough for a restaurant to deliver food requires a lot more detail than you’d think if you’re normal experience with food ordering is calling the restaurant and asking for a pizza with mushrooms.

So here are the basics - a menu is a hierarchy with up to 4 tiers, it looks like this:

Groups -> Items -> Option Groups -> Option Items

So one example could look like this:

Entree (a group)

-> Large Pizza (an item)

-> What topping would you like? (an option group)

-> Anchovies (an option item)

Each thing is modeled in the data as a JSON object, and if it’s not a leaf, it will have a “children” key which will lead you to the next level. That’s children in the sense of computer science not biology. :)

Items (the second level) are orderable with IDs that you can add to a tray - some of them require a specific number of option items. Inside of these menu items exist "option groups" which are not things you can add to a tray. Option groups (like "toppings", "dressing" or "sides”)  contain sets of option items. Option items (the 4th and lowest level of the tree) are the actual options that you can select to add to a tray.

Some menu items require a specific number of options in order for them to be valid in a tray. A good example would be a menu item called "teriyaki platter" which has options for a type of meat. Lets pretend these options are "chicken", "beef" and "salmon." You wouldn't be able to order a teriyaki platter without specifying which meat you want with it, so this would require at least one option to be valid tray element. This logic is represented by two fields in the menu item called "max_child_select" and "min_child_select", which refer to the maximum and minimum number of options that need to be selected in order for this to be valid. NOTE - if max_child_select is 0, it’s equivalent to infinity (that is, you can select as many as you like) it does not literally mean, you can select at most 0 items.

Lets recap the structure of typical menu data using this teriyaki platter as an example!



   "Dinner Entrees": [


       "name": "Teriyaki Platter",

       "id": "1234567890",

       "children": [


           "name": "Meat choices",

           "children": [


               "name": "Chicken",

               "id": "0987654321",









   "Other stuff": ...



In this case it goes:

Dinner entrees -> Teriyaki Platter -> Meat Choices -> Chicken

Build a tray: This is the food that the user wants to order. Maybe you will have an interface for them to select what to order or maybe you will programmatically select something for them. However you decide to do it, you know how the menu items are structured. Now you need to build a tray with the IDs of the selected items and option items to order.

The tray is composed of groups of menu items and associated, optional sub-items. A single menu item's format is:

[menu item id]/[qty],[option id],[option id]...

Multiple menu items are joined by a +:

[menu item id]/[qty]+[menu item id2]/[qty2]

For example:


Means 2 of menu item 3270 (with no sub options) and 1 of item num 3263 with sub option 3279.

And now you know how to validate a tray! That's the hardest part of using the APIs!

Please check out the other API 101 posts:

API Overview

API Walkthrough

Dealing With The Menu

Test vs Production 101: Test vs Production

Posted by David

[Part of Sam's series on how to use the API]

The servers you choose to use will determine whether your order actually goes through and charges a real credit card. This is the difference between a demo and delivering real, delicious, delicious food. If you are using the raw HTTP API, then the subdomains "" and "" will be what sets these apart. If you are using an API wrapper, then you would pass an argument like "ordrin.TEST" or "ordrin.PRODUCTION" when creating the ordrin object.

The test API is what you want to use when you are developing and testing (go figure), as well as when you are demoing at a hackathon (unless you have a good 45 minutes to stick around and wait for food to arrive). You can access to the test servers just by registering an account and creating an app, which will give you the keys you can immediately begin using, no approval required!

When you want to throw your app into the wild and have users placing real food orders with it, then you switch to the production API. Your API key needs to be approved by before you can use the production servers - you can email them with some details of your app to get approved. And then let the food come rolling in.

Both test and production servers have the same underlying data - if you can place a test order without any errors you can feel confident that the same order would have succeeded in the live server. So please test as much as possible on the test servers!

One important thing - when your key is approved for production it doesn’t remove access to the test servers, so you can continue developing/testing with the same key. You’re also free to start another app to specifically have test only keys if you’re worried about accidentally specifying the wrong server - it’s up to you!

Please check out the other API 101 posts:

API Overview

API Walkthrough

Dealing With The Menu

Test vs Production 101: API Overview

Posted by David

[Part of Sam's series on how to use the API]

The APIs are broken up into 3 modules - I’m going to chat a little bit about each one and what you use them for:


Restaurant API

The restaurant API is where the bulk of the work takes place for most basic apps. It allows you to get the relevant data about restaurants on the network.

It has four endpoints:

  • Delivery list - Find all restaurants delivering to a given address

  • Restaurant details - Access all of a specific restaurant’s data(most importantly, the menu)

  • Delivery check - Verify that a restaurant delivers to a given address, at a given time.

  • Fee - Calculates all necessary fees(like delivery/convenience charges)


User API

The user API allows you to:

  • Create users

  • Save/delete/modify address information

  • Save/delete/modify credit card and billing information

The only thing this does that you can’t do on your own is save credit cards securely - if you want to have saved cards, you’ll need to use the user API. If you don’t care about that - you can decide whether or not you want to store a lot of this information yourself or whether you want to store it via the API. Developers typically use this API to proxy the storage of user data, allowing them to store it with us behind the scenes. It may make your life easier if you plan on doing more complicated things with the API, but lets focus on throwing something basic together for your hackathon project.


Order API

This is where the magic happens! Sure, restaurant and user data is nice, but what you really want to do is order some damn food! This is the simplest of the three in principle, but requires the most amount of data(stuff like credit card info, name, email, phone number, delivery address, billing address, not to mention the actual order! jeez!). There is really only one endpoint in the order API but it can be called in two ways: guest order and user order.

Guest order is what most basic apps use because it usually takes one "line" of code after gathering the data. All you need to do is send a POST request (or make an API wrapper call) to guest order with the relevant info, and you're done! That will place an actual food order(or a test order if you are using the test API).

User order is really helpful as well because it makes things less janky if you already have your user data saved. It requires the same kind of authentication (not OAuth, don’t worry :) that the User API has.

And that's all there is to it! Please check out the other 101 posts:

API Overview

API Walkthrough

Dealing With The Menu

Test vs Production

How the Hell Do I Use the API?

Posted by David

[Sam, one of our Dev Evangelists, wrote this massive blog post on the basics of using the API. We've broken it up into a few chapters and hope to refine this as we get more questions via email and at hackathons. It's essentially the answers to the FAQs we get. So if you've got questions, send them our way!]

So this past Summer, I was a hackNY fellow and an Ordr.intern (yeah I like stupid cheesy puns). It was definitely the greatest Summer of my life. I will get around to talking about how amazing hackNY is some other time though. At, I had the opportunity to hack on some really cool open source stuff like this and this, as well as some awesome, less flashy, "evil" proprietary stuff that "helped the business grow." Now as an Developer Evangelist, I’m repping this bad ass API at hackathons. So to make my life easier in the inevitably sleepless upcoming weekends, I will lay down some basic knowledge here of how to get things working!

I’m going to break this down into bite size bits so you can just read what you need to read.


API Overview

API Walkthrough

Dealing With The Menu

Test vs Production


As always, it is great to see what people are building, so please tweet @sagnewshreds and @ordrin to let us know what amazing things you all wind up making! Anyone who builds something with the API will receive a kick ass exclusive Ordrin t-shirt (not the standard one with the fortune cookie logo, which is also a kick ass shirt)!

Shoot me a tweet or an email if you need any more help!

Unhackathon + = Awesomeness

Posted by David

Not long ago, sponsored Unhackathon, our first college hackathon of the new season, and it was a blast! The organizers did a great job of making an event that focused on being inclusive and beginner friendly. It was refreshing for the focus to not be on huge prizes and overemphasized competition as is common these days. Between the awesome food, an amazing venue at AlleyNYC and the creative side events like participants being able to paint their own t shirts - Unhackathon was a huge success. It was also a great weekend for, with 11 hacks built on our API!


It was a small event and was the only API sponsor. That meant I had to hustle like never before to help hackers out, but it was worth having all eyes on us when it came to people thinking of hack ideas! There were two winners in each prize category and both of the prizes for “most entertaining hack” went to teams who used the API. Here are some of the coolest things that were built using over the weekend:


Sweet Depression (Most entertaining hack award)

This is one of the coolest hacks I’ve seen in a while! The basic idea is that you give it your information (address, credit card, email, twitter handle, etc) and it will periodically perform sentiment analysis on your tweets. If your tweets are sad over time, it will use the API to order desserts for you. I am close friends with the members of this team, and know that they are some bad ass hackers! I’ve been looking forward to what they would do with the API, and they certainly did not disappoint.


RapEats (Most entertaining hack award)

Here is another hilariously awesome project. Made by two Rutgers hackers, including the new director of HackRU. This one is a chrome extension that replaces your new tab window. With RapEats, whenever you open a new tab, food is suggested to you based on rap lyrics. Using the Rap Genius API, as well as some hilarious pictures from a Tumblr page called Pictures of Rappers Eating, lyrics containing food items are displayed along with a box for you to order the food that was mentioned in the song. Many laughs were had with this at Unhackathon!


Voice Ordr

This allows you to order food via voice recognition! You just say what food you want, and it will figure out what you said and place an order for you. I think they only made it work in the terminal, given the time restrictions, but I am looking forward to when this gets polished and thrown into production!


Spoons and Tunes

What struck me about this one was that it made Spotify playlists for upcoming music events, and ordered you food based on the genre of the performer to get you in the mood for a concert. They used 3 different APIs in this one, and API mashups are always cool for hackathons!


Ordrin Filesystem

This hack is seriously kick ass! Built by two Rutgers hackers who are also hackNY fellows, OrdrinFS creates a unix filesystem using data from the API. These two always tear it up at hackathons, so I was excited when they told me they wanted to hack on the API. Each restaurant’s menu manifests itself as files and directories, and you can place orders by writing to an “” file! The results of your order are then written to a file called “ordr.out.” This is pure genius!



This one was a solo hack, and it is pretty crazy. Written entirely in C, it is a trojan that you can control via an IRC chatroom. The idea is that if your friend leaves a computer unattended, you will run this code, and whatever people say to the chatbot will happen to your friend’s computer. There were about a dozen different things you can do, including opening the CD drive(if there is one), but you could also have food delivered to your friend without them realizing what happened. It is apparent that a lot of fun was had in the making of this hack.

Unhackathon was awesome - I had a great time helping hackers out and meeting a ton of new people! We are all super excited to be at this upcoming HackRU! I can’t wait to see how people continue to come up with crazy awesome use cases for the API.


-- Sam Agnew - Dev Evangelist - @SagnewShreds


One word about CalHacks: Holy Cow that was Cool

Posted by David

Last weekend Jason Teplitz, former intern & genius evangelist represented at Cal Hacks. Huge shout out to the organizers! There were over 1,500 hackers there, and the event was amazing. Smoooooth runnings. Here are some of the coolest hacks built on

  • Spazz4fudz, the winner of best use of the API, orders food Twitch Plays Pokemon style. Fight against your friends, by mashing on the arrow keys to force the penguin towards the restaurant that you like. Once the penguin hits a restaurant, you can order food from it with the widget. Check out the video. 

  • SmartBox was a physical box that could detect your mood and respond to requests. Among those requests: “Order me food” would launch the widget.
  • KnapSack is an iOS app that remembers your budget and location so that you can order a randomized meal within your price range at the press of a button. Gold star to Shreyas Kalyan who, while working on Knapsack, upgraded the swift library to be compatible with the newest version of Xcode.
  • OrderBot allows you to text a number with your food request and it would order it for you. Natural language processing, SMS, and food. Yum!
  • feedMe saves all your information and picks a random restaurant near you. At the press of a button you can either order a randomized meal from that restaurant, or order an uber to take you there. For most of the team this was their first webapp. We were pumped that they chose to learn webdev on the API.

Nearly half of these hacks were built using the widget, which is now new and improved thanks to Polina.  Enjoy the cool pics, especially the LIGHTSABRES we gave out as prizes.  Can’t wait to see what people build with it at HackRU this weekend!



The new widget is powerful like a bionic unicorn

Posted by David

Seriously. A bionic unicorn with a rainbow tail. And we have our developer Polina Viro to thank.


Our embeddable widgets adds a menu just like you'd add a youtube video - with a few lines of javascript and html. You can let your users to either search for a restaurant - either with or without a default address, or go directly to ordering from a restaurant specified by the restaurant ID.

The new widget allows for selecting which restaurant to order from: you can now input your address and check out the list of all restaurants that potentially deliver to your location (as well as see which ones are open and closed at the given time). In addition, if you’re embedding the widget, you may choose to prefill the delivery address for your customer. In that case, you’re immediately taken to the restaurant select page (with an option to change the delivery address).

Second, there is now a single widget. Old-timers will remember how there were two widgets - one for mobile, and one for web views. Now there is a single, responsive widget in the place of the two - the mobile view being activated for widths under 810px, and the web view for anything wider than that.

Thanks, Polina!