Knowledge Center

Knowledge Center > Commerce > Zuora for Salesforce Development Resources > Order Builder > Order Builder Reference > zsubscribe Method

zsubscribe Method

Overview

This article describes the Order Builder zsubscribe() method. The zsubscribe() method uses the Zuora subscribe() method to create a subscription.

Syntax

List<SubscribeResult> zsubscribe(List<SubscribeRequest> sub_reqs)

Input Parameters

The zsubscribe() method takes the following input parameter.

Parameter Type Description
sub_request List<SubscribeRequest> A list of the SubscribeRequest objects

SubscribeRequest

The SubscribeRequest is used to provide the parameter values for the subscribe() call. It contains the following properties.

Property Type Description
BillToContact zObject

The contact associated with this account in the Account's BillToId field.

This field is required only if the account does not exist.

PaymentMethod zObject

The payment details for the account. The account will be updated with this payment as the default payment method.

Use this field if you are associating an electronic payment method with the account. A payment gateway must be enabled.

SoldToContact zObject Normally the same as BillToContact, though it can be different. If you do not specify SoldToContact, it defaults to the information in BillToContact.
Options SubscribeOptions

Specifies parameters related to invoicing - whether to immediately generate an invoice and collect payment, and whether the invoice should cover all subscriptions or just this new subscription. In addition, starting with WSDL 47.1, this object can also specify an invoice target date.

Sdata SubscriptionData The information on the contract dates and terms.
previewOptions PreviewOptions Specify true to call subscribe() with the preview mode. After that is completed, the call system will roll back the subscription and return only the temporary invoice data. Specfiy false to call subscribe() without the preview mode.
zAccount zObject The Account object containing the information for this particular subscription. It has all the information needed to create an account for a subscription. If you are creating the account with the subscribe() call, you need to complete all required fields.

SubscribeOptions

The SubscribeOptions is used to provide the parameter values for subscription options for the  subscribe() call. It contains the following properties.

Property Type Description
GenerateInvoice Boolean Specifies whether an invoice is to be generated when the subscription is created.
ProcessPayments Boolean

Use this when you are using electronic payment types.

If GenerateInvoice is true, specifies whether payment should be applied when the subscription is created.

If the account's AutoPay flag is true and GenerateInvoice is true and ProcessPayments is true, then the payment is created for the invoice balance and charged.

SubscribeInvoiceProcessingOptions SubscribeInvoiceProcessingOptions If GenerateInvoice is true, this property contains the fields specifying how to process the invoice.

SubscribeInvoiceProcessingOptions

The SubscribeInvoiceProcessingOptions is used to determine how to process the invoice for the  subscribe() call. It contains the following properties.

Property Type Description
InvoiceTargetDate String

A dateTime value that sets the target date for the invoice. Default is the current day. (WSDL 47.1+)

A Date value that sets the target date for the invoice. Default is the current day. (WSDL 69+)

This property is available in the Versions 2.61 and later of Zuora 360.

InvoiceDate String

A dateTime value that sets the date on which to generate the invoice. (WSDL 49.0+)

A Date value that sets the date on which to generate the invoice. (WSDL 69+)

InvoiceProssingScope String

A string that specifies the scope of the requested invoice, "Account" or "Subscription".

This property is available in the Versions 2.103 and later of Zuora 360.

SubscriptionData

The SubscriptionData is used to provide the parameter values for subscription data for the subscribe() call. It contains the following properties.

Property Type Description
RatePlanData

List<zObject> 

A list of one or more RatePlanData objects
Subscription zObject A single Subscription

PreviewOptions

The PreviewOptions is used to provide the parameter values for subscription options for the  subscribe() call. It contains the following properties.

Property Type Description
EnablePreviewMode Boolean Specifies whether the call should create a subscription, or whether it should return a preview of the order. 
NumberOfPeriods Integer Specifies the number of periods to show in a preview.

Response

The zsubscribe() method returns a list of zApi.SubscribeResult objects that ​provides the results for the  subscribe() call.

SubscribeResult

The zApi.SubscribeResult includes the following properties.

Property Type Description
AccountId String The system-generated Zuora ID for the created account
AccountNumber String The account number
Errors List An array of errors denoting why the subscribe request may have failed
InvoiceDatas List A wrapper for an invoice and its line items. This field is returned only when using the preview mode for subscribe().
InvoiceId String The system-generated Zuora invoice ID associated with the subscription
InvoiceNumber String An invoice number associated with the subscription
PaymentTransactionNumber String A payment transaction number associated with this subscription
SubscriptionId String An identification number for the subscription
SubscriptionNumber String A number for the subscription
Success Boolean Indicates whether the subscribe request succeeded (true) or did not succeed (false).

Exceptions

The zsubscribe() method uses the following exception classes to catch the exception when an error occurs during the  subscribe() call:

  • zAPIException
  • zForceException
  • zRemoteException

Previewing an Invoice

Using the PreviewOptions object, you can preview a subscription to see the invoice charges that will be generated by the subscription.

To preview an invoice:

  1. Populate PreviewOptions in the SubscribeRequest object.
    • Set EnablePreviewMode to true.
    • Set NumberOfPeriods to the number of billing periods to include in the preview invoice. You must specify a positive value.
  2. Populate the rest of the fields in the SubscribeRequst object, such as the appropriate product rate plan and charge data.
  3. Call zsubscribe() with the above SubscribeRequest object.
  4. Zuora will return the InvoiceData in Zuora.zApi.SubscribeResult, which contains the invoice and resulting invoice items. 

​Sample Code for Invoice Preview

Download the sample code from Githubsee the sample code that demonstrates how to use the preview feature with an existing account and a product rate plan that has two charges: a one-time charge and a monthly recurring charge. 

Sample Code

// zApiInstance should be instantiated and the login() method must
// have been invoked prior to invoking any other method on the
// object

try {
//account
Zuora.zObject acc = new Zuora.zObject('Account');
acc.setValue('Name', 'for subscribe - Account Name');
acc.setValue('Currency','USD');
acc.setValue('BillCycleDay',1);
acc.setValue('PaymentTerm','Net 30');
acc.setValue('Batch','Batch1');

//bill to contact
Zuora.zObject billToContact = new Zuora.zObject('Contact');
billToContact.setValue('FirstName','Jim');
billToContact.setValue('LastName','Green');
billToContact.setValue('WorkEmail', 'billto@zuora.com');
billToContact.setValue('Country','US');
billToContact.setValue('State','CA');

//sold to contact
Zuora.zObject soldToContact = new Zuora.zObject('Contact');
soldToContact.setValue('FirstName', 'Kate');
soldToContact.setValue('LastName', 'Green');
soldToContact.setValue('WorkEmail', 'soldto@zuora.com');
soldToContact.setValue('Country', 'US');
soldToContact.setValue('State','CA');

//payment method
Zuora.zObject pm = new Zuora.zObject('PaymentMethod');
pm.setValue('Type','Credit Card');
pm.setValue('CreditCardType', 'Visa');
pm.setValue('CreditCardNumber', '4111111111111111');
pm.setValue('CreditCardExpirationYear', '2011');
pm.setValue('CreditCardExpirationMonth', '03');
pm.setValue('CreditCardHolderName', 'Firstly Lastly');

//RatePlanCharge
Zuora.zObject rpc = new Zuora.zObject('RatePlanCharge');
rpc.setValue('ProductRatePlanChargeId', '4028e6962f001d02012f0aa37bc60dbb');
rpc.setValue('Quantity', 50.00);

Zuora.zObject rpcd = new Zuora.zObject('RatePlanChargeData');
rpcd.setValue('RatePlanCharge', rpc);

Zuora.zObject rp = new Zuora.zObject('RatePlan');
rp.setValue('ProductRatePlanId', '4028e6962f001d02012f0aa290a50c7b');

Zuora.zObject rpd = new Zuora.zObject('RatePlanData');
rpd.setValue('RatePlan', rp);
rpd.setValue('RatePlanChargeData', new List<Zuora.zObject>{rpcd});

//subscription
Zuora.zObject sub = new Zuora.zObject('Subscription');
sub.setValue('Name', 'subscription - SubscriptionName');
sub.setValue('ContractEffectiveDate', '2011-04-01T02:47:06');
sub.setValue('InitialTerm', 12);
sub.setValue('RenewalTerm', 12);

//subscription data
Zuora.zApi.SubscriptionData sd = new Zuora.zApi.SubscriptionData();
sd.Subscription = sub;
sd.RatePlanData = new List<Zuora.zObject> {rpd};

//subscription options
Zuora.zApi.SubscribeOptions so= new Zuora.zApi.SubscribeOptions();
so.GenerateInvoice = true;
so.ProcessPayments = false;

//Preview options
Zuora.zApi.PreviewOptions previewOpt = new Zuora.zApi.PreviewOptions();
previewOpt.EnablePreviewMode = true;
previewOpt.NumberOfPeriods = numOfPeriods;

//subscribe request
Zuora.zApi.SubscribeRequest subsRequest = new
Zuora.zApi.SubscribeRequest();

subsRequest.ZAccount = acc;
subsRequest.BillToContact = billToContact;
subsRequest.SoldToContact = soldToContact;
subsRequest.SubscribeOptions = so;
subsRequest.SubscriptionData = sd;
subsRequest.PaymentMethod = pm;

subsRequest.PreviewOptions = previewOpt;

List<Zuora.zApi.SubscribeRequest> subsRequestLists = new
List<Zuora.zApi.SubscribeRequest>{subsRequest};

List<Zuora.zApi.SubscribeResult> subscribeResults =
zApiInstance.zsubscribe(subsRequestLists);

for (Zuora.zApi.SubscribeResult result : subscribeResults) {
if (result.Success) {
//Handle with the invoice data returned by previewing subscriptions
  if (result.InvoiceDatas != null) {
    for (Zuora.zObject invData: result.InvoiceDatas) {
      //in Preview mode, handle with the invoice data
      Zuora.zObject invoice = (Zuora.zObject) invData.getValue( 'Invoice' );
      Decimal amount = ( Decimal ) invData.getValue( 'Amount' );
      List<Object> invoiceItems = invData.getArrayValue( 'InvoiceItem' );
      if( invoiceItems != null ){
        for( Object invoiceItem : invoiceItems ){
          Zuora.zObject zInvoiceItem = ( Zuora.zObject ) invoiceItem;
          //zInvoiceItem.getValue( 'ChargeAmount' )
          //zInvoiceItem.getValue( 'ChargeDate' );
        }
      }
    }
  }
} else {
//failure
//get the errors
Zuora.zObject[] errors = result.errors;
for (Zuora.zObject error : errors) {
String errorCode = (String)error.getValue('Code');
String message = (String)error.getValue('Message');
//more code here...
}
}
}
} catch (Zuora.zRemoteException ex) {
if ('INVALID_FIELD' == ex.code) {
// An invalid field was specified
//more code here...
} else {
//more code here...
}
} catch (Zuora.zAPIException ex) {
ex.getMessage();
//more code here...
} catch (Zuora.zForceException ex) {
//more code here...
}
Last modified
16:54, 2 Jun 2016

Tags

Classifications

(not set)