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 modified 2yr ago
Copy link
On this page
Standard Plan Object
Plan Items
Admin Role
Create a Standard Plan
Retrieve a Plan
Get List of all Plans associated with Company
Add Items to a Plan
Get Subscriptions used by Plan