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 /users endpoint with a JWT. Thereafter, that will log in the existing user.

Parameters

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.

Request

POST /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": "[e-mail]",
   "mobile_phone_number": "[phone]",
   "addresses": [{
               "city":"Danielsen",
               "service":"google",
               "alias":"",
               "country":"Paraguay",
               "zip_code":"0556",
               "state":"Oslo",
               "street_name":"Streetname 7"
             }]
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "roles": ["user"],
    "tags": [],
    "auth0_id": "some-id",
    "mobile_phone_number": "[phone]",
    "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": "[e-mail]",
    "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

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.

Request

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

Response

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

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: https://stripe.com/docs/api/payment_methods/create https://stripe.com/docs/stripe-js/reference#stripe-create-payment-method

Request

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

Response

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.