Additional features coming with EU VAT reform to the Accounting API

Less than 10 minutes to read

Additional API features to support EU VAT reform changes

Financial settings - destination_vat - To determine if a business is using destination VAT:

To ensure the correct rules are applied when integrating with the API, we need to be able to identify if a business has enabled the use of destination VAT.

To enable this a new attribute has been added to the financial_settings endpoint.

Perform a GET request on the financial_settings

e.g. GET /financial_settings

{
  "$path": "/financial_settings",
  "year_end_date": null,
  "year_end_lockdown_date": null,
  "accounting_type": "accrual",
  "accounts_start_date": null,
  ...
  "destination_vat": true
}

Sales Artefacts - destination_consignment - To determine if a Sales artefact is marked as a destination consignment:

This is the flag that will indicate whether a Sales artefact (sales_invoices, sales_quotes, sales_estimates, sales_credit_notes, sales_corrective_invoices) is able to use destination VAT.
The attribute is not available on purchase artefacts.
It can be set to true or false by the API on a POST or PUT request.
When the value is true - you can then use destination vat tax rates.
When the value is not true - destination vat tax rates are not available.
It is only available when destination vat is enabled in financial settings.
It is only valid to be set as true when the business is GB and VAT registered.
It is only valid to be set as true when the contact on the artefact is in EU and not VAT registered, if the contact is NI the flag cannot be set.
The value will persist even if Destination VAT has been subsequently turned off in Financial Settings
It is allowed to amend the flag on existing artefacts, even if the Destination VAT enabled setting was changed to false in financial settings.
You can still save / update existing artefacts and retain the flag as being true, but can only change it to true from false if all other validations pass

Perform a GET request on a sales artefact endpoint:

e.g. GET /sales_invoices/a298d0ddea874d86aaa991758f80b01f

{
  "id": "a298d0ddea874d86aaa991758f80b01f",
  "displayed_as": "SI-2",
  "$path": "/sales_invoices/a298d0ddea874d86aaa991758f80b01f",
  "created_at": "2021-05-07T10:31:34Z",
  ...
  "destination_consignment": false,
  ...
}

Sales Artefacts - destination_vat_rates_in_use - To determine if a Sales artefact is using destination VAT rates:

This is the flag that will indicate whether a Sales artefact (sales_invoices, sales_quotes, sales_estimates, sales_credit_notes, sales_corrective_invoices) is using destination VAT.
The attribute is not available on purchase artefacts.
Atrribute cannot be set via the API, it is reporting a status of an artefact

Perform a GET request on a sales artefact endpoint:

e.g. GET /sales_invoices/a298d0ddea874d86aaa991758f80b01f

{
  "id": "a298d0ddea874d86aaa991758f80b01f",
  "displayed_as": "SI-2",
  "$path": "/sales_invoices/a298d0ddea874d86aaa991758f80b01f",
  "created_at": "2021-05-07T10:31:34Z",
  ...
  "destination_vat_rates_in_use": false,
  ...
}

Sales Artefacts - Tax breakdown - When fetching the PDF representation Of A Sales artefact

In a PDF representation of a Sales artefact (sales_invoices, sales_quotes, sales_estimates, sales_credit_notes, sales_corrective_invoices) that uses destination VAT, the tax breakdown will be displayed always in Euros.

Perform a GET request on a sales artefact endpoint:

GET /sales_invoices/{id}
Accept: application/pdf

Services - oss_service - Flag a service item as a OSS service so that destination VAT can be charged:

Flag is used to indicate whether a service item is OSS (One Stop Shop) item.
Not available on product records.
Can only apply flag when destination VAT is enabled for a business.
Attribute will appear on all services with a value of false by default.
The flag is not available in NA businesses (CA / US).
The flag can be set in any region where destination VAT is available - UKI & EU.
If destination VAT is disabled at business level, any OSS flag that was previously set on a service will remain.

Perform a GET request on a service endpoint:

e.g. GET /services/7017abd5d3754b48b277170a8f7c36cf

{
  "id": "7017abd5d3754b48b277170a8f7c36cf",
  "displayed_as": "asdasd",
  "$path": "/services/7017abd5d3754b48b277170a8f7c36cf",
  "created_at": "2021-05-07T12:28:06Z",
  "updated_at": "2021-05-07T12:28:06Z",
  "deletable": true,
  "deactivatable": true,
  ...
    "oss_service": true
}

Contacts - destination_vat_blocking - Flag to indicate if a contact is blocked from using destination vat when creating and editing artefacts:

Indicates if a Contact is blocked from using destination VAT in the context of creating and editing of artefacts
This attribute reports a status - you cannot set the value using POST or PUT
Intended to save time and logic, rather then using a contact’s country, tax registration etc, this attribute summarises a decision into a single attribute using the influencing factors.

Perform a GET request on the contacts endpoint:

e.g. GET /contacts/b781757e3be94e788a16a9c766a87a5c

{
  "id": "b781757e3be94e788a16a9c766a87a5c",
  "displayed_as": "SI-2",
  "$path": "/sales_invoices/b781757e3be94e788a16a9c766a87a5c",
  "created_at": "2021-05-06T15:40:02Z",
  "updated_at": "2021-05-06T15:40:03Z",
  ...
  "destination_vat_blocking": true
}

Tax Rates endpoint - include_destination_vat_rates param - Param to show destination vat tax rates:

In order to use destination tax, we need to be able to identify tax rates from other countries, outside of domestic rates.
When feature complete, only a single call with the param will be required. This will return all domestic and non-domestic rates in a single request.
For testing purposes, the param has been added and dummy data will be returned until the feature is completed. The dummy rates currently returning will be CIS tax rates, this allows developers to test their applications using the param.
While in the dummy state, two calls will be need to get all available tax rates, one without the param (gets domestic rates), one with the param, (gets non-domestic dummy data).
Before the launch, we will be updating and returning domestic + non-domestic rates when the feature is complete.
This param conflicts with sending cis_only param. You can only pass one or the other. If both are passed a valaidation error will be returned.

Perform a GET request on the tax_rates endpoint, passing the include_destination_vat_rates param:

e.g. GET /tax_rates?include_destination_vat_rates=true

Dummy data returned in response:

{
  "$total": 3,
  "$page": 1,
  "$next": null,
  "$back": null,
  "$itemsPerPage": 20,
  "$items": [
    {
      "id": "GB_CIS_ZERO",
      "displayed_as": "Gross 0.00%",
      "$path": "/tax_rates/GB_CIS_ZERO"
    },
    {
      "id": "GB_CIS_STANDARD",
      "displayed_as": "Standard 20.00%",
      "$path": "/tax_rates/GB_CIS_STANDARD"
    },
    {
      "id": "GB_CIS_HIGHER",
      "displayed_as": "Higher 30.00%",
      "$path": "/tax_rates/GB_CIS_HIGHER"
    }
  ]
}

New Endpoint - Tax determinations:

Tax Determination Engine provides an API that given information about an artefact, the business generating the artefact, and the customer of the artefact, provides a set of legislatively valid VAT rates describing the percentage that should be applied per item.
This endpoint is using the Tax Determination Engine to know which subset of rates and the order they are displayed in, for a certain scenario defined by the different params.
Only GET requests are possible.
In order to use destination tax, the param include_destination_vat should be included, if available artefact_id or the contact_id should be supplied as well, if they are not supplied in combination with include_destination_vat the country of the business will be used to get accurate tax rate information
The only required param is usage(sales, purchases).
The complete list of params will be displayed in the Taxes section.
If the endpoint cannot find the artefact or the contact provided the response will be a 404
If the artefact requires that eu_goods_services_type_id is supplied, then you should pass artefact_line_goods_services_type param as either GOODS or SERVICES to get accurate tax rate information.
Triangulated goods are not supported by TDE for the moment so the param artefact_line_goods_services_type has the following valid values(GOODS, SERVICES)

Performing GET requests:

GET /tax_determinations?usage=sales
GET /tax_determinations?usage=sales&include_destination_vat=true&artefact_id=94e788a16a9c766a87a5c

Dummy data returned in response:

{
  "$total": 5,
  "$page": 1,
  "$next": null,
  "$back": null,
  "$itemsPerPage": 20,
  "$items": [
    {
      "id": "GB_STANDARD",
      "displayed_as": "Standard 20.00%",
      "$path": "/tax_rates/GB_STANDARD"
    },
    {
      "id": "GB_LOWER",
      "displayed_as": "Lower Rate 5.00%",
      "$path": "/tax_rates/GB_LOWER"
    },
    {
      "id": "GB_ZERO",
      "displayed_as": "Zero Rated 0.00%",
      "$path": "/tax_rates/GB_ZERO"
    },
    {
      "id": "GB_EXEMPT",
      "displayed_as": "Exempt 0.00%",
      "$path": "/tax_rates/GB_EXEMPT"
    },
    {
      "id": "GB_NO_TAX",
      "displayed_as": "No VAT",
      "$path": "/tax_rates/GB_NO_TAX"
    }
  ]
}