---
title: "Fully replace an existing plan by ID"
method: PUT
path: "/plans/{id}"
tags: ["Plan"]
---

# Fully replace an existing plan by ID

`PUT /plans/{id}`

Replaces the entire plan record identified by `{id}` with the supplied payload. This is a **full replacement** — fields omitted from `data` are not preserved from the prior version, so submit the complete desired plan `data` on every call, not a partial diff. Submitting the same payload twice for the same `{id}` is idempotent. The caller must hold the UPDATE_PLAN permission. As with plan creation, `data.payer` is extracted and stored as `payerId`, and the referenced payer is not validated for existence. `data`'s full shape is defined by the external Plan JSON schema and may include required fields beyond `payer`.

## Path parameters

- `id` string, required

## Headers

- `tenant-id` string, required

## Request body

- CreatePlanRequest
  - `data` PlanSchema — Represents a healthcare plan with business line, network type, and benefits information.
    - `lineOfBusiness` 'Medicare' | 'Medicaid' | 'Commercial' — Specifies the line of business associated with a healthcare plan.
    - `networkType` 'Commercial - HMO' | 'Commercial - PPO' | 'Medicare - HMO' | 'Medicaid - HMO' — Specifies the line of business and network type combination for a healthcare plan.
    - `benefits` string — The benefits offered under the plan.
    - `name` string — The name of the plan.

## Response `200`

The plan as it exists after the replacement.

- GetPlanResponse — A single plan record as it appears in a paginated plans listing.
  - `id` string — Server-assigned unique identifier for the plan.
  - `tenantId` string — Identifier of the tenant that owns this plan.
  - `payerId` string — Identifier of the payer this plan is associated with. Extracted server-side from `data.payer` at creation time.
  - `data` object — The plan's domain data, validated against the Plan JSON schema at creation/update time.

## Other responses

- `400` — Returned when `tenant-id` is missing or `data` fails validation against the Plan JSON schema. DAL-side validation errors are passed through with their original body.
- `401` — Unauthorized - Authentication required
- `403` — Forbidden - Caller lacks the UPDATE_PLAN permission
- `404` — Returned when no plan exists with the given `{id}` for the tenant. Passed through unchanged from the downstream data service (DAL).
- `500` — Returned for an unexpected internal error.
- `502` — Returned when the downstream data service (DAL) responds with a server error.
- `503` — Returned when the downstream data service (DAL) cannot be reached.

---

[API](https://skmtc.net/certifyos/apis/certify-api-layer.md) · [All operations](https://skmtc.net/certifyos/apis/certify-api-layer/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/certifyos/certify-api-layer/revisions/563848e0ecc0/schema)