.. _storage:

================================
OpenBooks - file and data format
================================

Your administration is stored in a single **.openbooks** file.  
This is a zip file with the following format:  

::

    administration.openbooks/
    ├── administration.xml
    ├── invoices/
    │   ├── invoice_0000000001.xml
    │   ├── invoice_0000000002.xml
    ├── documents/
    │   ├── invoice_1.pdf
    │   ├── invoice_2.pdf
    │   ├── receipt_3.png

**administration.xml** contains all company settings and data. This includes company info, projects, contacts, vat rates and cost centers.

**invoices/** Contains all incomming and outgoing invoices, stored in Peppol BIS 3.0 format.

**documents/** Contains all documents from which invoices have been generated.

Data structures
===============

Administration
--------------

- info — Contact information, stored as **Contact**
- next id — Id reserved for new data entry
- path — File path to save to
- program version — Version of data format
- country — Country code (used for tax reports)
- contacts **list** — List of contacts
- projects **list** — List of projects
- invoices **list** — List of invoices
- tax brackets **list** — List of available tax brackets
- AI service — Which AI service to use
- AI key — API key for selected AI service
- email service — Which email service to use
- email key — API key for selected email service

Contact
-------

- id **auto** — reference id **C/[id]**
- name **required** — Full name of individual or company name
- address line 1 **required** — Address
- address line 2 **required** — Zip, place
- country **required** — Country
- type **required** — Contact type, **business** or **consumer**
- tax number — Tax identification number
- business number — Business number
- email — Email address
- Phone number — Phone number
- bank account — Bank account number (to display on outgoing invoices)

Invoice (`docs <https://accountancyeurope.eu/wp-content/uploads/2025/04/250423-VAT-and-the-Digital-Age-Factsheet-Accountancy-Europe.pdf>`_)
-------------------------------------------------------------------------------------------------------------------------------------------

- id **auto** — reference id **I/[id]**
- sequential number **auto** — Generated sequential invoice number
- customer **required** — Customer contact information, stored as reference **C/[id]**
- supplier **required** — Supplier contact information, stored as reference **C/[id]**
- issue at **required** — Date when invoice was issued
- delivered at **required** — Date when goods or services were delivered
- expires at **required** — Date when invoice expires
- document **required** — Document associated with invoice, stored as filename
- billing items **required** **list** — List of billed items
- project — Project, stored as reference **P/[id]**
- cost center id — Cost center, stored as reference **E/[id]** (incoming invoices only)
- total **required** — Total amount billed
- tax **required** — Total tax billed
- net **required** — Total amount excl. tax
- status **required** — Payment status **paid** **expired** **cancelled** **refunded**, **corrected**
- shipping address line 1 **required** — Address
- shipping address line 2 **required** — Zip, place
- country **required** — Country
- currency **required** — Currency used for billing
- keep until **required** — Date until invoice needs to be stored legally
- payment on account date — If advance payment received and differs from invoice date (Ireland only)
- tax representative — If supplier uses tax representative in another Member State (Belgium only)
- corrected sequential number — For corrective invoices, the sequential number that identifies the original invoice to be corrected

Billing item
------------

- id **auto** — reference id **B/[id]**
- invoice **auto** — reference to invoice **I/[id]**
- description **required** — Description of billed item
- tax bracket **required** — Tax bracket (e.g. 0%, 21%, exempt, reversed)
- tax section **required** — Tax section (e.g. 1a up to 4b in The Netherlands)
- amount **required** — Amount of items, or a percentage
- amount is percentage **required** — Amount of items, or a percentage
- net per item **required** — Is amount a percentage
- net **required** — Total amount excl. tax
- discount **required** — Total discount
- tax **required** — Total tax billed
- is intra-community **required** — If applicable, note like “intra-Community supply of goods”
- is triangulation **required** — For EU triangulation: note scheme and buyer liable
- currency **required** — Currency used for billing
- internal code — Article or service code

Project
-------

- id **auto** — reference id **P/[id]**
- description **required** — Description of project
- start date **required** — Project started at date
- status **required** — Status of project **running** **paused** **cancelled**
- end date — Project cancelled at date

Cost center
-----------

- id **auto** — reference id **E/[id]**
- code **required** — Internal code of cost center
- description **required** — Description of cost center

Tax bracket
-----------

- id **auto** — reference id **T/[id]**
- country code **required** — 2 letter country code
- description **required** — Description of tax bracket
- rate **required** — Tax rate %