Skip to main content

zQuoteUtil.sendToZBilling Method

Zuora

zQuoteUtil.sendToZBilling Method

This article describes the sendToZBilling method that was re-implemented and available in version 5.6 or later of Zuora Quotes.

sendToZBilling Method

The sendToZBilling method of the zQuoteUtil global class collects, validates, and sends one or more quotes to Zuora Billing.

Requirements

To use the sendToZBilling method, you must configure the following:

  • In the Zuora application: 
  • In your Salesforce org:
    • Set the API URL to use WSDL version 42 or higher. For example, https://www.zuora.com/apps/services/a/42.0.
    • Users must be assigned Read, Create, Edit, and Delete object permissions on the Quote Processing Data custom object to be able to use the sendToZBilling method.
    • Users must have access to the following classes:
      • AmendmentBuilder
      • QuoteProcessingDataTriggerManager
      • QuoteToBillingData
      • QuoteToBillingHandler
      • RestHelper
      • RestRequest
      • SubscriptionBuilder

To add permissions to the Quote Processing Data object:

  1. Navigate to Setup > Administration Setup > Manage Users > Profiles.
  2. Select the user profile, then click Edit.
  3. In the Custom Object Permissions section, select Read, Create, Edit, and Delete for Quote Processing Data.
  4. Click Save.

To add permissions to these classes:

  1. Navigate to Setup > Administration Setup > Manage Users > Profiles and click the user profile name.
  2. In the Enabled Apex Classes Access section, click Edit.
  3. Add the following classes to the Enabled Apex Classes column:
    • AmendmentBuilder
    • QuoteProcessingDataTriggerManager
    • QuoteToBillingData
    • QuoteToBillingHandler
    • RestHelper
    • RestRequest
    • SubscriptionBuilder
  4. Click Save.

Error Handling

During the subscribe() call, if one of the following actions fails, the entire transaction for the particular subscription request is rolled back: 

  • Billing account creation
  • Subscription creation
  • Invoice generation
  • Payment processing

In the subscribe() call, each subscription processing action is a separate transaction.

Errors can also occur if the subscriptions, invoices, and payments are successfully created, but the write-back to the quotes fails. In this case, the billing account ID, subscription ID, invoice ID and payment ID will be written to the CSV file with the failure log in an email to the Zuora user.

Usage Limits

  • If you have a high volume of quotes, use the AsyncQuoteSubmit class to submit quotes instead of using the sendToZBilling method.
  • Requests that fall within a 30-quote limit, explained below, are processed synchronously. The requests over the 30 quotes are processed asynchronously. The 30-quote limit is defined as follows:

    Quote type

    Basis of the limit calculation

    New subscriptions

    # of quotes

    Primary quotes

    # of sub-quotes (primary quotes are not counted)

    Amendments

    # of amendments

  • There is always one invoice and one payment processed for each quote. So if multiple amendments are created for an Amendment/Renewal quote, only one invoice and one payment will be created for that quote.  
  • A maximum of three amendments is allowed in each Amendment or Renewal quote.
  • With Orders enabled, the sendToZBilling method uses only the Id values in the ZBillingQuoteRequest object and ignores other data in it. To send a list of Orders, it directly queries the Quote through OrderService to get all the needed information.

Method Signature

The signature for the sendToZBilling method is:

global static List<ZQuoteUtil.ZBillingResult> sendToZBilling
   (List<ZQuoteUtil.ZBillingQuoteCollection> zBillingQuoteCollections);

Security Considerations

DML Operations run by the sendToZBilling process will be executed in System mode. It means that any custom integration that triggers the submission process on a Quote should ensure proper validation of access rights when exposing actions to users that systematically submit quotes, as the Edit access is not specifically validated within the call.

ZQuoteUtil.ZBillingQuoteCollection

ZBillingQuoteCollection is a wrapper class that stores a list of quote requests for a particular Zuora billing account. All of the quote requests in a ZBillingQuoteCollection object will be created for the same billing account in Zuora.

This class contains the following global properties. All the properties are required.

 Property Type  Description
entityId String The Zuora Entity ID for the entity that this request is being directed to. 
quoteRequests List<ZBillingQuoteRequest>

Contains a list of quote requests. Each quote request will be used to create a subscription request, which is then sent to Zuora for processing.

sessionId String ID of this session
sfdcAccountId Id

Indicates the Salesforce Account ID to which all quotes in this ZBillingQuoteCollection belong.

This value is required when zAccountId is new. It is optional for other values of zAccountId.

zAccountId String

Indicates the Zuora Billing Account ID.

For new accounts, set this field to new. A new billing account will be created, and all of the quotes in this ZBillingQuoteCollection object will be created under this new billing account.

ZQuoteUtil.ZBillingQuoteRequest

The ZBillingQuoteRequest class stores the information required to assemble the subscription request that is sent to Zuora for processing.

This class contains the following global properties.

 Property Type  Description
applyCreditBalance Boolean Determines whether any credit balance on a customer's account is automatically applied to invoices. If no value is specified, this field defaults to false.
effectiveDate Date Specifies the start date of the quote
enableAccountAutoPay Boolean Specifies whether to enable auto pay for this account

generateInvoice  

Boolean

Specifies whether or not the invoice should be generated for this subscription. If not specified, the value of the Generate Invoice field in the Quote object will be used.

invoiceProcessingOption String

Specifies at which level the invoice will be processed, Subscription or Account.

When generateInvoice at the org or quote level is set to True, the invoiceProcessing option is set to Subscription, by default.

paymentAmount Decimal The payment amount

paymentMethodId

String

The electronic payment method ID. If you do not specify a value, the default payment method will be used to process the payments.

processPayment

Boolean

Specifies whether or not the payment for this subscription should be processed when sent to Z-Billing.

See Process Payments in Z-Billing for information about how this setting takes effect.

setNewPaymentAsDefault Boolean

Specifies whether to set the new payment method as the default.

Setting this field to true takes effect only if you are specifying an electronic payment method, as defined in Zuora, in the paymentMethodId field.

A payment gateway must be enabled and support the payment method specified in the paymentMethodId field.

sfdcQuoteId

Id

The Salesforce Quote ID.

The data passed here must be valid Salesforce record IDs.

invoiceOwnerId Id This parameter is optional and is only required if you want to set different invoice owner at Zuora.

ZQuoteUtil.ZBillingResult

The ZBillingResult class stores the SendToZBilling and previewQuotes results. 

If there are less than 30 quote requests, the SendToZBilling process will be executed synchronously. In that case, each ZBillingResult will contain the success/failure status, the ID of the Quote, and the status message for each quote.

If there are more than 30 quote requests, the SendToZBilling process will be executed asynchronously as a Zuora background job. In this case, there will be a single ZBillingResult object returned that contains the success/failure status and the status message.

If an invalid quote is passed to the sendToZBilling global method, e.g. a quote that does not contain a product, the invalid quote is caught by the pre-validation, and only the invalid quote is returned in the ZBillingResult.

The success/failure status indicates whether the request was successfully received by Zuora. 

The class includes the following properties.

 Property Type  Description
chargeMetrics List <zqu.zQuoteUtil.ChargeMetrics>

Charge level metrics previewed from Zuora.

The chargeMetrics will only be populated when using the global method zqu.QuoteManager.PreviewQuote(String quoteId).

This property is available in the 6.50 (Q2 2015) or later release of Zuora Quotes.

message String The status message of the SendToZBilling call
sfdcQuoteId Id

The ID of the quote that this result refers to.

This field will be empty when the result is returned during an asynchronous request.

success Boolean Indicates whether the call is successful.
totalInfo zQuoteUtil.TotalInfo Total, Total without Tax, Sub total, Discount, and Tax 
totalMrr Decimal Total MRR of the quote
totalTcv Decimal Total TCV of the quote
zAccountId String Account ID
zSubscriptionId String Subscription ID

ZQuoteUtil.ChargeMetrics

The ChargeMetrics class stores the charge level metrics previewed from Zuora.

This class is available as of the 6.50 (Q2 2015) or later release of Zuora Quotes.

Property Type Description
chargeNumber String The Charge Number of the Rate Plan Charge being amended (see Known Issues below)
deltaMrr Decimal

The Delta MRR value provided from the Zuora.

The delta of the total MRRs between the original subscription and the amendment. 

For renewals, this is the MRR of the new contract.

deltaTcv Decimal

The Delta TCV value provided from the Zuora.

The delta of the TCVs between the original subscription and the amendment. 

For renewals, this is the TCV of the new contract.

mrr Decimal

The MRR value provided from the Zuora.

The MRR calculates subscription recurring fees normalized to a monthly value.

sfdcQuoteRatePlanChargeId Id The SFDC Id of the corresponding zqu__QuoteRatePlanCharge__c record
tcv Decimal

The TCV value provided from the Zuora.

The TCV calculates the total recurring charges over the lifetime of a subscription.

productRatePlanId String The Zuora Id of the ProductRatePlan this charge is associated with
productRatePlanChargeId String The Zuora Id of the ProductRatePlanCharge this charge is associated with
originalRatePlanId String The Zuora Id of the RatePlan being amended (Only available for Update Product amendments)
originalId String The Zuora Id of the RatePlanCharge being amended (Only available for Update Product amendments)

Sample Code

List<String> lstQuoteIds = new List<String>{'a0t8N000000EAJEQA4','a0t8N000000EAU7QAO'};
        List<Quote__c> listQuotes = [SELECT ID,Account__c,ZuoraAccountId__c from Quote__c where ID IN :lstQuoteIds];
        zQuoteUtil.ZBillingQuoteCollection[] quotesToSend = new zQuoteUtil.ZBillingQuoteCollection[]{};
            for(Quote__c quote : listQuotes){
                zQuoteUtil.ZBillingQuoteCollection quoteCollection = new zQuoteUtil.ZBillingQuoteCollection();
                quoteCollection.sfdcAccountId = quote.Account__c;
                System.debug('Account Id ----> ' + quote.Account__c);
                quoteCollection.quoteRequests = new zQuoteUtil.ZBillingQuoteRequest[]{};
                    zQuoteUtil.ZBillingQuoteRequest request = new zQuoteUtil.ZBillingQuoteRequest();
                request.sfdcQuoteId = quote.Id;
                System.debug('Quote Id ----> ' + quote.Id);
                request.effectiveDate = Date.Today();
                quoteCollection.quoteRequests.add(request);
                quotesToSend.add(quoteCollection);
            }
        zQuoteUtil.zBillingResult[] resultOneShot = zQuoteUtil.sendToZBilling(quotesToSend);
        //System.debug('ResultSendToZuora: ' + resultOneShot);
        for(zQuoteUtil.zBillingResult res : resultOneShot){
            System.debug('Result: QuoteId = ' + res.sfdcQuoteId + ', Success = ' + res.success + ', message = ' + res.message );
        }
        

You can send multiple quotes in one request by enabling the Enable Multi-Subscription Quoting setting under Zuora Config > Advanced Quoting Configuration Settings.

If you want to cancel a subscription, use the createCancellationAmendment method to create a  QuoteAmendment__c record of type Cancellation and link it to the quote. For example, you could use the following with the sendToZBilling method to cancel a subscription:  

Id quoteId = 'a0GE0000005HRhD';
Quote__c cancelledAmendmentQuote = zQuoteUtil.createCancellationAmendment(quoteId);
// now send the quote to Z-Billin