Organisation, buyers and items

Three records sit behind every invoice: who issues it, who receives it, and what is on it.

Your organisation is the seller

The supplier on every invoice is your organisation: the name, address and tax number it verified when it joined Yona. There is no separate seller to create. GET /i/v1/sellers returns that single seller record, and sellerId on an invoice is optional; when you send it, it must be your own.

Attempts to create, change or delete sellers are refused with 409 and BIZ205. To change supplier details, change the organisation in the Yona app.

Buyers

A buyer is saved once and referenced by id on invoices.

Field	Notes
`name`	Required
`partyType`	`individual`, `company`, `partnership`, `non_profit` or `government`
`taxId`, `taxIdType`	The tax identifier and its type: `tin`, `rn`, `foreign` or `none`. Leave both out for an individual without one
`legalName`, `email`, `phone`, `address`	Used on the document and for delivery
`reference`	Your own id for the buyer, for reconciliation

Is the buyer on the network?

Invoices to a buyer who is on the e-invoicing network are delivered through it. For anyone else, Yona delivers by email or a share link, and still reports the invoice to the authority. Yona checks a buyer’s reachability for you when the buyer is created and refreshes it in the background; those checks are free. GET /i/v1/buyers/reachability shows the result, and POST /i/v1/buyers/reachability/check asks the authority again on demand, which uses credits.

Tax numbers

GET /i/v1/invoices/lookup/tax-id/{value} returns the taxpayer record behind a tax number, before you save anything.
POST /i/v1/buyers/{id}/verify-tax-number verifies a saved buyer’s number with the authority and records the result on the buyer; GET /i/v1/buyers/{id}/verification-status reads it back.

Both use credits. Verification places a hold that is released if the authority cannot answer.

Items

An item is something you sell, saved with everything a line needs:

Field	Notes
`name`, `description`	Shown on the document
`itemType`	`goods` or `service`
`hsnCode` or `serviceCode`	The HS code for goods, the service code for services
`productCategory`	The category the code belongs to
`unitCode`	The unit of measure, such as `EA`, `KGM` or `HUR`
`unitPriceMinor`, `currency`	The price, in minor units
`taxCategory`	The tax category code
`sku`	Your own reference

A line item that carries an itemId takes its price and tax category from the item, so an invoice can be as short as a buyer, a kind and a list of item ids with quantities. Items you no longer sell are archived, not deleted, so old invoices keep their lines.

Code lists for units, tax categories, HS and service codes are at Reference data.