Tutorial: Renew P-Series Software Edition Using API

This tutorial introduces the request parameters and provides a request example to show you how to renew P-Series Software Edition using API.

Before you begin: Understand the request parameters

Before renewing P-Series Software Edition using API, we recommend that you read the table below to understand the request parameters and collect the corresponding values.

Note: If the desired software PBX has been subscribed to both plan and service, you will need to renew both of them at the same time.


Item	Parameter	Description
Operation Type	`operationType`	The operation type. In this scenario, the value is fixed at `renew_plan`.
Product ID	`productId`	Specify the product that you want to renew. The Product ID for P-Series Software Edition is `12`.
PBX Serial Number (SN)	`productNo`	Specify the device that you want to renew. 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 renew P-Series Software Edition. You will need to query the Billing Contact ID as described in the following steps.
Plan Type & Service Type	`serviceType`	When renewing plan, the value is fixed at `plan`. When renewing service, the value is fixed at `service`.
Plan ID & Service ID	`serviceId`	Specify the specific plan and service that you want to renew. You will need to query the information as described in the following steps.
Connection Plan ID	`connectionPlanId`	Optional. Specify the current subscription plan. Note: This parameter is required only when you renew both plan and service, and it should be the same as Plan ID.
Quantity	`quantity`	Specify the number of extensions that you want to renew. Note: The value must be exactly the same as the current number of extensions.
Purchase Type	`purchaseType`	The purchase type. In this scenario, the value is fixed at `renew`.
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`

Step 1. Get Serial Number (SN)

Make a request to the Query Product List API endpoint with the Product ID 12.
```
GET {base_url}/product/openapi/instance_product/v1/client/instance_product_list?productId=12
```
Note down the returned value of productNo for the desired Software PBX.

Step 2. Get plan ID and service ID

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

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. Renew P-Series Software Edition

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`	renew_plan
Product ID	`productId`	12
PBX Serial Number (SN)	`productNo`	3651D4485749
Billing Contact ID	`billingId`	3197218168379846218
Plan Type	`serviceType`	plan
Plan ID	`serviceId`	3049041101760282624 (ID for Enterprise Plan)
Quantity	`quantity`	100
Purchase Type	`purchaseType`	renew
Billing Model	`billingModel`	recurring
Billing Cycle	`billingCycle`	annually
Multi Cycle	`multiCycle`	1

The sample request to renew P-Series Software Edition for 1 year 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": "renew_plan",
  "productId": 12,
  "productNo": "3651D4485749",
  "billingId": 3197218168379846218,
  "serviceList": [
    {
      "serviceType": "plan",
      "serviceId": 3049041101760282624,
      "quantity": 100,
      "purchaseType": "renew",
      "billingModel": "recurring",
      "billingCycle": "annually",
      "multiCycle": 1
    }
  ]
}

Result

The sample response is shown below:

{
    "code": "success",
    "detailMessage": "",
    "requestId": "f7d4de6098f89893849102a193d58cb5",
    "result": {
        "instanceId": "1155954",
        "orderNo": "SH3206263865014738944",
        "orderStatus": "succeed",
        "productNo": "3651D4485749",
        "transactionNo": "BS3206263866281418753"
    },
    "status": 200
}