Sell a Thing

I just wanna sell a thing. How is that hard? It's not!

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:
1.Create a user
2.Create a product
3.Make an order
4.Pay for it.
Create a User
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.
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": "[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 Product
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.
Make an Order
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.
Parameters
Request
Response
Body Parameters
Type
Description
currency
string
3 letter ISO currency code as defined by ISO 4217.
billing_address
object
Address used for billing purposes.
deliveries
array
Used to store the delivery history for an order.
delivery_address
object
Address used for delivery.
delivery_status
string
See delivery statuses. Default is PENDING.
delivery_time
object
Expected arrival time for delivery, timestampformat.
order_status
string
See order statuses. Default is CREATED.
items
array
List of items associated with an order.
human_id
string
Human readable ID that identifies the order easily, e.g. 3AG7UA.
payments
array
List of Payment objects associated with order.
payment_method
object
See Payment Methodfor more info on the payment method object.
resources
array
The resources in the order.
top_up_amount
number
Extra amount added to total_amount to fulfill the company’s minimum order value.
top_up_vat
float
The VAT percentage on the top_up_amount. Decimal from 0.0 to 1.0, e.g. 0.25 = 25%.
total_amount
float
Amount with two decimals. e.g., 12.34. The amount is automatically calculated based on items in the order.
total_quantity
number
Total number of products in an order, e.g. 3 spoons and 2 forks = 5 products.
units
number
Number of unique products in an order, e.g. 3 spoons and 2 forks = 2 product units.
accounting_reference
string
An accounting reference ID.
stripe_charge_id
string
The reference ID from a Stripe charge.
stripe_refund_id
string
The reference ID from a Stripe refund.
subscription
object
AssociatedSubscription referenced by subscription_id.
POST /orders HTTP/1.1
Content-Type: application/json
Authorization: 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 OK
Content-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"
}
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.
token
string
Token created with the card details (number, expiration month, expiration year, card verification code).
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",
  "token": "tok_1Bv5yfEeeXxFpLJtpWYeGYuy"
}
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",
  "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
  }
}
2. Pay the order
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.
Parameters
Request
Response
Arguments
Type
Description
orders
array
List with orders to be paid.
payment_method
string
The payment method ID that you want to use.
POST /payments HTTP/1.1
Content-Type: application/json
Authorization: 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 OK
Content-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.

Blueprints (Use Cases) - Previous

What Kind of Build?

Next - Blueprints (Use Cases)

Subscribe!

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.

Body Parameters	Type	Description
`currency`	`string`	3 letter ISO currency code as defined by ISO 4217.
`billing_address`	`object`	`Address` used for billing purposes.
`deliveries`	`array`	Used to store the delivery history for an order.
`delivery_address`	`object`	`Address` used for delivery.
`delivery_status`	`string`	See `delivery statuses`. Default is `PENDING`.
`delivery_time`	`object`	Expected arrival time for delivery, `timestamp`format.
`order_status`	`string`	See `order statuses`. Default is `CREATED`.
`items`	`array`	List of `items` associated with an order.
`human_id`	`string`	Human readable ID that identifies the order easily, e.g. `3AG7UA.`
`payments`	`array`	List of `Payment` objects associated with order.
`payment_method`	`object`	See `Payment Method`for more info on the payment method object.
`resources`	`array`	The `resources` in the order.
`top_up_amount`	`number`	Extra amount added to `total_amount` to fulfill the company’s minimum order value.
`top_up_vat`	`float`	The VAT percentage on the `top_up_amount.` Decimal from 0.0 to 1.0, e.g. 0.25 = 25%.
`total_amount`	`float`	Amount with two decimals. e.g., 12.34. The amount is automatically calculated based on items in the order.
`total_quantity`	`number`	Total number of products in an order, e.g. 3 spoons and 2 forks = 5 products.
`units`	`number`	Number of unique products in an order, e.g. 3 spoons and 2 forks = 2 product units.
`accounting_reference`	`string`	An accounting reference ID.
`stripe_charge_id`	`string`	The reference ID from a Stripe charge.
`stripe_refund_id`	`string`	The reference ID from a Stripe refund.
`subscription`	`object`	Associated`Subscription` referenced by subscription_id.

Attribute	Type	Description
`payment_method`	`string`	Must be `stripe` for triggering a Stripe payment method.
`token`	`string`	Token created with the card details (number, expiration month, expiration year, card verification code).

Arguments	Type	Description
`orders`	`array`	List with `orders` to be paid.
`payment_method`	`string`	The payment method ID that you want to use.