---
title: "Change a mandate, or pause, resume or end it"
method: PATCH
path: "/api/v1/mandates/{id}"
tags: ["lodestar"]
---

# Change a mandate, or pause, resume or end it

`PATCH /api/v1/mandates/{id}`

## Request

- Base URL: `https://worthune.com`
- URL: `https://worthune.com/api/v1/mandates/{id}`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Api-Key`

objective, constraints and approvalPolicy are each replaced whole. Status moves draft → active ⇄ paused → ended; ending is final and withdraws pending proposals. The household and type never change.

## Request body

- object
  - `objective` object
  - `constraints` object
  - `approvalPolicy` object
  - `status` 'draft' | 'active' | 'paused' | 'ended'
  - `expectedVersion` integer

## Response `200`

Updated.

- object
  - `ok` unknown, required
  - `mandate` Mandate, required
    - `id` integer, required
    - `householdId` integer, nullable, required: null for a book mandate (rules-change).
    - `scope` 'household' | 'book', required
    - `type` 'strategy-watch' | 'tax-optimization' | 'rules-change', required: strategy-watch and tax-optimization work one household; rules-change works the book (Growth and above).
    - `typeVersion` string, required
    - `objective` object, required
      - `target` 'maximize-ending-net-worth' | 'minimize-lifetime-tax', required
      - `statement` string, required
    - `constraints` object, required
      - `profile` object: Pinned assumption profile; exactly one of profile and assumptions.
        - `id` string, required
        - `version` string, required
      - `assumptions` ProjectionAssumptions: Unknown keys are rejected — the accepted set is exactly: annualReturn, inflationRate, defaultIncomeGrowth, socialSecurityCola, returnsByWrapper.
        - `annualReturn` number, required: Nominal annual return applied to every account balance (one blended rate).
        - `inflationRate` number, required: Annual inflation applied to inflation-adjusted expense streams.
        - `defaultIncomeGrowth` number, required: Growth for income streams that carry no growthRate of their own.
        - `socialSecurityCola` number: COLA applied to COMPUTED social_security benefits from each benefit's start year. Defaults to inflationRate; pass 0 for a flat benefit.
        - `returnsByWrapper` object: Per-wrapper returns; unlisted wrappers keep the blended annualReturn.
          - `taxable` number: Return for taxable accounts, replacing annualReturn (and any sampled path) for that wrapper.
          - `traditional` number: Return for traditional accounts, replacing annualReturn (and any sampled path) for that wrapper.
          - `roth` number: Return for roth accounts, replacing annualReturn (and any sampled path) for that wrapper.
          - `hsa` number: Return for hsa accounts, replacing annualReturn (and any sampled path) for that wrapper.
          - `plan529` number: Return for plan529 accounts, replacing annualReturn (and any sampled path) for that wrapper.
          - `cash` number: Return for cash accounts, replacing annualReturn (and any sampled path) for that wrapper.
          - `annuity` number: Return for annuity accounts, replacing annualReturn (and any sampled path) for that wrapper.
      - `horizonYears` integer, required: The horizon starts in the UTC year of each cycle.
      - `strategies` string[]: Default: every strategy the type runs.
      - `taxRates` object
        - `marginalOrdinary` number, required
        - `qualifiedAndLtcg` number, required
      - `illustrativeCharacteristics` boolean
      - `ladderCandidates` object[]
        - `annualAmountUsd` number, required
        - `years` integer, required
      - `bracketFill` object: bracket-fill: rates to fill (default 12, 22, 24) and years to convert (default 10).
        - `fillToRatesPct` number[]
        - `years` integer
      - `charitableGiving` object: charitable-giving: the household's cash gifts each year (required for the strategy to run), other itemized deductions (default 0), the bunching cycle (default 2) and the IRA distributions a QCD can replace (default the first year's RMD).
        - `annualGivingUsd` number, required
        - `otherItemizedDeductionsUsd` number
        - `bunchYears` integer
        - `iraDistributionsUsd` number
      - `maxHouseholds` integer: rules-change only: households per book cycle (default 1,000; the rest are reported).
      - `materialityFloorUsd` number: Default 1,000. A candidate below it is not proposed unless it removes or delays a ruin year.
      - `cooldownDays` integer: Default 30, per strategy, after a proposal is approved, rejected or expires.
      - `maxOpenProposals` integer: Default 3.
      - `reviewCadence` 'none' | 'monthly' | 'quarterly': Default quarterly.
      - `planner` 'on' | 'off': Household mandates. Default off. "on" runs each cycle through the organization's planner model when one is assigned and certified for this mandate type (and the deployment allows it); otherwise the cycle is deterministic, and its outcome says why. The planner chooses among proposals the gate would pass, never adds one.
    - `approvalPolicy` object, required
      - `approvers` 'approver-or-owner', required
      - `expiresAfterDays` integer, required: Default 30; a proposal with a deadline expires at the deadline when that is sooner.
    - `status` 'draft' | 'active' | 'paused' | 'ended', required
    - `version` integer, required
    - `lastReviewPeriod` string, nullable
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
    - `endedAt` string, date-time, nullable

## Other responses

- `400`: Malformed JSON, a body of the wrong shape, or a top-level field that fails its check.
- `401`: No key presented (Authorization: Bearer wk_… or X-Api-Key).
- `402`: Unrecognized or revoked API key.
- `403`: The key's role is below the operation's floor (viewer < developer < owner), the key predates organization support, or the plan lacks the feature. On a sandbox key, also: the cap of 5 active households on create and import, the cap of 1 active Lodestar mandate, and the white-label surfaces (tenant config, embed tokens) and narration or mapping drafts on Worthune's model (they run on your own: a model assigned at /api/v1/model-policy, or x-model-key), which the sandbox does not carry.
- `404`: No such mandate in your organization.
- `409`: expectedVersion does not match, or a concurrent change.
- `422`: Invalid fields or an impossible status move.
- `429`: Hourly per-org stateful quota, a per-route durable limit, or the 120 requests/minute per-IP burst backstop.
- `503`: Billing is not configured on this deployment; household resources are disabled rather than served without tenancy (production fail-closed).

---

[API](https://skmtc.dev/worthune/apis/worthune-api.md) · [All operations](https://skmtc.dev/worthune/apis/worthune-api/llms.txt) · [OpenAPI document](https://skmtc.dev/worthune/apis/worthune-api/revisions/9f2241072555?raw)