Skip to main content
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.
Support for cancelling engagements in additional states is planned for a future release. Check back for updates.
You can check whether a specific engagement is cancellable by querying the cancellable field: 
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

1

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.
2

Send the cancel mutation

Call engagementCancel with the engagement’s GID:
Request
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:
Variables
{
  "id": "gid://ownright/Engagement/42"
}
3

Handle the response

On success, the engagement is returned with its status set to Cancelled:
Successful response
{
  "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:
Error response
{
  "data": {
    "engagementCancel": {
      "engagement": null,
      "userErrors": [
        {
          "code": "ENGAGEMENT_NOT_CANCELLABLE",
          "field": ["id"],
          "message": "The specified engagement cannot be cancelled."
        }
      ]
    }
  }
}

​
Error codes

The engagementCancel mutation can return the following error codes:
CodeDescription
ENGAGEMENT_NOT_CANCELLABLEThe engagement is not in a state that allows cancellation
ENGAGEMENT_NOT_FOUNDThe specified EngagementGID does not exist or you don’t have access
Cancellation is irreversible. Once an engagement is cancelled, it cannot be reopened. Make sure you confirm the cancellation with the appropriate stakeholders before proceeding.