Annual Plan Modification

Use this flow to modify an issued annual policy through the standard staged path. An annual-capable streamlined payment-and-bind operation is account-specific and is not exposed by the published schema.

searchPlan -> annualPlanModificationQuote -> amount decision -> staged zero-amount finalization or assigned annual direct completion -> reconciliation

The annual modification operations support traveler changes, trip-segment changes, or both. Product configuration and partner enablement determine which changes are allowed.

The supplied SDL's modifyPlan mutation accepts the single-trip ModifyPlanRequestInput, not ModifyAnnualPlanRequestInput. Do not send annual fields through that mutation.

Standard Supported Paths

• For a positive amount, use only the annual-capable direct operation assigned during onboarding.
• Use planModify only for a no-payment staged path explicitly enabled for the account.
• For a negative amount, use only the annual-capable direct operation and payment contract assigned during onboarding.

Account-Specific Capability

Direct AR or provider-token annual charges and refunds are available only when explicitly provisioned by Travel Insured. The operation contract is supplied as part of the account-specific integration configuration. The published schema does not name that operation, so this guide does not show or infer a mutation.

Operation Summary

Flow

Full screen
sequenceDiagram
    autonumber
    actor Traveler
    participant App as Partner app
    participant Backend as Partner backend
    participant API as Travel Insured GraphQL API

    Traveler->>App: Request annual policy change
    App->>Backend: Submit plan number and proposed change
    Backend->>Backend: Authorize servicing access
    Backend->>API: searchPlan
    API-->>Backend: Annual plan, traveler IDs, segment GUIDs
    Backend->>API: annualPlanModificationQuote
    API-->>Backend: Price, totalAmountDue, and available coverage choices
    Backend-->>App: Present complete change and amount due
    Traveler->>App: Approve modification
    alt totalAmountDue is greater than zero
      Backend->>API: Approved annual modify-with-payment request
      API-->>Backend: Bound plan and document links
    else totalAmountDue equals zero and no-payment path is enabled
      Backend->>API: annualPlanModifyRequest
      API-->>Backend: modificationPlanGuid
      Backend->>API: planModify(modificationPlanGuid)
      API-->>Backend: planNumber and document links
    else totalAmountDue is less than zero
      Backend->>API: Assigned annual direct request with AR or token refund details
      API-->>Backend: Bound plan and document links
    else Amount is missing or stale
      Backend->>API: Re-quote complete annual change
    end
    Backend-->>App: Return confirmed modification

Step 1: Find the Annual Policy

Use searchPlan and select only fields needed to authorize and construct the proposed modification.

query FindAnnualPlan($planSearchRequest: PlanSearchRequestInput!, $first: Int) {
  searchPlan(planSearchRequest: $planSearchRequest, first: $first) {
    totalCount
    nodes {
      planNumber
      planStatus
      isActive
      isAnnual
      planPrimaryTraveler {
        travelerId
        firstName
        lastName
        dateOfBirth
      }
      planAdditionalTravelers {
        travelerId
        firstName
        lastName
        dateOfBirth
      }
      segmentTripDetails {
        policySegmentGuid
        departureDate
        depositDate
        returnDate
        isModifyEnabled
        destinations {
          countryIsoCode
          stateIsoCode
          destinationName
        }
        coverages {
          productCoverageTypeCode
          coverageLimits {
            productCoverageLimitId
          }
        }
      }
    }
  }
}

Request example variables:

{
  "planSearchRequest": {
    "agencyNumber": "<authorized-agency-number>",
    "planNumber": "<issued-plan-number>",
    "searchAllTravelers": true,
    "strictSearch": true
  },
  "first": 10
}

Before showing any result:

1. Enforce agency, tenant, and customer servicing authorization on the backend.
2. Confirm exactly one intended plan was selected.
3. Confirm isAnnual is true, the plan is active, and the target segment permits modification.
4. Retain API-returned traveler IDs and policySegmentGuid; never infer or generate them.

See Quote and Policy Search for all plan-search filters and pagination.

Step 2: Quote the Proposed Modification

query QuoteAnnualModification(
  $modifyAnnualPlanQuoteRequest: ModifyAnnualPlanQuoteRequestInput!
) {
  annualPlanModificationQuote(
    modifyAnnualPlanQuoteRequest: $modifyAnnualPlanQuoteRequest
  ) {
    planNumber
    availableCoverages {
      productCoverageTypeCode
      pricingCoverageLimits {
        productCoverageLimitId
        totalPrice
      }
    }
    pricingDetail {
      totalAmountDue
    }
  }
}

The following example shows an existing trip-segment update.

Request example variables:

{
  "modifyAnnualPlanQuoteRequest": {
    "planNumber": "<issued-plan-number>",
    "planTravelers": [
      {
        "id": 101,
        "primaryTraveler": true,
        "firstName": "<primary-first-name>",
        "lastName": "<primary-last-name>",
        "dateOfBirth": "1985-06-15"
      }
    ],
    "tripSegment": {
      "action": "<assigned-segment-action>",
      "tripId": "<policy-segment-guid-from-search>",
      "departureDate": "<future-departure-date: YYYY-MM-DD>",
      "depositDate": "<eligible-deposit-date: YYYY-MM-DD>",
      "returnDate": "<future-return-date: YYYY-MM-DD>",
      "destinations": [
        { "countryIsoCode": "FR" }
      ],
      "tripSegmentTravelers": [
        {
          "id": 101,
          "tripCost": 2500.00
        }
      ],
      "coveragesToAdd": []
    }
  }
}

Identifier Rules

• planTravelers[].id and tripSegment.tripSegmentTravelers[].id come from the current plan and must identify the same person.
• tripSegment.tripId comes from segmentTripDetails.policySegmentGuid for an existing segment.
• Select productCoverageTypeCode and productCoverageLimitId from the current modification quote response before staging a coverage addition.
• Do not use IDs from a different environment, plan, segment, or earlier stale search result.

tripSegment.action is required by the SDL. Use the action vocabulary and existing-segment rules supplied for your account. tripId and depositDate are nullable in the schema but may be required by the selected action.

totalAmountDue is:

new premium - existing premium

A positive result is additional premium, zero is no price change, and a negative result is a premium reduction. For a negative amount, use the AR or provider-token refund shape defined by the annual-capable direct contract assigned to the account. Server-side validation determines whether the transaction is eligible.

Show the customer the complete change and totalAmountDue, then record explicit approval. Preserve an immutable server-side copy of the approved input.

Step 3: Choose the Completion Path

After the customer approves the complete quoted annual change and amount, use this decision table. Do not infer behavior from schema nullability.

Use exactly one path for a modification. Do not stage first and then submit the same change through an annual streamlined operation. The supplied SDL's modifyPlan mutation is single-trip only and cannot accept this annual request shape. Use only the annual operation and payment contract assigned during onboarding.

Staged Path: Stage the Approved Change

Call annualPlanModifyRequest with the same approved traveler and segment data, plus required document-delivery preferences.

mutation StageAnnualModification(
  $modifyAnnualPlanRequest: ModifyAnnualPlanRequestInput!
) {
  annualPlanModifyRequest(
    modifyAnnualPlanRequest: $modifyAnnualPlanRequest
  ) {
    planGuid
  }
}

Request example variables:

{
  "modifyAnnualPlanRequest": {
    "planNumber": "<issued-plan-number>",
    "deliveryTypeCodes": [
      { "deliveryType": "Email" }
    ],
    "planTravelers": [
      {
        "id": 101,
        "primaryTraveler": true,
        "firstName": "<primary-first-name>",
        "lastName": "<primary-last-name>",
        "dateOfBirth": "1985-06-15"
      }
    ],
    "tripSegment": {
      "action": "<assigned-segment-action>",
      "tripId": "<policy-segment-guid-from-search>",
      "departureDate": "<future-departure-date: YYYY-MM-DD>",
      "depositDate": "<eligible-deposit-date: YYYY-MM-DD>",
      "returnDate": "<future-return-date: YYYY-MM-DD>",
      "destinations": [
        { "countryIsoCode": "FR" }
      ],
      "tripSegmentTravelers": [
        { "id": 101, "tripCost": 2500.00 }
      ],
      "coveragesToAdd": [
        {
          "productCoverageTypeCode": "<selected-coverage-type>",
          "productCoverageLimitId": 301,
          "startDate": "<coverage-start-date: YYYY-MM-DD>",
          "endDate": "<coverage-end-date: YYYY-MM-DD>"
        }
      ]
    }
  }
}

Store the returned planGuid as modificationPlanGuid. It identifies this staged change and is different from the original purchase-stage GUID.

Step 4: Complete Additional Payment and Bind

Use this step only when totalAmountDue > 0. The verified embedded-payment session contract is for staged purchases and does not document paid annual modifications. Use only the annual-capable direct operation assigned during onboarding. For zero or negative amounts, use the applicable path in Step 5. Do not infer behavior from schema nullability.

Annual Plan Modify with Payment API Request

When your account is approved for annual direct completion, send the exact customer-approved annual modification through the assigned annual-capable operation. That request stages the annual change, processes payment, and binds the modification as one transaction. Do not first call annualPlanModifyRequest or planModify, and do not send a modification-stage GUID to the purchase payment-session endpoint.

Use one of the following payment methods when a premium charge or refund is due:

• Accounts receivable (AR): set the assigned request's payment method to AR, include the approved amount and a unique idempotency key, and omit token fields.
• Approved provider token: include the approved amount, required billing party, provider-discriminated token details, and a unique idempotency key; omit the AR payment method.

The supplied SDL does not name an annual-capable direct mutation, so obtain the operation name and ModifyAnnualPlanRequestInput-compatible payment contract assigned to your account. Do not substitute the single-trip modifyPlan mutation. For refunds, use the amount representation defined by that assigned contract; do not infer signed or absolute semantics. Keep payment tokens and billing data server-side, never log them, and reconcile an uncertain response before retrying or collecting payment again.

Step 5: Finalize an Enabled Zero-Amount Modification

The planModify operation and variables are shared with the canonical staged finalization request. Send the annual staging response's modificationPlanGuid as planGuid.

Use this mutation directly only when totalAmountDue = 0 and the no-payment path is enabled. It is not part of a paid journey.

Successful finalization returns the current planNumber and document links. It does not return a modification status field.

Modification Is Not Cancellation

The public schema does not expose a general paid retail cancellation mutation. Do not recommend or use annualPlanModifyRequest, an annual direct modification, or a zero-value modification as a cancellation workaround; use the separately authorized cancellation servicing route supplied for the account.

Failure and Recovery

Mask traveler data, plan numbers, transaction IDs, and document links in logs. Return document links only to an authorized customer.

Implementation Checklist

• Confirm isAnnual is true and authorize the plan and target segment.
• Use response-derived traveler, segment, and coverage values.
• Apply the amount decision table; stop and re-quote missing or stale pricing.
• Stage only an enabled zero-amount branch with annualPlanModifyRequest, never planModifyRequest.
• Do not send annual changes through the single-trip modifyPlan operation.
• Use the assigned annual-capable direct contract for AR or provider-token refunds.
• Call planModify with the same modificationPlanGuid only for an enabled staged zero-amount modification.
• Reconcile unknown payment, refund, and finalization outcomes before retrying.
• Keep modification refunds distinct from cancellation.

Related Guides

• Quote and Policy Search
• Single Trip Modification
• API Integration Guide