Subscription Cancellation Endpoint

Overview

The Subscription Cancellation API allows merchants to terminate an active subscription before its scheduled end date. Once cancelled, no further charges will be processed for that subscription.

Endpoint

DELETE https://api-stg.directa24.com/v3/subscriptions/{subscription_id}

Where {subscription_id} is the unique numeric identifier of the subscription you wish to cancel.

Cancel a subscription

This endpoint allows cancellation of an existing subscription by ID.

delete

/v3/subscriptions/{subscription_id}

Path parameters

subscription_idinteger · int64required

Unique numeric identifier of the subscription to be cancelled. This is the subscription ID provided when the subscription was created.

Example: 123456789

Header parameters

Content-Typestring · default: application/jsonrequired

Media type of the body sent to the API.

X-Datestring · date-timerequired

ISO8601 Datetime with Timezone (yyyy-MM-dd'T'HH:mm:ssZ)

X-Loginstringrequired

Merchant X-Login API Key.

Authorizationstringrequired

Authorization control hash.

X-Idempotency-Keystring

Unique idempotency key for ensuring that the same request is not processed more than once.

Body

object

Responses

application/json

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url 'https://api-stg.directa24.com/v3/subscriptions/{subscription_id}' \
  --header 'Content-Type: application/json' \
  --header 'X-Date: 2025-03-16T18:37:05.289Z' \
  --header 'X-Login: text' \
  --header 'Authorization: text' \
  --data '{}'

200

420

421

426

501

200

{
  "message": "Subscription successfully cancelled"
}

Subscription successfully cancelled

Request Parameters

This endpoint uses only a path parameter to identify the subscription:

Parameter	Type	Required	Description
id	integer	Yes	Unique numeric identifier of the subscription to cancel.

Request Body

The request body should be empty for this endpoint.

{}

Response

Success Response

A successful cancellation returns an HTTP 200 status code with a confirmation message:

{
  "message": "Subscription successfully cancelled"
}

Error Responses

The API may return the following errors:

Subscription Already Cancelled (421)

Returned when attempting to cancel a subscription that has already been cancelled:

{
  "code": 421,
  "description": "Subscription was already cancelled.",
  "type": "SUBSCRIPTION_ALREADY_CANCELLED"
}

Subscription Not Found (420)

Returned when the specified subscription ID does not exist:

{
  "code": 420,
  "description": "Subscription does not exist.",
  "type": "SUBSCRIPTION_NOT_FOUND"
}

Subscription Terminated (426)

Returned when attempting to cancel a subscription that has already been terminated (completed its lifecycle):

{
  "code": 426,
  "description": "Subscription is terminated and cannot be cancelled.",
  "type": "SUBSCRIPTION_IS_TERMINATED"
}

Generic Error (501)

Returned when an unexpected error occurs:

{
  "code": 501,
  "description": "Generic Error",
  "type": "GENERIC_ERROR"
}

Cancellation Effects

When a subscription is cancelled:

1. The subscription status is immediately changed to CANCELLED

2. All scheduled future charges are removed

3. The cancellation is recorded in the subscription history

Important Notes

1. Cancellation vs. Refund: Cancelling a subscription only prevents future charges. It does not refund any previous charges. To process refunds for previous transactions, use the separate Refund API.

2. Reactivation: Once a subscription is cancelled, it cannot be reactivated. A new subscription must be created if the customer wishes to resume the service.

3. Timing: Cancellation takes effect immediately, regardless of the subscription's billing cycle.