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
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 /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": "[email protected]",
   "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": "[email protected]",
    "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:
​https://stripe.com/docs/api/payment_methods/create​
​https://stripe.com/docs/stripe-js/reference#stripe-create-payment-method​
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.

Blueprints (Use Cases) - Previous

Sell a Thing

Last modified 2yr ago

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.