Skip to main content

Remove a Product (Amendment)

Zuora

Remove a Product (Amendment)

  1. Last updated
  2. Save as PDF

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

Remove a Product from a Subscription (API version 29.0+)

In version 29.0 and greater, you can use the amend() call to create amendments. 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 RemoveProduct.
    • Specify a name for the amendment.
    • Specify the Subscription's ID.
    • Specify the ID of the RatePlan to remove within the RatePlanData object.
    • Set ContractEffectiveDate (and ServiceActivation and CustomerAcceptance, if applicable).
  • 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

    <api:amend>
     <api:requests>
        <api:Amendments>

<!-- Specify basic amendment metadata and dates --> 
          <obj:AutoRenew>true</obj:AutoRenew>
           <obj:ContractEffectiveDate>2010-01-01</obj:ContractEffectiveDate>
           <obj:CustomerAcceptanceDate>2010-01-01</obj:CustomerAcceptanceDate>
           <obj:Description>Removing a product</obj:Description>
           <obj:EffectiveDate>2010-01-01</obj:EffectiveDate>
           <obj:Name>Removing a product</obj:Name>

<!-- Specify the Id of the RatePlan that you wish to remove from the subscription. Specify this in the AmendmentSubscriptionRatePlanId field -->
           <obj:RatePlanData>
              <api:RatePlan>
                 <obj:AmendmentSubscriptionRatePlanId>402892c42ce80787012ce80ea2310019
                 </obj:AmendmentSubscriptionRatePlanId>
              </api:RatePlan>
           </obj:RatePlanData>
           <obj:ServiceActivationDate>2010-01-01</obj:ServiceActivationDate>
           <obj:Status>Completed</obj:Status>
           <obj:SubscriptionId>402892c42ce80787012ce80ea1aa0014</obj:SubscriptionId>

<!-- Set Type to RemoveProduct -->
           <obj:Type>RemoveProduct</obj:Type>
        </api:Amendments>
        <api:AmendOptions>
           <api:GenerateInvoice>false</api:GenerateInvoice>
           <api:ProcessPayments>false</api:ProcessPayments>
        </api:AmendOptions>
        <api:PreviewOptions>
           <api:EnablePreviewMode>true</api:EnablePreviewMode>
        </api:PreviewOptions>
     </api:requests>
  </api:amend>

Remove a Product from 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 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 RemoveProduct.
  • Specify a name for the amendment.
  • Specify the Subscription's ID.
  • Set ContractEffectiveDate (and ServiceActivation and CustomerAcceptance, if applicable).
  • Specify the ID of the RatePlan to remove within the RatePlanData object.
  • 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_amend1279686293769</ns2:Name>
      <ns2:RatePlanData>
           <ns1:RatePlan xsi:type="ns2:RatePlan">
              <ns2:AmendmentSubscriptionRatePlanId>402892ca29f33da70129f33f348f00a8
              </ns2:AmendmentSubscriptionRatePlanId>
           </ns1:RatePlan>
      </ns2:RatePlanData>
      <ns2:ServiceActivationDate>2010-07-21</ns2:ServiceActivationDate>
      <ns2:SubscriptionId>402892ca29f33da70129f33f35fb00ac</ns2:SubscriptionId>
      <ns2:Type>RemoveProduct</ns2:Type>
  </ns1:zObjects>
</ns1:create>

Remove a Product from a Subscription (API versions 24.0 and earlier)

To remove a product from 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 RemoveProduct.
  • Set the EffectiveDate. This should correspond to the value of ContractEffectiveDate.
  • Specify a name for the amendment.
  • 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> 
  <ns1:zObjects xsi:type="ns2:Amendment">   
    <ns2:EffectiveDate>2009-08-01</ns2:EffectiveDate>   
    <ns2:Name>Remove a Product</ns2:Name>   
    <ns2:Status>Draft</ns2:Status>   
    <ns2:SubscriptionId>4028e69922c95b270122cd80a82f30c0</ns2:SubscriptionId>   
    <ns2:Type>RemoveProduct</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 RemoveProduct.
  • Set the AmendmentSubscriptionRatePlanId 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>4028e69922ece21e0122f110b43332f5</ns2:AmendmentId>   
    <ns2:AmendmentSubscriptionRatePlanId>4028e69922c95b270122cd80a8d830db
    </ns2:AmendmentSubscriptionRatePlanId>
    <ns2:AmendmentType>RemoveProduct</ns2:AmendmentType> 
  </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>
 <ns1:zObjects xsi:type="ns2:Amendment">
   <ns2:Id>4028e69922ece21e0122f110b43332f5</ns2:Id>
   <ns2:ContractEffectiveDate>2009-08-01</ns2:ContractEffectiveDate>
   <ns2:Status>Completed</ns2:Status> </ns1:zObjects>
</ns1:update>

Remove a Product with a Future-dated Remove (WSDL version 74.0+) 

In WSDL 74.0 and later, use the amend() call to create RemoveProduct amendments even when future-dated RemoveProduct amendments already exist on the subscription. You must specify the future-dated removed rate plan in the amend() call. By default, rate plans that were removed by an amendment with the Remove Product Amendment type, are not returned by queries. To return rate plans that were removed by an amendment, add AmendmentType != null in the where clause conditions. See Querying for Removed RatePlans for more information.

With the amend() call, pass the following information:

  • Amendment  object and the following fields:
    • Set the Type to RemoveProduct.
    • Specify a name for the amendment.
    • Specify the Subscription ID.
    • Specify the ID of the RatePlan to remove within the RatePlanData object.
    • Set ContractEffectiveDate (and ServiceActivation and CustomerAcceptance, if applicable). 
  • 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

    <api:amend>
     <api:requests>
        <api:Amendments>

<!-- Specify basic amendment metadata and dates --> 
          <obj:AutoRenew>true</obj:AutoRenew>
           <obj:ContractEffectiveDate>2020-03-01</obj:ContractEffectiveDate>
           <obj:CustomerAcceptanceDate>2020-03-01</obj:CustomerAcceptanceDate>
           <obj:ServiceActivationDate>2020-03-01</obj:ServiceActivationDate>
           <obj:Description>Removing a product</obj:Description>
           <obj:Name>Removing a product</obj:Name>

<!-- Specify the Id of the RatePlan that you wish to remove from the subscription. Specify this in the AmendmentSubscriptionRatePlanId field -->
           <obj:RatePlanData>
              <api:RatePlan>
                 <obj:AmendmentSubscriptionRatePlanId>402892c42ce80787012ce80ea2310019
                 </obj:AmendmentSubscriptionRatePlanId>
              </api:RatePlan>
           </obj:RatePlanData>           
           <obj:Status>Completed</obj:Status>
           <obj:SubscriptionId>402892c42ce80787012ce80ea1aa0014</obj:SubscriptionId>

<!-- Set Type to RemoveProduct -->
           <obj:Type>RemoveProduct</obj:Type>
        </api:Amendments>
        <api:AmendOptions>
           <api:GenerateInvoice>false</api:GenerateInvoice>
           <api:ProcessPayments>false</api:ProcessPayments>
        </api:AmendOptions>
        <api:PreviewOptions>
           <api:EnablePreviewMode>true</api:EnablePreviewMode>
        </api:PreviewOptions>
     </api:requests>
  </api:amend>