Skip to main content

Renew a Subscription

Zuora

Renew a Subscription

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

Note that a subscription will automatically renew if the Subscription field AutoRenew has been set to true.

Renew a Subscription (WSDL 29.0 and higher)

With WSDL 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(), passing it the following information:

  • An Amendment object setting the following fields:
    • Set the Type to Renewal.
    • Specify a name for the amendment.
    • Specify the Subscription's ID.
    • Set ContractEffectiveDate (and ServiceActivation and CustomerAcceptance, if applicable).
  • 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.

SOAP Example

<api:amend>   
  <api:requests>      
    <api:Amendments>         
      <obj:ContractEffectiveDate>2010-01-01</obj:ContractEffectiveDate>         
      <obj:CustomerAcceptanceDate>2010-01-01T20:44:54.718+05:30</obj:CustomerAcceptanceDate>         
      <obj:Description>testing description - aaaaaaaaaaaaa</obj:Description>         
      <obj:EffectiveDate>2010-01-01</obj:EffectiveDate>         
      <obj:Name>testing renewal - name</obj:Name>         
      <obj:ServiceActivationDate>2010-01-01</obj:ServiceActivationDate>         
      <obj:Status>Completed</obj:Status>         
      <obj:SubscriptionId>402892c42ce80787012ce80ea1aa0014</obj:SubscriptionId>         
      <obj:Type>Renewal</obj:Type>      
   </api:Amendments>      
   <api:AmendOptions>         
     <api:GenerateInvoice>false</api:GenerateInvoice>         
     <api:ProcessPayments>false</api:ProcessPayments>      
    </api:AmendOptions>      
    <api:PreviewOptions>         
    <api:EnablePreviewMode>false</api:EnablePreviewMode>      
    </api:PreviewOptions>   
  </api:requests>
</api:amend>

Renew a Subscription (WSDL 25.0-28.0)

With WSDL version 25.0, we 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 renew a subscription:

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

SOAP Example

<api:amend>
   <api:requests>
      <api:Amendments>
         <obj:ContractEffectiveDate>2010-01-01</obj:ContractEffectiveDate>
         <obj:CustomerAcceptanceDate>2010-01-01T20:44:54.718+05:30</obj:CustomerAcceptanceDate>
         <obj:Description>Renewal amendment</obj:Description>
         <obj:EffectiveDate>2010-01-01</obj:EffectiveDate>
         <obj:Name>Renewal Amendment</obj:Name>
         <obj:ServiceActivationDate>2010-01-01</obj:ServiceActivationDate>
         <obj:Status>Completed</obj:Status>
         <obj:SubscriptionId>402892c42ce80787012ce80ea1aa0014</obj:SubscriptionId>
         <obj:Type>Renewal</obj:Type>
      </api:Amendments>
      <api:PreviewOptions>
         <api:EnablePreviewMode>true</api:EnablePreviewMode>
      </api:PreviewOptions>
   </api:requests>
</api:amend>

Renew a Subscription (WSDL 24.0 and earlier)

To renew a subscription:

  1. Create a new amendment.
  2. 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 Renewal.
  • Specify the Subscription's ID.
  • Set the EffectiveDate to the date and time of the renewal. 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 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:EffectiveDate>2009-11-08T08:00:00</ns2:EffectiveDate>
    <ns2:Name>Renew Subscription</ns2:Name>
    <ns2:Status>Draft</ns2:Status>
    <ns2:SubscriptionId>4028e69922ece21e0122f1de76654503</ns2:SubscriptionId>
    <ns2:Type>Renewal</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 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>4028e69922ece21e0122f734f76777d6</ns2:Id>
    <ns2:ContractEffectiveDate>2009-11-08</ns2:ContractEffectiveDate>
    <ns2:ServiceActivationDate>2009-11-08</ns2:ServiceActivationDate>
    <ns2:ContractAcceptanceDate>2009-11-08</ns2:ContractAcceptanceDate>
    <ns2:Status>Completed</ns2:Status>
  </ns1:zObjects>
</ns1:update>