In order to get the calculation data from the /vehicles/vehicle/:vehicle_id endpoint you will need to get a vehicle ID.

A variety of user interfaces for selecting vehicles that can be seen on Comcar, all of which effectively allow the user to narrow their choice down to 1 single vehicle.

• Make, model, fuel type dropdowns followed by a derivative list
• Company car tax summary tables listing makes, models and then derivatives
• Fuel Benefit check, presenting a list of makes, models and derivatives

You can present a list of makes, models, optionally grades or engines and finally single vehicles, using the following endpoints:

• /vehicles/makes/
• /vehicles/makes/:make/models/
• /vehicles/makes/:make/models/:model/vehicles

Optional grade and engine endpoints:

• /vehicles/makes/:make/models/:model/grades
• /vehicles/makes/:make/models/:model/engines

You can also search for vehicles using the vehicle search endpoint:

• /vehicles/search

The API provides you with 3 years of vehicle and fuel benefit tax data, so you don't need to do any of the calculations yourself. You can show the components of the calculation for the user's benefit.

The following image shows an example tax calculation from Comcar.co.uk, with vehicle benefit on the left and fuel benefit on the right (click the image to open in a new window)

All the data shown in the image is available in the vehicle endpoint:
/vehicles/vehicle/:vehicle_id

In the following sections, an array will be represented as array[] assuming a zero-index. So array[0] refers to the first item in the array

When array[ i ] is used the i is referring to the index of the current tax year e.g. when looking at Year 2018/19 i = 0

Tax Year Labels

The year labels at the top of the calculation are based on the year component of the data.tax[ i ].period_start and data.tax[ i ].period_end

For example, the first year's label, 2018/19 will to get the 2018 from the date 2018-04-06 (period start) and the 19 from the date 2019-04-05 (period end)

The tax periods run from the 6th April until the 5th April the following year

P11D

The P11D value is available at data.price.p11d. This value remains the same across all tax years so it is not repeated in the tax array

This has been calculated by removing First Registration Fee (FRF) and first year Vehicle Excise Duty (VED) from the On The Road price (OTR), including any taxable options

On The road (OTR)	data.price.otr
First Registration Fee (FRF)	data.price.first_registration_fee
First Year VED:	data.ved[ 0 ]

Percentage Charge

This is the appropriate tax percentage which is applied to the P11D value to calculate Benefit In Kind (BIK).

The percentage changes each year and varies according to CO₂ emissions and fuel type. You can see the full table in in Comcar's tax pages but we'll provide the correct percentage in the API

The value is given as a decimal at data.tax[ i ].co2_percentage.
So 0.28 represents 28%

Alternative fuel discounts, diesel supplements and battery range are taken into account where necessary

Benefit In Kind (BIK) and Tax payable

Benefit In Kind (BIK) is the salary equivalent of the vehicle and is taxed at the individual's top rate of tax.

It may be worth pointing out to the user that vehicle or fuel benefit may push them into the next tax band - they may pay tax at a higher rate because of a company vehicle.

The BIK, vehicle benefit tax and fuel benefit tax are all available in the data.tax[] array.

The vehicle and fuel benefit tax is shown at each available tax band, data.tax[ i ].bands[].

This data is for comparison purposes, so you can compare 2 vehicles side by side for a particular tax band. In reality the Salary and P11d combination could result in tax being paid across multiple bands.

bands[ 1 ].vehicle_tax = vehicle_bik * bands[ 1 ].percentage

Vehicle BIK:	data.tax[ i ].vehicle_bik
Vehicle tax per band	data.tax[ i ].bands[ i ].vehicle_tax
Percentage for lowest tax band	data.tax[ i ].bands[ i ].percentage

Other bands will be available in the array and can be displayed in the ascending order tax percentage along with their label data.tax[ i ].bands[ i ].label

Income tax rates vary between UK and Scottish rate taxpayers. The most common rates to show are 20% and 40% (Scottish rates are currently not supplied in the API)

Recalculating tax based on options (API v1)

If you need to recalculate the tax for a vehicle based on additional options, you will need to add the include=equipment query parameter to the /vehicles/vehicle/:vehicle_id request. This will then give you back all standard and optional equipment.

Get the sum total of the change_co2 or change_battery_range property for any optional equipment that gets selected in your tool.

Then make an additional request to the vehicle end point using the tax_override_co2 or tax_override_battery_range query parameters. This will give you updated battery, CO₂ and tax data.

For example, if the WLTP CO2 is 140, and the options selected have a total change_co2 value of 5, the total will be 145.

The WLTP CO2 values are limited to remain within their "Test Energy High" and "Test Energy Low" limits.

For further information please refer to the API v1 reference here: api.comcar.co.uk/docs/v1

The /vehicles/search endpoint supports the following filters

• make (list of strings) This can be a specific make or a list of make names. For example make=ford,kia You can use our /vehicles/makes/ endpoint to get a list of possible makes
• model (list of strings) This can be a specific model or a list of model names. For example model=ka,fiesta You can use our /vehicles/makes/:make/models/ endpoint to get a list of possible models
• fueltype (list of strings) This can be a specific fueltype or a list of fueltypes. For example fueltype=petrol,diesel,electric
• bodystyle (list of strings) This can be a specific bodystyle or a list of bodystyles. For example fueltype=suv,doublecab,saloon
• min_battery_range (integer) Minimum value for a battery range. min_battery_range=0 would only return vehicles with a battery range of 0 or above.
• max_battery_range (integer) Maximum value for a battery range. max_battery_range=500 would only return vehicles with a battery range of 500 or below.
• min_otr (integer) Minimum value for a otr. min_otr=20000 would only return vehicles with an otr of 20000 or above
• max_otr (integer) Maximum value for a otr. max_otr=50000 would only return vehicles with an otr of 50000 or below

The following modifiers are supported:

• order_by (string) the vehicle field to order the overall results by. This can be any field returned by the endpoint. For example order_by=make asc would order the results alphabetically
• group_by (string) a field to group the results by. Currently limited to make model or derivative. This can be combined with group_order_by which orders the result of the grouped field. For example, to retrieve the cheapest model for each make you could do group_by=model&group_order_by=otr asc

The following finance fields are available to filter the prices by:

• months - how long the contract is for (in months).
• initial_payments - number of payments in months you have to pay in the first month. (e.g. if price is £200 and the contract length is 6 months it's a £1200 payment (200 x 6))
• mileage - mileage per annum. You can't drive over this figure without having to pay excess pence per mile (see excess_ppm field in /search response)
• is_maintenance_inc - 'true' or 'false' whether the price includes maintenance.
• agreement_type_code
  • 'flb' - finance lease with balloon payment
  • 'pch' - personal contract hire
  • 'bch' - business contract hire
• price_type - (comma seperated list)
  • 'in_stock' only vehicles marked as in stock
  • cheapest show the cheapest rate
  • dealer_offer show only dealer offers.

Use these terms when displaying example rates or comparing different rates accross vehicles if the user has not specified terms.