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

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 /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": "[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 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

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.

Request

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

Response

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

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).

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",
  "token": "tok_1Bv5yfEeeXxFpLJtpWYeGYuy"
}

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

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

Request

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

Response

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.