# Renewal Management and Auto-Renewal



Overview [#overview]

Renewal Management covers different modes for renewing a policy:

* **Standard**: Manual renewal created and managed with explicit actions taken by the client, extending the policy's `endTime` by creating a new term
* **Auto-Renewal**: Automatic handling of renewal creation and optionally, issuance
* **Do Not Renew**: Mark policies for non-renewal when they do not meet underwriting or appetite thresholds, using the auto-renewal mechanism
* **Renewal with a Gap**: Renewing the policy such that the new term starts strictly *after* the preceding term's end time.

Renewal management operates at a term level, so that terms contain the settings for automatic renewal handling. Only the latest term can have an active Auto-Renewal.

<Callout>
  When renewing with a gap, there is no gap segment created. Rather, the terms have a period of time between them that no term or segment covers.
</Callout>

Manual Renewal [#manual-renewal]

To manually renew a policy, create a [renewal transaction](/features/policy-management/policy-transactions) with a new `endTime` for the policy. This end time must be strictly greater than the current policy end time.

You may also make coverage changes, installment plan changes, etc. as you would be able to do with a standard policy change. The lifecycle of the renewal transaction follows the same process as other policy transactions.

<span id="autorenewal" />

Auto-Renewal [#auto-renewal]

Each <ApiLink name="AccountResponse">account</ApiLink> can be assigned an <ApiLink name="AutoRenewalPlanRef">Auto-Renewal Plan</ApiLink>. If one is set, then an <ApiLink name="AutoRenewalResponse">Auto-Renewal</ApiLink> will be created based on the `renewalCreateLeadDays` property on the plan.

If there is not already an Auto-Renewal set on the latest term, one can be created manually with the <ApiLink name="createAutoRenewal">Create Auto-Renewal</ApiLink> API endpoint.

The auto-renewal has a set of triggers to create a <ApiLink name="PolicyTransactionResponse">renewal transaction</ApiLink>, and advance it through acceptance and issuance.

An existing auto-renewal can be updated to change the times that renewal transaction will be accepted and/or issued.

Policies that have an auto-renewal plan that has `generateAutoRenewals` set to `true` will have auto-renewals added to new policy terms at the time they are created. Policies issued with quotes that have this setting will be created with an auto-renewal on their first term.

Auto-Renewal States [#auto-renewal-states]

The `autoRenewalState` property on the auto-renewal has the following meanings:

* `active`: The auto-renewal is active and the trigger times set will continue to advance the renewal transaction through issuance
* `issued`: A renewal transaction for the term has been issued and so the auto-renewal is no longer active
* `doNotRenew`: The renewal transaction will not be accepted or issued, and other renewal transactions for that policy will likewise be prevented from issuance.
* `terminated`: The renewal referenced has reached a terminal state (`invalidated`, `rejected`, `refused`, or `discarded`). There will be no additional plugin calls or events for the auto-renewal.
* `discarded`: The auto-renewal will be inactive with no plugin calls or events.
* `error`: The auto-renewal is in an error state and cannot advance, but it can be <ApiLink name="updateAutoRenewal">updated</ApiLink> via the API.

<span id="auto_renewal_plugin" />

Auto-Renewal Plugin [#auto-renewal-plugin]

For each of the non-null time on the auto-renewal options, before any automatic action, a plugin will fire. You can use this plugin to generate notices, call external systems, etc.

Manually advancing the renewal transaction will not trigger the plugin. However, if the transaction is manually accepted and then allowed to be issued through the auto-renewal workflow, it will trigger the plugin at the expected time with `renewalEvent: issue`.

The renewal options object itself will be sent to the plugin as part of this request:

```
{
    renewalEvent": create | issue | accept
    "autoRenewal": { /* The entire Auto-Renewal as would be sent through the API */ }
}
```

The renewal event will be `create`, `accept`, or `issue`.

And the plugin can return a response of this form to update the auto-renewal:

```
{
    autoRenewalState: active | doNotRenew | discarded
    renewalTransactionType: string
    newTermDuration: integer?
    renewalTransactionCreateTime: DateTime?
    renewalTransactionAcceptTime: DateTime?
    renewalTransactionIssueTime: DateTime?
}
```

<Callout>
  If the `autoRenewalState` is set to `discarded` on the `create` event, then no renewal transaction will be created.
</Callout>

Manual Renewal Operations on an Auto-Renewal [#manual-renewal-operations-on-an-auto-renewal]

It is OK to create a renewal transaction while an auto-renewal is active. You may want to then update the auto-renewal with the locator of the alternate renewal so that it is then managed automatically.

Advancing a renewal transaction manually will not modify the `renewalTransactionAcceptedTime` or `renewalTransactionIssuedTime` properties. These times are specifically reserved for automatic actions and are not updated during manual advancements.

If *any* renewal is issued for that term, either automatically or manually, the auto-renewal for that term, if it exists, will change state to `issued`.

If the renewal transaction referenced by the auto-renewal is manually advanced ahead of the planned automatic events, the plugin will still fire but no automatic action will occur.

Cancellations and Auto-Renew [#cancellations-and-auto-renew]

When a renewal transaction being managed by Auto-Renewal is followed by a cancellation, the renewal will be reset to `draft` state. The auto-renewal will then become `invalidated` (but the renewal itself will *not* be invalidated.) You can manage the renewal manually from that point, or reactiveate the auto-renewal, which will advance the renewal on the next pending trigger time for the auto-renewal.

Do Not Renew [#do-not-renew]

The auto-renewal can put the policy into "Do Not Renew" status <ApiLink name="markPolicyForDoNotRenew">via the API</ApiLink>. It will then have state `doNotRenew`. No renewal transaction for that policy will be permitted to be issued when an auto-renewal with this state exists on the policy.

Use the <ApiLink name="reactivateAutoRenewal">reactivate</ApiLink> endpoint to lift the do-not-renew status.

Renewal with a Gap [#renewal-with-a-gap]

By specifying an `effectiveTime` for the renewal that is after the current policy end time, the renewal will be created with a gap. The new term, and the first segment within that term, will have `startTime` equal to the renewal's `effectiveTime`.

<Callout>
  Unlike [reinstatement with a gap](/features/policy-management/reinstatements#reinstatementWithGap), there is no gap segment created for a renewal with a gap. The gap period is not covered by any terms or segments.
</Callout>

See Also [#see-also]

* [Renewal Management and Auto-Renewal API](/api/policy-management/renewal-management)
* <ApiLink name="AutoRenewalPlanRef">
    Configuration
  </ApiLink>