Skip to main content

How do I cancel a subscription through the API at the end of the last invoice period?

Zuora

How do I cancel a subscription through the API at the end of the last invoice period?

Overview

When you cancel a subscription using the Zuora application, there is an option to cancel the subscription using the end of the last invoice period as the cancellation effective date. To do this, select End of Last Invoice Period for the Cancellation Effective Date field. The Cancellation Date field in the UI will default to one day later than the end of the last invoice period. For example, if the last invoice period is from April 24, 2012 to May 23, 2012, the cancellation date will be May 24, 2012. 

When you cancel a subscription via the SOAP API, there is no option to cancel the subscription using the end of the last invoice period. Therefore, to cancel a subscription via the API and ensure you do not generate a negative invoice as a result of canceling a subscription in the middle of a billing period that's been invoiced, you must use a cancelation date that is equivalent to the end of last invoice period.

This solution will walk you through an algorithm that can be used to determine the latest ChargedThroughDate (for all charges within the subscription you wish to cancel). After you obtain the latest ChargedThroughDate, you will use this date as the EffectiveDate for the cancellation amendment.

Solution

Cancel a subscription using the Zuora Application

In this example, the customer XYZ Corp has been billed for their subscription for the service period of February 1, 2012 - February 29, 2012. On February 15, 2012, they decide to cancel their subscription. According to your company's cancelation policy, cancelation is allowed only at the end of the last invoice period. Therefore, you will set the cancellation date to be March 1, 2012 by selecting End of Last Invoice Period. Then, there will not be any negative invoices (credits) issued back to the customer as a result of their cancelation. 

Cancel a subscription through the SOAP API

Dates populated in a cancelation amendment

To cancel a subscription via the SOAP API, you can either use the amend() call or the create() call. When using these calls, you must enter several dates to activate the amendment. Let's review these dates you will be required to enter. This is based on your Zuora Billing configuration settings and which date is auto-populated by Zuora when the subscription is canceled. 

To cancel a subscription via the API, you need to enter the subscription dates to activate the amendment:

  • ContractEffectiveDate: This is the effective date for the amendment. This can be the date your customer notifies you of the cancellation. 
  • ServiceActivationDate: This is the service activation date for the amendment. This date is only required if your Settings > Default Subscription Settings > Require Service Activation of Orders? is set to Yes.
  • CustomerAcceptanceDate: This is the customer acceptance date for the amendment. This date is only required if your Settings > Default Subscription Settings > Require Customer Acceptance of Orders? is set to Yes. 
  • EffectiveDate: This is the date the subscription will be canceled. It is the date that Zuora uses to automatically generate the CancelledDate for the subscription cancelation. 

Here are the dates as referenced in our SOAP API documentation

Subscription Cancellation Soap Example.jpg

When canceling a subscription via the API, the EffectiveDate used in the cancelation amendment is used to automatically generate the CancelledDate for the subscription.

CancelledDate.jpg

Determine EffectiveDate for Cancellation Amendment

To cancel a subscription at the end of last invoice period, you will need to use an EffectiveDate that is the earliest cancelation date you can use without creating a negative invoice (credit). For example, if the last invoice period is from February 1, 2012 through February 29, 2012, the EffectiveDate should be March 1, 2012. 

To determine the correct EffectiveDate to use, you must first find the latest ChargedThroughDate among all the charges in the subscription. Next, you will use the value of that field as the EffectiveDate for the cancelation amendment.

ChargethroughDate API Docs.jpg

Steps

  1. Query the Subscription object to get the Id, where Status = 'Active'.
  2. Query the RatePlan object using the SubscriptionId from Step 1.
  3. Query all RatePlanCharge object and compare its ChargedThroughDate, where IsLastSegment = 'true'.
  4. Get the LATEST ChargedThroughDate and use it as the  EffectiveDate (which Zuora will by default use as the CancelledDate) for the subscription.

Example

# $subId contains the latest version of the subscription you want to find the latest charges on (where status is 'Active')
$endOfTermDate = '';

# Find all RatePlans on this subscription
$rpResult = $zapi->zQuery("SELECT Id,Name,ProductRatePlanId FROM RatePlan WHERE SubscriptionId='".$subId."'");

foreach($rpResult->result-><wbr/>records as $rp){
# Get all charges on each RatePlan
$rpcResult = $zapi->zQuery("SELECT Id,Name,<wbr/>ProductRatePlanChargeId,ChargeModel,ChargeType,UOM,Quantity,ChargedThroughDate FROM RatePlanCharge WHERE RatePlanId='".$rp->Id."' AND IsLastSegment=true");

foreach($rpcResult->result-><wbr/>records as $rpc){
# For all charges, find maximum ChargedThroughDate
if(isset($rpc-><wbr/>ChargedThroughDate)){
# Check the current rateplancharge against the current latest charge, and save it to $endOfTermDate if it's later.
if($rpc->ChargedThroughDate > $activeSub->endOfTermDate){
$endOfTermDate = $rpc->ChargedThroughDate;

}
}
}
}

# $endOftermDate now stores the latest chargedThroughDate