Cancel a Subscription (Amendment)

Last updated
Save as PDF

Use the Cancellation amendment to cancel a subscription. Your approach will depend on the WSDL version that you are using, as described in the multiple sections below.

It's important to understand the distinction between the date the customer requests cancellation, and the date the cancellation takes effect (which may be a future date). The different WSDL versions handle this in various ways, as noted below. Generally, the Contract Effective Date is the date the customer provides notice of cancellation, and the Cancellation Effective Date is the date the cancellation takes effect. For more on these concepts, refer to our Cancellations page.

You cannot cancel draft subscriptions.

Canceling a Subscription (WSDL 29.0 and higher)

With version 29.0 and greater, you can use the amend() call to create amendments. Similar to the subscribe() call, the amend() call allows you to generate an invoice and capture payment electronically when amending subscriptions. The call also allows you to preview the invoices before amending the subscription.

Call amend() with the following information:

An Amendment object setting the following fields:
- Set the Type to Cancellation.
- Specify a name for the amendment.
- Specify the Subscription's ID.
- Set the EffectiveDate. This is the date when subscription cancellation takes effect. See Subscription and Amendment Dates for more information about how to use dates when canceling subscriptions.
PreviewOptions: Set PreviewMode to true if you want preview what the invoice would be (including the amount and charges) after the amendment, without creating the amendment. This is useful when calculating prorations and complex charges.

If you want un-cancel the subscription, then delete the amendment that canceled it in the first place. As a best practice, wait to cancel a subscription until the end of the billing period to avoid creating a cancelation invoice. You can't un-cancel a subscription after that invoice is generated. Your only recourse for un-canceling a subscription after invoice generation is to start a new subscription, which interrupts billing and risks a negative invoice, potentially transferring to a credit balance or causing a refund. If you do cancelations at the end of billing periods, then you don't generate cancelation invoices, leaving available your option to undo the cancelation.

SOAP Example

<api:amend>
  <api:requests>
     <api:Amendments>
         <obj:ContractEffectiveDate>2010-01-01</obj:ContractEffectiveDate>
         <obj:CustomerAcceptanceDate>2010-01-01</obj:CustomerAcceptanceDate>         
         <obj:Description>Cancel a subscription amendment</obj:Description>         
         <obj:EffectiveDate>2010-01-01</obj:EffectiveDate>         
         <obj:Name>Cancel a subscription amendment</obj:Name>         
         <obj:ServiceActivationDate>2010-01-01</obj:ServiceActivationDate>         
         <obj:Status>Completed</obj:Status>         
         <obj:SubscriptionId>402892c42ce80787012ce80ea1aa0014</obj:SubscriptionId>  
         <obj:Type>Cancellation</obj:Type>      
      </api:Amendments>
      <api:PreviewOptions>
         <api:EnablePreviewMode>true</api:EnablePreviewMode>
      </api:PreviewOptions>
  </api:requests>
</api:amend>

Canceling a Subscription (WSDL 25.0-28.0)

In version 25.0, Zuora added functionality to amend subscriptions in a single create() call. Zuora recommends that all Z-Commerce API users use the new amend() functionality. However, if you use create() and want to amend the subscription in a single call, you must set the CallOptions in your SOAP header and set useSingleTransaction to true.

Set the following fields to create an amendment to cancel a subscription:

Specify a name for the amendment.
Set the Type to Cancellation.
Specify the Subscription's ID.
Set ContractEffectiveDate (and ServiceActivation and CustomerAcceptance, if applicable).

SOAP Example

<ns1:create xmlns:ns1="http://api.zuora.com/">
  <ns1:zObjects xmlns:ns2="http://object.api.zuora.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:Amendment">   
    <ns2:Id xsi:nil="1" />   
    <ns2:ContractEffectiveDate>2010-07-21</ns2:ContractEffectiveDate>   
    <ns2:Name>test_amend1279686293769</ns2:Name>   
    <ns2:SubscriptionId>402892ca29f33da70129f33f35fb00ac</ns2:SubscriptionId>   
    <ns2:Type>Cancellation</ns2:Type>   
    <ns2:EffectiveDate>2010-07-21</ns2:EffectiveDate>
  </ns1:zObjects>
</ns1:create>

Cancelling a Subscription (WSDL 24.0 and earlier)

To cancel a subscription:

Create a new amendment.
Update the new amendment, setting the status to Completed.

Create a New Amendment

Use the create() call to create the new amendment. Set the following fields:

Specify a name for the amendment.
Set the Type to Cancellation.
Specify the Subscription's ID.
Set the EffectiveDate to the date and time of the cancellation. This must be a date in the future.
Set the Status to Draft.

SOAP Example

The SOAP call envelope payload should look like the following:

<ns1:create>
  <ns1:zObjects xsi:type="ns2:Amendment">   
    <ns2:EffectiveDate>2009-11-08</ns2:EffectiveDate>   
    <ns2:Name>Cancel Subscription</ns2:Name>   
    <ns2:Status>Draft</ns2:Status>   
    <ns2:SubscriptionId>4028e69922ece21e0122f1de76654502</ns2:SubscriptionId>   
    <ns2:Type>Cancellation</ns2:Type>
  </ns1:zObjects>
</ns1:create>

Update the New Amendment

Set the following fields:

Set the Id field to the Amendment ID returned in the initial query.
Set the ContractEffectiveDate to a date and time in the future.
If Require Customer Acceptance of Orders? is set to Yes on the Z-Billing Admin Default Subscription Settings page, then you must specify the ContractAcceptanceDate.
If Require Service Activation? is set to Yes on the Z-Billing Admin Default Subscription Settings page, then you must specify the ServiceActivationDate.
Set the Status to Completed.

SOAP Example

The SOAP call envelope payload should look like the following:

<ns1:update>
  <ns1:zObjects xsi:type="ns2:Amendment">   
    <ns2:Id>4028e69922ece21e0122f734f76777d5</ns2:Id>   
    <ns2:ContractEffectiveDate>2009-11-08</ns2:ContractEffectiveDate>   
    <ns2:ServiceActivationDate>2009-11-08</ns2:ServiceActivationDate>   
    <ns2:CustomerAcceptanceDate>2009-11-08</ns2:CustomerAcceptanceDate>   
    <ns2:Status>Completed</ns2:Status>
  </ns1:zObjects>
</ns1:update>