Plans
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 | |
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 | |
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 | |
retry_payment_in_minutes | integer | Defines how many time BuiltOn has to wait to retry a payment. Default is 720 (12 hours). |
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 | |
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. |
*Paths listed above and denoted with a star are accessible to both Users and Admins. Additional Admin Role paths are listed below.
Parameters
Request
Response
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 | |
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
}
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