Skip to main content
POST
/
subscriptions
/
{subscription_id}
/
cancel
Subscription - Cancel Subscription
curl --request POST \
  --url https://sandbox.hyperswitch.io/subscriptions/{subscription_id}/cancel \
  --header 'Content-Type: application/json' \
  --header 'X-Profile-Id: <x-profile-id>' \
  --header 'api-key: <api-key>' \
  --data '{
  "cancel_option": "immediately",
  "credit_option_for_current_term_charges": "prorate",
  "refundable_credits_handling": "schedule_refund",
  "unbilled_charges_option": "invoice"
}'
{
  "id": "<string>",
  "status": "active",
  "merchant_reference_id": "<string>",
  "profile_id": "<string>",
  "merchant_id": "<string>",
  "customer_id": "<string>",
  "cancelled_at": "<string>"
}

Authorizations

​
api-key
string
header
required

Use the API key created under your merchant account from the HyperSwitch dashboard. API key is used to authenticate API requests from your merchant server only. Don't expose this key on a website or embed it in a mobile application.

Headers

​
X-Profile-Id
string
required

Profile ID for authentication

Path Parameters

​
subscription_id
string
required

The unique identifier for the subscription

Body

application/json

Request payload for cancelling a subscription.

​
cancel_option
enum<string>
Available options:
immediately,
end_of_term,
specific_date
​
cancel_at
string | null

Optional date when the subscription should be cancelled (if not provided, cancels immediately)

​
unbilled_charges_option
enum<string>
Available options:
invoice,
delete
​
credit_option_for_current_term_charges
enum<string>
Available options:
none,
prorate,
full
​
account_receivables_handling
enum<string>
Available options:
no_action,
schedule_payment_collection,
write_off
​
refundable_credits_handling
enum<string>
Available options:
no_action,
schedule_refund
​
cancel_reason_code
string | null

Reason code for canceling the subscription

Response

Subscription cancelled successfully

Response payload returned after successfully cancelling a subscription.

​
id
string
required

A type for subscription_id that can be used for subscription ids

​
status
enum<string>
required

Possible states of a subscription lifecycle.

  • Created: Subscription was created but not yet activated.
  • Active: Subscription is currently active.
  • InActive: Subscription is inactive.
  • Pending: Subscription is pending activation.
  • Trial: Subscription is in a trial period.
  • Paused: Subscription is paused.
  • Unpaid: Subscription is unpaid.
  • Onetime: Subscription is a one-time payment.
  • Cancelled: Subscription has been cancelled.
  • Failed: Subscription has failed.
Available options:
active,
created,
in_active,
pending,
trial,
paused,
unpaid,
onetime,
cancelled,
failed
​
profile_id
string
required

A type for profile_id that can be used for business profile ids

​
merchant_id
string
required

A type for merchant_id that can be used for merchant ids

​
customer_id
string
required

A type for customer_id that can be used for customer ids

​
merchant_reference_id
string | null

Merchant specific Unique identifier.

​
cancelled_at
string | null

Date when the subscription was cancelled