Companies, documents, money
The few notions that come back in every call.
The company
Everything is filed by company. A Hela account may run several; each has its own sales, stock, wallets, API keys and partner connections. In the API, the company id is in the path: /companies/{companyId}/…. A key opens only the company that created it.
Documents
| Document | What it is | Main events |
|---|---|---|
Sale (sale) |
A till receipt or an invoice. A sale has lines, a total, a payment status and a delivery status. | sale.created, invoice.issued, invoice.paid, invoice.partially_paid, invoice.refunded, sale.cancelled |
Quote (quote) |
An offer, which can be accepted, signed, converted into a sale. | quote.created, quote.accepted, quote.signed, quote.converted |
Purchase (purchase) |
A supplier order or supplier invoice. | purchase.created, purchase.received, purchase.paid |
Delivery (delivery) |
A delivery note attached to a sale. | delivery.created |
Transaction (transaction) |
Money in or out of a wallet. | transaction.created, payment.received |
Expense (expense) |
Money out without a supplier invoice. | expense.created |
Stay (stay) |
A room booking (hotel module). | stay.checked_in, stay.checked_out |
Time entry (time_entry) |
Hours worked for a client. | time_entry.created |
A sale is an invoice when it is addressed to an identified partner or leaves a balance due; a counter receipt paid on the spot is a cash sale. Several connectors let you leave cash sales out (the "counter sales" setting).
Partners
A partner (partner) is a customer, a supplier, or both. It carries a name, contact details, a tax id and — for e-invoicing — a country, a VAT number and a Peppol id.
Money
Every amount is an integer in minor units, with its currency:
{ "amount": 12500, "currency": "USD" } // 125.00 USD
{ "amount": 20000, "currency": "CDF" } // 20,000 FC — the franc has no decimals
{ "amount": 1500, "currency": "KES" } // 15.00 KES
The number of decimals depends on the currency, not on a setting. To get a readable number, divide by 10^decimals of the currency; the SDK does it (toMajor). Never store an amount as a float.
A company has a base currency and may sell in others; a sale in a foreign currency carries its rate (rateToBase), frozen at the time of the sale.
Dates
All dates are ISO 8601 UTC (2026-09-28T14:03:00.000Z). The company has a time zone (timezone), used to delimit "the day" in reports and till closings.
Identifiers
Identifiers are UUIDs. Documents also carry a readable number (ERNS-SALE-260928-0012) whose format is set in the settings; show the number, store the UUID.
Permissions
Every API action maps to a product permission (sales:view, sales:create, inventory:update, …). An API key carries a subset of these permissions called scopes. Permissions reserved for humans (settings:members, developers:manage, billing:*) cannot be given to a key; three scopes exist only for keys: events:read, webhooks:manage, exports:create.