CRUD: Update a subscription

Note: The Subscribe and Amend features are approaching end of support on February 16, 2026. For more information, please refer to the Product and Feature End of Support page.

Request
path Parameters
id
required
string

Object id

query Parameters
rejectUnknownFields
boolean
Default: false

Specifies whether the call fails if the request body contains unknown fields. With rejectUnknownFields set to true, Zuora returns a 400 response if the request body contains unknown fields. The body of the 400 response is:

{
    "message": "Error - unrecognised fields"
}

By default, Zuora ignores unknown fields in the request body.

header Parameters
Accept-Encoding
string

Include the Accept-Encoding: gzip header to compress responses as a gzipped file. It can significantly reduce the bandwidth required for a response.

If specified, Zuora automatically compresses responses that contain over 1000 bytes of data, and the response contains a Content-Encoding header with the compression algorithm so that your client can decompress it.

Content-Encoding
string

Include the Content-Encoding: gzip header to compress a request. With this header specified, you should upload a gzipped file for the request payload instead of sending the JSON payload.

Authorization
string

The value is in the Bearer {token} format where {token} is a valid OAuth token generated by calling Create an OAuth token.

Zuora-Entity-Ids
string

An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.

Zuora-Track-Id
string <= 64 characters

A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.

The value of this field must use the US-ASCII character set and must not include any of the following characters: colon (:), semicolon (;), double quote ("), and quote (').

Request Body schema: application/json
required
AccountId
string

This field can be updated when Status is Draft. The ID of a valid account ID.

AutoRenew
boolean

This field can be updated when Status is Draft. Indicates if the subscription automatically renews at the end of the term. Values: true, false

CancelledDate
string <date>

The date of the Amendment object. Values: inherited from Amendment.EffectiveDate

ContractAcceptanceDate
string <date>

The date when the customer accepts the contract.

This field can be updated when Status is Pending Acceptance.

Note : This field is only required in the Subscribe call if the Require Customer Acceptance of Orders? setting is set to Yes. If this setting is set to Yes:

  • If the ServiceActivationDate field is required, you must set this field, ServiceActivationDate, and ContractEffectiveDate fields in the Subscribe call to activate a subscription.
  • If the ServiceActivationDate field is not required, you must set both this field and the ContractEffectiveDate field in the Subscribe call to activate a subscription. If you only set a valid date in the ContractEffectiveDate field, the Subscribe call still returns success, but the subscription is in Pending Acceptance status.

This field can also be updated when the subscription is still on version one (has not been amended before) and the Allow update Subscription trigger dates? setting in Billing Settings is set to Yes.

ContractEffectiveDate
string <date>

The date when the contract takes effect.

This field can be updated when Status is Draft.

Note: This field is required in the Subscribe call. If you set the value of this field to null and both the ServiceActivationDate and ContractAcceptanceDate fields are not required, the Subscribe call still returns success, but the new subscription is in DRAFT status. To activate the subscription, you must set a valid date to this field.

This field can also be updated when the subscription is still on version one (has not been amended before) and the Allow update Subscription trigger dates? setting in Billing Settings is set to "Yes".

CurrentTermPeriodType
string

The period type for the current subscription term. This field is used with the CurrentTerm field to specify the current subscription term. Values:

  • Month (default)
  • Year
  • Day
  • Week
ExternallyManagedBy
string

An enum field on the Subscription object to indicate the name of a third-party store. This field is used to represent subscriptions created through third-party stores.

Enum: "Amazon" "Apple" "Google" "Roku"
InitialTerm
integer <int32>

The length of the period for the first subscription term. This field can be updated when Status is Draft. Required: If TermType is Termed Character limit: 20 Values: any valid number.

InitialTermPeriodType
string

The period type for the first subscription term. Values:

  • Month (default)

  • Year

  • Day

  • Week Note:

  • This field can be updated when Status is Draft.

  • This field is used with the InitialTerm field to specify the initial subscription term.

InvoiceOwnerId
string

This field can be updated when Status is Draft. A valid account ID.

IsInvoiceSeparate
boolean

Determines if the subscription is invoiced separately. If TRUE, then all charges for this subscription are collected into the subscription's own invoice. Values: TRUE, FALSE (default)

Name
string

The unique identifier of the subscription. If you don't specify a value, then Zuora generates a name automatically. Whether auto-generated or manually specified, the subscription name must be unique. Otherwise an error will occur. Character limit: 100 Values: one of the following:

  • leave null to automatically generate
  • a string of 100 characters or fewer
Notes
string

Use this field to record comments about the subscription. Character limit: 500 Values: a string of 500 characters or fewer

RenewalSetting
string

This field can be updated when Status is Draft. Specifies whether a termed subscription will remain termed or change to evergreen when it is renewed. Required: If TermType is Termed Values: RENEW_WITH_SPECIFIC_TERM (default), RENEW_TO_EVERGREEN

RenewalTerm
integer <int32>

The length of the period for the subscription renewal term. This field can be updated when Status is Draft. Required: If TermType is Termed. Character limit: 20 Values: one of the following:

  • leave null to default to 0
  • any number
RenewalTermPeriodType
string

The period type for the subscription renewal term. Values:

  • Month (default)

  • Year

  • Day

  • Week Note:

  • This field is used with the RenewalTerm field to specify the subscription renewal term.

  • This field can be updated when Status is Draft.

ServiceActivationDate
string <date>

The date when the subscription is activated.

Character limit: 29

This field can be updated when Status is Pending Activation.

Note: This field is only required in the Subscribe call if the Require Service Activation of Orders? setting is set to Yes. If this setting is set to Yes:

  • If the ContractAcceptanceDate field is required, you must set this field, ContractAcceptanceDate, and ContractEffectiveDate fields in the Subscribe call to activate a subscription.
  • If the ContractAcceptanceDate field is not required, you must set both this field and the ContractEffectiveDate field in the Subscribe call to activate a subscription. If you only set a valid date in the ContractEffectiveDate field, the Subscribe call still returns success, but the subscription is in Pending Activation status.

This field can also be updated when the subscription is still on version one (has not been amended before) and the Allow update Subscription trigger dates? setting in Billing Settings is set to "Yes".

Status
string

The status of the subscription. Character limit: 18 Values: automatically generated Possible values: one of the following:

  • Draft
  • Pending Activation
  • Pending Acceptance
  • Active
  • Cancelled
  • Expired
  • Suspended (This value is in Limited Availability.)
TermStartDate
string <date>

This field can be updated when Status is Draft. The date when the subscription term begins. If this is a renewal subscription, then this date is different from the subscription start date. Character limit: 29 Version notes: --

TermType
string

This field can be updated when Status is Draft. Indicates if a subscription is termed or evergreen. Character limit: 9 Values: TERMED, EVERGREEN

Version
integer <int32>

The version number of the subscription. Values: automatically generated

CpqBundleJsonId__QT
string <= 32 characters

The Bundle product structures from Zuora Quotes if you utilize Bundling in Salesforce. Do not change the value in this field.

OpportunityCloseDate__QT
string <date>

The closing date of the Opportunity. This field is used in Zuora data sources to report on Subscription metrics. If the subscription originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.

OpportunityName__QT
string <= 100 characters

The unique identifier of the Opportunity. This field is used in Zuora data sources to report on Subscription metrics. If the subscription originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.

QuoteBusinessType__QT
string <= 32 characters

The specific identifier for the type of business transaction the Quote represents such as New, Upsell, Downsell, Renewal or Churn. This field is used in Zuora data sources to report on Subscription metrics. If the subscription originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.

QuoteNumber__QT
string <= 32 characters

The unique identifier of the Quote. This field is used in Zuora data sources to report on Subscription metrics. If the subscription originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.

QuoteType__QT
string <= 32 characters

The Quote type that represents the subscription lifecycle stage such as New, Amendment, Renew or Cancel. This field is used in Zuora data sources to report on Subscription metrics. If the subscription originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.

IntegrationId__NS
string <= 255 characters

ID of the corresponding object in NetSuite. Only available if you have installed the Zuora Connector for NetSuite.

IntegrationStatus__NS
string <= 255 characters

Status of the subscription's synchronization with NetSuite. Only available if you have installed the Zuora Connector for NetSuite.

Project__NS
string <= 255 characters

The NetSuite project that the subscription was created from. Only available if you have installed the Zuora Connector for NetSuite.

SalesOrder__NS
string <= 255 characters

The NetSuite sales order than the subscription was created from. Only available if you have installed the Zuora Connector for NetSuite.

SyncDate__NS
string <= 255 characters

Date when the subscription was synchronized with NetSuite. Only available if you have installed the Zuora Connector for NetSuite.

property name*
additional property
any

Custom fields of the Subscription object. The name of each custom field has the form customField__c. Custom field names are case sensitive. See Manage Custom Fields for more information.

Responses
200
401
put/v1/object/subscription/{id}
Request samples
application/json
{
  • "IsInvoiceSeparate": true
}
Response samples
application/json
{
  • "Success": true,
  • "Id": "2c93808457d787030157e02ea04123cf"
}