Annual Plan Quote to Purchase Integration Guide

Intended Audience: Partner development teams and technology executives
Last Updated: May 12, 2026
Version: 1.0

This guide covers the published annual-plan purchase flow. Annual-plan purchase uses annual-specific quote and staging mutations, then reuses the same deferred payment and binding pattern as single-trip staged purchase.

Overview

The published annual-plan flow consists of four operations:

1. Annual Plan Quote using annualPlanQuote
2. Stage Annual Policy Purchase using stageAnnualPolicyPurchase
3. Process Payment using processPayment
4. Policy Bind Request using policyBindRequest

Use this flow when you are selling annual products rather than a single-trip policy.

---

1. Authentication and Setup

Send both headers on every request:

• Authorization: ApiKey {{apiToken}}
• x-api-key: {{accessKey}}
• Content-Type: application/json

Send the API token with the ApiKey prefix exactly as shown above.

Separate Annual Setup

Before testing the annual flow:

1. Import the annual-plan Postman collection linked at the top of this guide.
2. Configure graphqlBaseUrl, apiToken, accessKey, agencyNumber, and optional agentId in your Postman environment.
3. Confirm your partner access includes annual-plan products before attempting annualPlanQuote.
4. Use a product code returned by annualPlanQuote rather than reusing a single-trip product code.

---

2. Annual-Specific Data Shapes

Annual-plan purchase uses these annual-specific input types:

AnnualPlanQuoteRequestInput

Required fields:

• agencyNumber
• effectiveDate
• residencyCountryIsoCode
• residencyStateIsoCode
• travelers[]

Optional fields:

• agentId
• applicationDate
• ownerId
• quoteNumber
• tripSegment

AnnualPolicyPurchaseStageInput

Required fields:

• agencyNumber
• deliveryTypes[]
• planTravelers[]
• product
• quoteNumber

Optional fields:

• agentId
• applicationDate
• marketingChannelId
• ownerId
• tripSegment

PlanTravelerInput

Key distinctions from the single-trip flow:

• annual staging uses planTravelers[] instead of trip.primaryTraveler plus trip.additionalTravelers
• each traveler includes id, primaryTraveler, dateOfBirth, firstName, and lastName
• contactInfo is optional in schema and recommended for the primary traveler
• beneficiaries, middleName, and tripCost are optional in schema

TripSegmentInput

The annual flow can optionally include a trip segment with:

• departureDate
• returnDate
• destinations[]
• travelers[]

Use tripSegment when you want the annual quote or staged policy tied to a known planned trip segment during purchase.

---

3. Step 1: Annual Plan Quote

Use the annualPlanQuote mutation with an AnnualPlanQuoteRequestInput payload and retain the returned products, pricing, and coverage details for customer selection.

Retain:

• quoteNumber
• selected productCode
• optional coverage IDs

---

4. Step 2: Stage Annual Policy Purchase

Use the stageAnnualPolicyPurchase mutation with an AnnualPolicyPurchaseStageInput payload to validate the quote and create the staged annual plan.

Retain:

• planGuid

Recommended implementation guidance:

1. Keep traveler IDs stable between quote and staging.
2. Use contactInfo for the primary traveler even though it is nullable in schema.
3. Treat planGuid as session-based checkout state.

---

5. Step 3: Process Payment

Annual staged purchase uses the same deferred payment mutation as the single-trip flow. Use the processPayment mutation with a PaymentProcessingRequestInput payload and retain the returned paymentRequestId and planGuid.

Schema-required fields:

• planGuid
• paymentMethod

Schema-optional fields:

• billingPartyInformation
• hostedPaymentUrl
• iFrameCommunicatorUrl

---

6. Step 4: Bind the Annual Policy

Annual staged purchase also uses the same bind mutation. Use the policyBindRequest mutation with the staged planGuid and confirmed payment transactionId, then retain the returned planNumber and document links.

After a successful bind:

• planNumber becomes the final issued policy identifier
• the returned document links provide the current policy documents

---

7. Choosing the Annual Flow

Choose the annual flow when:

• the selected product is an annual plan product returned by annualPlanQuote
• your partner experience sells recurring or multi-trip annual travel coverage
• you need the annual traveler model rather than the single-trip TripInput model

Use the single-trip v2 guide when you are selling one-trip policies or when you want to use the new streamlined purchasePolicy mutation.