Knowledge Center

Knowledge Center > How Do I . . . ? > How do I cancel a subscription through the API at the end of the last invoice period?

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

Overview

When canceling a subscription using the Zuora application, there is an option to cancel the subscription using a Cancellation Effective Date equal to the End of the Last Invoice Period. When selecting End of the Last Invoice Period, the Cancellation Date in the UI defaults to a date that is +1 day after the last invoiced period. For example, if the last invoice period is from April 24, 2012 through May 23, 2012, the Cancellation Date will be May 23, 2012 + 1 day = May 24, 2012. 

End of Last Invoice Period.jpg

When canceling a subscription via the SOAP API, there is not an option to cancel the subscription using the End of Last Invoice Period - this option is only available via the UI. Therefore, to cancel a subscription via the API and ensure you do not generate a negative invoice as a result of cancelling 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). Once you obtain the latest ChargedThroughDate, you will use this date as the EffectiveDate for the cancellation amendment.

Solution

Canceling 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 and per your company's cancelation policy, you will only allow cancelation at the End of the Last Invoice Period. Therefore, you will set the Cancellation Date to March 1, 2012 by choosing End of Last Invoice Period; by doing this, there will not be any negative invoices (credits) issued back to the customer as a result of their cancelation. 

Last Invoiced Date.jpg

 

Cancelled Subscription Example.jpg

 

Canceling 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 entered. This is based on your Z-Billing configuration settings and which date is auto-populated by Zuora when the subscription is canceled. 

To cancel a subscription via the API, you will 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 Z-Billing  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 Z-Billing  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

Determining the EffectiveDate for the 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 latest ChargedThroughDate amongst 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
Last modified
01:18, 25 Mar 2016

Tags

Classifications

(not set)