Manage manual renewals using APIs

Partners can submit renewal orders before or after the Anniversary Date, validate pricing and eligibility, and manage quantities and offer rules for each subscription. This capability provides partners with flexibility to maintain service continuity, adjust renewal timing, and ensure that subscription terms and quantities align with customer needs throughout the renewal cycle.

The following two manual renewal types are supported:

• Early renewals
• Late renewals

Early renewals

Early renewal enables partners to renew subscriptions before AD. It introduces new behavior in the subscription lifecycle and state transitions.

The following are the key capabilities and rules that define how early renewal works in practice:

• Place renewal orders ahead of AD

  Partners can submit renewal orders before the customer’s AD. These orders are invoiced immediately upon placement.

• Order return period

  The return period is 14 days, and it starts from the date the order is placed.Returns are allowed both before and after the AD; however, the AD does not roll back after a return.

• Price effective date

  • For non-3YC customers: The price effective date is based on the order placement date.
  • For 3YC customers: The price effective date is based on the license commitment start date. Early renewal does not modify the customer’s commitment cycle. When a customer under 3YC attempts to renew early (before AD), the system preserves the integrity of the 3‑year commitment. In 3YC, AD is not reset to the early renewal date. Instead, AD is rolled over only after renewal is processed, ensuring that the next renewal cycle remains aligned with the original 3YC structure.

• Quantity and product rules

  • The first early renewal order must include only existing products and quantities.
  • Offer‑level validation ensures that the ordered quantity (plus any previously renewed quantity) does not exceed the customer’s current quantity.
  • Seats or products additions are allowed only after the initial early renewal order is successfully processed.

  Note: EOL SKUs can be early renewed only for 3YC customers and are blocked for non‑3YC customers; EOS SKUs cannot be early renewed for any customer type.

• Subsequent orders
  Partners must place any subsequent renewal orders only after the first early renewal order is fully processed. Concurrent (back‑to‑back) orders without waiting for order completion are not allowed.

• Impact on renewal preferences
  Early renewal does not alter the customer’s renewal preferences or quantities set for auto-renewal. The renewal date remains unchanged and continues to drive system‑initiated auto‑renewals. After an early renewal, only the anniversary date is updated. The renewal date remains unchanged and continues to serve as the auto‑renew trigger.

Impact of early renewal on anniversary date and renewal date

Examples: Early Renewal, Auto‑Renewal, and AD Behavior

Early renewal workflow using APIs

1. Preview Renewal

The Create Order API with orderType set to PREVIEW_RENEWAL allows partners to simulate a renewal order before the actual renewal is processed. This helps validate renewal eligibility, pricing, and offer availability in advance.

Notes:

• subscriptionId is necessary when the order is for an existing subscription
• If the intention is to renew a new offer, then it is optional.
  • Optionally, in this case, deploymentId and currency can be included as valid properties.
• The order request will be rejected if a subscriptionId is found for the offerId included in the request.

Request

• URL: <ENV>/v3/customers/<customer-id>/orders

• Body:

  {
  "orderType": "PREVIEW_RENEWAL",
  "externalReferenceId": "759",
  "currencyCode": "USD",
  "lineItems": [
   {
     "extLineItemNumber": 1,
     "offerId": "80004567EA01A12",
     "subscriptionId": "e0b170437c4e96ac5428364f674dffNA",
     "quantity": 10
   }
   ]
  }
  

Response

   {
   "referenceOrderId": "",
   "externalReferenceId": "",
   "orderId": "",
   "customerId": "1006370655",
   "currencyCode": "USD",
   "orderType": "PREVIEW_RENEWAL",
   "creationDate": "2025-05-02T22:49:54Z",
   "status": "",
  "lineItems": [
    {
      "extLineItemNumber": 1,
      "offerId": "11083117CA03A12",
      "quantity": 10,
      "subscriptionId": "3d0630693446f8bdff9cbd08f4b68bNA",
      "status": "1000",
      "currencyCode": "USD",
      "proratedDays": 365,
      "pricing": {
        "partnerPrice": 350.50,
        "discountedPartnerPrice": 350.50,
        "netPartnerPrice": 350.50,
        "lineItemPartnerPrice": 3505.00
      }
    }
   ]
   }

2. Create renewal order

Use the POST /v3/customers/<customer-id>/orders endpoint with orderType as RENEWAL to place a renewal order.

Notes:

• subscriptionId is necessary when the order is for an existing subscription
• If the intention is to create a subscription for a new offer, then it is optional.
  • Optionally, in this case, deploymentId and currency can be included as valid properties.
• The order request will be rejected if a subscriptionId is found for the offerId included in the request.

Request:

{
  "orderType": "RENEWAL",
  "externalReferenceId": "759",
  "currencyCode": "USD",
  "lineItems": [
    {
      "extLineItemNumber": 1,
      "offerId": "80004567EA01A12",
      "subscriptionId": "e0b170437c4e96ac5428364f674dffNA",
      "quantity": 10

    }
  ]
}

Response

{
  "referenceOrderId": "",
  "orderType": "RENEWAL",
  "externalReferenceId": "759",
  "customerId": "9876543210",
  "orderId": "5120008001",
  "currencyCode": "USD",
  "creationDate": "2019-05-02T22:49:54Z",
  "status": "1002",
  "lineItems": [
    {
      "extLineItemNumber": 1,
      "offerId": "80004567EA01A12",
      "quantity": 1,
      "status": "1002",
      "subscriptionId": "e0b170437c4e96ac5428364f674dffNA"
    }
  ],
  "links": { ... }
}

3. Verify renewed quantity details using GET Subscriptions API

Use the <ENV> /v3/customers/<customer-id>/subscriptions/<subscription-id> or <ENV> /v3/customers/<customer-id>/subscriptions API to verify renewed quantity for the subscription.

The renewedQuantity parameter in the response indicates the quantity that was manually renewed before the Anniversary Date.

A sample response is as follows:

{
  "subscriptionId": "1c3a4517c44cfc925704fe942a79abNA",
  "offerId": "65304479CA01A12",
  "currentQuantity": 10,
  "usedQuantity": 0,
  "autoRenewal": {
    "enabled":true,
    "renewalQuantity": 5
  },

"renewedQuantity":5,
  "creationDate": "2024-09-13T09:22:13Z",
  "renewalDate": "2025-09-13",
  "status": "1000",
  "currencyCode": "USD",

  "links": {
    "self": {
      "uri": "/v3/customers/123456789/subscriptions/1c3a4517c44cfc925704fe942a79abNA",
      "method": "GET",
      "headers": []
    }
  }
}

Late renewals

Late renewal occurs after the AD when the subscription either did not auto‑renew or was opted out of auto‑renewal.

Rules:

• Occurs after Anniversary Date (AD) up to the allowed grace period (typically 14 days).
• Partners can renew expired or near‑expired subscriptions manually during this window.
• Can only include products from the previous term.
• Quantity must be equal to or less than the previous‑term quantity.
• Additional quantity is not allowed in the renewal order.
• New purchases require a separate new Create Order workflow.

Note: You can use the same set of APIs mentioned above for Early Renewals, to perform late renewals as well. A renewal‑type order placed after the AD is considered a late renewal order. Whereas, a renewal type of order placed with line item before AD will be considered an Early Renewal Order.