Cancelling an engagement

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.

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.

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"
}

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:

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

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

Getting Started

Core Concepts

Guides

API Reference

Queries

Mutations

Members

Webhooks

Cancelling an engagement

Which engagements can be cancelled?