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