> For the complete documentation index, see [llms.txt](https://docs.digit.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digit.org/local-governance/access/local-governance-stack/property-tax/property-tax-service/property-mutation-and-mutation-calculator.md). # Property Mutation & Mutation Calculator Property ownership transfer configuration ## **Overview** The mutation service enables property ownership changes due to sale or inheritance. It uses a configurable workflow to manage approvals and helps municipalities collect payments smoothly. The mutation APIs and flows are part of the **property-services** codebase and rely on configured values and integrated external services to control the mutation process. ## **Pre-requisites** * Prior knowledge of Java/J2EE. * Prior knowledge of Spring Boot. * Prior knowledge of REST APIs and related concepts like path parameters, headers, JSON etc. * Prior knowledge of Git * Prior knowledge of the demand-based systems. * The following services should be up and running: * user * MDMS * Persister * Location * Localization * Id-Gen * Billing-service * URL-shortener ## **Key Functionality** Enables the user to create a mutation and transfer the ownership to the new owner. ## **Configuration Steps** {% stepper %} {% step %} ### Configure Mutation Workflow The mutation workflow controls how ownership transfers are managed. **➤ Key Mutation Config Values** | Config Key | Value Type | Purpose | | ------------------------------ | ------------- | -------------------------------------- | | `is.mutation.workflow.enabled` | `true/false` | Enable/disable the mutation workflow | | `mutation.workflow.name` | `PT.MUTATION` | Workflow identifier for mutation flows | **✔ What to Do** 1. In your PT service configuration (environment YAML/properties), add the mutation workflow keys. 2. Ensure `mutation.workflow.name` is set to **PT.MUTATION**. 3. The service will use this when a mutation request enters the system. 4. **Important:** In a mutation request payload, include `"creationReason": "MUTATION"` so the service treats it as a mutation request. Otherwise, it won’t trigger the mutation workflow. Sample config ``` "workflow": { "tenantId": "pb.amritsar", "businessService": "PT.MUTATION", "action": "OPEN", "moduleName": "PT" }, "additionalDetails": { "documentDate": 1580722677000, "marketValue" : 1000, "documentValue": "1897", "documentNumber": "Xar34", "reasonForTransfer": "Sale", "isPropertyUnderGovtPossession": true "govtAcquisitionDetails": "" "isMutationInCourt":true, "caseDetails": "", } ``` To add {% endstep %} {% step %} ### Provide Additional Details in Mutation Request ``` { "RequestInfo": { "apiId": "Rainmaker", "action": "", "did": 1, "key": "", "msgId": "20170310130900|en_IN", "requesterId": "", "ts": 1513579888683, "ver": ".01", "authToken": "{{Auth_Token}}" }, "BusinessServices": [ { "tenantId": "pb", "businessService": "PT.MUTATION", "business": "PT", "businessServiceSla": null, "states": [ { "tenantId": "pb", "sla": null, "state": null, "applicationStatus": "INWORKFLOW", "docUploadRequired": false, "isStartState": true, "isTerminateState": false, "actions": [ { "tenantId": "pb", "action": "OPEN", "nextState": "OPEN", "roles": [ "CITIZEN", "EMPLOYEE" ] } ] }, { "tenantId": "pb", "sla": null, "state": "OPEN", "applicationStatus": "INWORKFLOW", "docUploadRequired": false, "isStartState": true, "isTerminateState": false, "actions": [ { "tenantId": "pb", "action": "VERIFY", "nextState": "DOCVERIFIED", "roles": [ "PT_DOC_VERIFIER" ] }, { "tenantId": "pb", "action": "REJECT", "nextState": "REJECTED", "roles": [ "PT_DOC_VERIFIER" ] }, { "tenantId": "pb", "action": "SENDBACKTOCITIZEN", "nextState": "CORRECTIONPENDING", "roles": [ "PT_DOC_VERIFIER" ] } ] }, { "tenantId": "pb", "sla": null, "state": "DOCVERIFIED", "applicationStatus": "INWORKFLOW", "docUploadRequired": false, "isStartState": false, "isTerminateState": false, "actions": [ { "tenantId": "pb", "action": "FORWARD", "nextState": "FIELDVERIFIED", "roles": [ "PT_FIELD_INSPECTOR" ] } ] }, { "tenantId": "pb", "sla": null, "state": "FIELDVERIFIED", "applicationStatus": "INWORKFLOW", "docUploadRequired": false, "isStartState": false, "isTerminateState": false, "actions": [ { "tenantId": "pb", "action": "PAY", "nextState": "PAID", "roles": [ "CITIZEN", "PT_CEMP" ] } ] }, { "tenantId": "pb", "sla": null, "state": "REJECTED", "applicationStatus": "INACTIVE", "docUploadRequired": false, "isStartState": false, "isTerminateState": true, "actions": null }, { "tenantId": "pb", "sla": null, "state": "PAID", "applicationStatus": "INWORKFLOW", "docUploadRequired": false, "isStartState": false, "isTerminateState": false, "isStateUpdatable": false, "actions": [ { "tenantId": "pb", "action": "APPROVE", "nextState": "APPROVED", "roles": [ "PT_APPROVER" ] } ] }, { "tenantId": "pb", "sla": null, "state": "APPROVED", "applicationStatus": "ACTIVE", "docUploadRequired": false, "isStartState": false, "isTerminateState": true, "isStateUpdatable": false, "actions": null }, { "tenantId": "pb", "sla": null, "state": "CORRECTIONPENDING", "applicationStatus": "INWORKFLOW", "docUploadRequired": false, "isStartState": false, "isTerminateState": false, "isStateUpdatable": true, "actions": [ { "tenantId": "pb", "action": "REJECT", "nextState": "REJECTED", "roles": [ "CITIZEN", "PT_CEMP" ] }, { "tenantId": "pb", "action": "REOPEN", "nextState": "OPEN", "roles": [ "CITIZEN", "PT_CEMP" ] } ] } ] } ] } ``` {% endstep %} {% step %} ### Integrate with Mutation Calculator Mutation fees aren’t hard-coded — they’re calculated dynamically via a **mutation calculator** that the property service calls during the workflow. **💡 How It Works** * The **mutation calculator** service evaluates a fee based on the **property’s usage type** and **its current market value**. * The workflow can invoke this service at the right point in the mutation flow to generate a fee demand. {% endstep %} {% step %} ### Mutation Fee Logic & Billing Slabs The mutation fee calculation considers multiple factors: **🔹 Criteria Used** * **Usage Type** (e.g., Residential / Non-Residential) * **Current Market Value (CMV)** * **Billing Slabs** (tiered ranges of values) * **Calculation Type**: * **FLAT** → a fixed fee * **RATE** → a percentage of CMV | Usage type | Minimum Market value | Maximum Market Value | Rate Percentage | Fixed amount | Calculation Type | | ---------------- | -------------------- | -------------------- | --------------- | ------------ | ---------------- | | Residential | 0 | X lacs | A% of CMV | INR G | FLAT | | Non -Residential | 0 | X lacs | E% of CMV | INR Q | RATE | | Residential | X+1 Lacs | Y Lacs | B% of CMV | INR H | FLAT | | Non -Residential | X+1 Lacs | Y Lacs | B% of CMV | INR H | RATE | | Residential | Y+1 Lacs | >Y+1Lacs | D% of CMV | INR L | FLAT | | Non -Residential | Y+1 Lacs | >Y+1Lacs | C% of CMV | INR I | RATE | **🧮 Fee Determination** 1. Find the slab where the property’s CMV falls. 2. Match the usage type. 3. Apply the slab’s calculation type: * *If FLAT* → use the slab’s fixed amount. * *If RATE* → calculate fee as `X% of CMV` (where X is the slab’s configured rate). {% endstep %} {% step %} ### Rebate & Penalty Rules To make mutation work in your system, follow these integration steps: 1. Use an existing **active propertyId** from the system. 2. Call the **property/update** API (`/property/_update`) including updated owner info and workflow details. 3. Ensure mutation workflow fields are part of the request so the system knows this is a mutation request. {% endstep %} {% step %} ### Configure Integrations To make mutation work in your system, follow these integration steps: 1. Use an existing **active propertyId** from the system. 2. Call the **property/update** API (`/property/_update`) including updated owner info and workflow details. 3. Ensure mutation workflow fields are part of the request so the system knows this is a mutation request. {% endstep %} {% endstepper %} ## **Reference Docs** Refer to the parent for external services:[ Property Services | Doc-Links](/local-governance/access/local-governance-stack/property-tax/property-tax-service.md) | Title | Link | | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | API contract for MT calculator | [mutation-calculator.yml](https://raw.githubusercontent.com/egovernments/municipal-services/master/docs/property-services/property-mutation-fees-calculator_API_Contract.yml) | | API list to create Mutation Slabs mutation/\_create, \_search, \_update | [API COLLECTION MT\_SLABS](https://www.getpostman.com/collections/02965abc6345b5e1a633) | | API list for MT-Calculator mutation/\_calculate | [POSTMAN API COLLECTION - MT-CALCULATE](https://www.getpostman.com/collections/e044d1f64feeafe82f70) | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.digit.org/local-governance/access/local-governance-stack/property-tax/property-tax-service/property-mutation-and-mutation-calculator.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.