> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/onboarding/cancel-application.md).

# Cancel Application

Use this endpoint to cancel the signing process for an existing onboarding application by revoking the signer's active token.

This endpoint applies to both:

* Full applications created with `POST /merchant-onboarding/applications`
* Short applications created with `POST /merchant-onboarding/applications-short`

Cancel revokes the signing token so the signer can no longer complete the current session. It does not delete the application record.

#### Cancel vs. Resend

These two commands are related but serve different purposes.

| Action                     | Endpoint                                                | Use when                                                                                                |
| -------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Cancel the signing process | `POST /merchant-onboarding/{applicationId}/cancel`      | You need to stop the active signing session and prevent the current signer from completing the package. |
| Resend to the same signer  | `PUT /merchant-onboarding/applications/{applicationId}` | The application should continue and the same signer needs another opportunity to complete the package.  |

If you want to send the application back to the same signer without stopping the process, use [Resend Application](/onboarding/resend-application.md) instead.

#### When to use Cancel Application

Use Cancel Application when you need to:

* stop the current signer from completing the package
* prevent a signing session that was sent to the wrong recipient from being completed
* halt onboarding for a merchant that has withdrawn from the process
* stop the signing flow before creating a corrected application
* revoke access for a signer whose details were entered incorrectly

Typical examples include:

* the application was sent to the wrong email address
* the signer is no longer the correct point of contact
* the merchant has asked to stop onboarding
* your operations team needs to halt the process before it progresses further

#### When not to use Cancel Application

Do not use this endpoint when:

* the application is in Draft status and has not yet been sent to a signer — there is no signing token to revoke
* the application has already been signed and is in review or boarding
* you want to send the package back to the same signer — use Resend Application instead
* the application is already in a terminal state such as `boarded`, `rejected`, or `withdrawn`

For Draft applications that need to be discarded, coordinate with your Bead team.

#### Endpoint

```http
POST /merchant-onboarding/{applicationId}/cancel
```

#### Path parameter

| Parameter       | Description                                                                      |
| --------------- | -------------------------------------------------------------------------------- |
| `applicationId` | The onboarding application identifier returned when the application was created. |

#### Authentication and headers

Onboarding requests use API key authentication.

```http
X-Api-Key: {apiKey}
Accept: application/json
```

No request body is required.

#### What this endpoint does

Cancel Application revokes the active signing token for the specified application. After the token is revoked, the current signer can no longer access or complete the hosted onboarding and signing experience.

The application record is preserved. Retrieve the application status after cancelling to confirm the resulting state before deciding on next steps.

#### Typical request pattern

A common cancel pattern is:

1. Retrieve the current application status with `GET /merchant-onboarding/applications/{applicationId}`.
2. Confirm that the signing process should be stopped.
3. Call `POST /merchant-onboarding/{applicationId}/cancel`.
4. Retrieve the updated status to confirm the application state.
5. Decide on next steps — whether to create a new application, coordinate with your Bead team, or take no further action.

#### Example request

```http
POST /merchant-onboarding/{applicationId}/cancel
X-Api-Key: {apiKey}
Accept: application/json
```

No request body is required.

#### Example response

A successful cancel returns HTTP `200` with no response body.

#### Status handling

Before cancelling, retrieve the current application status.

```http
GET /merchant-onboarding/applications/{applicationId}
```

Cancel is applicable to applications that have an active signing session. The following statuses are relevant to cancel decisions:

| Status             | Cancel guidance                                                                                                                    |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `draft`            | Do not cancel — the application has not been sent to a signer yet. No signing token exists to revoke.                              |
| `submitted`        | Cancel may be appropriate if the application was sent to the wrong signer or the process should be stopped before the signer acts. |
| `signing`          | Cancel is appropriate if the signer should not complete the package.                                                               |
| `viewed`           | Cancel is appropriate if the signer has opened but not completed the package and should no longer proceed.                         |
| `changesRequested` | Cancel may be appropriate depending on the operational context. Coordinate with your Bead team if unsure.                          |
| `signed`           | Do not cancel — the application has already been signed. Cancelling is not applicable.                                             |
| `reviewing`        | Do not cancel — the application is under review. Coordinate with your Bead team.                                                   |
| `boarding`         | Do not cancel — the application is in downstream boarding. Coordinate with your Bead team.                                         |
| `boarded`          | Do not cancel — onboarding is complete.                                                                                            |
| `withdrawn`        | Do not cancel — the application is already in a terminal state.                                                                    |
| `rejected`         | Do not cancel — the application is already in a terminal state.                                                                    |

After calling cancel, retrieve the application again to confirm the status before taking further action.

#### Cancel and creating a new application

Cancelling an application stops the current signing process but does not automatically create a replacement application.

If you need to restart onboarding with a different signer or corrected merchant data, create a new application after confirming the cancel succeeded.

Reuse the same `partnerId` and merchant reference when the underlying merchant relationship continues.

#### Error handling

| Scenario                                             | Expected result                                           |
| ---------------------------------------------------- | --------------------------------------------------------- |
| Unknown `applicationId`                              | The request returns not found.                            |
| Application is in Draft status with no signing token | The request may return a validation or conflict response. |
| Application is already signed, boarding, or boarded  | Cancel is not applicable; do not call this endpoint.      |
| API key is missing or invalid                        | The request returns unauthorized or forbidden.            |
| API key does not have access to the application      | The request returns forbidden.                            |

#### Best practices

* Retrieve the current application status before cancelling to confirm a signing session is active.
* Do not call cancel on Draft applications — there is no signing token to revoke.
* After cancelling, retrieve the application status to confirm the resulting state before deciding on next steps.
* If the intent is to restart onboarding with the same signer, use Resend Application instead of cancel.
* If the intent is to restart onboarding with a different signer or corrected data, create a new application after confirming the cancel succeeded.
* Do not attempt to cancel an application that is already in a terminal state.
* Coordinate with your Bead team if you are unsure whether a cancellation is appropriate for a given status.

#### Related pages

* [Submit Application](/onboarding/submit-application.md)
* [Get Status](/onboarding/get-status.md)
* [Resend Application](/onboarding/resend-application.md)
* [Webhooks for Application Events](/onboarding/webhooks-for-application-events.md)
* [Sample Payload](/onboarding/sample-payload.md)
* [Reference Guide](/reference-guide.md)


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.bead.xyz/onboarding/cancel-application.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.