# Execute policy transactions



import Image from 'next/image';

This article explains how to **execute policy transactions** in the Socotra Insurance Suite.

Overview [#overview]

What will I learn in this tutorial? [#what-will-i-learn-in-this-tutorial]

By the end of this tutorial, you will have an understanding of:

* Policies in Socotra, including their terms and segments.
* How to describe, change, renew, cancel, or reinstate a policy using the Socotra API.

What will I need? [#what-will-i-need]

You will need the following:

* A Postman account
* [A copy of the Socotra Sample Collection and Environment](/getting-started/socotra-sample-postman-collection-and-environment)
* A workspace configured to use the Socotra API

For more information about using Postman, see: [Set up Postman to use the Socotra API](/getting-started/set-up-postman-to-use-the-socotra-api)

Key concepts [#key-concepts]

What is a policy? [#what-is-a-policy]

In Socotra, a **policy** is a transaction between the **insurer** (an insurance company) and the **insured** (a customer). Policies outline products provided to the insured by the insurer.

For example, a home owner’s insurance policy typically contains information related to:

* The exposure (the home being insured)
* The coverages (definitions of how much the home is insured for)
* The general administration of the policy

Policies are subdivided into **terms** and **segments**.

What are terms and segments? [#what-are-terms-and-segments]

Terms [#terms]

In an insurance policy, a **term** is the period of time between the policy's start and end.

A term spans from the initial effective date to the expiration date of the policy.

When a policy is renewed, a new term is created and the expiration date is pushed further into the future, typically by the same length of time as the original term.

For example, the terms of a homeowners policy that’s been renewed twice would look something like sample below:

* Term 0: January 2024 - January 2025 (initial policy creation)
* Term 1: January 2025 - January 2026 (first renewal)
* Term 2: January 2026 - January 2027 (second renewal)

Segments [#segments]

In an insurance policy, a segment is a subdivision of a term. A segment contains all of the elements of a policy, meaning any of the following:

* Products
* Policy Lines
* Exposure Groups
* Exposures
* Coverages

When a policy is first created, it has a single default term and a single default segment. The graphic below shows an example of a basic policy.

<Image src="/images/execute-policy-transactions/image9.png" alt="alt text" width={1999} height={1082} unoptimized />

Graphical representation of a basic policy, term, segment, and elements. It begins on the Effective Date (Eff Date) and ends on the Expiration Date (Exp Date).

<span id="policyTransaction" />

What is a policy transaction? [#what-is-a-policy-transaction]

A **policy transaction** is a change made to a policy. There are four basic types of policy transactions that can be made to an existing policy:

* Change
* Renew
* Cancel
* Reinstate

<Callout>
  In addition to the above, an **issuance policy transaction** is automatically created and issued by the system when a quote moves to the `issued` state, and the resulting policy is created, while a **reversal policy transaction** may be issued to reverse a previously issued transaction. See the [Policy Transactions](/features/policy-management/policy-transactions) feature guide for more information.
</Callout>

It takes two steps to make a policy transaction:

* Creation (define instructions for what to do to the policy)
* Issuance (execute the instructions)

In the section below, we're going to cover some examples of each of these types of policy transactions.

Example scenarios [#example-scenarios]

Example 1 - Changing a policy [#example-1---changing-a-policy]

<Image src="/images/execute-policy-transactions/image14.png" alt="image1" width={1999} height={1135} unoptimized />

In this example, we see a policy with a single term and two segments. This means that the policy was modified sometime during the first term.

In Segment A, they have two coverages:

* **Coverage A**: $550,000 limit
* **Coverage B**: 10% limit

Mid-way through the customer’s first term, they request that their limit for Coverage A be increased from $550,000 to $600,000. This would be accomplished by creating and issuing a change transaction.

Upon issuance of the change transaction, a new segment is created in the term with two coverages:

* **Coverage A**: $600,000 limit (increased from $550,000)
* **Coverage B**: 10% (stays the same)

Example 2 - Renewing a policy [#example-2---renewing-a-policy]

<Image src="/images/execute-policy-transactions/image5.png" alt="image2" width={1999} height={624} unoptimized />

In this example, we see a continuation from Example 1. The customer wants to renew their coverage, but they also want to add an additional Personal Property coverage. This would be accomplished by creating and issuing a renewal transaction containing data for the new coverage.

Upon issuance of the renewal transaction, the system would:

* Create a new term
* Create a new segment in the term
* Add all requested coverages to the new segment

Example 3 - Canceling a policy [#example-3---canceling-a-policy]

<Image src="/images/execute-policy-transactions/image13.png" alt="image3" width={1999} height={624} unoptimized />

Continuing the scenario in examples 1 and 2, the customer has decided they would like to cancel their policy, which has four months remaining until the end of its second term.

Upon creating and issuing the cancellation transaction, the system would make a “gap” segment to represent the remaining period where no coverage was provided to the customer.

Tutorials [#tutorials]

Scenario - Homeowner seeking to modify home insurance coverage [#scenario---homeowner-seeking-to-modify-home-insurance-coverage]

For these tutorials, let’s use the example of a homeowner called Homer Sample.

* Homer Sample owns a home with a roof that is 15 years old.
* He has an existing policy from Example Insurance with an effective date of January 1, 2024.
* The policy has two coverages:
  * Coverage A, with a limit of $550,000
  * Coverage B, with a limit of 10%

For these tutorials, we’ll use Postman to simulate policy transactions Socotra can make based on Homer Sample’s requested changes.

Tutorial 1 - Making a change to a policy [#tutorial-1---making-a-change-to-a-policy]

Homer Sample reaches out to Example Insurance Company with a request:

* Homer Sample wants to increase the coverage on his dwelling from **:math:`550,000** to **`\ 600,000**.
* He wants this to take effect on **June 1, 2024**.

We can easily accomplish this with the Socotra API.

However, before we can make any policy changes, first we need to locate his customer account number.

<span id="11---locating-customers-account-number-in-postman" />

1.1 - Locating customer's account number in Postman [#11---locating-customers-account-number-in-postman]

To locate a customer’s account number using the Socotra API in Postman, follow these steps:

1. In the Socotra Sample Collection, navigate to **Policy > Accounts > List Accounts**.
2. Click **Send** to run the request.
3. The response body will include a list of all the accounts on the current tenant.
4. Locate the account you want to use. For this tutorial, we’ll use Homer Sample’s account.

<Image src="/images/execute-policy-transactions/image3.png" alt="image4" width={1999} height={1223} unoptimized />

5. Copy the account’s `locator` value (the unique identifier of the account) and paste it into the `accountLocator` environment variable in the Socotra Sample Environment.

**Tip**: Keep the Socotra Sample Environment open as a tab in Postman so you can easily switch back and forth between it and the requests.

<span id="12---locating-customers-policy-in-postman" />

1.2 - Locating customer's policy in Postman [#12---locating-customers-policy-in-postman]

The next step is to locate Homer Sample’s policy.

When a quote is issued in Socotra, the system automatically generates a corresponding policy. To find the policy, we’ll first search for the issued quote that created it.

To locate a customer’s policy using the Socotra API in Postman, follow these steps:

1. In the Socotra Sample Collection, navigate to **Policy > Quotes > List Account’s Quotes**.
2. Run the request.
3. Locate the quote in the response body. The relevant quote should have a `quoteStatus` of `issued`.

<Image src="/images/execute-policy-transactions/image8.png" alt="image5" width={1999} height={1223} unoptimized />

4. Once you’ve identified the issued quote, scroll down until you find the quote’s `policyLocator`.

<Image src="/images/execute-policy-transactions/image6.png" alt="image6" width={1999} height={1223} unoptimized />

5. Copy the policy locator and paste it into the `policyLocator` environment variable in the Socotra Sample Environment.

<span id="13---retrieving-customers-policy-details" />

1.3 - Retrieving customer's policy details [#13---retrieving-customers-policy-details]

Now that we have Homer Sample’s policy number, we can retrieve details about the elements of his policy.

In particular, we’re interested in finding the policy’s:

* Exposures (i.e. the dwelling)
* The exposure’s coverages

To retrieve a customer’s policy details, we can use the Describe Policy Snapshot endpoint of the Socotra API, which retrieves information about a policy as it exists at a current date and time.

To locate a customer’s policy details, follow these steps:

1. In the Socotra Sample Collection, navigate to **Policy > Policies > Describe Policy Snapshot**.

2. In the date query parameter, enter the following: 2024-06-01T00:00:00Z.
   1. This is a timestamp that tells the endpoint to retrieve the policy as it existed on the specified date.
   2. In this scenario, Homer Sample wants the insurance coverage to change on this date, so we’ll retrieve the policy information at this point to ensure we have the most up-to-date information.

3. Run the request.

The response body will look similar to the JSON contained in the code block below:

```json
{
	"locator": "01J5E660YXGBBNT26TQESCZHQF",
	"accountLocator": "01J5E5RNSWR0QVPCFF2XT83CFK",
	"productName": "Ho3",
	"timezone": "America/New_York",
	"currency": "USD",
	"transaction": {
		"locator": "01J5E660YXGBBNT26TQESCZHQF",
		"transactionCategory": "issuance",
		"transactionType": "issuance",
		"effectiveTime": "2024-01-01T00:00:00Z",
		"issuedTime": "2024-08-16T18:11:45.647779Z",
		"preferences": {
			"installmentPreferences": {
				"installmentPlanName": "monthly10"
			}
		},
		"segment": {
			"locator": "01J5E66VBHEQWA7Z8Y3XDVFAXV",
			"segmentType": "coverage",
			"startTime": "2024-01-01T00:00:00Z",
			"endTime": "2025-01-01T00:00:00Z",
			"element": {
				"type": "Ho3Segment",
				"locator": "01J5E66VBHEQWA7Z8Y3XDVFAXV",
				"parentLocator": "01J5E66VBHEQWA7Z8Y3XDVFAXV",
				"elements": [
					{
						"type": "DwellingPolicy",
						"locator": "01J5E66VBJYBESTDJFYAZBPAXX",
						"parentLocator": "01J5E66VBHEQWA7Z8Y3XDVFAXV",
						"elements": [
							{
								"type": "Coverage_bPolicy",
								"locator": "01J5E66VBMACX1D1K00K0YYZNE",
								"parentLocator": "01J5E66VBJYBESTDJFYAZBPAXX",
								"coverageTerms": {
									"Coverage_b_limit": "CB20"
								},
								"staticLocator": "01J5E660YX6ZEJSYTVN9XAXF14",
								"originalEffectiveTime": "2024-01-01T00:00:00Z"
							},
							{
								"type": "Coverage_aPolicy",
								"locator": "01J5E66VBKYGJZT44JYPCNA3T6",
								"parentLocator": "01J5E66VBJYBESTDJFYAZBPAXX",
								"coverageTerms": {
									"Coverage_a_limit": "CA550000"
								},
								"staticLocator": "01J5E660YXV5ZQC2MM6CW5DW8Q",
								"originalEffectiveTime": "2024-01-01T00:00:00Z"
							}
						],
						"data": {
							"windHailExclusion": "No",
							"yearBuilt": 2013,
							"distanceToCoast": 3000,
							"occupancy": "Primary"
						},
						"staticLocator": "01J5E660YX1PHQNZ1F0404830V",
						"originalEffectiveTime": "2024-01-01T00:00:00Z"
					}
				],
				"data": {
					"applicantInsuranceScore": "800",
					"applicantDob": "1980-01-01",
					"applicantFirstName": "Homer",
					"applicantLastName": "Sample",
					"noPriorInsurance": "No"
				},
				"staticLocator": "01J5E660YXGBBNT26TQESCZHQF",
				"originalEffectiveTime": "2024-01-01T00:00:00Z"
			},
			"duration": 12
		}
	},
	"delinquencyPlanName": "defaultDelinquencyPlan"
}
```

The **`transaction`** object is the most relevant portion of the response body for the purposes of this tutorial. It contains all of the information about the segment, exposure, and coverages.

Navigating down the JSON tree, the transaction object contains:

* `transaction`
  * `segment` (a default period of 12 months from startTime to endTime)
    * `element` (the exposure group)
      * `elements` (the exposures, i.e. the dwelling)
        * `elements` (the coverages, i.e. Coverage\_aPolicy and Coverage\_bPolicy)

For the purposes of this tutorial, Homer Sample wants to change the `coverage_a_limit` from $550,000 to $600,000.

<span id="14---creating-a-change-transaction" />

1.4 - Creating a change transaction [#14---creating-a-change-transaction]

Now that we’ve located Homer Sample’s policy, we’re ready to create a change transaction to modify it.

There are essentially two steps to making any transaction, including change transactions:

* Creating the transaction
* Issuing the transaction

In this section, we’ll cover creating the transaction. In the next section, we’ll cover issuing the transaction.

We’re going to change the coverage from $550,000 (`CA550000`) to $600,000 (`CA600000`).

The code sample below shows the `Coverage_aPolicy` (extracted from the full code block above).

```json
{
	"type": "Coverage_aPolicy",
	"locator": "01J5E66VBKYGJZT44JYPCNA3T6",
	"parentLocator": "01J5E66VBJYBESTDJFYAZBPAXX",
	"coverageTerms": {
		"Coverage_a_limit": "CA550000"
	},
	"staticLocator": "01J5E660YXV5ZQC2MM6CW5DW8Q",
	"originalEffectiveTime": "2024-01-01T00:00:00Z"
}
```

The `staticLocator` is the unique identifier we'll use to target the coverage for modification.

To create a change transaction to a policy, follow these steps:

1. While viewing the Socotra Sample Collection, navigate to **Policy > Policies > Post-issuance Flows > Policy Change > Create Change Transaction**.
2. Click the **Body** tab.
3. Paste the `staticLocator` value of the `Coverage_aPolicy` object into the request body.

<Image src="/images/execute-policy-transactions/image4.png" alt="image7" width={1999} height={1223} unoptimized />

4. Set the `effectiveTime` field to June 1, 2024 (`2024-06-01T00:00:00Z`).

<Image src="/images/execute-policy-transactions/image11.png" alt="image8" width={1999} height={1201} unoptimized />

5. Click **Send**.
6. You should receive a response message containing a `locator` value.

<Image src="/images/execute-policy-transactions/image1.png" alt="image9" width={1999} height={1223} unoptimized />

When you create a transaction, it’s assigned a unique identifier stored in the locator field. Note that the transaction is in a draft state, meaning it won’t go into effect until it’s issued.

1. Copy and paste the locator value into the transactionLocator environment variable in the Socotra Sample Environment.

<span id="15---issuing-a-change-transaction" />

1.5 - Issuing a change transaction [#15---issuing-a-change-transaction]

Now that we’ve created a change transaction for Homer Sample’s policy, we’re finally ready to issue the transaction.

To issue a change transaction, follow these steps:

1. While viewing the Socotra Sample Collection, navigate to **Policy > Policies > Post-issuance Flows > Policy Change > Issue Change Transaction**.
2. Click **Send**.
3. You should receive a response indicating success.

<Image src="/images/execute-policy-transactions/image10.png" alt="image10" width={1999} height={1223} unoptimized />

<span id="16---viewing-the-changed-policy" />

1.6 - Viewing the changed policy [#16---viewing-the-changed-policy]

Now that the change transaction has been issued, we can check the policy to see the reflected changes to Homer Sample’s policy.

To do that, we’ll use the **Describe Policy Term** endpoint (**Policy > Policies > Describe Policy Term**). Running this endpoint for this policy reveals that there are now two subsegments:

* The original segment (the policy before the change)
* The new segment (the policy after the change)

The JSON in the code block below should look similar to your response body. Note the two objects in the *subsegments* array.

```json
{
	"policyLocator": "01J5E660YXGBBNT26TQESCZHQF",
	"locator": "01J5E660YXGBBNT26TQESCZHQF",
	"staticLocator": "01J5E660YXGBBNT26TQESCZHQF",
	"termNumber": 0,
	"startTime": "2024-01-01T00:00:00Z",
	"endTime": "2025-01-01T00:00:00Z",
	"duration": 12,
	"durationBasis": "months",
	"subsegments": [
		{
			"locator": "01J5E66VBHEQWA7Z8Y3XDVFAXV",
			"type": "coverage",
			"startTime": "2024-01-01T00:00:00Z",
			"endTime": "2024-06-01T00:00:00Z",
			"duration": 5.001344086021505,
			"elements": [
				{
					"locator": "01J5E66VBKYGJZT44JYPCNA3T6",
					"staticLocator": "01J5E660YXV5ZQC2MM6CW5DW8Q",
					"type": "Coverage_aPolicy",
					"chargeSummaries": {
						"coverage_a_premium": 343.84
					}
				},
				{
					"locator": "01J5E66VBMACX1D1K00K0YYZNE",
					"staticLocator": "01J5E660YX6ZEJSYTVN9XAXF14",
					"type": "Coverage_bPolicy",
					"chargeSummaries": {
						"coverage_b_premium": 68.77
					}
				},
				{
					"locator": "01J5E66VBHEQWA7Z8Y3XDVFAXV",
					"staticLocator": "01J5E660YXGBBNT26TQESCZHQF",
					"type": "Ho3Segment",
					"data": {
						"noPriorInsurance": "No",
						"applicantInsuranceScore": "800",
						"applicantDob": "1980-01-01",
						"applicantFirstName": "Homer",
						"applicantLastName": "Sample"
					}
				},
				{
					"locator": "01J5E66VBJYBESTDJFYAZBPAXX",
					"staticLocator": "01J5E660YX1PHQNZ1F0404830V",
					"type": "DwellingPolicy",
					"data": {
						"occupancy": "Primary",
						"windHailExclusion": "No",
						"yearBuilt": 2013,
						"distanceToCoast": 3000
					}
				}
			]
		},
		{
			"locator": "01J5E7AV7P2CEWGEX4K034V1XE",
			"type": "coverage",
			"startTime": "2024-06-01T00:00:00Z",
			"endTime": "2025-01-01T00:00:00Z",
			"duration": 6.998655913978495,
			"elements": [
				{
					"locator": "01J5E7AV7QBNBRHTTGQHPXHKDW",
					"staticLocator": "01J5E660YXV5ZQC2MM6CW5DW8Q",
					"type": "Coverage_aPolicy",
					"chargeSummaries": {
						"coverage_a_premium": 481.16
					}
				},
				{
					"locator": "01J5E7AV7RE6HPEDDFE2RSTR57",
					"staticLocator": "01J5E660YX6ZEJSYTVN9XAXF14",
					"type": "Coverage_bPolicy",
					"chargeSummaries": {
						"coverage_b_premium": 96.23
					}
				},
				{
					"locator": "01J5E7AV7P2CEWGEX4K034V1XE",
					"staticLocator": "01J5E660YXGBBNT26TQESCZHQF",
					"type": "Ho3Segment",
					"data": {
						"applicantInsuranceScore": "800",
						"applicantDob": "1980-01-01",
						"applicantFirstName": "Homer",
						"applicantLastName": "Sample",
						"noPriorInsurance": "No"
					}
				},
				{
					"locator": "01J5E7AV7PP2XY7593HGP537HY",
					"staticLocator": "01J5E660YX1PHQNZ1F0404830V",
					"type": "DwellingPolicy",
					"data": {
						"windHailExclusion": "No",
						"yearBuilt": 2013,
						"distanceToCoast": 3000,
						"occupancy": "Primary"
					}
				}
			]
		}
	]
}
```

Tutorial 2 - Renewing a policy [#tutorial-2---renewing-a-policy]

Now that we’ve practiced making and executing a change to a policy, let’s try renewing a policy. Homer Sample has decided that he want to renew his coverage:

* His original term was from January 2024 to January 2025.
* He wants to renew coverage through January 2026.
* He also wants to add a personal property coverage to his dwelling.

With the Socotra API, we can easily renew the policy while also adding a new coverage.

**Note**: For a refresher on how to locate a customer’s account number or policy number, refer back to sections 1.1 and 1.2.

To create a renewal transaction for a policy, follow these steps:

1. While viewing the Socotra Sample Collection, navigate to **Policy > Policies > Post-issuance Flows > Policy Renewal > Create Renewal Transaction**.
2. Click the **Body** tab. You should see something similar to the JSON in the code block below:

```json
[
	{
		"action": "params",
		"effectiveTime": "<insert_time_stamp_here>"
	},
	{
		"action": "add",
		"elements": [
			{
				"parentLocator": "<insert_dwelling_locator_here>",
				"type": "Personal_Property"
			}
		]
	}
]
```

The code block above contains the data required to add a coverage to a policy during the renewal process. There are two placeholders:

* “effectiveTime”: “`<insert_time_stamp_here>`”
* “parentLocator”: “`<insert_dwelling_locator_here>`”

For the `<insert_time_stamp_here>` placeholder, you should provide a time stamp that’s on the same day as the end date of the previous segment.

The excerpt below shows you where to find the segment’s `startTime` and `endTime` (near the bottom).

```json
{
    "locator": "01J5E660YXGBBNT26TQESCZHQF",
    "accountLocator": "01J5E5RNSWR0QVPCFF2XT83CFK",
    "productName": "Ho3",
    "timezone": "America/New_York",
    "currency": "USD",
    "transaction": {
        "locator": "01J5E7848G8Y1Q9TAYMFFCMH0S",
        "transactionCategory": "change",
        "transactionType": "change",
        "effectiveTime": "2024-06-01T00:00:00Z",
        "issuedTime": "2024-08-16T18:31:25.332935Z",
        "preferences": {
            "installmentPreferences": {
                "installmentPlanName": "monthly10"
            }
        },
        "segment": {
            "locator": "01J5E7AV7P2CEWGEX4K034V1XE",
            "segmentType": "coverage",
            "startTime": "2024-06-01T00:00:00Z",
            "endTime": "2025-01-01T00:00:00Z",
            "element": {
        // ... <SHORTENED FOR BREVITY> ...
```

To find the effective time, look for the `endDate` of the previous term.

For example, if the `endDate` of the previous term is `2025-01-01T00:00:00Z`, the time stamp used for renewal should be the same value. This shows that the policy renews on the same day that the old policy ended so that coverage does not lapse.

To find the unique identifier of the dwelling, we can look at the response body of Describe Policy Snapshot. You can find the dwelling locator at `transaction.segment.element.elements.[0].locator` (under the `type` value `DwellingPolicy`).

```json
{
	"locator": "01J5E660YXGBBNT26TQESCZHQF",
	"accountLocator": "01J5E5RNSWR0QVPCFF2XT83CFK",
	"productName": "Ho3",
	"timezone": "America/New_York",
	"currency": "USD",
	"transaction": {
		"locator": "01J5E7848G8Y1Q9TAYMFFCMH0S",
		"transactionCategory": "change",
		"transactionType": "change",
		"effectiveTime": "2024-06-01T00:00:00Z",
		"issuedTime": "2024-08-16T18:31:25.332935Z",
		"preferences": {
			"installmentPreferences": {
				"installmentPlanName": "monthly10"
			}
		},
		"segment": {
			"locator": "01J5E7AV7P2CEWGEX4K034V1XE",
			"segmentType": "coverage",
			"startTime": "2024-06-01T00:00:00Z",
			"endTime": "2025-01-01T00:00:00Z",
			"element": {
				"type": "Ho3Segment",
				"locator": "01J5E7AV7P2CEWGEX4K034V1XE",
				"parentLocator": "01J5E7AV7P2CEWGEX4K034V1XE",
				"elements": [
					{
						"type": "DwellingPolicy",
						"locator": "01J5E7AV7PP2XY7593HGP537HY",
						"parentLocator": "01J5E7AV7P2CEWGEX4K034V1XE",
						"elements": [
							{
								"type": "Coverage_bPolicy",
								"locator": "01J5E7AV7RE6HPEDDFE2RSTR57",
								"parentLocator": "01J5E7AV7PP2XY7593HGP537HY",
								"coverageTerms": {
									"Coverage_b_limit": "CB20"
								},
								"staticLocator": "01J5E660YX6ZEJSYTVN9XAXF14",
								"originalEffectiveTime": "2024-01-01T00:00:00Z"
							},
							{
								"type": "Coverage_aPolicy",
								"locator": "01J5E7AV7QBNBRHTTGQHPXHKDW",
								"parentLocator": "01J5E7AV7PP2XY7593HGP537HY",
								"coverageTerms": {
									"Coverage_a_limit": "CA600000"
								},
								"staticLocator": "01J5E660YXV5ZQC2MM6CW5DW8Q",
								"originalEffectiveTime": "2024-01-01T00:00:00Z"
							}
						],
						"data": {
							"windHailExclusion": "No",
							"yearBuilt": 2013,
							"distanceToCoast": 3000,
							"occupancy": "Primary"
						},
						"staticLocator": "01J5E660YX1PHQNZ1F0404830V",
						"originalEffectiveTime": "2024-01-01T00:00:00Z"
					}
				],
				"data": {
					"applicantInsuranceScore": "800",
					"applicantDob": "1980-01-01",
					"applicantFirstName": "Homer",
					"applicantLastName": "Sample",
					"noPriorInsurance": "No"
				},
				"staticLocator": "01J5E660YXGBBNT26TQESCZHQF",
				"originalEffectiveTime": "2024-01-01T00:00:00Z"
			},
			"duration": 6.998655913978495,
			"basedOn": "01J5E66VBHEQWA7Z8Y3XDVFAXV"
		}
	},
	"delinquencyPlanName": "defaultDelinquencyPlan"
}
```

The value we want to copy and paste into the renewal request body is the `staticLocator` of the dwelling.

So, for a policy that renews on January 1 2025, we’d use a request body something like the one below:

```json
[
	{
		"action": "params",
		"effectiveTime": "2025-01-01T00:00:00Z"
	},
	{
		"action": "add",
		"elements": [
			{
				"parentLocator": "01J5E7AV7PP2XY7593HGP537HY",
				"type": "Personal_Property"
			}
		]
	}
]
```

3. Click **Send** to execute the request.
4. You should see a response body like the one in the screenshot below.

<Image src="/images/execute-policy-transactions/image7.png" alt="image11" width={1999} height={1223} unoptimized />

5. Copy and paste the `locator` into the `renewalTrxLocator` environment variable in the Socotra Sample Environment.
6. Navigate to the Issue Renewal Transaction endpoint.
7. Click **Send** to execute it.

You should receive a response like the one below, indicating that the policy has been renewed.

<Image src="/images/execute-policy-transactions/image2.png" alt="image12" width={1999} height={1223} unoptimized />

Tutorial 3 - Canceling a policy [#tutorial-3---canceling-a-policy]

Now that we’ve renewed the policy, let’s learn how to cancel a policy. Homer Sample has decided that he want to cancel his coverage:

* His original term was from **January 2024** to **January 2025**
* He renewed for a new term from **January 2025** to **January 2026**
* In **March 2025**, he decided he wanted to cancel his policy.

With the Socotra API, we can easily cancel the policy. This is considerably more straightforward than changing or renewing a policy because there’s no request body to build. We simply need to create a cancellation transaction and then issue it.

1. While viewing the Socotra Sample Collection, navigate to **Policy > Policies > Post-issuance Flows > Policy Cancellation > Create Cancellation Transaction**.

2. Click the **Body** tab.
   1. Set the timestamp to the requested cancellation date.
   2. In this case, March 1 2025 is the requested end date

3. For a time stamp, this is: `2025-03-01T00:00:00Z`.

4. Click **Send**.

5. You should receive a response message similar to the one in the screenshot below:

6. Copy the `locator` field in the response body.
   1. This is the unique identifier for the transaction.
   2. We’ll use this value to issue the transaction.

7. While viewing the Socotra Sample Collection, navigate to **Policy > Policies > Post-issuance Flows > Policy Cancellation > Issue Cancellation Transaction**.

8. Paste the `locator` value you copied in step 6 into the `transactionLocator` field.

9. Click **Send**.

10. You should receive a response indicating success.

Tutorial 4 - Reinstating a policy [#tutorial-4---reinstating-a-policy]

Finally, let’s practice reinstating a policy. Homer Sample has changed his mind. After canceling his policy in March of 2025, he decided in July of 2025 to reinstate the policy.

Reinstating the policy is a virtually identical process to canceling it, except we’ll be using the Reinstatement endpoints instead of the cancellation endpoints.

1. While viewing the Socotra Sample Collection, navigate to **Policy > Policies > Post-issuance Flows > Policy Reinstatement > Create Reinstatement Transaction**.

2. Click the **Body** tab.

3. Set the timestamp to July 2025 (e.g. *2025-07-01T00:00:00Z*).

4. Click **Send**.

5. You should receive a response message similar to the one in the screenshot below:

6. Copy the `locator` field in the response body.
   1. This is the unique identifier for the transaction.
   2. We’ll use this value to issue the transaction.

7. While viewing the Socotra Sample Collection, navigate to **Policy > Policies > Post-issuance Flows > Policy Reinstatement > Issue Reinstatement Transaction**.

8. Paste the `locator` value you copied in step 6 into the `transactionLocator` field.

9. Click **Send**.

10. You should receive a response indicating success.

Ready for the next module? [#ready-for-the-next-module]

See [Trigger billing, pay, and invoices](/getting-started/trigger-billing-pay-and-invoices) to continue this learning path.