Knowledge Center

Knowledge Center > API > REST API > REST API Reference > Subscriptions > Cancel subscription

Cancel subscription

This REST API reference describes how to cancel an active subscription

Request

  • Production: PUT https://api.zuora.com/rest/v1/subscriptions/{subscription-key}/cancel
  • API Sandbox: PUT https://apisandbox-api.zuora.com/rest/v1/subscriptions/{subscription-key}/cancel

Request parameters

subscription-key

required

path

Subscription number or ID. Subscription status must be Active.

Request Header

zuora-version

optional

The minor version of the Zuora REST API. 

You only need to set this parameter if you use the collect or invoice field. See REST API Basics for more information.

Accept

optional

Optionally enter application/json. Only JSON is returned.

Request body

cancellationPolicy

required

Cancellation method. Possible values are: EndOfCurrentTerm, EndOfLastInvoicePeriod, SpecificDate. If using SpecificDate, the cancellationEffectiveDate field is required.

cancellationEffectiveDate

optional

Date the cancellation takes effect, in the format yyyy-mm-dd.  Use only if cancellationPolicy is SpecificDate. Should not be earlier than the subscription contract-effective date, later than the subscription term-end date, or within a period for which the customer has been invoiced.

invoiceCollect

required

This field has been replaced by the invoice field and the collect field. invoiceCollect is available only for backward compatibility.

If true, an invoice is generated and payment automatically collected. Default is false.

This field is in Zuora REST API version control. Supported minor versions are 186.0, 187.0, 188.0, and 189.0. See Zuora REST API Versions for more information.

invoiceTargetDate

optional

If an invoice is to be generated, the date through which to calculate the charges, as yyyy-mm-dd

invoice

optional

Creates an invoice for a subscription. The invoice generated in this operation is only for this subscription, not for the entire customer account.

If the value is true, an invoice is created. If the value is false, no action is taken.
The default value is false

This field is in Zuora REST API version control. Supported minor versions are 196.0 or later. To use this field in the method, you must set the zuora-version parameter to the minor version number in the request header. See Zuora REST API Versions for more information.

collect

optional

Collects an automatic payment for a subscription. The collection generated in this operation is only for this subscription, not for the entire customer account.
If the value is true, the automatic payment is collected. If the value is false, no action is taken.
The default value is false.
Prerequisite: invoice must be true

This field is in Zuora REST API version control. Supported minor versions are 196.0 or later. To use this field in the method, you must set the zuora-version parameter to the minor version number in the request header. See Zuora REST API Versions for more information.

applyCreditBalance

optional

Applies a credit balance to an invoice.
If the value is true, the credit balance is applied to the invoice. If the value is false, no action is taken.
Prerequisite: invoice must be true

Note: If you are using the field invoiceCollect rather than the field invoice, the invoiceCollect value must be true.

To view the credit balance adjustment, retrieve the details of the invoice using the Get Invoices method.

OpportunityCloseDate_QT

optional

The closing date of the Opportunity. This field is populated when the subscription originates from Zuora Quotes.

This field is used only for reporting subscription metrics. 

See Subscription Data Source for more information.

OpportunityName_QT

optional

The unique identifier of the Opportunity. This field is populated when the subscription originates from Zuora Quotes.

This field is used only for reporting subscription metrics. 

See Subscription Data Source for more information.

QuoteBusinessType_QT

optional

The specific identifier for the type of business transaction the Quote represents such as New, Upsell, Downsell, Renewal, or Churn. This field is populated when the subscription originates from Zuora Quotes.

This field is used only for reporting subscription metrics. 

See Subscription Data Source for more information.

QuoteNumber_QT

optional

The unique identifier of the Quote. This field is populated when the subscription originates from Zuora Quotes.

This field is used only for reporting subscription metrics. 

See Subscription Data Source for more information.

QuoteType_QT

optional

The Quote type that represents the subscription lifecycle stage such as New, Amendment, Renew or Cancel. This field is populated when the subscription originates from Zuora Quotes.

This field is used only for reporting subscription metrics. 

See Subscription Data Source for more information.

Response

success

Contains true if successful, otherwise false.

processId

Internal process ID to assist Zuora support. Only returned if success is false.

reasons

Information on one or more reasons for the result. Only returned if success is false.

code

Eight-digit numeric error code

message

Description of the error

cancelledDate The date that the subscription was canceled
subscriptionId The internal subscription ID

invoiceId

ID of the invoice, if one is generated

paymentId

ID of the payment, if a payment is collected

paidAmount

Amount paid

totalDeltaMrr

Change in the subscription monthly recurring revenue as a result of the update

totalDeltaTcv

Change in the total contracted value of the subscription as a result of the update

Examples

The following JSON and CURL examples show how to cancel a subscription. Some fields in the REST methods are supported as of Zuora REST API minor versions. The fields you can specify depends on the REST API minor version you use.

JSON Examples (REST API Minor Version 196.0 and later)

In API minor version 196.0 and later, the invoicecollect field is replaced by the invoice and collect fields. To use the collect and invoice fields,  you must set the zuora-version parameter to the minor version number in the request header. 

HTTP/JSON request:

PUT https://api.zuora.com/rest/v1/subscriptions/A-S00001084/cancel

JSON request:

{
  "cancellationPolicy": "SpecificDate",
  "cancellationEffectiveDate": "2019-05-31",
  "invoice": true,
  "collect": false
}

JSON response:

{
  "success": true,
  "subscriptionId": "8a8082c453cd2a620154efc7bba0350e",
  "cancelledDate": "2019-05-31",
  "totalDeltaMrr": 0,
  "totalDeltaTcv": -703.2258065,
  "invoiceId": "8a8082c453cd2a620153e426c7eb78b3"
}

JSON Examples (REST API Minor Version 189.0 and earlier)

HTTP/JSON request:

PUT https://api.zuora.com/rest/v1/subscriptions/A-S00001084/cancel

JSON request:

{
  "cancellationPolicy": "SpecificDate",
  "invoiceCollect": false,
  "cancellationEffectiveDate": "2019-05-31"
}

JSON response:

{
  "success": true,
  "subscriptionId": "8a8082c453cd2a620154efc7bba0350e",
  "cancelledDate": "2019-05-31",
  "totalDeltaMrr": 0,
  "totalDeltaTcv": -703.2258065,
  "invoiceId": "8a8082c453cd2a620153e426c7eb78b3"
}

CURL Example

CURL request:

#
## Cancel Subscription
##
echo
echo "=============Cancel Subscription============="
echo
curl -i -k -H "apiAccessKeyId:$USER_NAME" -H "apiSecretAccessKey:$PASSWORD" -H "Content-Type:application/json" -H "Accept:application/json" -d '
{
    "cancellationPolicy":"SpecificDate",
    "cancellationEffectiveDate": "2013-07-01",
    "invoiceCollect": false,
    "invoiceTargetDate": "2019-05-31"
}
' -X PUT $BASE_URL/v1/subscriptions/ff808081298c6e5401298c7a845c007b/cancel

JSON response:

{
  "success": true,
  "subscriptionId": "8a8082c453cd2a620154efc7bba0350e",
  "cancelledDate": "2019-05-31",
  "totalDeltaMrr": 0,
  "totalDeltaTcv": -703.2258065,
  "invoiceId": "8a8082c453cd2a620153e426c7eb78b3"
}
Last modified
15:54, 21 Sep 2016

Tags

Classifications

(not set)