specification: API Commons Plans
specificationVersion: '0.1'
schema: https://raw.githubusercontent.com/api-evangelist/interface-research/main/schema/api-commons.yml#/$defs/Plans
provider: HMRC UK Tax Authority
providerId: hmrc
created: '2026-05-04'
# Provenance stamped 2026-08-11: this artifact was written by the API Evangelist
# bulk sweep dated 2026-05-04, not harvested from the provider. See roadmap#35.
method: generated
modified: '2026-05-05'
reconciled: true
tags:
  - Government
  - Making Tax Digital
  - Regulatory
  - Tax
  - UK
description: HMRC's Developer Hub APIs are free of charge for all software vendors and businesses. Access is
  gated by HMRC application registration, OAuth user authorization, and software-recognition for production
  endpoints; there are no paid tiers. The platform distinguishes a sandbox environment from production, and
  provides a single rate-limit ceiling that can be raised by request via HMRC support. This artifact models
  HMRC's offering as a single free Developer plan plus a partner-recognition track for software vendors.
sources:
  - https://developer.service.hmrc.gov.uk/api-documentation
  - https://developer.service.hmrc.gov.uk/api-documentation/docs/reference-guide
  - https://developer.service.hmrc.gov.uk/api-documentation/docs/terms-of-use
plans:
  - id: hmrc-developer
    name: Developer (Sandbox + Production)
    type: freemium
    description: Free access to all HMRC Developer Hub APIs, including sandbox and production. Available to
      registered software developers; production traffic is subject to a 3 requests/second per-application
      throttle and to HMRC's Terms of Use, fraud-prevention header requirements, and software recognition
      where applicable.
    entries:
      - label: API Requests
        description: HMRC does not publish a per-month request quota; usage is governed by the 3 RPS
          per-application throttle plus fraud-prevention header requirements
        name: api_requests
        type: quota
        metric: requests
        limit: -1
        timeFrame: month
        geo: UK
        domains:
          - https://api.service.hmrc.gov.uk
          - https://test-api.service.hmrc.gov.uk
        unit: 1
        price: '0.00'
        userMultiplied: false
      - label: Per-Application Rate Limit
        description: Default per-application steady-state limit on production
        name: rate_limit
        type: rate
        metric: requests_per_second
        limit: 3
        timeFrame: second
        geo: UK
        domains:
          - https://api.service.hmrc.gov.uk
        unit: 1
        price: '0.00'
        userMultiplied: false
      - label: Sandbox Access
        description: Free sandbox environment for testing
        name: sandbox
        type: quota
        metric: requests
        limit: -1
        timeFrame: month
        geo: UK
        domains:
          - https://test-api.service.hmrc.gov.uk
        unit: 1
        price: '0.00'
        userMultiplied: false
    elements:
      - name: Free of Charge
      - name: OAuth 2.0 User Authorization
      - name: Application Registration Required
      - name: Sandbox Environment
      - name: Public Documentation
      - name: Fraud Prevention Headers Required
      - name: HMRC VAT (Making Tax Digital) API
      - name: HMRC Self Assessment API
      - name: HMRC PAYE (Pay As You Earn) API
      - name: HMRC Customs Declarations API
      - name: HMRC Corporation Tax API
  - id: hmrc-recognised-software
    name: Recognised Software Vendor
    type: enterprise
    description: Free access tier for software vendors whose products have been formally recognised by HMRC
      for Making Tax Digital, PAYE, Self Assessment, etc. No additional fee; status enables product listing
      on HMRC's recognised-software pages and access to vendor-support channels.
    entries:
      - label: API Requests
        description: Same per-application throttle as the Developer plan; raise requests can be lodged with
          HMRC SDS Team
        name: api_requests
        type: quota
        metric: requests
        limit: -1
        timeFrame: month
        geo: UK
        domains:
          - https://api.service.hmrc.gov.uk
        unit: 1
        price: '0.00'
        userMultiplied: false
      - label: Default Rate Limit
        description: Per-application throttle, raisable by support request
        name: rate_limit
        type: rate
        metric: requests_per_second
        limit: 3
        timeFrame: second
        geo: UK
        domains:
          - https://api.service.hmrc.gov.uk
        unit: 1
        price: '0.00'
        userMultiplied: false
    elements:
      - name: Free of Charge
      - name: HMRC Recognised Software Listing
      - name: SDS Team Support
      - name: Eligible for Rate-Limit Uplift
      - name: HMRC VAT (Making Tax Digital) API
      - name: HMRC Self Assessment API
      - name: HMRC PAYE (Pay As You Earn) API
      - name: HMRC Customs Declarations API
      - name: HMRC Corporation Tax API
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com
x-canonical:
  generated: '2026-10-08'
  vocabulary: all/0-working/economics/plans-canonical.yml
  models:
  - free
  units:
  - rate
  - request
  plans:
  - name: Developer (Sandbox + Production)
    access: freemium
    model: free
    model_how: derived
    units:
    - rate
    - request
    periods:
    - month
    - second
  - name: Recognised Software Vendor
    access: enterprise
    model: free
    model_how: derived
    units:
    - rate
    - request
    periods:
    - month
    - second