License Creation/Renewal/Upgrade Request

The Create new, Renew and Upgrade scenarios use the same request format.

  • Create new is needed to create new license keys.
  • Renew is needed to prolong license keys.
  • Upgrade scenario is needed when multiple sales options are available and it is necessary to switch between them.

In this chapter:

Request

Response

Examples

 

Request

The HTTP POST request is made for a specified endpoint with the following parameters:

Name Size (Characters) Description

APS_PROTOCOL_MODEL

1

2 - Standard implementation is expected.

3 - With reporting implementation with Get License Key Info Request support is expected.

When this field is absent, Standard (2) must be assumed.

APS_ACTION

up to 30

  • PURCHASE for the Create new scenarios.
  • RENEW for the Renew scenarios.
  • UPGRADE for the Upgrade scenarios.

APS_TEST_MODE

1

Y means that the order is a test one. The license key generated must not be accounted towards the billing report; it could be a fake one though issuing a key that can be successfully installed into an application is advised.

N or missing this field means that the order is real.

ACTIVATION_DATA

unlimited

Activation data is a packet of tech data required to obtain a valid application license. This parameter is specific to every extension. Some examples of activation data include:

  • White IP address
  • Domain name
  • Hardware ID
  • Global unique identifier (GUID)

This parameter is optional. You can omit it if the license does not require any activation data.

PURCHASE_ID

up to 10

KA license number (without prefix and version).

Example: If the full license number is EXT.00123456.0012, then only 00123456 will be passed in this field.

PRODUCT_ID

up to 30

ID/SKU of the product purchased.

The ISV endpoint should be aware of this ID/SKU in order to distinguish between various products (if multiple products are offered).

PURCHASE_DATE

10

The date of purchase in the format DD/MM/YYYY, e.g., 12/03/2016.

This date corresponds to the date when the current license key action has been initiated, with no regard to the license validity date or initial subscription date.

SUBSCRIPTION_DATE

10

Date of subscription (the DD/MM/YYYY format). This date indicates the original date when the license key has been created.

When an existing license is upgraded or renewed, this date would stay the same, while the PURCHASE_DATE will change.

START_DATE

10

Start date of the current re-billing period (the DD/MM/YYYY format).

In KA this is the start date of the license key validity period.

In case of a renew request, START_DATE will be different from what was sent in the first license creation request for the same PURCHASE_ID.

EXPIRY_DATE

10

Expiry date (date of the next re-billing) (the DD/MM/YYYY format).

This is the next re-billing deadline; KA calculates it by adding the update period (1 calendar month) and the grace period (10 days) to the START_DATE.

In case of a renew request, EXPIRY_DATE will be different from what was sent in the first license creation request for the same PURCHASE_ID.

PREVIOUS_LICENSE_BODY

unlimited

This parameter holds the license body that was previously saved in KA. The license body is encoded in BASE64.

This parameter is passed only with the RENEW and UPGRADE requests.

REG_NAME

up to 100

Internal ID of the license owner in KA.

LASTNAME

up to 50

These properties are taken from the corresponding KA license owner information fields.

Note: Often a license owner and a Plesk instance owner are not the same entity: a license owner might be a big reseller company that runs their business on selling Plesk to smaller hosting companies, while a Plesk instance owner might be a hosting company.

FIRSTNAME

up to 50

COMPANY

up to 100

EMAIL

up to 100

PHONE

up to 50

FAX

up to 50

STREET

up to 100

CITY

up to 100

ZIP

up to 20

STATE

up to 40

COUNTRY

up to 50

Notes:

  • Ordering of the fields is not guaranteed.
  • Additional fields might be added in future. In case an unknown field is encountered while processing the request, the implementation should ignore it (i.e., process the request as if such field is absent).
 

Response

In case the request is successfully processed, the implementation should send the response with the status code 200 OK. The following table describes the data returned in the successful response:

Location Meaning Comments

Response body

License body

The license body data must be delivered to the ISV application in exactly the same form as provided in the response body. No transformations are permitted regardless of the content type.

The exact format of the body should be defined by ISV (can be binary or any kind of textual data - does not matter). The ISV application should be able to recognize this body as a valid key to unlock certain functionality for the end user.

X-APS-Expiration-Date response header

Expiration date

(HTTP Date, RFC 1123)

The ISV endpoint must return expiration date for the generated license key. The ISV endpoint should return the date matching the one requested in the EXPIRY_FIELD.

The expiration date specified in the response should be always used instead of the one requested.

In case the request fails, the implementation should return the appropriate status code and a brief explanation of the reasons of the failure.

The recommended response codes are:

Status Code Possible Reasons KA Responsibility

200 OK

The license key generation is successful

Get the license body from the response, wrap it appropriately and deliver to the ISV application.

400 Bad Request

  • Invalid field value
  • Too big field value
  • Invalid combination of property values

Return the appropriate failure message to the party that issued the original request.

401 Unauthorized

KA did not send an appropriate authentication header

Normally, should not be observed.

403 Forbidden

Authorization failed

Return an appropriate failure message to the administrator responsible for the integration and to the party that issued the original request.

4xx

Any other issue with the request

Return the appropriate failure message to the party that issued the original request.

5xx

Server error

Return the appropriate failure message to the party that issued the original request.

 

Examples

Correct PURCHASE request:

POST /handler.php HTTP/1.1
Accept: */*
Content-Type: application/x-www-form-urlencoded
Host: isv.endpoint.example.org
Authorization: Basic am9objpxd2UxMjM=

APS_PROTOCOL_MODEL=2&APS_ACTION=PURCHASE&APS_TEST_MODE=N&PURCHASE_ID=12345678&PRODUCT_ID=someproduct1&PURCHASE_DATE=12%5c03%5c2016&SUBSCRIPTION_DATE=12%5c03%5c2016&START_DATE=12%5c03%5c2016&EXPIRY_DATE=22%5c04%5c2016&REG_NAME=54321&LASTNAME=Smith&FIRSTNAME=John&COMPANY=Acme%2c+Inc.&EMAIL=john%40example.org&PHONE=111-222-333&FAX=111-222-345&STREET=Park+Lane%2c+333&CITY=New+York&ZIP=11415&STATE=NY&COUNTRY=US

Successful PURCHASE response with a binary license body:

HTTP/1.1 200 OK
Date: Thu, 12 Mar 2016 15:02:10 GMT
Server: Web Server
X-APS-Expiration-Date: Fri, 22 Apr 2016 15:02:10 GMT
Content-Type: application/octet-stream

<response body bytes go here>

Correct RENEW request:

POST /handler.php HTTP/1.1
Accept: */*
Content-Type: application/x-www-form-urlencoded
Host: isv.endpoint.example.org
Authorization: Basic am9objpxd2UxMjM=

APS_PROTOCOL_MODEL=2&APS_ACTION=RENEW&APS_TEST_MODE=N&PURCHASE_ID=12345678&PRODUCT_ID=someproduct1&PURCHASE_DATE=12%5c04%5c2016&SUBSCRIPTION_DATE=12%5c03%5c2016&START_DATE=12%5c04%5c2016&EXPIRY_DATE=22%5c05%5c2016&PREVIOUS_LICENSE_BODY=NCA4IDE1IDE2IDIzIDQy&REG_NAME=54321&LASTNAME=Smith&FIRSTNAME=John&COMPANY=Acme%2c+Inc.&EMAIL=john%40example.org&PHONE=111-222-333&FAX=111-222-345&STREET=Park+Lane%2c+333&CITY=New+York&ZIP=11415&STATE=NY&COUNTRY=US

Successful RENEW response with a binary license body:

HTTP/1.1 200 OK
Date: Thu, 12 Mar 2016 15:02:10 GMT
Server: Web Server
X-APS-Expiration-Date: Sun, 22 May 2016 15:02:10 GMT
Content-Type: application/octet-stream

<response body bytes go here>

Incorrect request (an invalid EXPIRY_DATE is specified):

POST /handler.php HTTP/1.1
Accept: */*
Content-Type: application/x-www-form-urlencoded
Host: isv.endpoint.example.org
Authorization: Basic am9objpxd2UxMjM=

APS_PROTOCOL_MODEL=2&APS_ACTION=PURCHASE&APS_TEST_MODE=N&PURCHASE_ID=12345678&PRODUCT_ID=someproduct1&PURCHASE_DATE=12%5c03%5c2016&SUBSCRIPTION_DATE=12%5c03%5c2016&START_DATE=12%5c03%5c2016&EXPIRY_DATE=22%5c04%5c2015&REG_NAME=54321&LASTNAME=Smith&FIRSTNAME=John&COMPANY=Acme%2c+Inc.&EMAIL=john%40example.org&PHONE=111-222-333&FAX=111-222-345&STREET=Park+Lane%2c+333&CITY=New+York&ZIP=11415&STATE=NY&COUNTRY=US

Error response:

HTTP/1.1 400 Bad Request
Date: Thu, 12 Mar 2016 15:02:10 GMT
Server: Web Server
Content-Type: text/plain; charset=UTF-8

Error: Subscription expiration date cannot be less than subscription start date

Unauthorized response:

HTTP/1.1 401 Unauthorized
Date: Thu, 12 Mar 2016 15:02:10 GMT
Server: Web Server
Content-Type: text/plain; charset=UTF-8
WWW-Authenticate: Basic realm="License Key Generator"

Error: No credentials supplied. Please authorize

Authorization failed response:

HTTP/1.1 401 Forbidden
Date: Thu, 12 Mar 2016 15:02:10 GMT
Server: Web Server
Content-Type: text/plain; charset=UTF-8

Error: Access denied
 

Leave your feedback on this topic here

If you have questions or need support, please visit the Plesk forum or contact your hosting provider.
The comments below are for feedback on the documentation only. No timely answers or help will be provided.