Cancel a Subscription (Amendment)
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
toCancellation
. - 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.
- Set the
PreviewOptions
: SetPreviewMode
totrue
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
toCancellation
. - Specify the Subscription's ID.
- Set
ContractEffectiveDate
(andServiceActivation
andCustomerAcceptance
, 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
toCancellation
. - 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
toDraft
.
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 theContractAcceptanceDate
. - If Require Service Activation? is set to
Yes
on the Z-Billing Admin Default Subscription Settings page, then you must specify theServiceActivationDate
. - Set the
Status
toCompleted
.
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>