Update a Product (Amendment)
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 totrue
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 tofalse
.- 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
toUpdateProduct
. - Specify a name for the amendment.
- Specify the Subscription's ID.
- Set
ContractEffectiveDate
- Also set
ServiceActivation
andCustomerAcceptance
, if applicable.
- Also set
- 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:
- Create a new amendment.
- Create a new RatePlan.
- Update the RatePlanCharge.
- 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>