Creates a modification quote for an active policy; purchasing it via POST /quotes/{quoteId}/purchase replaces the policy.
Only the dates and duration can be modified. Location, event, experience, exposure, product and payout option are taken from the original policy; a different value is refused with MODIFICATION_FIELD_NOT_SUPPORTED. Daily cover is fixed, so a longer stay re-derives the total exposure. A policy can be modified once (POLICY_ALREADY_MODIFIED) and not within the modification cut-off before cover starts (MODIFICATION_CUTOFF_PASSED). An upgrade charges the difference plus the modification fee and requires a payment reference (MODIFICATION_PAYMENT_REQUIRED); a same-price change charges nothing; on a downgrade the difference is not refunded.
For departure-time cover, the policy keeps its departure time unless you send a new departureTime with durationMinutes, which moves the cover window. A policy bought without a departure time cannot be given one (MODIFICATION_FIELD_NOT_SUPPORTED).
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Modification Flow
sequenceDiagram
participant P as Partner
participant API as WeatherIT API
Note over P,API: Original policy remains active throughout
P->>API: POST /policies/{id}/modify<br/>New dates, location, or amount
API->>API: Validate policy is active
API-->>P: Modification quote<br/>(new pricing_options)
P->>P: Show customer old vs new pricing
alt Customer accepts
P->>API: POST /quotes/{quote_id}/purchase<br/>Purchase modification quote
API-->>P: New policy created<br/>(linked to original)
Note over P,API: Original policy superseded
else Customer declines
Note over P,API: Original policy unchanged
end
What This Endpoint Does
- Validates Policy: Ensures the policy exists and is active
- Accepts New Parameters: Takes updated coverage dates, location, or exposure amount
- Generates Modification Quotes: Returns new pricing options for modified coverage
- Preserves Original: Original policy remains active until modification is purchased
When to Use This Endpoint
Call this endpoint when:
- Customer needs to extend their coverage period
- Coverage dates need to change (booking rescheduled)
- Coverage amount needs adjustment (booking value changed)
- Location changes (different coordinates)
Request Parameters
The request body matches the standard quote creation format:
| Field | Required | Description |
|---|---|---|
| experienceDetails.type | Yes | Event type (camping, hiking, event, sports, experience, accommodation) |
| experienceDetails.name | Yes | Experience name |
| experienceDetails.location | Yes | Updated location with coordinates |
| coverage.startDate | Yes | New start date (YYYY-MM-DD, within 12 months) |
| coverage.endDate | Yes | New end date (YYYY-MM-DD, within 12 months) |
| coverage.exposureAmount | Yes | New coverage amount |
| options.partnerQuoteId | No | Your reference for this modification |
Understanding the Response
Response structure matches the Create Quote endpoint:
| Field | Description |
|---|---|
| quotes_generated | Number of pricing options (typically 2-3) |
| expires_at | Quote expiration (3 hours from creation) |
| pricing_options[] | Array with quote_id, payout_percentage, premium |
| coverage | New proposed coverage details |
| weather_protection | Trigger details for new coverage |
pricing_options[] includes voucher fields when applicable:
| Field | Description |
|---|---|
| is_voucher_option | Whether this option uses voucher payout |
| voucher_discount_amount | Discount when selecting voucher payout |
| voucher_display_name | Display name for voucher option |
How Modification Works
1. Call this endpoint with new parameters
2. Receive modification quotes (original policy stays active)
3. Customer selects preferred option
4. Purchase using `POST /quotes/{quote_id}/purchase`
5. New policy created, linked to originalImportant: Original policy remains active until modification is purchased. If the modification quote expires or isn't purchased, the original policy continues unchanged.
Error Handling
| Error | Code | Description |
|---|---|---|
| POLICY_NOT_FOUND | 404 | Policy doesn't exist |
| POLICY_NOT_ACTIVE | 422 | Policy is cancelled, completed, or expired |
| DATE_LIMIT_EXCEEDED | 422 | Dates beyond 12-month window |
| START_DATE_IN_PAST | 422 | Start date is in the past |
| END_DATE_BEFORE_START | 422 | End date is before start date |
| NO_COVERAGE_AVAILABLE | 422 | Parameters don't meet underwriting criteria |
| LOCATION_NOT_SUPPORTED | 422 | New location isn't covered |
| ANNUAL_POLICY_NOT_MODIFIABLE | 422 | Annual policies cannot be modified |
| VALIDATION_ERROR | 400 | Invalid date format or missing fields |
What Can Be Modified
| Modifiable | Not Modifiable |
|---|---|
| Coverage dates | Customer information |
| Coverage duration | Completed policies |
| Exposure amount | Cancelled policies |
| Location | Policies with active claims |
| Payout percentage | Past coverage periods |
Pricing Changes
Modifications may cost more or less depending on:
- Higher premium: Extended period, increased amount, higher-risk location/dates
- Lower premium: Shortened period, decreased amount, lower-risk location/dates
- Similar premium: Date shift with comparable risk profile
Request ID Tracking
Include an X-Request-Id header for request tracing and debugging. Each response includes this header for correlating requests with support inquiries.
Note: This endpoint does not support idempotency caching. Calling it again generates a new modification quote each time. Idempotency is supported when purchasing the modification quote via
POST /quotes/{quote_id}/purchase.
Best Practices
- Verify policy status first: Call
GET /policies/{id}before attempting modification - Validate dates client-side: Check 12-month window before API call
- Show pricing comparison: Display original vs new premium to customer
- Explain the process: Customer's original policy stays active until they purchase
Next Steps
After creating a modification quote:
- Display all pricing options to customer
- Show comparison with original policy (premium difference)
- When customer selects option:
POST /quotes/{quote_id}/purchase - Send updated policy confirmation
- Update your booking system with new policy_id