> ## Documentation Index
> Fetch the complete documentation index at: https://dev.ownright.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancelling an engagement

> How to cancel an engagement that is no longer needed

If an engagement is no longer needed — for example, the deal fell through or was submitted
in error — you can cancel it using the `engagementCancel` mutation.

## Which engagements can be cancelled?

Currently, an engagement can only be cancelled when it is in the **Received** or
**Setting up** state.

<Info>
  Support for cancelling engagements in additional states is planned for a
  future release. Check back for updates.
</Info>

You can check whether a specific engagement is cancellable by querying the `cancellable`
field:

```graphql theme={null}
query CheckCancellable($id: EngagementGID!) {
  engagement(id: $id) {
    ... on PurchaseEngagement {
      id
      cancellable
      status {
        state
      }
    }
    ... on RefinanceEngagement {
      id
      cancellable
      status {
        state
      }
    }
  }
}
```

If `cancellable` is `true`, you can proceed with the cancellation.

## Cancelling an engagement

<Steps>
  <Step title="Verify the engagement is cancellable">
    Query the engagement and check that `cancellable` returns `true`. If the engagement
    has already progressed past the Setting up state, the cancellation will be rejected.
  </Step>

  <Step title="Send the cancel mutation">
    Call `engagementCancel` with the engagement's GID:

    ```graphql Request theme={null}
    mutation CancelEngagement($id: EngagementGID!) {
      engagementCancel(id: $id) {
        engagement {
          ... on PurchaseEngagement {
            id
            shortId
            cancellable
            status {
              state
            }
          }
          ... on RefinanceEngagement {
            id
            shortId
            cancellable
            status {
              state
            }
          }
        }
        userErrors {
          code
          field
          message
        }
      }
    }
    ```

    **Variables:**

    ```json Variables theme={null}
    {
      "id": "gid://ownright/Engagement/42"
    }
    ```
  </Step>

  <Step title="Handle the response">
    On success, the engagement is returned with its status set to **Cancelled**:

    ```json Successful response [expandable] theme={null}
    {
      "data": {
        "engagementCancel": {
          "engagement": {
            "id": "gid://ownright/Engagement/42",
            "shortId": "ENG-42",
            "cancellable": false,
            "status": {
              "state": "CANCELLED"
            }
          },
          "userErrors": []
        }
      }
    }
    ```

    If the engagement cannot be cancelled, the `userErrors` array will contain the
    reason:

    ```json Error response [expandable] theme={null}
    {
      "data": {
        "engagementCancel": {
          "engagement": null,
          "userErrors": [
            {
              "code": "ENGAGEMENT_NOT_CANCELLABLE",
              "field": ["id"],
              "message": "The specified engagement cannot be cancelled."
            }
          ]
        }
      }
    }
    ```
  </Step>
</Steps>

## Error codes

The `engagementCancel` mutation can return the following error codes:

| Code                         | Description                                                           |
| ---------------------------- | --------------------------------------------------------------------- |
| `ENGAGEMENT_NOT_CANCELLABLE` | The engagement is not in a state that allows cancellation             |
| `ENGAGEMENT_NOT_FOUND`       | The specified `EngagementGID` does not exist or you don't have access |

<Warning>
  Cancellation is irreversible. Once an engagement is cancelled, it cannot be
  reopened. Make sure you confirm the cancellation with the appropriate
  stakeholders before proceeding.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="File uploads" icon="upload" href="/lender-api/guides/file-uploads">
    Learn the staged upload flow for attaching mortgage documents.
  </Card>

  <Card title="API Reference" icon="code" href="/lender-api/reference/connecting">
    Explore all queries, mutations, and types available in the Lender API.
  </Card>
</CardGroup>