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

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

Request

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

Response

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

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

Request

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

Response

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

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

Response

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

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.

Request

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

Response

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

Path Parameters	Type	Description
<plan_id>	string	Plan ID associated with returned list of subscriptions.

Request

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

Response

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