Tutorial: Purchase Commercial License for P-Series Software Edition Using API

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

Before you begin: Understand the request parameters

Before purchasing a commercial license for P-Series Software Edition 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 `purchase_plan`.
Product ID	`productId`	Specify the product to which you want to subscribe. The Product ID for P-Series Software Edition is `12`.
Partner ID	`partnerId`	Specify the user for whom you want to purchase a commercial license for P-Series Software Edition. Note: This parameter is required only when you purchase a NEW license for a subordinate user. You will need to query the information as described in the following steps.
PBX Serial Number (SN)	`productNo`	Specify the device for which you want to purchase commercial license. You will need to query the PBX SN as described in the following steps. Note: This parameter is required only when you purchase a commercial license for an EXISTING software PBX.
Billing Contact ID	`billingId`	Specify the contact who can receive the invoice after you purchase a commercial license. You will need to query the Billing Contact ID as described in the following steps.
Plan Type & Service Type	`serviceType`	When subscribing to plan, the value is fixed at `plan`. When subscribing to or trying service, the value is fixed at `service`.
Plan ID & Service ID	`serviceId`	Specify the specific plan and service to which you want to subscribe. You will need to query the information as described in the following steps.
Connection Plan ID	`connectionPlanId`	Optional. Specify the specific plan to which you want to subscribe. Note: This parameter is required only when you subscribe to both plan and service, and it should be the same as Plan ID.
Quantity	`quantity`	Specify the number of extensions to which you want to subscribe.
Purchase Type	`purchaseType`	The purchase type. In this scenario, the value is fixed at `purchase`.
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 subscribe to both plan and service, the value of the Multi Cycle must be exactly the same.

(Optional) Step 1. Get subordinate user ID or PBX Serial Number (SN)

Get subordinate user ID

Note: This is required only when you purchase a NEW license for a subordinate user. If you purchase a NEW license for yourself, you can skip this step.

Make a request to the Query Subordinate User List API endpoint.
```
GET {base_url}/user/openapi/user/v1/client/partner_list
```
Note down the returned value of partnerId for the desired subordinate user.

Get PBX Serial Number (SN)

Note: This parameter is required only when you purchase a commercial license for an EXISTING software PBX.

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. Purchase commercial license for 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`	purchase_plan
Product ID	`productId`	12
PBX Serial Number (SN)	`productNo`	3651E1292455
Billing Contact ID	`billingId`	3197218168379846218
Plan Type & Plan ID	`serviceType` & `serviceId`	`serviceType`: `plan` `serviceId`: `3049041101760282624` (ID for Ultimate Plan)
Service Type & Service ID	`serviceType` & `serviceId`	`serviceType`: `service` `serviceId`: `3129372068699893760` (ID for Disaster Recovery service) Note: Disaster Recovery is only supported on Ultimate Plan.
Connection Plan ID	`connectionPlanId`	3049041101760282624 (ID for Ultimate Plan)
Quantity	`quantity`	100
Purchase Type	`purchaseType`	purchase
Billing Model	`billingModel`	recurring
Billing Cycle	`billingCycle`	annually
Multi Cycle	`multiCycle`	2

The sample request to purchase a 2-year commercial license with 100 extensions, Ultimate Plan, and Disaster Recovery 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": "purchase_plan",
  "productId": 12, 
  "productNo": "3651E1292455", 
  "billingId": 3197218168379846218,
  "serviceList": [
    {
      "serviceType": "plan",
      "serviceId": 3049041101760282624,
      "quantity": 100,
      "purchaseType": "purchase",
      "billingModel": "recurring",
      "billingCycle": "annually",
      "multiCycle": 2
    },
    {
      "connectionPlanId":3049041101760282624,
      "serviceType": "service",
      "serviceId": 3129372068699893760,
      "purchaseType": "purchase",
      "billingModel": "recurring",
      "billingCycle": "annually",
      "multiCycle": 2
    }
  ]
}

Result

The sample response is shown below:

{
    "code": "success",
    "detailMessage": "",
    "requestId": "2f26962eacd60daaf624e69b5afacd73",
    "result": {
        "instanceId": "1282391",
        "orderNo": "ZC3206258125675945984",
        "orderStatus": "succeed",
        "productNo": "3651E1292455",
        "transactionNo": "AK3206258126833573889"
    },
    "status": 200
}