Tutorial: Switch Linkus Cloud Service Subscription Using API

This tutorial introduces the request parameters and provides a request example to show you how to switch Linkus Cloud Service subscription for the desired PBX using API.

Before you begin: Understand the request parameters

Before switching Linkus Cloud Service subscription using API, we recommend that you read the table below to understand the request parameters and collect the corresponding values.


Item	Parameter	Description
Operation Type	`operationType`	The operation type. In this scenario, the value is fixed at `switch_plan`.
Product ID	`productId`	Specify the product for which you want to switch subscription. The Product ID for Linkus Cloud Service is `9`.
PBX Serial Number (SN)	`productNo`	Specify the device for which you want to switch Linkus Cloud Service subscription. You will need to query the PBX SN as described in the following steps.
Billing Contact ID	`billingId`	Specify the contact who can receive the invoice after you switch Linkus Cloud Service subscription. You will need to query the Billing Contact ID as described in the following steps.
Plan Type	`serviceType`	The plan type. In this scenario, the value is fixed at `plan`.
Plan ID	`serviceId`	Specify the specific plan to which you want to switch. You will need to query the Plan ID as described in the following steps.
Purchase Type	`purchaseType`	The purchase type. In this scenario, the value is fixed at `switch`.
Billing Model	`billingModel`	The billing model. In this scenario, the value is fixed at `recurring`.
Billing Cycle	`billingCycle`	The billing cycle. In this scenario, the value is fixed at `annually`.
Multi Cycle	`multiCycle`	The interval of recurring billing. Valid value: `1`, `2`, `3`, `4`, `5` Important: If you switch from Linkus Cloud Service to Linkus Cloud Service Pro, you can NOT change the interval of recurring billing. For example, if a PBX has been subscribed to Linkus Cloud Service for 1 year and is to be switched to Linkus Cloud Service Pro, then the value of Multi Cycle can only be `1`.

Step 1. Get Serial Number (SN) from PBX web portal

On PBX web portal, click (Resource Monitor).
Scroll down to Information section, then note down the Serial Number.

Step 2. Get plan ID

Make a request to the Query Available Subscription / Trial Plans and Services for a Product API endpoint with the Product ID 9.
```
GET {base_url}/pricing/openapi/purchase/v1/purchase_product_info?productId=9
```
Note down the returned value of planId for the desired plan.

Step 3. Get billing contact ID

Make a request to the Query Billing Contact List API endpoint.

GET {base_url}/user/openapi/user/v1/client/billing_contact_list

Note down the returned value of billingContactId for the desired billing contact.

Step 4. Switch Linkus Cloud Service subscription

Make a request to the Create an Order API endpoint with the collected values.

POST {base_url}/order/openapi/order/v1/save

In this tutorial, the values we collect are shown below:


Item	Parameter	Value
Operation Type	`operationType`	switch_plan
Product ID	`productId`	9
PBX Serial Number (SN)	`productNo`	369471667338
Billing Contact ID	`billingId`	3197218168379846218
Plan Type	`serviceType`	plan
Plan ID	`serviceId`	3048918719332507648 (ID for Linkus Cloud Service Pro)
Purchase Type	`purchaseType`	switch
Billing Model	`billingModel`	recurring
Billing Cycle	`billingCycle`	annually
Multi Cycle	`multiCycle`	1

The sample request for switching from Linkus Cloud Service to Linkus Cloud Service Pro is shown below:

POST /order/openapi/order/v1/save HTTP/1.1
Host: openapi.partner.yeastar.com
Content-Type: application/json
User-Agent: OpenAPI
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsicmVzMSJdLCJYLU1TLVVTRVIiOiJ7XCJleHByXCI6XCIwXCIsXCJ0eXBlXCI6XCJwYXJ0bmVyXCIsXCJ1Y0lkXCI6XCIzMDc2OTE1NDU0NDY4NzY3NzQ0XCIsXCJ1c2VyQ29kZVwiOlwiUGFydG5lclwiLFwidXNlcklkXCI6XCIzMDc2OTE1NDU0NDg5NzM5MjY0XCIsXCJ1c2VybmFtZVwiOlwicGFydG5lcmV4YW1wbGVAb3V0bG9vay5jb21cIn0iLCJ1c2VyX25hbWUiOiJwYXJ0bmVyZXhhbXBsZUBvdXRsb29rLmNvbSIsInNjb3BlIjpbImFsbCJdLCJleHAiOjE3Mzk3MTc5MjYsInRva2VuX3R5cGUiOiJvcGVuYXBpIiwianRpIjoidmlzMkh0QkxaUStNQmxPbS9UdThWR1pyNFljPSIsImF1dGhvcml0aWVzIjpbIjc5Il0sImNsaWVudF9pZCI6IjE0NDI5NjM2ODBiMjM0YjA0YmRjZDVjMTZmODcyOWQ2In0.RPRoTJRkXCB4krDSwGRpUFyCfUVv2LHjIiBICA1pCiY

{
  "operationType": "switch_plan",
  "productId": 9,
  "productNo": "369471667338",
  "billingId": 3197218168379846218,
  "serviceList": [
    {
      "serviceType": "plan",
      "serviceId": 3048918719332507648,
      "purchaseType": "switch",
      "billingModel": "recurring",
      "billingCycle": "annually",
      "multiCycle": 1
    }
  ]
}

Result

The sample response is shown below:

{
    "code": "success",
    "detailMessage": "",
    "requestId": "9bfe0453dccd45b49957811e0a8f3c99",
    "result": {
        "instanceId": "106396",
        "orderNo": "BF3206196711837917184",
        "orderStatus": "succeed",
        "productNo": "369471667338",
        "transactionNo": "YJ3206196712509005825"
    },
    "status": 200
}