Subscribe!
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.
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:
Create a User
Create a Standard Plan
Create a Subscription
Set up Payment
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.
Argument | Type | Description |
|
| First name of the user. |
|
| Last name of the user. |
|
| Title of the user. |
|
| E-mail of the user. |
|
| Phone number of the user. |
|
| An |
|
| Billing |
|
| Biographical note about the user. |
|
| List of tags associated with the user. |
|
| Additional notes regarding the user. |
POST /v2/users HTTP/1.1Content-Type: application/jsonAuthorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibGFzdF9uYW1lIjoiRG9lIiwiZmlyc3RfbmFtZSI6IkpvaG4iLCJpYXQiOjE1MTYyMzkwMjJ9.YEqWlNmcheENbeSTjXhA-LMfULwa7t_Ab71tDmLGUxAX-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 OKContent-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": {}}
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.
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.
Argument | Type | Description |
| string | ID of the Plan associated with the subscription. |
| string | Name of subscription method. Must be |
| string | A short description. |
| boolean | If |
POST /subscriptions HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <jwt>X-Builton-Api-Key: <builton-api-key>Host: api.builton.dev​{"plan": "5931697ed57ba271c0c7de66","subscription_method": "license"}
HTTP/1.1 200 OKContent-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}
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.
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.
​
Attribute | Type | Description |
|
| Must be |
|
| ​ Payment Method created with the card details (number, expiration month, expiration year, cvc). Stripe references: |
POST /payment_methods HTTP/1.1Content-Type: application/jsonAuthorization: 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 OKContent-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}}
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.
