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