Quote to Purchase Integration Guide v2

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

This guide uses the original partner-facing quote-to-purchase structure and extends it to reflect the latest published GraphQL schema for single-trip policies.

It covers both supported purchase patterns. The deferred flow remains a first-class design for integrations that need separate payment orchestration. The v2 update adds the published streamlined purchasePolicy mutation, refreshed schema optionality, updated authentication examples, and current search and modification references.

Overview

Travel Insured's GraphQL API enables partners to embed travel insurance directly into the customer journey, reduce purchase friction, and support multiple checkout architectures.

Core Integration Flow

Travel Insured publishes two supported purchase patterns for single-trip policies:

Streamlined Purchase Flow

1. Generate Quote using quote
2. Purchase Policy using purchasePolicy

Use this pattern when your integration can submit payment details in the same mutation that stages and binds the policy.

Deferred Purchase Flow

1. Generate Quote using quote
2. Stage Policy Purchase using stagePolicyPurchase
3. Process Payment using processPayment
4. Policy Bind Request using policyBindRequest

Use this pattern when your checkout requires hosted payment pages, embedded payment experiences, or separate payment-session handling.

Related Published Capabilities

• Saved Quote Details using savedQuote for resume flows
• Policy search and servicing using searchPlan
• Streamlined policy modification using modifyPolicyWithPayment

Annual-plan purchase uses separate annual-plan mutations and is covered in its own guide and Postman collection.

---

1. Before Integration: Authentication & Prerequisites

API Credentials

Your integration team will receive:

Required Integration Headers

Every API request must include these headers:

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

Important: Send the API token as a raw value with an ApiKey prefix exactly as shown above.

Environment Setup

Typical partner onboarding includes:

• Development/Sandbox for testing and implementation work
• Production for live traffic

We recommend development-first implementation with end-to-end validation before production cutover.

---

2. Understanding the Data Contract

State Carried Through the Flow

Your integration must persist and pass these identifiers through the quote-to-purchase workflow:

Treat these identifiers as session state. Pass them unchanged between requests and do not parse or modify them.

Required Information by Stage

At Quote Time

• Trip dates, destinations, and travelers
• Traveler names and dates of birth
• Residency country and state
• Trip cost per traveler

At Purchase Time

• All quote information, consistent with the original quote
• Primary traveler full address and contact details
• Additional traveler information if applicable
• Beneficiary designations if collected; if provided, percentages should total 100%
• Selected product code and optional coverage IDs
• Preferred document delivery method

At Streamlined Purchase Time

• All purchase information above
• Payment method and payment details in the purchasePolicy payload
• Optional payment.idempotencyKey for safe retry handling

At Deferred Payment Time

• Staged plan identifier planGuid
• Payment method type
• Billing party information if your integration sends it here
• Hosted payment or iframe configuration as needed

At Deferred Finalization

• Staged plan identifier planGuid
• Payment gateway transaction ID
• No raw payment card data

---

3. Step 1: Generate a Quote

What This Operation Does

Creates a rate quote for one or more travelers covering a specified trip. The quote captures available products, coverage options, pricing, upsell products, and acceptable payment methods.

Partners should persist the quote identifier as a resumable quote reference, not as a locked-price artifact. Pricing should be treated as dynamic and repriced in the moment during downstream purchase handling.

Request Inputs

Travel Details:

• Departure date
• Return date
• Destinations
• Trip cost per traveler

Traveler Details:

• First and last name
• Date of birth
• Email
• Residency country and state

Your Organization Context:

• Agency number
• Agent ID, if used

Response Data

A successful quote response includes:

• quoteNumber to persist for purchase
• products[] with product code, product name, total price, available payment methods, optional coverages, and upsell products

Implementation Guidance

1. Use the quote response to drive product selection UI.
2. Let customers select a product and optional coverages from the returned product list.
3. Store quoteNumber with the customer session.
4. If the customer abandons, use savedQuote to retrieve the quote later.
5. If the customer returns later, be prepared for current pricing to be recalculated.

Example Operation

Use the quote mutation with a QuoteRequestInput payload and retain the returned quoteNumber, product selections, available payment methods, coverage choices, and upsell products needed for downstream purchase handling.

---

4. Optional: Retrieve a Saved Quote

When to Use This

If your implementation supports customer resumption, such as quote reminder emails or abandoned cart recovery, retrieve a prior quote using savedQuote instead of forcing the customer to start over.

Constraints

• Original quote parameters are not a guaranteed price lock.
• If trip details materially change, generate a fresh quote.
• Resume flows should expect current pricing to be recalculated as needed.

Implementation Note

If you need a fresh pricing response before checkout, generate a new quote rather than attempting to mutate an archived quote.

---

5. Purchase Input Fields: Required vs. Optional

This reference table summarizes shared required and optional fields across the published purchase flows.

Traveler Inputs

PrimaryTravelerInput

AdditionalTravelerInput

Product and Policy Context

ProductDetailInput

Shared Purchase Context

Streamlined Payment Details

Deferred Payment Processing

PaymentProcessingRequestInput

---

6. Step 2: Streamlined Purchase Using purchasePolicy

What This Operation Does

purchasePolicy validates the quote, stages the policy, processes payment, and binds the policy in a single mutation.

This is the shortest path from quote to issuance and is the recommended pattern when your payment platform supports tokenized payment or approved AR billing.

When to Use It

• Tokenized card or wallet payments
• AR or invoicing flows supported by your commercial agreement
• Partner experiences that want fewer server round trips

Request Inputs

The mutation expects:

• quoteNumber
• agencyNumber
• deliveryMethods[]
• product.productCode
• Full trip details including the primary traveler
• payment.paymentMethod
• Token details when payment.paymentMethod is TOKEN

Response Data

A successful response includes:

• success
• policyNumber
• amountCharged
• transactionId
• Document URLs
• errorCode and errorMessage on failure

Implementation Guidance

1. Send payment.idempotencyKey to prevent duplicate charges on retries.
2. Use TOKEN only with a valid network token and cryptogram.
3. Use AR only when your agreement supports invoicing or remittance.
4. Persist policyNumber as the final system-of-record policy identifier.

Example Operation

Use the purchasePolicy mutation with a PolicyPurchaseInput payload and expect a response that indicates success, returns the final policyNumber, includes the charged amount and transaction ID, and provides document URLs or failure details.

---

7. Step 3: Deferred Purchase Using stagePolicyPurchase

What This Operation Does

Converts an active quote into a staged purchase that is priced but not yet final. It captures purchase-grade traveler information, beneficiary designations, product selection, and delivery preferences, then returns a planGuid for the remaining deferred-flow steps.

The deferred flow is a supported design for integrations where payment must remain outside the purchase mutation.

Key Differences from Quote Stage

Request Inputs

Quote Reference:

• quoteNumber

Product Selection:

• Product code from the quote response
• Optional coverage IDs
• Optional effective date in the product payload

Traveler and Trip Details:

• Trip dates and destinations consistent with the quoted trip
• Primary traveler name, date of birth, email, phone, and full address
• Additional travelers when applicable
• Beneficiaries when collected
• Optional fields such as middleName, memberNumber, depositDate, and finalPaymentDate

Delivery Preferences and Partner Context:

• Required delivery methods
• Required agency number
• Optional agentId, marketingChannelId, applicationDate, ownerId, and tourNumber

Data Validation Rules

The API validates:

1. The quote reference is valid and can be repriced under current rating logic.
2. Traveler data matches the quoted trip.
3. Selected product and optional coverages match quote availability.
4. Traveler names and dates of birth are consistent.
5. Beneficiary percentages total 100% if beneficiaries are supplied.
6. Trip dates fall within acceptable purchase windows.

Response Data

A successful response includes planGuid, which you should retain for processPayment and policyBindRequest.

Example Operation

Use the stagePolicyPurchase mutation with a PolicyPurchaseStageInput payload and retain the returned planGuid for the remaining deferred purchase steps.

---

8. Step 4: Process Payment

What This Operation Does

Registers the payment session for the staged plan and returns identifiers needed to complete payment through your selected deferred-payment model.

This operation does not process raw card data. Payment capture is handled through Travel Insured's secure payment partner.

Request Inputs

Required:

• planGuid
• paymentMethod

Optional:

• billingPartyInformation
• hostedPaymentUrl
• iFrameCommunicatorUrl

Response Data

A successful payment-processing response includes:

• paymentRequestId
• planGuid

Implementation Guidance

1. Store paymentRequestId in your logs for support correlation.
2. Complete the hosted or embedded payment step before the payment session times out.
3. Capture the gateway transactionId for the final bind step.
4. If payment fails or the customer abandons, re-stage the plan if needed.

Example Operation

Use the processPayment mutation with a PaymentProcessingRequestInput payload and retain the returned paymentRequestId and planGuid for support tracing and final policy binding.

---

9. Step 5: Policy Bind Request (Deferred Finalization)

What This Operation Does

Validates the payment transaction with the payment gateway, finalizes the staged plan, and issues the policy.

Once this operation succeeds, the customer has an issued active policy and the response returns policy identifiers and document links.

Request Inputs

• planGuid
• transactionId

Response Data

A successful bind response includes:

• planNumber
• cobDownloadLink
• eobDownloadLink

Implementation Guidance

1. Persist planNumber as the final policy reference for deferred purchase.
2. Store document links for customer access.
3. Retry only after understanding the prior payment outcome.
4. If payment was declined or expired, restart from staging with a fresh session.

Example Operation

Use the policyBindRequest mutation with the staged planGuid and confirmed payment transactionId, then retain the returned planNumber and document links for customer servicing.

---

10. Failure Handling and Common Issues

Quote Stage

Streamlined or Deferred Purchase Stage

Deferred Payment Stage

Finalization Stage

---

11. Integration Patterns and Best Practices

Choosing the Right Purchase Pattern

Recommended Checkout Flow

1. Generate a quote early in checkout and persist quoteNumber.
2. Support resume flows with savedQuote when customers return later.
3. Choose streamlined purchase for one-step issuance when payment can be submitted in the mutation.
4. Choose deferred purchase when payment handling requires a separate session.
5. Persist final policy identifiers and document links for servicing and support.

Session Management

• Quotes do not have a fixed expiry, but pricing should be treated as dynamic until purchase.
• Deferred staged plans and payment sessions should be treated as temporary checkout state.
• Final policy identifiers are permanent and should be retained for support, servicing, and claims.

Compliance and Data Privacy

• Travel Insured does not receive or process raw payment card data in partner applications.
• Payment tokenization and PCI controls are handled through the payment partner.
• Secure API credentials and rotate them periodically.

---

12. Search and Retrieve Policies

Partners often need to retrieve customer policies for support, modification, or renewal workflows.

When to Offer Search

• Customer service lookup by policy number, traveler name, or email
• Policy management dashboards
• Renewal or follow-on workflows
• Administrative review of issued policies

How to Search

Use searchPlan to retrieve policy details by policy number, traveler information, issue dates, agency, or trip dates.

Returned policy details can include:

• Primary and additional travelers
• Trip dates and destinations
• Coverage selections
• Payment and refund history
• Policy status and servicing context

What You Can Do with Retrieved Policies

1. Display policy details to the customer.
2. Start supported modification flows.
3. Support servicing and operational review.
4. Use the issued policy context for follow-on workflows.

---

13. Policy Modification and Changes

After a policy is issued, customers may need to update traveler information, trip details, or coverage selections.

The latest published schema also includes modifyPolicyWithPayment for streamlined modification scenarios where payment for the change can be handled in the same mutation.

Typical Modification Workflow

1. Retrieve the existing policy using searchPlan.
2. Evaluate the requested changes and the price impact.
3. Submit the supported modification request.
4. Process incremental payment or refund handling as required by the modification path.
5. Return updated policy details and documents to the customer.

Modification Constraints

• Changes are generally subject to product and timing rules.
• Pricing is recalculated using current rating and policy conditions.
• Some changes may require additional servicing review depending on the policy state.

---

14. Technical Support and Resources

Key Artifacts for Your Team

Provide your development team with:

1. This integration guide.
2. The GraphQL schema reference.
3. Environment credentials and endpoint URLs.
4. Sample request and response payloads.
5. Your Travel Insured integration contact.

Support Channels

• Technical questions: your dedicated integration engineer
• Credential management: your account team
• Production issues: Travel Insured support with your payment request IDs and policy identifiers

Next Steps

1. Set up your development environment.
2. Test quote, purchase, and resume flows end to end.
3. Validate the purchase pattern that matches your payment architecture.
4. Perform regression testing before production cutover.

---

15. FAQ

Q: Is deferred purchase still supported?
A: Yes. Deferred purchase is a supported design pattern for integrations that need separate payment-session handling.

Q: What happens if a customer abandons during checkout?
A: Saved quotes can be resumed later, but pricing is not locked and may be recalculated when the customer returns. Deferred staged plans and payment sessions should be treated as temporary checkout state.

Q: How do I choose between purchasePolicy and the deferred flow?
A: Use purchasePolicy when you can submit payment in the same mutation. Use the deferred flow when your payment experience requires hosted pages, iframes, or separate orchestration.

Q: Can I customize the product names or pricing in my checkout?
A: Display product names and pricing from the quote response. Do not alter them in ways that conflict with the underwritten policy.

Q: How do I know a deferred payment succeeded before calling policyBindRequest?
A: Capture the transaction ID directly from your payment partner's callback or confirmed payment result. Do not rely on browser redirects alone.

Q: How often should I refresh API credentials?
A: Rotate credentials periodically and immediately upon team changes or suspected compromise.

---

Questions or integration support needed? Contact your Travel Insured partner team to get started.