Plans

Standard Plan Object

Standard Plans can only be created on the dashboard or by using a Service Account. See below for more info and the Blueprint Subscribe! for more details about how Plans and Subscriptions can work.

Attribute

Type

Description

method

string

The plan type. Default is basic.

currency

string

3 letter ISO currency code as defined by ISO 4217.

interval_unit

string

The billing frequency. Choices: DAY, WEEK, MONTH, MONTH_END, ANNUAL

name

string

The name of the plan.

human_id

string

Human readable ID that identifies the order easily, e.g. 3AG7UA

note

string

A short description of the plan.

billing_interval

string

Defines billing frequency. Choices: WEEK, MONTH, MONTH_END

items

array

List of items in the Plan. See description below.

units

number

Total number of items in the plan.

total_amount

integer

The amount to be charged on the interval specified. If missing, this will be calculated as the sum of the items.

initial_fail_amount_action

string

Decides the action taken if a payment fails in the Subscription. Choices: CANCEL, CONTINUE

max_fail_attempts

integer

If initial_fail_amount_action is CONTINUE, this is the number of interval_units that is allowed to fail before the Subscription stops.

setup_fee

integer

Initial setup fee or administrative fee, charged on creation of Subscription. Can’t be less than 0. Default is 0.

is_prorated

boolean

Sets if a plan is allowed to charge a prorate amount, which value is defined in the Subscription. Default is true.

should_retry_payments

boolean

Allow to use a retry payment system. It means if the attempt to pay a Subscription fails then automatically BuiltOn will plan another payment later. Default is false

max_payment_retries

integer

Defines how many time BuiltOn will retry to pay a Subscription . Default is 0.

retry_payment_in_minutes

integer

Defines how many time BuiltOn has to wait to retry a payment. Default is 720 (12 hours).

Plan Items

The attribute items in the Plan Object is where you put the Products your user wants to buy. These items are stored in an array. Each item has the below attributes. See Updating Items in an Order for more details on how this is used.

Attributes

Type

Description

product

string

A Product unique ID.

quantity

number

The quantity of the product.

discount

number

The discount of the product.price in the plan.

sub_products

array

An array of sub-product IDs associated in the plan.

Admin Role

*Paths listed above and denoted with a star are accessible to both Users and Admins. Additional Admin Role paths are listed below.

Create a Standard Plan

Parameters
Request
Response

Body Parameters

Type

Description

interval_unit

string

The frequency that the Subscription acts upon. Choices areday, week, month, month_end, annual

billing_interval

string

Defines billing frequency. Choices are week, month, month_end

currency

string

Three letter ISO currency code as defined by ISO 4217.7

name

string

The name of the plan.

note

string

A short description of the plan.

items

array

List of items associated with the Plan.

setup_fee

number

A setup fee that will be paid at the beginning of the first payment cycle. Can't be less than 0. Default value is 0.

prepay

boolean

Defines whether the subscription payment is charged at the beginning or end of the billing cycle. Default value is false.

is_prorated

boolean

Sets if a Plan is allowed to charge a prorate amount, which value is defined in the Subscription. Default is true.

total_amount

number

Total amount of plan if not calculated automatically from products/resources.

should_retry_payments

boolean

Allow to use a retry payment system. It means if the attempt to pay a Subscription fails then automatically BuiltOn will plan another payment later. Default is false

max_payment_retries

integer

Defines how many time BuiltOn will retry to pay a Subscription . Default is 0.

retry_payment_in_minutes

integer

Defines how many time BuiltOn has to wait to retry a payment. Default is 720 (12 hours).

POST /plans HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"interval_unit": "WEEK",
"name": "Plan Deluxe",
"currency": "NOK",
"static": true,
"billing_interval": "MONTH",
"items": [{"product": "<product1_id>", "quantity": 1},
{"product": "<product2_id>", "quantity": 2, "discount": 0.5}],
"initial_fail_amount_action": "CONTINUE",
"max_fail_attempts": 1,
"note": "This is a note regarding the Plan"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"_id": {
"$oid": "5931697ed57ba271c0c7de66"},
"created": {
"$date": 1496410494652},
"modified": {
"$date": 1496410494652},
"auto_bill_amount": false,
"billing_interval": "MONTH",
"initial_fail_amount_action": "CONTINUE",
"max_fail_attempts": 1,
"name": "Plan Deluxe",
"name": "basic"
"total_amount": 300.0,
"interval_unit": "WEEK",
"items": [
{"discount": 0.0,
"product": {"$oid": "5931697ed57ba271c0c7de64"},
"quantity": 1},
{"discount": 0.5,
"product": {"$oid": "5931697ed57ba271c0c7de65"},
"quantity": 2}],
"currency": "NOK",
"note": "This is a note regarding the Plan",
"deleted": false,
"company": {
"$oid": "57ee9c71d76d431f8511142f"},
"static": true,
"setup_fee": 0
}

Retrieve a Plan

Parameters
Request
Response

Path Parameters

Type

Description

<plan_id>

string

ID of the plan to get.

GET /plans/5931697ed57ba271c0c7de66 HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev

HTTP/1.1 200 OK
Content-Type: application/json
{
"_id": {
"$oid": "5931697ed57ba271c0c7de66"},
"created": {
"$date": 1496410494652},
"updated": {
"$date": 1496411756242},
"items": [
{"discount": 0.0,
"product": {"$oid": "5931697ed57ba271c0c7de64"},
"quantity": 1},
{"discount": 0.5,
"product": {"$oid": "5931697ed57ba271c0c7de65"},
"quantity": 2}
],
"deleted": false,
"billing_interval": "MONTH",
"currency": "NOK",
"name": "Golden Plan",
"interval_unit": "WEEK",
"static": false,
"total_amount": 500.0,
"company": {"$oid": "57ee9c71d76d431f8511142f"},
"setup_fee": 0
}

Get List of all Plans associated with Company

Request
Response
GET /plans HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"created": {"$date": 1496412265911},
"interval_unit": "WEEK",
"currency": "NOK",
"name": "Golden Plan",
"updated": {"$date": 1496412265911},
"static": false,
"billing_interval": "MONTH",
"_id": {"$oid": "59317069d57ba2781c739479"},
"total_amount": 500.0,
"company": {"$oid": "57ee9c71d76d431f8511142f"},
"deleted": false,
"items": [
{
"discount": 0.0,
"quantity": 1,
"product": {"$oid": "59317069d57ba2781c739477"}
},
{
"discount": 0.0,
"quantity": 2,
"product": {"$oid": "59317069d57ba2781c739478"}
}
]
},
{
"created": {"$date": 1496412265930},
"interval_unit": "WEEK",
"...": "..."
}
]

Add Items to a Plan

Parameters
Request
Response

Path Parameters

Type

Description

<plan_id>

string

Plan ID where Items will be added

Body Parameters

Type

Description

items

array

List of Item objects associated with Plan.

PUT /plans/5931697ed57ba271c0c7de66/items HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"items": [{"product": "<product1_id>", "quantity": 1},
{"product": "<product2_id>", "quantity": 2, "discount": 0.5}]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"_id": {"$oid": "5931697ed57ba271c0c7de66"},
"created": {"$date": 1496410494652},
"updated": {"$date": 1496410494652},
"method": "recurring_order",
"auto_bill_amount": false,
"billing_interval": "MONTH",
"initial_fail_amount_action": "CONTINUE",
"max_fail_attempts": 1,
"name": "Recurring Order Plan Deluxe",
"total_amount": 300.0,
"interval_unit": "WEEK",
"items": [{"product": "<product1_id>", "quantity": 1},
{"product": "<product2_id>", "quantity": 2, "discount": 0.5}],
"currency": "NOK",
"note": "This is a note regarding the Plan",
"deleted": false,
"company": {"$oid": "57ee9c71d76d431f8511142f"},
"static": true,
}

Get Subscriptions used by Plan

Parameters
Request
Response

Path Parameters

Type

Description

<plan_id>

string

Plan ID associated with returned list of subscriptions.

GET /plans/5bace152cb416c14a3115a6c/subscriptions HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"_id":{"$oid":"5964a0ead57ba2036750a3b4"},
"_cls":"SubscriptionMethod.LicenseSubscription",
"created":{"$date":1538056530832},
"updated":{"$date":1538056530832},
"active":true,
"deleted":false,
"trial":false,
"user":{"$oid":"57ee9c72d76d431f85111432"},
"company":{"$oid":"57ee9c71d76d431f8511142f"},
"status":"CREATED",
"payments":[],
"infinite":false,
"plan":{"$oid":"5bace152cb416c14a3115a6c"},
"prorate_amount":0.0,
"total_fail_attempts":0,
"method":"license",
"name":"LICENSE"
}
]