Subscriptions
Get them subs!
Attribute | Type | Description |
method | string | Name of subscription method. license |
plan | object |
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 |
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 |
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 |
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
.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}
}
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 | |
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"}
}
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"}
}
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 | |
infinite | boolean | If true , the subscription will run until the User stops it. |
ending_date | string | End date, timestamp format. |
payment_method | string |
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"}
}
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"}
}
*Paths listed above and denoted with a star are accessible to both Users and Admins. Additional Admin Role paths are listed below.
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"}
}
]
Last modified 2yr ago