Use Case For Managing Your Subscription Sales

You can use REST services to manage your subscription sales.

In this use case, you work through the process of using REST to sell a subscription plan for a fictitious company, CED Cyber Solutions.

This use case demonstrates how to:

  1. Create Prerequisite Records

  2. Create a Billing Account

  3. Create a Draft Subscription

  4. Edit Your Draft Subscription

  5. Add an Add-On Item

Create Prerequisite Records

Before you begin, you need to create the following records:

After creating these records, make note of their internal IDs. Throughout this example, use the IDs listed in the following table:

Record Type

Name

ID

Subscription Plan

DEFEND Package

1

Price Book

Standard Pricing

1

Customer

Clean Water Co.

1

Subscription

Three Years

1

Billing Schedule

Monthly, 1st of the month

1

Service Items

Managed Detection and Response

7

Create a Billing Account

Clean Water Co. wants to be billed on the first of the month. They use the same currency as your primary currency. Since they are starting their subscription on January 1, 2020, that is when billing starts.

The startDate must always be in the format YYYY-MM-DD. Use this format regardless of the date format preferences set.

A successful request returns a response with HTTP status 204 No Content. The returned response headers contain the endpoint for the new record. Make note of the Billing Account ID. The example Billing Account internal ID is 1.

Example Billing Account

            {
    "billingSchedule": { "id": "1" },
    "currency": { "id": "1" },
    "customer": { "id": "16" },
    "name": "REST Billing Account",
    "startDate": "2020-01-01"
} 

          

Create a Draft Subscription

Your subscription references all records that you have created.

On a successful response, make note of the subscription ID. Use the ID to make changes to your draft subscription. The ID for your example subscription is 1.

Example Subscription

            {
    "customer": { "id": "1" },
    "billingAccount": { "id": "1" },
    "subscriptionPlan": { "id": "1" },
    "priceBook": { "id": "1" },
    "initialTerm": { "id": "1" }
} 

          

Edit Your Draft Subscription

When you created your subscription, you chose not to supply information about the line items included or the pricing of those line items. This means that the fields use the default values from the subscription plan.

If desired, you can change the defaults. To change the defaults, you send a PATCH request with the ID of the target record appended to the end of the patch request. The contents of the request body only need to include your changes. Make sure that all changes to dependent fields are included.

Clean Water Co. wants the silver support tier and has 25 users. Because they are one of your first customers, they receive a 50% discount on their setup costs.

Note:

Leaving a field undefined leaves it unchanged. If you want to set the value of a field to an empty value, you must explicitly set the field to null in the request body.

A successful request returns a response with HTTP status 204 No Content. The endpoint for the modified record is returned in the response headers.

Example Edited Subscription

            {
    "subscriptionLine": {
        "items": [
            {
                "lineNumber": 4,
                "isIncluded": true
            }
        ]
    },
    "priceInterval": {
        "items": [
            {
                "subscriptionPlanLineNumber": 1,
                "discount": 50.0
            },
            {
                "subscriptionPlanLineNumber": 3,
                "quantity": 25
            }
        ]
    }
} 

          

Add an Add-On Item

Before adding add-on items to any subscription plan, you must Enabling SuiteBilling Features.

Clean Water Co. would like to add Managed Detection and Response to their subscription. The requirements for the line are as follows:

  • Bill in advance

  • Always add to renewal subscriptions

  • Have a prorated start and end date

  • Charge $50.00 per month, prorated by day

Adding an add-on item to a draft subscription is an edit. You complete this edit by sending a PATCH request to the subscription endpoint with the ID appended to the end.

Because the add-on item is not tied to any subscription plan or price book, you must supply all of the subscription line and price book line information.

Because the add-on line requires new pricing information, you must create another price plan. If you are unfamiliar with this process, see Use Case For Managing Your Subscription Catalog. You assign an ID of 19 to the new price plan.

If the customer decides that they no longer want the add-on item, you can PATCH the subscription to mark the line as not included.

Example Add-On Items

            {
    "subscriptionLine": {
        "items": [
            {
                "lineNumber": 7,
                "item": { "id": "7" },
                "subscriptionLineType": "2",
                "billingMode": "IN_ADVANCE",
                "renewalOption": "ALWAYS",
                "prorateStartDate": true,
                "prorateEndDate": true
            }
        ]
    },
    "priceInterval": {
        "items": [
            {
                "subscriptionPlanLineNumber": 7,
                "pricePlan": { "id": "19" },
                "frequency": "MONTHLY",
                "repeatEvery": "1",
                "startOffsetUnit": "MONTH",
                "startOffsetValue": 1,
                "prorateBy": "DAY"
            }
        ]
    }
} 

          

Related Topics

SuiteBilling Use Cases
Use Case For Managing Your Subscription Catalog

General Notices