Renew, suspend, or resume subscriptions

When a subscription expires or before it expires, you can renew the subscription.

If an end subscriber requests to suspend or pause a subscription, you can use the "Pause a subscription" operation to do it.

When a subscription is in the Suspended status, the only action you can take is to resume a suspended subscription with the "Resume a subscription" operation.

In this guide, you will learn:

  • How to renew a subscription
  • How to suspend a subscription
  • How to resume a subscription
Quickstart API
v1 API

Renew a subscription

The Update a subscription API operation allows you to renew a subscription that is about to expire.

Note that only termed subscriptions can be renewed.

The following code example renews the subscription (id = 8ad08f74803a5e3e01803f340e3c2148) on 2023-01-01. The renewal term is 12 months.
cURLJavaNode
Copy
Copied
curl -X PATCH "https://rest.test.zuora.com/v2/subscriptions/8ad08f74803a5e3e01803f340e3c2148"
  -H "Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3" 
  -H "Content-Type: application/json" 
  -d '{
         "description": "Renew a subscription", 
         "renew":{
            "start_on": {
                "contract_effective": "2023-01-01"
            }
          },
         "terms": { 
            "renewal_term": { 
                "interval": "month", 
                "interval_count": 12, 
                "type": "termed"
            }
         }
      }'
Copy
Copied
LocalDate renewStartDate = LocalDate.of(2023,1,1);
String subscriptionId = createdSubscription.getId();

SubscriptionTermPatchRequest renewalTerm = new SubscriptionTermPatchRequest()
    .renewalTerm(new Term()
        .type(Term.TypeEnum.TERMED)
        .interval(Term.IntervalEnum.MONTH)
        .intervalCount(12)

SubscriptionRenewPatchRequest renewSubscriptionRequest = new SubscriptionRenewPatchRequest()
    .startOn((new StartOn()
        .contractEffective(renewStartDate)));

SubscriptionPatchRequest updateRequest = new SubscriptionPatchRequest()
    .renew(renewSubscriptionRequest)
    .terms(renewalTerm)
    .description("Renew a subscription");

Subscription updatedSubscription = zuoraClient.subscriptions().patchSubscription(subscriptionId,updateRequest);
Copy
Copied
const renewRequest = {
  description: 'Renew a subscription',
  renew:{
    start_on: {
      contract_effective: '2023-01-01',
    }
  },
  terms: {
    renewal_term: {
      interval: 'month',
      interval_count: 12,
      type: 'termed',
    }
  }
};
  
const renewSubscription = await zuoraClient.subscriptions.patchSubscription('8ad092478455c5f3018460fd67d9444c',renewRequest);

Suspend a subscription

If the end subscriber requests to suspend a subscription, you can use the Pause a subscription operation to do it.

It is also required to specify the rules for pause a subscription. For example, the subscription can be paused on a specific date or after a certain number of periods from today.

  • To pause a date on a certain date, specify pause_date.
  • To pause a date at the end of the current billing period, specify the following fields:
    • pause_at
    • pause_interval
    • pause_interval_count
You can optionally specify the resume_behavior field to define the behavior when the paused subscription resumes.

The following example pauses an active subscription for one month at the end of the current billing period. Subsequently, when the subscription is resumed, the subscription term is automatically extended by one month.

cURLJavaNode
Copy
Copied
curl --request POST 
     --url 'https://rest.test.zuora.com/v2/subscriptions/A-S00000035/pause' 
     --header 'Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3' 
     --header 'Content-Type: application/json' 
     --data '{
                "pause_at":"specific_period",
                "pause_interval": "month",
                "pause_interval_count": 1,
                "resume_behavior": {
                    "extend_term": true
                 }
              }
Copy
Copied
String subscriptionId = createdSubscription.getId();

PauseSubscriptionRequest pauseRequest = new PauseSubscriptionRequest()
    .pauseAt(PauseSubscriptionRequest.PauseAtEnum.SPECIFIC_PERIOD)
    .pauseInterval(PauseSubscriptionRequest.PauseIntervalEnum.MONTH)
    .pauseIntervalCount(new BigDecimal(1))
    .resumeBehavior(new ResumeSubscriptionRequest().extendTerm(true));

Subscription pausedSubscription = zuoraClient.subscriptions().pauseSubscription(subscriptionId, pauseRequest);
Copy
Copied
const pausedSubscription = await zuoraClient.subscriptions.pauseSubscription('8ad095b8844282ff0184528d63f3242f',
    {
      pause_date: '2022-12-20',
      pause_interval_count: '1',
      pause_interval: 'month',
      resume_behavior: {
        extend_term: true,
      },
    }
);

Resume a subscription

When a subscription is in the Suspended status, the only action you can take is to resume a suspended subscription with the Resume a subscription operation.

The resume date cannot be earlier than the suspend date and cannot be later than the subscription term end date.

The following example resumes the subscription that is suspended.

cURLJavaNode
Copy
Copied
curl --request POST      
     --url 'https://rest.test.zuora.com/v2/subscriptions/8ad08f74803a5e3e01803f340e3c2148/resume'      
     --header 'Authorization: Bearer 6d151216ef504f65b8ff6e9e9e8356d3'      
     --header 'Content-Type: application/json'      
     --data '{ 
                "extend_term": true,
                "resume_date": "2022-09-10"
             }' 
Copy
Copied
ResumeSubscriptionRequest resumeRequest = new ResumeSubscriptionRequest()
    .extendTerm(true)
    .resumeDate("2022-09-10");
 
Subscription resumedSubscription = zuoraClient.subscriptions().resumeSubscription(pausedSubscription.getId(), resumeRequest);
Copy
Copied
const resumedSubscription = await zuoraClient.subscriptions.resumeSubscription('8ad08ccf80efe77c0180f1f5f80d39c9',
    {
      extend_term: true,
      resume_date: '2022-09-10',
    }
);