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.

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.

payment_method_id

string

Payment Method created with the card details (number, expiration month, expiration year, cvc).

Stripe references:

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",
"payment_method_id": "pm_1EzglsEeeXxFpLJtjuEvd123"
}
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",
"payment_method_id": "pm_1EzglsEeeXxFpLJtjuEvd123",
"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.