Subscription - Cancel Subscription

POST /subscriptions/{subscription_id}/cancel

Cancels a subscription.

Try it: https://sandbox.hyperswitch.io/subscriptions/{subscription_id}/cancel

Example — cURL

Cancel subscription (cURL)
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"
}
'

Example response (200)

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.

Do not expose the api-key in client-side code or mobile apps.

Headers

  • X-Profile-Id (string, required) — Profile ID for authentication

  • Content-Type: application/json

Path Parameters

  • subscription_id (string, required) — The unique identifier for the subscription

Request body

Content-Type: application/json

Request payload for cancelling a subscription.

  • cancel_option (enum) 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) Available options: invoice, delete

  • credit_option_for_current_term_charges (enum) Available options: none, prorate, full

  • account_receivables_handling (enum) Available options: no_action, schedule_payment_collection, write_off

  • refundable_credits_handling (enum) Available options: no_action, schedule_refund

  • cancel_reason_code (string | null) Reason code for canceling the subscription

Response

Status: 200 Content-Type: application/json

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

Suggest edits: https://github.com/juspay/hyperswitch/edit/main/api-reference/v1/subscriptions/cancel.mdx Raise issue: https://github.com/juspay/hyperswitch/issues/new?title=Issue%20on%20docs&body=Path:%20/v1/subscriptions/cancel

Related: Subscription — Resume Subscription — https://api-reference.hyperswitch.io/v1/subscriptions/resume

PreviousPayment Method - List Customer Saved Payment MethodsNextConnector Account - Create