Skip to main content

Update a Product (Amendment)

Zuora

Update a Product (Amendment)

  1. Last updated
  2. Save as PDF

Use the UpdateProduct amendment to update a product in a subscription. The method that you use depends on the version of the Zuora API that you are using.

Create an UpdateProduct Amendment in a Subscription (API version 29.0+)

In WSDL 29.0 and later, 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 an Amendment object with the following information:

  • Set the Type to UpdateProduct.
  • Specify a name for the amendment.
  • Specify the Subscription's ID.
  • Set ContractEffectiveDate (and ServiceActivation and CustomerAcceptance, if applicable).
  • Set the RatePlanData object, which wraps the desired Rate Plan of the new product. If you want to override any of the fields at the charge level, specify this within RatePlanChargeData.
  • Use AmendOptions if you want to generate an invoice.
    • ApplyCreditBalance: Set this to true if you want any credit balance on a customer's account to be automatically applied to invoices. If you do not specify a value then this field defaults to false.
    • GenerateInvoice: Set this to true if you want Zuora to generate an invoice after the amend() call to bill the customer immediately for the new product.
    • ProcessPayment: Set this to true if you want Zuora to collect payment against the invoice. To use this, the Account must have AutoPay set to true.
    • InvoiceProcessingOptions: Set the InvoiceTargetDate to the date you want Zuora to calculate charges for the invoice. This is used only when GenerateInvoice is set to true. If you do not specify this and GenerateInvoice is set to true, Zuora will use the current date.
  • Use PreviewOptions to view a preview of the invoice before creating it. 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


<ns1:amend xmlns:ns1="http://api.zuora.com/">    
  <ns1:requests>        
    <ns1:Amendments xmlns:ns2="http://object.api.zuora.com/"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">            
    <!-- Specify amendment dates and names -->            
      <ns2:ContractEffectiveDate>2011-03-15</ns2:ContractEffectiveDate>            
      <ns2:CustomerAcceptanceDate>2011-03-15</ns2:CustomerAcceptanceDate>            
      <ns2:Description>testing amend for TimeTrade</ns2:Description>            
      <ns2:EffectiveDate>2011-03-15</ns2:EffectiveDate>            
      <ns2:Name>TimeTrade Test - Add New Product</ns2:Name>            
      <!-- Specify the Id of the existing RatePlan that you wish to update.  This is
           specified in AmendmentSubscriptionRatePlanId -->
      <ns2:RatePlanData>                
        <ns1:RatePlan>                    
          <ns2:AmendmentSubscriptionRatePlanId>4028e6962eb8004a012ebd076579723f
          </ns2:AmendmentSubscriptionRatePlanId>                
        </ns1:RatePlan>                
        <!-- Using RatePlanChargeDate node, specify the charge or charges you wish to
             update, such as changing price or quantity.  -->                
          <ns1:RatePlanChargeData>                    
            <ns1:RatePlanCharge>                        
              <ns2:ProductRatePlanChargeId>4028e6972eb80043012ebd03b23d5598
              </ns2:ProductRatePlanChargeId>                        
              <ns2:Quantity>7</ns2:Quantity>                    
            </ns1:RatePlanCharge>                    
            <!-- Add optional RatePlanChargeTierData node here  --> 
            <!-- NOTE: If using tiered or volume pricing, you must override the 
                 pricing using RatePlanChargeTierData  -->                
          </ns1:RatePlanChargeData>            
      </ns2:RatePlanData>            
      <ns2:ServiceActivationDate>2011-03-15</ns2:ServiceActivationDate>            
      <ns2:Status>Completed</ns2:Status>            
      <ns2:SubscriptionId>4028e6962eb8004a012ebd076551723a</ns2:SubscriptionId> 
      <ns2:Type>UpdateProduct</ns2:Type>
    </ns1:Amendments>
    <ns1:AmendOptions> 
      <ns1:GenerateInvoice>True</ns1:GenerateInvoice>
      <ns1:ProcessPayments>True</ns1:ProcessPayments>
    </ns1:AmendOptions>        
    <ns1:PreviewOptions>            
      <ns1:EnablePreviewMode>False</ns1:EnablePreviewMode>
    </ns1:PreviewOptions>
  </ns1:requests>
</ns1:amend>

Create an UpdateProduct Amendment in a Subscription (API versions 25.0-28.0)

In WSDL 25.0, Zuora added functionality to amend subscriptions in a single create() call. Zuora recommends that all Z-Commerce API users use the 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 a new amendment:

  • Set the Type to UpdateProduct.
  • Specify a name for the amendment.
  • Specify the Subscription's ID.
  • Set ContractEffectiveDate
    • Also set ServiceActivation and CustomerAcceptance, if applicable.
  • Set the RatePlanData object, which wraps the desired rate plan of the new product. If you want to override any of the fields at the charge level, specify this within RatePlanChargeData.
  • Create the amendment. Use the useSingleTransaction CallOption to execute this call successfully.

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:ContractEffectiveDate>2010-07-21</ns2:ContractEffectiveDate>   
    <ns2:CustomerAcceptanceDate>2010-07-21</ns2:CustomerAcceptanceDate>   
    <ns2:EffectiveDate>2010-07-21</ns2:EffectiveDate>   
    <ns2:Name>test_amend1279683889873</ns2:Name>   
    <ns2:RatePlanData>     
       <ns1:RatePlan xsi:type="ns2:RatePlan">       
         <ns2:AmendmentSubscriptionRatePlanId>402892ca29f3191a0129f31a84d000a8
         </ns2:AmendmentSubscriptionRatePlanId>     
       </ns1:RatePlan>     
         <ns1:RatePlanChargeData>       
           <ns1:RatePlanCharge xsi:type="ns2:RatePlanCharge">         
             <ns2:Description>111111</ns2:Description>         
             <ns2:Price>1000</ns2:Price>         
             <ns2:ProductRatePlanChargeId>402892ca29f3191a0129f31a82b00099
             </ns2:ProductRatePlanChargeId>       
           </ns1:RatePlanCharge>     
         </ns1:RatePlanChargeData>   
    </ns2:RatePlanData>
    <ns2:ServiceActivationDate>2010-07-21</ns2:ServiceActivationDate>   
    <ns2:SubscriptionId>402892ca29f3191a0129f31a86ad00ac</ns2:SubscriptionId>   
    <ns2:Type>UpdateProduct</ns2:Type>
  </ns1:zObjects>
</ns1:create>

Create an UpdateProduct Amendment in a Subscription (API versions 24.0 and earlier)

To update an existing product in a subscription:

  1. Create a new amendment.
  2. Create a new RatePlan.
  3. Update the RatePlanCharge.
  4. 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:

  • Set the Type to UpdateProduct.
  • Specify the ID of the Subscription object.
  • Set the Status to Draft. This is important, because the amendment is not complete until you add the new product.

SOAP Example

The SOAP call envelope payload should look like the following:


<ns1:create> 
  <ns1:zObjects xsi:type="ns2:Amendment">   
    <ns2:EffectiveDate>2009-07-15</ns2:EffectiveDate>   
    <ns2:Name>Change Charge Quantity</ns2:Name>   
    <ns2:Status>Draft</ns2:Status>   
    <ns2:SubscriptionId>4028e6992276b151012280791cc701a9</ns2:SubscriptionId>   
    <ns2:Type>UpdateProduct</ns2:Type> </ns1:zObjects>
</ns1:create>

Create a New RatePlan

Set the following fields:

  • Set the new AmendmentId to the new Amendment ID returned in your previous query.
  • Set the new AmendmentSubscriptionRatePlanId to the correct RatePlan ID.
  • Set the AmendmentType to UpdateProduct.
  • Set the ProductRatePlanId to the rate plan ID returned from querying the RatePlan object. The rate plan should belong to the subscription that you specified in your previous query.

Zuora will create RatePlanCharges and RatePlanChargeTiers in the background.

SOAP Example

The SOAP call envelope payload should look like the following:


<ns1:create> 
  <ns1:zObjects xsi:type="ns2:RatePlan">
    <ns2:AmendmentId>4028e6992276b1510122843ec65731b9</ns2:AmendmentId>   
    <ns2:AmendmentSubscriptionRatePlanId>4028e6992276b151012280791d2801b7
    </ns2:AmendmentSubscriptionRatePlanId>   
    <ns2:AmendmentType>UpdateProduct</ns2:AmendmentType> 
    <ns2:ProductRatePlanId>402882eb1db92512011db9262be70025</ProductRatePlanId>
  </ns1:zObjects>
</ns1:create>

Update the RatePlanCharge

Next, update the RatePlanCharge for the product.

SOAP Example

The SOAP call envelope payload should look like the following:


<ns1:update> 
  <ns1:zObjects xsi:type="ns2:RatePlanCharge">   
    <ns2:Id>4028e6992276b15101228441bf7531ce</ns2:Id>   
    <ns2:Quantity>2</ns2:Quantity> 
  </ns1:zObjects>
</ns1:update>

Update the New Amendment

Set the following fields:

  • 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> 
  <ns1:zObjects xsi:type="ns2:Amendment">   
    <ns2:Id>4028e6992276b1510122843ec65731b9</ns2:Id>   
    <ns2:ContractEffectiveDate>2009-07-15</ns2:ContractEffectiveDate>   
    <ns2:Status>Completed</ns2:Status> 
  </ns1:zObjects>
</ns1:update>

Create an UpdateProduct Amendment Before a Future-dated Update (API version 71.0+)

In WSDL 71.0 and later, you can use the amend() call to create UpdateProduct amendments even when future-dated UpdateProduct amendments already exist on the subscription.

Call amend(), passing it an Amendment object with the following information:

  • Set the Type to UpdateProduct.
  • Specify a name for the amendment.
  • Specify the Subscription's ID.
  • Set ContractEffectiveDate. This is the date when the customer notifies you that they want to make changes to their subscription.
  • Set SpecificUpdateDate to the date when you want the UpdateProduct amendment to take effect.
  • Set the RatePlanData object, which wraps the desired Rate Plan of the new product. If you want to override any of the fields at the charge level, specify this within RatePlanChargeData.

SOAP Example


<ns1:amend xmlns:ns1="http://api.zuora.com/">    
  <ns1:requests>        
    <ns1:Amendments xmlns:ns2="http://object.api.zuora.com/"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">            
    <!-- Specify amendment dates and names -->            
      <ns2:ContractEffectiveDate>2015-07-01</ns2:ContractEffectiveDate>            
      <ns2:CustomerAcceptanceDate>2015-07-01</ns2:CustomerAcceptanceDate>            
      <ns2:Description>update before update</ns2:Description>                      
      <ns2:Name>Amendment Name</ns2:Name>  
      <ns2:SpecificUpdateDate>2015-07-01</ns2:SpecificUpdateDate>          
      <!-- Specify the Id of the existing RatePlan that you wish to update.  This is
           specified in AmendmentSubscriptionRatePlanId -->
      <ns2:RatePlanData>                
        <ns1:RatePlan>                    
          <ns2:AmendmentSubscriptionRatePlanId>4028e6962eb8004a012ebd076579723f
          </ns2:AmendmentSubscriptionRatePlanId>                
        </ns1:RatePlan>                
        <!-- Using RatePlanChargeDate node, specify the charge or charges you wish to
             update, such as changing price or quantity.  -->                
          <ns1:RatePlanChargeData>                    
            <ns1:RatePlanCharge>                        
              <ns2:ProductRatePlanChargeId>4028e6972eb80043012ebd03b23d5598
              </ns2:ProductRatePlanChargeId>                        
              <ns2:Quantity>10</ns2:Quantity>                    
            </ns1:RatePlanCharge>                    
            <!-- Add optional RatePlanChargeTierData node here  --> 
            <!-- NOTE: If using tiered or volume pricing, you must override the 
                 pricing using RatePlanChargeTierData  -->                
          </ns1:RatePlanChargeData>            
      </ns2:RatePlanData>            
      <ns2:ServiceActivationDate>2015-07-01</ns2:ServiceActivationDate>            
      <ns2:Status>Completed</ns2:Status>            
      <ns2:SubscriptionId>4028e6962eb8004a012ebd076551723a</ns2:SubscriptionId> 
      <ns2:Type>UpdateProduct</ns2:Type>
    </ns1:Amendments>
  </ns1:requests>
</ns1:amend>