Skip to main content

Update a Product on Subscription with Future-dated Updates

Zuora

Update a Product on Subscription with Future-dated Updates

Orders is now generally available as of Zuora Billing Release 284 (August 2019). You can access all the new capabilities in the Sandbox environment starting August 31, 2020. The Production deployment is September 10, 2020.

If you are an existing Zuora Subscribe and Amend customer and want to adopt Orders, see What is Orders Harmonization and join the Orders Harmonization community group for more information. If you want to enable Orders, submit a request at Zuora Global Support.

You can create an Update Product order action even if there is already a future-dated Update Product order action on the subscription. 

For example:

  • A customer subscribes to your Basic Service for one year starting on January 1, 2021.
  • In March, the customer wants to upgrade to your Premium Service on a future date, July 1, 2021. So you create a future-dated Update Product amendment by setting the effective date to July 1, 2021.
  • In April, the customer wants to upgrade to your Special Service starting on May 1, 2021. So you create an Update Product amendment by setting the update date to May 1, 2021. 

The following table lists the services your customer has subscribed to:

Service Name Effective Date and End Date Rate Plan Charge

Basic Service

January 1, 2021 - April 30, 2021

$10/seat/month * 10 seat

Special Service

May 1, 2021 - June 30, 2021

$9/seat/month * 15 seat

Premium Service

July 1, 2021 - December 31, 2021

$8/seat/month * 20 seat

You can create an Update Product order action before a future-dated Update Product order action on the subscription in Zuora UI and REST API.

Use the Zuora application

You can use the Zuora UI to update a product even when future-dated Update Product order actions already exist on the subscription.

  1. Follow the steps 1 - 7 in Update a Product in a Subscription to update the target rate plan for the included product. The rate plan charges in the selected rate plan are listed.

    update-product.png

  2. Complete the following steps to apply the Premium Service settings to the rate plan charge:
    1. Click the name of the rate plan charge to be updated, which is displayed in blue text in the UI. The rate plan charge details are expanded.
    2. Scroll up to the top of the page, and set the dates in the Contract effectiveService activation, and Customer acceptance fields to be July 1, 2021.
    3. In the Charge pricing section of the Products and charges area, change the price to 2 and quantity to 20.

      first-product-update.png

    4. In the Timing and frequency of charge section, select Upon contract effective for the Trigger condition field. You can select another option as long as the setting reflects your business requirement correctly.

      trigger-condition.png

    5. After all the changes are completed, click Done and then Continue.
  3. Complete the following steps to apply the Special Service settings in another product update:
    1. Click Update below the name of the rate plan to be updated.
    2. Scroll up to the Trigger Dates area and set the dates in the Contract effectiveService activation, and Customer acceptance fields to be May 1, 2021.
    3. Toggle the Make this update before a future date change switch to specify an exact date for this update. In this tutorial, select a date in May during which you are to apply the Special Service settings. 

      specific-update-date-2020.png

    4. Click the name of the rate plan charge to be updated, which is displayed in blue text in the UI. The rate plan charge details are expanded.
    5. In the Charge pricing section of the Products and charges area, change the price to 9 and quantity to 15.

      second-product-update.png

    6. In the Timing and frequency of charge section, select Upon contract effective for the Trigger condition field. You can select another option as long as the setting reflects your business requirement correctly.
    7. After all the changes are completed, click Done and then Continue.
  4. To view the update to the subscription with a future-dated update, click the Order Actions tab. You can see the first Update Product order action addresses the Premium Service update and the second addresses the Premium Service update.

    review-order-actions.png

  5. Click Activate to activate the order.

Use the REST API

You can use the "Create order" operation and the specificUpdateDate field to update a product on subscription with future-dated updates. Before the Orders feature is enabled, you have to use the "Update subscription", "Amend", or "CRUD: Create amendment" operation.

To update a product on subscription with future-dated updates by creating an order:

  1. Determine the values of the following variables:

    Variable Description
    $SubscriptionNum The number of the subscription to update. For example, A-S00000001.
    $AccountNum The number of the account that will own the order. For example, A00000001.
    $RPId The ID of the rate plan to update in the subscription. For example, 2c92c0f85d7d53d3015dac494dfc5cbf.
    $ChargeNum The number of the charge to update in the rate plan. For example, C-00000020.
    $Today Today's date. For example, 2020-01-17.
    $UpdateDatePremium The Service Activation Date and Customer Acceptance Date for the Premium Service. For example, 2021-07-01.
    $UpdateDateSpecial The Service Activation Date and Customer Acceptance Date for the Special Service. For example, 2021-05-01.
  2. Use the "Create and activate order" operation to create an order under an existing account:

    Request POST /v1/orders/
    Request Body
    {
      "orderDate": "$Today",
      "existingAccountNumber": "$AccountNum",
      "subscriptions": [
        {
          "subscriptionNumber": "$SubscriptionNum",
          "orderActions": [
            {
              "type": "UpdateProduct",
              "triggerDates": [
                {
                  "triggerDate": "$Today",
                  "name": "ContractEffective"
                },
                {
                  "triggerDate": "$UpdateDatePremium",
                  "name": "ServiceActivation"
                },
                {
                  "triggerDate": "$UpdateDatePremium",
                  "name": "CustomerAcceptance"
                }
              ],
              "updateProduct": {
                "ratePlanId": "$RPId",
                "chargeUpdates": [
                  {
                    "description": null,
                    "chargeNumber": "$ChargeNum",
                    "pricing": {
                      "recurringPerUnit": {
                        "listPrice": 8,
                        "quantity": 20,
                        "priceChangeOption": null,
                        "priceIncreasePercentage": null
                      }
                    },
                    "effectiveDate": {
                      "specificTriggerDate": "$UpdateDatePremium",
                      "triggerEvent": "SpecificDate"
                    },
                    "customFields": {}
                  }
                ],
                "customFields": {}
              }
            },
            {
              "type": "UpdateProduct",
              "triggerDates": [
                {
                  "triggerDate": "$Today",
                  "name": "ContractEffective"
                },
                {
                  "triggerDate": "$UpdateDateSpecial",
                  "name": "ServiceActivation"
                },
                {
                  "triggerDate": "2$UpdateDateSpecial",
                  "name": "CustomerAcceptance"
                }
              ],
              "updateProduct": {
                "ratePlanId": "$RPId",
                "uniqueToken": null,
                "specificUpdateDate": "$UpdateDateSpecial",
                "chargeUpdates": [
                  {
                    "description": null,
                    "chargeNumber": "$ChargeNum",
                    "pricing": {
                      "recurringPerUnit": {
                        "listPrice": 9,
                        "quantity": 15,
                        "priceChangeOption": "NoChange",
                        "priceIncreasePercentage": null
                      }
                    },
                    "effectiveDate": {
                      "specificTriggerDate": "$UpdateDateSpecial",
                      "triggerEvent": "SpecificDate"
                    },
                    "billing": {
                      "billingPeriodAlignment": null
                    },
                    "customFields": {}
                  }
                ]
              }
            }
          ]
        }
      ]
    }
    

    To create the order under a new account instead of an existing account, specify the newAccount field instead of the existingAccountNumber field.

To preview invoices for the updated subscription, use the "Preview order" operation.