zamend Method
The article describes the Order Builder zamend() method. The zamend() method uses the Zuora amend() method to apply amendments to a single subscription.
Syntax
Zuora.zApi.AmendResult zamend ( List<Zuora.zApi.AmendRequest> amendRequests)
Input Parameter
The zamend() method takes the following input parameter.
| Parameter | type | Description |
|---|---|---|
| amendRequest | List<Zuora.zApi.AmendRequest> | A list of the AmendRequest object containing amendments for a single subscription. |
Only one subscription can be amended per call. Thus the method accepts only one AmendRequest, which can contain the Amendment objects up to the following:
- For WSDL versions 69+: Up to ten Amendment objects
- For WSDL versions 42.0 through 68: Up to three Amendment objects
- For WSDL versions 29.0 through 41.0: Only one Amendment object
zApi.AmendRequest
The AmendRequest object uses the following properties for the amend() call.
| Property | Type | Description |
|---|---|---|
| amendments | List<zObject> | An array of Amendment type zObjects |
| amendOptions | zApi.AmendOptions | The amendment options |
| previewOptions | zApi.PreviewOptions | The amendment preview options |
zApi.AmendOptions
The AmendOptions is used to provide the parameter values for amend options for the amend() call. It includes the following properties.
| Property | Type | Description |
|---|---|---|
| generateInvoice | Boolean | Set to true if you want Zuora to generate an invoice after the amend()call to immediately bill the customer for the new product. |
| processPayments | Boolean | Set to true if you want Zuora to collect payment against the invoice. Note that the Account must have the AutoPay setting set to true. |
| invoiceProcessingOptions | zApi.InvoiceProcessingOptions | Specifies whether, and how, an invoice should be generated for a new amendment. |
zApi.InvoiceProcessingOptions
The InvoiceProcessingOptions is used to provide the parameter values for the invoice processing options for the amend() call. It includes the following properties.
| Property | Type | Description |
|---|---|---|
| invoiceTargetDate | String | Specifies a date for when an invoice should be generated. |
| invoiceDate | String | Specifies the date on which to generate the invoice. (WSDL 49.0+). |
zApi.PreviewOptions
zApi.PreviewOptions is used to provide the parameter values for the preview options for the amend() call. It includes the following properties.
| Property | Type | Description |
|---|---|---|
| enablePreviewMode | Boolean | Specifies whether the call should create a subscription/amendment, or whether it should return a preview of the order. |
| numberOfPeriods | Integer | Specifies the number of periods to show in a preview. |
Response
The zamend() method returns a single Zuora.zApi.AmendResult object that provides the results for the amend() call.
zApi.AmendResult
The Zuora.zApi.AmendResult has the following properties.
| Property | Type | Description |
|---|---|---|
| amendmentIds | String[] | The ID of the Amendment objects. |
| errors | zObject[] | An array of errors indicating why the amend request may have failed. |
| invoiceDatas | zObject[] | A wrapper for an invoice and its line items. This field is returned only when settingPreviewMode for amend() to true. |
| InvoiceId | String | The system-generated Zuora invoice ID for the created Account. |
| paymentTransactionNumber | String | A payment transaction number associated with this amendment. |
| SubscriptionId | String | Id of the subscription. |
| success | Boolean | Indicates whether the amend request succeeded (true) or did not succeed (false). |
Exceptions
The zamend() method uses the following exception classes to catch an exception when an error occurs in the call:
zAPIExceptionzForceExceptionzRemoteException
Sample Code
See the sample code at Github that demonstrates using the Order Builder zApi.zAmend() call to implement the following use cases:
- Create an "Add New Product" amendment. Add a product rate plan that has two charges: a one-time charge and a monthly recurring charge.
- Preview the invoice for the next two months.