Skip to main content

amend()

Zuora

amend()

  1. Last updated
  2. Save as PDF

Use the amend call to change a subscription, such as upgrading the subscription. This SOAP API reference includes syntax, call wrappers and container descriptions, requirements, and examples.

Usage

  • Supported objects: Amendment
  • Version availability: WSDL 28.0+
  • Asynchronous process: no

Limits

Objects per Call

The number of amendments supported in a single amend call are:

  • For WSDL versions 69+: Up to ten amendments
  • For WSDL versions 42.0 through 68: Up to three amendments
  • For WSDL versions 29.0 through 41.0: Only one amendment

Errors

If one of your Amendment objects fails in a single amend() call, then the entire call fails.

Fields

The following fields are always required for this call:

Amendment.Type

Syntax and Arguments

amend call diagram for syntax and arguments

The amend() call uses the following items:

Call wrappers

Every amend() request requires an AmendRequest wrapper. Every amend() call responds with an AmendResult wrapper.

Request: AmendRequest

Pass an AmendRequest wrapper with the amend() call. AmendRequest is a wrapper that includes an object and containers. 

AmendRequest Objects and Containers

Name Description

Amendment (object)

required

 Make changes on a subscription.

AmendOptions (container)

required

 Specify billing options.

PreviewOptions (container)

optional

 Preview an amendment before committing its changes to a subscription. 

ExternalPaymentOptions (container)

optional

 Create or change a subscription and mark its invoice as already paid. 

Response: AmendResult

The AmendResult wrapper is the response for the amend() call.

AmendResult Fields

Name Description

AmendmentId

The ID of the associated Amendment object. There can be as many as three AmendmentId values.

Type: zns:ID

Character limit:

Version notes: WSDL 28.0 - 41.0 supports only one AmendmentId value. WSDL 42.0+ supports three AmendmentId values.

Values: valid Amendment object IDs

Error

An array of errors that indicate why the amend() call failed.

Type: zns:Error

Character limit:

Version notes: WSDL 28.0+

Values: 

InvoiceData

A wrapper for the associated invoice preview. This field is only returned when the EnablePreviewMode field value is set to true.

Type: zns:InvoiceData

Character limit:

Version notes: WSDL 28.0+

Values: 

InvoiceId

The ID of the associated Invoice object.

Type: zns:ID

Character limit:

Version notes: WSDL 28.0+

Values: 

PaymentTransactionNumber

The payment transaction number associated with this amendment.

Type: string

Character limit:

Version notes: WSDL 28.0+

Values: 

SubscriptionId

The ID of the new Subscription object that is created when amending a subscription; the old subscription is cancelled and kept on file with its original ID.

Type: zns:ID

Character limit:

Version notes: WSDL 46.0+

Allowable values: valid Subscription object IDs

Success

Indicates if the amend() call succeeded or failed. The value is true if the call succeeded.

Type: boolean

Character limit:

Version notes: WSDL 28.0+

Values: true, false

TotalDeltaMrr

Total Monthly Recurring Revenue (MRR) for this subscription (WSDL 48+)

Type: decimal

Character limit:

Version notes: WSDL 48.0+

Values:

TotalContractedValue

Total Contract Value (TCV) of this subscription (WSDL 48+)

Type: decimal

Character limit:

Version notes: WSDL 48.0+

Values:

Containers

Containers go inside an AmendRequest wrapper.

AmendOptions

Use the AmendOptions container to specify billing options, such as invoice generation and when to process payments.

AmendOptions Fields

Name Required? Description

ApplyCreditBalance

optional

Determines whether any credit balance on a customer's account is automatically applied to invoices. If no value is specified then this field defaults to false.

Type: boolean

Version notes: WSDL 54.0+

Values: true, false 

GenerateInvoice

optional

Determines whether to generate an invoice to immediately bill the customer for a new product or changes of Terms And Conditions. As a best practice, set this value to true to prevent any errors that might occur if the account has a balance.

Type: boolean

Version notes: WSDL 28.0+

System-generated: no

Values: true (default), false 

Usage Notes:

  • Even if you do not include this field in the amend() call, Zuora still parses this field with the default value, true, when processing the amend() call. If you do not want to generate the invoice after creating the New Product or Term And Condition amendment, set the value of this field to false in the request. 
  • If EnablePreviewMode=true is specified in the PreviewOptions container, then preview mode will be enabled and an invoice will not be generated, regardless of whether GenerateInvoice is specified as true or false.

InvoiceProcessingOptions

optional

Contains an attribute for generating invoices. This field doesn't take any values itself.

Type: container

Version notes: WSDL 28.0+

System-generatedl: no

Values: no values -- use it to nest an attribute

ProcessPayments

optional

Determines whether to collect payment against the invoice generated by the amend() call. 

Type: boolean

Version notes: WSDL 28.0+

System-generated: no

Values: true, false

Usage Notes:

Even if you do not include this field in the amend() call, Zuora still parses this field with the default value, true, when processing the amend() call. If you do not want to collect payment against the generated invoice after creating the New Product or Term And Condition amendment, set the value of this field to false in the request. 

Additional Field Detail

InvoiceProcessingOptions

InvoiceProcessingOptions contains a field related to generating invoices. You only need to use the InvoiceProcessingOptions container if you both want to generate invoices with the amend() call and you want to specify a target date. If you don't want to do both of these actions, then skip the InvoiceProcessingOptions container.

If you decide to generate invoices but don't include this container and its attribute, then Zuora uses the current date as the target date.

You can specify values for the following InvoiceProcessingOptions field:

Name Required? Description
InvoiceDate optional

The invoice date.

Type: 

  • date supported as of WSDL version 69+
  • dateTime supported through WSDL version 68

Version notes: WSDL 28.0+

Values: a valid date and time value
InvoiceTargetDate optional

The date that determines which charges to bill. Charges prior to this date or on this date are billed on the resulting invoices. 

Type: 

  • date supported as of WSDL version 69+
  • dateTime supported through WSDL version 68

Version notes: WSDL 28.0+

Values: a valid date and time value

Process Payments

Determines whether to collect payment against the invoice. To set the value to true, the Account.Autopay field must also be set to true. If the Account.Autopay value is false, the invoice has a balance, and you don't specify a value for the ProcessPayments field, then Zuora returns the following error: Cannot process payment.

PreviewOptions

Use the PreviewOptions container to preview an amendment before committing its changes to a subscription. You can use a preview to provide a quote of the new charges to a customer before the customer commits to the amended subscription. For example, send an amend() call with an Amendment object that removes an existing rate plan, another Amendment object that adds a new rate plan, and turn on the preview options.

  • You must use WSDL version 42.0+ to send multiple Amendment objects with a single amend() call. You can't preview changes before committing them if you are using an older WSDL version. 
  • You must use WSDL version 120.0 or higher to include taxation items for the corresponding invoices in the preview result. 

PreviewOptions Fields

Name Required? Description
EnablePreviewMode optional

Determines whether the call creates an amendment or displays a preview of the change.

Type: boolean

Character limit:

Version notes: WSDL 28.0+

System-generated: no

Values: true, false 

Usage Notes:

If either NumberOfPeriods, PreviewThroughTermEnd, or InvoiceTargetDate are not specified when EnablePreviewMode=true, the preview target date will be today (the date when the preview request is submitted).
NumberOfPeriods optional

Indicates the number of invoice periods to show in a preview.

Type: integer

Character limit:

Version notes: WSDL 28.0+

System-generated: no

Values: a positive integer greater than 0

Usage Notes:

  • PreviewOptions must exist and EnablePreviewMode=true must be set.

  • This option cannot be used in combination with the PreviewThroughTermEnd field.

  • If an InvoiceTargetDate field is specified in the InvoiceProcessingOptions, then this value will be ignored.
PreviewThroughTermEnd optional Request to preview the charge through the end of the subscription term.

Type: boolean

Character limit: N/A

Version notes: WSDL 51.0+

System-generated: no

Values: true, false 

Usage Notes:

  • PreviewOptions must exist and EnablePreviewMode=true must be set. 

    This option is valid for Termed subscriptions only, not Evergreen subscriptions.

  • This option cannot be used in combination with the NumberofPeriods.

  • If an InvoiceTargetDate field is specified in the invoiceProcessingOptions, then this value is ignored.
PreviewType optional

The type of preview you will receive from a preview request.

Type: string

Values: 

  • InvoiceItem
  • ChargeMetrics
  • InvoiceItemChargeMetrics

Usage Notes:

  • InvoiceItem is the default. A preview request will return an invoice item preview.
  • A ChargeMetrics request will return a charge metrics preview
  • An InvoiceItemChargeMetrics request will return an invoice item and charge metrics of that item.
IncludeExistingDraftInvoiceItems optional

Specifies whether to include draft invoice items in amendment previews.

Type: boolean

Character limit: N/A

Version notes: WSDL 72.0+

System-generated: No

Values: 

  • true (default). Includes draft invoice items in amendment previews. 
  • false. Excludes draft invoice items in amendment previews.

Usage Notes: This field is only applicable if the EnablePreviewMode field is set to true. 

ExternalPaymentOptions

Use the ExternalPaymentOptions container to create or change a subscription and mark its invoice as already paid. You're essentially linking a payment that you've already received to an invoice. This feature is equivalent to using the web-based UI to process a manual payment.

An external payment occurs outside Zuora but must be recorded in Zuora to ensure that account balances and invoice balances are appropriately updated. An external payment can be any type, such as a credit card, debit card, ACH, check, wire transfer, bank transfer, Paypal, CCRef, and cash, but it's usually cash or a check.

ExternalPaymentOptions Fields

Name Required? Description
Amount required

The amount of the payment. The value must be equal to the invoice's total balance.

Type: decimal

Character limit:

Version notes: WSDL 42.0+

System-generated: no

Values:a positive decimal value 

Partial external payments and external overpayments are not supported. The Amount field value must equal the invoice's total balance. Otherwise the entire call will fail.
EffectiveDate required

The date when the external payment was made. If you leave this field value empty, then Zuora provides the current system date and time.

Type: 

  • date supported as of WSDL version 69+
  • dateTime supported through WSDL version 68

Character limit: 29

Version notes: WSDL 42.0+

System-generated: yes, if null

Values: a valid date and time value
GatewayOrderId optional

The ID of the gateway order, which is the merchant-specified natural key value. 

Type: string

Character limit: 255

Version notes: WSDL 42.0+

System-generated: no

Values: a string of 255 characters or fewer
PaymentMethodId required

The ID of the payment method. A payment method is the form of payment that a customer used for the external payment. The ID is the unique identifier for that particular payment method.

Type: zns:ID

Character limit: 32

Version notes: WSDL 42.0+

System-generated: no

Values:a valid payment method ID
ReferenceId optional

The ID returned by the bank or gateway that created the payment.

Type: string

Character limit: 60

Version notes: WSDL 42.0+

System-generated: no

Values:a string of 60 characters or fewer

Extra Details

EffectiveDate

While similarly named fields in other areas of the Zuora API refer to when the item takes effect, the EffectiveDate field in the ExternalPaymentOptions container is the date that the payment was made. For example, the customer makes a payment on 01 October 2012. You create the record of the payment on 07 October 2012. The EffectiveDate value is 01 October, not 07 October because that's when the money moved from the customer's account to the merchant's account. The CreatedDate field value is the value that reflects the 01 October date.

GatewayOrderId

The ID of the gateway order, which is the merchant-specified natural key value. A gateway is an online service provider that connects a virtual terminal to a payment processor.

The source of this ID varies by merchant. Some merchants use their shopping cart order IDs, and others use something different. Merchants use this ID to track transactions in their eCommerce systems.

Gateways can do a uniqueness check on this value as a means to prevent multiple submissions of the same transaction, such as when a customer clicks the Pay button twice during a single checkout process, inadvertently sending two identical orders to Zuora and the gateway.  A uniqueness check prevents DuplicateOrderID exceptions.

Examples

This example call amends a suscription with the following information:

  • The following dates are all 01 January 2012:
    • Contract effective
    • Customer acceptance
    • Effective
    • Service activation
  • Description: renewing at customer request
  • Name: renewal
  • Status: Completed
  • Subscription ID: 402892c42ce80787012ce80ea1aa0014
  • Type: Renewal
  • The AmendOptions object doesn't generate an invoice nor process payments
    • Generate invoice: false
    • Process payments: false
  • The PreviewOptions object commits the changes without a preview
    • Enable preview mode: true
    • Allow preview through the end of a subscription term: true
<api:amend>
   <api:requests>
      <api:Amendments>
         <obj:ContractEffectiveDate>2012-01-01T20:44:54.718+05:30</obj:ContractEffectiveDate>
         <obj:CustomerAcceptanceDate>2012-01-01T20:44:54.718+05:30</obj:CustomerAcceptanceDate>
         <obj:Description>renewing at customer request</obj:Description>
         <obj:EffectiveDate>2012-01-01T20:44:54.718+05:30</obj:EffectiveDate>
         <obj:Name>renewal</obj:Name>
         <obj:ServiceActivationDate>2012-01-01T20:44:54.718+05:30</obj:ServiceActivationDate>
         <obj:Status>Completed</obj:Status>
         <obj:SubscriptionId>402892c42ce80787012ce80ea1aa0014</obj:SubscriptionId>
         <obj:Type>Renewal</obj:Type>
      </api:Amendments>
      <api:AmendOptions>
         <api:GenerateInvoice>false</api:GenerateInvoice>
         <api:ProcessPayments>false</api:ProcessPayments>
      </api:AmendOptions>
      <api:PreviewOptions>
         <api:EnablePreviewMode>true</api:EnablePreviewMode>
         ​<api:PreviewThroughTermEnd>true</api:PreviewThroughTermEnd>
      </api:PreviewOptions>
   </api:requests>
</api:amend>