Skip to main content

Amendment

Zuora

Amendment

  1. Last updated
  2. 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:

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:

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.