Skip to Content

Cancel a subscription

POST/subscriptions/{subscriptionId}/cancel

Cancel 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

HeaderDescriptionRequired
AuthorizationBearer token with your secret API keyyes

Path Parameters

NameTypeRequiredDescription
subscriptionIdstringyes

Request Body

FieldTypeRequiredDescription
deadlineintegeryesThe 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

StatusDescription
200The 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.
400Validation error
401Missing 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.
403API key lacks the required scope
404Resource not found
422The 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.
500Relayer 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.
503type: 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.
504code: 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

FieldTypeRequiredDescription
subscription_idstringyes
statusenum: cancelling | cancelledyes
tx_hashstring | nullyes

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

Start building

XO

Request Demo

Schedule a call with our team

Select a productArrow right

Start building
Grateful

Contact Us

We're here to help