Build MTD ITSA Quarterly Update (JSON)

Skill: Convert business income & expenses into a quarterly MTD Income Tax update

Region: United Kingdom Category: Tax — Making Tax Digital for Income Tax (MTD ITSA) Does: Takes a business's income and expense totals for a period and maps them onto the JSON body for HMRC's MTD for Income Tax quarterly update API, per business source (self-employment / UK & foreign property). Spec: HMRC MTD for Income Tax REST API — cumulative quarterly update (JSON over OAuth 2.0, fraud-prevention headers)

Mandatory from 6 April 2026 for sole traders & landlords with qualifying income over £50,000 (over £30,000 from April 2027). Quarterly updates are cumulative from the start of the tax year; the year is finalised separately by the Final Declaration (see build-mtd-itsa-final-declaration-json).

When this applies

• Each quarterly period per business source, submit a cumulative income/expense summary by the deadline (standard periods 6 Apr–5 Jul, 6 Jul–5 Oct, 6 Oct–5 Jan, 6 Jan–5 Apr, due the 7th after period end; or calendar-quarter election to 30 Jun/30 Sep/31 Dec/31 Mar).
• One submission per business (each self-employment and each property business is reported separately).

Structure (cumulative update → JSON)

{
  "periodDates": { "periodStartDate": "2026-04-06", "periodEndDate": "2026-07-05" },
  "periodIncome":   { "turnover": 0.00, "other": 0.00 },
  "periodExpenses": {            // category breakdown (or "consolidatedExpenses")
    "costOfGoods": 0.00, "paymentsToSubcontractors": 0.00, "wagesAndStaffCosts": 0.00,
    "premisesRunningCosts": 0.00, "adminCosts": 0.00, "advertisingCosts": 0.00,
    "interestOnBankOtherLoans": 0.00, "financeCharges": 0.00,
    "professionalFees": 0.00, "depreciation": 0.00, "other": 0.00
  }
}

Mapping & rules

• Cumulative basis — figures are year-to-date from 6 April to the period end (not just the quarter); each update supersedes the prior one for the same tax year.
• Per business source — submit against the correct businessId; self-employment uses the SE schema, property uses the UK/foreign property schema (with consolidatedExpenses permitted under the turnover threshold).
• Decimals — all monetary fields are GBP to 2 decimal places; expenses are categorised, or a single consolidatedExpenses figure is used where eligible.
• Quarterly period set — use the standard or calendar quarter dates consistently for the tax year per the business's election.
• API — call within the OAuth-authorised user session with the required fraud-prevention (Gov-Client/Gov-Vendor) headers; updates are estimates, with accounting adjustments made at Final Declaration.

Worked example (Q1, self-employment)

{
  "periodDates": { "periodStartDate": "2026-04-06", "periodEndDate": "2026-07-05" },
  "periodIncome": { "turnover": 18000.00, "other": 0.00 },
  "periodExpenses": { "costOfGoods": 4000.00, "premisesRunningCosts": 1200.00,
                      "adminCosts": 800.00, "other": 0.00 }
}

Submitted to the MTD ITSA quarterly-update endpoint for the business's businessId, due 7 Aug 2026.

Validation checklist

• Correct business source / businessId and SE vs property schema
• Figures are cumulative year-to-date, not single-quarter
• Standard or calendar quarter dates used consistently for the year
• Income/expense categories valid (or eligible consolidatedExpenses); GBP 2 dp
• Submitted by the 7th after the period end (standard) under the £50k mandation (Apr 2026)
• OAuth session + fraud-prevention headers present; this is an estimate, not the final figure
• Year to be finalised by the separate Final Declaration

Last updated: 2026-06-02 — MTD ITSA mandation thresholds, quarterly-period rules, and the API schema are phasing in from April 2026; confirm the current API version, period rules, and mandation thresholds against current HMRC MTD ITSA developer documentation before use.