# API terminology

> Definitions for the public resources, identifiers, dates, and payment values used by the Fiest Partner API.

Source: https://docs.fiest.io/api/terminology

Use these meanings when mapping Fiest data into an integration. The names in
the API describe the public contract. They do not describe Fiest's storage
model or imply access to data outside the current authorization.

## Restaurants and access [#restaurants-and-access]

| Term                  | Meaning                                                                                                                                                                                                                                                                         |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Restaurant            | One Fiest business location. Restaurant-scoped requests use a `restaurantId` returned by [list restaurants](/api/reference/list-restaurants).                                                                                                                                   |
| Organization          | A Management grouping of restaurants. It can contain several restaurants, and a restaurant can appear in more than one authorized organization. Use an exact `organizationId` from [list organizations](/api/reference/list-organizations) when the API asks you to select one. |
| Authorized restaurant | A restaurant included in the current OAuth grant. An ID from another connection does not grant access.                                                                                                                                                                          |

## Menus and catalog data [#menus-and-catalog-data]

| Term               | Meaning                                                                                                                                                                                                                                                                          |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Restaurant catalog | The restaurant's food and drink items, including items not placed in a selected menu. Use `restaurantId` to address the restaurant; the API has no separate catalog container ID. Catalog imports can also create products, which the menu-item reads do not return.             |
| Menu               | A named selection of restaurant catalog items. A restaurant can have several menus, each with its own item selection and effective prices. See [menus, items, and prices](/api/menus-and-prices).                                                                                |
| Draft menu         | A menu that is not active for POS or selected for online ordering. Creating or importing a draft does not publish it.                                                                                                                                                            |
| POS menu           | The menu currently selected for point-of-sale use. The API reports this as `isPosMenu`.                                                                                                                                                                                          |
| Online menu        | The menu selected for customer-facing online ordering. The API reports this through `isOnlineMenu`. Selection alone does not guarantee that ordering is open.                                                                                                                    |
| Menu item          | A food or drink item in a restaurant's catalog. Its `catalogItemId` stays the same across menus; it does not identify a separate placement in each menu. Each menu can set a different effective price.                                                                          |
| Menu price         | The effective price of an item in one menu. `effectivePriceMinor` in a menu listing has this meaning. The catalog listing and draft editor use `basePriceMinor` for the item's base price. The API does not currently write menu-specific overrides.                             |
| Category           | A grouping of menu items. The catalog listing reports an item's restaurant-wide category; a menu listing reports its category in that menu. These can differ. Its `categoryId` remains stable when its name or position changes.                                                 |
| Catalog import     | A reviewed, create-only request that adds catalog data to a new or existing inactive draft. Planning validates the document without creating data; applying the same plan creates it. Import entities named `product` and `product_category` are outside the menu-item read API. |

## Orders and payments [#orders-and-payments]

| Term                  | Meaning                                                                                                                                                                                                                                                                                                                                                                                                          |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sold order            | A completed sale returned by [find orders](/api/reference/find-orders). Its details describe the sale as recorded, including sale-time tax evidence where available. Its item prices need not equal today's menu prices.                                                                                                                                                                                         |
| Sold-line catalog IDs | On a line with `catalogItemKind=menu_item`, `catalogItemId` identifies the same item in catalog and menu reads, and `menuId` identifies the menu used for the sale. `catalogCategoryId` identifies the category used for the sale; a current menu view can place the item elsewhere. These IDs may be `null` when the sale has no matching catalog identity. A `product` line is outside the menu-item read API. |
| `orderOrigin`         | How the order entered Fiest. This is separate from its payment method. See [settlement attribution](/api/settlement-attribution).                                                                                                                                                                                                                                                                                |
| `paymentMethod`       | How the sale was recorded as paid or settled. A marketplace method does not by itself mean that the order came from a marketplace integration.                                                                                                                                                                                                                                                                   |
| Accounting summary    | Raw sales, refunds, VAT, and payment-method totals for an inclusive business-date range. It does not include later payment-method corrections.                                                                                                                                                                                                                                                                   |
| Payment report        | A correction-aware view of payment-method allocation. `rawRows` show the original allocation; `adjustedRows` replace it only when `status` is `ready`. Do not add both sets of rows as sales. See [bookkeeping](/api/bookkeeping).                                                                                                                                                                               |
| Payment correction    | An approved change to the allocation of an existing payment between methods. It does not create another sale or change the order's origin.                                                                                                                                                                                                                                                                       |

## Values and identifiers [#values-and-identifiers]

| Term            | Meaning                                                                                                                                                                                                             |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Business date   | The restaurant-local date used for reporting. It follows the restaurant's time zone and business-day start hour, so it can differ from the calendar date of a UTC timestamp.                                        |
| Minor units     | Integer currency units. For EUR, `100` minor units means €1.00. Do not treat a `Minor` field as a decimal euro amount.                                                                                              |
| Public ID       | A stable identifier supplied by the API. Menu, item, and category public IDs are UUIDs. Keep IDs unchanged even when display names or prices change. The UUID format does not remove the need for authorization.    |
| Opaque ID       | An identifier whose format carries no meaning for clients. Pass an `orderId`, version, action ID, or payment source identity back exactly as returned. Do not construct one from a receipt number or another field. |
| Idempotency key | A client-generated UUID used to retry a write without creating the same action twice. Reuse the key for a retry of the same request, and use a new key for a new action.                                            |

The menu, catalog, and sold-order operations use the same `menuId` and
`catalogItemId` for the same resources. Preserve `catalogItemKind` alongside
order-line IDs: products are outside the food and drink menu read API.