-
Notifications
You must be signed in to change notification settings - Fork 0
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 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,
"auto_renew": bool,
"notify_on_renewal": bool,
"contact": bool,
"last_contacted": datetime,
"funding_id": uint64,
"funding_source": string,
"user_id": uint64
}
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
monthlyandyearly. - renews: the date and time the Subscription should be renewed, expressed according to RFC 3339.
- auto_renew: whether the Subscription will be automatically renewed when it comes up for renewal.
- notify_on_renewal: whether the user should receive a notification email when the Subscription goes up for renewal.
- contact: whether the user should be contacted about their Subscription. This property can only be updated with administrative credentials.
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_contacted: the date and time the user was last contacted about their Subscription, expressed as RFC 3339.
- 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.
This request requires administrative authentication.
GET /subscriptions
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
expiredfor Subscriptions that should be renewed andexpiringfor Subscriptions that will be renewed in the next 24 hours - 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.
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.
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.
- User not permitted to list subscriptions
- After timestamp not valid RFC 3339
- Before timestamp not valid RFC 3339
- Count not an integer
- Status was not a valid value
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.
GET /users/{username}/subscription
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.
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
}
]
}
- Username not specified
- User does not have access to user's subscription
- User not found
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. If the contact field is set, it requires administrative credentials, regardless of whose account it is run against.
PUT /users/{username}/subscription
Because this request has a body, the Content-Type, and Content-Length headers need to be set.
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",
"auto_renew": true,
"notify_on_renewal": true
}
}
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.
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
}
]
}
- Username not specified
- User does not have access to user's subscription
- User does not have administrative credentials but tried to set a property that requires administrative credentials
- User not found