# Subscriptions 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. For more information, see Subscriptions. ## Preview a subscription - [POST /v1/subscriptions/preview](https://developer.zuora.com/v1-api-reference/api/subscriptions/post_previewsubscription.md): The REST API reference describes how to create a new subscription in preview mode. This call does not require a valid customer account. It can be used to show potential new customers a preview of a subscription with complete details and charges before creating an account, or to let existing customers preview a subscription with all charges before committing. Notes: - The response of the Preview Subscription call is based on the REST API minor version you set in the request header. The response structure might be different if you use different minor version numbers. - If you have the Invoice Settlement feature enabled, we recommend that you set the Zuora-Version parameter to 207.0 or later available versions. Otherwise, an error is returned. - Default values for customerAcceptanceDate and serviceActivationDate are set as follows. | | serviceActivationDate(SA) specified | serviceActivationDate (SA) NOT specified | | ------------- |:-------------| :-----| | customerAcceptanceDate (CA) specified | SA uses value in the request call; CA uses value in the request call| CA uses value in the request call;SA uses CE as default | | customerAcceptanceDate (CA) NOT specified | SA uses value in the request call; CA uses SA as default | SA and CA use CE as default | ## Preview a subscription by subscription key - [POST /v1/subscriptions/{subscription-key}/preview](https://developer.zuora.com/v1-api-reference/api/subscriptions/previewexistingsubscription.md): Describes how to preview an existing subscription to view information about existing and future invoices or credit memos. Note: The Zuora-Version parameter must be 207.0 or later. ## Create a subscription - [POST /v1/subscriptions](https://developer.zuora.com/v1-api-reference/api/subscriptions/post_subscription.md): This operation describes how to create a new subscription for an existing customer account. ### Notes If you have the Invoice Settlement feature enabled, it is best practice to set the Zuora-Version parameter to 211.0 or later available versions. Otherwise, an error occurs. Default values for customerAcceptanceDate and serviceActivationDate are set as follows. This API operation does not support creating a pending subscription. | | serviceActivationDate(SA) specified | serviceActivationDate (SA) NOT specified | | ------------- |:------------- | :-----| | customerAcceptanceDate (CA) specified| SA uses value in the request call; CA uses value in the request call| CA uses value in the request call;SA uses CE as default | | customerAcceptanceDate (CA) NOT specified | SA uses value in the request call; CA uses SA as default | SA and CA use CE as default | This call supports a subset of the functionality of our Create an order call. We recommend using "Create an order" instead of this call because the Orders call has the following advantages: - Provides options for managing the entire subscription lifecycle from creation through to cancellation using different order actions. - Allows the creation or modifying of multiple subscriptions in a single order. - Allows a single order to combine both recurring subscription digital goods or services with order line items for physical goods. - Orders are treated as atomic transactions. If any part fails, the entire order and subscription changes are rolled back. This call can be used to create a single subscription and there are no deprecation plans for this call. We will continue to support this call. ## List subscriptions by account key - [GET /v1/subscriptions/accounts/{account-key}](https://developer.zuora.com/v1-api-reference/api/subscriptions/get_subscriptionsbyaccount.md): Retrieves all subscriptions associated with the specified account. Zuora only returns the latest version of the subscriptions. Subscription data is returned in reverse chronological order based on updatedDate. Note that the rate plans inside the subscriptions are not sorted specifically and are returned in a random order. ## Retrieve a subscription by key - [GET /v1/subscriptions/{subscription-key}](https://developer.zuora.com/v1-api-reference/api/subscriptions/get_subscriptionsbykey.md): This REST API reference describes how to retrieve detailed information about a specified subscription in the latest version. ## Update a subscription - [PUT /v1/subscriptions/{subscription-key}](https://developer.zuora.com/v1-api-reference/api/subscriptions/put_subscription.md): Use this call to make the following kinds of changes to a subscription: - Add a note - Change the renewal term or auto-renewal flag - Change the term length or change between evergreen and termed - Add a new product rate plan - Remove an existing subscription rate plan - Change the quantity or price of an existing subscription rate plan - Change rate plans - to replace the existing rate plans in a subscription with other rate plans. Changing rate plans is currently not supported for the Billing - Revenue Integration feature. When Billing - Revenue Integration is enabled, changing rate plans will no longer be applicable in Zuora Billing. ### Notes: - The "Update a subscription" call creates a new subscription object that has a new version number and to which the subscription changes are applied. The new subscription object has the same subscription name but a new, different, subscription ID. The Status field of the new subscription object will be set to Active unless the change applied was a cancelation or suspension in which case the status reflects that. The Status field of the originating subscription object changes from Active to Expired. A status of Expired does not imply that the subscription itself has expired or ended, merely that this subscription object is no longer the most recent. - In one request, this call can make: - Up to 9 combined add, update, and remove changes - No more than 1 change to terms & conditions - Updates are performed in the following sequence: 1. First change the notes on the existing subscription, if requested. 2. Then change the terms and conditions, if requested. 3. Then perform the remaining amendments based upon the effective dates specified. If multiple amendments have the same contract-effective dates, then execute adds before updates, and updates before removes. - The update operation is atomic. If any of the updates fails, the entire operation is rolled back. - The response of the Update Subscription call is based on the REST API minor version you set in the request header. The response structure might be different if you use different minor version numbers. - If you have the Invoice Settlement feature enabled, it is best practice to set the Zuora-Version parameter to 211.0 or later available versions. Otherwise, an error occurs. ### Override a Tiered Price There are two ways you override a tiered price: - Override a specific tier number. For example: tiers[{tier:1,price:8},{tier:2,price:6}] - Override the entire tier structure. For example: tiers[{tier:1,price:8,startingUnit:1,endingUnit:100,priceFormat:"FlatFee"}, {tier:2,price:6,startingUnit:101,priceFormat:"FlatFee"}] If you just override a specific tier, do not include the startingUnit field in the request. ## Retrieve a subscription by key and version - [GET /v1/subscriptions/{subscription-key}/versions/{version}](https://developer.zuora.com/v1-api-reference/api/subscriptions/get_subscriptionsbykeyandversion.md): This REST API reference describes how to retrieve detailed information about a specified subscription in a specified version. When you create a subscription amendment, you create a new version of the subscription. You can use this method to retrieve information about a subscription in any version. ## Renew a subscription - [PUT /v1/subscriptions/{subscription-key}/renew](https://developer.zuora.com/v1-api-reference/api/subscriptions/put_renewsubscription.md): Renews a termed subscription using existing renewal terms. When you renew a subscription, the current subscription term is extended by creating a new term. If any charge in your subscription has the billing period set as SubscriptionTerm, a new charge segment is generated for the new term. Note: If you have the Invoice Settlement feature enabled, it is best practice to set the Zuora-Version parameter to 211.0 or later available versions. Otherwise, an error occurs. ## Cancel a subscription - [PUT /v1/subscriptions/{subscription-key}/cancel](https://developer.zuora.com/v1-api-reference/api/subscriptions/put_cancelsubscription.md): This REST API reference describes how to cancel an active subscription. Note: If you have the Invoice Settlement feature enabled, it is best practice to set the Zuora-Version parameter to 211.0 or later available versions. Otherwise, an error occurs. ## Resume a subscription - [PUT /v1/subscriptions/{subscription-key}/resume](https://developer.zuora.com/v1-api-reference/api/subscriptions/put_resumesubscription.md): This REST API reference describes how to resume a suspended subscription. Note: If you have the Invoice Settlement feature enabled, it is best practice to set the Zuora-Version parameter to 211.0 or later available versions. Otherwise, an error occurs. ## Suspend a subscription - [PUT /v1/subscriptions/{subscription-key}/suspend](https://developer.zuora.com/v1-api-reference/api/subscriptions/put_suspendsubscription.md): This REST API reference describes how to suspend an active subscription. Note: If you have the Invoice Settlement feature enabled, it is best practice to set the Zuora-Version parameter to 211.0 or later available versions. Otherwise, an error occurs. ## Delete a subscription by number - [PUT /v1/subscriptions/{subscription-key}/delete](https://developer.zuora.com/v1-api-reference/api/subscriptions/put_deletesubscription.md): This REST API reference describes how to delete a subscription of the specified subscription number. ## Update subscription custom fields of a subscription version - [PUT /v1/subscriptions/{subscriptionNumber}/versions/{version}/customFields](https://developer.zuora.com/v1-api-reference/api/subscriptions/put_updatesubscriptioncustomfieldsofaspecifiedversion.md): Updates the custom fields of a specified subscription version. ## List subscription metrics by subscription numbers - [GET /v1/subscriptions/subscription-metrics](https://developer.zuora.com/v1-api-reference/api/subscriptions/getmetricsbysubscriptionnumbers.md): Lists subscription metrics for the subscriptions that you specify by subscription numbers.