-
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": string,
"active": bool,
"in_grace_period": bool,
"expires": datetime,
"auth_tokens": array of strings
}
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.
- auth_tokens: the tokens authorizing payment. These will vary based on the subscription provider, and each provider has their own set of rules and expectations. Note that auth tokens will never be returned as part of any response; they are only used in requests.
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.
The Subscription Resource is kept lean on purpose; it's meant to be compatible with a variety of payment gateways that act as Subscription Providers and update Subscriptions through callbacks to the Update Subscription endpoint. Each Subscription Provider will have their own auth token expectations.
The auth_tokens array should consist of a single auth_token, which should be set to a Card Token obtained through Stripe's API or Stripe.js.
Not yet implemented.
Dwolla has no recurring billing at the moment, so this will be implemented through recurring tasks on IronWorker.The auth_tokens array should consist of two strings. The first should be an OAuth access token obtained from the Dwolla API. The second should be the user's Dwolla PIN. The PIN will be encrypted with a two-way hash before being stored.
This request requires administrative authentication.
GET /subscriptions/in_grace_period
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.
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.
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.
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 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.
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
}
]
}
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.
POST /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. Furthermore, the "expires" property will be ignored for this request.
A sample request body:
{
"auth_tokens": ["tok_jOq0M8vJprCUUU"]
}
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.
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 started the subscription",
"subscriptions": [
{
// See the Subscription Resource for the contents of this part
}
]
}
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. The "expires" property will be ignored unless this request is run with administrative credentials.
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:
{
"expires": "2010-12-02T12:47:31-05:00",
"auth_tokens": ["tok_jOq0M8vJprCUUU"]
}
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.
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
}
]
}
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.
DELETE /users/{username}/subscription
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.
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
}
]
}