Overview

The policy is the individual insurance contract — one per product sold in an emitted order. It is created right after the order's emission and becomes the source of truth about the coverage: the policy number, the term, the effective coverages, the decomposed premium and the event trail.

Policy lifecycle

How to read the diagram: blue = policy in force · red = canceled (emits a webhook) · green = natural end of term (no webhook).

Status	Meaning
active	The policy is in force from creation. The insurer's issuance confirmation does not change the status: it shows up as the external_policy_number being filled in, and emits the issued webhook. Until then, external_policy_number is null.
canceled	The policy was canceled — through policy cancellation, through order cancellation after emission, or by the insurer. The status changes at the moment of cancellation and emits the canceled webhook.
finished	The term ended (term.end_date). Terminal status, without a webhook — the end of term is known since issuance.

Premium refund on cancellation

The refund, when due, is computed over what has been paid, as of the moment the cancellation is requested:

• Within 7 calendar days of contracting — cooling-off right: full refund of what was paid.
• After 7 days: proportional refund — the part of what was paid that exceeds the coverage period already elapsed.

Endpoints

Endpoint	Description
GET /v1/insurance/policies/{policy_key}	Retrieves one policy.
GET /v1/insurance/policies?order_key=	Lists the policies of an emitted order.
POST /v1/insurance/policies/{policy_key}/cancel	Cancels a policy individually.