Cancel a subscription
POST/subscriptions/{subscriptionId}/cancelCancel an active subscription as the merchant via a signed request. Exodus submits the on-chain cancelWithSig transaction and pays the gas. The subscription transitions to cancelling once the cancel is sent, then to cancelled once the on-chain event is indexed. If the cancel does not take effect on-chain, the subscription returns to active and the subscription.cancel_failed webhook fires.
Headers
| Header | Description | Required |
|---|---|---|
| Authorization | Bearer token with your secret API key | yes |
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| subscriptionId | string | yes |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| deadline | integer | yes | The Unix time in seconds after which the signed cancel can no longer take effect, identical to the deadline signed. It must be at most 7 days after the request, or the cancel is rejected with 400 validation_error and param: deadline. |
Example Request
Request
const response = await fetch('https://checkout-api.exodus.com/subscriptions/<subscriptionId>/cancel', {
method: 'POST',
headers: {
Authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"deadline": 1798761600
}),
});Responses
| Status | Description |
|---|---|
| 200 | The cancel result. status is cancelling until the on-chain event is indexed, including while the cancel is sent and not yet seen on-chain; tx_hash is the hash of the cancel transaction, which may not be confirmed yet. A retry while the subscription is cancelling sends nothing new and returns the held tx_hash (null when none is held). A retry signed with a later deadline replaces the held signature, and Exodus uses the newer signature if it has to send the cancel again. A pending cancel can still fail: the subscription then returns to active and subscription.cancel_failed fires, so sign a new cancel to try again. A first cancel can also answer status: cancelled with its tx_hash when Exodus recorded the cancel as final before it answered. Cancelling a subscription that is already cancelled is a no-op 200 with tx_hash: null. |
| 400 | Validation error |
| 401 | Missing or invalid API key, missing X-Signature header, or the X-Signature was not produced by the merchant signer registered for the subscription's chain ("Invalid merchant signature"). A present but wrong-size X-Signature is rejected as a 400 with param: X-Signature; it must be a 64-byte (Solana) or 65-byte (EVM) hex string. |
| 403 | API key lacks the required scope |
| 404 | Resource not found |
| 422 | The cancel cannot be processed as sent. Merchant signer not configured carries no code (type: invalid_request). Revert decoded before submission: code is the contract error name (SignatureExpired, SubscriptionNotFound, SubscriptionNotActive, InvalidSignature), or UnknownRevert when it cannot decode the error. Post-submission revert: OnChainRevert. SubscriptionNotActive or OnChainRevert because an earlier cancel already took effect is not an error: it returns 200 with status: cancelling. A cancel that was sent but whose confirmation could not be read yet is not an error: it returns 200 with status: cancelling and the tx_hash. |
| 500 | Relayer wallet not configured on this environment (no code). A relay failure the API cannot decode is not a 500 on this route: it returns the 422 UnknownRevert described above. Any other unexpected failure inside the cancel relay returns "Internal server error" with no code. |
| 503 | type: service_unavailable. No code: the relayer is paused by operators or, on EVM, cannot pay gas right now, or, on EVM, a temporary network read failed before the cancel was sent (nothing is sent in that case). Retry later with the same deadline and signature until that deadline passes. code: subscription_manager_paused: the merchant's subscription manager is paused on-chain; retrying will not succeed until the manager's pauser unpauses it. The pause may be Exodus-initiated as an incident response, so confirm the cause with support before unpausing. |
| 504 | code: tx_pending: rare. The cancel was sent, but Exodus could not record it, so the subscription can stay active and charges can go on. data carries subscription_id and tx_hash (null when the request sent nothing new). Retry the same request with the same signature. The retry returns the subscription's current state: 200 cancelling or cancelled once Exodus records the cancel, or the error a first cancel gets when the cancel did not take effect. |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
| subscription_id | string | yes | |
| status | enum: cancelling | cancelled | yes | |
| tx_hash | string | null | yes |
Example Response
{
"subscription_id": "0x9f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a",
"status": "cancelling",
"tx_hash": "0x7e81c228fc4fcf0372a86ce6f8bbc457210a8b51fc30dee5557280e5153c9f06"
}Error Response
Error (e.g. 400)
{
"error": {
"type": "validation_error",
"message": "amount must be a positive number",
"param": "amount"
}
}Last updated on
