Concepts

The model#

Flavoso is an ordering system for restaurants. Every restaurant has its own ordering page, menu, kitchen and dashboard. Your app works on behalf of a restaurant once its owner has agreed.

App#

An app is your software as Flavoso knows it: created in the console, with a client ID (flv_app_…), a client type, redirect URIs, the scopes it may request and one webhook. An app can be connected to any number of restaurants; an account has at most 10 apps.

Every app has a status: in development, in review, approved, rejected or suspended. Until approval, it only connects to your test restaurant and to restaurants you own yourself.

Restaurant#

A restaurant is a business on Flavoso. In the API it is called tenant: with id, name, slug (the part of the address of its ordering page), timezone, currency and country. GET /me names it.

A restaurant has a plan (Starter, Pro, Premium). The API is included in every plan; reservations come with Pro and up.

Connection#

A connection is an owner's consent: this app may work with this restaurant, with these scopes. Its id is called connection_id in the token endpoint's response and in every event, and id in GET /me, because GET /me returns the connection itself. Its created_at is there as well.

There is at most one active connection per app and restaurant. If the owner connects again, the new scopes apply from then on. A connection ends when the owner disconnects, when your app calls DELETE /connection or when Flavoso ends it; then app.disconnected arrives.

Tokens#

• Access token (flv_at_…): goes into every request, valid for one hour.
• Refresh token (flv_rt_…): gets new access tokens, valid for 180 days from its last use and replaced by a new one on every use.

Every token belongs to exactly one connection and so to exactly one restaurant. An app with a hundred restaurants manages a hundred token pairs, ideally stored by connection_id or tenant.id.

Scopes#

Nine scopes control what a connection may do, for example orders:write or menu:read. Write includes read. The owner sees them in plain words when connecting. Details under Scopes.

Test and live#

There are no separate test keys and no second address. The difference is the restaurant: a test restaurant can never go live, and everything from it carries livemode: false, in GET /me and in every event. The same app, the same routes, the same token formats.

Objects and ids#

Every object carries its object (order, product, reservation, event …) and an id. Ids are UUIDs, except for events (evt_…) and requests (req_…). An id never changes, even when the restaurant changes a name or a price.

Your own ids, such as your POS item number, go alongside as external_id. See Requests.

Two directions#

• Your app asks: REST at https://api.flavoso.com/v1, JSON both ways.
• Flavoso reports: every change as an event, delivered by webhook or fetched with GET /events.

A change is the same wherever it happens: in the dashboard, on the kitchen display, in the phone app, at the receipt printer or through the API. An event reports it exactly once.