VAT Codes
VAT code and rate endpoints
List VAT codes
Credential: a company's API key or OAuth token.
Retrieves all VAT codes for your company, sorted by VAT code. VAT codes
define the rate and booking principle used to calculate VAT on journal
entries — pass a VAT code's id as vatCodeId on a journal-entry or
draft-journal-entry line to apply it.
Each code also carries the ledger account (and contra account) the VAT amount is booked to. Results are cached for 5 seconds; a create, update or delete through this API drops the cached list, so a read that follows the write reflects it. A list read already in flight during the write can serve the previous rows for up to 5 seconds.
Required Scope
vat-codes-read
List VAT codes › Responses
List of VAT codes and rates for the company
idThe unique identifier of the VAT code
vatCodeVAT code identifier
nameName/description of the VAT code
vatRateVAT rate percentage
typeWhat the code is for: which side of the VAT return it reports on and how the VAT is posted. Every type belongs to exactly one group, reported as group.
principleVAT principle - Gross (VAT included) or Net (VAT excluded)
groupThe group the type belongs to, which the VAT-code form shows above the type: output for sales, input for purchases, reverse_charge for purchases where the buyer accounts for the VAT. Membership by type — output: Output/sales, Domestic without VAT, Sales to other EU countries, Sales of services to other EU countries, Foreign sales to non-EU countries, Sales of products EU country-specific, Sales of services EU country-specific; input: Input/purchase; reverse_charge: Purchased products/abroad, Purchased services/abroad, Purchased products/domestic (reverse charge), Purchased products EU - Rubrik A, Purchased services EU - Rubrik A. The group follows from the type on every read and is not accepted on create or update: choose the type, and the group is set. Null when the stored type is one this version does not name.
countryCountry the code is specific to (ISO 3166-1 alpha-2) on the country-specific EU sales types; null on every other type
accountToBookIdThe ledger account ID to book VAT to
accountToBookNumberThe ledger account number to book VAT to
accountToBookNameThe ledger account name to book VAT to
contraAccountToBookIdThe contra account ID for VAT entries
contraAccountToBookNumberThe contra account number for VAT entries
contraAccountToBookNameThe contra account name for VAT entries
Create a VAT code
Credential: a company's API key or OAuth token.
Creates a VAT code. The code must be free within the company (409
VAT_CODE_ALREADY_EXISTS otherwise), and the booking accounts must be the
company's own (404 VAT_CODE_ACCOUNT_NOT_FOUND otherwise).
The type decides the rest, and the same rules the app applies answer here:
each type demands one principle — Net on the reverse-charge purchase types,
Gross on every other — and an omitted principle follows the type (400
VAT_CODE_INVALID_PRINCIPLE when a stated one does not). A reverse-charge
type needs contraAccountToBookId (400 VAT_CODE_CONTRA_ACCOUNT_REQUIRED).
The country-specific EU sales types need country (400
VAT_CODE_COUNTRY_REQUIRED) and every other type refuses one (400
VAT_CODE_COUNTRY_NOT_ALLOWED).
vatRate is a percentage (25 is 25%). Two values are never VAT rates and are
refused with the rate in details.vatRate: a rate above 0 and below 1, a
fraction sent where the percentage belongs (400 VAT_CODE_RATE_FRACTION), and a
rate of exactly 100 (400 VAT_CODE_RATE_HUNDRED). 0 is accepted for exempt and
zero-rated codes.
Required Scope
vat-codes-write
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Create a VAT code › Request Body
vatCodeShort code, unique within the company
nameName of the VAT code
vatRateVAT rate in percent. A rate above 0 and below 1 is refused (VAT_CODE_RATE_FRACTION), and so is 100 itself (VAT_CODE_RATE_HUNDRED).
typeWhat the code is for: which side of the VAT return it reports on and how the VAT is posted
accountToBookIdAccount the VAT amount is booked to; one of the company's accounts
principleGross when the amount on a line includes VAT, Net when VAT is added on top. Each type demands one principle (Net on the reverse-charge types, Gross on the rest); omitted, it follows the type.
contraAccountToBookIdAccount the offsetting VAT amount is booked to. Required on the reverse-charge types, which post the VAT on both sides. Null clears it.
countryCountry (ISO 3166-1 alpha-2) on the country-specific EU sales types, where it is required; refused on every other type. Null clears it.
Create a VAT code › Responses
VAT code created successfully
idThe unique identifier of the VAT code
vatCodeVAT code identifier
nameName/description of the VAT code
vatRateVAT rate percentage
typeWhat the code is for: which side of the VAT return it reports on and how the VAT is posted. Every type belongs to exactly one group, reported as group.
principleVAT principle - Gross (VAT included) or Net (VAT excluded)
groupThe group the type belongs to, which the VAT-code form shows above the type: output for sales, input for purchases, reverse_charge for purchases where the buyer accounts for the VAT. Membership by type — output: Output/sales, Domestic without VAT, Sales to other EU countries, Sales of services to other EU countries, Foreign sales to non-EU countries, Sales of products EU country-specific, Sales of services EU country-specific; input: Input/purchase; reverse_charge: Purchased products/abroad, Purchased services/abroad, Purchased products/domestic (reverse charge), Purchased products EU - Rubrik A, Purchased services EU - Rubrik A. The group follows from the type on every read and is not accepted on create or update: choose the type, and the group is set. Null when the stored type is one this version does not name.
countryCountry the code is specific to (ISO 3166-1 alpha-2) on the country-specific EU sales types; null on every other type
accountToBookIdThe ledger account ID to book VAT to
accountToBookNumberThe ledger account number to book VAT to
accountToBookNameThe ledger account name to book VAT to
contraAccountToBookIdThe contra account ID for VAT entries
contraAccountToBookNumberThe contra account number for VAT entries
contraAccountToBookNameThe contra account name for VAT entries
Get a VAT code
Credential: a company's API key or OAuth token.
Returns a single VAT code with its booking accounts.
Required Scope
vat-codes-read
path Parameters
vatCodeIdVAT code ID
Get a VAT code › Responses
VAT code details
idThe unique identifier of the VAT code
vatCodeVAT code identifier
nameName/description of the VAT code
vatRateVAT rate percentage
typeWhat the code is for: which side of the VAT return it reports on and how the VAT is posted. Every type belongs to exactly one group, reported as group.
principleVAT principle - Gross (VAT included) or Net (VAT excluded)
groupThe group the type belongs to, which the VAT-code form shows above the type: output for sales, input for purchases, reverse_charge for purchases where the buyer accounts for the VAT. Membership by type — output: Output/sales, Domestic without VAT, Sales to other EU countries, Sales of services to other EU countries, Foreign sales to non-EU countries, Sales of products EU country-specific, Sales of services EU country-specific; input: Input/purchase; reverse_charge: Purchased products/abroad, Purchased services/abroad, Purchased products/domestic (reverse charge), Purchased products EU - Rubrik A, Purchased services EU - Rubrik A. The group follows from the type on every read and is not accepted on create or update: choose the type, and the group is set. Null when the stored type is one this version does not name.
countryCountry the code is specific to (ISO 3166-1 alpha-2) on the country-specific EU sales types; null on every other type
accountToBookIdThe ledger account ID to book VAT to
accountToBookNumberThe ledger account number to book VAT to
accountToBookNameThe ledger account name to book VAT to
contraAccountToBookIdThe contra account ID for VAT entries
contraAccountToBookNumberThe contra account number for VAT entries
contraAccountToBookNameThe contra account name for VAT entries
Delete a VAT code
Credential: a company's API key or OAuth token.
Deletes a VAT code nothing refers to. A code that an account defaults to is
refused with 400 VAT_CODE_IN_USE_BY_LEDGER, and one that has been posted
with is refused with 400 VAT_CODE_IN_USE_BY_JOURNAL_ENTRY; each carries
the count in details.
Required Scope
vat-codes-write
path Parameters
vatCodeIdVAT code ID
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Delete a VAT code › Responses
VAT code deleted successfully
Update a VAT code
Credential: a company's API key or OAuth token.
Updates a VAT code. Only the fields provided in the request are changed;
send null to clear contraAccountToBookId or country. The create
rules apply to the merged result.
Once a code has been posted with, its rate, type, principle, accounts and
country are locked (400 VAT_CODE_IN_USE_BY_JOURNAL_ENTRY); the name and
the code stay editable.
A vatRate equal to the rate the code already holds is no change: it is not
written and does not count as an accounting change, so it is neither locked nor
refused, and a code holding an impossible rate can still have its name and code
edited. A vatRate that changes the rate is refused when the new rate is
never a VAT rate (400 VAT_CODE_RATE_FRACTION or VAT_CODE_RATE_HUNDRED, as on create), and is
locked like the other accounting fields once the code has been posted with — so
an impossible rate can be corrected only while the code has no postings.
Required Scope
vat-codes-write
path Parameters
vatCodeIdVAT code ID
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Update a VAT code › Request Body
principleGross when the amount on a line includes VAT, Net when VAT is added on top. Each type demands one principle (Net on the reverse-charge types, Gross on the rest); omitted, it follows the type.
contraAccountToBookIdAccount the offsetting VAT amount is booked to. Required on the reverse-charge types, which post the VAT on both sides. Null clears it.
countryCountry (ISO 3166-1 alpha-2) on the country-specific EU sales types, where it is required; refused on every other type. Null clears it.
vatCodeShort code, unique within the company
nameName of the VAT code
vatRateVAT rate in percent. A rate above 0 and below 1 is refused (VAT_CODE_RATE_FRACTION), and so is 100 itself (VAT_CODE_RATE_HUNDRED) unless the code already holds that rate.
typeWhat the code is for. A new type carries its own principle unless one is stated.
accountToBookIdAccount the VAT amount is booked to; one of the company's accounts
Update a VAT code › Responses
VAT code updated successfully
idThe unique identifier of the VAT code
vatCodeVAT code identifier
nameName/description of the VAT code
vatRateVAT rate percentage
typeWhat the code is for: which side of the VAT return it reports on and how the VAT is posted. Every type belongs to exactly one group, reported as group.
principleVAT principle - Gross (VAT included) or Net (VAT excluded)
groupThe group the type belongs to, which the VAT-code form shows above the type: output for sales, input for purchases, reverse_charge for purchases where the buyer accounts for the VAT. Membership by type — output: Output/sales, Domestic without VAT, Sales to other EU countries, Sales of services to other EU countries, Foreign sales to non-EU countries, Sales of products EU country-specific, Sales of services EU country-specific; input: Input/purchase; reverse_charge: Purchased products/abroad, Purchased services/abroad, Purchased products/domestic (reverse charge), Purchased products EU - Rubrik A, Purchased services EU - Rubrik A. The group follows from the type on every read and is not accepted on create or update: choose the type, and the group is set. Null when the stored type is one this version does not name.
countryCountry the code is specific to (ISO 3166-1 alpha-2) on the country-specific EU sales types; null on every other type
accountToBookIdThe ledger account ID to book VAT to
accountToBookNumberThe ledger account number to book VAT to
accountToBookNameThe ledger account name to book VAT to
contraAccountToBookIdThe contra account ID for VAT entries
contraAccountToBookNumberThe contra account number for VAT entries
contraAccountToBookNameThe contra account name for VAT entries