# `gnucash-uk-vat`
## Introduction
This is a utility which manages HMRC (UK) VAT returns in accordance with
HMRC MTD directives for users of the GnuCash accounting system. It can
study your GnuCash accounts, compare this with your HMRC VAT obligations,
and produce the VAT return to meet your obligations. As an optional step,
once the VAT return is filed, a bill can be posted describing the VAT
owing, and posted to an Accounts Payable account.
## Discuss
There's a #gnucash-uk-vat channel on our Discord server if you want
to discuss... https://discord.gg/3cAvPASS6p
## A word from our sponsors :)
If you need low cost, automated accounts filing for small businesses,
Accounts Machine has a commercial offering which incorporates the
functionality you see here in a web service.
The proposition is simple. Accounts Machine does not offer an
accounting system. You manage your accounts using GnuCash or anything
which produces CSV output. You manage your accounts, manage your
invoices, manage receipts, and record everything in your application
under your control. When it comes to filing returns, you upload your
accounts to accountsmachine.io and use the system to file VAT returns,
corporation tax returns, and company accounts with Companies House.
The production of returns is as automated as possible. Accounts
production conforms to iXBRL specifications, and HMRC VAT MTD.
This service is able to simplify accounts filing for simple businesses.
Your company should be a Limited Company, conform to micro-entity
requirements, and have a single trade. This service is aimed at making
life easier for startups and small businesses.
The roadmap is for launch in 2Q2022. VAT filing is complete, just going
through the final validation process with HMRC.
[Demo is here](https://drive.google.com/file/d/1hMIPaSKxuWNScTD_0-tdmwexLYWCzTAv/view?usp=sharing)
Visit https://accountsmachine.io. Accounts Machine is registered with HMRC
and Companies House for filing purposes and have successfully filed VAT,
corp tax and company accounts.
Join our discord service to keep on top of latest progress:
https://discord.gg/3cAvPASS6p
Enthusiastic early adopters will find free deal links on the Discord
server. Looking forward to filing for you. :)
## GnuCash backends
Two ways of interacting with your GnuCash accounts are supported:
- The `gnucash` module is bundled only with Linux GnuCash packages, and can
only by used on Linux.
- The `piecash` module is pure Python and can be obtained from package
repositories. This module only supports GnuCash files saved in
Sqlite files or a Postgres database. You can convert a GnuCash XML file into
Sqlite by using the "Save As..." option in GnuCash.
## Status
This is a command-line utility, with a GTK-based dialog mode which removes
the need to know about configuration files or command-line options.
I have used this to submit my own VAT returns. If you want to join the
party come to the #gnucash-uk-vat channel on Discord server
https://discord.gg/3cAvPASS6p and I'll try to help you through the process.
## Credentials
In order to use this, you need production credentials (client ID and secret)
for the VAT submission API. HMRC does not permit these credentials to be
shared publicly:
> We have checked with our colleagues who look after HMRC’s API
> Platform. They have advised that this is not allowed and would be likely
> to result in your Developer Hub application being blocked. We recommend
> that instead of sharing these credentials that you inform your users how
> they can register for their own Developer Hub application and use its
> credentials with your code.
You can either apply for production credentials using
the HMRC developer portal (you need to register), or contact me as I can
share a few credentials privately.
Developer hub:
https://developer.service.hmrc.gov.uk/api-documentation/docs/using-the-hub
You click 'Get production credentials' and enter details about the
application. I call this application `gnucash-uk-vat`, you should call
it something different. When you apply for credentials, HMRC will contact
you to fill in an application. As I understand it, this involves going
through a full acceptance test which involves testing against the
sandbox.
Once you have credentials, you should put them in the `config.json` file in
the `application` section placeholders.
## Installing
To install directly from a git repository:
```
pip3 install git+https://github.com/cybermaggedon/gnucash-uk-vat
```
To install/update from the local checkout, a wrapper script can be used:
```
[git-bash-prompt]> ./setup.sh
```
See [Installing](docs/installation.md).
## Usage
There are two modes:
- [Assist mode](docs/assist.md), which is a GTK-based dialog-driven.
This automates everything including configuration file setup.
- [CLI mode](docs/cli.md), which is purely CLI-based and has no
dependency on PyGTK.
## GnuCash accounts structure
See [Accounts](docs/accounts.md).
## Local test service
There is a local test service which allows you to emulate the HMRC VAT
service with test data under your control.
See [local test](docs/local-test.md).
## Sample accounts
A sample account file is included at `accounts/accounts.gnucash`. This
account file contains some transactions dated in the 1Q17 quarter which match
the test data in HMRC's Sandbox. There are also some transactions in 2020
which match the obligations in the `dummy-vat-service` data.
# Licences, Compliance, etc.
## Privacy
`gnucash-uk-vat` is hosted by you. It runs on your computer, accesses
information from your accounts, and forwards data using the HMRC APIs.
Everything is within your control. No other network systems are used, and no
information is transmitted to other parties.
Additional data (configuration and credentials) is stored on your
filesystem under your control and you should manage the credential
files as you would any password or other secret.
## Licence
Copyright (c) 2020-2021, Cyberapocalypse Limited
Copyright (c) 2021-2024, Accounts Machine Limited
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
# Tests
Run `pytest` or `make test`
Raw data
{
"_id": null,
"home_page": "https://github.com/cybermaggedon/gnucash-uk-vat",
"name": "gnucash-uk-vat",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "vat, hmrc, gnucash, accounting, uk, tax",
"author": "Cybermaggedon",
"author_email": "Cybermaggedon <mark@cyberapocalypse.co.uk>",
"download_url": "https://files.pythonhosted.org/packages/79/02/176988fd3542100533532d966baa66dfc648fe17e5f9ddc72493669e20ec/gnucash_uk_vat-1.8.0.tar.gz",
"platform": null,
"description": "\n# `gnucash-uk-vat`\n\n## Introduction\n\nThis is a utility which manages HMRC (UK) VAT returns in accordance with\nHMRC MTD directives for users of the GnuCash accounting system. It can\nstudy your GnuCash accounts, compare this with your HMRC VAT obligations,\nand produce the VAT return to meet your obligations. As an optional step,\nonce the VAT return is filed, a bill can be posted describing the VAT\nowing, and posted to an Accounts Payable account.\n\n## Discuss\n\nThere's a #gnucash-uk-vat channel on our Discord server if you want\nto discuss... https://discord.gg/3cAvPASS6p\n\n## A word from our sponsors :)\n\nIf you need low cost, automated accounts filing for small businesses,\nAccounts Machine has a commercial offering which incorporates the\nfunctionality you see here in a web service.\n\nThe proposition is simple. Accounts Machine does not offer an\naccounting system. You manage your accounts using GnuCash or anything\nwhich produces CSV output. You manage your accounts, manage your\ninvoices, manage receipts, and record everything in your application\nunder your control. When it comes to filing returns, you upload your\naccounts to accountsmachine.io and use the system to file VAT returns,\ncorporation tax returns, and company accounts with Companies House.\nThe production of returns is as automated as possible. Accounts\nproduction conforms to iXBRL specifications, and HMRC VAT MTD.\n\nThis service is able to simplify accounts filing for simple businesses.\nYour company should be a Limited Company, conform to micro-entity\nrequirements, and have a single trade. This service is aimed at making\nlife easier for startups and small businesses.\n\nThe roadmap is for launch in 2Q2022. VAT filing is complete, just going\nthrough the final validation process with HMRC.\n[Demo is here](https://drive.google.com/file/d/1hMIPaSKxuWNScTD_0-tdmwexLYWCzTAv/view?usp=sharing)\n\nVisit https://accountsmachine.io. Accounts Machine is registered with HMRC\nand Companies House for filing purposes and have successfully filed VAT,\ncorp tax and company accounts.\n\nJoin our discord service to keep on top of latest progress:\nhttps://discord.gg/3cAvPASS6p\n\nEnthusiastic early adopters will find free deal links on the Discord\nserver. Looking forward to filing for you. :)\n\n## GnuCash backends\n\nTwo ways of interacting with your GnuCash accounts are supported:\n- The `gnucash` module is bundled only with Linux GnuCash packages, and can\n only by used on Linux.\n- The `piecash` module is pure Python and can be obtained from package\n repositories. This module only supports GnuCash files saved in\n Sqlite files or a Postgres database. You can convert a GnuCash XML file into\n Sqlite by using the \"Save As...\" option in GnuCash.\n\n## Status\n\nThis is a command-line utility, with a GTK-based dialog mode which removes\nthe need to know about configuration files or command-line options.\nI have used this to submit my own VAT returns. If you want to join the\nparty come to the #gnucash-uk-vat channel on Discord server \nhttps://discord.gg/3cAvPASS6p and I'll try to help you through the process.\n\n## Credentials\n\nIn order to use this, you need production credentials (client ID and secret)\nfor the VAT submission API. HMRC does not permit these credentials to be\nshared publicly:\n\n> We have checked with our colleagues who look after HMRC\u2019s API\n> Platform. They have advised that this is not allowed and would be likely\n> to result in your Developer Hub application being blocked. We recommend\n> that instead of sharing these credentials that you inform your users how\n> they can register for their own Developer Hub application and use its\n> credentials with your code.\n\nYou can either apply for production credentials using\nthe HMRC developer portal (you need to register), or contact me as I can\nshare a few credentials privately.\n\nDeveloper hub: \nhttps://developer.service.hmrc.gov.uk/api-documentation/docs/using-the-hub\n\nYou click 'Get production credentials' and enter details about the\napplication. I call this application `gnucash-uk-vat`, you should call\nit something different. When you apply for credentials, HMRC will contact\nyou to fill in an application. As I understand it, this involves going\nthrough a full acceptance test which involves testing against the\nsandbox.\n\nOnce you have credentials, you should put them in the `config.json` file in\nthe `application` section placeholders.\n\n## Installing\n\nTo install directly from a git repository:\n\n```\npip3 install git+https://github.com/cybermaggedon/gnucash-uk-vat\n```\n\nTo install/update from the local checkout, a wrapper script can be used:\n\n```\n[git-bash-prompt]> ./setup.sh\n```\n\nSee [Installing](docs/installation.md).\n\n## Usage\n\nThere are two modes:\n- [Assist mode](docs/assist.md), which is a GTK-based dialog-driven.\n This automates everything including configuration file setup.\n- [CLI mode](docs/cli.md), which is purely CLI-based and has no\n dependency on PyGTK.\n\n## GnuCash accounts structure\n\nSee [Accounts](docs/accounts.md).\n\n## Local test service\n\nThere is a local test service which allows you to emulate the HMRC VAT\nservice with test data under your control.\n\nSee [local test](docs/local-test.md).\n\n## Sample accounts\n\nA sample account file is included at `accounts/accounts.gnucash`. This\naccount file contains some transactions dated in the 1Q17 quarter which match\nthe test data in HMRC's Sandbox. There are also some transactions in 2020\nwhich match the obligations in the `dummy-vat-service` data.\n\n# Licences, Compliance, etc.\n\n## Privacy\n\n`gnucash-uk-vat` is hosted by you. It runs on your computer, accesses\ninformation from your accounts, and forwards data using the HMRC APIs.\nEverything is within your control. No other network systems are used, and no\ninformation is transmitted to other parties.\n\nAdditional data (configuration and credentials) is stored on your\nfilesystem under your control and you should manage the credential\nfiles as you would any password or other secret.\n\n## Licence\n\nCopyright (c) 2020-2021, Cyberapocalypse Limited\nCopyright (c) 2021-2024, Accounts Machine Limited\n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program. If not, see <https://www.gnu.org/licenses/>.\n\n# Tests\n\nRun `pytest` or `make test`\n\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "UK HMRC VAT submission bridge for GnuCash users",
"version": "1.8.0",
"project_urls": {
"Documentation": "https://github.com/cybermaggedon/gnucash-uk-vat/blob/main/README.md",
"Download": "https://github.com/cybermaggedon/gnucash-uk-vat/archive/refs/tags/v1.8.0.tar.gz",
"Homepage": "https://github.com/cybermaggedon/gnucash-uk-vat",
"Issues": "https://github.com/cybermaggedon/gnucash-uk-vat/issues",
"Repository": "https://github.com/cybermaggedon/gnucash-uk-vat"
},
"split_keywords": [
"vat",
" hmrc",
" gnucash",
" accounting",
" uk",
" tax"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7902176988fd3542100533532d966baa66dfc648fe17e5f9ddc72493669e20ec",
"md5": "89492a503478660ee7612911cd0a0663",
"sha256": "5007ab0ff4f85ee31505cf21cc52b289c9aa6a84125be4e5a5dc60af256b3327"
},
"downloads": -1,
"filename": "gnucash_uk_vat-1.8.0.tar.gz",
"has_sig": false,
"md5_digest": "89492a503478660ee7612911cd0a0663",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 58276,
"upload_time": "2025-07-28T14:47:29",
"upload_time_iso_8601": "2025-07-28T14:47:29.924249Z",
"url": "https://files.pythonhosted.org/packages/79/02/176988fd3542100533532d966baa66dfc648fe17e5f9ddc72493669e20ec/gnucash_uk_vat-1.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 14:47:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cybermaggedon",
"github_project": "gnucash-uk-vat",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "gnucash-uk-vat"
}
JSON
