# Glossary > BILLZ domain entities and what they mean. Terms that appear in the API reference and in the BILLZ interface. ## The three words that cause the most confusion | Term | What it means in BILLZ | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Transaction** | Everything that happens at the cash register: a **draft**, a **held sale**, a **sale**, a **return**. It is one entity at different stages; in the API it is `Order`. | | **Import** | What brings products into the system: goods arriving at the warehouse, with line items, a supplier and prices. | | **Order** | Only a **purchase order** (procurement). A sale is never called an order, neither in the interface nor in the documentation. | In the API, the transaction methods are named `/v2/order`, `/v2/order-product`, `/v2/order-payment`, and the entity in the models is `Order`; in the documentation text it is a **sale** or a **transaction**. More on this fork in terminology in the [online order guide](/en/guides/ecommerce-order/#terminology-fork). ## Entities | Entity | Name | What it is | | ------------------ | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Product` | Product | A catalog item. `product_type_id` has exactly three values: product, service, bundle (reference list `GET /v2/product-type`). Variability is a separate flag, `is_variative`. Stock and prices are stored per shop (`shop_measurement_values`, `shop_prices`). | | `ProductVariation` | Product variation | There is no separate entity in the API: a variation is the same product with `parent_id` filled in, its own barcode and a set of attributes. Its `name` is built as “parent name / attribute / attribute”; the original name is in `base_name`. With `group_variations=true` (only in `/v2/product-search-with-filters`) variations are returned nested in `variations` as a truncated model. | | `Category` | Category | A hierarchical product classifier; `parent_id` defines nesting. | | `Brand` | Brand | A reference list of product manufacturers/brands. | | `CustomField` | Custom field | An arbitrary product characteristic defined by the company: `custom_field_id` + `custom_field_value` (plus `custom_field_name`, `custom_field_system_name` and `from_parent`, a flag that the value is inherited from the parent product). The reference list of the fields themselves is `GET /v2/product-characteristic`. Edited via `PATCH /v2/product/{id}/patch-props`. | | `Attribute` | Attribute | A property of a variative product (size, color). In `product_field_filters`: `field_type: attribute`, with `field_values` holding the IDs of attribute values (for `custom`, the values themselves). | | `MeasurementUnit` | Unit of measure | Piece, kg, meter, etc. A company reference list (`GET /v2/measurement-unit`) with the fields `precision` (fractional precision), `short_name`, `is_default`, `is_editable`. Whether a product is divisible is set by its fields `is_divisible` and `measurement_type` (`COUNTABLE` / `UNCOUNTABLE`). | | `Shop` | Shop (outlet) | A physical point of sale of the company. Almost all warehouse and financial entities are tied to `shop_id`. The set of shops visible to a token is limited by the user’s permissions: without the permission to see the stock of all shops, the `shop_ids` filter is silently narrowed to the accessible ones, and if the intersection is empty, all shops of the company are substituted. | | `User` | User | An employee of the company. | | `Supplier` | Supplier | A counterparty that supplies products, with company details and a default markup. | | `Customer` | Customer (buyer) | A buyer of the company: phone, customer cards, loyalty program, cashback, debts. | | `CustomerCard` | Customer card | A name, a code and the `is_active` flag; there is no expiry date and no link to a loyalty program. The code is generated by the server (`POST /v1/client-card`, the body contains only `customer_id`); the name is built from the last five digits of the code. A custom value cannot be passed. The response is `{"id": "", "card_code": "..."}`: `id` here is the **customer** ID. | | `LoyaltyProgram` | Loyalty program | Rules for accruing cashback and discounts. Linked to the company and to the customer; a second card does not move the customer to another program. | | `Order` | Transaction (receipt) | The central entity of the cash register. Goes through the stages: draft → (held sale) → paid sale → (return). Contains line items, discounts, payments and the customer. In BILLZ, only a purchase order is called an order. | | `OrderItem` | Receipt line item | A product in the receipt: quantity, price, discount, amount. | | `Payment` | Payment | The part of the receipt paid with a specific payment type (`company_payment_type_id`); a receipt can be paid with several methods. | | `GiftCard` | Gift card / gift certificate | A prepaid payment instrument; it is added to a sale and redeemed on payment. | | `Promo` | Promotion | A discount rule. There are seven types (percentage, fixed price, 1+1, carousel, by receipt amount, by item count — per product and per cart), but only `PERCENTAGE` and `FIXED PRICE` make it into the catalog’s `promo_price`. A promotion is taken into account only if it is active, valid at the current time in the company’s time zone, does not require a promo code, applies to the retail price and is assigned directly to products. | | `Import` | Import (supply) | Goods arriving at the warehouse: a document with line items, a supplier, supply prices and selling prices (`retail_price`, `wholesale_price`, `min_price`, `max_price`). Until the supply is completed, its quantity is kept in a separate stock figure, `import_started_measurement_value`. | | `SupplierOrder` | Purchase order | A procurement document: it is created, filled with products and sent to the supplier. | | `Transfer` | Transfer (movement) | Moving products between shops: create → add products → send → accept/cancel. | | `WriteOff` | Write-off | Writing products off with a reason from the reference list: create → add products → complete/reject. | | `Stocktaking` | Stocktaking | A recount of stock; the `type` field takes five values: `full`, `partial` and the service values `import`, `transfer`, `order`, which are generated by other documents. The result is surpluses and shortages. | | `CashBox` | Cash register | The cash drawer of a shop; sale operations are tied to a cash register shift. | | `PaymentType` | Payment type | A payment method of the company: cash, UzCard, Humo, terminal, etc. | | `Currency` | Currency | The company currency and the exchange rate history (`company-currency-rates`). | | `ReportRow` | Report row | An element of a paginated report (`*-table`). | | `ReportTotals` | Report totals | Aggregates over the whole selection (`*-totals` / `*-report`); calculated independently of the current page. | | `AsyncEnvelope` | Asynchronous response envelope | The response of event methods with `Billz-Response-Channel: HTTP`: `{session_id, company_id, id, status_code, error{code,message}, correlation_id, topic, data}`. The HTTP code is taken from `status_code`, the ID of the created object from `id`. On a timeout (600 s, for [report export to Excel](/en/reference/report-export/) — 100 s) a shortened body arrives **without** `status_code`; see [response codes and errors](/en/reference/errors/). | | `Error` | Error | The error body. The API has no single format: some methods respond with `{"error": {"code", "message"}}`, some with `{"code", "message", "error", "data"}`, and some with numeric codes such as `20084`. See [error codes](/en/reference/errors/). | ## Terms that get confused The terms below sound like synonyms but mean different things. | Pair | Difference | | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Sale** and **order** | A customer’s purchase is an `Order`, a sale (`/v2/order`). “Order” in BILLZ means a **purchase order**, a purchase from a supplier (`/v2/supplier-order`). An online order from a website is posted as a sale. See [online order](/en/guides/ecommerce-order/). | | **Draft** and **posted document** | A created document is a draft: it exists and has an ID, but it does not affect stock. Stock is moved by **posting**, which is a separate call and a separate permission. | | **Held sale** and **draft** | A draft is an unfinished sale that is being worked on. A held sale is an unfinished sale that has been deliberately paused, with a time and a comment, to return to it later. | | **Write-off** and **return** | A write-off removes a product from the warehouse for a reason from the reference list (defect, loss). A return cancels a sale and puts the product back into stock. These are different processes with different permissions. | | **`id`** and **`order_number`** | `id` is the UUID of the sale, the key for linking systems. `order_number` is the short number visible in the interface. | | **Revenue** and **receipt total** | Reports calculate revenue taking returns, exchanges and currency conversions into account (`net_gross_sales`). Summing `total_price` over receipts from the sales search gives a different number. See [sales export](/en/guides/sales-export/). | | **Read permission** and **write permission** | Separate access toggles: write-offs have five of them — view the list, view cost price, create, post, delete. For an **integration key** the routes are defined by a [fixed list](/en/reference/permissions/); the role toggles change the content of the response: [key role permissions](/en/reference/role-permissions/). | The full description of structures and fields is in the [API reference](/en/reference/api/).