> 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, or to withdraw a Draft application before it's ever sent to a signer.
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, when one exists, so the signer can no longer complete the current session. It does not delete the application record — the application moves to `withdrawn`.
{% hint style="warning" %} **Cancel is available while an application is in `draft`, `viewed`, or `signing` status.** Once an application has been submitted — including `submitted`, `changesRequested`, `resubmitted`, and every status beyond — the cancel window is closed. Calling this endpoint on an application outside `draft`/`viewed`/`signing` returns an error; it is not a judgment call to make case by case. {% endhint %}
**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:
* discard a Draft application that was created in error, before any signer has been involved
* 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 created in Draft status and is no longer needed
* 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
All of the above only apply **before submission** — while the application is still in `draft`, `viewed`, or `signing` status. For Draft applications there is no signer or signing token yet — cancel simply marks the application `withdrawn` before it ever reaches a signer. If the application has already been submitted, Cancel Application is no longer the right tool; see [When not to use Cancel Application](#when-not-to-use-cancel-application) below.
**When not to use Cancel Application**
Do not use this endpoint once an application has been submitted. This includes:
* the application has been submitted and is in `submitted`, `changesRequested`, or `resubmitted` status — the submission window has closed
* the application has already been signed and is in review or boarding (`signed`, `reviewing`, `reviewed`, `boarding`)
* the application is already in a terminal state (`boarded`, `withdrawn`, `rejected`)
* you want to send the package back to the same signer — use Resend Application instead
**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, when one exists, so the current signer can no longer access or complete the hosted onboarding and signing experience. For a Draft application, there is no signing token to revoke — cancel simply moves the application to `withdrawn` before it reaches a signer.
The application record is preserved; it is never deleted. A successful cancel — from `draft`, `viewed`, or `signing` — always results in the application moving to `withdrawn`. You can retrieve the application afterward to confirm, but the outcome is deterministic, not something you need to check for.
**Typical request pattern**
A common cancel pattern is:
1. Retrieve the current application status with `GET /merchant-onboarding/applications/{applicationId}`.
2. Confirm the application is in `draft`, `viewed`, or `signing` status.
3. Call `POST /merchant-onboarding/{applicationId}/cancel`.
4. Optionally retrieve the updated status — it will be `withdrawn`.
5. Decide on next steps — whether to create a new application 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. The application's status becomes `withdrawn`.
**Status handling**
**Cancel is valid while the application is in `draft`, `viewed`, or `signing` status.** A successful cancel always results in `withdrawn`. Retrieve the current application status before cancelling — do not attempt this call against any other status.
```http
GET /merchant-onboarding/applications/{applicationId}
```
| Status | Cancellable? | Resulting status | Cancel guidance |
| ------------------ | ------------ | ---------------- | ------------------------------------------------------------------------------------------------- |
| `draft` | **Yes** | `withdrawn` | No signing token exists yet. Cancel marks the application `withdrawn` before it reaches a signer. |
| `submitted` | No | — | The application has been submitted. The cancel window has closed. |
| `signing` | **Yes** | `withdrawn` | The signer has not completed the package. Cancel stops the signing session. |
| `viewed` | **Yes** | `withdrawn` | The signer opened, but did not complete, the package. Cancel stops the signer proceeding. |
| `changesRequested` | No | — | The application was submitted and returned for changes. Cancel is not applicable. |
| `resubmitted` | No | — | The application was resubmitted after changes. Cancel is not applicable. |
| `signed` | No | — | The application has already been signed. Cancelling is not applicable. |
| `reviewing` | No | — | The application is under review. Coordinate with your Bead team if needed. |
| `boarding` | No | — | The application is in downstream boarding. Coordinate with your Bead team if needed. |
| `boarded` | No | — | Onboarding is complete. |
| `withdrawn` | No | — | The application is already in a terminal state. |
| `rejected` | No | — | The application is already in a terminal state. |
**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` | `404 Not Found`. |
| Application is not in `draft`, `viewed`, or `signing` status (already submitted or already terminal) | `409 Conflict` — cancel is not valid for the application's current status. |
| Malformed request | `400 Bad Request`. |
| API key is missing or invalid | `401 Unauthorized`. |
| API key does not have access to the application | `403 Forbidden`. |
If you need to stop an application that has already returned `409 Conflict` on cancel, do not retry the call — the status has moved past the point where cancel applies. Coordinate with your Bead team on next steps instead.
**Best practices**
* Retrieve the current application status before cancelling — cancel is valid for `draft`, `viewed`, or `signing` status.
* Cancel works on Draft applications too — there is no signing token to revoke, but the application still moves to `withdrawn`.
* Do not call cancel on an application that has already been submitted (`submitted`, `changesRequested`, `resubmitted`, or beyond) — it will return `409 Conflict`.
* If you want an application to remain cancellable, request cancellation before the signer submits it. Once submitted, that window is closed and cannot be reopened from the API.
* A successful cancel always results in `withdrawn` — you don't need to poll to find out what happened, though you can retrieve the application afterward to confirm.
* 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.
* 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=&goal=
```
`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.