Amendment

Last updated
Save as PDF

Amendments change subscriptions. When a customer needs to make a change to a subscription, you make that change through an amendment. Common changes include the following:

Change the terms and conditions of a contract.
Add a product to, or remove of product from, a subscription.
Update an existing product, such as changing the quantity.
Renew a subscription on the autorenewal date or before.
Cancel a subscription, or transfer to another owner (can be also be done directly on a subscription without an amendment)
Suspend an active subscription. (This feature is in Limited Availability.)
Resume a suspended subscription. (This feature is in Limited Availability.)

The Amendment object holds the changes that you want to make to the relevant Subscription object, including its RatePlan, RatePlanCharge, and RatePlanChargeTier.

Supported calls

You can use this object with the following calls:

amend()
create()
query()
update()
delete()

Invoiced amendments cannot usually be deleted. One exception to this rule is auto-renew amendments. You can delete the last auto-renew amendment even if an invoice has been generated.

Walkthroughs and use cases

Here are some common ways to use this object:

Add a product to the subscription
set Type to NewProduct
Update information about a product's rate plan charge
set Type to UpdateProduct
Remove a product or part of a product from a subscription
set Type to RemoveProduct
Change the terms and conditions of the subscription
set Type to TermsAndConditions
Change the owner of the subscription
set Type to OwnerTransfer
Renew a subscription
set Type to Renewal
Cancel a subscription
set Type to Cancellation
Suspend a subscription (This feature is in Limited Availability.)
set Type to SuspendSubscription
Resume a subscription (This feature is in Limited Availability.)
set Type to ResumeSubscription

Field Descriptions

All field names are case sensitive. Check enumerated values in descriptions to confirm capitalization and spacing. See Field Types for additional information.

Name	Required to Create?	Allowed Operations	Description
AutoRenew	conditional	Create Query Update* Delete Filter	Determines whether the subscription is automatically renewed, or whether it expires at the end of the term and needs to be manually renewed. Required: For amendment of type TermsAndConditions when changing the automatic renewal status of a subscription. Type: boolean Version notes: -- Values: true, false
BookingDate	optional	Create Query Filter	The date when the amendment is signed. This field is to standardize the booking date information to increase audit ability and traceability of data between Zuora Billing and Zuora Revenue. It is mapped as the booking date for a sale order line in Zuora Revenue. Type: date Version notes: 118.0
Code	required	Query Filter	A unique alphanumeric string that identifies the amendment. Type: string Character limit: 50 Version notes: -- Values: automatically generated
ContractEffectiveDate	required	Create Query Update Delete Filter	The date when the amendment's changes become effective for billing purposes. Type: date: Supported as of WSDL version 69+ dateTime: Supported through WSDL version 68 Version notes: --
CreatedById	optional	Query Filter	The user ID of the person who created the amendment. Type: zns:ID Character limit: 32 Version notes: WSDL 20.0+ Values: automatically generated
CreatedDate	optional	Query Filter	The date when the amendment was created. Type: dateTime Version notes: WSDL 20.0+ Values: automatically generated
CurrentTerm	conditional	Create Query Update* Amend Delete Filter	The length of the period for the current subscription term. This field can be updated when Status is `Draft`. Required: Only if the value of the Type field is set to `TermsAndConditions` and TermType is set to `TERMED`. This field is not required if TermType is set to `EVERGREEN`. Type: long Character limit: Version notes: WSDL 73.0+ Values: a valid number Note: The InitialTerm field is deprecated from WSDL 73.0, use the CurrentTerm field instead.
CurrentTermPeriodType	conditional	Create Query Update* Amend Delete Filter	The period type for the current subscription term. Type: string Character limit: Version notes: WSDL 73.0+ Values: `Month` (default) `Year` `Day` `Week` Note: This field can be updated when Status is `Draft`. This field is used with the CurrentTerm field to specify the current subscription term.
CustomerAcceptanceDate	conditional	Create Query Update Delete Filter	The date when the customer accepts the amendment's changes to the subscription. This field is only required if Zuora is configured to require customer acceptance in Z-Billing and the subscription is currently in the Pending Acceptance status (the value of the Status field is currently PendingAcceptance). Use this field together with the Status field. When you set a date in this field as a customer acceptance date, you should also set the Status field as `Completed`. Type: date: Supported as of WSDL version 69+ dateTime: Supported through WSDL version 68 Version notes: --
Description	optional	Create Query Update* Delete Filter	A description of the amendment. Type: string Character limit: 500 Version notes: -- Values: maximum 500 characters
DestinationAccountId	optional	Create Filter	The ID of the subscription owner that the subscription is being transferred to. Type: zns:ID Character limit: 32 Version notes: WSDL 33.0+ requires either the DestinationAccountId field or the DestinationInvoiceOwnerId field for owner transfer amendments Values: a valid account ID
DestinationInvoiceOwnerId	optional	Create Filter	The ID of the invoice owner that the subscription is being transferred to. Type: zns:ID Character limit: 32 Version notes: WSDL 33.0+ requires either the DestinationAccountId field or the DestinationInvoiceOwnerId field for owner transfer amendments Values: a valid invoice ID
EffectiveDate	conditional	Create Query Update Delete Filter	The date when the cancellation amendment takes effect. Type: date: Supported as of WSDL version 69+ dateTime: Supported through WSDL version 68 Version notes: --
Id	optional	Query Filter	The ID of this object. Upon creation of this object, this field becomes AmendmentId. Type: zns:ID Character limit: 32 Version notes: -- Values: automatically generated
Name	required	Create Query Update* Delete Filter	The name of the amendment. Type: string Character limit: 100 Version notes: -- Values: a string of 100 characters or fewer
RatePlanData	conditional	Create	A container for one RatePlan object. Required: Only for NewProduct, RemoveProduct and UpdateProduct amendments. Type: zns:RatePlanData Character limit: Version notes: -- Values: RatePlanData
RenewalSetting	conditional	Subscribe Amend Update* Filter	Specifies whether a termed subscription will remain termed or change to evergreen when it is renewed. Required: If TermType is Termed Type: string Character limit: Version notes: WSDL 62+ Values: RENEW_WITH_SPECIFIC_TERM (default), RENEW_TO_EVERGREEN
RenewalTerm	conditional	Create Query Update* Delete Filter	The term of renewal for the amended subscription. This field can be updated when Status is `Draft`. Required: Only if the value of the Type field is set to `TermsAndConditions`. Type: long Character limit: Version notes: -- Values: a valid number
RenewalTermPeriodType	optional	Create Query Update* Amend Subscribe Delete Filter	The period type for the subscription renewal term. This field can be updated when Status is `Draft`. Required: Only if the value of the Type field is set to `TermsAndConditions`. This field is used with the RenewalTerm field to specify the subscription renewal term. Type: string Character limit: Version notes: WSDL 73.0+ Values: `Month` (default) `Year` `Day` `Week`
ResumeDate	conditional	Amend Query Update Filter	The date when the subscription resumption takes effect. See Resume Date for more information. This feature is in Limited Availability. If you want to have access to the feature, submit a request at Zuora Global Support. Required: This field is only applicable if you resume a suspended subscription. Type: date Version notes: WSDL 76.0+
ServiceActivationDate	conditional	Create Query Update Delete Filter	The date when service is activated. This field is only required if Zuora is configured to require service activation in Z-Billing and the subscription is currently in the Pending Activation status (the value of the Status field is currently `PendingActivation`). Use this field together with the Status field. When you set a date in this field as a service activation date, you should also set the Status field as the expected next phase status: `Completed` or `PendingAcceptance`. Type: date: Supported as of WSDL version 69+ dateTime: Supported through WSDL version 68 Version notes: --
SpecificUpdateDate	conditional	Amend Create Query Update	The date when the UpdateProduct amendment takes effect. This field is only applicable if there is already a future-dated UpdateProduct amendment on the subscription. See Create an UpdateProduct Amendment Before a Future-dated Update for more information. Req uired: Only for the UpdateProduct amendments if there is already a future-dated UpdateProduct amendment on the subscription. Type: date Version notes: WSDL 71.0+
Status	required	Create Query Delete Filter	The status of the amendment. Type: string (enum) Character limit: 17 Version notes: -- Values: one of the following: Draft (default, if left null) Pending Activation Pending Acceptance Completed
SubscriptionId	required	Create Query Update* Delete Filter	The ID of the subscription that the amendment changes. Type: zns:ID Character limit: 32 Version notes: -- Values: a valid subscription ID
SuspendDate	conditional	Amend Query Update Filter	The date when the subscription suspension takes effect. See Suspend Date for more information. This feature is in Limited Availability. If you want to have access to the feature, submit a request at Zuora Global Support. Required: This field is only applicable if you suspend an active subscription. Type: date Version notes: WSDL 76.0+
TermStartDate	conditional	Create Query Update Delete Filter	The date when the new terms and conditions take effect. Required: Only if the value of the Type field is set to TermsAndConditions. Type: date: Supported as of WSDL version 69+ dateTime: Supported through WSDL version 68 Version notes: --
TermType	conditional	Create Query Update* Delete Filter	Indicates if the subscription isTERMED or EVERGREEN. A TERMED subscription has an expiration date, and must be manually renewed. An EVERGREEN subscription doesn't have an expiration date, and must be manually ended. Required: Only when as part of an amendment of type TermsAndConditions to change the term type of a subscription. Type: string Character limit: 9 Version notes: -- Values: TERMED, EVERGREEN
Type	required	Create Query Update* Delete Filter	The type of amendment. Type: string (enum) Character limit: 20 Version notes: The SuspendSubscription and ResumeSubscription values are available in WSDL 76.0+. Values: one of the following: Cancellation NewProduct OwnerTransfer RemoveProduct Renewal UpdateProduct TermsAndConditions SuspendSubscription (This value is in Limited Availability.) ResumeSubscription (This value is in Limited Availability.)
UpdatedById	optional	Query Filter	The ID of the user who last updated the amendment. Type: zns:ID Character limit: 32 Version notes: WSDL 20.0+ Values: automatically generated
UpdatedDate	optional	Query Filter	The date when the amendment was last updated. Type: dateTime Version notes: WSDL 20.0+ Values: automatically generated

Additional Field Detail

AutoRenew

Determines whether the subscription is automatically renewed, or whether it expires at the end of the term and needs to be manually renewed.

This field is required for termed subscriptions. The Subscription object's TermType field value is TERMED for termed subscriptions and EVERGREEN for evergreen subscriptions, which are subscriptions that don't expire.

You can use this field when the Type field value is TermsAndConditions.

CustomerAcceptanceDate

The date when the customer accepts the amendment's changes to the subscription.

This field is required if Zuora is configured to require customer acceptance in ZBilling and the subscription is currently in the Pending Acceptance status (the value of the Status field is PendingAcceptance).

Use this field together with the Status field. When you set a date in this field as a customer acceptance date, you should also set the Status field as Completed.

DestinationAccountId

The ID of the subscription owner that the subscription is being transferred to.

Use this field in an amend() call to transfer the subscription owner of a subscription. After the call is finished, this field becomes read-only.

You must specify either the DestinationAccountId field or the DestinationInvoiceOwnerId field to use the amend() call to transfer ownership.

If you are using an older version of the WSDL (32.0 or older), then this field is required for owner transfers; the DestinationInvoiceOwnerId field isn't available to you.

DestinationInvoiceOwnerId

The ID of the invoice owner that the subscription is being transferred to.

Use this field in an amend() call to transfer the invoice owner of a subscription. After the call is finished, this field becomes read-only.

You must specify either the DestinationAccountId field or the DestinationInvoiceOwnerId field to use the amend() call to transfer ownership.

This field isn't available to you if you are using an older version of the WSDL (32.0 or older); you can use the DestinationAccountId field only.

Id

The ID of this object. Every object has a unique identifier that Zuora automatically assigns upon creation. You use this ID later when you work with the object. For example, if you send an amend() call to modify an existing subscription, then you need to include the specific Subscriptionobject's ID with the call.

Status

The status of the amendment, which can be one of the following values:

Draft
The default status. Draft is used temporarily in the code while making changes before the amendment is in Completed status.
PendingAcceptance
The amendment is waiting for customer acceptance. This value is available only if Zuora is configured to require customer acceptance in ZBilling.
PendingActivation
The amendment is waiting to be activated. This value is available only if Zuora is configured to require service activation in ZBilling.
Completed
The amendment's changes are in effect.
Cancelled
The amendment is canceled. Its changes don't take effect.

Some fields can only be updated while the object is still in Draft status. These are noted in the table above with an asterisk next to the word "Update".

Type

The type of amendment. Each amendment type describes an action you can take to modify an existing subscription.

Cancellation
Cancels the subscription.
NewProduct
Adds products or services to the subscription. If you are adding multiple products, then use a separate Amendment object for each new product. You can submit multiple Amendment objects in a single amend() call unless you're using an older WSDL (41.0 and older).
OwnerTransfer
Transfers ownership of the subscription to another account or invoice owner.
RemoveProduct
Removes a product from a subscription. If you are switching to a different product, then you can remove a product and add a product in the same amend() call unless you're using an older WSDL (41.0 and older).
Renewal
Automatically renews a termed subscription in advance of the next renewal term start date.
UpdateProduct
Updates the charge information, including the price or quantity of a product, in the subscription. For example, add or remove seats.
TermsAndConditions
Extends or shortens the initial term or renewal term of the subscription.
SuspendSubscription
Suspends an active subscription. This value is in Limited Availability.
ResumeSubscription
Resumes a suspended subscription. This value is in Limited Availability.