Part 3: Amend a Subscription Using Zuora API

Last updated
Save as PDF

Overview

Zuora Internal Documentation. This article is intended for Zuora only. Do not share or distribute publicly.

This section explains how to use amendments in Zuora to update, replace, or cancel subscriptions via the API.

Update Subscription

Updating a product allows you to make changes to quantities and / or pricing in a subscription without switching the customer's rate plan. You can use either the create() call or the amend() call, passing in an Amendment object having a Type equal to UpdateProduct.

Here are the values that you will need to set in the amendment object:

ContractEffectiveDate: Set this dateTime value to be the date that you want this update to take effect.
Description: Enter a short business description, for your future reference, describing the update that you are making.
RatePlanData: Within this complex Zuora data type, you will need to include the following values:
- Within a RatePlan object, you will pass in the following:
  - AmendmentSubscriptionRatePlanId: Set this value to the ID of the rate plan within the subscription that you wish to update. Note: to do this, you will have to query for the unique value of this rate plan ID within that subscription.
- Within a RatePlanChargeData object, you will need to pass in one or more RatePlanCharge sub-objects having the following values:
  - ProductRatePlanChargeId: Set this value to the ID of the specific charge within the subscription rate plan that you want to update within your tenant. Note: to do this, you will have to query for the unique value of this charge ID within your tenant.
  - Price: If you want to change the price of this charge for your subscriber (for example, lower the monthly price as part of a discount), then enter the new value for the price in this field.
  - Quantity: For per unit charges, if you want to change the quantity of units that this subscriber has purchased (for example, because the subscriber has upgraded to more licenses), then enter the new quantity in this field.
SubscriptionId: Enter the ID for the subscription object within the customer subscription that you wish to update. Note: to do this, you will have to query for the unique value of this subscription ID within your tenant.
Type: Set to UpdateProduct.

When using the amend() call, you should also consider setting the following values for the AmendOptions:

GenerateInvoice: Set to false if you do not want an invoice to be generated as part of the amendment. If you omit this value, it will be set to true.
ProcessPayment: Set to false if you do not want a payment to be processed as part of the amendment. If you omit this value, it will be set to true.

Sample XML Code for Update Subscription

For your reference, here is sample XML code for using the amend() call to update the price to $25 and the quantity to 5 on a customer subscription with a SubscriptionId of abc123, for a rate plan with an AmendmentSubscriptionRatePlanId of bcd234, on a charge with a ProductRatePlanChargeId of cde345, and with an effective date of January 12, 2012:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns2="http://object.api.zuora.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns1="http://api.zuora.com/">
    <SOAP-ENV:Header>
        <ns1:SessionHeader>
            <ns1:session>(sessionID)</ns1:session>
        </ns1:SessionHeader>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <ns1:amend>
            <ns1:requests>
                <ns1:Amendments>
                    <ns2:ContractEffectiveDate>2012-01-12T00:00:00.000-08:00</ns2:ContractEffectiveDate>
                    <ns2:Description>Seat license upgrade with discount</ns2:Description>
                    <ns2:RatePlanData>
                        <ns1:RatePlan>
                            <ns2:AmendmentSubscriptionRatePlanId>bcd234
                            </ns2:AmendmentSubscriptionRatePlanId>
                        		</ns1:RatePlan>
                        <ns1:RatePlanChargeData>
                            <ns1:RatePlanCharge>
                                <ns2:ProductRatePlanChargeId>cde345
                                </ns2:ProductRatePlanChargeId>
                                <ns2:Price>25</ns2:Price>
                                <ns2:Quantity>5</ns2:Quantity>
                            	    	</ns1:RatePlanCharge>
                        	  </ns1:RatePlanChargeData>	
                       </ns2:RatePlanData>
                    <ns2:SubscriptionId>abc123</ns2:SubscriptionId>
                    <ns2:Type>UpdateProduct</ns2:Type>
                 </ns1:Amendments>
                <ns1:AmendOptions>
                    <ns1:GenerateInvoice>false</ns1:GenerateInvoice>
                    <ns1:ProcessPayments>false</ns1:ProcessPayments>
                 </ns1:AmendOptions>
            </ns1:requests>
        </ns1:amend>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Here is sample code for the same amendment when using the create() call:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns2="http://object.api.zuora.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns1="http://api.zuora.com/">
    <SOAP-ENV:Header>
        <ns1:CallOptions>
            <ns1:useSingleTransaction>true</ns1:useSingleTransaction>
        </ns1:CallOptions>
        <ns1:SessionHeader>
            <ns1:session>(sessionID)</ns1:session>
        </ns1:SessionHeader>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <ns1:create>
            <ns1:zObjects xsi:type="ns2:Amendment">
                <ns2:ContractEffectiveDate>2012-01-12T00:00:00.000-08:00</ns2:ContractEffectiveDate>
                <ns2:Description>Seat license upgrade with discount</ns2:Description>
                <ns2:RatePlanData>
                    <ns1:RatePlan>
                        <ns2:AmendmentSubscriptionRatePlanId>bcd234
                        </ns2:AmendmentSubscriptionRatePlanId>
                    		</ns1:RatePlan>
                    <ns1:RatePlanChargeData>
                        <ns1:RatePlanCharge>
                            <ns2:ProductRatePlanChargeId>cde345</ns2:ProductRatePlanChargeId>
                            <ns2:Price>25</ns2:Price>
                            <ns2:Quantity>5</ns2:Quantity>
                        	    	</ns1:RatePlanCharge>
                    	  </ns1:RatePlanChargeData>	
                   </ns2:RatePlanData>
                <ns2:SubscriptionId>abc123</ns2:SubscriptionId>
                <ns2:Type>UpdateProduct</ns2:Type>
             </ns1:zObjects>
        </ns1:create>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Replace Subscription

Replace a rate plan when a customer upgrades or downgrades his subscription (for example, upgrading from a silver to a gold plan), or otherwise wants to change his current subscription plan (for example, changing from an Annual to a Monthly plan). To change a customer's rate plan, you must remove the old rate plan and add a new one.

To do this using the Zuora API, use the create() call and pass in both a RemoveProduct Amendment object and an AddProduct Amendment object.

Note: The amend() call within the Zuora API is not supported for this particular amendment, because the Replace Rate Plan amendment encapsulates two amendments (RemoveProduct and AddProduct) into a single action, and the amend() call only supports a single amendment at a time.

Here are the values that you will need to set in the RemoveProduct amendment object:

ContractEffectiveDate: Set this dateTime value to be the date that you want this replacement to take effect.
RatePlanData: Within this complex Zuora data type, you will need to include the following values:
- Within a RatePlan object, you will pass in the following:
  - AmendmentSubscriptionRatePlanId: Set this value to the ID of the rate plan within the subscription that you wish to remove. Note: to do this, you will have to query for the unique value of this rate plan ID within that subscription.
SubscriptionId: Enter the ID for the subscription object within the customer subscription that you are amending. Note: to do this, you will have to query for the unique value of this subscription ID within your tenant.
Type: Set to RemoveProduct.

Here are the values that you will need to set in the NewProduct amendment object:

ContractEffectiveDate: Set this dateTime value to be the date that you want this replacement to take effect. Be sure to enter the same value that you entered for the ContractEffectiveDate in the RemoveProduct amendment object.
Description: Enter a short business description, for your future reference, describing the replacement that you are making.
RatePlanData: Within this complex Zuora data type, you will need to include the following values:
- Within a RatePlan object, you will pass in the following:
  - ProductRatePlanId: Set this value to the ID of the product rate plan that you are adding as part of the amendment. Note: to do this, you will have to query for the unique value of this product rate plan ID within your tenant.
- (Optional) Within a RatePlanChargeData object, you may optionally pass in one or more RatePlanCharge sub-objects if you want to override the default prices or quantities for any charges in this new rate plan. The most likely use case is if you offer a per-unit charge (for example, number of seats) in the new rate plan and need to set the quantity for the number of units purchased. You will include the following values in each RatePlanCharge sub-object:
  - ProductRatePlanChargeId: Set this value to the ID of the specific charge within the product rate plan that you want to modify. Note: to do this, you will have to query for the unique value of this charge ID within your tenant.
  - Price: If you want to change the default price of this charge for your subscriber (for example, lower the monthly price as part of a discount), then enter the new value for the price in this field.
  - Quantity: For per unit charges, if you want to change the default quantity of units that this subscriber has purchased (for example, because the subscriber has purchased a certain number of seats), then enter the quantity in this field.
SubscriptionId: Enter the ID for the subscription object within the customer subscription that you are amending. Be sure to enter the same value that you entered for the SubscriptionId in the RemoveProduct amendment object.
Type: Set to NewProduct.

Sample XML Code for Replace Subscription

For your reference, here is sample XML code for using the create() call to replace the rate plan for a customer's subscription with a SubscriptionId of abc123 and with an effective date of January 12, 2012. The subscription rate plan being removed has an AmendmentSubscriptionRatePlanId of bcd234. The product rate plan being added has a ProductRatePlanId of cde345, and in this example, we are not overriding any of the default prices or quantities for any changes in this new rate plan.

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns2="http://object.api.zuora.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns1="http://api.zuora.com/">
    <SOAP-ENV:Header>
        <ns1:CallOptions>
            <ns1:useSingleTransaction>true</ns1:useSingleTransaction>
        </ns1:CallOptions>
        <ns1:SessionHeader>
            <ns1:session>(sessionID)</ns1:session>
        </ns1:SessionHeader>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <ns1:create>
            <ns1:zObjects xsi:type="ns2:Amendment">
                <ns2:ContractEffectiveDate>2012-01-12T00:00:00.000-08:00</ns2:ContractEffectiveDate>
                <ns2:RatePlanData>
                    <ns1:RatePlan>
                        <ns2:AmendmentSubscriptionRatePlanId>bcd234
                        </ns2:AmendmentSubscriptionRatePlanId>
                    		</ns1:RatePlan>
                   </ns2:RatePlanData>
                <ns2:SubscriptionId>abc123</ns2:SubscriptionId>
                <ns2:Type>RemoveProduct</ns2:Type>
             </ns1:zObjects>
            <ns1:zObjects xsi:type="ns2:Amendment">
                <ns2:ContractEffectiveDate>2012-01-04T00:00:00.000-08:00</ns2:ContractEffectiveDate>
                <ns2:Description>Upgrade to gold plan</ns2:Description>
                <ns2:RatePlanData>
                    <ns1:RatePlan>
                        <ns2:ProductRatePlanId>cde345</ns2:ProductRatePlanId>
                    		</ns1:RatePlan>
                   </ns2:RatePlanData>
                <ns2:SubscriptionId>abc123</ns2:SubscriptionId>
                <ns2:Type>NewProduct</ns2:Type>
             </ns1:zObjects>
        </ns1:create>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Cancel Subscription

To cancel a customer subscription in Zuora, you can use the amend() call, passing in an Amendment object with a Type of Cancellation and a SubscriptionId equal to the Id of the subscription that you are canceling (to obtain the SubscriptionId, you will have to query for the unique value of this subscription ID within your tenant).

Note: While we recommend the amend() call, you can also use the create() API call to cancel a subscription. If you choose to use the create() call, you must set the useSingleTransaction field value to "true" in the CallOptions within your API call Header.

In the amend() call, set both the Contract Effective Date and Effective Date within the Amendment object equal to the date when the cancellation should take place.

Sample XML Code for Cancel Subscription

For your reference, here is sample XML code for using the amend() call to cancel a customer subscription with a SubscriptionId of 4028e69633eb4e310133eb624c0b08a1 with an effective date of January 10, 2012:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns2="http://object.api.zuora.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns1="http://api.zuora.com/">
    <SOAP-ENV:Header>
        <ns1:SessionHeader>
            <ns1:session>(session)</ns1:session>
        </ns1:SessionHeader>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <ns1:amend>
            <ns1:requests>
                <ns1:Amendments>
                    <ns2:ContractEffectiveDate>2012-01-10T00:00:00.000-08:00</ns2:ContractEffectiveDate>
                    <ns2:EffectiveDate>2012-01-10T00:00:00.000-08:00</ns2:EffectiveDate>
                    <ns2:SubscriptionId>4028e69633eb4e310133eb624c0b08a1</ns2:SubscriptionId>
                    <ns2:Type>Cancellation</ns2:Type>
                 </ns1:Amendments>
             </ns1:requests>
        </ns1:amend>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

What's Next

Proceed to Part 4: Update Customer Payment Method and Account Information.