> ## Documentation Index > Fetch the complete documentation index at: https://docs.tesouro.com/llms.txt > Use this file to discover all available pages before exploring further. # VAT rates > Learn how the VAT rates for invoices and quotes work. This page uses the term "VAT" to collectively refer to VAT and sales tax (e.g. GST). ## Overview [Invoices](/finops/guides/accounts-receivable/invoices/create) and [quotes](/finops/guides/accounts-receivable/quotes/create) must include VAT amounts, even if the VAT rate is 0%. Countries have different VAT rates for different types of products and services. For example, Germany has a standard VAT rate of 19%, a reduced VAT rate of 7%, and a zero VAT rate for certain transactions. ## VAT use cases VAT rates are generally driven by the country of the organization (seller) with some exceptions. One of those exceptions is the One-Stop Shop (OSS) scheme in Europe, where the VAT rates are based on the counterpart (buyer) country instead. Below are some scenarios common invoicing scenarios covered by Tesouro API. Organization country: Germany\ Counterpart country: Germany We assume that the organization has a German [VAT ID](/finops/guides/organizations/vat-ids) (of type `eu_vat`): ```json Organization VAT ID lines theme={null} { "country": "DE", "type": "eu_vat", "value": "123456789" } ``` `GET /vat-rates?counterpart_id=<...>&entity_vat_id=<...>` returns **German** VAT rates (based on the organization's country). Organization country: Netherlands\ Counterpart country: Norway We assume that the organization has a Dutch [VAT ID](/finops/guides/organizations/vat-ids) (of type `eu_vat`): ```json Organization VAT ID lines theme={null} { "country": "NL", "type": "eu_vat", "value": "123456789B12" } ``` `GET /vat-rates?counterpart_id=<...>&entity_vat_id=<...>` returns **Dutch** VAT rates (based on the organization's country). European Union has the [One Stop Shop (OSS)](https://vat-one-stop-shop.ec.europa.eu/one-stop-shop_en) scheme for cross-border B2C sales in the EU. EU organizations registered under the OSS scheme need to create a separate [VAT ID](/finops/guides/organizations/vat-ids) with the `eu_oss_vat` type for use in invoices that fall under that scheme. ```json {2} title="OSS VAT number" lines theme={null} { "country": "DE", // Organization's EU country of registration "type": "eu_oss_vat", "value": "123456789" } ``` In the following scenario: Organization country: Germany\ Organization `entity_vat_id_id` points to the OSS VAT number\ Counterpart country: France `GET /vat-rates?counterpart_id=<...>&entity_vat_id=<...>` returns **French** VAT rates (based on the counterpart's country). ## VAT rate catalog Tesouro maintains a catalog of VAT rates for select countries. API Partners can query the available rates via the [`GET /vat-rates`](/finops/reference/openapi/vat-rates/get-vat-rates) endpoint ([see below](#get-vat-rates)). ### Supported countries Currently, the `GET /vat-rates` endpoint provides VAT rates for the following countries: **What about other countries?** Organizations from other countries should not use the `GET /vat-rates` endpoint, and should instead use the invoice field `line_items[].tax_rate_value` to specify tax/VAT rates directly. Organizations are responsible for providing the correct VAT rate values for the invoice to be compliant. ### Get VAT rates To query the applicable VAT rates for an invoice, use the [`GET /vat-rates`](/finops/reference/openapi/vat-rates/get-vat-rates) endpoint with the parameters mentioned below. If the organization does not have a [VAT ID](/finops/guides/organizations/vat-ids), use: ```lines theme={null} GET /vat-rates?counterpart_id=<...> ``` If the organization has a VAT ID, use: ```lines theme={null} GET /vat-rates?entity_vat_id_id=<...>&counterpart_id=<...> ``` * For transactions that fall under the EU OSS scheme, specify the `entity_vat_id_id` that has the `eu_oss_vat` type (not `eu_vat`). \* For UK organizations that trade under the [Northern Ireland protocol](/finops/guides/organizations/vat-ids#example-ni-protocol), the organization VAT ID must have `country`="GB" and `type`=`eu_vat` (not `gb_vat`). The `GET /vat-rates` endpoint returns the applicable VAT rates based on the organization country, counterpart country, transaction type (e.g. B2B or B2C), and the presense (or absense) of organization VAT ID. Below is a sample response assuming the organization and counterpart are German. German VAT rates are 0%, 7%, and 19%. The VAT `value` in the response is the percentage multiplied by 100, that is, 7% is represented as 700.0 and 19% as 1900.0. ```json expandable lines theme={null} { "data": [ { "id": "a39a2ec3-765d-4f75-9a17-585a5d22509d", "created_at": "2022-09-23T12:28:31.941357+00:00", "updated_at": "2022-09-23T12:28:31.941375+00:00", "value": 0, "country": "US", "valid_from": null, "valid_until": null, "status": "active" }, { "id": "51cefc6c-9f82-484e-ae6a-a3a89b507bea", "created_at": "2022-09-23T12:28:31.941398+00:00", "updated_at": "2022-09-23T12:28:31.941406+00:00", "value": 700.0, "country": "US", "valid_from": null, "valid_until": null, "status": "active" }, { "id": "479155c3-0995-4689-a3cf-7482ea5132a9", "created_at": "2022-09-23T12:28:31.941423+00:00", "updated_at": "2022-09-23T12:28:31.941431+00:00", "value": 1900.0, "country": "US", "valid_from": null, "valid_until": null, "status": "active" } ] } ``` Note down the returned VAT `id` values. You will need them later to specify the corresponding VAT rates for individual line items in invoices and quotes. If a counterpart is exempt from paying VAT on an invoice, you can provide the reason for exemption via the optional `tax_exemption_rationale` field on the invoice object. For example, in situations where an invoice's line item is assigned a 0% VAT, you can provide the reason for exemption via the `tax_exemption_rationale` field when creating or updating an invoice. The reason provided will also be displayed on the invoice PDF. ## Specify VAT rates when creating or updating invoices and quotes When you create an invoice or a quote by calling [`POST /receivables`](/finops/reference/openapi/receivables/post-receivables), you must provide the `vat_rate_id` for each line item in the `line_items` array. In the example below, the first line item is taxed at 19% (VAT rate ID = 479155c3-0995-4689-a3cf-7482ea5132a9) and the second line item is taxed at 7% (VAT rate ID = 51cefc6c-9f82-484e-ae6a-a3a89b507bea). Tesouro will automatically calculate the tax amounts based on the specified VAT rate IDs and return the total tax in the `total_tax_amount` field in the invoice response. ```sh {13,18} expandable lines theme={null} curl -X POST 'https://api.sandbox.tesouro.com/v1/receivables' \ -H 'X-Finops-Version: 2025-06-23' \ -H 'X-Organization-Id: ORGANIZATION_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "type": "invoice", ... "line_items": [ { "quantity": 5, "product_id": "8755c86a-d630-4920-b6fd-fd2917d87dfb", "vat_rate_id": "479155c3-0995-4689-a3cf-7482ea5132a9" }, { "quantity": 1, "product_id": "b97601e1-e795-4c47-85d5-e5c54a75058d", "vat_rate_id": "51cefc6c-9f82-484e-ae6a-a3a89b507bea" } ], ... }' ``` Similarly, to update the VAT rate for a specific line item in an existing draft invoice or quote, call `PATCH /receivables/{receivables_id}` and provide the new `vat_rate_id` for that line item: ```sh expandable lines theme={null} curl -X PATCH 'https://api.sandbox.tesouro.com/v1/receivables/411dc6eb...6289b3' \ -H 'X-Finops-Version: 2025-06-23' \ -H 'X-Organization-Id: ORGANIZATION_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "invoice": { "line_items": [ { "quantity": 5, "product_id": "8755c86a-d630-4920-b6fd-fd2917d87dfb", "vat_rate_id": "51cefc6c-9f82-484e-ae6a-a3a89b507bea" }, { "quantity": 1, "product_id": "b97601e1-e795-4c47-85d5-e5c54a75058d", "vat_rate_id": "479155c3-0995-4689-a3cf-7482ea5132a9" } ] } }' ```