Subscriptions

Subscriptions represent the financial status of a User's account. They're simply a way of tracking which accounts are active and which owe money.

The Subscription Resource

The Subscription resource is represented in responses under the subscriptions property. The subscriptions property will be an array of Subscriptions.

Subscriptions appear as follows:

{
  "id": string,
  "active": bool,
  "in_grace_period": bool,
  "expires": datetime
}

Mutable Properties

Mutable properties are properties that can be modified through interactions with the API.

• expires: the date and time the Subscription expires, expressed according to RFC 3339.

Immutable Properties

Immutable properties are properties that are created and modified only by the system; there is no way to modify them through the API.

• id: A unique, immutable identifier for this Subscription.
• active: True if the Subscription is active, False otherwise.
• in_grace_period: True if the Subscription is past its expiration date, but within the grace period granted for the User to recover from billing issues without service disruption.

Listing Subscriptions In The Grace Period

This request requires administrative authentication.

Request Format

Endpoint

GET /subscriptions/in_grace_period

Optional Parameters

The following URL parameters are accepted when listing Subscriptions, and will filter the list accordingly:

• after: the ID of a Subscription. Only Subscriptions sent after that Subscription will be returned.
• before: the ID of a Subscription. Only Subscriptions sent before that Subscription will be returned.
• count: the maximum number of Subscriptions to return, as an integer. Defaults to 20, with a maximum of 100.

Response Format

Header

This request sets the Last-Modified header to the latest expires property of the Subscriptions returned.

The Content-Type of this request will be subscriptions/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be subscriptions/json.

Body

This request returns a list of Subscription resources as a JSON array:

{
  "code": 200,
  "msg": "Successfully retrieved a list of subscriptions",
  "subscriptions": [
    {
      // See the Subscription Resource for the contents of this part
    },
    {
      // See the Subscription Resource for the contents of this part
    }
  ]
}

In the event no subscriptions are to be returned, an empty array will be returned.

Getting Information About A User's Subscription

This request requires only authentication if it is run against a Subscription that belongs to the authenticating User. If it is run against another User's Subscription, it requires administrative credentials.

Request Format

Endpoint

GET /users/{username}/subscription

Response Format

Header

This request sets the Last-Modified header to the expires property of the Subscription returned.

The Content-Type of this request will be subscriptions/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be subscriptions/json.

Body

This request returns a list of Subscription resources as a JSON array. The array will only have one item:

{
  "code": 200,
  "msg": "Successfully retrieved subscription information",
  "subscriptions": [
    {
      // See the Subscription Resource for the contents of this part
    }
  ]
}

Updating A Subscription

This request requires administrative credentials.

Request Format

Endpoint

PUT /users/{username}/subscription

Request Headers

Because this request has a body, the Content-Type, and Content-Length headers need to be set.

Request Body

The request body should be a Subscription Resource. Only the Mutable Properties will be used; the rest will be ignored.

A sample request body:

{
  "expires": "2010-12-02T12:47:31-05:00"
}

Response Format

Header

This request sets the Last-Modified header to the expires property of the Subscription returned.

The Content-Type of this request will be subscriptions/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be subscriptions/json.

Body

This request returns a list of Subscription resources as a JSON array. The array will only have one item—the Subscription that was modified:

{
  "code": 200,
  "msg": "Successfully updated the subscription",
  "subscriptions": [
    {
      // See the Subscription Resource for the contents of this part
    }
  ]
}

Canceling A Subscription

This request requires only authentication if it is run against a Subscription that belongs to the authenticating User. If it is run against another User's Subscription, it requires administrative credentials.

Request Format

Endpoint

DELETE /users/{username}/subscription

Response Format

Header

This request sets the Last-Modified header to the expires property of the Subscription returned.

The Content-Type of this request will be subscriptions/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be subscriptions/json.

Body

This request returns a list of Subscription resources as a JSON array. The array will only have one item—the Subscription that was just canceled:

{
  "code": 200,
  "msg": "Successfully canceled the subscription",
  "subscriptions": [
    {
      // See the Subscription Resource for the contents of this part
    }
  ]
}