In Bezala's data model, "receipt" and "transaction" are the same thing. Throughout the API the resource is called transaction (so the endpoint is /api/transactions) but conceptually what you're working with is an expense backed by a receipt or invoice — coffee, hotel rooms, equipment, subscriptions, vendor bills.
This is the most-used object in Bezala. The other expense types — daily allowances, trips, rewards — share the same lifecycle but live in their own endpoints.
Anatomy of a receipt
A receipt has, at minimum:
A date — when the purchase happened.
A credit account (asset account) — the payment method. For a personal-card receipt, this is "Reimbursable to employee"; for a company-card receipt, it's the company-card account; for an invoice paid by bank transfer, it's the bank account.
A list of VAT lines — each line is an expense account, an amount, and a VAT code. Most receipts have one line, but a single receipt can be split across multiple expense accounts (a hotel bill that's part lodging, part meals).
A list of attachments — image or PDF files of the receipt itself.
It also commonly has:
A description — what was bought, who attended, the business purpose.
A vendor — set when the receipt should be paid to a third party rather than reimbursed.
Cost centers — one per dimension. Project, Office, Department, etc.
A bill line reference — when the receipt is matched against a credit-card statement entry.
A budget line reference — when the receipt is being charged against a pre-approved budget.
Three ways a receipt is created
In the order of frequency:
Email forwarding. The user forwards the receipt email to their personal receipts_email address (issued by /api/auth/token). Bezala extracts the attachment, runs OCR, applies any matching transaction rules, and creates a draft transaction. This is how most receipts enter Bezala, and it's automatable too — see importing emails receipts from email.
Mobile app. The user takes a photo of the receipt; the app uploads it via POST /api/attachments with draft=1, which creates a draft transaction with the photo attached. Then the user fills in the rest.
API. Your integration creates the transaction directly. Two patterns: upload the attachment first and then call POST /api/transactions referencing the attachment ID, or build a complete transaction in one call with no attachments. The first is the common one.
Creating a receipt with an attachment
The cleanest sequence is two calls:
The response gives you both the attachment ID and a transaction ID — Bezala has created a draft transaction to hold the image:
Omit draft: 1 from the PUT to submit the transaction at the same time. Include draft: 1 to keep it as a draft for the user to finalise later.
If you have all the data up front and don't need a multi-step flow, you can also send the whole thing in one POST /api/transactions and reference attachment IDs you've already uploaded:
VAT lines
A receipt's amount is expressed as one or more VAT lines. Each line is:
expense_account_id — the account being debited.
amount_cents — the gross amount of this line, in cents.
amount_currency — the currency code ("EUR", "SEK", "NOK", etc.). Falls back to the company's currency if omitted.
vat_id — the VAT rate. Get the list from GET /api/home.
participants — only required if the chosen expense account demands it (set per account).
A two-line example splitting a hotel bill into "Accommodation" and "Meals":
The total of the lines is the receipt total. There's no separate total field on the receipt — it's the sum of the VAT line amounts.
Account rules and auto-coding
Bezala has a feature called account rules (GET /api/account_rules) that auto-applies an expense account to a receipt based on text matching. A rule is a (pattern, account_code) pair: any receipt whose description, vendor, or VAT-line text contains the pattern gets coded to the matching account.
When you create a transaction via POST /api/transactions, Bezala runs account rules against the description and VAT lines and may overwrite the expense account on a line if a rule matches. This is helpful for getting consistent coding without forcing users to remember which account is which, but it can be surprising if you're integrating and expecting your expense_account_id to be the final word.
If you want to suppress this behaviour for a specific integration, get in touch with support — the rule application is a per-company setting.
Approval
Approval works exactly as described in approval workflows. The shorthand:
Marking as paid
Some workflows pay receipts outside Bezala — for example, an accountant pays the employee from the bank UI rather than via the SEPA file Bezala generates. To record that the receipt has been paid:
This only works for receipts that are accounted or in queue. Trying to mark a draft as paid is a no-op.
Listing and filtering
GET /api/transactions supports the standard filters from Conventions: page, per_page, state, user_id, date_range, updated_after. The most useful patterns:
Conditional fields
GET /api/transactions/:id/conditional_values returns the dynamic field values that depend on the current state of the transaction — for example, which VAT codes are valid given the country, the available cost centers given the user's permissions, the available expense accounts given the user's role and the chosen credit account.
If you're building a UI on top of the API, this is the endpoint that tells you what to show in dropdowns. If you're doing data integration, you usually don't need it.
Linking to budgets and bill lines
Two of the more advanced fields on a transaction:
budget_line_id — when set, ties the transaction's matching VAT line(s) to a specific line of a pre-approved budget. The budget's used_amount updates accordingly.
bill_line_id — when set, marks this transaction as the proof for a specific credit-card bill line. Bezala will reconcile the two sides when the credit-card bill is processed.
Both are documented in their own articles: budgets and credit card bills.