Publish and Version a Benefit Plan

Use immutable published versions so claims can be reproduced against the configuration effective on the date of service.

Why versioning matters

A published version is not edited in place. Amendments create a new draft, and publishing the successor preserves the configuration that governed earlier claims.

Plan Lifecycle

Draft
Editable candidate

→

Published
Effective configuration

→

Superseded
Retained history

State	Use	Mutation rule
Draft	Review before activation	May be changed before publication
Published	Resolved for effective claims and member views	Immutable; amend to change
Superseded	Historical reconstruction and audit	Read-only

1. Create a Draft

For a new controlled plan, create a draft rather than using the convenience create-and-publish endpoint:

Shellnew draft

draft=$(curl -fsS -X POST \
  "${BENEFIT_PLAN_URL}/api/v1/plans/drafts" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: ${TENANT_ID}" \
  -d '{
    "tenantId": "placeholder",
    "planId": "EVAL-PPO-2027",
    "planName": "Evaluator Premier PPO 2027",
    "payer": "Acme Health Plan",
    "effectiveDate": "2027-01-01T00:00:00Z",
    "planType": "PPO",
    "metalLevel": "Gold",
    "lineOfBusiness": "Commercial",
    "costSharing": {
      "individualDeductible": 1750,
      "familyDeductible": 3500,
      "individualOutOfPocketMax": 6500,
      "familyOutOfPocketMax": 13000
    }
  }')

echo "$draft" | jq '{planId,versionId,versionNumber,versionState}'
VERSION_ID=$(echo "$draft" | jq -r '.versionId')

2. Publish the Reviewed Version

Shellpublish

curl -fsS -X POST \
  "${BENEFIT_PLAN_URL}/api/v1/plans/EVAL-PPO-2027/versions/${VERSION_ID}/publish" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: ${TENANT_ID}" \
  -d '{"effectiveDate":"2027-01-01T00:00:00Z"}' |
  jq '{planId,versionId,versionNumber,versionState,publishedAt}'

Effective-date control

Confirm regulatory limits, network references, service mappings, and member communications before publication. Publication makes the version eligible for runtime resolution.

3. Amend a Published Plan

Create a successor draft from the latest published version:

Shellamend

amendment=$(curl -fsS -X POST \
  "${BENEFIT_PLAN_URL}/api/v1/plans/EVAL-PPO-2027/amend" \
  -H "X-Tenant-ID: ${TENANT_ID}")

echo "$amendment" |
  jq '{planId,versionId,versionNumber,versionState,predecessorVersionId}'

Review and publish the new draft using its returned versionId. The former published version becomes superseded rather than disappearing.

4. Verify Version History

Shellhistory

curl -fsS \
  -H "X-Tenant-ID: ${TENANT_ID}" \
  "${BENEFIT_PLAN_URL}/api/v1/plans/EVAL-PPO-2027/versions" |
  jq '.items[] | {
    versionNumber, versionId, versionState,
    effectiveDate, publishedAt, predecessorVersionId
  }'

Completion check

The chain has monotonic version numbers, a predecessor link on the amendment, one current published version, and retained superseded history.