Previewing a Subscription

Last updated
Save as PDF

Overview

Starting with version 25.0 of the SOAP API, customers can preview invoices that would be generated by the subscribe() call. If you have configured taxation rules in Z-Tax, the subscription preview will calculate the tax amounts for charges in the subscription.

Previewing an Invoice for subscribe()

To preview an invoice:

Call subscribe(), passing the appropriate product rate plan and charge data.
Populate PreviewOptions:
1. Set EnablePreviewMode to true.
2. Set NumberOfPeriods to the number of billing periods to include in the preview invoice, or
3. Set PreviewThroughTermEnd to preview the invoice through the end of a termed subscription (WSDL 51.0+).

You can only set NumberOfPeriods or PreviewThroughTermEnd, but not both.
As an alternative to NumberOfPeriods or PreviewThroughTermEnd, you can set the InvoiceTargetDate in the SubscribeOptions to preview to a specific date.
If neither NumberOfPeriods nor PreviewThroughTermEnd nor InvoiceTargetDate are specified when EnablePreviewMode=true, then 1 billing period will be previewed by default.

Zuora returns an InvoiceData node in the SubscribeResult, which contains the invoice and resulting invoice items.

To include taxation items for the corresponding invoices in the result, you must use WSDL version 120 or higher.

Request

The following is a sample subscribe() call using the preview option.

<!-- sample subscribe call for preview mode -->
<ns1:subscribe>
  <ns1:subscribes>
  <ns1:Account>
   <ns2:AccountNumber>t-1246636315.4928</ns2:AccountNumber>
   <ns2:AutoPay>false</ns2:AutoPay>
   <ns2:Batch>Batch1</ns2:Batch>
   <ns2:BillCycleDay>1</ns2:BillCycleDay>
   <ns2:Currency>USD</ns2:Currency>
   <ns2:CustomerServiceRepName>CSR Dude</ns2:CustomerServiceRepName>
   <ns2:Name>Company XYZ, Inc.</ns2:Name>
   <ns2:PaymentTerm>Due Upon Receipt</ns2:PaymentTerm>
  </ns1:Account>
  <ns1:PaymentMethod>
   <ns2:CreditCardAddress1>123 Main</ns2:CreditCardAddress1>
   <ns2:CreditCardCity>San Francisco</ns2:CreditCardCity>
   <ns2:CreditCardCountry>United States</ns2:CreditCardCountry>
   <ns2:CreditCardExpirationMonth>1</ns2:CreditCardExpirationMonth>
   <ns2:CreditCardExpirationYear>2011</ns2:CreditCardExpirationYear>
   <ns2:CreditCardHolderName>Test Name</ns2:CreditCardHolderName>
   <ns2:CreditCardNumber>5105105105105100</ns2:CreditCardNumber>
   <ns2:CreditCardPostalCode>94109</ns2:CreditCardPostalCode>
   <ns2:CreditCardState>California</ns2:CreditCardState>
   <ns2:CreditCardType>MasterCard</ns2:CreditCardType>
   <ns2:Type>CreditCard</ns2:Type>
  </ns1:PaymentMethod>
  <ns1:BillToContact>
   <ns2:Address1>123 Main</ns2:Address1>
   <ns2:Address2>APT 1</ns2:Address2>
   <ns2:City>San Francisco</ns2:City>
   <ns2:Country>United States</ns2:Country>
   <ns2:FirstName>Jon</ns2:FirstName>
   <ns2:LastName>Nordstrom</ns2:LastName>
   <ns2:PostalCode>94109</ns2:PostalCode>
   <ns2:State>California</ns2:State>
   <ns2:WorkEmail>test@email.com</ns2:WorkEmail>
   <ns2:WorkPhone>4155551212</ns2:WorkPhone>
  </ns1:BillToContact>

<!-- Preview Options - Set EnablePreviewMode to true to generate a preview invoice -->
  <ns1:PreviewOptions>
   <ns1:EnablePreviewMode>True</ns1:EnablePreviewMode>
   <ns1:NumberOfPeriods>1</ns1:NumberOfPeriods>
  </ns1:PreviewOptions>
<!-- End PreviewOptions -->

  <ns1:SubscriptionData>
   <ns1:Subscription>
    <ns2:AutoRenew>true</ns2:AutoRenew>
    <ns2:ContractAcceptanceDate>2009-07-03</ns2:ContractAcceptanceDate>
    <ns2:ContractEffectiveDate>2009-07-03</ns2:ContractEffectiveDate>
    <ns2:InitialTerm>12</ns2:InitialTerm>
    <ns2:Name>A-S00000020090703080755</ns2:Name>
    <ns2:RenewalTerm>12</ns2:RenewalTerm>
    <ns2:ServiceActivationDate>2009-07-03</ns2:ServiceActivationDate>
    <ns2:TermStartDate>2009-07-03</ns2:TermStartDate>
   </ns1:Subscription>
   <ns1:RatePlanData>
    <ns1:RatePlan>
     <ns2:ProductRatePlanId>4028e6991f863ecb011fb8b7904141a6</ns2:ProductRatePlanId>
    </ns1:RatePlan>
   </ns1:RatePlanData>
  </ns1:SubscriptionData>
</ns1:subscribes>
</ns1:subscribe>

Response

The following is an example response:

<soapenv:Body>
        <ns1:subscribeResponse xmlns:ns1="http://api.zuora.com/">
            <ns1:result>
<!-- Preview mode: no account generated-->
 
                <ns1:AccountId xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="1"/>
                <ns1:AccountNumber xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="1"/>
 
<!-- Preview mode: InvoceData wrapper is returned with invoice information -->
                <ns1:InvoiceData>
                    <ns1:Invoice xmlns:ns2="http://object.api.zuora.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:Invoice">
                        <ns2:AccountId>4028e6992b31191e012b75ae45ee1602</ns2:AccountId>
                        <ns2:Amount>500.00</ns2:Amount>
                        <ns2:AmountWithoutTax>500.00</ns2:AmountWithoutTax>
                        <ns2:TaxAmount>0.00</ns2:TaxAmount>
                    </ns1:Invoice>
                    <ns1:InvoiceItem xmlns:ns2="http://object.api.zuora.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:InvoiceItem">
                        <ns2:AccountingCode/>
                        <ns2:ChargeAmount>500.00</ns2:ChargeAmount>
                        <ns2:ChargeDate>2010-10-06T17:28:50.883-08:00</ns2:ChargeDate>
                        <ns2:ChargeDescription/>
                        <ns2:ChargeName>Setup Fee</ns2:ChargeName>
                        <ns2:ProductId>4028e6992548fa470125560f8ed1057e</ns2:ProductId>
                        <ns2:Quantity>1</ns2:Quantity>
                        <ns2:ServiceEndDate>2010-10-01</ns2:ServiceEndDate>
                        <ns2:ServiceStartDate>2010-10-01</ns2:ServiceStartDate>
                        <ns2:TaxAmount>0E-9</ns2:TaxAmount>
                        <ns2:TaxExemptAmount>0E-9</ns2:TaxExemptAmount>
                        <ns2:UnitPrice>500.000000000</ns2:UnitPrice>
                        <ns2:UOM/>
                    </ns1:InvoiceItem>
                </ns1:InvoiceData>
<!-- End InvoiceDate-->
 
 
<!-- Preview Mode: No subscription or actual invoice is generated -->
                <ns1:InvoiceId xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="1"/>
                <ns1:InvoiceNumber xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="1"/>
                <ns1:SubscriptionId xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="1"/>
                <ns1:SubscriptionNumber xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="1"/>
                <ns1:Success>true</ns1:Success>
            </ns1:result>
        </ns1:subscribeResponse>
    </soapenv:Body>