Skip to content
Developer home

Additional features coming with EU VAT reform to the Accounting API

  Less than 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 responce:

{
  "$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"
    }
  ]
}