CloudStore API endpoints

This document is intended as a reference for working with the Cloudstore API.
The CloudStore API is a collection of endpoints that enable you to place, change, renew or cancel orders in the 2tCloud Platform. You can register new customers, get an overview of all active subscriptions for that customer for subscription management purposes, and order new subscriptions.
More details on each endpoint can be found in this reference guide.

Take a note of the OAuth Base URL in the screenshot above. You will get a different URL, most likely https://portal.cloudnet.services.  You need to prepend that URL to all endpoints described below.

Sending requests

You send a request to a specific endpoint, with headers to identify yourself, with a specific method, and with optional parameters. You need to know the Base URL in advance. 

For example:

Item

Description

URL

https://portal.cloudnet.services/aps/2/collections/service-plans

HTTP headers

OAuth oauth_consumer_key="VFTRnNEgsqt7nRL05vIvdirG0Dj2sVj8",oauth_signature_method="HMAC-SHA1",oauth_timestamp="1613642599",oauth_nonce="9MkVTAHZ4XV",oauth_version="1.0",oauth_signature="sUFt3q3CYjkzRlTsrSAYc%2BlRz9c%3D"

Method

GET

You can use Postman to specify these details. Note that the method and the URL are on the top left, and you can specify the key and secret in the authorization tab:

The key and secret that you fill in at the Authorization tab are automatically converted to the correct HTTP header.  You can verify that header in the Headers tab.

By clicking on the Code link, you will receive various examples of how to use code in various languages to connect.

If you send parameters in a POST command, you can click on the Body tab, and specify the Json content.  Make sure to also select the content type to JSON as shown below : 

 

Get available service plans

Item

Description

URL

/aps/2/collections/service-plans

Method

GET

 

A list of all available service plans will be returned in the following format:

[
    {
        "name": {
            "en_US": "Hosted Exchange Basic 2013",
            "fr_FR": "Hosted Exchange Basic 2013",
            "nl_NL": "Hosted Exchange Basic 2013"
        },
        "planId": 93530,
        "publication": {
            "published": false
        },
        "billingTerms": {
            "model": "CHARGE_BEFORE_SUBSCRIPTION_PERIOD",
            "period": {
                "unit": "STATEMENT_DAY",
                "duration": 1
            },
            "autorenewal": {
                "days": 1,
                "type": "BEFORE_EXPIRATION_DATE"
            },
            "recurringPricesEvery": "BILLING_PERIOD"
        },
        "resourceRates": [
 
       ...
 
       ]
 
    }
 
]
CODE

Note that the name of each plan is available in multiple languages, and you can identify the planId from the response.


 

Get all available resources

 

Item

Description

URL

/aps/2/collections/bss-resources

Method

GET

 

A list of all available resources will be returned in the following format:

[
    {
        "id": 1003711,
        "MPN": "0a590a70-13fa-4cf4-996e-7c7da8055491",
        "name": {
            "en_US": "Microsoft Stream Storage Add-On (500 GB) for students",
            "fr_FR": "Microsoft Stream Storage Add-On (500 GB) for students",
            "nl_NL": "Microsoft Stream Storage Add-On (500 GB) for students"
        },
        "vendorId": "Microsoft",
        "vendorName": "Microsoft",
        "unitOfMeasure": {
            "en_US": "License",
            "fr_FR": "Licence",
            "nl_NL": "Licentie"
        },
        "aps": {
            "modified": "2021-02-16T11:48:04Z",
            "id": "ebd5884b-9902-4c33-950c-50d35e1427f4",
            "type": "http://www.odin.com/billing/Resource/1.3",
            "status": "aps:ready",
            "revision": 4
        }
    },
     ...
]
CODE

Note that you can identify the name of each resource in multiple languages, and the Id of the resource can be determined.

 


 

Get service plan details

 

Item

Description

URL

/aps/2/resources/452a91b7-d565-4f47-904a-8aac8d9c0628

Method

GET

When you know the ID of a specific plan, you can get the plan details. The response looks like: 

{
    "name": {
        "en_US": "NCE Microsoft Azure Reserved Instances",
        "fr_FR": "NCE Microsoft Azure Reserved Instances",
        "nl_NL": "NCE Microsoft Azure Reserved Instances"
    },
    "planId": 1798135,
    "publication": {
        "published": true
    },
...
}
CODE

 


 

Get service plan resources

 

Item

Description

URL

/aps/2/resources/452a91b7-d565-4f47-904a-8aac8d9c0628/resources

Method

GET

When you know the ID of a specific plan, you can get the available resources for that particular plan with this query. The response looks like:

[
    {
        "unitOfMeasure": {
            "en_US": "Unit(s)",
            "fr_FR": "Unité(s)",
            "nl_NL": "Stuk(s)"
        },
        "aps": {
            "modified": "2021-02-22T11:23:15Z",
            "id": "27e90c64-7277-4862-8993-4b3280a1690c",
            "type": "http://www.odin.com/billing/Resource/1.3",
            "status": "aps:ready",
            "revision": 2
        },
        "name": {
            "en_US": "Azure RI",
            "fr_FR": "Azure RI",
            "nl_NL": "Azure RI"
        },
...
}]
CODE


 

Create a customer account

 

Item

Description

URL

/aps/2/resources

Method

POST

First you must make an a customer account.  Post the following data to create an account.  Substitute with the correct data for the account you want to create:

[
    {
        "aps": {
            "type": "http://parallels.com/pa/bss-account-info/1.0",
            "id": "ceeeffac-d2f2-4e36-ae4a-3fe27ed58097"
        },
        "taxStatus": "COMPANY",
        "localeId": "en_US"
    },
    {
        "aps": {
            "type": "http://parallels.com/aps/types/pa/account/1.2"
        },
        "type": "CLIENT",
        "personal": false,
        "companyName": "1st APS inc",
        "bssAccountInfo": {
            "aps": {
                "id": "ceeeffac-d2f2-4e36-ae4a-3fe27ed58097"
            }
        },
        "addressPostal": {
            "countryName": "us",
            "locality": "APS",
            "postalCode": "12345",
            "region": "VA",
            "streetAddress": "11, APS"
        },
        "adminContact": {
            "email": "isv1@aps.test",
            "givenName": "Mike",
            "familyName": "Wilson",
            "telVoice": "1#888#1234567"
        },
        "billingContact": {
            "email": "isv1@aps.test",
            "givenName": "Mike",
            "familyName": "Wilson",
            "telVoice": "1#888#1234567"
        },
        "techContact": {
            "email": "isv1@aps.test",
            "givenName": "Mike",
            "familyName": "Wilson",
            "telVoice": "1#888#1234567"
        }
    }
]
CODE

Note that you must also create a user for the account. See following steps.

 


 

Get list of accounts

 

Item

Description

URL

/aps/2/collections/accounts

Method

GET

This will return a list of all accounts. Note that you can get the APS id of the account in this section: 

 

...,

"aps": {
            "modified": "2021-02-22T11:04:47Z",
            "id": "b5369636-94c8-4768-a180-d88d485a93ba",
            "type": "http://parallels.com/aps/types/pa/account/1.2",
            "status": "aps:ready",
            "revision": 4
        },

...

Do not use the nummeric ID field that contains only numbers, like 123456, but always use the Guid type ID's.

 


 

Create a user for the created account

 

Item

Description

URL

/aps/2/resources/b5369636-94c8-4768-a180-d88d485a93ba/users/

Method

POST

Post the following data to create a user. In the URL you must place the ID of the created account. You can get that ID by using the list of accounts. Substitute below with the correct data for the user:

{
   "aps": {
      "type": "http://parallels.com/aps/types/pa/admin-user/1.2"
   },
   "isAccountAdmin": true,
   "login": "mw@aps.test",
   "password": "p@$$w0rd",
   "email": "mw@aps.test",
   "givenName": "Mike",
   "familyName": "Wilson",
   "telVoice": "1(888)1234567",
   "addressPostal": {
      "streetAddress":"11, ISVone",
      "locality":"Herndon",
      "region":"VA",
      "countryName":"us",
      "postalCode":"12345"
   }
}
CODE

 


 

Place an order

 

Item

Description

URL

/aps/2/services/order-manager/orders

Method

POST

Parameters

  • The ID of the Customer Account

  • The ID of the Plan

  • The Subscription period

  • (optionally) Additional Resources

  • (optionally) Parameters required for the underlying APS or plan, such as Office 365

  • AcceptedTerms, some Plans require that you accept terms of use(s)

  • PaymentMethodId, default 0 for 'pay via invoice'

Important !  Substitute the accountId, planId and resourceId with valid values.

Example:

{
    "type": "SALES",
    "accountId": "3fef9702-b2ad-419a-9924-a56882e5f06c",
    "promoCode": "123",
    "paymentMethodId": "3",
    "products": [
        {
            "planId": "ae0e6e84-0d37-4b17-8f6c-5709633529ab",
            "period": {
                "unit": "MONTHS",
                "duration": 1
            },
            "resources": [
                {
                    "resourceId": "1c3ab0be-3160-45a1-a9b4-7824f74673ff",
                    "amount": 40
                }
            ],
            "parameters": [
                {
                    "aps": {
                        "type": "http://aps-standard.org/samples/vpsdemo/management/1.0"
                    },
                    "client": "1st APS, inc.",
                    "mail": "jsmith@aps.test"
                }
            ],
            "childProducts": [
                { // Another service plan - upsell
                }
            ]
        },
        { // Another service plan
        }
    ],
    "attributes": [
        {
            "attributeID": "comments",
            "value": "Requested by the ERP system."
        }
    ],
    "acceptedTerms": [
        "1"
    ],
    "specialPricing": { // See the "Set Special Prices" section for details
    }
}
CODE

 

Example for ordering Office 365:

{
    "type": "SALES",
    "accountId": "ceeeffac-d2f2-4e36-ae4a-3fe27ed58098",
    "paymentMethodId": "0",
    "products": [
        {
            "planId": "cdc7dbd7-977a-4f48-8d17-4f9847c090f5",
            "period": {
                "unit": "MONTHS",
                "duration": 1
            },
            "parameters": [
                {
                    "Type": "http://www.parallels.com/Office365/Tenant/2.8",
                    "Param": {
                        "Subdomain": "CopacoOfficeTest12",
                        "Email": "admin@CopacoOfficeTest6.onmicrosoft.com",
                        "FirstName": "first",
                        "LastName": "last",
                        "Phone": "123"
                    }
                }
            ]
        }
    ],
    "acceptedTerms": [
        "1"
    ]
}
CODE

 

Get orders

 

Item

Description

URL

/aps/2/services/order-manager/orders

Method

GET

This will return a list of all orders.

You can optionally add additional filters to the URL. In this case, a request will look as follows:

GET /aps/2/services/order-manager/orders?in({property},{value}),select({linkToResources}),ge(creationDate,{fromDate}),le(creationDate,{toDate}),like(number,*000001),limit({from},{to})
CODE

The following functions can be used:

·       in verifies whether a property is in a specified list, for example, request only sales orders and billing orders:

·       in(type,(SO,BO))
CODE

The following properties are allowed in the function:

o   resellerId is the APS ID of the reseller that provides the ordered services.

o   customerId is the APS ID of the customer that placed the order.

o   endCustomerName is a customer name.

o   endCustomerType is an account type (“PROVIDER”, “RESELLER”, or “CUSTOMER”).

o   ID of an order or account attribute.

o   internalId is and integer showing an order unique ID in the platform.

o   orderId is a string showing an order unique APS ID.

o   orderNumber is a string ID assigned by the platform to an order, for example, “SO000004”.

o   status is an order status.

o   type is an order type. The most common types for API are in the following list:

§  BO is a billing order generated at the end of a billing period usually to bill an account for resources consumed during the passed billing period.

§  CL is a cancellation order generated when a subscription is cancelled and the sales vendor owns money to the customer.

§  CF is a cancellation order generated when a subscription is cancelled and the customer owns money to the sales vendor.

§  RN is a renewal order created when a subscription must be renewed for the next period.

§  SO is a sales order that contains a request for certain service plans.

§  CH is a change order that a subscriber uses to change a subscription.

o   provisioningStatus is an order provisioning status.

o   paymentStatus is the payment status of an order.

o   subscriptionId is the APS ID of the subscription whose orders are requested.

NOTE

A list of order attribute IDs and account attribute IDs is created by the provider using the control panel. Those IDs are unique within the platform.

·       like verifies if a property matches a wildcard mask that uses the wildcard symbols * and ?. Currently, this function is applicable to orderNumber, endCustomerName, and attribute IDs (either account or order attributes).

Example of filtering by order number:

like(orderNumber,*00001)
CODE

Example of filtering by attribute ID:

like(ORDER_ID1,test1234)
CODE

·       ge and le (respectively “Greater or Equal” and “Lower or Equal”) functions are applicable to the internal ID and the date-time properties to select the orders in a certain date and time interval:

o   internalId

o   creationTime

o   orderDate

o   expirationDate

For example, seek for orders created in the specified time period:

ge(creationTime,2018-04-26T16:00:00Z),le(creationTime,2018-04-26T18:00:00Z)
CODE

·       limit fetches orders in a range of numbers, for example get orders in the range of 0 to 9:

limit(0,9)
CODE


 

Get subscriptions

 

Item

Description

URL

/aps/2/collections/bss-subscriptions

Method

GET

This will return a list of all subscriptions.

You can optionally specify parameters in the query:

·       Get all subscriptions of a customer using a filter:

·       GET /aps/2/collections/bss-subscriptions?account.aps.id=7fd20173-b11e-4459-8e95-ff4810eb1ebd
CODE

The above request contains the APS ID of a customer.

·       Search for a subscription using a property with a unique value, for example, search it by name:

GET /aps/2/collections/subscriptions?like(name,*Demo*)
CODE

 


 

Change subscription

 

Item

Description

URL

/aps/2/services/order-manager/orders

Method

POST

Example to change the duration for a subscription:

{
   "type": "CHANGE",
   "subscriptionId": "456808a0-b5a6-4092-ab67-b77e33743a07",
   "planId": "ae0e6e84-0d37-4b17-8f6c-5709633529ab",
   "paymentMethodId": "11",
   "period": {
      "unit": "MONTHS",
      "duration": 3
   }
}
CODE

Example to add additional amount of resources:

 

{
   "type": "CHANGE",
   "subscriptionId": "4c867c87-fbf7-49e8-9f7e-0d06e8f7a003", 
   "paymentMethodId": "11", 
   "resources": [{
       "resourceId": "bf8ea705-3f2b-4f3c-b445-a11ec100da82", 
       "amount": 10 
   }]
}
CODE

 


 

Cancel subscription

 

Item

Description

URL

/aps/2/services/order-manager/orders

Method

POST

You need to provide the Id of an existing subscription, for example: 

{
   "type": "CANCELLATION",
   "subscriptionId": "456808a0-b5a6-4092-ab67-b77e33743a07",
   "refundType": "CREDIT_MEMO"
}
CODE


 

Renew subscription

 

Item

Description

URL

/aps/2/services/order-manager/orders

Method

POST

Example to renew a subscription:

{
   "type": "RENEWAL",
   "subscriptionId": "456808a0-b5a6-4092-ab67-b77e33743a07",
   "paymentMethodId": "11",
   "period": {
      "unit": "MONTHS",
      "duration": 1
   }
}
CODE