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.
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, NON_RENEWINGand CANCELLED.
payment_method
object
ID of already created .
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 intervals set in the Plan for the subscription to run.
infinite
boolean
If true, the subscription will run until the user stops it. Or an apocalypse of appropriate scale.
current_billing_ date_period_start
string
The date on which the customer was billed last.
current_billing_ date_period_end
string
The date on which the customer will be billed next. 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 amount that was subtracted at the last payment. plan.total_amount+prorate_amount.
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.
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
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
string
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.  Or zombies attack.
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.  Or the sun explodes.
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"}
}
Recurring Order Subscription Object
When your users create a recurring order plan, they still need to subscribe to it.
Attribute
Type
Description
method
string
Name of subscription method. recurring_order.
name
string
The name of the subscription type. Default is RECURRING_ORDER.
note
string
A short note regarding the subscription.
user
object
​User associated with the subscription.
status
string
Status for the subscription. This will change according to the subscription’s state. Default is CREATED, others are ACTIVE, FUTURE, NON_RENEWINGand CANCELLED.
plan
object
The Recurring Order Planassociated with the subscription.
payment_method
object
The Payment Method associated with the subscription.
payments
array
The Payment objects associated with the subscription.
starting_date
number
Start date, timestamp format.
ending_date
string
End date of subscription, timestamp format.
interval_total
number
The total number of Planintervals the subscription will run.
infinite
boolean
If true, the subscription will run until the user stops it. Or society breaks down.
current_billing_ date_period_start
string
The date on which the customer was billed last.
current_billing_ date_period_end
string
The next billing date. This will also be the date on which the next current_billing_date_period_start of the subscription starts.
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 amount that was subtracted at the last payment. plan.total_amount+prorate_amount.
total_fail_attempts
number
The number of failed payment attempts in the subscription. See Planmax_fail_attempts.
initial_order
object
The initial Order in the subscription, used to create the Recurring Order Plan. 
orders
object
List of Orders.
Create a Recurring Order Subscription
You can create a Recurring Order Subscription from an existing Order by including the plan in the request.  
Parameters
Request
Response
Body Parameters
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.
order
string
ID of the Order associated with the subscription.
subscription_method
string
Name of subscription method. license
note
string
A short description.
start_now
boolean
If true, the subscription will start now.
starting_date
number
Starting date for the subscription if start_nownot set true.
POST /subscriptions HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
​
{
    "order": "58b85693d76d439fdacea41b",
    "subscription_method": "recurring_order",
    "plan": {"plan_method": "recurring_order", "interval_unit": "WEEK", 
                "currency": "NOK", "billing_interval": "MONTH", 
                "recurring_days": [{"day": 3, "hour": 10, "minute": 30}], "total_amount": 100}
    "starting_date": {"$date": 1499854560000},
    "payment_method": <payment_method_id>  
}
HTTP/1.1 200 OK
Content-Type: application/json
{
    "company": {"$oid": "57ee9c71d76d431f8511142f"},
    "active": true,
    "status": "CREATED",
    "name": "LICENSE",
    "method": "recurring_order",
    "_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}.
    "order": {"$oid": "58b85693d76d439fdacea41b"},
    "starting_date": {"$date": 1499854560000},
    "payment_method": <payment_method_id>  
}
You can also create a Recurring Order Subscription while simultaneously creating a Plan and an Order by including the plan  and the items you want to place in the order.
Parameters
Request
Response
Body Parameters
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
note
string
A short description.
start_now
boolean
If true, the subscription will start now.
starting_date
number
Starting date for the subscription if start_nownot set true.
POST /subscriptions HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
​
{
    "subscription_method": "recurring_order",
    "plan": {"plan_method": "recurring_order", "interval_unit": "WEEK", "currency": "NOK", 
            "billing_interval": "MONTH", "recurring_days":[{"day": 3, "hour": 10, "minute": 30}], 
                                                            "items": [{"product": "Product ID", "quantity": 2}, 
                                                                      {"product": "Product ID",  "quantity":1}]},
    "starting_date": 1523876899,
    "payment_method": <payment_method_id>  
}
HTTP/1.1 200 OK
Content-Type: application/json
{
    "company": {"$oid": "57ee9c71d76d431f8511142f"},
    "active": true,
    "status": "CREATED",
    "name": "LICENSE",
    "method": "recurring_order",
    "_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}.
    "order": {"$oid": "58b85693d76d439fdacea41b"},
    "starting_date": 1523876899",
    "payment_method": <payment_method_id>  
}
Important: The Subscription can start now if you add start_now=True in the subscription data; then you don't have to set the starting_date field. See the Recurring Order Plan on how to create a plan for this subscription type.
Delete Subscription
Parameters
Request
Response
Path Parameter
Type
Description
subscription_id
string
ID of the subscription to start.
DELETE /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": true,
    "method": "license",
    "_id": {"$oid": "5964a0ead57ba2036750a3b4"}
}

Plans

Next - Building Blocks

Payments

Last updated 2 months ago

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.
`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`, `NON_RENEWING`and `CANCELLED.`
`payment_method`	`object`	ID of already created .
`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 intervals set in the `Plan` for the subscription to run.
`infinite`	`boolean`	If `true`, the subscription will run until the user stops it. Or an apocalypse of appropriate scale.
`current_billing_ date_period_start`	`string`	The date on which the customer was billed last.
`current_billing_ date_period_end`	`string`	The date on which the customer will be billed next. 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 amount that was subtracted at the last payment. `plan.total_amount`+`prorate_amount.`
`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`
`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`	`string`	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. Or zombies attack.

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. Or the sun explodes.
`ending_date`	`string`	End date, `timestamp` format.
`payment_method`	`string`	ID of an already created `Payment Method`.

Attribute	Type	Description
`method`	`string`	Name of subscription method. `recurring_order.`
`name`	`string`	The name of the subscription type. Default is `RECURRING_ORDER.`
`note`	`string`	A short note regarding the subscription.
`user`	`object`	`User` associated with the subscription.
`status`	`string`	Status for the subscription. This will change according to the subscription’s state. Default is `CREATED`, others are `ACTIVE`, `FUTURE`, `NON_RENEWING`and `CANCELLED.`
`plan`	`object`	The `Recurring Order Plan`associated with the subscription.
`payment_method`	`object`	The `Payment Method` associated with the subscription.
`payments`	`array`	The `Payment` objects associated with the subscription.
`starting_date`	`number`	Start date, `timestamp` format.
`ending_date`	`string`	End date of subscription, `timestamp` format.
`interval_total`	`number`	The total number of `Plan`intervals the subscription will run.
`infinite`	`boolean`	If `true`, the subscription will run until the user stops it. Or society breaks down.
`current_billing_ date_period_start`	`string`	The date on which the customer was billed last.
`current_billing_ date_period_end`	`string`	The next billing date. This will also be the date on which the next current_billing_date_period_start of the subscription starts.
`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 amount that was subtracted at the last payment. `plan.total_amount`+`prorate_amount.`
`total_fail_attempts`	`number`	The number of failed payment attempts in the subscription. See `Planmax_fail_attempts`.
`initial_order`	`object`	The initial `Order` in the subscription, used to create the `Recurring Order Plan`.
`orders`	`object`	List of `Orders`.

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

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