Subscriptions

Get them subs!

Standard Subscription Object

Attribute

Type

Description

method

string

Name of subscription method. license

plan

object

ID of the Plan associated with the subscription.

name

string

The name of the subscription type.

human_id

string

Human readable ID that identifies the order easily, e.g. 3AG7UA.

note

string

A short description of the subscription.

user

object

User ID associated with the subscription.

status

string

Status for the subscription. Default isCREATED. Others are ACTIVE, FUTURE, CANCELLED, DONE, NON_RENEWING and ON_HOLD

payment_method

object

ID of already created payment method.

payments

array

The Payments associated with the subscription.

starting_date

number

Start date, timestamp format. Default is current date if missing.

ending_date

string

End date of subscription, timestamp format.

interval_total

number

Number ofinterval_unitset in thePlanfor the duration of the subscription period.

trial_ends

number

The end date of the trial period, timestamp format.

infinite

boolean

If true, the subscription will run until the user stops it.

current_billing_ date_period_start

number

The date on which the customer was billed last, timestamp format.

current_billing_ date_period_end

number

The date on which the customer will be billed next, timestamp format.

The next current_billing_date_period_start of the subscription will be set to this.

prorate_amount

number

The amount prorated. Currency set in Plan.

prorate_date

number

The date of the last time an amount was prorated.

last_billing_amount

number

The last amount that was billed.

total_fail_attempts

number

The number of failed payment attempts in the subscription. See Plan: max_fail_attempts

deleted

boolean

Has this been deleted? Default is false.

Note: If the user set more than one of the parameters infinite, ending_date or interval_total, the API overrides the parameters with: infinite > ending_date > interval_total.

User Role

Create a Standard Subscription*

To create a new subscription, the user needs to choose a plan.

Note: start_now must be set to true for the subscription to start automatically after creation. An associated payment_method must be in the request data.

Parameters
Request
Response

Attribute

Type

Description

plan

string or object

ID of the Plan associated with the subscription. Can also provide a Plan object if the Plan hasn't already been created.

subscription_method

string

Name of subscription method.license

payment_method

string

ID of already created payment method.

note

string

A short description.

start_now

boolean

If true, the subscription will start now.

POST /subscriptions HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"plan": "5931697ed57ba271c0c7de66",
"subscription_method": "license"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"company": {"$oid": "57ee9c71d76d431f8511142f"},
"active": true,
"status": "CREATED",
"name": "LICENSE",
"method": "license",
"_id": {"$oid": "5964a0ead57ba2036750a3b4"},
"deleted": false,
"prorate_amount": 0.0,
"_cls": "SubscriptionMethod.LicenseSubscription",
"plan": {"$oid": "5931697ed57ba271c0c7de66"},
"payments": [],
"infinite": false,
"created": {"$date": 1499767018360},
"user": {"$oid": "57ee9c72d76d431f85111432"},
"updated": {"$date": 1499767018360}
}

Start Subscription*

It is possible to start a subscription once a subscription has been created by providing the subscription_id. It is also possible to update the following information while starting the subscription. For example, maybe the subscription has been paused for awhile and the User would like to restart the subscription and update their payment method at the same time.

Parameters
Request
Response

Path Parameter

Type

Description

subscription_id

string

ID of the subscription to start.

Body Parameters

Type

Description

payment_method

string

ID of an already created payment method.

starting_date

number

Start date, timestamp format. Default is current date if missing.

ending_date

number

End date, timestamp format.

interval_total

number

Number of intervals, set in the Plan, the subscription will run.

infinite

boolean

If true, the subscription will run until the user stops it.

POST /subscriptions/<subscription_id>/start HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"payment_method": "<payment-method-id>"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"plan": {"$oid": "5931697ed57ba271c0c7de66"},
"payment_method": {"$oid": "<payment-method-id>"},
"user": {"$oid": "57ee9c72d76d431f85111432"},
"prorate_amount": 0.0,
"name": "LICENSE",
"payments": [],
"status": "ACTIVE",
"active": true,
"updated": {"$date": 1499768160086},
"_cls": "SubscriptionMethod.LicenseSubscription",
"infinite": false,
"starting_date": {"$date": 1499854560000},
"ending_date": {"$date": 1511954560000},
"created": {"$date": 1499767018360},
"current_billing_date_period_end": {"$date": 1502532960000},
"current_billing_date_period_start": {"$date": 1499854560000},
"company": {"$oid": "57ee9c71d76d431f8511142f"},
"deleted": false,
"method": "license",
"_id": {"$oid": "5964a0ead57ba2036750a3b4"}
}

Stop Subscription*

To stop the subscription, the user can either choose to stop it on a chosen ending_date or immediately, if that value is missing. The remaining amount will be prorated to the user at the next current_billing_date_period_end if the Plan has prorate set true.

Parameters
Request
Response

Path Parameter

Type

Description

subscription_id

string

ID of the subscription to start.

Body Parameter

Type

Description

ending_date

string

End date, timestamp format.

POST /subscriptions/<subscription_id>/stop 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
{
"plan": {"$oid": "5931697ed57ba271c0c7de66"},
"payment_method": {"$oid": "<payment-method-id>"},
"user": {"$oid": "57ee9c72d76d431f85111432"},
"prorate_amount": -428.57,
"name": "LICENSE",
"note": "A note regarding the subscription",
"payments": [],
"status": "NON_RENEWING",
"active": true,
"updated": {"$date": 1499773617984},
"_cls": "SubscriptionMethod.LicenseSubscription",
"infinite": false,
"starting_date": {"$date": 1499854560000},
"ending_date": {"$date": 1499860512000},
"created": {"$date": 1499767018360},
"current_billing_date_period_end": {"$date": 1502532960000},
"current_billing_date_period_start": {"$date": 1499854560000},
"company": {"$oid": "57ee9c71d76d431f8511142f"},
"deleted": false,
"method": "license",
"_id": {"$oid": "5964a0ead57ba2036750a3b4"}
}

Update Subscription*

The user can update the below fields in the subscription.

Parameters
Request
Response

Path Parameter

Type

Description

subscription_id

string

ID of the subscription to start.

Body Parameters

Type

Description

note

string

A short description.

interval_total

number

Number of intervals, set in the Plan, the subscription will run.

infinite

boolean

If true, the subscription will run until the User stops it.

ending_date

string

End date, timestamp format.

payment_method

string

ID of an already created Payment Method.

PUT /subscriptions/5964a0ead57ba2036750a3b4 HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"note": "A note regarding the subscription",
"infinite": true
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"plan": {"$oid": "5931697ed57ba271c0c7de66"},
"payment_method": {"$oid": "<payment-method-id>"},
"user": {"$oid": "57ee9c72d76d431f85111432"},
"prorate_amount": 0.0,
"name": "LICENSE",
"note": "A note regarding the subscription",
"payments": [],
"status": "ACTIVE",
"active": true,
"updated": {"$date": 1499773617984},
"_cls": "SubscriptionMethod.LicenseSubscription",
"infinite": true,
"starting_date": {"$date": 1499854560000},
"created": {"$date": 1499767018360},
"current_billing_date_period_end": {"$date": 1502532960000},
"current_billing_date_period_start": {"$date": 1499854560000},
"company": {"$oid": "57ee9c71d76d431f8511142f"},
"deleted": false,
"method": "license",
"_id": {"$oid": "5964a0ead57ba2036750a3b4"}
}

Retrieve Subscription by ID*

Parameters
Request
Response

Path Parameter

Type

Description

subscription_id

string

ID of the subscription to start.

GET /subscriptions/<subscription_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
{
"plan": {"$oid": "5931697ed57ba271c0c7de66"},
"payment_method": {"$oid": "<payment-method-id>"},
"user": {"$oid": "57ee9c72d76d431f85111432"},
"prorate_amount": -428.57,
"name": "LICENSE",
"note": "A note regarding the subscription",
"payments": [],
"status": "NON_RENEWING",
"active": true,
"updated": {"$date": 1499773617984},
"_cls": "SubscriptionMethod.LicenseSubscription",
"infinite": false,
"starting_date": {"$date": 1499854560000},
"ending_date": {"$date": 1499860512000},
"created": {"$date": 1499767018360},
"current_billing_date_period_end": {"$date": 1502532960000},
"current_billing_date_period_start": {"$date": 1499854560000},
"company": {"$oid": "57ee9c71d76d431f8511142f"},
"deleted": false,
"method": "license",
"_id": {"$oid": "5964a0ead57ba2036750a3b4"}
}

Recurring Order Subscription Object

When your users create a recurring order plan, they still need to subscribe to it.

Attribute

Type

Description

method

string

Name of subscription method. recurring_order.

name

string

The name of the subscription type. Default is RECURRING_ORDER.

note

string

A short note regarding the subscription.

user

object

User associated with the subscription.

status

string

Status for the subscription. This will change according to the subscription’s state. Default is CREATED. Others are ACTIVE, FUTURE, CANCELLED, DONE, NON_RENEWING and ON_HOLD

plan

object

The Recurring Order Planassociated with the subscription.

payment_method

object

The Payment Method associated with the subscription.

payments

array

The Payment objects associated with the subscription.

starting_date

number

Start date, timestamp format.

ending_date

string

End date of subscription, timestamp format.

interval_total

number

The total number of Planintervals the subscription will run.

infinite

boolean

If true, the subscription will run until the user stops it.

current_billing_ date_period_start

string

The date on which the customer was billed last.

current_billing_ date_period_end

string

The next billing date. This will also be the date on which the next current_billing_date_period_start of the subscription starts.

prorate_amount

number

The amount prorated. Currency set in Plan.

prorate_date

number

The date of the last time an amount was prorated

last_billing_amount

number

The amount that was subtracted at the last payment. plan.total_amount+prorate_amount.

total_fail_attempts

number

The number of failed payment attempts in the subscription. See Planmax_fail_attempts.

initial_order

object

The initial Order in the subscription, used to create the Recurring Order Plan.

orders

object

List of Orders.

User Role

Create a Recurring Order Subscription*

You can create a Recurring Order Subscription from an existing Order by including the plan in the request.

Parameters
Request
Response

Body Parameters

Type

Description

plan

string or object

ID of the Plan associated with the subscription. Can also provide a Plan object if the Plan hasn't already been created.

order

string

ID of the Order associated with the subscription.

subscription_method

string

Name of subscription method. license

note

string

A short description.

start_now

boolean

If true, the subscription will start now.

starting_date

number

Starting date for the subscription if start_nownot set true.

POST /subscriptions HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"order": "58b85693d76d439fdacea41b",
"subscription_method": "recurring_order",
"plan": {"plan_method": "recurring_order", "interval_unit": "WEEK",
"currency": "NOK", "billing_interval": "MONTH",
"recurring_days": [{"day": 3, "hour": 10, "minute": 30}], "total_amount": 100}
"starting_date": {"$date": 1499854560000},
"payment_method": <payment_method_id>
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"company": {"$oid": "57ee9c71d76d431f8511142f"},
"active": true,
"status": "CREATED",
"name": "LICENSE",
"method": "recurring_order",
"_id": {"$oid": "5964a0ead57ba2036750a3b4"},
"deleted": false,
"prorate_amount": 0.0,
"_cls": "SubscriptionMethod.LicenseSubscription",
"plan": {"$oid": "5931697ed57ba271c0c7de66"},
"payments": [],
"infinite": false,
"created": {"$date": 1499767018360},
"user": {"$oid": "57ee9c72d76d431f85111432"},
"updated": {"$date": 1499767018360}.
"order": {"$oid": "58b85693d76d439fdacea41b"},
"starting_date": {"$date": 1499854560000},
"payment_method": <payment_method_id>
}

You can also create a Recurring Order Subscription while simultaneously creating a Plan and an Order by including the plan and the items you want to place in the order.

Parameters
Request
Response

Body Parameters

Type

Description

plan

string or object

ID of the Plan associated with the subscription. Can also provide a Plan object if the Plan hasn't already been created.

subscription_method

string

Name of subscription method. license

note

string

A short description.

start_now

boolean

If true, the subscription will start now.

starting_date

number

Starting date for the subscription if start_nownot set true.

POST /subscriptions HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"subscription_method": "recurring_order",
"plan": {"plan_method": "recurring_order", "interval_unit": "WEEK", "currency": "NOK",
"billing_interval": "MONTH", "recurring_days":[{"day": 3, "hour": 10, "minute": 30}],
"items": [{"product": "Product ID", "quantity": 2},
{"product": "Product ID", "quantity":1}]},
"starting_date": 1523876899,
"payment_method": <payment_method_id>
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"company": {"$oid": "57ee9c71d76d431f8511142f"},
"active": true,
"status": "CREATED",
"name": "LICENSE",
"method": "recurring_order",
"_id": {"$oid": "5964a0ead57ba2036750a3b4"},
"deleted": false,
"prorate_amount": 0.0,
"_cls": "SubscriptionMethod.LicenseSubscription",
"plan": {"$oid": "5931697ed57ba271c0c7de66"},
"payments": [],
"infinite": false,
"created": {"$date": 1499767018360},
"user": {"$oid": "57ee9c72d76d431f85111432"},
"updated": {"$date": 1499767018360}.
"order": {"$oid": "58b85693d76d439fdacea41b"},
"starting_date": 1523876899",
"payment_method": <payment_method_id>
}

Important: The Subscription can start now if you add start_now=True in the subscription data; then you don't have to set the starting_date field. See the Recurring Order Plan on how to create a plan for this subscription type.

Delete Subscription*

Parameters
Request
Response

Path Parameter

Type

Description

subscription_id

string

ID of the subscription to start.

DELETE /subscriptions/<subscription_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
{
"plan": {"$oid": "5931697ed57ba271c0c7de66"},
"payment_method": {"$oid": "<payment-method-id>"},
"user": {"$oid": "57ee9c72d76d431f85111432"},
"prorate_amount": -428.57,
"name": "LICENSE",
"note": "A note regarding the subscription",
"payments": [],
"status": "NON_RENEWING",
"active": true,
"updated": {"$date": 1499773617984},
"_cls": "SubscriptionMethod.LicenseSubscription",
"infinite": false,
"starting_date": {"$date": 1499854560000},
"ending_date": {"$date": 1499860512000},
"created": {"$date": 1499767018360},
"current_billing_date_period_end": {"$date": 1502532960000},
"current_billing_date_period_start": {"$date": 1499854560000},
"company": {"$oid": "57ee9c71d76d431f8511142f"},
"deleted": true,
"method": "license",
"_id": {"$oid": "5964a0ead57ba2036750a3b4"}
}

Admin Role

*Paths listed above and denoted with a star are accessible to both Users and Admins. Additional Admin Role paths are listed below.

Get all Subscriptions

Receives a list of all subscriptions associated with a company.

Request
Parameters
Response
GET /subscriptions/search?method=license HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev

Query Parameters

Type

Description

method

string

Allows for filtering of subscriptions by type of method: license, recurring_order

HTTP/1.1 200 OK
Content-type: application/json
[
{
"plan": {"$oid": "5931697ed57ba271c0c7de66"},
"payment_method": {"$oid": "<payment-method-id>"},
"user": {"$oid": "57ee9c72d76d431f85111432"},
"prorate_amount": -428.57,
"name": "LICENSE",
"note": "A note regarding the subscription",
"payments": [],
"status": "NON_RENEWING",
"active": true,
"updated": {"$date": 1499773617984},
"_cls": "SubscriptionMethod.LicenseSubscription",
"infinite": false,
"starting_date": {"$date": 1499854560000},
"ending_date": {"$date": 1499860512000},
"created": {"$date": 1499767018360},
"current_billing_date_period_end": {"$date": 1502532960000},
"current_billing_date_period_start": {"$date": 1499854560000},
"company": {"$oid": "57ee9c71d76d431f8511142f"},
"deleted": false,
"method": "license",
"_id": {"$oid": "5964a0ead57ba2036750a3b4"}
}
]