Previewing a Subscription
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:
- Set
EnablePreviewMode
totrue
. - Set
NumberOfPeriods
to the number of billing periods to include in the preview invoice, or - Set
PreviewThroughTermEnd
to preview the invoice through the end of a termed subscription (WSDL 51.0+).
- Set
- You can only set
NumberOfPeriods
orPreviewThroughTermEnd
, but not both. - As an alternative to
NumberOfPeriods
orPreviewThroughTermEnd
, you can set theInvoiceTargetDate
in theSubscribeOptions
to preview to a specific date. - If neither
NumberOfPeriods
norPreviewThroughTermEnd
norInvoiceTargetDate
are specified whenEnablePreviewMode
=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>