Plans

Standard Plan Object

Standard Plans can only be created on the dashboard or by using a Service Account. The Recurring Order Plans, however, can be created by your users. 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.

interval_count

integer

Duration of the subscription, with interval_unit as a unit.

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.

Recurring Order Plan Object

The Recurring Order Plan can be paid every time an order occurs, or periodically, e.g. pay for all scheduled orders at the end of the month.

Attribute

Type

Description

method

string

The plan type: recurring_order.

currency

string

Three letter ISO currency code as defined by ISO 4217.

name

string

The name of the plan. Default is RECURRING_ORDER_PLAN.

note

string

A short description of the plan.

interval_unit

string

The subscription's frequency. DAY, WEEK, or MONTH.

recurring_days

array

Defines the schedule for the recurring order. See Recurring Day for more info.

interval_count

integer

Duration of the subscription, with interval_unit as a unit.

billing_interval

string

Defines billing frequency. Choices: WEEK, MONTH, MONTH_END or PER_ORDER.

items

array

List of items associated with 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

The set up fee the user pays. Can’t be less than 0. Default is 0.

is_prorated

boolean

Allows prorate amounts to be charged. Value is defined in the Subscription. Default is true.

Recurring Day

A Recurring Order Plan must contain recurring days as a list. The list contains the parameters that schedule the orders. The parameters to select the schedule are day, hour and minute. You choose the time of day by using the parameters hour and minute. If not set, the time of day will be set by the initial order.

The day in recurring_days is relative to the Plan's interval_unit. For example, if the interval_unit is set WEEK, the value of day is between 0 and 6. See table below:

Weekly
Monthly

Number

Day

0

Monday

1

Tuesday

2

Wednesday

3

Thursday

4

Friday

5

Saturday

6

Sunday

Number = Day of the month. I.e., no 0, start on the 1st.

Note: If the billing date is the 31st, the billing date will be the end of the month for every month with fewer days than that. E.g. Start Jan 31, next billing date is Feb 28. Then back to March 31.

User Role

Create a Recurring Order Plan*

Parameters
Request
Response

Argument

Type

Description

interval_unit

string

The subscription's frequency. DAY, WEEK, or MONTH.

recurring_days

array

Defines the schedule for the recurring order. See Recurring Day for more info.

billing_interval

string

Defines billing frequency. Choices: WEEK, MONTH, MONTH_END.

currency

string

Three letter ISO currency code as defined by ISO 4217.7.

name

string

The name of the plan. Default is RECURRING_ORDER_PLAN.

note

string

A short description of the plan.

active

boolean

If the plan is active. Default is true.

interval_count

integer

Duration of the subscription, with interval_unit as a unit.

items

array

List of items associated with Plan. See description below.

total_amount

integer

The amount charged at the end of the billing interval. If missing, the total_amount will be calculated as the sum of the items.

initial_fail_ amount_action

string

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

max_fail_attempts

integer

If initial_fail_amount_action is CONTINUE, this is the maximum number of failed payments in a row before the Subscription stops. If set to CANCEL, the Subscription stops if one payment fails.

setup_fee

integer

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

prepay

boolean

Defines if the subscription payment is charged at the beginning or end of the billing cycle.

is_prorated

boolean

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

POST /plans HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"method": "recurring_order",
"interval_unit": "WEEK",
"name": "Recurring Order Plan Deluxe",
"currency": "NOK",
"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",
"recurring_days": [{"day": 0, "hour": 10, "minute": 42},
{"day": 4, "hour": 20, "minute": 15}]
}
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": [
{"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": false,
"setup_fee": 0,
"recurring_days": [{"day": 0, "starting_day": {"$date": 1496410494652}, "next_day": {"$date": 1496410494652}},
{"day": 0, "starting_day": {"$date": 1496410494998}, "next_day": {"$date": 1496410494998}}],
}

Update Recurring Order Plan*

Parameters
Request
Response

Path Parameter

Type

Description

recurring_order_plan_id

string

ID of the queried Recurring Order Plan.

Body Parameters

Type

Description

name

string

Name of the plan.

note

string

Note regarding the plan.

initial_fail_ amount_action

string

Indicates what happens when a payment fails in the subscription. Choices: CONTINUE, CANCEL.

max_fail_attempts

number

How many times a payment can fail in the subscription before it is stops.

discount

number

Percentage as a decimal value from 0 to 1, e.g. 0.25 = 25%, discount on the total_amount.

total_amount

number

The total cost of the subscription payment. If set, the total_amount is not based on the sum of products.

recurring_days

array

The dates when the order will recur. See Recurring Day for more info.

PUT /plans/<plan_id> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"method": 'recurring_order',
"interval_unit": "WEEK",
"name": "Recurring Order Plan Deluxe",
"currency": "NOK",
"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",
"interval_count": false,
"total_amount": false,
"setup_fee": 0,
"recurring_days": [{"day": 0, "starting_day": {"$date": 1496410494652}, "next_day": {"$date": 1496410494652}},
{"day": 4, "starting_day": {"$date": 1496410494998}, "next_day": {"$date": 1496410494998}},
{"day": 2, "hour": 10, "minute": 15}]
}
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": [
{"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": false,
"setup_fee": 0,
"recurring_days": [{"day": 0, "starting_day": {"$date": 1496410494652}, "next_day": {"$date": 1496410494652}},
{"day": 4, "starting_day": {"$date": 1496410494998}, "next_day": {"$date": 1496410494998}},
{"day": 2, "starting_day": {"$date": 1496410495952}, "next_day": {"$date": 1496410495952}}]
}

Note: When updating recurring_days, you overwrite the existing list. Be sure to include the existing format, as well as any added dates, as it includes the next billing period start dates, e.g.:

{"day": 0, "starting_day": {"$date": 1496410494652}, "next_day": {"$date": 1496410494652}}

Get List of all Recurring Order Plans*

Returns a list of all the Recurring Order Plans that a User has created.

Parameters
Request
Response

Query Parameter

Type

Description

size

integer

Number of items to retrieve.

page

integer

Which page to retrieve. Default page size is 50.

sorting

string

Field used for sorting results. If missing, the default is created.

include_deleted

boolean

If true, deleted products are also listed.

GET /plans 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
[
{
"method": 'recurring_order',
"interval_unit": "WEEK",
"name": "Recurring Order Plan Deluxe",
"currency": "NOK",
"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",
"interval_count": false,
"total_amount": false,
"setup_fee": 0,
"recurring_days": [{"day": 0, "starting_day": {"$date": 1496410494652}, "next_day": {"$date": 1496410494652}},
{"day": 4, "starting_day": {"$date": 1496410494998}, "next_day": {"$date": 1496410494998}},
{"day": 2, "hour": 10, "minute": 15}]
}
]

Delete Recurring Order Plan*

Parameters
Request
Response

Path Parameter

Type

Description

recurring_order_plan_id

string

ID of the queried Recurring Order Plan.

DELETE /plans/<recurring_order_plan_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
{
"method": 'recurring_order',
"interval_unit": "WEEK",
"name": "Recurring Order Plan Deluxe",
"currency": "NOK",
"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",
"interval_count": false,
"total_amount": false,
"setup_fee": 0,
"deleted": true,
"recurring_days": [{"day": 0, "starting_day": {"$date": 1496410494652}, "next_day": {"$date": 1496410494652}},
{"day": 4, "starting_day": {"$date": 1496410494998}, "next_day": {"$date": 1496410494998}},
{"day": 2, "hour": 10, "minute": 15}]
}

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},
"updated": {
"$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"
}
]