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

Building Blocks - Previous

Subscriptions and Plans

Subscriptions

Last updated 1 month ago

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).

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.

Body Parameters	Type	Description
`interval_unit`	`string`	The frequency that the Subscription acts upon. Choices are`day, 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).

Path Parameters	Type	Description
`<plan_id>`	`string`	ID of the plan to get.