Build smart with Purchase Invoices

In the platform, the Purchase invoice flow represents the entire journey of a company's expenses. It handles everything from receiving a bill from a supplier (as a PDF, image, scanned document, or e-invoice), getting the expense approved, accounting for reverse charge VAT, managing currency valuations, and finally recording it in the bookkeeping and registering the payment.

This guide covers the key concepts, the business logic behind the purchase invoice lifecycle, how the purchasing flow connects to the API, and key rules to keep in mind when building your integration.

A note on naming: In the platform, these are called Purchase invoices. In the API, the same concept is referred to as Supplier invoices. You'll see this reflected in endpoint names like /supplierinvoices and /supplierinvoicedrafts. The terms refer to the same thing, the naming difference is a legacy of how the API was originally built.

Key concepts

These are key concepts covered in this guide:

• Suppliers: The organisations providing goods or offerings to the business. They’re linked to specific Terms of Payment.
• Purchase invoice drafts: Preliminary invoices. They can be freely edited, have cost allocations applied, and be sent for approval.
• Purchase invoices: Finalised invoices that have been posted to the general ledger.
• Attachments and scanning: Digital files (like a PDF) that act as the source document. Through Auto Assist and scanning, the platform can interpret these files automatically.
• Approval: A workflow step ensuring an expense is verified by an authorised user before it is posted.
• Supplier ledger items and valuations: The financial tracking record. If the invoice is in a foreign currency, its value can be adjusted over time using Valuation histories.
• Offsets (Kvittning): The process of matching a credit note against a debit invoice to clear the balance.
• Over/Under payments: Handling situations where the paid amount slightly differs from the invoice amount.

Business rules & logic

To protect accounting integrity, invoices usually start as Drafts (/supplierinvoicedrafts). E-invoices sent from suppliers, or PDFs interpreted by the scanning service, automatically land here. This path is mandatory if the expense needs to go through an Approval workflow or if cost allocation periods need to be set up. Once approved, the draft is converted into a locked, finalised invoice. If your integration already has the full accounting data, you can skip the draft entirely and create a finalised Purchase invoice directly.

Once finalised, a purchase invoice can't be deleted. Mistakes must be corrected by creating a Credit note and offsetting it.

If a company purchases in a foreign currency, exchange rates fluctuate. The platform allows updating the open ledger balance using Valuation histories before payment is made.

Not all expenses come with a formal invoice. Users can register purchases made without an invoice (receipts) or purchases paid with private money, which changes the accounting template used. Finally, when purchasing from abroad or in specific industries, Reverse charge VAT rules apply and must be handled correctly in the account coding.

Common workflows

From a business perspective, the typical expense cycle follows these steps:

1. Set up the supplier: The user ensures the Supplier exists in the registry with the correct Terms of Payment.
2. Receive and scan the bill: The bill arrives as an e-invoice draft, or a user uploads a PDF receipt as an Attachment. The Auto Assist scanning feature can extract data to pre-fill the manual Draft.
3. Allocate and approve (Optional): The cost is spread over several months if needed, and the draft gets approved by a manager.
4. Finalise and value: The draft is converted into a finalised Purchase invoice, generating Supplier ledger items. If it is a foreign invoice, its value might be adjusted over time.
5. Pay via bank integration: The invoice is sent for payment directly via a bank integration. Once paid, the payment is registered.
6. Handle mismatches and offsets: If the payment didn't exactly match (e.g., small fee differences), an over/under payment journal entry is created. If there was a return, a credit note is offset against the debit invoice.

Connection to the API

Your integration handles these workflows using the API's endpoints. Here is the conceptual mapping:

• Suppliers and terms: Use /suppliers for the registry. Fetch payment terms via GET /termsofpayment.
• Attachments and scanning: Upload files via POST /attachments and link them using /attachmentlinks. These files can be processed by Auto Assist.
• Working with Drafts: POST to /supplierinvoicedrafts. Update them (PUT), remove them (DELETE), or manage periods via DELETE /supplierinvoicedrafts/{id}/allocationperiods. Approve them using PUT /approval/supplierinvoice/{id} and convert via POST /supplierinvoicedrafts/{id}/convert.
• Direct Invoices and costs: Create finalised invoices instantly using POST /supplierinvoices.
• Valuations: Manage exchange rate changes on open foreign invoices via /supplierinvoicevaluationhistories.
• Payments and offsets: Register payments using POST /supplierinvoices/{invoiceId}/payments. Find offset candidates via GET /supplierinvoices/{creditInvoiceId}/offsetcandidates and apply them with POST /supplierinvoices/{creditInvoiceId}/offset.
• Tracking balances: Keep track of what is owed by reading /supplierledgeritems.
• Bulk export (SIE): Use the /siefileimportexport endpoints to send large volumes of purchasing data to an external auditor.

Relations to other domains

The purchasing domain is deeply connected to the rest of the financial platform:

• Projects and cost centres: Expenses are often tagged to specific Projects /projects) and Cost centres /costcenters) to track profitability.

• Stock: Supplier purchases of physical goods correlate with inbound delivery adjustments to update the stock balances.
• Accounting: Conversions and payments trigger updates to Accounts, Journal entries, and the VAT Report /vatreport).

Important things to consider

Keep these critical pitfalls in mind to build a robust integration:

• The purchase order gap: While users can manage Purchase orders in the graphical interface, there are no API endpoints for Purchase orders in V2. Do not try to automate this specific step!
• Over/Under payment limits: The API has a specific endpoint for payment differences (/voucherwithoverunderpayment), but note that this endpoint is currently not available for Swedish companies.
• Draft vs final deletion: Drafts have a DELETE endpoint. Finalised Invoices don't.
  

Good luck with the coding!