Last updated Jun 14, 2026

Payroll and benefits handoff

Matter is not a payroll system and is not a benefits administrator. The product surface around employees stops at the boundary of corporate governance and statutory legal documents. Wage processing, withholding remittance, plan administration, and per-employee election tracking happen in dedicated systems — payroll providers (Gusto, Rippling, Justworks, Paychex, ADP), retirement-plan record-keepers (Guideline, Vanguard, Fidelity), and benefits administrators (TASC, WageWorks, the insurance carriers themselves).

This page is the architectural commitment that defines that boundary. The endpoints in api/manage/employees, api/manage/state-registrations, and api/exit/dissolution honour it. PRs that propose extending Matter into recurring wage flow or plan administration should be read against this page first.

What Matter does

Matter owns the corporate-governance and account-existence surface around employment and benefits. Specifically:

Account existence

• State employer registrations. StateRegistration (reg_*) tracks whether the entity has an open employer account in a given state — the account that withholds state income tax, files SUTA wage reports, and carries the employer's PFML/TDI/SDI status where applicable. Matter opens these accounts via the registered-agent partner, surfaces the account ID + recurring filing schedule on the Compliance calendar, and closes the account when the entity dissolves.
• Bank accounts. BankAccount (bka_*) records linkage to the partner bank (Mercury, Column). Matter does not move money; it records the account exists, captures the linkage attestation, and tracks closure intent.
• Payroll-provider linkage. payroll_provider_attestation is a Document.kind that records which payroll provider the entity has connected (Gusto, Rippling, etc.) plus the provider's external account identifier and the state-registration IDs the provider has been given. The attestation is a static record; the per-cycle flow lives in the provider.
• Benefit-plan linkage. benefit_plan_attestation is a Document.kind that records which retirement-plan record-keeper the entity has engaged (Guideline, Vanguard, etc.), the plan-document opinion-letter reference, and the trustee designation. Plan administration happens with the record-keeper; Matter records the engagement.

Corporate authorisations

• Resolutions for employment/benefits actions: adopting a benefit plan, terminating one, designating an officer-slate change, authorising an employer-account opening or closure. These are board or sole-director consents — pure governance.
• Authorizations for high-stakes signed actions: the Authorization pause that gates entities.dissolve, plan-termination resolutions, major officer-slate changes.

Statutory legal documents

These are documents whose content is shaped by law — the entity generates them as a legal duty, regardless of which payroll/benefits provider runs the underlying operations:

• cobra_qualifying_event_notice, cobra_general_notice, cobra_election_form, cobra_termination_notice — COBRA notices have prescribed contents under federal law (qualifying-event type, coverage loss date, premium amount, 60-day election window). Matter generates the notice from a template; the election is captured by the benefits administrator or carrier, not Matter.
• insurance_policy_termination_notice and benefits_carrier_termination_acknowledgement — formal termination of a group policy with an insurance carrier (Anthem, MetLife). Legal documents Matter generates and stores.
• notice_of_dissolution, creditor_publication_record — DGCL §281 creditor notices. Matter generates and tracks delivery.
• plan_of_dissolution, liquidating_distribution_statement — DGCL §275 governance documents.
• payroll_provider_attestation, benefit_plan_attestation — the linkage records described above.

Compliance calendar entries

Compliance view lists that obligations are due (Form 941 quarterly, W-2 by Jan 31, 1099-NEC by Jan 31, Form 5500 by July 31 + extension, state SUTA quarterly, ACA 1094-C/1095-C if ALE, etc.). The calendar entries say what's due, when, in which jurisdiction. The actual return content is the provider's responsibility; the obligation tracking is Matter's. The provider acknowledges filed status by webhook, flipping the Filing's status to accepted on Matter's side.

Account closures

closeBankAccount, terminateRegisteredAgent, closeStateRegistration all share the same shape: Matter records the closure intent, captures the partner system's acknowledgement Document, and updates the entity's status. The actual closure happens off-Matter (banks require wet signature; SoS offices process state filings; payroll providers disconnect from the state account before account closure).

What Matter does NOT do

These belong to payroll providers, benefits administrators, or retirement-plan record-keepers — not to Matter.

Wage processing

• Running payroll cycles. Computing gross-to-net, generating pay stubs, depositing wages, paying contractors. Matter has no runPayrollCycle verb and no PayrollCycle resource at the per-cycle level.
• Withholding remittance. Federal 941 deposits, state withholding payments, FUTA/SUTA payments, FICA contributions. The payroll provider remits to the IRS and to each state revenue authority.
• Form 941 / 940 / W-2 / W-3 / 1099-NEC content. The provider files these. Matter tracks the obligation (it's on the calendar; it's due by date X) but not the form contents. A Filing resource of type: form_941 records the obligation and accepts an acknowledgement attestation when the provider confirms filing.
• State withholding final returns / SUTA final reports. Same pattern — Matter has Filing.type enums for the per-state withholding final returns (ca_state_withholding_final, ny_state_withholding_final, etc.) so the obligation is categorised, but the provider files them.

Per-employee benefits flow

• COBRA election tracking. Matter generates the notice; the benefits administrator records who elected, who waived, who timed out. Matter has no CobraElection resource.
• Premium remittance. COBRA premium collection, employer-share premium payments, FSA/HSA contributions. Provider domain.
• Benefits enrollment. Open-enrollment flows, qualifying-life-event enrollment changes, dependent additions, beneficiary designations. All benefits-administrator domain.
• ALE designation. Whether the entity is an Applicable Large Employer (50+ FTE) for ACA purposes is computed by the payroll provider from headcount and hours data the provider already holds. Matter does not expose /v1/entities/{id}/ale_status; the provider computes it and surfaces it on filed 1094-C / 1095-C.
• ACA 1094-C / 1095-C content. Provider files these; Matter tracks the obligation on the compliance calendar.

Retirement-plan administration

• The plan document and trust. A 401(k) plan is a legal entity separate from the sponsoring corporation under ERISA. The plan trust is administered by the record-keeper.
• Form 5500 / Form 5310 content. The record-keeper files these; Matter records the obligation and the board resolution authorising plan termination.
• Participant distributions. Account-balance distributions, rollover elections, IRS withholding on early distributions, Form 1099-R issuance. All record-keeper domain.
• Plan-administrator role. Matter records who the plan administrator is (a post_dissolution_responsible_persons[] entry on the dissolved entity, when relevant); the administrator's day-to-day responsibilities live with the record-keeper.

How handoff works

The pattern is the same in every direction: Matter records the authorisation; the provider runs the flow; the provider acknowledges back.

                   ┌─────────────────────────┐
                   │   Matter (governance)   │
                   │  - Resolution authoring │
                   │  - StateRegistration    │
                   │  - Filing (obligation)  │
                   │  - Provider attestation │
                   └────────────┬────────────┘
                                │
           "open account"       │       "filed Form 941"
           (one-time)           │       (recurring)
                                ▼
                   ┌─────────────────────────┐
                   │  Provider (Gusto et al) │
                   │  - Run cycles           │
                   │  - Remit withholdings   │
                   │  - File 941/W-2/1099    │
                   │  - Issue Form 1099-R    │
                   └────────────┬────────────┘
                                │
                    Webhook acknowledgement
                                │
                                ▼
                   ┌─────────────────────────┐
                   │   Matter (governance)   │
                   │  - Filing.status →      │
                   │    accepted             │
                   │  - Calendar advances    │
                   └─────────────────────────┘

When the entity dissolves, the handoff inverts cleanly:

1. Matter generates the board resolution authorising plan termination and the COBRA notices. Matter writes the per-state employer-account final-return obligations onto the compliance calendar.
2. The payroll provider runs the final cycle, files the final 941 / 940 / W-2 / 1095-C, and issues acknowledgements.
3. The retirement-plan record-keeper files Form 5310 / Form 5500-final, distributes account balances, and issues 1099-R forms.
4. Matter closes the StateRegistration (closeStateRegistration), closes the BankAccount (closeBankAccount), terminates the RegisteredAgent (terminateRegisteredAgent), and finally files the Certificate of Dissolution.

The dissolution cascade documented in /cookbook/dissolve-an-entity sequences these steps with Filing.depends_on[] so step 4 cannot fire until steps 1–3 are acknowledged.

Why the boundary

Two reasons.

Specialisation matters

Payroll, benefits, and retirement-plan administration are deep, heavily-regulated domains with active platforms that have invested years in compliance infrastructure. Matter's edge is the entity-as-object surface — formation, governance, equity, filings, dissolution. Pulling payroll into Matter would compete on a surface where Matter has no advantage and would dilute the framing that makes the entity-as-object surface coherent.

Source-of-truth ownership

Wage data, hours data, plan-balance data — these are continuously updated by the provider and the entity's HR / finance team. If Matter mirrored them, Matter would either (a) be permanently stale, or (b) need to assume source-of-truth ownership and force migration off the provider. Both are bad outcomes. The handoff pattern lets Matter own governance — which is naturally low-frequency, signed, and durable — while the provider owns flow.

Adding a handoff for a new domain

When a new employment / benefits / payroll surface comes up (PEO, EOR, international payroll, pension plans, self-funded health plans, etc.), the design pattern is:

1. Identify the corporate-authorisation moment. Is there a board resolution, a signed contract, a registered account? That part is Matter — model it as a Resolution, a Document, a StateRegistration, a partner attestation Document.
2. Identify the recurring flow. Wage cycles, premium remittance, plan accruals, claim adjudications? That's the provider — Matter does not model it.
3. Identify the legal documents the entity must generate. COBRA notices, plan-termination resolutions, dissolution notices? Matter models these as Document.kind enum values with templates.
4. Identify the calendar obligations. Annual filings, quarterly reports, statutory deadlines? Matter writes these to the Compliance calendar; provider acknowledges via Filing.status transitions.
5. Identify the account closures. When the entity dissolves or moves off the provider, what closes? Matter exposes a closure verb that records intent + captures the provider's acknowledgement Document.

If a proposal cannot be expressed in those five buckets without inventing a recurring-flow resource, it crosses the line. Either the proposal needs to be reshaped, or it belongs in the provider — not in Matter.