specification: FinOps Framework
specificationVersion: '1.0'
alignedWith:
  framework: FinOps Foundation Framework
  frameworkUrl: https://www.finops.org/framework/
  dataSpec: FOCUS
  dataSpecVersion: '1.3'
  dataSpecUrl: https://focus.finops.org/focus-specification/v1-3/
provider: HMRC UK Tax Authority
providerId: hmrc
publisherName: HM Revenue & Customs
serviceCategory: Government / Tax
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
  - FinOps
  - Cost Management
  - FOCUS
description: 'FOCUS-aligned FinOps definition for HMRC. The HMRC Developer Hub APIs themselves are zero-cost
  to consumers; FinOps for HMRC therefore tracks the indirect cost of integration (rate-limit-driven design,
  software-recognition compliance, fraud-prevention overhead) rather than direct billing. ChargeCategory
  for HMRC API usage is effectively zero / not-billed.'
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
billingModel:
  pricingCategory: Free / No Charge
  billingFrequency: Not Applicable
  billingCurrency: GBP
  chargeCategories:
    - Adjustment
  chargeFrequency: Not Applicable
  notes: HMRC does not invoice for API access. Internal cost is consumer integration effort + dependent SaaS
    fees from the consuming software vendor.
focusColumns:
  ServiceName: HMRC Developer Hub
  ServiceCategory: Government / Tax
  ProviderName: HMRC UK Tax Authority
  PublisherName: HM Revenue & Customs
  InvoiceIssuerName: 'Not applicable (free service)'
  PricingCategory: Free
  PricingUnit: request
  BillingCurrency: GBP
  ChargeCategory: Adjustment
principles:
  - name: Visibility
    description: Use the HMRC Developer Hub application dashboard to monitor request volume and 429 rates
      per registered application. Capture Request-Id correlation IDs and Gov-Client-* fraud-prevention
      header values in your observability pipeline.
  - name: Allocation
    description: Allocate engineering and integration cost by HMRC API family (VAT MTD, Self Assessment,
      PAYE, Customs Declarations, Corporation Tax). Tag traffic by tax-period and by the end-customer of
      the consuming software so internal recharge to the relevant product line is possible.
  - name: Optimization
    description: HMRC penalises batching; design submission flows around real-time user actions to stay
      under the 3 RPS per-application throttle. Cache reference data (rates, codes) where HMRC permits to
      reduce gateway pressure. If sustained throughput is required, lodge a rate-limit-uplift request with
      HMRC SDS rather than spawning multiple applications.
  - name: Accountability
    description: Assign a named owner per HMRC API integration who is responsible for software-recognition
      status, fraud-prevention header correctness, Terms-of-Use compliance, and incident response when HMRC
      issues 503 / SCHEDULED_MAINTENANCE notices.
domains:
  - name: Understand Usage and Cost
    capabilities:
      - Data Ingestion
      - Allocation
      - Reporting and Analytics
      - Anomaly Management
  - name: Quantify Business Value
    capabilities:
      - Planning and Estimating
      - Forecasting
      - Budgeting
      - Benchmarking
      - Unit Economics
  - name: Optimize Usage and Cost
    capabilities:
      - Rate Optimization
      - Workload Optimization
      - Licensing and SaaS
  - name: Manage the FinOps Practice
    capabilities:
      - FinOps Practice Operations
      - FinOps Education and Enablement
      - Onboarding Workloads
      - Intersecting Disciplines
meters:
  - name: api_requests
    description: Count of requests sent to HMRC APIs per registered application
    unit: request
    aggregation: sum
    dimensions:
      - api
      - environment
      - application_id
      - tax_period
      - end_customer
  - name: throttled_responses
    description: Count of HTTP 429 / MESSAGE_THROTTLED_OUT responses, used as a leading indicator for
      design changes or rate-limit uplift requests
    unit: response
    aggregation: sum
    dimensions:
      - api
      - application_id
  - name: maintenance_events
    description: Count of 503 SCHEDULED_MAINTENANCE / SERVER_ERROR responses
    unit: event
    aggregation: sum
    dimensions:
      - api
  - name: recognised_software_status
    description: Indicator that the consuming product holds HMRC Recognised Software status for a given
      tax regime
    unit: status
    aggregation: max
    dimensions:
      - api
      - application_id
apis:
  - name: HMRC VAT (Making Tax Digital) API
    baseURL: https://api.service.hmrc.gov.uk
    tags:
      - Government
      - Making Tax Digital
      - REST
      - Tax
      - UK
      - VAT
    serviceName: HMRC VAT (Making Tax Digital) API
    serviceCategory: Government / Tax
  - name: HMRC Self Assessment API
    baseURL: https://api.service.hmrc.gov.uk
    tags:
      - Government
      - Income Tax
      - REST
      - Self Assessment
      - Tax
      - UK
    serviceName: HMRC Self Assessment API
    serviceCategory: Government / Tax
  - name: HMRC PAYE (Pay As You Earn) API
    baseURL: https://api.service.hmrc.gov.uk
    tags:
      - Government
      - PAYE
      - Payroll
      - REST
      - Tax
      - UK
    serviceName: HMRC PAYE (Pay As You Earn) API
    serviceCategory: Government / Tax
  - name: HMRC Customs Declarations API
    baseURL: https://api.service.hmrc.gov.uk
    tags:
      - Customs
      - Excise
      - Government
      - REST
      - Tax
      - UK
      - XML
    serviceName: HMRC Customs Declarations API
    serviceCategory: Government / Tax
  - name: HMRC Corporation Tax API
    baseURL: https://api.service.hmrc.gov.uk
    tags:
      - Business
      - Corporation Tax
      - Government
      - REST
      - Tax
      - UK
    serviceName: HMRC Corporation Tax API
    serviceCategory: Government / Tax
unitEconomics:
  - name: Throttle Pressure
    metric: throttled_responses / api_requests
  - name: Cost per HMRC Submission (consumer side)
    metric: consumer_engineering_and_saas_cost / submissions
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com