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_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

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.

Request

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"
}

Response

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

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.

Request

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>"
}

Response

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

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

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

Request

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

Response

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

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.

Request

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
}

Response

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

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

Request

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

Response

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

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

Parameters

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

Response

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"}
    }
]