> 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. {% hint style="warning" %} **Cancel is only available while an application is in `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 `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: * 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 All of the above only apply **before submission** — while the application is still in `viewed` or `signing` status. 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 is in `draft` status and has not yet been sent to a signer — there is no signing token to revoke * 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 For Draft applications that need to be discarded, coordinate with your Bead team. **Endpoint** ```http POST /merchant-onboarding/{applicationId}/cancel ``` **Path parameter**
ParameterDescription
applicationIdThe 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 the application is in `viewed` or `signing` status. 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** **Cancel is only valid while the application is in `viewed` or `signing` status.** Retrieve the current application status before cancelling — do not attempt this call against any other status. ```http GET /merchant-onboarding/applications/{applicationId} ```
StatusCancellable?Cancel guidance
draftNoThe application has not been sent to a signer yet. No signing token exists to revoke.
submittedNoThe application has been submitted. The cancel window has closed — this is a submission-stage status, not a pre-submission one.
signingYesThe signer has not yet completed the package. Cancel is appropriate to stop the signing session.
viewedYesThe signer has opened but not completed the package. Cancel is appropriate to stop the signer from proceeding.
changesRequestedNoThe application has been submitted and returned for changes. This is a post-submission status — cancel is not applicable.
resubmittedNoThe application has been resubmitted after changes. This is a post-submission status — cancel is not applicable.
signedNoThe application has already been signed. Cancelling is not applicable.
reviewingNoThe application is under review. Coordinate with your Bead team if the process needs to stop.
boardingNoThe application is in downstream boarding. Coordinate with your Bead team if the process needs to stop.
boardedNoOnboarding is complete — a terminal state.
withdrawnNoAlready in a terminal state.
rejectedNoAlready 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` | `404 Not Found`. | | Application is not in `viewed` or `signing` status (already submitted, already terminal, or still Draft) | `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 only valid for `viewed` or `signing` status. * Do not call cancel on Draft applications — there is no signing token to revoke. * 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. * 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. * 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.