Cancel an active policy and issue a refund of the premium.
A policy can be cancelled until 48 hours before its cover starts (the default; error.details.context.lead_hours gives the window that applied), measured from the cover start time in the timezone of the insured location. Inside that window the request is refused with 422 and error.details.original_error_code = CANCELLATION_WINDOW_CLOSED; error.details.context.cutoff_at gives the cut-off as ISO-8601 with the location's UTC offset. Some sales channels do not allow cancellation at all (CANCELLATION_NOT_PERMITTED). Once cover has started, cancellation is refused with COVERAGE_ACTIVE.
Annual and annual cat policies can be cancelled at any time, before or during the term, and the cancellation takes effect immediately. The request takes no effective date. If the cover has not started the full premium is refunded. Once it has started the refund is the premium for the unexpired days of the term, less the cancellation fee agreed for your account (GST inclusive), and never below zero. If a claim on the policy has already been approved or paid there is no refund, but the policy is still cancelled. Any claim not yet approved or paid is closed by the cancellation, and no claim can be approved afterwards.
This operation is idempotent with a 7-day TTL — use X-Request-Id for safe retries.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Cancellation & Refund Flow
flowchart TB
A["POST /policies/{id}/cancel"] --> B{"Policy Status?"}
B -->|"Active"| C{"Timing?"}
B -->|"Already cancelled"| D["409 ALREADY_CANCELLED"]
B -->|"Completed"| E["422 POLICY_COMPLETED"]
B -->|"Has paid claims"| F["422 HAS_PAID_CLAIMS"]
C -->|"Before coverage starts"| G["Full refund"]
C -->|"During coverage"| H["Pro-rata refund<br/>for unused days"]
C -->|"After coverage"| I["No refund"]
G --> J["Policy cancelled<br/>+ refund details"]
H --> J
I --> J
style A fill:#e3f2fd
style J fill:#e8f5e9
style D fill:#fff3e0
style E fill:#fce4ec
style F fill:#fce4ec
What This Endpoint Does
- Validates Cancellation: Checks policy can be cancelled
- Calculates Refund: Determines refund amount based on timing
- Processes Cancellation: Updates policy status to cancelled
- Returns Refund Details: Provides breakdown of refund amount
When to Use This Endpoint
- Customer cancels their booking/trip
- Customer requests policy cancellation
- Booking was refunded and insurance no longer needed
Request Parameters
| Parameter | Required | Description |
|---|---|---|
| reason | Yes | Why policy is being cancelled (e.g., "Trip cancelled") |
Understanding the Response
policy object contains:
| Field | Description |
|---|---|
| id | UUID of the cancelled policy |
| policy_number | Human-readable reference |
| status | Always "cancelled" |
| cancelled_at | Timestamp of cancellation |
cancellation object:
| Field | Description |
|---|---|
| cancelled_at | When cancellation was processed |
| reason | Cancellation reason provided |
| type | Cancellation type (e.g., "customer_requested") |
| refund_amount | Total amount to be refunded |
| refund_tax_breakdown | Tax components of refund |
| refund_tax_total | Total tax portion of refund |
Refund Calculation
Refunds are calculated based on:
- Before coverage starts: Full premium refund (minus admin fee if applicable)
- During coverage period: Pro-rata refund for unused days
- After coverage ends: No refund (policy completed)
Error Handling
| Error | Code | Description |
|---|---|---|
| POLICY_NOT_FOUND | 404 | Policy doesn't exist |
| ALREADY_CANCELLED | 409 | Policy was already cancelled |
| POLICY_COMPLETED | 422 | Coverage period has ended |
| HAS_PAID_CLAIMS | 422 | Policy has paid claims - cannot cancel |
| COVERAGE_ACTIVE | 422 | Cannot cancel while coverage is active (partner-specific) |
| ANNUAL_POLICY_NOT_CANCELLABLE | 422 | Annual policies cannot be cancelled via API |
Idempotency
Include X-Request-Id header for safe retries:
- System caches responses for 7 days (168 hours)
- Safe to retry on network failures
- Returns original cancellation response if already processed
- Check
X-Idempotent-Replayed: trueheader to detect cached responses - Only 2xx and 4xx responses are cached — 5xx errors are always retryable
Important Considerations
- Claims impact: Policies with paid claims cannot be cancelled
- Timing matters: Refund amount depends on when cancellation occurs
- Irreversible: Cancellation cannot be undone - customer would need new quote
- Pending claims: Any pending claims are cancelled with the policy
Best Practices
- Confirm with customer: Cancellation is irreversible
- Use idempotency: Always include X-Request-Id for production
- Show refund amount: Let customer know expected refund before confirming
- Store cancellation details: Keep record of cancellation reason and refund