Plans

Standard Plan Object

Standard Plans can only be created on the dashboard (for now), but here are the object details so you can see what's in it. 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.

name

string

The name of the plan.

note

string

A short description of the plan.

interval_unit

string

The frequency that the subscription acts upon. Choices: DAY, WEEK, MONTH, MONTH_END, ANNUAL

interval_count

integer

Total number of interval_units.

billing_interval

string

Defines billing frequency. Choices: WEEK, MONTH, MONTH_END

static

boolean

Defines if plan is allowed to be changed.

items

array

List of items in the Plan. See description below.

units

number

Total number of items in the plan.

currency

string

Three letter ISO currency code as defined by ISO 4217.

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 what happens 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

If you need to charge a subscription fee to the customer. 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.

deleted

boolean

Classifies Plan object as either deleted or not. Default is false.

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.

active

boolean

If the plan is active. Default is true.

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

Total number of interval_units.

billing_interval

string

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

static

boolean

Defines if plan is allowed to be changed.

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 what happens 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.

deleted

boolean

Classifies Plan object as either deleted or not. Default is false.

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.

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.

Create a Standard Plan

You create Standard Plans through the dashboard (for now). Under Subscriptions, you'll see Plans. Click on that and you'll see + Plan near the top.

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

The number of interval_units the subscription runs before it stops.

static

boolean

Sets if the plan is changeable after its creation.

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 what happens if a payment fails in the Subscription. 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

It is only possible to update a plan if static is false . Is is only possible to update the fields listed below.

Parameters
Request
Response

Path Parameter

Type

Description

recurring_order_plan_id

string

ID of the queried Recurring Order Plan.

Body Parameters

Type

Description

active

boolean

If the plan is active. Default is true.

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