# Menus, items, and prices

> Identify catalog items across menus and read the price that applies in each menu.

Source: https://docs.fiest.io/api/menus-and-prices

A restaurant has one set of food and drink items. A menu selects some of those
items and can set a different price for an item. The same item keeps its ID when
it appears in another menu.

The restaurant's catalog is its set of food and drink items. Address it with
`restaurantId`; there is no separate catalog container ID. A menu selects
items from that set and may override their prices. Address one menu with
`menuId`.

| Field           | Identifies                                                                                                 | What changes across menus?                                                                                     |
| --------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `restaurantId`  | The authorized restaurant                                                                                  | Nothing. Obtain it from [list restaurants](/api/reference/list-restaurants).                                   |
| `menuId`        | One named menu                                                                                             | Each menu has its own ID, item selection, and prices. Obtain IDs from [list menus](/api/reference/list-menus). |
| `catalogItemId` | One food or drink item in the restaurant catalog                                                           | The ID stays the same when the item appears in several menus. It is an item ID, not a menu placement ID.       |
| `categoryId`    | The item's restaurant-wide category in the catalog listing, or its category in the selected menu's listing | An item can appear under a different category in a menu.                                                       |

An order line uses `catalogItemId` for the same item ID when
`catalogItemKind=menu_item`. The order line's `menuId` identifies the menu
used for that sale.
`catalogItemKind=product` refers to a different kind of catalog item that the
menu-item reads do not return. These order-line IDs can be `null`, and an old
sale's recorded name or price need not match the current menu. See
[API terminology](/api/terminology) for the field mapping.

Store IDs exactly as returned. Their UUID format does not grant access to a
restaurant or menu outside the current OAuth authorization.

## Choose the right item read [#choose-the-right-item-read]

| Need                                                                                  | Operation                                                          | Price returned                                                  | Limit                   |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------- | ----------------------- |
| List the restaurant's food and drink items, including items outside the selected menu | [List restaurant catalog items](/api/reference/list-catalog-items) | Restaurant-wide `basePriceMinor`                                | Pages of up to 50 items |
| Read every item placed in a menu                                                      | [List a menu's items and prices](/api/reference/list-menu-items)   | `effectivePriceMinor` for that menu, alongside `basePriceMinor` | Pages of up to 50 items |

Page through the catalog listing until `nextAfter` is `null` to enumerate every
food and drink item, including items outside a selected menu. Use `query` to
filter by name. The catalog listing returns the restaurant-wide category; a
menu listing returns the category assigned in that menu.

## List the items and prices in a menu [#list-the-items-and-prices-in-a-menu]

1. Call [list menus](/api/reference/list-menus) and select a `menuId`.
   `posMenuId` and `onlineMenuId` identify the selected menus; `isPosMenu`
   and `isOnlineMenu` mark them in each summary. The online menu is the menu
   selected for online use. These are independent selections; online ordering
   can still be paused in restaurant settings.

2. Call [list items in a menu](/api/reference/list-menu-items):

   ```http
   GET /v1/restaurants/{restaurantId}/menus/{menuId}/items?limit=50
   ```

3. If `nextAfter` is a UUID, send it as `after` on the next request. Continue
   until `nextAfter` is `null`. The default `availability=all` includes hidden
   items; use `availability=available` when you only need visible ones.

This read requires `fiest.restaurant.read` and `fiest.menu.read`. Management
portfolio connections may also require `fiest.organization.read` and an exact
`organization_id` selector, as described in the endpoint reference.

## Read prices correctly [#read-prices-correctly]

For a fixed-price item in a menu listing, `basePriceMinor` is its
restaurant-wide base price. `effectivePriceMinor` is the price effective in
the selected menu. `priceSource` says whether that price comes from the base item or a menu
override. Amounts are integer euro cents.

For example, the same pizza could have a base price of €13.50, cost €12.50 in
a lunch menu, and cost €14.50 in a dinner menu. All three reads use the same
`catalogItemId`; the two menu reads return different `effectivePriceMinor` values.

| View                  | `basePriceMinor` | `effectivePriceMinor` | `priceSource`   |
| --------------------- | ---------------: | --------------------: | --------------- |
| Lunch menu            |           `1350` |                `1250` | `menu_override` |
| Dinner menu           |           `1350` |                `1450` | `menu_override` |
| Menu with no override |           `1350` |                `1350` | `base`          |

An open-price item has `openPrice=true`, `effectivePriceMinor=null`, and
`priceSource=open_price`. Do not treat `null` as a zero sale price.

An order line's `unitPriceMinor` records the sale. Do not recalculate an old
sale from a menu's current `effectivePriceMinor`. These reads also exclude Dashboard
products outside the food and drink menu-item contract.

## Writing prices [#writing-prices]

[Update a draft menu item](/api/reference/update-draft-menu-item) changes the
catalog item's base price only when the item is unshared and the selected menu
is inactive. It does not set a menu-specific price. The Partner API currently
has no operation to create or change a menu price override. Do not send a menu
listing's `effectivePriceMinor` to the draft edit operation as though it were
an override. The draft edit accepts `basePriceMinor`.