Subscriptions

Statuses

Every subscription has a status associated with it:

active: A subscription that is currently being used, either because the current time is between its start or end date or because it was the subscription for depletable resources (traffic) that is currently being used.

inactive: A subscription that is not currently being used, either because its not active yet or because there is another depletable resource (traffic) subscription being used.

expired: A subscription that has either expired or that has been depleted.

Listing

GET /subscriptions/

Gets the list of subscriptions of the user.

param status:: filters only subscriptions in that status. Can be one of active , inactive, expired, all, notexpired. Default is all.
param resource:: a list (comma separated) of resources. One or more of: dssd, cpu, mem, tx, ip, vlan.
statuscode 200:: no error

Example request:

GET /api/2.0/subscriptions/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 20,
        "offset": 0,
        "total_count": 5
    },
    "objects": [
        {
            "amount": "32212254720",
            "auto_renew": true,
            "descendants": [],
            "discount_amount": null,
            "discount_percent": null,
            "discounts": null,
            "end_time": "2015-08-26T12:00:00+00:00",
            "free_tier": false,
            "id": "14",
            "period": "365 days, 2:45:57.487493",
            "price": "0E-20",
            "remaining": "32212254720",
            "resource": "dssd",
            "resource_uri": "/api/2.0/subscriptions/14/",
            "start_time": "2014-08-26T09:14:02.512507+00:00",
            "status": "active",
            "subscribed_object": null,
            "uuid": "e067df3c-35c5-4327-927e-2ee52b6f796a",
            "was_billed": true
        },
        {
            "amount": "1",
            "auto_renew": true,
            "descendants": [],
            "discount_amount": null,
            "discount_percent": null,
            "discounts": null,
            "end_time": "2015-08-26T12:00:00+00:00",
            "free_tier": false,
            "id": "13",
            "period": "365 days, 2:46:06.019766",
            "price": "0E-20",
            "remaining": "1",
            "resource": "ip",
            "resource_uri": "/api/2.0/subscriptions/13/",
            "start_time": "2014-08-26T09:13:53.980234+00:00",
            "status": "active",
            "subscribed_object": "94.26.101.195",
            "uuid": "aa442254-08fa-4d36-b511-47d4aa3a303b",
            "was_billed": true
        },
        {
            "amount": "1",
            "auto_renew": true,
            "descendants": [],
            "discount_amount": null,
            "discount_percent": null,
            "discounts": null,
            "end_time": "2015-08-26T12:00:00+00:00",
            "free_tier": false,
            "id": "12",
            "period": "365 days, 2:46:12.563258",
            "price": "0E-20",
            "remaining": "1",
            "resource": "vlan",
            "resource_uri": "/api/2.0/subscriptions/12/",
            "start_time": "2014-08-26T09:13:47.436742+00:00",
            "status": "active",
            "subscribed_object": "10619300-edda-42ba-91e0-7e3df0689d00",
            "uuid": "e31585fb-6c3f-422d-a51e-395fd53fd2e5",
            "was_billed": true
        },
        {
            "amount": "17179869184",
            "auto_renew": true,
            "descendants": [],
            "discount_amount": null,
            "discount_percent": null,
            "discounts": null,
            "end_time": "2015-08-26T12:00:00+00:00",
            "free_tier": false,
            "id": "10",
            "period": "365 days, 2:46:54.269604",
            "price": "0E-20",
            "remaining": "17179869184",
            "resource": "mem",
            "resource_uri": "/api/2.0/subscriptions/10/",
            "start_time": "2014-08-26T09:13:05.730396+00:00",
            "status": "active",
            "subscribed_object": null,
            "uuid": "5830f712-6eef-4732-9dbd-6a9f3b1fcb2f",
            "was_billed": true
        },
        {
            "amount": "10000",
            "auto_renew": true,
            "descendants": [],
            "discount_amount": null,
            "discount_percent": null,
            "discounts": null,
            "end_time": "2015-08-26T12:00:00+00:00",
            "free_tier": false,
            "id": "9",
            "period": "365 days, 2:47:23.682426",
            "price": "0E-20",
            "remaining": "10000",
            "resource": "cpu",
            "resource_uri": "/api/2.0/subscriptions/9/",
            "start_time": "2014-08-26T09:12:36.317574+00:00",
            "status": "active",
            "subscribed_object": null,
            "uuid": "664fb99b-f8cc-4e85-8764-ef3215767682",
            "was_billed": true
        }
    ],
    "price": "0E-20"
}

Subscription duration

There are three parameters that determine the subscription’s duration. All times are in UTC. Not all combinations are valid:

start_time: In ISO 8601 format. Defaults to the current time.

end_time: In ISO 8601 format.

period: Free form text describing the period. Ex: ‘2 months 1 week’.

Inputs			Result
start_time	end_time	period
True	True	True	Error: Ambiguous.
True	True	False	Between start_time and end_time.
True	False	True	Period from start_time.
True	False	False	Error: Not specific enough.
False	True	True	Period until end_time.
False	True	False	From now until end_time.
False	False	True	Period from now.
False	False	False	Error: Not specific enough.

Creating

POST /subscriptions/

Status Codes:

201 Created – object created

Creates a new subscription. There is a limit of 500 subscriptions that can be purchased in one request.

The resource can be a license or one of: dssd (hdd is an alias for this, but is being deprecated), cpu, mem, tx, ip, vlan.

When buying tx, the time parameters are ignored.

Trying to purchase a subscription for IP or VLAN with an amount bigger than one will generate several subscriptions of that type.

Subscription times are rounded to noon UTC, using the following rules:

End time is always rounded to the next noon.
Start time is rounded to the maximum between the current time an the previous noon. This means that subscriptions bought for now do start now, but subscriptions for the future start at the previous noon.

Warning

Subscriptions are mostly immutable for the customer. The only parameter that can be changed is the auto renew.

Example request:

POST /api/2.0/subscriptions/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "amount": 30000,
            "period": "1 month",
            "resource": "dssd"
        }
    ]
}

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "amount": "30000",
            "auto_renew": true,
            "descendants": [],
            "discount_amount": "0",
            "discount_percent": "0",
            "end_time": "2013-04-22T12:00:00+00:00",
            "id": "28",
            "period": "31 days, 1:31:53.888650",
            "price": "0.000003839842975139617919921875",
            "remaining": "30000",
            "resource": "dssd",
            "resource_uri": "/api/2.0/subscriptions/28/",
            "start_time": "2013-03-22T10:28:06.111350+00:00",
            "status": "active",
            "subscribed_object": null,
            "uuid": "f622f364-bccf-4a36-a1ce-632a81640ad4"
        }
    ],
    "price": "0.000003839842975139617919921875"
}

Extending

POST /subscriptions/{id}/action/?do=extend

Status Codes:

200 OK – no error

Extends the subscription. An extended subscription is actually just another subscription that is linked to the original If a period or and end_time are specified in the request,they are used. If neither are specified, the creation length of the subscription is used.

A caveat to this is that a subscription created initially with an end_time, the exact interval is used. Subscriptions that are created with a period have the period parsed again in the context of the new start_time. An example would be a subscription created on the 1st of February with a period of ‘1 month’ will be extended for 31 days, but one that was created with an end date of 1st of March will be extended for 28 days.

If the specified subscription has actually been extended, it traverses and extends the last subscription in the chain.

Autorenewing

POST /subscriptions/{id}/action/?do=auto_renew

Toggles the autorenew flag of the subscription. Optionally, the value can be specified in the request.

Status Codes:

200 OK – no error

Schema

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "allowed_detail_http_methods": [
        "get",
        "post"
    ],
    "allowed_list_http_methods": [
        "get",
        "post"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "amount": {
            "blank": false,
            "default": 1,
            "help_text": "Subscription amount",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "auto_renew": {
            "blank": false,
            "default": true,
            "help_text": "States if the subscription will auto renew on expire",
            "nullable": false,
            "readonly": false,
            "type": "boolean",
            "unique": false
        },
        "descendants": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Subscriptions that have been extended from the current one",
            "nullable": true,
            "readonly": true,
            "type": "related",
            "unique": false
        },
        "discount_amount": {
            "blank": true,
            "default": "No default provided.",
            "help_text": "Amount of discount",
            "nullable": true,
            "readonly": false,
            "type": "decimal",
            "unique": false
        },
        "discount_percent": {
            "blank": true,
            "default": "No default provided.",
            "help_text": "Percent of discount",
            "nullable": true,
            "readonly": false,
            "type": "decimal",
            "unique": false
        },
        "discounts": {
            "blank": true,
            "default": "No default provided.",
            "help_text": "All discounts for this subscription",
            "nullable": true,
            "readonly": true,
            "type": "dict",
            "unique": false
        },
        "end_time": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "End time of subscription",
            "nullable": true,
            "readonly": false,
            "type": "datetime",
            "unique": false
        },
        "free_tier": {
            "blank": false,
            "default": false,
            "help_text": "Boolean data. Ex: True",
            "nullable": false,
            "readonly": false,
            "type": "boolean",
            "unique": false
        },
        "id": {
            "blank": false,
            "default": "",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": true
        },
        "period": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Duration of the subscription",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "price": {
            "blank": false,
            "default": 0,
            "help_text": "Subscription price",
            "nullable": false,
            "readonly": false,
            "type": "decimal",
            "unique": false
        },
        "remaining": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Amount remaining",
            "nullable": true,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "resource": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Name of resource associated with the subscription",
            "nullable": false,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "resource_uri": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "start_time": {
            "blank": false,
            "default": "2015-03-19T13:55:01.236421+00:00",
            "help_text": "Start time of subscription",
            "nullable": false,
            "readonly": false,
            "type": "datetime",
            "unique": false
        },
        "status": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Status of the subscription",
            "nullable": false,
            "readonly": true,
            "type": "string",
            "unique": false
        },
        "subscribed_object": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Subscribed object - the target of this subscription, if applicable",
            "nullable": true,
            "readonly": false,
            "type": "string",
            "unique": false
        },
        "uuid": {
            "blank": false,
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "nullable": true,
            "readonly": false,
            "type": "string",
            "unique": true
        },
        "was_billed": {
            "blank": false,
            "default": false,
            "help_text": "Boolean data. Ex: True",
            "nullable": false,
            "readonly": false,
            "type": "boolean",
            "unique": false
        }
    },
    "filtering": {
        "subscribed_object": [
            "exact"
        ]
    }
}

Grouped subscriptions

GET /groupedsubscriptions/

Returns only the first subscriptions from a chain of extended subscriptions. The extensions are listed in the ‘descendants’ attribute and the end_time is that of the last subscription in the chain.

Status Codes:

200 OK – no error

Calculator

POST /subscriptioncalculator/

Returns the price of the subscriptions POSTed in the same format as the normal subscriptions.

Status Codes:

200 OK – no error

Example request:

POST /api/2.0/subscriptioncalculator/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "amount": 10000000000,
            "period": "1 month",
            "resource": "dssd"
        }
    ]
}

Example response:

HTTP/1.1 200 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "amount": "10000000000",
            "discount_amount": "0E-24",
            "discount_percent": "0",
            "discounts": {},
            "end_time": "2015-04-20T12:00:00+00:00",
            "free_tier": false,
            "period": "31 days, 22:04:59.904871",
            "price": "1.010484993457794189453125",
            "resource": "dssd",
            "start_time": "2015-03-19T13:55:00.095129+00:00",
            "was_billed": true
        }
    ],
    "price": "1.010484993457794189453125"
}

Similarly, the price of extending a subscription can be calculated.

Example request:

POST /api/2.0/subscriptioncalculator/7272/action/?do=extend HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "amount": "32212254720",
    "discount_amount": "9.60750000000000000",
    "discount_percent": "0.2500000000",
    "discounts": {
        "period": "0.2500000000"
    },
    "end_time": "2016-08-26T12:00:00+00:00",
    "free_tier": false,
    "period": "366 days, 0:00:00",
    "price": "28.82250000000000000000",
    "resource": "dssd",
    "start_time": "2015-08-26T12:00:00+00:00",
    "was_billed": true
}