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.onekeypayments.com/v3/subscriptions/{subscription_id}

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

Cancel a subscription

delete

This endpoint allows cancellation of an existing subscription by 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-TypestringRequired

Media type of the body sent to the API.

Default: application/json

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-KeystringOptional

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

Body

objectOptional

Responses

200

Subscription successfully cancelled

application/json

Responseobject

420

Subscription does not exist

application/json

421

Subscription was already cancelled

application/json

426

Subscription is terminated and cannot be cancelled

application/json

501

Generic Error

application/json

delete

HTTPcURLJavaScriptPython

DELETE /v3/subscriptions/{subscription_id} HTTP/1.1
Host: api-stg.onekeypayments.com
Content-Type: application/json
X-Date: 2025-05-15T12:59:01.054Z
X-Login: text
Authorization: text
Accept: */*
Content-Length: 2

{}

{}

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 ✅.

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.