Linking a menu to Toast Online Ordering on the GraphQL API

This guide is for developers building a Food brand website on the Gorilla Dash GraphQL API. It explains how to put an Order button on each menu listing that opens the same product on the visitor's chosen restaurant's Toast Online Ordering page, what the website asks for, and what an organisation administrator has to set up in Gorilla Dash before there is a link to show. A tribe, throughout, is one location, branch or business unit inside the organisation — one restaurant.

If you have not connected to the GraphQL API before, read The Gorilla Dash REST API and GraphQL API: which one to use first. It explains where a website's credentials live and how to exchange them for the access token every query below needs.

The words used here

What the link looks like

A generated link has the shape https://order.toasttab.com/online/{restaurant slug}/item-{item name}_{restaurant's item GUID}. The restaurant slug comes from Toast, and the item name and GUID come from that restaurant's own Toast menu, so the same menu item links to a different address at each restaurant. That is why every query has to say which tribe the visitor has chosen.

Asking for the link

First, fetch the locations for your picker with query Locations { tribes { name slug } }, and keep each tribe's slug.

Then ask for the link on every listing in a menu, passing the selected tribe's slug: query MenuWithOrderLinks($menu: String!, $tribe: String) { foodMenu(name: $menu) { name foodMenuSections { name slug foodMenuListItems(status: "Active") { id name type external_order_url(tribe_slug: $tribe) foodMenuItems { id name price(tribe_slug: $tribe) } } } } }

On a single listing page, ask for the same field on one listing: query ListingWithOrderLink($menu: String!, $section: String!, $slug: String!, $tribe: String) { foodMenuListItem(food_menu_name: $menu, section_slug: $section, slug: $slug) { id name external_order_url(tribe_slug: $tribe) foodMenuItems { name price(tribe_slug: $tribe) } } }

Ask for price(tribe_slug:) alongside the link, as both queries above do. It returns the price that tribe charges on that listing, so the price shown next to the button is the price the customer will be asked for. Without a tribe_slug it returns the price set on the listing, or the menu item's default price when the listing has none, which is not the same number.

Showing the button

• A URL came back — show the Order button and open that address. Opening it in a new tab is usual, because it leaves the brand site.
• null came back — hide the button for that listing at that tribe. Do not fall back to a guessed or hard-coded Toast address: null means Gorilla Dash could not build a link that the restaurant will honour, and a guessed one lands the customer on a missing page.
• No tribe has been chosen yet — every listing returns null. Ask the visitor to choose a location first, or send them to the location picker.

Ask again whenever the visitor changes location. Both the links and the prices belong to the tribe, not to the menu.

What has to be set up in Gorilla Dash

A generated link is only returned when every one of the following is true. An organisation administrator sets these up and the website needs no configuration of its own, so this list is here to help you work out why the field came back null. The Food settings: platform menus, ordering links and order push guide explains how an administrator performs each step, and is the page to send them to.

1. Food, then Settings, then Online ordering link is set to Toast. If the brand takes orders on its own domain rather than order.toasttab.com, that address is entered there as well.
2. The tribe is connected to Toast — its Toast Restaurant GUID is saved — and its menu has been pulled. The nightly menu pull stores both the restaurant's ordering slug and its menu. A brand using its own ordering domain has to type each restaurant's slug into the tribe's Toast Slug content, because the slug Toast uses is not guaranteed to work on another domain. A typed Toast Slug always wins over the pulled one.
3. The listing holds exactly one menu item. A combo listing offers the customer a choice of menu items, so there is no single Toast product for it to open and it never gets a link.
4. That menu item has a confirmed Toast mapping, under Food, then Platform mapping. Unconfirmed suggestions are not used.
5. That restaurant's Toast menu was pulled from Toast and sells the product, without hiding it from online ordering. Where Toast records no visibility at all for an item, it counts as orderable and there is nothing to switch on; where Toast does record visibility, that list has to include the online ordering channel.
6. The listing's External Order URL is empty. An address typed there is used instead of the generated link, as described below. A per-tribe ordering address typed on a tribe's food prices is a different field and is not what this one returns.

Overriding a link by hand

An administrator can type an External Order URL on a listing. That address is returned instead of the generated one, whatever the ordering platform is set to, and it is treated as a template: these placeholders are filled in for the tribe your query named.

Use one slug placeholder or the other, never both. An address containing {{tribe.slug}} keeps the older rule it was written against, so a {{toast.slug ?? tribe.slug}} in the same address is left as it is — and because any placeholder still standing voids the address, the link comes back null rather than arriving with the token in it.

An address that uses {{toast.item}} without {{tribe.slug}} returns null at a tribe with no typed Toast Slug, because such a template is unmistakably a Toast ordering link and the tribe's Gorilla Dash slug is not a Toast restaurant. Pairing {{toast.item}} with {{tribe.slug}} keeps the older rule and needs no typed Toast Slug, because the item segment is read from that tribe's copy of the Toast menu. Either way, the link is null when the product cannot be found in that menu.

When a listing has no link

The Online ordering link card on Food, then Settings, has a preview. Choose a listing and a tribe there to see the exact link Gorilla Dash will return, or the reason there is none — which is quicker than working back from a null in a query.