{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Subscription Management","description":"Developer documentation for the WHMCS API — the","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"subscription-management","__idx":0},"children":["Subscription Management"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Subscription Management is an optional function that can be defined within a gateway module. Its purpose is to remotely cancel a recurring subscription agreement with a payment gateway, manually and automatically. The stored Subscription ID value in WHMCS is then removed."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a service is assigned to a payment gateway that implements this function (for example PayPal Subscriptions) and a Subscription ID is set, a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Cancel Subscription"]}," button is displayed under the Products/Services tab in the admin area. Clicking it will trigger the API call defined in the _cancelSubscription function."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"automatic-cancellation","__idx":1},"children":["Automatic Cancellation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Automatic Subscription Management"]}," feature is enabled under ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Setup > General Settings > Invoices tab"]},", a subscription will be cancelled automatically under the following circumstances:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A cancellation request is submitted"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The order is cancelled or set to fraud via the admin interface of WHMCS"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The API is used to cancel or fraud an order with “cancelsub=true” passed"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An upgrade order is placed for the product/service"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"implementing-in-payment-gateway-modules","__idx":2},"children":["Implementing in payment gateway modules"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This feature should only be defined for payment gateways which create automatic recurring subscriptions that are processed outside of WHMCS (for example PayPal Subscriptions)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Implementation is a two-step process:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A subscription ID must be stored in tblhosting.subscriptionid for the given service in order for the cancel subscription function to be invocable. Typically this value should be set as part of a payment gateway callback routine (see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developers.whmcs.com/payment-gateways/callbacks/"},"children":["callbacks"]},")"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Define the _cancelSubscription function in the gateway module file."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This function should contain the necessary API calls to cancel a recurring payment subscription at the payment gateway."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Return a \"success\" response to indicate successful subscription cancellation. The stored tblhosting.subscriptionid value is then removed."," ","Any other response is considered a failure, and the subscriptionid value will remain in place."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An example of this function is shown in the sample gateway module at ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/WHMCS/sample-gateway-module/blob/master/modules/gateways/gatewaymodule.php"},"children":["Sample Gateway Module"]}]}]},"headings":[{"value":"Subscription Management","id":"subscription-management","depth":1},{"value":"Automatic Cancellation","id":"automatic-cancellation","depth":2},{"value":"Implementing in payment gateway modules","id":"implementing-in-payment-gateway-modules","depth":2}],"frontmatter":{"title":"Subscription Management","seo":{"title":"Subscription Management"}},"lastModified":"2026-08-03T17:00:42.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/payment-gateways/subscription-management","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}