Creating a Subscription

To register a new subscription, it is enough to specify some general setup information. If the subscription is created by Administrator or reseller, the subscription owner needs to be specified too. In addition, you can specify various settings when creating a subscription.

A subscription can have all these settings specified, or it can hold just some of them. You can specify settings on creation or later (they can be set using the set operation). The only exception from this rule is a service plan: it cannot be applied to a subscription after it is created. To learn more about the service plan management via API RPC, proceed to section Managing Service Plans.

In this chapter:

Request Packet Structure

Response Packet Structure

Samples

 

Request Packet Structure

A request XML packet adding a new subscription to Plesk database includes the add operation node:

<packet>
<webspace>
   <add>
   ...
   </add>
</webspace>
</packet>

 

The add node does not have a separate type, it is nested within the complex type (domain_input.xsd). The add node has the following graphics representation:

webspace_add

Note: The interactive schema navigator for all request packets is available here: http://plesk.github.io/api-schemas/1.6.8.0/agent_input.svg.

  • The gen_setup node is required. It is used to specify the most important information about the subscription, that is: its name, the Plesk user who owns it, the hosting type used for this subscription, the IP address associated with the subscription, and other information. Data type: setGenSetupType (plesk_domain.xsd). See the structure of this node in the General Account Information section.
  • The hosting node is optional. It specified hosting settings set for the subscription. Data type: domainHostingAgentSet (plesk_domain.xsd). See the structure of this node in the Hosting Settings section.
  • The limits node is optional. It specifies limits imposed on use of Plesk resources for this subscription. Data type: domainLimits (plesk_domain.xsd). See the structure of this node in the Limits section.
  • The prefs node is optional. It specifies a collection of subscription preferences. Data type: domainPrefs (plesk_domain.xsd). See the structure of this node in the Subscription Preferences section.
  • The performance node is optional. It specifies a collection of Web site performance settings (bandwidth, the maximal number of connections). Data type: DomainPerformanceType (plesk_domain.xsd).
    Should be added only if the hosting type is physical hosting.
    See the structure of this node in the Performance Settings section.
  • The permissions node is optional. It specifies a list of services and privileges provided with the subscription. Data type: domainPerms (plesk_domain.xsd). See the section Permissions for details.
  • The php-settings node is optional. It specifies custom PHP settings that will act as a preset for all domains within the subscription. Data type: phpSettings (plesk_domain.xsd). See the section PHP Settings for details.
  • The plan-id node is optional. It specifies the service plan by ID if it is necessary to create a subscription to a certain service plan. Data type: integer. To learn more about service plans, proceed to section Managing Service Plans.
  • The plan-name node is optional. It specifies the service plan by name if it is necessary to create a subscription to a certain service plan. Data type: string. To learn more about service plans, proceed to section Managing Service Plans.

    Note: You can use only service plans to which the XML API requester has access.

  •  The plan-guid node is optional. It specifies the service plan by GUID if it is necessary to create a subscription to a certain service plan. Data type: string. To learn more about service plans, proceed to section Managing Service Plans.
  •  The plan-external-id node is optional. It specifies the ID of a service plan in the Plesk components (f.e, Business Manager). Data type: string. To learn more about service plans, proceed to section Managing Service Plans.

Important: When creating request packets, put nodes and elements in the order they follow in the packet structure.

 

Response Packet Structure

The add node of the response packet is structured as follows:

Note: The interactive schema navigator for all response packets is available here: http://plesk.github.io/api-schemas/1.6.8.0/agent_output.svg.

  • The result node is required. It wraps the result of the requested add operation. Data type: resultType (common.xsd).
  • The status node is required. It returns the execution status of the add operation. Data type: string. Allowed values: ok | error.
  • The errcode node is optional. Is used to return the error code when the add operation fails. Data type: unsignedInt.
  • The errtext node is optional. Can be used to return an error message if the add operation fails. Data type: string.
  • The id node is required if the add operation succeeds. Returns the unique identifier of a subscription just added to Plesk. Data type: integer.
  • The guid node is required if the add operation succeeds. Returns the global unique identifier of the subscription just added to Plesk. Data type: string.
 

Samples

Creating subscriptions under different Plesk users

Subscriptions can be created by the Administrator, resellers, or customers.

Here is a sample request packet that can be used by a customer to create a web hosting subscription. The account is created with a minimal collection of Web hosting settings.

<packet>
<webspace>
    <add>
      <gen_setup>
        <name>sample.com</name>
        <ip_address>10.58.103.100</ip_address>
      </gen_setup>
      <hosting>
        <vrt_hst>
          <property>
            <name>ftp_login</name>
            <value>ftp16se4fdf0</value>
          </property>
          <property>
            <name>ftp_password</name>
            <value>qweqwe</value>
          </property>
          <ip_address>10.58.103.100</ip_address>
        </vrt_hst>
      </hosting>
    </add>
  </webspace>
</packet>

Response:

<?xml version="1.0" encoding="UTF-8"?>
<packet version="1.6.7.0">
  <webspace>
    <add>
      <result>
        <status>ok</status>
        <id>4</id>
        <guid>5ff343c1-a40b-4305-8986-2f27c240db7e</guid>
      </result>
    </add>
  </webspace>
</packet>

The following packet creates a subscription for customer with ID 1234:

<packet>
<webspace>
<add>
   <gen_setup>
      <name>example.com</name>
      <owner-id>1234</owner-id>
      <htype>vrt_hst</htype>
      <ip_address>192.0.2.123</ip_address>
      <status>0</status>
   </gen_setup>
   <hosting>
      <vrt_hst>
          <property>
            <name>ftp_login</name>
            <value>ftp16se4fdf0</value>
          </property>
          <property>
            <name>ftp_password</name>
            <value>qweqwe</value>
          </property>
          <ip_address>192.0.2.54</ip_address>
       </vrt_hst>
    </hosting>
</add>
</webspace>
</packet> 
Creating multiple subscriptions

To create two subscriptions with a single packet, include two different add nodes:

<packet>
<webspace>
<add>
   <gen_setup>
      <name>example.com</name>
      <htype>vrt_hst</htype>
      <ip_address>192.0.2.123</ip_address>
      <status>0</status>
   </gen_setup>
   <hosting>
      <vrt_hst>
		      <ip_address>192.0.2.123</ip_address>
      </vrt_hst>
    </hosting>
</add>
<add>
   <gen_setup>
      <name>sample.com</name>
      <ip_address>192.0.2.124</ip_address>
      <status>0</status>
   </gen_setup>
   <hosting>
      <vrt_hst>
			<property>
				<name>ssl</name>
				<value>false</value>
			</property>
    	      <ip_address>192.0.2.123</ip_address>
       </vrt_hst>
    </hosting>
</add>
</webspace>
</packet> 
Using a particular service plan

The following sample packet creates a subscription to a service plan Bronze.

<packet>
<webspace>
<add>
   <gen_setup>
      <name>example.com</name>
      <htype>vrt_hst</htype>
      <ip_address>192.0.2.123</ip_address>
      <status>0</status>
   </gen_setup>

   <hosting>
      <vrt_hst>
			<property>
				<name>ssl</name>
				<value>false</value>
			</property>
    	      <ip_address>192.0.2.123</ip_address>
       </vrt_hst>
    </hosting>
   <plan-name>base_template</plan-name>
</add>
</webspace>
</packet>

Note: To see the sample packets that set optional settings (hosting settings, limits, preferences, and others), refer to the related section in the Subscription Settings section.

 

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.