Sell a Thing
One of the the simplest flows you can make with our Building Blocks is to have a customer buy something. We're going to go through that flow step by step. For simplicity's sake, we're assuming you have your authentication and payment solutions in place already.
Let's pretend you're selling used DVDs, because that's super relevant. You're going to do these things:
Create a user
Create a product
Make an order
Pay for it.
Eventually, you'll want to check out the User Object and all the related endpoints you can hit. But, 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": "[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 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": "[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": {}}
You create products through the dashboard. It's very simple. Under the Orders tab, you'll see Products. Near the top will be New product +. Click that and give it a name, set the price and VAT. You're then taken to that product's details, which you can fill in to your heart's content. Pop over to the Products and see all its associated endpoints when you're ready.
Aka, Create an Order. Check out the Order Object and all its related endpoints for more info. But if you're just trying to make an order for a couple DVDs, you use /orders.
Body Parameters | Type | Description |
|
| 3 letter ISO currency code as defined by ISO 4217. |
|
|
|
|
| Used to store the delivery history for an order. |
|
|
|
|
| See |
|
| Expected arrival time for delivery, |
|
| See |
|
| List of |
|
| Human readable ID that identifies the order easily, e.g. |
|
| List of |
|
| See |
|
| The |
|
| Extra amount added to |
|
| The VAT percentage on the |
|
| Amount with two decimals. e.g., 12.34. The amount is automatically calculated based on items in the order. |
|
| Total number of products in an order, e.g. 3 spoons and 2 forks = 5 products. |
|
| Number of unique products in an order, e.g. 3 spoons and 2 forks = 2 product units. |
|
| An accounting reference ID. |
|
| The reference ID from a Stripe charge. |
|
| The reference ID from a Stripe refund. |
|
| Associated |
POST /orders HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <jwt>X-Builton-Api-Key: <builton-api-key>Host: api.builton.dev​{"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": "I am a note."}
HTTP/1.1 200 OKContent-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"}
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 |
|
| Token created with the card details (number, expiration month, expiration year, card verification code). |
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","token": "tok_1Bv5yfEeeXxFpLJtpWYeGYuy"}
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","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}}
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 details.
Arguments | Type | Description |
|
| List with |
|
| The payment method ID that you want to use. |
POST /payments HTTP/1.1Content-Type: application/jsonAuthorization: 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 OKContent-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.
