Knowledge Center

Knowledge Center > API > REST API > REST API Reference > Subscriptions > Renew subscription

Renew subscription

Renews a termed subscription using existing renewal terms.

Request

  • Production: PUT https://api.zuora.com/rest/v1/subscriptions/{subscription-key}/renew
  • API Sandbox: PUT https://apisandbox-api.zuora.com/rest/v1/subscriptions/{subscription-key}/renew

Request parameters

subscription-key

required

path

Subscription number or ID

Request Header

zuora-version

optional

The minor version of the Zuora REST API. 

You only need to set this parameter if you use the collect or invoice field. See REST API Basics for more information.

Accept

optional

Optionally enter application/json. Only JSON is returned.

Request body

invoiceCollect

optional

This field has been replaced by the invoice field and the collect field. invoiceCollect is available only for backward compatibility.

If true, an invoice is generated and payment collected automatically during the renewal. If false (default), no invoicing or payment takes place.

This field is in Zuora REST API version control. Supported minor versions are 186.0, 187.0, 188.0, and 189.0. See Zuora REST API Versions for more information.

invoiceTargetDate

optional

Date through which to calculate charges if generating an invoice, in yyyy-mm-dd format. Default is current date.

invoice

optional

Creates an invoice for a subscription. The invoice generated in this operation is only for this subscription, not for the entire customer account.

If the value is true, an invoice is created. If the value is false, no action is taken.
The default value is false

This field is in Zuora REST API version control. Supported minor versions are 196.0 or later. To use this field in the method, you must set the zuora-version parameter to the minor version number in the request header. See Zuora REST API Versions for more information.

collect

optional

Collects an automatic payment for a subscription. The collection generated in this operation is only for this subscription, not for the entire customer account.
If the value is true, the automatic payment is collected. If the value is false, no action is taken.
The default value is false.
Prerequisite: invoice must be true

This field is in Zuora REST API version control. Supported minor versions are 196.0 or later. To use this field in the method, you must set the zuora-version parameter to the minor version number in the request header. See Zuora REST API Versions for more information.

applyCreditBalance

optional

Applies a credit balance to an invoice.
If the value is true, the credit balance is applied to the invoice. If the value is false, no action is taken.
Prerequisite: invoice must be true

Note: If you are using the field invoiceCollect rather than the field invoice, the invoiceCollect value must be true.

To view the credit balance adjustment, retrieve the details of the invoice using the Get Invoices method.

OpportunityCloseDate_QT

optional

The closing date of the Opportunity. This field is populated when the subscription originates from Zuora Quotes.

This field is used only for reporting subscription metrics. 

See Subscription Data Source for more information.

OpportunityName_QT

optional

The unique identifier of the Opportunity. This field is populated when the subscription originates from Zuora Quotes.

This field is used only for reporting subscription metrics. 

See Subscription Data Source for more information.

QuoteBusinessType_QT

optional

The specific identifier for the type of business transaction the Quote represents such as New, Upsell, Downsell, Renewal, or Churn. This field is populated when the subscription originates from Zuora Quotes.

This field is used only for reporting subscription metrics. 

See Subscription Data Source for more information.

QuoteNumber_QT

optional

The unique identifier of the Quote. This field is populated when the subscription originates from Zuora Quotes.

This field is used only for reporting subscription metrics. 

See Subscription Data Source for more information.

QuoteType_QT

optional

The Quote type that represents the subscription lifecycle stage such as New, Amendment, Renew or Cancel. This field is populated when the subscription originates from Zuora Quotes.

This field is used only for reporting subscription metrics. 

See Subscription Data Source for more information.

Response

success

Contains true if successful, otherwise false.

processId

Internal process ID to assist Zuora support. Only returned if success is false.

reasons

Information on one or more reasons for the result. Only returned if success is false.

code

Eight-digit numeric error code

message

Description of the error

termStartDate

Date the new subscription term begins, as yyyy-mm-dd

termEndDate

Date the new subscription term ends, as yyyy-mm-dd

invoiceId

Invoice ID, if one is generated

paymentId

Payment ID, if payment is collected

paidAmount

Payment amount, if payment is collected

totalDeltaMrr

Change in the subscription monthly recurring revenue as a result of the update. For a renewal, this is the MRR of the subscription in the new term.

totalDeltaTcv

Change in the total contracted value of the subscription as a result of the update. For a renewal, this is the TCV of the subscription in the new term.

Examples

The following JSON and CURL examples show how to create a subscription for an existing customer account. Some fields in the REST methods are supported as of Zuora REST API minor versions. The fields you can specify depends on the REST API minor version you use.

JSON Examples (REST API Minor Version 196.0 and later)

In API minor version 196.0 and later, the invoicecollect field is replaced by the invoice and collect fields. To use the collect and invoice fields,  you must set the zuora-version parameter to the minor version number in the request header. 

HTTP/JSON request:

PUT https://api.zuora.com/rest/v1/subscriptions/A-S00001084/renew

JSON request:

{
  "invoice": true,
  "collect": false
}

JSON response:

{
  "termStartDate": "2014-02-01",
  "success": true,
  "termEndDate": "2014-05-01",
  "subscriptionId": "2c92c8f83dcbd8b1013dcce0f09100a5"
}

JSON Examples (REST API Minor Version 189.0 and earlier)

HTTP/JSON request:

PUT https://api.zuora.com/rest/v1/subscriptions/A-S00001084/rene

JSON request:

{
  "invoiceCollect" : false
}

JSON response:

{
  "termStartDate": "2014-02-01",
  "success": true,
  "termEndDate": "2014-05-01",
  "subscriptionId": "2c92c8f83dcbd8b1013dcce0f09100a5"
}

CURL Example

CURL request:

##
## Renew Subscription
##
echo
echo "=============Renew Subscription============="
echo
curl -i -k -H "apiAccessKeyId:$USER_NAME" -H "apiSecretAccessKey:$PASSWORD" -H "Content-Type:application/json" -H "Accept:application/json" -d '
{
  "invoiceCollect":true,
  "invoiceTargetDate":"yyyy-mm-dd",
}
' -X PUT $BASE_URL/v1/subscriptions/ff808081298c6e5401298c7a845c007b/renew

JSON response:

{
  "termStartDate": "2014-02-01",
  "success": true,
  "termEndDate": "2014-05-01",
  "subscriptionId": "2c92c8f83dcbd8b1013dcce0f09100a5"
}
Last modified

Tags

Classifications

(not set)