Sales Tax and VAT

There are several different ways to set the sales_tax_rate or manual_sales_tax amount, depending on what is passed in the request and which resource you are requesting. Depending on what is set, the API will respond with different fields.

Expenses and Bills

Normally there is no need to specify the sales_tax_rate or the manual_sales_tax_amount for an expense or bill yourself. If you leave both of these fields out, the correct sales_tax_rate will be set for the category of the expense or bill. If you later retrieve an expense or bill set in this manner, the response will include the sales_tax_rate field.

If you include a manual_sales_tax_amount when creating an expense or bill through the API, it will set this and return the manual_sales_tax_amount in the response and for all other requests for this expense or bill in the future. No sales_tax_rate will be returned but you can calculate it yourself, as shown below.

If you include a sales_tax_rate when creating an expense or bill through the API this is used to calculate a manual_sales_tax_amount. This manual_sales_tax_amount will be returned in the response and in future requests. This is calculated from the gross value and the sales_tax_rate percentage supplied.

For example, if you posted the JSON below, the response would include a manual_sales_tax_amount of 16.67, 20% of 83.33. These two amounts, when added together, give the gross value of 100.

{ "expense":
    {
        "user": "https://api.freeagent.com/v2/users/1",
        "category": "https://api.freeagent.com/v2/categories/285",
        "dated_on": "2012-10-22",
        "gross_value": "-100.0",
        "sales_tax_rate": "20",
        "description": "Example of setting a sales_tax_rate manually",
        "receipt_reference": "001",
    }
}

If you specify both a manual_sales_tax_amount and a sales_tax_rate the sales_tax_rate will be ignored and only the manual_sales_tax_amount will be returned in the response.

If you need to calculate the sales_tax_rate from the sales_tax_amount and the gross_value you can use the following formula:

net_value = abs(gross_value) - manual_sales_tax_amount
sales_tax_rate = (manual_sales_tax_amount / net_value) * 100

Invoices

Invoices are much simpler than expenses and bills and only have a sales_tax_rate parameter for each invoice_item. This is a percentage rate and it is a required field. An example of this is shown below.

{ "invoice":
  {
    "contact":"https://api.freeagent.com/v2/contacts/2",
    "dated_on":"2001-12-12T00:00:00+00:00",
    "due_on":"2001-12-17T00:00:00+00:00",
    "reference":"003",
    "currency":"GBP",
    "exchange_rate":"1.0",
    "net_value":"0.0",
    "status":"Draft",
    "comments":"An example invoice comment."
    "omit_header":false,
    "payment_terms_in_days":5,
    "ec_status":"EC Goods",
    "invoice_items":[
      {
        "description":"Test InvoiceItem",
        "item_type":"Hours",
        "price":"0.0",
        "quantity":"0.0",
        "sales_tax_rate":"20"
      }
    ]
  }
}

EC VAT MOSS

Sales can be tagged as VAT MOSS by providing an ec_status of EC VAT MOSS.

When creating a MOSS Invoice or Estimate you must also provide a place_of_supply. When creating a Bank Transaction Explanation, you must provide a place_of_supply and a sales_tax_rate.

The place_of_supply field must be a country name from the following list of EU members:

  • Austria
  • Belgium
  • Bulgaria
  • Croatia
  • Cyprus
  • Czech Republic
  • Denmark
  • Estonia
  • Finland
  • France
  • Germany
  • Greece
  • Hungary
  • Ireland
  • Italy
  • Latvia
  • Lithuania
  • Luxembourg
  • Malta
  • Netherlands
  • Poland
  • Portugal
  • Romania
  • Slovakia
  • Slovenia
  • Spain
  • Sweden

You can get the available MOSS rates for the sales_tax_rate field from the following endpoint:

GET https://api.freeagent.com/v2/ec_moss/sales_tax_rates?country=Austria&date=2017-01-01
  • country - The country specified as place_of_supply
  • date - The transaction date in YYYY-MM-DD format

Response

Status: 200 OK
{
  "sales_tax_rates": [
    {
      "percentage": "20.0",
      "band": "Standard"
    },
    {
      "percentage": "13.0",
      "band": "Reduced"
    },
    {
      "percentage": "12.0",
      "band": "Parking"
    }
  ]
}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <sales-tax-rates type="array">
    <sales-tax-rate>
      <percentage type="decimal">20.0</percentage>
      <band>Standard</band>
    </sales-tax-rate>
    <sales-tax-rate>
      <percentage type="decimal">13.0</percentage>
      <band>Reduced</band>
    </sales-tax-rate>
    <sales-tax-rate>
      <percentage type="decimal">12.0</percentage>
      <band>Parking</band>
    </sales-tax-rate>
  </sales-tax-rates>
</freeagent>
Show as JSON