# Policy Status



Overview [#overview]

You can easily obtain a policy's status in Socotra and listen on status updates. Socotra defines the following policy statuses:

| Status          | Meaning                                                                                                                                                                                                                                                        |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pending`       | The policy has not yet reached its `startTime`, or it was cancelled prior to reaching its `startTime`.                                                                                                                                                         |
| `expired`       | The policy's `endTime` is in the past.                                                                                                                                                                                                                         |
| `cancelled`     | The transaction stack contains an issued cancellation that has an effective time in the past. It is removed when the policy is reinstated or the cancellation is reversed.                                                                                     |
| `cancelPending` | The transaction stack contains an issued cancellation that has an effective time in the future. The status is removed when the policy is reinstated (with or without a gap), the cancellation is reversed, or the cancellation effective time enters the past. |
| `onRisk`        | The policy is not `pending`, `expired`, or `cancelled`.                                                                                                                                                                                                        |
| `delinquent`    | There is an active [delinquency](/features/billing/delinquency). This status is set when delinquency is `inGrace` and unset when the delinquency is in `preGrace`, `settled`, or `lapseTriggered`.                                                             |
| `doNotRenew`    | The latest term's [auto-renewal](/features/policy-management/renewal-management) object has `doNotRenew`.                                                                                                                                                      |

Socotra does not attempt to impose a singular status in cases where a policy can be said to fulfill multiple state conditions. This is why the platform exposes `statuses`, an array of enumerated values, on <ApiLink name="PolicyResponse" />. For example, a policy's status can be `[onRisk, cancelPending]`.

Obtaining Policy Status [#obtaining-policy-status]

API [#api]

Policy status is provided as `statuses` on the `PolicyResponse` returned by endpoints such as <ApiLink name="fetchPolicy" /> and supplied as inputs to plugins like the [precommit plugin](/configuration/plugins/precommit).

<span id="policy-status-event-stream" />

Event Stream [#event-stream]

The [event stream](/configuration/general-topics/events) includes `policy.status.update`, which is emitted on any change to policy status. The event body includes `newStatuses` and `removedStatuses` to indicate which statuses may have been added and which may have been removed, respectively. Both `newStatuses` and `removedStatuses` have `ListPageResponsePolicyStatus` values:

<ApiSchema name="ListPageResponsePolicyStatus" />

For example, when a new on-risk policy is issued, you should expect to see an event like this:

```json
{
	"locator": "...",
	"requestId": "...",
	"userLocator": "...",
	"timestamp": "...",
	"type": "policy.status.update",
	"data": {
		"removedStatuses": {
			"listCompleted": true
		},
		"policyLocator": "...",
		"newStatuses": {
			"listCompleted": true,
			"items": ["onRisk"]
		}
	}
}
```

If you were to then issue a cancellation effective now or in the past, a new event would be emitted:

```json
{
	"locator": "...",
	"requestId": "...",
	"userLocator": "...",
	"timestamp": "...",
	"type": "policy.status.update",
	"data": {
		"removedStatuses": {
			"listCompleted": true,
			"items": ["onRisk"]
		},
		"policyLocator": "...",
		"newStatuses": {
			"listCompleted": true,
			"items": ["cancelled"]
		}
	}
}
```

As the event implies, `statuses` in `PolicyResponse` would be `[cancelled]`.


## API Reference

ListPageResponsePolicyStatus
Properties:
  listCompleted (boolean, required)
  items (Enum[], required)