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:

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:

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:

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:

Calculator

POST /subscriptioncalculator/

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

Status Codes:

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
}