> ## Documentation Index > Fetch the complete documentation index at: https://docs.intermezzo.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update per-employee pension rates > Update an employee's per-employee pension contribution rates. Creates a new membership history version effective from the specified valid_from date. Override rates must be >= the scheme minimums (HMRC AE compliance). If tax_treatment is overridden, wage_type_code must also be provided. ## OpenAPI ````yaml /api-reference/preview.json patch /gb/organizations/{organization_id}/employees/{employee_id}/pension/rates openapi: 3.1.0 info: title: FastAPI version: 0.1.0 servers: [] security: [] paths: /gb/organizations/{organization_id}/employees/{employee_id}/pension/rates: patch: tags: - Great Britain - Pension summary: Update per-employee pension rates description: >- Update an employee's per-employee pension contribution rates. Creates a new membership history version effective from the specified valid_from date. Override rates must be >= the scheme minimums (HMRC AE compliance). If tax_treatment is overridden, wage_type_code must also be provided. operationId: >- update_pension_rates_gb_organizations__organization_id__employees__employee_id__pension_rates_patch parameters: - name: organization_id in: path required: true schema: anyOf: - type: string - type: string format: uuid title: Organization Id - name: employee_id in: path required: true schema: anyOf: - type: string - type: string format: uuid title: Employee Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PensionRateUpdateRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PensionMembershipResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - BearerToken: [] components: schemas: PensionRateUpdateRequest: properties: valid_from: type: string format: date title: Valid From description: Effective date of the rate change employee_rate: anyOf: - type: number maximum: 1 minimum: 0 - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Employee Rate description: Employee contribution rate override employer_rate: anyOf: - type: number maximum: 1 minimum: 0 - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Employer Rate description: Employer contribution rate override employee_cap: anyOf: - type: number minimum: 0 - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Employee Cap description: Per-period employee contribution cap override employer_cap: anyOf: - type: number minimum: 0 - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Employer Cap description: Per-period employer contribution cap override tax_treatment: anyOf: - $ref: '#/components/schemas/PensionTaxTreatment' - type: 'null' description: Per-employee tax treatment override wage_type_code: anyOf: - type: string - type: 'null' title: Wage Type Code description: Wage type code; MUST be provided when tax_treatment is set additionalProperties: true type: object required: - valid_from title: PensionRateUpdateRequest description: >- Request to update per-employee pension contribution rates. Creates a new membership history version effective from valid_from. Standard PATCH semantics: - Field **omitted** from the request body → carry forward the current value unchanged. - Field explicitly set to **null** → clear the override (fall back to scheme default). - Field set to a **value** → apply as the new override. PensionMembershipResponse: properties: valid_from: type: string format: date title: Valid From description: Date from which this version of the membership record is effective valid_to: anyOf: - type: string format: date - type: 'null' title: Valid To description: >- Date on which this version expires (exclusive); null = current version. Set automatically when a new version is created employee_rate: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Employee Rate description: >- Per-employee employee contribution rate override; null = use scheme default employer_rate: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Employer Rate description: >- Per-employee employer contribution rate override; null = use scheme default employee_cap: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Employee Cap description: >- Per-employee maximum employee contribution per period; null = use scheme default employer_cap: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Employer Cap description: >- Per-employee maximum employer contribution per period; null = use scheme default tax_treatment: anyOf: - $ref: '#/components/schemas/PensionTaxTreatment' - type: 'null' description: >- Per-employee tax treatment override (e.g. RELIEF_AT_SOURCE for an employee whose scheme is SALARY_SACRIFICE); null = use scheme default wage_type_code: anyOf: - type: string - type: 'null' title: Wage Type Code description: >- Per-employee wage type code override for the payslip deduction line; null = use scheme default. Required when tax_treatment override is set status: $ref: '#/components/schemas/PensionMembershipStatus' description: >- Current membership status: ACTIVE (enrolled, contributions calculated), OPTED_OUT (left the scheme; contributions refunded if within 1-month opt-out window), NOT_ENROLLED (no active membership) version: type: integer title: Version description: >- Sequential version number of this membership record; starts at 0, incremented on each change (status change, rate update, etc.) worker_category: anyOf: - $ref: '#/components/schemas/WorkerCategory' - type: 'null' description: >- AE worker category at enrolment time: ELIGIBLE_JOBHOLDER (age 22–SPA, earnings ≥ trigger — employer must enrol), NON_ELIGIBLE_JOBHOLDER (outside age/earnings band — can opt in), ENTITLED_WORKER (earnings below lower limit — can join, employer need not contribute), EXCLUDED (not subject to AE). Null if not yet enrolled entry_route: anyOf: - $ref: '#/components/schemas/PensionEntryRoute' - type: 'null' description: >- How the employee entered the scheme: AUTO_ENROLLED (system enrolled automatically at payroll approval), OPTED_IN (employee requested enrolment), JOINED (entitled worker chose to join). Null if not enrolled enrolment_date: anyOf: - type: string format: date - type: 'null' title: Enrolment Date description: Date on which the membership became ACTIVE; null if not yet enrolled opt_out_date: anyOf: - type: string format: date - type: 'null' title: Opt Out Date description: Date the employee opted out; null if not opted out enrolment_communication_date: anyOf: - type: string format: date - type: 'null' title: Enrolment Communication Date description: >- Date the statutory enrolment letter was issued to the employee; used to validate the 1-month opt-out window scheme_id: anyOf: - type: string - type: 'null' title: Scheme Id description: >- UUID of the pension scheme the employee is enrolled in; null for legacy memberships created before multi-scheme support (engine falls back to the org's default scheme) created_at: type: string format: date-time title: Created At description: Timestamp when this version of the membership record was created created_by: anyOf: - type: string - type: 'null' title: Created By description: >- User identifier who created this version; null if created by the system (e.g. auto-enrolment) additionalProperties: true type: object required: - valid_from - status - version - worker_category - entry_route - enrolment_date - opt_out_date - enrolment_communication_date - scheme_id - created_at - created_by title: PensionMembershipResponse description: >- Current pension membership state for an employee. Reflects the latest (highest version) membership history record. Per-employee rate override fields (employee_rate, employer_rate, etc.) are null when the scheme defaults apply; non-null values take precedence over the scheme. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError PensionTaxTreatment: type: string enum: - NET_PAY - RELIEF_AT_SOURCE - SALARY_SACRIFICE title: PensionTaxTreatment PensionMembershipStatus: type: string enum: - ACTIVE - OPTED_OUT - NOT_ENROLLED title: PensionMembershipStatus WorkerCategory: type: string enum: - ELIGIBLE_JOBHOLDER - NON_ELIGIBLE_JOBHOLDER - ENTITLED_WORKER - EXCLUDED title: WorkerCategory PensionEntryRoute: type: string enum: - AUTO_ENROLLED - OPTED_IN - JOINED title: PensionEntryRoute ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: BearerToken: type: oauth2 flows: password: scopes: read:all: Read all write:all: Write all read:health_check: Read health check write:health_check: Write health check read:wage_types: Read wage types write:wage_types: Write wage types tokenUrl: >- https://auth-preview.intermezzo.ai/authorize?audience=api-preview.intermezzo.ai ````