Glossary

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.

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": "<customer 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 — 100 s) a shortened body arrives without status_code; see response codes and 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.

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.
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.
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; the role toggles change the content of the response: key role permissions.

The full description of structures and fields is in the API reference.