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
The default maximum number of subscriptions allowed on an account is 12,000. However, if you have overridden the value of this limit for your tenant, the value will remain according to your configuration.
Zuora can increase the limit of subscriptions per account upon request. To increase the limit, see Zuora’s Performance Booster and Performance Booster Elite offerings.
Note that the method that Zuora uses to calculate the number of existing subscriptions on an account is explained as below.
When you create a new subscription on an account, the start and end dates of the subscription determine a time frame. When calculating the number of existing subscriptions on the account, Zuora only counts in those existing subscriptions that have a time frame that overlaps with the new subscription to be created. The time frame of an existing subscription is also determined by the start and end dates of the existing subscription. For an evergreen subscription, this time frame is without an end date.
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 |
This field can be updated when Status is The ID of the account associated with this subscription. Type: 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: Character limit: 32 Version notes: -- Values: a valid account ID |
| AutoRenew | optional |
Create |
This field can be updated when Status is Indicates if the subscription automatically renews at the end of the term. Type: boolean Character limit: Version notes: WSDL 20.0+ Values: |
| CancelledDate | optional | Query Filter |
The date on which the subscription was canceled. Type:
Character limit: Version notes: -- Values: a valid date |
| ContractAcceptanceDate |
optional |
Create |
The date when the customer accepts the contract. This field can be updated when Status is Note: The customer acceptance date is only required if the Require Customer Acceptance of Orders? Setting is set to
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". Type:
Character limit: Version notes: -- |
| ContractEffectiveDate | required |
Create |
The date when the contract takes effect. This field can be updated when Status is 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 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". Type:
Character limit: Version notes: --
|
| CpqBundleJsonId__QT | optional |
Query |
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 |
The user ID of the person who created the subscription.
Type: Character limit: 32 Version notes: WSDL 20.0+ Values: automatically generated |
| CreatedDate | optional |
Query |
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 |
The account ID that created the subscription or the amended subscription. Type: Character limit: 32 Version notes: Values: automatically generated |
| CreatorInvoiceOwnerId | optional |
Query |
The account ID that owns the invoices associated with the subscription or the amended subscription. Type: Character limit: 32 Version notes: Values: automatically generated |
| Currency | optional | Query |
The code corresponding to the currency. Type: string Character limit: 3 Version notes: WSDL 137+ Values: a valid currency code Note: This field is available only if you have the Multiple Currencies feature enabled. |
|
CurrentTerm |
optional |
Query |
The length of the period for the current subscription term. If TermType is set to 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:
|
| ExternallyManagedBy | optional | Create Query Update |
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. Type: string Values:
|
| Id | optional | Query Filter |
The ID of this object. Upon creation, the ID of this object is SubscriptionId. Type: Character limit: 32 Version notes: Values: automatically generated |
| InitialTerm | conditional |
Create |
The length of the period for the first subscription term. This field can be updated when Status is Required: If TermType is Termed Type: bigint Character limit: 20 Version notes: -- Values: any valid number. |
|
InitialTermPeriodType |
optional |
Create |
The period type for the first subscription term. Type: string Character limit: Version notes: WSDL 73.0+ Values:
Note:
|
| InvoiceOwnerId | required |
Create |
This field can be updated when Status is 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 |
Determines if the subscription is invoiced separately. If Type: boolean Character limit: Version notes: -- Values: |
| IsLatestVersion | optional | Query Filter |
Indicates whether the current subscription object is the latest version. Type: boolean Character limit: Version notes: WSDL 124.0+ Values: |
| LastBookingDate | optional | Query | The last change date of a subscription. This field is writable only when the subscription is newly created as a first version subscription. The value of this field is as follows:
Type: dateTime Character limit: Version notes: WSDL 122.0+ |
| Name | required |
Create |
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 Type: string Character limit: 100 Version notes: -- Values: one of the following:
|
| Notes | optional |
Create |
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 |
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 |
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 |
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 |
The original ID of this subscription. Type: Character limit: Version notes: WSDL 20.0+ Values: automatically generated |
| OriginalSubscriptionId | n/a | n/a | Deprecated. Use OriginalId instead. |
| PaymentTerm | optional |
Query |
The name of the payment term associated with the subscription. Type: string Character limit: 100 Version notes: WSDL 115.0+ Values: automatically generated |
| PreviousSubscriptionId | optional |
Query |
The subscription ID immediately prior to the current subscription. Type: zns:ID Character limit: 32 Version notes: -- Values: automatically generated |
| QuoteBusinessType__QT | optional |
Create |
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 |
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 |
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 |
| Revision | optional |
Query |
An auto-generated decimal value uniquely tagged with a subscription. The value always contains one decimal place, for example, the revision of a new subscription is 1.0. If a further version of the subscription is created, the Revision value will be increased by 1. The Revision value is always incremental regardless of the deletion of subscription versions. The Revision value may be greater than the version value. In this case, the difference value between the two values indicates the number of deletions of amendments or order actions. Type: string Character limit: Version notes: WSDL 107+ Values: automatically generated |
|
RenewalSetting |
conditional |
Subscribe |
This field can be updated when Status is 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: |
|
RenewalTerm |
conditional |
Create |
The length of the period for the subscription renewal term. This field can be updated when Status is Required: If TermType is Termed. Type: bigint Character limit: 20 Version notes: -- Values: one of the following:
|
|
RenewalTermPeriodType |
optional |
Create |
The period type for the subscription renewal term. Type: string Character limit: Version notes: WSDL 73.0+ Values:
Note:
|
| ServiceActivationDate |
optional |
Create |
The date when the subscription is activated. This field can be updated when Status is Pending Activation. Note: The service activation date is only required if the Require Service Activation of Orders? Setting is set to
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". Type:
Character limit: 29 Version notes: -- |
| Status | optional |
Query |
The status of the subscription. Type: string (enum) Character limit: 18 Version notes: -- Values: automatically generated Possible values: one of the following:
|
| SubscriptionBillToId | optional | Query |
The bill-to contact ID of the subscription. The value of this field is Type: string Version notes: WSDL 121.0+ |
| SubscriptionBillToSnapshotId | optional | Query |
The snapshot ID of the subscription's bill-to contact. The snapshot ID will not change after the subscription version is created. The value of this field is Type: string Version notes: WSDL 121.0+ |
| SubscriptionEndDate | optional |
Query |
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:
Character limit: 29 Version notes: -- Values: automatically generated |
| SubscriptionStartDate | required |
Query |
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:
Character limit: 29 Version notes: -- Values: automatically generated |
| TermEndDate | required |
Query |
This field can be updated when Status is 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:
Character limit: 29 Version notes: -- Values: automatically generated |
| TermStartDate | required |
Create |
This field can be updated when Status is The date when the subscription term begins. If this is a renewal subscription, then this date is different from the subscription start date. Type:
Character limit: 29 Version notes: -- |
| TermType | required |
Create |
This field can be updated when Status is 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: |
| UpdatedById | optional |
Query |
The ID of the user who last updated the subscription. Type: Character limit: 32 Version notes: WSDL 20.0+ Values: automatically generated |
| UpdatedDate | optional |
Query |
The date when the subscription was last updated. Type: dateTime Character limit: 29 Version notes: WSDL 20.0+ Values: automatically generated |
| Version | optional |
Query |
The version number of the subscription. Type: int Character limit: Version notes: -- Values: automatically generated |
| SubscriptionSoldToId | optional | Query Filter |
The ID of the sold-to contact. Use this field to assign an existing account as the sold-to contact of a subscription. Type: Character limit: 32 Version notes: WSDL 132.0+ |
| SubscriptionSoldToSnapshotId | optional | Query Filter |
The snapshot of the ID for an account used as the sold-to contact of a subscription. This field is used to store the original information about the account, in case the information about the account is changed after the creation of the subscription. Type: Character limit: 32 Version notes: WSDL 132.0+ |
| 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.
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:
DraftPending ActivationPending AcceptanceActiveCancelledExpiredSuspended
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".