Skip to content
This repository has been archived by the owner on Feb 24, 2020. It is now read-only.

Subscriptions

Jump to bottom
Paddy Foran edited this page Sep 23, 2013 · 11 revisions

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": uint64,
  "amount": uint,
  "period": string,
  "renews": datetime,
  "notify_on_renewal": bool,
  "last_notified": datetime,
  "funding_id": uint64,
  "funding_source": string,
  "user_id": uint64,
  "campaign": uint64
}

Mutable Properties

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

  • amount: the amount the user will pay for the Subscription, as cents in USD.
  • period: a string describing when the Subscription renews. Valid values are monthly and yearly.
  • renews: the date and time the Subscription should be renewed, expressed according to RFC 3339.
  • notify_on_renewal: whether the user should receive a notification email when the Subscription goes up for renewal.
  • campaign: the Campaign the payments should be applied to. A Campaign of 0 means whatever the current non-auxilliary Campaign is.
  • funding_id: the ID of the PaymentInfo object that is used to pay for this Subscription.
  • funding_source: the type of PaymentInfo object that funding_id correlates to.
  • user_id: The ID of the User object this Subscription belongs to.

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.
  • last_notified: the date and time the user was last notified about their Subscription, expressed as RFC 3339.

Listing Subscriptions

This request requires administrative authentication.

Request Format

Endpoint

GET /subscriptions

Optional Parameters

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

  • status: the status of the Subscription. Valid values consist of renewing for Subscriptions that should be renewed and renewing_soon for Subscriptions that will be renewed in the next 24 hours
  • after: the ID of a Subscription. Only Subscriptions with an ID greater than that Subscription will be returned.
  • before: the ID of a Subscription. Only Subscriptions with an ID lower than 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 renews 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.

Errors

Status Code Field Explanation
403 ERROR_ACCESS_DENIED User does not have permission to list subscriptions.
400 ERROR_INVALID_FORMAT after The after query parameter was not a valid ID.
400 ERROR_INVALID_FORMAT before The before query parameter was not a valid ID.
400 ERROR_INVALID_FORMAT count The count query parameter was not a valid integer.
400 ERROR_TOO_SHORT count The count query parameter was less than or equal to 0.
400 ERROR_TOO_LONG count The count query parameter was greater than 100.
400 ERROR_INVALID_VALUE status The status passed was not a valid status.
500 ERROR_ACT_OF_GOD An unknown error occurred.

Listing Subscriptions By User

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

Request Format

Endpoint

GET /users/{username}/subscriptions

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 with an ID greater than that Subscription will be returned.
  • before: the ID of a Subscription. Only Subscriptions with an ID lower than 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 renews 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.

Errors

Status Code Field Explanation
403 ERROR_ACCESS_DENIED User does not have permission to list subscriptions.
400 ERROR_INVALID_FORMAT after The after query parameter was not a valid ID.
400 ERROR_INVALID_FORMAT before The before query parameter was not a valid ID.
400 ERROR_INVALID_FORMAT count The count query parameter was not a valid integer.
400 ERROR_TOO_SHORT count The count query parameter was less than or equal to 0.
400 ERROR_TOO_LONG count The count query parameter was greater than 100.
400 ERROR_INVALID_VALUE status The status passed was not a valid status.
404 ERROR_NOT_FOUND username No user could be found using the specified username.
500 ERROR_ACT_OF_GOD An unknown error occurred.

Creating A Subscription

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

Request Format

Endpoint

POST /subscriptions

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:

{
  "subscription": {
  	"amount": 100,
  	"period": "monthly",
  	"notify_on_renewal": true,
  	"campaign": 0
  }
}

Response Format

Header

This request sets the Last-Modified header to the renews 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 created.

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

Errors

Status Code Field Explanation
400 ERROR_BAD_REQUEST_FORMAT The request body was not valid JSON.
500 ERROR_ACT_OF_GOD An unknown error occurred.
400 ERROR_MISSING_PARAM subscription No subscription property was included in the request body.
400 ERROR_MISSING_PARAM subscription.amount No amount was included in the subscription.
400 ERROR_MISSING_PARAM subscription.period No period was included in the subscription.
404 ERROR_NOT_FOUND subscription.campaign_id The specified campaign was not found.
400 ERROR_INVALID_VALUE subscription.campaign_id The specified campaign has ended.
403 ERROR_ACCESS_DENIED subscription.user_id The authenticating user is not authorised to create subscriptions for the specified user.
400 ERROR_MISSING_PARAM subscription.funding_id The subscription supplied had no funding source ID.
400 ERROR_MISSING_PARAM subscription.funding_source The subscription supplied had no funding source provider.
404 ERROR_NOT_FOUND subscription.funding_id The funding source specified was not found.
400 ERROR_WRONG_OWNER subscription.funding_id The funding source specified does not belong to the specified user.
400 ERROR_INVALID_VALUE subscription.funding_source The funding source provider specified was not valid.
400 ERROR_INVALID_VALUE subscription.period The period provided was not valid.

Getting Information About 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

GET /subscriptions/{id}

Response Format

Header

This request sets the Last-Modified header to the renews 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
    }
  ]
}

Errors

Status Code Field Explanation
400 ERROR_MISSING_PARAM id The subscription ID was not set.
400 ERROR_INVALID_FORMAT id The ID supplied was not a valid ID.
403 ERROR_ACCESS_DENIED id The authenticating user did not have access to the specified subscription.
404 ERROR_NOT_FOUND id The specified subscription did not exist.
500 ACT_OF_GOD An unknown error occurred.

Updating 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

PUT /subscriptions/{id}

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:

{
  "subscription": {
  	"amount": 100,
  	"period": "monthly",
  	"notify_on_renewal": true
  }
}

Response Format

Header

This request sets the Last-Modified header to the renews 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
    }
  ]
}

Errors

Status Code Field Explanation
400 ERROR_MISSING_PARAM id The subscription ID was not set.
400 ERROR_INVALID_FORMAT id The specified ID was not a valid ID.
400 ERROR_BAD_REQUEST_FORMAT The body of the request was not valid JSON.
500 ERROR_ACT_OF_GOD An unknown error occurred.
400 ERROR_MISSING_PARAM subscription The request body did not include a subscription element.
404 ERROR_NOT_FOUND id The specified Subscription did not exist.
403 ERROR_ACCESS_DENIED The authenticating user does not have access to the specified subscription.
403 ERROR_ACCESS_DENIED subscription.user_id The authenticating user does not have access to the specified user's subscriptions.
404 ERROR_NOT_FOUND subscription.funding_id The specified funding source was not found.
400 ERROR_WRONG_OWNER subscription.funding_id The specified funding source does not belong to the specified user.
400 ERROR_INVALID_VALUE subscription.funding_source The specified funding source provider was not valid.
404 ERROR_NOT_FOUND subscription.campaign_id The specified campaign was not found.
400 ERROR_INVALID_VALUE subscription.campaign_id The specified campaign has already ended.

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 /subscriptions/{id}

Response Format

Header

This request sets the Last-Modified header to the renews 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 cancelled:

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

Errors

Status Code Field Explanation
400 ERROR_MISSING_PARAM id No subscription ID was specified.
400 ERROR_INVALID_FORMAT id The specified subscription ID was not a valid ID.
404 ERROR_NOT_FOUND id The specified subscription was not found.
500 ERROR_ACT_OF_GOD An unknown error occurred.
403 ERROR_ACCESS_DENIED The authorizing user does not have access to the specified subscription.
Clone this wiki locally