Adding a Product

From API Documentation

Jump to: navigation, search

To add a product to a subscription, use the NewProduct Amendment.

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 add a product to a subscription (version 29.0+)

Call amend() passing it

  • 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.
  • AmendOptions is used to specify the following three items:
    • GenerateInvoice - Set to true if you want Zuora to generate an invoice after the amend() call to immediately bill the customer for the new product.
    • ProcessPayment - Set to true if you want Zuora to collect payment against the invoice. Please note that the Account must have AutoPay set to true.
    • InvoiceProcessingOptions - Set the InvoiceTargetDate to the date you want Zuora to calculate charges for the invoice. Only used when GenerateInvoice is set to true. If omitted 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 (amount, charges, etc) after the amendment, without creating the amendment. Helpful for calculating prorations, and complex charges.

Example SOAP/XML of the call: 

<ns1:amend>
 <ns1:requests>
  <ns1:Amendments>
<!--Specify the basic amendment information, such as trigger dates, name etc.  -->
       <ns2:ContractEffectiveDate>2010-01-01T20:44:54.718+05:30</ns2:ContractEffectiveDate>
       <ns2:CustomerAcceptanceDate>2010-01-01T20:44:54.718+05:30</ns2:CustomerAcceptanceDate>
       <ns2:Description>testing description - aaaaaaaaaaaaa</ns2:Description>
       <ns2:EffectiveDate>2010-01-01T20:44:54.718+05:30</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>2010-01-01T20:44:54.718+05:30</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>


To add a product to a subscription (version 25.0-28.0)

Create a new amendment. NOTE: This call can be used to create multiple amendments for a single subscription in one call.

  • Set 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.
    • Create the amendment. Please make sure to use the 'useSingleTransaction' CallOption to execute this call successfully.

Example SOAP/XML of the call: 

<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>2010-07-21T12:13:44.589+08:00</ns2:ContractEffectiveDate>
   <ns2:CustomerAcceptanceDate>2010-07-21T12:13:44.589+08:00</ns2:CustomerAcceptanceDate>
   <ns2:EffectiveDate>2010-07-21T12:13:44.589+08:00</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>2010-07-21T12:13:44.589+08:00</ns2:ServiceActivationDate>
   <ns2:SubscriptionId>402892ca29f3335a0129f334fefe00ac</ns2:SubscriptionId>
   <ns2:Type>NewProduct</ns2:Type>
  </ns1:zObjects>
</ns1:create>


To add a product to a subscription (version 24.0-)

1) Create a new Amendment.

  • Set the following fields:
    • Set the Type to NewProduct.
    • Specify the Subscription's Id.
    • Set the Status to Draft. Setting Status to Draft is important because the Amendment shouldn't be complete until the new product is added.
  • Create the new amendment, see the create() API call.

The SOAP call envelope payload should look like this: 

<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>2008-11-20T12:00:00-08:00</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>

2) Now create a new RatePlan.

  • Set the following fields:
    • Set the new AmendmentId to the new Amendment Id returned in step 1.
    • Set the AmendmentType to NewProduct.
    • Set the ProductRatePlanId to the Id returned from querying the Zuora Product Catalog for ProductRatePlan objects.
  • Create the new RatePlan.

NOTE: RatePlanCharges and RatePlanChargeTiers will be created in the background; for more information, see RatePlanCharge.

The SOAP call envelope payload should look like this: 

<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>

NOTE: This RatePlan will assume the default pricing and quantity from the product catalog. If the price or quantity needs to be changed, the corresponding RatePlanCharge in this RatePlan will need to be queried and updated.

3) Update the new Amendment, and set the Status to Completed.

  • Set the following fields:
    • Set the Id field to the Amendment Id returned in step 1.
    • Set the ContractEffectiveDate to a date and time in the future.
    • If Require Customer Acceptance of Orders? is set on the Z-Billing Admin "Default Subscription Settings" page to Yes, then ContractAcceptanceDate will also need to be specified.
    • If Require Service Activation? is set on the Z-Billing Admin "Default Subscription Settings" page to Yes, then ServiceActivationDate will also need to be specified.
    • Set the Status to Completed.
  • Update the new amendment.

The SOAP call envelope payload should look like this: 

<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>2008-11-20T12:00:00-08:00</ns2:ContractEffectiveDate>
   <ns2:CustomerAcceptanceDate>2008-11-22T12:00:00-08:00</ns2:CustomerAcceptanceDate>
   <ns2:Description>Test changing</ns2:Description>
   <ns2:ServiceActivationDate>2008-11-22T12:00:00-08:00</ns2:ServiceActivationDate>
   <ns2:Status>Completed</ns2:Status>
 </ns1:zObjects>
</ns1:update>
Retrieved from "http://apidocs.developer.zuora.com/index.php/Adding_a_Product"