Subscription
From API Documentation
This object contains the information needed to create a new subscription for the account. It is part of the entire subscribe process. The subscribe call is a superset of Subscription.
A subscription represents a customer signing up for a product for a certain amount of time. Each subscription can have one or more RatePlans. See Invoking The subscribe() Call for more information about creating subscriptions.
How Subscription and Product Relate to Each Other
The set of {Product, product rate plan(s), and product rate plan charge(s)} is a defined set of products a company sells (for example, a family plan with each member costing $10). The set of {a Subscription, rate plan(s), and rate plan charge(s)} is an instance of a Product, with actual quantities specified (five family members on a family plan, for example).
Supported Calls
This object is used in the query, subscribe(), and subscribeWithExistingAccount() calls.
Fields
| Name | Required? | Type | Allowed Operations: ● Yes ○ No | Allowable Values | Description |
|---|---|---|---|---|---|
| AccountId | No for the subscribe call; Yes otherwise | zns: ID | ● Create
● Query | A valid account ID | This is the identification number of a valid Account. |
| AncestorAccountId | No | zns:ID | ○ Create
○ Query | Use as a filter to query all subscriptions under the same account hierarchy. | |
| AutoRenew | Yes | boolean | ● Create
● Query | True or False | Determines whether the subscription will be automatically renewed, or whether it will expire and need to be manually renewed at the end of the term. |
| CancelledDate | No | dateTime | ● Create
● Query | A valid dateTime value | The date on which the contract was cancelled. This is read only, since it is automatically generated. |
| ContractAcceptanceDate (known in Z-Billing as "Customer Acceptance Date") | Depends. If you have Zuora configured to require Customer Acceptance, you will need to pass this if you want the subscription created to be active, otherwise the subscription will be in a state of Pending Acceptance. If you don't require Customer Acceptance, you don't need to specify this date. | dateTime | ● Create
● Query | A valid dateTime value |
This is the date on which the contract was accepted by the customer, and will trigger charges that have their trigger event set to "Upon Customer Acceptance". Trigger dates must follow the rule ContractEffectiveDate <= ServiceActivationDate <= ContractAcceptanceDate. Note: For legacy reasons "ContractAcceptanceDate" corresponds to "Customer Acceptance Date" in the Z-Billing web application. |
| ContractEffectiveDate | Yes | dateTime | ● Create
● Query | A valid dateTime value |
This is the date on which the contract becomes effective, and will trigger charges that have their trigger event set to "Upon Contract Effective." Trigger dates must follow the rule ContractEffectiveDate <= ServiceActivationDate <= ContractAcceptanceDate. |
| CreatedById | System generated, always exists | ZNS:Id | ○ Create
● Query | 32 characters maximum. This field is not editable. | Available as of version 20.0 of the API. The Zuora system automatically generates this Id of the user who created the object. |
| CreatedDate | System generated by Zuora, and always exists. (Version 10.0-14.0, and 20.0+) | dateTime | ○ Create
● Query | A valid dateTime value | Please note the difference in behavior based on API version. In versions 10.0-14.0, CreatedDate returns the date which the original (base) subscription was created. In versions 20.0+ CreatedDate returns the date which the current subscription object was created. Old functionality (version 10.0-14.0) was replaced with a new field, OriginalCreatedDated. This change was meant to ensure naming consistency across all Zuora API object audit fields. |
| CreatorAccountId | No | zns:ID | ○ Create
● Query | ||
| Currency | Yes | string | Allowable values are defined in the Admin interface | The type of currency with which the account is being paid. | |
| InitialTerm | Yes | int | ● Create
● Query | Any valid number | This provides the initial term for the subscription in months. If it isn't specified, it is set to 0. |
| InvoiceOwnerId | Yes | zns:ID | ● Create
● Query | A valid account ID | Indicates the invoice owner of the subscription. |
| IsInvoiceSeparate | No | boolean | ● Create
● Query | True or false. The default value is false. | Whether the subscription should be invoiced separately. If you set this to true, all charges generated from this subscription will be collected into a dedicated invoice.
|
| Name | No | string | ● Create
● Query | 100 characters maximum | The name of the subscription. This is a unique identifier. If not specified, Zuora will auto-generate the name. |
| Notes | No | string (textarea) | ● Create
● Query | 500 characters maximum | A field to use to record notes relating to the subscription. |
| OriginalCreatedDate | System generated by Zuora, and always exists. (Version 20.0+) | dateTime | ○ Create
● Query | A valid dateTime value | Available in versions 20.0+. Returns the date which the original subscription object was created. Replaces the deprecated functionality of CreatedDate in versions 10.0-14.0. |
| OriginalId | No | zns:ID | ○ Create
● Query | This number is automatically generated | Available as of version 20.0 of the API, and replaces OriginalSubscriptionId. The ID for the very first subscription created for this customer. Since subscriptions are renewed, you can think of subscription IDs as a "chain" of subscriptions that connect from the first subscription to the current one. Although it is automatically generated, this field can be queried. |
| OriginalSubscriptionId | No | string | This number is automatically generated | Deprecated as of Version 20.0. Replaced by OrginalId. The ID for the very first subscription created for this customer. Since subscriptions are renewed, you can think of subscription IDs as a “chain” of subscriptions that connect from the first subscription to the current one. Although it is automatically generated, this field can be queried. | |
| PreviousSubscriptionId | No | zns:ID | ○ Create
● Query | This number is automatically generated | The subscription ID immediately prior to the current one. Although it is automatically generated, this field can be queried. |
| RenewalTerm | Yes | int | ● Create
● Query | Any valid number | This provides the renewal term for the subscription in months—the number of months for which you want to renew the subscription. If it isn't specified, it is set to 0. |
| ServiceActivationDate | If you have Zuora configured to require Service Activation, you will need to pass this if you want the subscription created to be active, otherwise the subscription will be in a state of Pending Activation. If you do not require Service Activation, you do not need to specify this field. | dateTime | ● Create
● Query | A valid dateTime value | This is when the service was activated, and will trigger charges that have their trigger event set to "Upon Service Activation".
Trigger dates must follow the rule ContractEffectiveDate <= ServiceActivationDate <= ContractAcceptanceDate. |
| Status | No. Always exists, read-only. | string (enum) | ● Create
● Query | Draft, Pending Activation, Pending Acceptance, Active, Cancelled, Expired | A list of values reflecting the status of the subscription. You cannot set this directly, rather you set it by setting various dates such as ContractEffectiveData, ServiceActivationDate and CustomerAcceptanceDate, or by taking various actions such as canceling or amending a subscription. |
| SubscriptionEndDate | No, always exists. Read-only. | dateTime | ○ Create
● Query | A valid dateTime value | This is when the subscription ends. Always equal to term end date, unless the subscription has been cancelled, and then it is the cancellation date. |
| SubscriptionStartDate | Yes | dateTime | ○ Create
● Query | A valid dateTime value | The date when the subscription term starts. This is equal to the term start date if the subscription is on its initial term. Otherwise, it is the original term start date if the subscription has renewed. |
| TermEndDate | No, but always exists for Termed Subscriptions. Read-only. | dateTime | ○ Create
● Query | A valid dateTime value | This is when the subscription term ends. It is NULL for an active subscription if it is of type (TermType) Evergreen. For an Evergreen subscription that has been canceled, it is set to the cancellation date. |
| TermStartDate | Yes | dateTime | ● Create
● Query | A valid dateTime value | When the subscription term starts. |
| TermType | No | string | ● Create
● Query | EVERGREEN, TERMED | Case sensitive. Denotes if a subscription is evergreen (has no end date or term length) or has a term. |
| UpdatedById | System generated, always exists | ZNS:Id | ○ Create
● Query | 32 characters maximum. This field is not editable. | Available as of version 20.0 of the API. The Zuora system automatically generates this Id of the user who last updated the object. |
| UpdatedDate | System generated, always exists | dateTime | ○ Create
● Query | This field is not editable. | Available as of version 20.0 of the API. The Zuora system automatically generates this, and denotes when the objects was last updated. |
| Version | No. This always exists, but is auto-generated. | int | ● Create
● Query | This is a read-only field | This is the version of the subscription (first version, second version, etc.). |
| VersionCreatedDate | No. This always exists, but is auto-generated. | dateTime | This is a read-only field. Available in v15.0-19.0. | Deprecated. Replaced by CreatedDate as of version 20.0. This is the date on which the subscription version was created. If there have been amendments, this date will give the date & time when the specific version of the subscription was created in Zuora. To query for when the base subscription was created, query for VersionCreatedDate for version=1 of the subscription. |
