Validate a Benefit Plan

Prove that the plan resolves for the intended date, presents understandable benefits, and drives a synthetic claim to the expected cost-sharing result.

Validation has two layers

The member view confirms what the plan says. A test claim confirms what adjudication does. Use both before considering configuration complete.

1. Retrieve the Member Benefit View

Shellas-of-date projection

export SERVICE_DATE=2026-07-15

curl -fsS \
  -H "X-Tenant-ID: ${TENANT_ID}" \
  "${BENEFIT_PLAN_URL}/api/v1/benefit-plans/${PLAN_ID}/member-view?serviceDate=${SERVICE_DATE}" |
  tee /tmp/benefit-member-view.json |
  jq '{planId,planName,planType,asOfDate,costSharing,categories}'

The member view is a categorized, date-sensitive projection of the plan. It is easier to review than the persistence model and represents the benefit information a consumer-facing experience can present.

2. Write Expected Results Before Testing

Scenario	Expected configuration	Evidence
In-network office visit	$30 copay; deductible does not apply	Primary care category in member view
In-network diagnostic lab	20% coinsurance after deductible	Diagnostic category in member view
Out-of-network office visit	$60 copay	Out-of-network tier in member view
Service date before effective date	Plan does not resolve	Not-found response or no active plan

3. Run a Synthetic Claim

Use the repository’s 834-to-837 smoke workflow to create the member context, submit a real synthetic 837P, and wait for adjudication:

Shellrepository root

TENANT_ID="${TENANT_ID}" \
BENEFIT_PLAN_URL="${BENEFIT_PLAN_URL}" \
ENROLLMENT_IMPORT_URL=http://localhost:5011 \
CLAIMS_URL=http://localhost:5001 \
scripts/smoke/834-to-837-e2e-smoke.sh

The workflow creates its own plan by default. For a controlled plan-specific test, use the same payload pattern while mapping the fixture’s external plan code to PLAN_ID. The Submit an 837 and Follow the Claim tutorial explains the complete trace.

4. Preserve the Evidence

Plan ID, version ID, and effective date used by adjudication
Member and provider identifiers from synthetic fixtures
Service category and network tier selected
Deductible and OOP accumulator values before and after the claim
Allowed amount, payer payment, and member responsibility
Adjudication pipeline trace and terminal claim status

Completion check

The member view matches the written expectations, the synthetic claim resolves the intended plan version, and its cost-sharing result is explainable from the configured rule and accumulator state.

Troubleshooting

Symptom	Likely cause
Member view returns 404	Plan ID, tenant, or service date does not select an effective published version.
Claim has no BenefitPlanId	The 834 external plan code is not mapped to the configured plan.
Wrong cost-sharing rule	Inspect service-category mapping and selected network tier before changing the benefit.
Unexpected deductible amount	Review accumulator state and whether `deductibleApplies` is set for the selected benefit.