Knowledge Center

Knowledge Center > API > REST API > REST API Reference > Subscriptions > Suspend Subscription

Suspend Subscription

This feature is in Limited Availability. If you wish to have access to the feature, submit a request at Zuora Global Support

This REST API reference describes how to suspend an active subscription.

Request

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

Request parameters

subscription-key

required

path

Subscription number or ID. Subscription status must be Active.

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

contractEffectiveDate

optional

The date when the customer notifies you that they want to amend their subscription.

Type: date

suspendPolicy

required

Suspend methods. Specify a way to suspend a subscription. See Suspend Date for more information.

Type: string (enum)

Value:

  • Today: The subscription suspension takes effect on today's date.

  • EndOfLastInvoicePeriod: The subscription suspension takes effect at the end of the last invoice period. The suspend date defaults to a date that is one day after the last invoiced period. You can choose this option to avoid any negative invoices (credits) issued back to the customer after the subscription suspension. 

  • SpecificDate: The subscription suspension takes effect on a specific date. You must define the specific date in the suspendSpecificDate field.

  • FixedPeriodsFromToday: The subscription suspension takes effect after a specified period based on today's date. You must specify the suspendPeriods and suspendPeriodsType fields to define the period.

suspendPeriods

conditional

The length of the period used to specify when the subscription suspension takes effect. The subscription suspension takes effect after a specified period based on today's date. You must use this field together with the suspendPeriodsType field to specify the period.

Type: integer

Note:

This field is only applicable only when the suspendPolicy field is set to FixedPeriodsFromToday.

suspendPeriodsType

conditional

The period type used to define when the subscription suspension takes effect. The subscription suspension takes effect after a specified period based on today's date. You must use this field together with the suspendPeriods field to specify the period.

Type: string (enum)

Values:

  • Day

  • Week

  • Month

  • Year

Note:

This field is only applicable only when the suspendPolicy field is set to FixedPeriodsFromToday.

suspendSpecificDate

conditional

A specific date when the subscription suspension takes effect, in the format yyyy-mm-dd.

Type: date

Note:

  • This field is only applicable only when the suspendPolicy field is set to SpecificDate.

  • The value should not be earlier than the subscription contract effective date, later than the subscription term end date, or within a period for which the customer has been invoiced.

resume

optional

Whether to set when to resume a subscription when creating a suspend amendment.

Values:

  • true

  • false

resumePolicy

optional

Resume methods. Specify a way to resume a subscription. See Resume Date for more information.

Values:

  • ​Today: The subscription resumption takes effect on today's date.

  • FixedPeriodsFromSuspendDate: The subscription resumption takes effect after a specified period based on the suspend date. You must specify the resumePeriods and resumePeriodsType fields to define the period.
  • SpecificDate: The subscription resumption takes effect on a specific date. You must define the specific date in the resumeSpecificDate field.

  • FixedPeriodsFromToday: The subscription resumption takes effect after a specified period based on the today's date. You must specify the resumePeriods and resumePeriodsType fields to define the period.

resumePeriods

conditional

The length of the period used to specify when the subscription is resumed. The subscription resumption takes effect after a specified period based on the suspend date or today's date. You must use this field together with the resumePeriodsType field to specify the period.

Type: integer

Note:

This field is only applicable when the resumePolicy field is set to FixedPeriodsFromToday or FixedPeriodsFromSuspendDate.

resumePeriodsType

conditional

The period type used to define when the subscription resumption takes effect. The subscription resumption takes effect after a specified period based on the suspend date or today's date. You must use this field together with the resumePeriods field to specify the period.

Type: string (enum)

Values:

  • Day

  • Week

  • Month

  • Year

Note:

This field is only applicable when the resumePolicy field is set to FixedPeriodsFromToday or FixedPeriodsFromSuspendDate.

resumeSpecificDate

conditional

A specific date when the subscription resumption takes effect, in the format yyyy-mm-dd.

Type: date

Note:

  • This field is only applicable only when the resumePolicy field is set to SpecificDate.

  • The value should not be earlier than the subscription suspension date.

extendsTerm

optional

Whether to extend the subscription term by the length of time the suspension is in effect.

Values:

  • true

  • false

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.

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

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

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.

invoiceTargetDate

optional

If an invoice is to be generated, the date through which to calculate the charges, as yyyy-mm-dd

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

subscriptionId

The subscription ID.

suspendDate

The date when subscription suspension takes effect, in the format yyyy-mm-dd.

resumeDate

The date when subscription resumption takes effect, in the format yyyy-mm-dd.

termEndDate

The date when the new subscription term ends, in the format yyyy-mm-dd.

totalDeltaTcv

Change in the total contracted value of the subscription as a result of the update.

invoiceId

Invoice ID, if an invoice is generated during the subscription process.

paymentId

Payment ID, if a payment is collected.

paidAmount

Payment amount, if a payment is collected.

Examples

HTTP/JSON request:

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

Request Header: To use the collect and invoice fields, you must set the zuora-version parameter to the REST API minor version number in the request header.

JSON request:

{
  "contractEffectiveDate": "2019-02-01",
  "suspendPolicy": "FixedPeriodsFromToday",
  "suspendPeriods":10,
  "suspendPeriodsType":"Day",
  "resume":true,
  "resumePolicy": "SpecificDate",
  "resumeSpecificDate":"2019-06-01",
  "extendsTerm":true,
  "invoice": true,
  "collect": false
}
JSON response:
{ 
  "success" : true, 
  "subscriptionId" : "8a8082c4539c5bcc0153a658a9636fcc", 
  "suspendDate" : "2019-05-01", 
  "resumeDate" : "2016-06-01", 
  "termEndDate" : "2020-02-01", 
  "totalDeltaTcv" : -896.666666700,
  "invoiceId" : "8a8082c453bb061f0153c529bc921b4b"
  }

CURL request:

#
## Cancel Subscription
##
echo
echo "=============Cancel Subscription============="
echo
curl -i -k -H "apiAccessKeyId:$USER_NAME" -H "apiSecretAccessKey:$PASSWORD" -H "Content-Type:application/json" -H "Accept:application/json" -d '
{
  "contractEffectiveDate": "2019-02-01",
  "suspendPolicy": "FixedPeriodsFromToday",
  "suspendPeriods":10,
  "suspendPeriodsType":"Day",
  "resume":true,
  "resumePolicy": "SpecificDate",
  "resumeSpecificDate":"2019-06-01",
  "extendsTerm":true,
  "invoice": true,
  "collect": false
}
' -X PUT $BASE_URL/v1/subscriptions/A-S00001084/suspend

JSON response:

{
  "success" : true,
  "subscriptionId" : "8a8082c4539c5bcc0153a658a9636fcc",
  "suspendDate" : "2019-05-01",
  "resumeDate" : "2016-06-01",
  "termEndDate" : "2020-02-01",
  "totalDeltaTcv" : -896.666666700,
  "invoiceId" : "8a8082c453bb061f0153c529bc921b4b"
}
Last modified
13:41, 21 Nov 2016

Tags

This page has no custom tags.

Classifications

(not set)