Updating a Product

From API Documentation

Jump to: navigation, search

Starting in Version 29.0 and greater, you can now create Amendments with the amend() call. Similar to the subscribe() call, you the amend() call allows you to generate an invoice and capture payment electronically when amending subscriptions, as well as previewing the invoices before actually amending the subscription.


NOTE: In version 25.0, Zuora added functionality to amend subscriptions in a single create() call. It is strongly recommended 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. See CallOptions for more details.

To update a product on subscription, use the UpdateProduct amendment.

Updating an Existing Product in a Subscription (Version 29.0+)

Use the amend() call, passing it an Amendment.

  • Set the following fields:
    • 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.
  • AmendOptions if you want to generate an invoice.
  • PreviewOptions if you want to see a preview of the invoice before creating it, else you can omit this. 
<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-15T20:44:54.718+05:30</ns2:ContractEffectiveDate>
            <ns2:CustomerAcceptanceDate>2011-03-15T20:44:54.718+05:30</ns2:CustomerAcceptanceDate>
            <ns2:Description>testing amend for TimeTrade</ns2:Description>
            <ns2:EffectiveDate>2011-03-15T20:44:54.718+05:30</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-15T20:44:54.718+05:30</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>

Updating an Existing Product in a Subscription (Version 25.0+):

Create a new amendment

  • Set the following fields:
    • 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.
    • Create the amendment. 
<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-21T11:44:49.875-08:00</ns2:ContractEffectiveDate>
   <ns2:CustomerAcceptanceDate>2010-07-21T11:44:49.875-08:00</ns2:CustomerAcceptanceDate>
   <ns2:EffectiveDate>2010-07-21T11:44:49.875-08:00</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-21T11:44:49.875-08:00</ns2:ServiceActivationDate>
   <ns2:SubscriptionId>402892ca29f3191a0129f31a86ad00ac</ns2:SubscriptionId>
   <ns2:Type>UpdateProduct</ns2:Type>
  </ns1:zObjects>
</ns1:create>


Updating an Existing Product in a Subscription (Version 24.0-):

1) Create a new Amendment:

  • Set the following fields:
    • Set the Type to UpdateProduct.
    • Set the SubscriptionId.
    • Set the Status to Draft. Setting it to Draft is important because the amendment then won't go through until all the product update is finished.
  • Create the new amendment, see the create() API call.

The SOAP call envelope payload should look like this: 

<ns1:create>
 <ns1:zObjects xsi:type="ns2:Amendment">
   <ns2:EffectiveDate>2009-07-15T12:00:00</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>

2) Now create a new RatePlan:

  • Set the following fields:
    • Set the new AmendmentId to the new amendment you've created.
    • Set the new AmendmentSubscriptionRatePlanId to the appropriate RatePlan id.
    • Set the AmendmentType to UpdateProduct.
  • Create the new RatePlan. RatePlanCharges will be created in the background; for more information, see RatePlanCharge.

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>
 </ns1:zObjects>
</ns1:create>

3) Update the appropriate RatePlanCharge. 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>

4) Update the new amendment:

  • Set the following fields:
    • Set the ContractEffectiveDate to a date and time in the future.
    • If you have set Require Customer Acceptance of Orders? on your Admin "Default Subscription Settings" page to Yes, then you will also need to specify a customer acceptance date.
    • If you have set Require Service Activation? on your Admin "Default Subscription Settings" page to Yes, then you will also need to specify a service activation date.
    • Set the Status to Completed.
  • Update the new amendment.

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-15T12:00:00</ns2:ContractEffectiveDate>
   <ns2:Status>Completed</ns2:Status>
 </ns1:zObjects>
</ns1:update>
Retrieved from "http://apidocs.developer.zuora.com/index.php/Updating_a_Product"