Package {hmrc}

hmrc: Download and Tidy HMRC Statistical Data

Description

Provides functions to download, parse, and tidy statistical data published by HM Revenue and Customs (HMRC) on GOV.UK. Returns annotated hmrc_tbl data frames with provenance metadata (source URL, fetch time, vintage, cell methods) for reproducible fiscal research. File URLs are resolved at runtime via the GOV.UK Content API, so data is always current.

Data fetchers

• hmrc_tax_receipts(): monthly tax receipts and NICs (rolling window, currently April 2017 onwards)

• hmrc_property_transactions(): monthly property transactions (April 2005 onwards)

• hmrc_income_tax_stats(): Income Tax liabilities by income range, outturn and projections

• hmrc_tax_gap(): tax gap estimates by tax and taxpayer group (2005-06 onwards)

• hmrc_stamp_duty(): annual stamp duty receipts (SDLT, SDRT, 2003-04 onwards)

• hmrc_vat(): monthly VAT receipts breakdown (April 1973 onwards)

• hmrc_rd_credits(): annual R&D tax credit statistics (2016-17 onwards)

• hmrc_fuel_duties(): monthly fuel duty receipts (January 1990 onwards)

• hmrc_tobacco_duties(): monthly tobacco duty receipts (January 1991 onwards)

• hmrc_corporation_tax(): annual Corporation Tax receipts by type

• hmrc_capital_gains(): annual CGT taxpayers, gains, liabilities (1987-88 onwards)

• hmrc_inheritance_tax(): IHT estates and liabilities by net-estate band

• hmrc_patent_box(): annual Patent Box election counts and relief

• hmrc_creative_industries(): annual Film, High-end TV, Games, Theatre and other reliefs

Discovery and infrastructure

• hmrc_search(): keyword search of the dataset catalogue

• hmrc_publications(): index of implemented and planned publications

• hmrc_list_tax_heads(): lookup table of tax-receipts identifiers

• hmrc_cache_info(): inspect locally cached files

• hmrc_clear_cache(): manage locally cached files

• hmrc_meta(): extract provenance metadata from any hmrc_tbl result

Citation

Run citation("hmrc") for the structured citation, or see the CITATION.cff file at the package root for the GitHub citation widget.

Data source

All data is published by HMRC on GOV.UK under the Open Government Licence. See https://www.gov.uk/government/organisations/hm-revenue-customs/about/statistics.

Author(s)

Maintainer: Charles Coverdale charlesfcoverdale@gmail.com

Authors:

• Charles Coverdale charlesfcoverdale@gmail.com

See Also

Useful links:

• https://charlescoverdale.github.io/hmrc/

• https://github.com/charlescoverdale/hmrc

• Report bugs at https://github.com/charlescoverdale/hmrc/issues

HMRC dataset catalogue

Description

A data frame describing every HMRC dataset known to the package, including those exposed by an ⁠hmrc_*⁠ function and those on the development roadmap (where function_name is NA). Use hmrc_search() for keyword search and hmrc_publications() for a tidy index.

Usage

catalogue

Format

A data frame with columns:

dataset

Character. Short identifier.

publication

Character. GOV.UK publication name.

function_name

Character. Exporting function (or NA).

frequency

Character. monthly, quarterly, annual, etc.

start

Character. First period of the published series.

publisher

Character. Usually "HMRC".

slug

Character. GOV.UK statistics slug.

url

Character. URL of the publication landing page.

description

Character. One-line description.

tags

Character. Space-separated keywords searched by hmrc_search().

Deprecated get_* aliases

Description

Renamed to use the ⁠hmrc_*⁠ prefix in v0.4.0. These aliases will be removed in v0.6.0.

Usage

get_tax_receipts(...)

get_vat(...)

get_fuel_duties(...)

get_tobacco_duties(...)

get_corporation_tax(...)

get_stamp_duty(...)

get_property_transactions(...)

get_rd_credits(...)

get_tax_gap(...)

get_income_tax_stats(...)

list_tax_heads()

clear_cache(max_age_days = NULL)

Inspect the local HMRC cache

Description

Returns a tidy table of files currently held in the package cache, with size and age. Useful for understanding what is stored locally and deciding when to clear stale files via hmrc_clear_cache().

Usage

hmrc_cache_info()

Value

A data frame with columns file, extension, size_bytes, size_mb, modified (POSIXct), age_days, path. The data frame is empty (zero rows) if the cache directory does not exist or is empty. The cache directory itself is attached as the attribute "cache_dir".

See Also

Other infrastructure: hmrc_clear_cache(), hmrc_list_tax_heads(), hmrc_meta(), hmrc_publications(), hmrc_search()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
info <- hmrc_cache_info()
attr(info, "cache_dir")
options(op)

Download HMRC Capital Gains Tax statistics

Description

Downloads and tidies HMRC Table 1 of the Capital Gains Tax statistics bulletin: estimated number of CGT taxpayers, amounts of gains, and tax liabilities by year of disposal. Data runs from 1987-88 onwards and is published annually each summer.

Usage

hmrc_capital_gains(tax_year = NULL, measure = NULL, cache = TRUE)

Arguments

Details

Gains are after the deduction of taper relief and losses plus attributed gains, but before deduction of the Annual Exempt Amount. Trusts include personal representatives of the deceased. Statistics for the latest tax years are provisional and are revised in subsequent publications as late returns arrive.

Value

An hmrc_tbl (long format) with columns tax_year, measure, value, and status ("provisional" for the years HMRC marks as provisional, otherwise NA). Numbers of taxpayers are in thousands; amounts in millions of pounds; percentages in per cent. Suppressed cells return NA.

Source

https://www.gov.uk/government/statistics/capital-gains-tax-statistics

See Also

Other data fetchers: hmrc_corporation_tax(), hmrc_creative_industries(), hmrc_fuel_duties(), hmrc_income_tax_stats(), hmrc_inheritance_tax(), hmrc_patent_box(), hmrc_property_transactions(), hmrc_rd_credits(), hmrc_stamp_duty(), hmrc_tax_gap(), hmrc_tax_receipts(), hmrc_tobacco_duties(), hmrc_vat()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  cgt <- hmrc_capital_gains(measure = "tax_total_gbp_m")
  tail(cgt)
})
options(op)

Clear the local HMRC data cache

Description

Deletes locally cached data files downloaded by the package. By default all cached files are removed; pass max_age_days to remove only files older than that.

Usage

hmrc_clear_cache(max_age_days = NULL)

Arguments

Value

Invisibly returns the number of files deleted.

See Also

Other infrastructure: hmrc_cache_info(), hmrc_list_tax_heads(), hmrc_meta(), hmrc_publications(), hmrc_search()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
hmrc_clear_cache(max_age_days = 30)
hmrc_clear_cache()
options(op)

Download HMRC Corporation Tax receipts by type

Description

Downloads and tidies the HMRC Corporation Tax Statistics annual publication, reporting receipts broken down by tax type for the most recent six financial years. Published annually in September.

Usage

hmrc_corporation_tax(cache = TRUE)

Arguments

Details

Some levies (e.g. Residential Property Developer Tax, Electricity Generators Levy) were introduced mid-series and have NA values for earlier years.

Value

An hmrc_tbl with columns tax_year, type, description, receipts_gbp_m.

Source

https://www.gov.uk/government/collections/analyses-of-corporation-tax-receipts-and-liabilities

See Also

Other data fetchers: hmrc_capital_gains(), hmrc_creative_industries(), hmrc_fuel_duties(), hmrc_income_tax_stats(), hmrc_inheritance_tax(), hmrc_patent_box(), hmrc_property_transactions(), hmrc_rd_credits(), hmrc_stamp_duty(), hmrc_tax_gap(), hmrc_tax_receipts(), hmrc_tobacco_duties(), hmrc_vat()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  ct <- hmrc_corporation_tax()
  ct[ct$type == "all_corporate_taxes", ]
})
options(op)

Download HMRC Creative Industries tax relief statistics

Description

Downloads and tidies Table 1 (annual time series) of the HMRC Creative Industries Statistics for each of the eight creative-industries reliefs: Film, High-end TV, Animation, Children's TV, Video Games, Theatre, Orchestra, and Museums and Galleries Exhibition. Published annually in August or September.

Usage

hmrc_creative_industries(sector = NULL, tax_year = NULL, cache = TRUE)

Arguments

Details

Creative Industries reliefs are paid on an accruals basis. The latest tax year in each sector's table is provisional and uplifted by HMRC for claims not yet received; status is recorded in the status column. Sector tables differ slightly in their column set (films track productions, video games track productions, theatre tracks claims/productions, museums track exhibitions, etc.); columns absent from a sector's table are returned as NA.

From the September 2026 edition the film, TV, animation and video games tables report the legacy tax relief alongside the expenditure credits that replace it: the Audio-Visual Expenditure Credit (AVEC), the Independent Film Tax Credit (IFTC) and the Video Games Expenditure Credit (VGEC). For those sectors this function returns HMRC's "total" columns, which cover the legacy relief and the credits together and are the columns HMRC says to use when comparing years. The split by relief type is not returned.

Value

An hmrc_tbl with columns:

sector

Character. Creative-industries sector identifier.

tax_year

Character. Tax year, e.g. "2023-24".

companies

Numeric. Number of companies (where reported).

claims

Numeric. Number of claims (where reported).

productions

Numeric. Number of productions (films, programmes, games, exhibitions, etc., where reported).

relief_gbp_m

Numeric. Amount of relief paid, GBP million.

status

Character. HMRC revision status (e.g. "Unchanged", "Provisional").

Source

https://www.gov.uk/government/collections/creative-industries-statistics

See Also

Other data fetchers: hmrc_capital_gains(), hmrc_corporation_tax(), hmrc_fuel_duties(), hmrc_income_tax_stats(), hmrc_inheritance_tax(), hmrc_patent_box(), hmrc_property_transactions(), hmrc_rd_credits(), hmrc_stamp_duty(), hmrc_tax_gap(), hmrc_tax_receipts(), hmrc_tobacco_duties(), hmrc_vat()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  film <- hmrc_creative_industries(sector = "film")
  tail(film)
})
options(op)

Download HMRC hydrocarbon oil (fuel duty) receipts

Description

Downloads and tidies the HMRC Hydrocarbon Oils Bulletin, which reports monthly fuel duty receipts. Data runs from January 1990 to the most recent published month, updated twice per year (January and July).

Usage

hmrc_fuel_duties(fuel = NULL, start = NULL, end = NULL, cache = TRUE)

Arguments

Details

petrol and diesel are HMRC's "Total petrol" and "Total diesel" columns. other is the sum of fuel oil, gas oil and road fuel gases. total is HMRC's total hydrocarbon oils receipts.

Value

An hmrc_tbl with columns date, fuel, description, receipts_gbp_m, and provisional (logical, TRUE for months HMRC flags as provisional).

Source

https://www.gov.uk/government/statistics/hydrocarbon-oils-bulletin

See Also

Other data fetchers: hmrc_capital_gains(), hmrc_corporation_tax(), hmrc_creative_industries(), hmrc_income_tax_stats(), hmrc_inheritance_tax(), hmrc_patent_box(), hmrc_property_transactions(), hmrc_rd_credits(), hmrc_stamp_duty(), hmrc_tax_gap(), hmrc_tax_receipts(), hmrc_tobacco_duties(), hmrc_vat()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  fuel <- hmrc_fuel_duties(fuel = "total", start = "2024-01")
  head(fuel)
})
options(op)

Download HMRC Income Tax liabilities by income range

Description

Downloads and tidies HMRC Table 2.5, which reports the number of Income Tax payers and their liabilities grouped by total income range, for each available tax year. Numbers of taxpayers are in thousands; amounts are in millions of pounds unless otherwise noted. Published annually in May/June.

Usage

hmrc_income_tax_stats(tax_year = NULL, cache = TRUE)

Arguments

Details

The earliest tax year is outturn from the Survey of Personal Incomes; later years are HMRC projections from that survey. The estimate column marks which is which. Values suppressed for small sample sizes are returned as NA.

Value

An hmrc_tbl with columns tax_year, income_range, income_lower_gbp, taxpayers_thousands, total_income_gbp_m, tax_liability_gbp_m, average_rate_pct (in per cent), average_tax_gbp, and estimate ("outturn" or "projection").

Source

https://www.gov.uk/government/statistics/income-tax-liabilities-by-income-range

See Also

Other data fetchers: hmrc_capital_gains(), hmrc_corporation_tax(), hmrc_creative_industries(), hmrc_fuel_duties(), hmrc_inheritance_tax(), hmrc_patent_box(), hmrc_property_transactions(), hmrc_rd_credits(), hmrc_stamp_duty(), hmrc_tax_gap(), hmrc_tax_receipts(), hmrc_tobacco_duties(), hmrc_vat()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  it <- hmrc_income_tax_stats()
  it[it$income_range == "All Ranges", ]
})
options(op)

Download HMRC Inheritance Tax liabilities by estate band

Description

Downloads and tidies HMRC Table 12.1a of the Inheritance Tax Liabilities Statistics: numbers of estates, tax due, average tax, and average effective tax rate, broken down by net-estate band, for the latest published year of death. Published annually in July, about two years after the end of the year of death because estates take time to settle.

Usage

hmrc_inheritance_tax(cache = TRUE)

Arguments

Value

An hmrc_tbl (long format) with columns:

tax_year

Character. Year of death, e.g. "2022-23".

estate_band_lower_gbp

Numeric. Lower limit of the net-estate band in pounds.

estate_band

Character. Plain-English label, e.g. "GBP 0-100k", "Total".

measure

Character. One of "number_not_taxed", "number_taxed", "tax_due_gbp_m", "avg_tax_gbp", "effective_rate_pct" (in per cent).

value

Numeric. Value, with ⁠[z]⁠ (no tax due to NRB) and ⁠[c]⁠ (disclosure suppression) returned as NA.

Source

https://www.gov.uk/government/statistics/inheritance-tax-liabilities-statistics

See Also

Other data fetchers: hmrc_capital_gains(), hmrc_corporation_tax(), hmrc_creative_industries(), hmrc_fuel_duties(), hmrc_income_tax_stats(), hmrc_patent_box(), hmrc_property_transactions(), hmrc_rd_credits(), hmrc_stamp_duty(), hmrc_tax_gap(), hmrc_tax_receipts(), hmrc_tobacco_duties(), hmrc_vat()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  iht <- hmrc_inheritance_tax()
  iht[iht$estate_band == "Total", ]
})
options(op)

List available tax heads in the HMRC Tax Receipts bulletin

Description

Returns a data frame describing all tax and duty heads available in hmrc_tax_receipts(). No network connection is required: the data is bundled with the package.

Usage

hmrc_list_tax_heads()

Value

A data frame with columns:

tax_head

Character. Identifier used in the tax argument of hmrc_tax_receipts().

description

Character. Plain-English description.

category

Character. Broad grouping.

available_from

Character. First year with receipts in HMRC's monthly table at the package release (NA if none in the current window).

See Also

Other infrastructure: hmrc_cache_info(), hmrc_clear_cache(), hmrc_meta(), hmrc_publications(), hmrc_search()

Examples

hmrc_list_tax_heads()

Provenance metadata of an hmrc_tbl

Description

Returns the provenance list attached to a result from any ⁠hmrc_*⁠ data fetcher: source URL, attachment URL, the GOV.UK publication timestamp of the edition (published_at), fetch time, vintage, cell methods, and so on. Useful for citation, audit trails, and reproducibility.

Usage

hmrc_meta(x)

Arguments

Value

A named list, or NULL if x has no metadata.

See Also

Other infrastructure: hmrc_cache_info(), hmrc_clear_cache(), hmrc_list_tax_heads(), hmrc_publications(), hmrc_search()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  tr <- hmrc_tax_receipts(tax = "vat", start = "2024-01")
  hmrc_meta(tr)
})
options(op)

Download HMRC Patent Box relief statistics

Description

Downloads and tidies Table 1 of the HMRC Patent Box Relief Statistics: annual number of companies electing into the Patent Box regime and the total relief claimed (in GBP million). The Patent Box was introduced from 1 April 2013; data runs from tax year 2013-14 to the most recent published year (typically with a one-year provisional lag). Published annually each September.

Usage

hmrc_patent_box(tax_year = NULL, cache = TRUE)

Arguments

Value

An hmrc_tbl with columns:

tax_year

Character. Tax year, e.g. "2023-24".

companies

Numeric. Number of companies electing into the regime (rounded to nearest 5 by HMRC).

relief_gbp_m

Numeric. Total relief in millions of pounds.

status

Character. HMRC's label for the year where it gives one (e.g. "projection" for the latest year), otherwise NA.

Source

https://www.gov.uk/government/statistics/patent-box-reliefs-statistics

See Also

Other data fetchers: hmrc_capital_gains(), hmrc_corporation_tax(), hmrc_creative_industries(), hmrc_fuel_duties(), hmrc_income_tax_stats(), hmrc_inheritance_tax(), hmrc_property_transactions(), hmrc_rd_credits(), hmrc_stamp_duty(), hmrc_tax_gap(), hmrc_tax_receipts(), hmrc_tobacco_duties(), hmrc_vat()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  hmrc_patent_box()
})
options(op)

Download monthly UK property transaction counts

Description

Downloads and tidies the HMRC Monthly Property Transactions bulletin, which counts residential and non-residential property transactions (SDLT returns, LBTT in Scotland, LTT in Wales) for England, Scotland, Wales, Northern Ireland, and the UK total. Data runs from April 2005 to the most recent completed month.

Usage

hmrc_property_transactions(
  type = c("all", "residential", "non_residential"),
  nation = NULL,
  start = NULL,
  end = NULL,
  cache = TRUE
)

Arguments

Value

An hmrc_tbl with columns date, nation, type, transactions, and provisional (logical, TRUE for months HMRC flags as provisional).

Source

https://www.gov.uk/government/statistics/monthly-property-transactions-completed-in-the-uk-with-value-40000-or-above

See Also

Other data fetchers: hmrc_capital_gains(), hmrc_corporation_tax(), hmrc_creative_industries(), hmrc_fuel_duties(), hmrc_income_tax_stats(), hmrc_inheritance_tax(), hmrc_patent_box(), hmrc_rd_credits(), hmrc_stamp_duty(), hmrc_tax_gap(), hmrc_tax_receipts(), hmrc_tobacco_duties(), hmrc_vat()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  mpt <- hmrc_property_transactions(type = "residential", nation = "england",
                                    start = "2025-01")
  head(mpt)
})
options(op)

Index of HMRC publications known to the package

Description

Tidy roster of HMRC publications, marking which are exposed via an ⁠hmrc_*⁠ function and which are on the development roadmap. Useful for planning analyses, citing the package, and tracking coverage over time.

Usage

hmrc_publications(status = c("all", "implemented", "planned"))

Arguments

Value

A data frame with one row per publication and a status column ("implemented" or "planned").

See Also

Other infrastructure: hmrc_cache_info(), hmrc_clear_cache(), hmrc_list_tax_heads(), hmrc_meta(), hmrc_search()

Examples

# Everything in the catalogue
hmrc_publications()

# Only roadmap items
hmrc_publications("planned")

Download HMRC R&D tax credit statistics

Description

Downloads and tidies the HMRC Research and Development Tax Credits Statistics publication, covering the SME R&D Relief and Research and Development Expenditure Credit (RDEC) schemes and, from 2024-25, the merged scheme and Enhanced R&D Intensive Support (ERIS). Annual data runs from 2016-17 to the most recent financial year, published annually in September.

Usage

hmrc_rd_credits(scheme = NULL, measure = NULL, cache = TRUE)

Arguments

Details

Figures for the most recent years are provisional and subject to revision as late claims are processed; the status column carries HMRC's label.

For accounting periods beginning on or after 1 April 2024 the SME and RDEC schemes were replaced by the merged scheme and ERIS. HMRC reports these inside the existing groupings, so the series stay comparable over time: sme is HMRC's "SME Total" column, which includes SME intensives and ERIS; rdec is HMRC's "RDEC & Merged RDEC Total" column ("LC & RDEC Total" in editions before September 2026), which includes merged-scheme claims by large companies and SMEs; and total is HMRC's all-schemes total. The merged scheme and ERIS are not yet returned as separate schemes.

Value

An hmrc_tbl with columns tax_year, scheme, description, measure, value, and status (HMRC's revision label, e.g. "Unchanged", "Provisional, Revised", "Provisional, Uplifted").

Source

https://www.gov.uk/government/statistics/corporate-tax-research-and-development-tax-credit

See Also

Other data fetchers: hmrc_capital_gains(), hmrc_corporation_tax(), hmrc_creative_industries(), hmrc_fuel_duties(), hmrc_income_tax_stats(), hmrc_inheritance_tax(), hmrc_patent_box(), hmrc_property_transactions(), hmrc_stamp_duty(), hmrc_tax_gap(), hmrc_tax_receipts(), hmrc_tobacco_duties(), hmrc_vat()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  rd <- hmrc_rd_credits(measure = "amount_gbp_m")
  tail(rd)
})
options(op)

Search the HMRC dataset catalogue

Description

Fuzzy keyword search across publication name, description, tags, and dataset identifier. Returns a tidy table of matching rows so users can discover what the package exposes (and what is on the roadmap).

Usage

hmrc_search(query = NULL, implemented = NULL, frequency = NULL)

Arguments

Value

A data frame, sorted with implemented datasets first.

See Also

Other infrastructure: hmrc_cache_info(), hmrc_clear_cache(), hmrc_list_tax_heads(), hmrc_meta(), hmrc_publications()

Examples

# Everything mentioning VAT
hmrc_search("vat")

# Only annual publications already implemented
hmrc_search(implemented = TRUE, frequency = "annual")

# Roadmap items mentioning capital gains
hmrc_search("capital gains", implemented = FALSE)

Download HMRC stamp duty receipts

Description

Downloads and tidies the HMRC Annual Stamp Tax Statistics, covering Stamp Duty Land Tax (SDLT), Stamp Duty Reserve Tax (SDRT) on shares, and other stamp duties. Annual data from 2003-04 to the most recent financial year, published each December.

Usage

hmrc_stamp_duty(type = NULL, cache = TRUE)

Arguments

Details

sdlt_total is SDLT on all property; shares_total is Stamp Duty Reserve Tax plus Stamp Duty on share documents; total is all stamp taxes. Land transaction taxes were devolved to Scotland (LBTT) in April 2015 and Wales (LTT) in April 2018, so SDLT after those dates covers England and Northern Ireland only.

Value

An hmrc_tbl with columns tax_year, type, description, receipts_gbp_m (rounded to nearest GBP 5m by HMRC).

Source

https://www.gov.uk/government/statistics/uk-stamp-tax-statistics

See Also

Other data fetchers: hmrc_capital_gains(), hmrc_corporation_tax(), hmrc_creative_industries(), hmrc_fuel_duties(), hmrc_income_tax_stats(), hmrc_inheritance_tax(), hmrc_patent_box(), hmrc_property_transactions(), hmrc_rd_credits(), hmrc_tax_gap(), hmrc_tax_receipts(), hmrc_tobacco_duties(), hmrc_vat()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  sd <- hmrc_stamp_duty(type = c("sdlt_total", "total"))
  tail(sd)
})
options(op)

Download HMRC tax gap estimates

Description

Downloads and tidies the HMRC Measuring Tax Gaps tables: estimates of the difference between the tax that should in theory be paid and the tax actually collected, by tax, taxpayer type and component. Since the 2026 edition HMRC publishes a consistent time series from 2005-06, and every edition revises earlier years. Published annually in June.

Usage

hmrc_tax_gap(tax = NULL, tax_year = NULL, cache = TRUE)

Arguments

Details

Rows that appear only in the GBP table (avoidance and hidden economy components) have gap_pct of NA. Estimates HMRC shows as ⁠<0.1⁠ (below GBP 0.05bn) are returned as NA. Each June edition revises the whole series, so results change between editions; hmrc_meta() records the edition's publication date.

Value

An hmrc_tbl with columns:

tax_year

Character. Tax year, e.g. "2024-25".

tax

Character. Tax group, e.g. "VAT", "Corporation Tax".

type

Character. Sub-group, e.g. "Self Assessment", "Tobacco duty", or the group total.

component

Character. Taxpayer group or duty, e.g. "Small businesses", "Cigarette duty".

gap_pct

Numeric. Tax gap as a per cent of theoretical liabilities (Table 1.1).

gap_gbp_bn

Numeric. Tax gap in GBP billion (Table 1.2).

Source

https://www.gov.uk/government/statistics/measuring-tax-gaps

See Also

Other data fetchers: hmrc_capital_gains(), hmrc_corporation_tax(), hmrc_creative_industries(), hmrc_fuel_duties(), hmrc_income_tax_stats(), hmrc_inheritance_tax(), hmrc_patent_box(), hmrc_property_transactions(), hmrc_rd_credits(), hmrc_stamp_duty(), hmrc_tax_receipts(), hmrc_tobacco_duties(), hmrc_vat()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  gap <- hmrc_tax_gap(tax = "Total tax gap")
  tail(gap)
})
options(op)

Download HMRC tax receipts and National Insurance contributions

Description

Downloads and tidies the monthly HMRC Tax Receipts and National Insurance Contributions bulletin published on GOV.UK. The bulletin covers all major UK taxes and duties at monthly frequency and is updated on approximately the 15th working day of each month. HMRC's monthly table is a rolling window: it currently starts in April 2017.

Usage

hmrc_tax_receipts(tax = NULL, start = NULL, end = NULL, cache = TRUE)

Arguments

Details

Months with no receipts for a head (for example Bank Levy outside its instalment months) are marked ⁠[X]⁠ by HMRC and returned as NA. If HMRC adds a new series to the bulletin (Vaping Products Duty is due from October 2026), it is returned under a snake_case tax_head built from its column label, with a one-off message, until the package adds it to hmrc_list_tax_heads().

Value

An hmrc_tbl (subclass of data.frame) with columns:

date

Date. The first day of the reference month.

tax_head

Character. Tax or duty identifier (see hmrc_list_tax_heads()).

description

Character. Plain-English series label.

receipts_gbp_m

Numeric. Cash receipts in millions of pounds (GBP).

Provenance metadata (source URL, fetch time, vintage) is attached as the "hmrc_meta" attribute and can be inspected with hmrc_meta().

Source

https://www.gov.uk/government/statistics/hmrc-tax-and-nics-receipts-for-the-uk

See Also

Other data fetchers: hmrc_capital_gains(), hmrc_corporation_tax(), hmrc_creative_industries(), hmrc_fuel_duties(), hmrc_income_tax_stats(), hmrc_inheritance_tax(), hmrc_patent_box(), hmrc_property_transactions(), hmrc_rd_credits(), hmrc_stamp_duty(), hmrc_tax_gap(), hmrc_tobacco_duties(), hmrc_vat()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  tr <- hmrc_tax_receipts(tax = c("income_tax", "vat"), start = "2025-04")
  head(tr)
})
options(op)

Download HMRC tobacco duty receipts

Description

Downloads and tidies the HMRC Tobacco Bulletin, which reports monthly tobacco products duty receipts by product type. Data runs from January 1991 to the most recent published month.

Usage

hmrc_tobacco_duties(product = NULL, start = NULL, end = NULL, cache = TRUE)

Arguments

Value

An hmrc_tbl with columns date, product, description, receipts_gbp_m, and provisional (logical, TRUE for months HMRC flags as provisional).

Source

https://www.gov.uk/government/statistics/tobacco-bulletin

See Also

Other data fetchers: hmrc_capital_gains(), hmrc_corporation_tax(), hmrc_creative_industries(), hmrc_fuel_duties(), hmrc_income_tax_stats(), hmrc_inheritance_tax(), hmrc_patent_box(), hmrc_property_transactions(), hmrc_rd_credits(), hmrc_stamp_duty(), hmrc_tax_gap(), hmrc_tax_receipts(), hmrc_vat()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  tob <- hmrc_tobacco_duties(product = "cigarettes", start = "2024-01")
  head(tob)
})
options(op)

Download HMRC VAT receipts

Description

Downloads and tidies the HMRC VAT Annual Statistics bulletin, which reports monthly VAT receipts broken down into payments, repayments, import VAT, and home VAT. Monthly data runs from April 1973; the bulletin is published annually (December).

Usage

hmrc_vat(measure = NULL, start = NULL, end = NULL, cache = TRUE)

Arguments

Details

Note that early years (pre-1985) have suppressed payment and repayment splits; only the total is available for those periods. From January 2021, import VAT collected via postponed VAT accounting is recorded within payments and repayments rather than the import VAT column.

Value

An hmrc_tbl with columns date, measure, description, receipts_gbp_m. Repayments are negative.

Source

https://www.gov.uk/government/statistics/value-added-tax-vat-annual-statistics

See Also

Other data fetchers: hmrc_capital_gains(), hmrc_corporation_tax(), hmrc_creative_industries(), hmrc_fuel_duties(), hmrc_income_tax_stats(), hmrc_inheritance_tax(), hmrc_patent_box(), hmrc_property_transactions(), hmrc_rd_credits(), hmrc_stamp_duty(), hmrc_tax_gap(), hmrc_tax_receipts(), hmrc_tobacco_duties()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  vat <- hmrc_vat(measure = c("total", "repayments"), start = "2024-01")
  head(vat)
})
options(op)

Tax head lookup table

Description

A data frame describing all tax and duty series available in hmrc_tax_receipts().

Usage

tax_heads

Format

A data frame with 42 rows and 4 columns:

tax_head

Character. Identifier used in the tax argument of hmrc_tax_receipts().

description

Character. Plain-English description.

category

Character. Broad grouping: "income", "nics", "consumption", "property", "environment", "other", or "total".

available_from

Character. First year with receipts in HMRC's monthly table at the package release. The table is a rolling window (currently April 2017 onwards), so long-standing taxes show the window start. NA means no receipts in the current window.

Source

Derived from the HMRC Tax Receipts and NICs bulletin. https://www.gov.uk/government/statistics/hmrc-tax-and-nics-receipts-for-the-uk