Knowledge Center

Knowledge Center > API > SOAP API > SOAP API Object Reference > Subscription

Subscription

A subscription is a product or service that has recurring charges, such as a monthly flat fee or charges based on usage. Subscriptions can also include one-time charges, such as activation fees. Every subscription must be associated with an account. At least one active account must exist before any subscriptions can be created.

The Subscription object contains the information needed to create and maintain a subscription associated with an Account object. This SOAP API reference describes the supported calls, limits, and fields associated with the Subscription object.

Supported Calls

You can use this object with the following calls:

To create a subscription, use the subscribe() call.

Limits

Subscriptions per Account

3,000 subscriptions are allowed on an account.

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
AccountId required

Create
Query
Update*
Delete
Filter

This field can be updated when Status is Draft.

The ID of the account associated with this subscription.

Type: zns:ID

Character limit: 32

Version notes: --

Values: a valid account ID

AncestorAccountId optional Filter

A filter option for querying all subscriptions under the same account hierarchy.

Type: zns:ID

Character limit: 32

Version notes: --

Values: a valid account ID

AutoRenew optional

Create
Query
Update*
Delete
Filter

This field can be updated when Status is Draft.

Indicates if the subscription automatically renews at the end of the term.

Type: boolean

Character limit:

Version notes: WSDL 20.0+

Valuestrue, false

CancelledDate optional Query
Filter

The date on which the subscription was canceled.

Type

  • date: Supported as of WSDL version 69+
  • dateTime: Supported through WSDL version 68

Character limit:

Version notes: --

Values: a valid date

ContractAcceptanceDate

optional

Create
Query
Update*
Subscribe
Delete
Filter

The date when the customer accepts the contract.

This field can be updated when Status is Draft.

Type

  • date: Supported as of WSDL version 69+
  • dateTime: Supported through WSDL version 68

Character limit:

Version notes: --

Note: The service activation date is only required if the Require Service Activation of Orders? Setting is set to Yes. If this setting is set to Yes:

  • If ContractAcceptanceDate field is required, you must set this field, ContractAcceptanceDate, and ContractEffectiveDate fields in the subscribe call to activate a subscription.
  • If 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 DRAT status.
ContractEffectiveDate required

Create
Query
Update*
Subscribe
Delete
Filter

The date when the contract takes effect.

This field can be updated when Status is Draft.

Type

  • date: Supported as of WSDL version 69+
  • dateTime: Supported through WSDL version 68

Character limit:

Version notes: --

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.

CpqBundleJsonId__QT optional

Query
Filter

The Bundle product structures from Zuora Quotes if you utilize Bundling in Salesforce. 

Do not change the value in this field.

Type: string

Character limit: 32

Version notes: WSDL 72.0+

Values: N/A

CreatedById optional

Query
Filter

The user ID of the person who created the subscription.

Type: zns:ID

Character limit: 32

Version notes: WSDL 20.0+

Values: automatically generated

CreatedDate optional

Query
Filter

The date the subscription was created.

This value is the same as the OriginalCreatedDate value until the subscription is amended.

Type: dateTime

Character limit:

Version notes: WSDL 20.0+

Values: automatically generated

CreatorAccountId optional

Query
Filter

The account ID that created the subscription or the amended subscription.

Type: zns:ID

Character limit: 32

Version notes:

Values: automatically generated

CreatorInvoiceOwnerId optional

Query
Filter

The account ID that owns the invoices associated with the subscription or the amended subscription.

Type: zns:ID

Character limit: 32

Version notes:

Values: automatically generated

CurrentTerm

optional

Query

The length of the period for the current subscription term. 

If TermType is set to TERMED, this field is required and must be greater than 0. If TermType is set to EVERGREEN, this value is ignored. Default is 0.

Type: bigint

Character limit: 20

Version notes: WSDL 73.0+

Values: automatically generated

CurrentTermPeriodType

optional

Query

The period type for the current subscription term.

This field is used with the CurrentTerm field to specify the current subscription term.

Type: string

Character limit:

Version notes: WSDL 73.0+

Values:

  • Month (default)
  • Year
  • Day
  • Week
Id optional Query
Filter

The ID of this object. Upon creation, the ID of this object is SubscriptionId.

Type: zns:ID

Character limit: 32

Version notes:

Values: automatically generated

InitialTerm conditional

Create
Query
Update*
Subscribe
Delete
Filter

The length of the period for the first subscription term.

This field can be updated when Status is Draft. If you use the subscribe() call, this field is required.

Required: If TermType is Termed

Type: bigint

Character limit: 20

Version notes: --

Values: any valid number. The default value is 0.

InitialTermPeriodType

optional

Create
Query
Update*
Subscribe
Delete
Filter

The period type for the first 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 InitialTerm field to specify the initial subscription term.
InvoiceOwnerId required

Create
Query
Update*
Delete
Filter

This field can be updated when Status is Draft.

The account ID that owns the invoices associated with the subscription. 

Type: zns:ID

Character limit:

Version notes: WSDL 32.0+

Values: a valid account ID

IsInvoiceSeparate optional

Create
Query
Update
Delete
Filter

Determines if the subscription is invoiced separately. If TRUE, then all charges for this subscription are collected into the subscription's own invoice.

Type: boolean

Character limit:

Version notes: --

Values: TRUE, FALSE (default)

Name required

Create
Query
Update*
Delete
Filter

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.

In WSDL 69+, you can change this value only when the subscription is in Draft status. Once the subscription is activated, you can't change this value, nor can you use this value for a different subscription.

Type: string

Character limit: 100

Version notes: --

Values: one of the following:

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

Create
Query
Update
Delete
Filter

Use this field to record comments about the subscription.

Type: string

Character limit: 500

Version notes: --

Values: a string of 500 characters or fewer

OpportunityCloseDate__QT optional

Create
Query
Update
Delete
Filter

The closing date of the Opportunity. 

This field is used in Zuora Reporting Data Sources to report on Subscription metrics.

If the subscription was originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.

Type: date

Character limit

Version notes: --

Values: populated by Zuora Quotes

OpportunityName__QT optional

Create
Query
Update
Delete
Filter

The unique identifier of the Opportunity. 

This field is used in the Zuora Reporting Data Sources to report on Subscription metrics.

If the subscription was originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.

Type: string

Character limit: 100

Version notes: --

Values: populated by Zuora Quotes

OriginalCreatedDate optional

Query
Filter

The date when the subscription was originally created. This value is the same as the CreatedDate value until the subscription is amended.

Type: dateTime

Character limit:

Version notes: WSDL 20.0+

Values: automatically generated

OriginalId optional

Query
Filter

The original ID of this subscription.

Type: zns:ID

Character limit:

Version notes: WSDL 20.0+

Values: automatically generated

OriginalSubscriptionId n/a n/a Deprecated. Use OriginalId instead.
PreviousSubscriptionId optional

Query
Filter

The subscription ID immediately prior to the current subscription.

Type: zns:ID

Character limit: 32

Version notes: --

Values: automatically generated

QuoteBusinessType__QT optional

Create
Query
Update
Delete
Filter

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 the Zuora Reporting Data Sources to report on Subscription metrics.

If the subscription was originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.

Type: string

Character limit: 32

Version notes: --

Values: populated by Zuora Quotes

QuoteNumber__QT optional

Create
Query
Update
Delete
Filter

The unique identifier of the Quote.

This field is used in the Zuora Reporting Data Sources to report on Subscription metrics.

If the subscription was originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.

Type: string

Character limit: 32

Version notes: --

Values: populated by Zuora Quotes

QuoteType__QT optional

Create
Query
Update
Delete
Filter

The Quote type that represents the subscription lifecycle stage such as New, Amendment, Renew or Cancel. 

This field is used in the Zuora Reporting Data Sources to report on Subscription metrics.

If the subscription was originated from Zuora Quotes, the value is populated with the value from Zuora Quotes.

Type: string

Character limit: 32

Version notes: --

Values: populated by Zuora Quotes

RenewalSetting

conditional

Subscribe
Update*
Amend
Filter

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

Type: string

Character limit:

Version notes: WSDL 62+

ValuesRENEW_WITH_SPECIFIC_TERM (default),
RENEW_TO_EVERGREEN

RenewalTerm

conditional

Create
Query
Update*
Subscribe
Delete
Filter

The length of the period for the subscription renewal term.

This field can be updated when Status is Draft. If you use the subscribe() call, this field is required.

Required: If TermType is Termed.

Type: bigint

Character limit: 20

Version notes: --

Values: one of the following:

  • leave null to default to 0
  • any number

RenewalTermPeriodType

optional

Create
Query
Update*
Subscribe
Delete
Filter

The period type for the subscription renewal term.

Type: string

Character limit:

Version notes: WSDL 73.0+

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

optional

Create
Query
Update*
Subscribe
Delete
Filter

The date when the subscription is activated. 

This field can be updated when Status is Draft.

Type

  • date: Supported as of WSDL version 69+
  • dateTime: Supported through WSDL version 68

Character limit: 29

Version notes: --

Note: The service activation date is only required if the Require Service Activation of Orders? Setting is set to Yes. If this setting is set to Yes:

  • If ContractAcceptanceDate field is required, you must set this field, ContractAcceptanceDate, and ContractEffectiveDate fields in the subscribe call to activate a subscription.
  • If 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 DRAT status.
Status optional

Query
Filter

The status of the subscription.

Type: string (enum)

Character limit: 17

Version notes: --

Values: automatically generated

Possible values: one of the following:

  • Draft
  • PendingActivation
  • PendingAcceptance
  • Active
  • Cancelled
  • Expired
  • Suspended
SubscriptionEndDate optional

Query
Filter

The date when the subscription term ends, where the subscription ends at midnight the day before.

For example, if the SubscriptionEndDate is 12/31/2016, the subscriptions ends at midnight (00:00:00 hours) on 12/30/2016.

This date is the same as the term end date or the cancelation date, as appropriate.

Type

  • date: Supported as of WSDL version 69+
  • dateTime: Supported through WSDL version 68

Character limit: 29

Version notes: --

Values: automatically generated

SubscriptionStartDate required

Query
Filter

The date when the subscription term starts. This date is the same as the start date of the original term, which isn't necessarily the start date of the current or new term.

Type

  • date: Supported as of WSDL version 69+
  • dateTime: Supported through WSDL version 68

Character limit: 29

Version notes: --

Values: automatically generated

TermEndDate required

Query
Update*
Filter

This field can be updated when Status is Draft.

The date when the subscription term ends. If the subscription is evergreen, the TermEndDate value is null or is the cancelation date, as appropriate. 

Type

  • date: Supported as of WSDL version 69+
  • dateTime: Supported through WSDL version 68

Character limit: 29

Version notes: --

Values: automatically generated

TermStartDate required

Create
Query
Update*
Filter

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.

Type

  • date: Supported as of WSDL version 69+
  • dateTime: Supported through WSDL version 68

Character limit: 29

Version notes: --

TermType required

Create
Query
Update*
Filter

This field can be updated when Status is Draft.

Indicates if a subscription is termed or evergreen. A termed subscription has a specific end date and requires manual renewal. An evergreen subscription doesn't have an end date and doesn't need renewal. This field can be updated when the subscription status is Draft.

Type: string (enum)

Character limit: 9

Version notes: --

Values: TERMED, EVERGREEN

UpdatedById optional

Query
Filter

The ID of the user who last updated the subscription.

Type: zns:ID

Character limit: 32

Version notes: WSDL 20.0+

Values: automatically generated

UpdatedDate optional

Query
Filter

The date when the subscription was last updated.

Type: dateTime

Character limit: 29

Version notes: WSDL 20.0+

Values: automatically generated

Version optional

Query
Filter

The version number of the subscription.

Type: int

Character limit:

Version notes: --

Values: automatically generated

VersionCreatedDate n/a n/a Deprecated. Use the CreatedDate field instead.

Additional Field Detail

AutoRenew

Indicates if the subscription automatically renews at the end of the term, or if the subscription expires at the end of the term and must be manually renewed. This field is required if this subscription is termed. Omit the field if this subscription is evergreen.

A termed subscription uses the value, Termed, for the TermType. An evergreen subscription uses the value, EVERGREEN, for the TermType.

ContractAcceptanceDate

The date when the customer accepts the contract. If the subscription includes charges that trigger at specific date points, then this date triggers charges set to the value, Customer Acceptance Date.

Trigger dates must follow this rule:

ContractEffectiveDate <= ServiceActivationDate <= ContractAcceptanceDate

If your configuration doesn't require customer acceptance, then this field is optional.

If your configuration requires customer acceptance, then this field is required if you want to create a subscription that is in Active status directly upon creation. If you don't pass this field, then the subscription is in Pending Acceptance status.

ContractEffectiveDate

The date when the contract takes effect. If the subscription includes charges that trigger at specific date points, then this date triggers charges set to the value, Upon Contract Effective.

Trigger dates must follow this rule:

ContractEffectiveDate <= ServiceActivationDate <= ContractAcceptanceDate

The value of the ContractEffectiveDate field is often the same as the value for the SubscriptionStartDate, but it doesn't have to be.

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 Subscription object's ID with the call.

The ID for the Subscription object is SubscriptionId.

InitialTerm

The number of periods for the first term of the subscription. This field is required if this subscription is termed. Omit the field if this subscription is evergreen.

A termed subscription uses the value, Termed, for the TermType. An evergreen subscription uses the value, EVERGREEN, for the TermType.Return to the top of the Fields section

RenewalTerm

The number of periods for the renewal term of the subscription. This field is required if this subscription is termed. Omit the field if this subscription is evergreen.

A termed subscription uses the value, Termed, for the TermType. An evergreen subscription uses the value, EVERGREEN, for the TermType.

ServiceActivationDate

The date when the subscription is activated. If the subscription includes charges that trigger at specific date points, then this date triggers charges set to the value, Upon Service Activation.

Trigger dates must follow this rule:

ContractEffectiveDate <= ServiceActivationDate <= ContractAcceptanceDate

This field is optional unless your configuration requires service activation. If your configuration requires service activation, then this field is required if you want to create a subscription that is in Active status directly upon creation. If you don't pass this field, then the subscription is in Pending Activation status.

Status

The status of the subscription. This field is automatically generated, and can be one of the following values:

  • Draft
  • PendingActivation
  • PendingAcceptance
  • Active
  • Cancelled
  • Expired
  • Suspended 

Fields that affect the Status field value are subscription date fields, such as ContractEffectiveDate, ServiceActivationDate, and CustomerAcceptanceDate. Calls that affect the Status field value are calls that create, cancel, or amend the subscription, such as subscribe() and amend().

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".

Last modified
14:55, 31 May 2017

Tags

Classifications

(not set)