Search…
BuiltOn API Documentation
Getting Started
Get Set Up
Setup an Authentication Provider
SDKs
Nuts & Bolts
Authentication
Service Account
Retrieve Items
Expanding Objects
Pagination
Errors
Common GET Parameters
Common Object Fields
Addresses
Images
Templates and Attributes
Building Blocks
Users
Products
Orders
Subscriptions and Plans
Plans
Subscriptions
Payments
Webhooks
Machine Learning
Intro to ML
Simple ML
Blueprints (Use Cases)
What Kind of Build?
Sell a Thing
Subscribe!
Powered By GitBook
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
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"}
}
]
Previous
Plans
Next - Building Blocks
Payments
Last modified 2yr ago
Copy link
On this page
Standard Subscription Object
User Role
Create a Standard Subscription*
Start Subscription*
Stop Subscription*
Update Subscription*
Retrieve Subscription by ID*
Admin Role
Get all Subscriptions