Subscribe!

Want to let your customers subscribe for your thing? Easy Peasy.

How We Do Subscriptions

TL;DR. First a plan is made, then it is subscribed to.

We have two concepts of how a Subscription works; either users can change the thing they're paying to get each month, or they can't. You don't change what you get on your Twitch, Netflix or HBO subscription. You just pay and you get the content. Products or services like these would use our Standard Plans to base their Subscriptions on.

However, we also wanted to let you make a plan that your users can change if they want. Think of a monthly wine delivery service that would let you pick the kinds of wine you want. Your users could pick regions or types of grape that they liked, how many bottles of each and even how often they want it delivered. If, after a few months, they wanted to mix things up, they could change the regions, grapes or number of bottles in their order and the next delivery would reflect those changes. Subscriptions like this are based on Recurring Order Plans.

Below, we walk you through the two types.

Standard Subscriptions

As an example, let's say we're making Gamefly, a company that gives you access to video games for a monthly fee. Here's what we'll do:

  1. Create a User

  2. Create a Standard Plan

  3. Create a Subscription

  4. Set up Payment

Create a User

Gamefly wants to let theirs users sign in online, which will create a user through our API. To just create a new user, call the /v2/users endpoint with a JWT. Thereafter, that will log in the existing user.

Parameters
Request
Response

Argument

Type

Description

first_name

string

First name of the user.

last_name

string

Last name of the user.

salutation

string

Title of the user.

email

string

E-mail of the user.

mobile_phone_number

string

Phone number of the user.

addresses

array

An array of Addresses associated with the user.

billing_address

object

Billing Address of the user.

bio

string

Biographical note about the user.

tags

array

List of tags associated with the user.

note

string

Additional notes regarding the user.

POST /v2/users HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOi
IxMjM0NTY3ODkwIiwibGFzdF9uYW1lIjoiRG9lIiwiZmlyc3RfbmFtZSI6IkpvaG4iLCJ
pYXQiOjE1MTYyMzkwMjJ9.YEqWlNmcheENbeSTjXhA-LMfULwa7t_Ab71tDmLGUxA
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"first_name": "John",
"last_name": "McClane",
"email": "diehardlover@email.com",
"mobile_phone_number": "+4712345678",
"addresses": [{
"city":"Danielsen",
"service":"google",
"alias":"",
"country":"Paraguay",
"zip_code":"0556",
"state":"Oslo",
"street_name":"Streetname 7"
}]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"roles": ["user"],
"tags": [],
"auth0_id": "some-id",
"mobile_phone_number": "+4712345678",
"billing_address":
{"service": "google",
"alias": " "},
"voucher": {"uuid": "b498e02b-2031-4d84-b55b-b460d22f44b4",
"consumed": 0,
"initial_quantity": 0,
"created": {"$date": 1512383756277},
"expires": {"$date": 1543919756277}},
"_cls": "User",
"created": {"$date": 1512383756277},
"addresses":
[{"zip_code": "0556",
"city": "Danielsen",
"street_name": "Streetname 7",
"country": "Paraguay",
"alias": " ",
"service": "google"}],
"company": {"$oid": "57ee9c71d76d431f8511142f"},
"email": "diehardlover@email.com",
"national_id": "1234567890",
"modified": {"$date": 1512383756279},
"avatar": " ",
"bio": " ",
"stripe_customer_id": " ",
"note": " ",
"first_name": "John",
"_id": {"$oid": "5a25250cd57ba213edcba515"},
"new_customer": true,
"last_name": "McClane",
"last_login": {"$date": 1512383756278},
"deleted": false,
"voucher": {}
}

Create a Standard Plan

You create Plans in the dashboard (for now). Under Subscriptions, you'll see Plans. Near the top will be New plan +. Enter the the basic parameters; name, delivery interval, billing interval and price. For Gamefly, maybe the first plan we'd make would be a basic plan. In the plan's details, we can add a description and fill in a few other fields. Easy.

Create a Subscription

Now that the Plan is created, your users can subscribe to it.

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

Argument

Type

Description

plan

string

ID of the Plan associated with the subscription.

subscription_method

string

Name of subscription method. Must be 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}

Get Paid

The fun part. Check out Payment Methods and Payments for all the parameters and related endpoints, as there are a few parts to getting paid. Here's the gist.

1. User adds a card

Your user will need to add a payment method, i.e. a credit or debit card, that they want to use to pay for their order.

Parameters
Request
Response

Attribute

Type

Description

payment_method

string

Must be stripe for triggering a STRIPE payment method.

token

string

Token created with the card details (number, expiration month, expiration year, card verification code)

POST /payment_methods HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"payment_method": "stripe",
"token": "tok_1Bv5yfEeeXxFpLJtpWYeGYuy"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"company": {
"$oid": "57ee9c71d76d431f8511142f"
},
"created": {
"$date": 1476118043580
},
"_id": {
"$oid": "<payment-method-id>"
},
"modified": {
"$date": 1476118043580
},
"deleted": false,
"user": {
"$oid": "57ee9c72d76d431f85111432"
},
"method": "stripe",
"name": "Stripe",
"customer_id": "cus_CJjTlT4Wci2P0u",
"token": "tok_1Bv5yfEeeXxFpLJtpWYeGYuy",
"card": {
"object": "card",
"address_state": null,
"fingerprint": "npPw68vQg1usKUWb",
"metadata": {},
"exp_year": 2019,
"country": "US",
"last4": "4242",
"address_zip_check": null,
"address_zip": null,
"funding": "credit",
"cvc_check": "unchecked",
"id": "card_1Bv5yfEeeXxFpLJtPBVfQ1wZ",
"tokenization_method": null,
"address_line1": null,
"exp_month": 12,
"brand": "Visa",
"dynamic_last4": null,
"address_country": null,
"address_line2": null,
"address_line1_check": null,
"name": null,
"address_city": null
}
}

2. Then They Pay You Automatically

And that's it. If the user has a payment method associated with them, it will get charged when the plan they've subscribed to says it should. And they get to game to their heart's content.

Recurring Order Subscriptions

Let's use the example of a monthly wine club mentioned above. We can pretend we're the kind of people that would join a wine club. Let's call it Too Many Chardonnays. Check out Orders and Subscriptions for more details on the different ways you can go about making recurring orders, but here's what we'll do:

  1. Create a User

  2. Create a Product

  3. Create a Recurring Order

  4. Create a Subscription

  5. Get Paid

Create a User

Check out the User object and all the related endpoints you can hit. To just create a new user, call the /v2/users endpoint with a JWT. Thereafter, that will log in the existing user.

Parameters
Request
Response

Argument

Type

Description

first_name

string

First name of the user.

last_name

string

Last name of the user.

salutation

string

Title of the user.

email

string

E-mail of the user.

mobile_phone_number

string

Phone number of the user.

addresses

array

An array of Addresses associated with the user.

billing_address

object

Billing Address of the user.

bio

string

Biographical note about the user.

tags

array

List of tags associated with the user.

note

string

Additional notes regarding the user.

POST /v2/users HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOi
IxMjM0NTY3ODkwIiwibGFzdF9uYW1lIjoiRG9lIiwiZmlyc3RfbmFtZSI6IkpvaG4iLCJ
pYXQiOjE1MTYyMzkwMjJ9.YEqWlNmcheENbeSTjXhA-LMfULwa7t_Ab71tDmLGUxA
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"first_name": "John",
"last_name": "McClane",
"email": "diehardlover@email.com",
"mobile_phone_number": "+4712345678",
"addresses": [{
"city":"Danielsen",
"service":"google",
"alias":"",
"country":"Paraguay",
"zip_code":"0556",
"state":"Oslo",
"street_name":"Streetname 7"
}]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"roles": ["user"],
"tags": [],
"auth0_id": "some-id",
"mobile_phone_number": "+4712345678",
"billing_address":
{"service": "google",
"alias": " "},
"voucher": {"uuid": "b498e02b-2031-4d84-b55b-b460d22f44b4",
"consumed": 0,
"initial_quantity": 0,
"created": {"$date": 1512383756277},
"expires": {"$date": 1543919756277}},
"_cls": "User",
"created": {"$date": 1512383756277},
"addresses":
[{"zip_code": "0556",
"city": "Danielsen",
"street_name": "Streetname 7",
"country": "Paraguay",
"alias": " ",
"service": "google"}],
"company": {"$oid": "57ee9c71d76d431f8511142f"},
"email": "diehardlover@email.com",
"national_id": "1234567890",
"modified": {"$date": 1512383756279},
"avatar": " ",
"bio": " ",
"stripe_customer_id": " ",
"note": " ",
"first_name": "John",
"_id": {"$oid": "5a25250cd57ba213edcba515"},
"new_customer": true,
"last_name": "McClane",
"last_login": {"$date": 1512383756278},
"deleted": false,
"voucher": {}
}

Create a Product

You create Products through the dashboard (for now). Under Orders, you'll see Products. Near the top will be Product +. Click that and enter the info required. Check out Products for more info on what else you can do with them.

Create a Recurring Order

Too Many Chardonnays isn't just a wine club, they also just sell wine. Their users can fill their wine case with whatever they want, like they're making a regular Order, and then decide they want to make this order a periodic thing that shows up at their house.

You can make an order a 'recurring order' by including these additional body parameters (in addition to the required parameter for a standard order): is_recurring (set to true), interval_unit, and recurring_days. This returns a JSON with order_status defined to CREATED.

When you make your Recurring Order this way, we're creating the Recurring Order Plan and the Recurring Order Subscription for you in the background. And your users just fill in a couple extra fields when they make the order.

Parameters
Request
Response

Body Parameters

Type

Description

is_recurring

boolean

Default is set to false for standard orders, however this needs to be set to true to create a recurring order.

interval_unit

string

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

recurring_days

array

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

currency

string

3 letter ISO currency code as defined by ISO 4217.

billing_address

object

Address used for billing purposes.

deliveries

array

Used to store the delivery history for an order.

delivery_address

object

Address used for delivery.

delivery_status

string

See delivery statuses. Default is PENDING.

delivery_time

object

Expected arrival time for delivery, timestampformat.

order_status

string

See order statuses. Default is CREATED.

items

array

List of items associated with an order.

human_id

string

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

payments

array

List of Payment objects associated with order.

payment_method

object

See Payment Methodsfor more info on the payment method object.

resources

array

The resources in the order.

top_up_amount

number

Extra amount added to total_amount to fulfill the company’s minimum order value.

top_up_vat

float

The VAT percentage on the top_up_amount. Decimal from 0.0 to 1.0, e.g. 0.25 = 25%.

total_amount

float

Amount with two decimals. e.g., 12.34. The amount is automatically calculated based on items in the order.

total_quantity

number

Total number of products in an order, e.g. 3 spoons and 2 forks = 5 products.

units

number

Number of unique products in an order, e.g. 3 spoons and 2 forks = 2 product units.

accounting_reference

string

An accounting reference ID.

stripe_charge_id

string

The reference ID from a Stripe charge.

stripe_refund_id

string

The reference ID from a Stripe refund.

subscription

object

Associated subscription referenced by subscription_id.

POST /orders HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"is_recurring": true,
"interval_unit": "WEEK",
"recurring_days": [{"day": 3, "hour": 10, "minute": 30}],
"items": [
{
"product": "5703fce3308714000dea1ff1",
"quantity": 1,
"discount": 0.1
},
{
"product": "5703fcde308714000dea1fe8",
"quantity": 3
}
],
"delivery_time": 1472022000000,
"delivery_address": {
"city": "Oslo",
"geo": [
59.9294087,
10.7643042
],
"zip_code": "0557",
"street_name": "Christies gate 34A",
"country": "Norway"
},
"billing_address": {
"city": "Oslo",
"geo": [
59.9294087,
10.7643042
],
"zip_code": "0557",
"street_name": "Christies gate 34A",
"country": "Norway"
},
"currency": "NOK",
"note": "some type of note"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"created": {"$date": 1488475795244},
"company": {"$oid": "586faf7445ed910006373513"},
"delivery_address": {
"city": "Oslo",
"geo": [
59.9294087,
10.7643042
],
"zip_code": "0557",
"street_name": "Christies gate 34A",
"country": "Norway"
},
"billing_address": {
"city": "Oslo",
"geo": [
59.9294087,
10.7643042
],
"zip_code": "0557",
"street_name": "Christies gate 34A",
"country": "Norway"
},
"_id": {"$oid": "58b85693d76d439fdacea41b"},
"total_amount": 40.0,
"delivery_time": {"$date": 1472022000000},
"note": "some type of note",
"total_quantity": 4,
"order_status": "CREATED",
"items": [
{
"product": "5703fce3308714000dea1ff1",
"quantity": 1,
"discount": 0.1
},
{
"product": "5703fcde308714000dea1fe8",
"quantity": 3
}
],
"user": {"$oid": "57ee9c72d76d431f85111432"},
"units": 2,
"delivery_status": "PENDING",
"modified": {"$date": 1488475795244},
"currency": "NOK"
}

Get Paid

1. User adds a card

Your user will need to add a payment method if they don't have one on file, i.e. a credit or debit card, that they want to use to pay for their order.

Parameters
Request
Response

Attribute

Type

Description

payment_method

string

Must be “stripe” for triggering a STRIPE payment method

token

string

Token created with the card details (number, expiration month, expiration year, card verification code)

POST /payment_methods HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"payment_method": "stripe",
"token": "tok_1Bv5yfEeeXxFpLJtpWYeGYuy"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"company": {
"$oid": "57ee9c71d76d431f8511142f"
},
"created": {
"$date": 1476118043580
},
"_id": {
"$oid": "<payment-method-id>"
},
"modified": {
"$date": 1476118043580
},
"deleted": false,
"user": {
"$oid": "57ee9c72d76d431f85111432"
},
"method": "stripe",
"name": "Stripe",
"customer_id": "cus_CJjTlT4Wci2P0u",
"token": "tok_1Bv5yfEeeXxFpLJtpWYeGYuy",
"card": {
"object": "card",
"address_state": null,
"fingerprint": "npPw68vQg1usKUWb",
"metadata": {},
"exp_year": 2019,
"country": "US",
"last4": "4242",
"address_zip_check": null,
"address_zip": null,
"funding": "credit",
"cvc_check": "unchecked",
"id": "card_1Bv5yfEeeXxFpLJtPBVfQ1wZ",
"tokenization_method": null,
"address_line1": null,
"exp_month": 12,
"brand": "Visa",
"dynamic_last4": null,
"address_country": null,
"address_line2": null,
"address_line1_check": null,
"name": null,
"address_city": null
}
}

2. Then They Pay

To pay an order, you're going to hit /payments with the order_id and the payment_method_id. Again, check out Payment Methods and Payments for more info.

Parameters
Request
Response

Arguments

Type

Description

orders

array

List with orders to be paid.

payment_method

string

The payment method ID that you want to use.

POST /payments HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"orders": ["<order-id>"],
"payment_method": "<payment-method-id>"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"company": {
"$oid": "57ee9c71d76d431f8511142f"
},
"created": {
"$date": 1476118043580
},
"_id": {
"$oid": "<payment-id>"
},
"modified": {
"$date": 1476118043580
},
"deleted": false,
"user": {
"$oid": "57ee9c72d76d431f85111432"
},
"amount": 450.2,
"metadata": {},
"current_state": "created",
"active": true,
"human_id": "51Q4LN",
"currency": "NOK",
"subject": "<order-id>",
"payment_method": "<payment-method-id>",
"payment_date": {
"$date": 147998016470
}
}

And that's it. If the payment for the order is successful, the order_status will change to SUCCESS. And the user will have a subscription to some yummy wines that'll show up when they want them to.