Subscriptions

Get them subs!

Standard Subscription Object
Attribute
Type
Description
method
string
Name of subscription method. license
plan
object
ID of the Plan associated with the subscription.
name
string
The name of the subscription type.
human_id
string
Human readable ID that identifies the order easily, e.g. 3AG7UA.
note
string
A short description of the subscription.
user
object
User ID associated with the subscription.
status
string
Status for the subscription. Default isCREATED. Others are ACTIVE, FUTURE, CANCELLED, DONE, NON_RENEWING and ON_HOLD
payment_method
object
ID of already created payment method.
payments
array
The Payments associated with the subscription.
starting_date
number
Start date, timestamp format. Default is current date if missing.
ending_date
string
End date of subscription, timestamp format.
interval_total
number
Number ofinterval_unitset in thePlanfor the duration of the subscription period.
trial_ends
number
The end date of the trial period, timestamp format.
infinite
boolean
If true, the subscription will run until the user stops it.
current_billing_ date_period_start
number
The date on which the customer was billed last, timestamp format.
current_billing_ date_period_end
number
The date on which the customer will be billed next, timestamp format.
The next current_billing_date_period_start of the subscription will be set to this.
prorate_amount
number
The amount prorated. Currency set in Plan.
prorate_date
number
The date of the last time an amount was prorated.
last_billing_amount
number
The last amount that was billed.
total_fail_attempts
number
The number of failed payment attempts in the subscription. See Plan: max_fail_attempts
deleted
boolean
Has this been deleted? Default is false.
Note: If the user set more than one of the parameters infinite, ending_date or interval_total, the API overrides the parameters with: infinite > ending_date > interval_total.
User Role
Create a Standard Subscription*
To create a new subscription, the user needs to choose a plan.
Note: start_now must be set to true for the subscription to start automatically after creation. An associated payment_method must be in the request data.
Parameters
Request
Response
Attribute
Type
Description
plan
string or object
ID of the Plan associated with the subscription. Can also provide a Plan object if the Plan hasn't already been created.
subscription_method
string
Name of subscription method.license
payment_method
string
ID of already created payment method.
note
string
A short description.
start_now
boolean
If true, the subscription will start now.
POST /subscriptions HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
​
{
    "plan": "5931697ed57ba271c0c7de66",
    "subscription_method": "license"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
    "company": {"$oid": "57ee9c71d76d431f8511142f"},
    "active": true,
    "status": "CREATED",
    "name": "LICENSE",
    "method": "license",
    "_id": {"$oid": "5964a0ead57ba2036750a3b4"},
    "deleted": false,
    "prorate_amount": 0.0,
    "_cls": "SubscriptionMethod.LicenseSubscription",
    "plan": {"$oid": "5931697ed57ba271c0c7de66"},
    "payments": [],
    "infinite": false,
    "created": {"$date": 1499767018360},
    "user": {"$oid": "57ee9c72d76d431f85111432"},
    "updated": {"$date": 1499767018360}
}
Start Subscription*
It is possible to start a subscription once a subscription has been created by providing the subscription_id. It is also possible to update the following information while starting the subscription. For example, maybe the subscription has been paused for awhile and the User would like to restart the subscription and update their payment method at the same time.
Parameters
Request
Response
Path Parameter
Type
Description
subscription_id
string
ID of the subscription to start.
Body Parameters
Type
Description
payment_method
string
ID of an already created payment method.
starting_date
number
Start date, timestamp format. Default is current date if missing.
ending_date
number
End date, timestamp format.
interval_total
number
Number of intervals, set in the Plan, the subscription will run.
infinite
boolean
If true, the subscription will run until the user stops it.
POST /subscriptions/<subscription_id>/start HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
​
{
    "payment_method": "<payment-method-id>"
}
HTTP/1.1 200 OK
Content-Type: application/json
​
{
    "plan": {"$oid": "5931697ed57ba271c0c7de66"},
    "payment_method": {"$oid": "<payment-method-id>"},
    "user": {"$oid": "57ee9c72d76d431f85111432"},
    "prorate_amount": 0.0,
    "name": "LICENSE",
    "payments": [],
    "status": "ACTIVE",
    "active": true,
    "updated": {"$date": 1499768160086},
    "_cls": "SubscriptionMethod.LicenseSubscription",
    "infinite": false,
    "starting_date": {"$date": 1499854560000},
    "ending_date": {"$date": 1511954560000},
    "created": {"$date": 1499767018360},
    "current_billing_date_period_end": {"$date": 1502532960000},
    "current_billing_date_period_start": {"$date": 1499854560000},
    "company": {"$oid": "57ee9c71d76d431f8511142f"},
    "deleted": false,
    "method": "license",
    "_id": {"$oid": "5964a0ead57ba2036750a3b4"}
}
Stop Subscription*
To stop the subscription, the user can either choose to stop it on a chosen ending_date or immediately, if that value is missing. The remaining amount will be prorated to the user at the next current_billing_date_period_end if the Plan has prorate set true.
Parameters
Request
Response
Path Parameter
Type
Description
subscription_id
string
ID of the subscription to start.
Body Parameter
Type
Description
ending_date
string
End date, timestamp format.
POST /subscriptions/<subscription_id>/stop HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
HTTP/1.1 200 OK
Content-Type: application/json
​
{
    "plan": {"$oid": "5931697ed57ba271c0c7de66"},
    "payment_method": {"$oid": "<payment-method-id>"},
    "user": {"$oid": "57ee9c72d76d431f85111432"},
    "prorate_amount": -428.57,
    "name": "LICENSE",
    "note": "A note regarding the subscription",
    "payments": [],
    "status": "NON_RENEWING",
    "active": true,
    "updated": {"$date": 1499773617984},
    "_cls": "SubscriptionMethod.LicenseSubscription",
    "infinite": false,
    "starting_date": {"$date": 1499854560000},
    "ending_date": {"$date": 1499860512000},
    "created": {"$date": 1499767018360},
    "current_billing_date_period_end": {"$date": 1502532960000},
    "current_billing_date_period_start": {"$date": 1499854560000},
    "company": {"$oid": "57ee9c71d76d431f8511142f"},
    "deleted": false,
    "method": "license",
    "_id": {"$oid": "5964a0ead57ba2036750a3b4"}
}
Update Subscription*
The user can update the below fields in the subscription.
Parameters
Request
Response
Path Parameter
Type
Description
subscription_id
string
ID of the subscription to start.
Body Parameters
Type
Description
note
string
A short description.
interval_total
number
Number of intervals, set in the Plan, the subscription will run.
infinite
boolean
If true, the subscription will run until the User stops it.
ending_date
string
End date, timestamp format.
payment_method
string
ID of an already created Payment Method.
PUT /subscriptions/5964a0ead57ba2036750a3b4 HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
​
{
    "note": "A note regarding the subscription",
    "infinite": true
}
HTTP/1.1 200 OK
Content-Type: application/json
​
{
    "plan": {"$oid": "5931697ed57ba271c0c7de66"},
    "payment_method": {"$oid": "<payment-method-id>"},
    "user": {"$oid": "57ee9c72d76d431f85111432"},
    "prorate_amount": 0.0,
    "name": "LICENSE",
    "note": "A note regarding the subscription",
    "payments": [],
    "status": "ACTIVE",
    "active": true,
    "updated": {"$date": 1499773617984},
    "_cls": "SubscriptionMethod.LicenseSubscription",
    "infinite": true,
    "starting_date": {"$date": 1499854560000},
    "created": {"$date": 1499767018360},
    "current_billing_date_period_end": {"$date": 1502532960000},
    "current_billing_date_period_start": {"$date": 1499854560000},
    "company": {"$oid": "57ee9c71d76d431f8511142f"},
    "deleted": false,
    "method": "license",
    "_id": {"$oid": "5964a0ead57ba2036750a3b4"}
}
Retrieve Subscription by ID*
Parameters
Request
Response
Path Parameter
Type
Description
subscription_id
string
ID of the subscription to start.
GET /subscriptions/<subscription_id> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
HTTP/1.1 200 OK
Content-Type: application/json
​
{
    "plan": {"$oid": "5931697ed57ba271c0c7de66"},
    "payment_method": {"$oid": "<payment-method-id>"},
    "user": {"$oid": "57ee9c72d76d431f85111432"},
    "prorate_amount": -428.57,
    "name": "LICENSE",
    "note": "A note regarding the subscription",
    "payments": [],
    "status": "NON_RENEWING",
    "active": true,
    "updated": {"$date": 1499773617984},
    "_cls": "SubscriptionMethod.LicenseSubscription",
    "infinite": false,
    "starting_date": {"$date": 1499854560000},
    "ending_date": {"$date": 1499860512000},
    "created": {"$date": 1499767018360},
    "current_billing_date_period_end": {"$date": 1502532960000},
    "current_billing_date_period_start": {"$date": 1499854560000},
    "company": {"$oid": "57ee9c71d76d431f8511142f"},
    "deleted": false,
    "method": "license",
    "_id": {"$oid": "5964a0ead57ba2036750a3b4"}
}
Admin Role
*Paths listed above and denoted with a star are accessible to both Users and Admins. Additional Admin Role paths are listed below.
Get all Subscriptions
Receives a list of all subscriptions associated with a company.
Request
Parameters
Response
GET /subscriptions/search?method=license HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
Query Parameters
Type
Description
method
string 
Allows for filtering of subscriptions by type of method: license
HTTP/1.1 200 OK
Content-type: application/json
[
    {
        "plan": {"$oid": "5931697ed57ba271c0c7de66"},
        "payment_method": {"$oid": "<payment-method-id>"},
        "user": {"$oid": "57ee9c72d76d431f85111432"},
        "prorate_amount": -428.57,
        "name": "LICENSE",
        "note": "A note regarding the subscription",
        "payments": [],
        "status": "NON_RENEWING",
        "active": true,
        "updated": {"$date": 1499773617984},
        "_cls": "SubscriptionMethod.LicenseSubscription",
        "infinite": false,
        "starting_date": {"$date": 1499854560000},
        "ending_date": {"$date": 1499860512000},
        "created": {"$date": 1499767018360},
        "current_billing_date_period_end": {"$date": 1502532960000},
        "current_billing_date_period_start": {"$date": 1499854560000},
        "company": {"$oid": "57ee9c71d76d431f8511142f"},
        "deleted": false,
        "method": "license",
        "_id": {"$oid": "5964a0ead57ba2036750a3b4"}
    }
]

Plans

Next - Building Blocks

Payments

Last updated -1

Attribute	Type	Description
`method`	`string`	Name of subscription method. `license`
`plan`	`object`	ID of the `Plan` associated with the subscription.
`name`	`string`	The name of the subscription type.
`human_id`	`string`	Human readable ID that identifies the order easily, e.g. `3AG7UA.`
`note`	`string`	A short description of the subscription.
`user`	`object`	`User` ID associated with the subscription.
`status`	`string`	Status for the subscription. Default is`CREATED`. Others are `ACTIVE`, `FUTURE`, `CANCELLED`, `DONE`, `NON_RENEWING` and `ON_HOLD`
`payment_method`	`object`	ID of already created payment method.
`payments`	`array`	The `Payments` associated with the subscription.
`starting_date`	`number`	Start date, `timestamp` format. Default is current date if missing.
`ending_date`	`string`	End date of subscription, `timestamp` format.
`interval_total`	`number`	Number of`interval_unit`set in the`Plan`for the duration of the subscription period.
`trial_ends`	`number`	The end date of the trial period, `timestamp` format.
`infinite`	`boolean`	If `true`, the subscription will run until the user stops it.
`current_billing_ date_period_start`	number	The date on which the customer was billed last, `timestamp` format.
`current_billing_ date_period_end`	`number`	The date on which the customer will be billed next, `timestamp` format. The next `current_billing_date_period_start` of the subscription will be set to this.
`prorate_amount`	`number`	The amount prorated. Currency set in `Plan`.
`prorate_date`	`number`	The date of the last time an amount was prorated.
`last_billing_amount`	`number`	The last amount that was billed.
`total_fail_attempts`	`number`	The number of failed payment attempts in the subscription. See `Plan`: `max_fail_attempts`
`deleted`	`boolean`	Has this been deleted? Default is `false`.

Attribute	Type	Description
`plan`	`string` or `object`	ID of the `Plan` associated with the subscription. Can also provide a Plan object if the Plan hasn't already been created.
`subscription_method`	`string`	Name of subscription method.`license`
`payment_method`	`string`	ID of already created payment method.
`note`	`string`	A short description.
`start_now`	`boolean`	If `true`, the subscription will start now.

Body Parameters	Type	Description
`payment_method`	`string`	ID of an already created payment method.
`starting_date`	`number`	Start date, `timestamp` format. Default is current date if missing.
`ending_date`	`number`	End date, `timestamp` format.
`interval_total`	`number`	Number of intervals, set in the `Plan`, the subscription will run.
`infinite`	`boolean`	If `true`, the subscription will run until the user stops it.

Body Parameters	Type	Description
`note`	`string`	A short description.
`interval_total`	`number`	Number of intervals, set in the `Plan`, the subscription will run.
`infinite`	`boolean`	If `true`, the subscription will run until the User stops it.
`ending_date`	`string`	End date, `timestamp` format.
`payment_method`	`string`	ID of an already created `Payment Method`.

Path Parameter	Type	Description
`subscription_id`	`string`	ID of the subscription to start.

Body Parameter	Type	Description
`ending_date`	`string`	End date, `timestamp` format.

Query Parameters	Type	Description
`method`	`string`	Allows for filtering of subscriptions by type of method: `license`