Skip to main content

Stops

Stopping your policy​

Once a policy is active (meaning SIGNED or STARTED), you can stop that policy to end the coverage. You can decide to stop at any time between the policy start date and its end date, which is calculated as your policy start date plus the contract duration as defined in your product configuration. Your policy becomes STOPPED and automatic workflows will no longer run for that policy, except for billing if there are still funds to balance out. When stopping a policy on a past date, your customer may be refunded because of pro-rata calculations. You can also choose to not refund customers for specific stop reasons - for example if you stop the policy because of non payment. Find out more about product customization here.

You can also elect to suspend your policy. A SUSPENDED policy will not be billed for its suspended time, but automatic workflows will continue running. You can then decide to reactivate the policy, at which point it will become STARTED once again.

Scheduled stops and the undo window​

On tenants where the scheduled stop model is enabled, POST /policies/{policyId}/stop records the request instead of applying it. The policy keeps its current status, keeps billing and keeps its coverage; stop carries the requested stopDate and an executesAt, and stoppedAt stays absent until the stop executes. executesAt is the later of the requested stop date and the end of the tenant's undo window (two hours by default), so a stop requested for today — or backdated — still waits out that window. The window only defers execution: once it runs, coverage ends on the requested date, not on the instant the job ran.

stop.requestedBy says who asked: their userId, the businessRoleId they acted under and, for a broker, their name (or email when they have no name).

A scheduled stop lives on its own branch until it executes, which is what lets the policy carry on as if nothing had been requested. Read that branch from GET /policies/{policyId}/branches: it is the open one with branchType STOP.

Saving a request before committing to it​

POST /policies/{policyId}/stop?draft=true records the same request without acting on it: the stop is written to its branch so it can be read back and resumed from anywhere, while coverage, billing and reporting stay untouched and nothing is scheduled. stop does not appear on the policy, so the draft is invisible to everything that reads a scheduled stop — read it with GET /policies/{policyId}?branchId={branchId}. Stop dates are not checked against their notice periods, since a draft is saved before one is picked; the confirming call checks them. Saving again replaces the draft, and drafting over a stop that is already scheduled is refused with MAX_BRANCH_TYPE_OPENED rather than silently overwriting it.

Calling a stop off​

Closing the branch is what calls a stop off, drafted or already scheduled: POST /policies/{policyId}/branches/{branchId}/invalidate, with a reason and an optional free-text comment. The policy is left in force with no gap in coverage, its pending execution is dropped, and stop disappears from the policy. Whoever may request a stop reason may call it off, so a reason reserved to your teams cannot be cancelled by the insured; a reason that reserves itself to nobody in particular falls back to the user who requested the stop, a broker of the policy's brokerage firm, or a superuser. The brokers of the wholesale firm the policy is distributed for may call off any stop, whatever its reason. Anyone else gets FORBIDDEN. Closing a branch that is already closed changes nothing.

Stop reasons that require proof​

A stop reason can declare the document categories it needs as evidence — a sale certificate for a vehicle sold, a withdrawal notice for a professional card. Declaring any of them is what makes the reason manager-validated: POST /policies/{policyId}/stop then answers STOP_DOCUMENTS_MISSING, listing the categories still absent, until every one of them sits on the stop branch. The categories are the same policyholderDocuments entries the rest of the platform classifies and reviews.

Once they are all there, the request is recorded and goes to the derogation queue instead of being scheduled: coverage continues, premiums keep being called, and no execution job exists yet. A manager accepts or refuses each document, with a reason on a refusal. A refused document stops counting as provided, so the request stays in the queue but can no longer be approved, and the requester is notified to replace it — the request never restarts and its effective date never moves. Approving the derogation is what schedules the execution, at the later of the requested date and the end of the undo window; an approval that lands after the requested date executes retroactively on that date.

Finding stops that have not run yet​

Both of the states above leave the policy in force, so neither shows up under a stopped status. POST /brokerage-firms/{brokerageFirmId}/policies/search takes a pendingStopStates filter to find them:

  • SCHEDULED — a stop that will execute on its own date, whether it is waiting out the undo window or simply dated in the future.
  • AWAITING_VALIDATION — a manager-validated request still in the derogation queue, with no execution booked until someone approves it.

A policy is in one state or the other, never both, so asking for both returns every stop that has not run. The filter widens a search rather than narrowing it: combined with statuses, you get the policies matching those statuses plus the ones with a pending stop, which is what makes "stopped, or about to be" expressible in a single query.

Each result carries isStopAwaitingValidation, so a list can label the two apart without reading the stop branch. Only policies whose coverage is still running are returned — once a stop executes, the policy is POLICY_STOPPED and leaves the filter. Drafts never appear: nothing is recorded on the policy until the request is confirmed, so there is no pending stop to find.

Stop configuration​

You can configure how and when policies should stop. For each product, you determine a list of stop configurations that contain:

  • the stop reason
  • stop date limits, such as allowing stops in the past or in the future
  • refund behavior, so whether the customer should be refunded for this specific stop reason
  • how long this stop reason is valid for: for example, you might let customers stop with FULL_CANCELLATION only for the first two weeks their policy is active

A stop reason can also require the client-submitted stop date to fall within a window around today — a minimum offset, a maximum offset, or both — so a reason known to attract retroactive abuse (unjustified refunds, loss of collected premiums) can be restricted to future dates only, or a reason meant only for near-term use can be closed off beyond a certain point. For example, a reason configured with a minimum offset of one day rejects any stop date before tomorrow, even the current day; one configured with a maximum offset of 30 days rejects any stop date beyond that — both with INVALID_STOP_REASON_DETAILS. Stop dates are still checked against the other stop date limits above (policy start, and whether the future is allowed at all) — whichever rule the requested date violates first is the one returned.

A stop reason can instead anchor its date limit to the policy's next renewal date rather than today. Configured this way, the reason is only usable while today is strictly before the renewal date minus that duration — for example, a two-month notice period rejects the reason with INVALID_STOP_REASON_DETAILS from the moment exactly two months remain before renewal, not only once fewer than two months remain. Such a reason takes no stop date as client input at all: the effective stop date is always the policy's next renewal date, since renewal is the only date the reason is meant to apply to.