Handling Rebate Contract Effective Dating

The decision this page settles is how to select the single rebate contract version that governs a claim by its 401-D1 Date of Service when contracts carry effective and termination dates, when amendments arrive retroactively, and when a successor agreement overlaps the tail of the one it replaces. Effective dating is where rebate attribution most often goes silently wrong: pick the version live today instead of the version live on the service date and every replayed accrual drifts; treat two overlapping versions as both governing and the rebate double-counts; miss the gap between a terminated contract and its successor and the claim accrues nothing when it should have accrued something. This guide gives a deterministic date-bracket resolver that returns exactly one governing version — or an explicit no-coverage verdict — using immutable versioned snapshots, UTC service-date boundaries, and amendment-sequence tie-breaking, as the temporal component of Manufacturer Rebate Contract Modeling.

The Decision: Which Version Governs a Service Date #

Given a set of contract versions for one manufacturer and drug, and a claim’s service date, the resolver must return one governing version. The cases below are the decision matrix; each maps to a deterministic rule, not an analyst judgment call.

The governing principle is that effective dating is resolved as of the service date, not as of now. A contract snapshot is immutable and version-stamped, so “which version was live on 2026-03-14” is a pure lookup against the interval set, and a retroactive amendment does not edit history — it publishes a new snapshot whose effective window reaches back, and the resolver simply finds it on re-adjudication. The two hard cases are overlap and gaps: overlap is broken deterministically by amendment sequence, and a gap is an explicit verdict that books a zero rebate rather than forcing the claim onto a version that did not govern it.

Step-by-Step Implementation #

The resolver builds in four moves: model the version with an effective interval and an amendment sequence, normalize the service date to a UTC-anchored date, bracket the versions whose interval contains the date, and break any residual tie by amendment sequence. Dates are compared as timezone-normalized date objects so a fill on a boundary day is not lost to a local-time off-by-one.

1. Model the version with an immutable effective interval. Each version carries effective_date, an optional termination_date, a termination_inclusive flag, and an amendment_seq that increments every time the manufacturer amends the terms. The snapshot is frozen so a change is always a new version, never an in-place edit.

from decimal import Decimal
from datetime import date, datetime, timezone
from typing import Optional
from pydantic import BaseModel, ConfigDict, model_validator


class ContractVersion(BaseModel):
    model_config = ConfigDict(extra="forbid", frozen=True)

    snapshot_id: str                       # e.g. "MFR0442-v2026.04"
    amendment_seq: int                     # increments per amendment; tie-breaker
    base_rate: Decimal
    effective_date: date
    termination_date: Optional[date] = None
    termination_inclusive: bool = True     # is termination_date itself covered?

    @model_validator(mode="after")
    def _window_ordered(self) -> "ContractVersion":
        if self.termination_date and self.termination_date < self.effective_date:
            raise ValueError("termination_date precedes effective_date")
        if self.amendment_seq < 0:
            raise ValueError("amendment_seq must be non-negative")
        return self

    def covers(self, svc: date) -> bool:
        """Is svc inside this version's effective interval?"""
        if svc < self.effective_date:
            return False
        if self.termination_date is None:
            return True
        if self.termination_inclusive:
            return svc <= self.termination_date
        return svc < self.termination_date

2. Normalize the service date to a UTC-anchored calendar date. The 401-D1 Date of Service arrives as CCYYMMDD with no timezone. Anchor it in UTC before comparing, so a claim that dispensed just before midnight local time is not bracketed into the wrong day and, with it, the wrong contract version.

def normalize_service_date(raw_401d1: str) -> date:
    """401-D1 Date of Service (CCYYMMDD) -> UTC-anchored calendar date."""
    if not raw_401d1 or len(raw_401d1) != 8:
        raise ValueError("invalid 401-D1 length")
    parsed = datetime.strptime(raw_401d1, "%Y%m%d").replace(tzinfo=timezone.utc)
    return parsed.date()

3. Bracket the versions whose interval contains the service date. Filter the manufacturer’s version set to those whose covers() is true. Zero matches is a coverage gap; one match resolves directly; more than one is an overlap that move 4 breaks.

def bracket_versions(versions: list[ContractVersion],
                     svc: date) -> list[ContractVersion]:
    """All versions whose effective interval contains the service date."""
    return [v for v in versions if v.covers(svc)]

4. Break overlap by amendment sequence and return one verdict. When a successor overlaps the tail of its predecessor, both covers() the date; the higher amendment_seq is the governing version because it is the later-filed term. A tie on sequence is a contract-data defect, not a coin flip, and raises rather than guessing.

class DateResolution(BaseModel):
    status: str                       # governed | no_coverage
    snapshot_id: Optional[str] = None
    amendment_seq: Optional[int] = None
    service_date: date


def resolve_version(versions: list[ContractVersion], raw_401d1: str) -> DateResolution:
    svc = normalize_service_date(raw_401d1)
    candidates = bracket_versions(versions, svc)

    if not candidates:
        return DateResolution(status="no_coverage", service_date=svc)

    candidates.sort(key=lambda v: v.amendment_seq, reverse=True)
    if len(candidates) > 1 and candidates[0].amendment_seq == candidates[1].amendment_seq:
        raise ValueError(
            f"ambiguous overlap: equal amendment_seq on {svc.isoformat()}"
        )

    winner = candidates[0]
    return DateResolution(
        status="governed", snapshot_id=winner.snapshot_id,
        amendment_seq=winner.amendment_seq, service_date=svc,
    )

The DateResolution feeds straight into Manufacturer Rebate Contract Modeling: a governed verdict names the exact snapshot_id whose base_rate and tiered rebate formula resolve the per-claim rate, while a no_coverage verdict books a zero rebate and flags the gap for a rebate analyst. The resolver reasons only over dates and snapshot ids — no 302-C2 Cardholder ID, 310-CA Patient Name, or raw payload is in scope, so the audit event carries the tokenized 402-D2 reference and the resolved snapshot_id alone.

Timeline of Overlapping Versions Against a Service Date #

The diagram traces three versions of one contract — an original, a retroactive amendment, and a successor — against a single claim’s service date, showing which one the resolver selects.

Figure: At the mid-May service date both v1 and the retroactive amendment v2 cover the claim; the resolver selects v2 by its higher amendment sequence, and a genuine gap between a terminated version and its successor would instead return a zero-rebate no-coverage verdict.

Verification and Testing Pattern #

Correctness means the resolver returns one deterministic version for any service date, selects the retroactive amendment over the original on overlap, and books no-coverage on a gap. Drive it against fixtures with explicit boundary dates.

import pytest

V1 = ContractVersion(snapshot_id="MFR-v1", amendment_seq=0,
                     base_rate=Decimal("0.235"),
                     effective_date=date(2026, 1, 1),
                     termination_date=date(2026, 6, 30))
V2 = ContractVersion(snapshot_id="MFR-v2", amendment_seq=1,
                     base_rate=Decimal("0.255"),
                     effective_date=date(2026, 1, 1),
                     termination_date=date(2026, 8, 31))
V3 = ContractVersion(snapshot_id="MFR-v3", amendment_seq=0,
                     base_rate=Decimal("0.240"),
                     effective_date=date(2026, 9, 1),
                     termination_date=None)


def test_overlap_prefers_higher_amendment_seq():
    r = resolve_version([V1, V2, V3], "20260515")   # mid-May
    assert r.status == "governed"
    assert r.snapshot_id == "MFR-v2"                 # retroactive amendment wins


def test_gap_returns_no_coverage():
    # V2 ends Aug 31, V3 starts Sep 1 -- Sep 1 is covered, but a claim on
    # a genuine gap day resolves to no_coverage.
    gapped = [V1, V3]                                # nothing covers Jul-Aug
    r = resolve_version(gapped, "20260715")
    assert r.status == "no_coverage"
    assert r.snapshot_id is None


def test_termination_boundary_inclusive():
    # Jun 30 is V1's inclusive termination day; V2 also covers it and wins on seq.
    r = resolve_version([V1, V2], "20260630")
    assert r.snapshot_id == "MFR-v2"


def test_clean_succession_selects_successor():
    r = resolve_version([V1, V3], "20260901")
    assert r.snapshot_id == "MFR-v3"


def test_ambiguous_equal_seq_raises():
    dup = V1.model_copy(update={"snapshot_id": "MFR-dup"})  # same seq 0, same window
    with pytest.raises(ValueError):
        resolve_version([V1, dup], "20260515")

The test_ambiguous_equal_seq_raises case is the load-bearing guard: two versions covering the same date with equal amendment sequence is a contract-data defect, and the resolver refuses to guess rather than silently attributing the rebate to whichever happened to sort first.

Gotchas and PHI Guardrails #

• Retroactive true-ups, not edits. An amendment effective in the past must never rewrite a booked accrual. Publish the new version, re-resolve the affected claims against it, and book the delta as a true-up — the immutable snapshot preserves both the original and amended attributions for audit, feeding Rebate Accrual Reconciliation.
• Timezone off-by-one at the boundary. 401-D1 carries no timezone; a naive local-time parse can push a late-night fill onto the adjacent calendar day and into the wrong version. Anchor every service date in UTC before bracketing, per Python’s datetime documentation.
• Gaps between contracts. A terminated contract with no live successor on the service date must return no_coverage and a zero rebate — never fall back to the most recent version. A phantom accrual against an expired contract is a reconciliation failure and a potential audit finding.
• Inclusive versus exclusive termination. Whether the termination date itself is covered is a contract term, carried on termination_inclusive. Hard-coding one interpretation silently mis-attributes every claim that dispenses on a seam day.
• PHI stays out of the temporal layer. The resolver reasons over dates and snapshot ids only. No 302-C2 Cardholder ID, 310-CA Patient Name, or raw claim bytes enter version selection; the audit event carries the tokenized 402-D2 reference and the resolved snapshot_id, honoring Security & Compliance Boundaries for Claims Data. Contract term definitions align with CMS rebate guidance at cms.gov.

Related #

• Manufacturer Rebate Contract Modeling — the parent model that consumes the governing version this resolver selects.
• Modeling Tiered Rebate Formulas in Python — the sibling guide that resolves the tiered bonus once the governing version is known.
• Rebate Accrual Reconciliation — books the true-ups that retroactive amendments and restated versions generate.
• WAC/AMP Spread Calculation — the WAC basis whose effective-dated reference the rebate rate is applied against.

← Back to Manufacturer Rebate Contract Modeling