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.

note

string

A short description of the subscription.

user

object

User ID associated with the subscription.

status

string

Status for the subscription. Default is CREATED. Others are ACTIVE, FUTURE, NON_RENEWINGand CANCELLED.

payment_method

object

ID of already created .

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 of intervals set in the Plan for the subscription to run.

infinite

boolean

If true, the subscription will run until the user stops it. Or an apocalypse of appropriate scale.

current_billing_ date_period_start

string

The date on which the customer was billed last.

current_billing_ date_period_end

string

The date on which the customer will be billed next. 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 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 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.

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

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

string

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. Or zombies attack.

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. Or the sun explodes.

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, NON_RENEWINGand CANCELLED.

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. Or society breaks down.

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.

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