Skip to main content

Add a Product (Amendment)

Zuora

Add a Product (Amendment)

  1. Last updated
  2. Save as PDF

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

Adding a Product to a Subscription (API version 29.0+)

In 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 NewProduct.
    • 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 to specify the following items:
    • 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.
    • 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


<ns1:amend>
   <ns1:requests> 
      <ns1:Amendments>
      
<!--Specify the basic amendment information, such as trigger dates, name etc. --> 
         <ns2:ContractEffectiveDate>2011-01-01</ns2:ContractEffectiveDate> 
         <ns2:CustomerAcceptanceDate>2011-01-01</ns2:CustomerAcceptanceDate> 
         <ns2:Description>testing description - aaaaaaaaaaaaa</ns2:Description> 
         <ns2:EffectiveDate>2011-01-01</ns2:EffectiveDate> 
         <ns2:Name>testing - name</ns2:Name>
         <ns2:RatePlanData>
       
<!--When adding a product, specify the ProductRatePlanId -->
            <ns1:RatePlan>
               <ns2:ProductRatePlanId>4028b8812d0261b6012d02660708001b</ns2:ProductRatePlanId> 
            </ns1:RatePlan>
            
<!--Insert optional RatePlanChargeData node here if you want to override any of the default values for the charges that belong to this rate plan--> 
         </ns2:RatePlanData> 
         <ns2:ServiceActivationDate>2011-01-01</ns2:ServiceActivationDate> 
         <ns2:Status>Completed</ns2:Status>
         <ns2:SubscriptionId>4028b8812d0261b6012d0266aac5001f</ns2:SubscriptionId>
            
<!--Specify NewProduct to add an amendment.--> 
         <ns2:Type>NewProduct</ns2:Type>
      </ns1:Amendments>
      
<!--To generate an invoice and capture payment of the order, set GenerateInvoice and ProcessPayment to true --> 
         <ns1:AmendOptions>
            <ns1:GenerateInvoice>True</ns1:GenerateInvoice> 
            <ns1:ProcessPayments>True</ns1:ProcessPayments>
         </ns1:AmendOptions>
         
<!--To preview what the invoice(s) generated WOULD be, set EnablePreviewMode to true. NOTE: This does NOT create the amendment -->
         <ns1:PreviewOptions> 
            <ns1:EnablePreviewMode>False</ns1:EnablePreviewMode> 
         </ns1:PreviewOptions>
   </ns1:requests>
</ns1:amend>

Adding a Product to a Subscription (API versions 25.0-28.0)

In version 25.0, Zuora 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 a new amendment:

  • Set the Type to NewProduct.
  • 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:Id xsi:nil="1" />
      <ns2:ContractEffectiveDate>2011-07-21</ns2:ContractEffectiveDate>   
      <ns2:CustomerAcceptanceDate>2011-07-21</ns2:CustomerAcceptanceDate>   
      <ns2:EffectiveDate>2011-07-21</ns2:EffectiveDate>   
      <ns2:Name>test_amend1279685624586</ns2:Name>   
      
      <ns2:RatePlanData>         
         <ns1:RatePlan xsi:type="ns2:RatePlan">       
             <ns2:ProductRatePlanId>402892ca29f3335a0129f334f123008c</ns2:ProductRatePlanId>     
         </ns1:RatePlan>     
         <ns1:RatePlanChargeData>	
            <ns1:RatePlanCharge xsi:type="ns2:RatePlanCharge">          
               <ns2:Description>2222222</ns2:Description>          
               <ns2:Price>1000</ns2:Price>          
               <ns2:ProductRatePlanChargeId>402892ca29f3335a0129f334f70f008e</ns2:ProductRatePlanChargeId>      	     
            </ns1:RatePlanCharge>     
        </ns1:RatePlanChargeData>   
     </ns2:RatePlanData>
     <ns2:ServiceActivationDate>2011-07-21</ns2:ServiceActivationDate>
     <ns2:SubscriptionId>402892ca29f3335a0129f334fefe00ac</ns2:SubscriptionId>   
     <ns2:Type>NewProduct</ns2:Type>
   </ns1:zObjects>
</ns1:create>

Adding a Product to a Subscription (API versions 24.0 and earlier)

To add a product to a subscription:

  1. Create a new amendment.
  2. Create a new RatePlan.
  3. 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 NewProduct.
  • Specify the ID of the Subscription object.
  • Set the Status to Draft. This is important, because the amendment is not completed until you add the new product.

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>2011-11-20</ns2:EffectiveDate>  
      <ns2:Name>test_amend1227171970720</ns2:Name>  
      <ns2:Status>Draft</ns2:Status>  
      <ns2:SubscriptionId>402882eb1db92512011db92607cf0011</ns2:SubscriptionId>  
      <ns2:Type>NewProduct</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 AmendmentType to NewProduct.
  • 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 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:RatePlan">  
      <ns2:AmendmentId>402882eb1db8f6b6011db92641ce0023</ns2:AmendmentId>  
      <ns2:AmendmentType>NewProduct</ns2:AmendmentType>  
      <ns2:ProductRatePlanId>402882eb1db92512011db9262be70025</ns2:ProductRatePlanId> 
   </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>402882eb1db8f6b6011db92641ce0023</ns2:Id>   
      <ns2:ContractEffectiveDate>2011-11-20</ns2:ContractEffectiveDate>   
      <ns2:CustomerAcceptanceDate>2011-11-22</ns2:CustomerAcceptanceDate>   
      <ns2:Description>Test changing</ns2:Description>   
      <ns2:ServiceActivationDate>2011-11-22</ns2:ServiceActivationDate>   
      <ns2:Status>Completed</ns2:Status> 
   </ns1:zObjects>
</ns1:update>