Update pension scheme
Partially update a workplace pension scheme. Creates a new configuration version effective from valid_from. Only provided fields are updated. Returns 404 if the scheme does not exist.
Authorizations
Get token from Auth0 and paste it here
Body
Create a new version of the pension scheme configuration effective from valid_from.
Only include fields that should change — unset fields are inherited from the current version.
valid_from is required and must be strictly later than the current version's valid_from.
Date from which the updated configuration takes effect; must be later than the current version's valid_from
Display name for the scheme; null = no change
Pension provider (NEST, OTHER); null = no change
NEST, OTHER Tax treatment method; null = no change. If changed, wage_type_code must also be updated to a compatible type
NET_PAY, RELIEF_AT_SOURCE, SALARY_SACRIFICE Which earnings count as pensionable; null = no change
QUALIFYING_EARNINGS, PENSIONABLE_PAY Employee contribution rate (minimum 0.05 = 5%); null = no change
0.05 <= x <= 1Employer contribution rate (minimum 0.03 = 3%); null = no change
0.03 <= x <= 1Maximum employee contribution per period (absolute amount); null = no change
Maximum employer contribution per period (absolute amount); null = no change
Months to postpone auto-enrolment for new eligible jobholders (0–3); null = no change
0 <= x <= 3Whether employer voluntarily contributes for Entitled Workers who join; null = no change
Employer's chosen cyclical re-enrolment date (every ~3 years); null = no change
Earliest permissible re-enrolment date (3 months before anniversary); null = no change
Latest permissible re-enrolment date (3 months after anniversary); null = no change
Wage type code for pension deduction line items; null = no change. Required when tax_treatment is changed
Response
Successful Response
Organisation's pension scheme configuration.
scheme_id is the stable handle identifier — use it in {scheme_id} path segments
and in membership scheme_id fields. valid_from/valid_to describe the validity
window of this particular configuration version.
Date from which this configuration version is effective
Stable handle UUID for the scheme; does not change when configuration is updated via PATCH. Use this in URL path segments and membership scheme_id fields
Whether this is the organisation's default scheme; only one scheme per org can be default. New eligible employees are auto-enrolled into the default scheme
Display name for the scheme
Pension provider (NEST = National Employment Savings Trust, OTHER = any other provider)
NEST, OTHER Tax treatment method: NET_PAY (deducted pre-tax), RELIEF_AT_SOURCE (deducted post-tax, provider claims tax relief from HMRC), SALARY_SACRIFICE (employee gives up salary; saves NIC for both parties)
NET_PAY, RELIEF_AT_SOURCE, SALARY_SACRIFICE Earnings base for contribution calculation: QUALIFYING_EARNINGS (band £6,240–£50,270/year, 2025-26), PENSIONABLE_PAY (full pay, no lower threshold)
QUALIFYING_EARNINGS, PENSIONABLE_PAY Employee contribution rate as a decimal (e.g. 0.05 = 5%); statutory minimum is 5% on qualifying earnings
^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$Employer contribution rate as a decimal (e.g. 0.03 = 3%); statutory minimum is 3% on qualifying earnings
^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$Maximum employee contribution per pay period as an absolute amount; null = no cap
^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$Maximum employer contribution per pay period as an absolute amount; null = no cap
^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$Months to postpone auto-enrolment for newly eligible jobholders (0 = enrol immediately, max 3)
Whether the employer voluntarily contributes for Entitled Workers (earnings below £6,240/year) who choose to join the scheme
Employer's chosen cyclical re-enrolment date (every ~3 years); opted-out employees are re-enrolled on this date
Earliest permissible re-enrolment date (3 months before the staging anniversary)
Latest permissible re-enrolment date (3 months after the staging anniversary)
Wage type code used for the pension deduction line item on payslip; must be PENSION category. NET_PAY/RAS use UK-P-001 or UK-P-002; SALARY_SACRIFICE requires UK-P-003
Timestamp when this configuration version was created
Date on which this version expires (exclusive); null means this is the current active version. Populated automatically when a newer version is created via PATCH
User identifier (from JWT sub) who created this version; null if created by the system