Products

Products as a Building Block can be physical things or services performed. Our APIs don't care.
We also have the concept of main products and sub-products. If a user buys a car, that would be a main product. They might also get the nice leather interior. They can't buy leather interior without buying the car, so the nice leather interior would be a sub-product. However, you can use the main product and sub-product relationship as you see fit, just follow the rules.
Rules for Main and Sub-Products:
Main products can have many sub-products. 
A sub-product can have many main, aka parent, products. 
A sub-product can not have any sub-products of its own.
Product Object
Attribute
Type
Description
name
string
The name of the product.
currency
string
Three letter currency code in standard ISO 4217 format.
price
number
The price of the product.
description
string
A full description of the product.
short_description
string
A brief description of the product.
main_product
boolean
Flag that marks whether or not it is a main product. Default is true, indicating it is a main product.
_sub_products
array
A list of sub products under the main product.
parents
array
The sub product’s parent.
default_position
array
The geo position for the product.
tags
array
List of tags associated with the product.
properties
object
The product’s properties.
vat
number
The percentage of VAT in the product price, as a decimal between 0.0 and 0.1,  e.g. 0.25 = 25%.
Note: A Main Product is the same thing as a Parent Product.
Percentages are calculated on your behalf when creating a Product through the Dashboard. When using the Dashboard, the VAT amount should be given as number between 0 and 100, e.g. 25 = 25%. 
Create a Product
You create Products through the dashboard. Under Orders, you'll see Products. Click on that and you'll see New product + near the top. Enter the info and you're all set.
Retrieve a Product
Note: The methods used to retrieve, list and search products do not require the use of the User's authorization token. This allows a user to access information regarding a product or products without having to sign in.
Parameters
Request
Response
Path Parameter
Type
Description
product_id
string
The product’s ID.
GET /products/<product_id> HTTP/1.1
Content-Type: application/json
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
HTTP/1.1 200 OK
Content-Type: application/json
​
{  
   "_cls":"Product",
   "parents":[],
   "tags":["fuzz", "Foo", "Bar"],
   "price":3.14,
   "_sub_products":[],
   "deleted":false,
   "company_take":-1.0,
   "max_distance":0,
   "description":"description",
   "created":{"$date":1492781492460},
   "vat":0.0,
   "properties":{},
   "active":true,
   "name":"Product Name",
   "modified":{"$date":1492781492461},
   "company":{"$oid":"57ee9c71d76d431f8511142f"},
   "currency":"NOK",
   "path":"/",
   "main_product":true,
   "_id":{"$oid":"58f9f856b70e2a56c4a0db3d"},
   "business_rules":[],
   "default_position":[-1,-1]
}
Get List of All Products
Parameters
Request
Response
Query Parameters
Type
Description
size
number
Number of items to retrieve. Default is 10.
page
number
Which page to retrieve. Default is 0.
sort
string
Field used for sorting results. Default is created.
from_date
number
Start date, timestamp format. Default is None.
to_date
number
End date, timestamp format. Default is None.
date_filter
string
Date field used to filter results. Default is created.
lat
number
Define the latitude.
lng
number
Define the longitude.
all
boolean
If true, get all products and sub-products.
include_deleted
boolean
If true, deleted products are also listed.
GET /products HTTP/1.1
Content-Type: application/json
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
HTTP/1.1 200 OK
Content-Type: application/json
​
[  
    {
       "_cls":"Product",
       "parents":[],
       "tags":["fuzz", "Foo", "Bar"],
       "price":3.14,
       "_sub_products":[],
       "deleted":false,
       "company_take":-1.0,
       "max_distance":0,
       "description":"description",
       "created":{"$date":1492781492460},
       "vat":0.0,
       "properties":{},
       "active":true,
       "name":"Product Name",
       "modified":{"$date":1492781492461},
       "company":{"$oid":"57ee9c71d76d431f8511142f"},
       "currency":"NOK",
       "path":"/",
       "main_product":true,
       "_id":{"$oid":"58f9f856b70e2a56c4a0db3d"},
       "business_rules":[],
       "default_position":[-1,-1]
    }
]
Search Products by Keywords
Parameters
Request
Response
Query Parameters
Type
Description
query
string
What you want to search for, e.g., name, description, or id.
size
number
Number of items to retrieve. Default is 10.
page
number
Which page to retrieve. Default is 0.
sort
string
Field used for sorting results. Default is created.
from_date
number
Start date, timestamp format. Default is None.
to_date
number
End date, timestamp format. Default is None.
date_filter
string
Date field used to filter results. Default is created.
lat
number
Define the latitude.
lng
number
Define the longitude.
include_deleted
boolean
If true, deleted products are also listed.
GET /products/search?query=description HTTP/1.1
Content-Type: application/json
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
HTTP/1.1 200 OK
Content-Type: application/json
​
[
    {
       "_cls":"Product",
       "parents":[],
       "tags":["fuzz", "Foo", "Bar"],
       "price":3.14,
       "_sub_products":[],
       "deleted":false,
       "company_take":-1.0,
       "max_distance":0,
       "description":"description",
       "created":{"$date":1492781492460},
       "vat":0.0,
       "properties":{},
       "active":true,
       "name":"Product Name",
       "modified":{"$date":1492781492461},
       "company":{"$oid":"57ee9c71d76d431f8511142f"},
       "currency":"NOK",
       "path":"/",
       "main_product":true,
       "_id":{"$oid":"58f9f856b70e2a56c4a0db3d"},
       "business_rules":[],
       "default_position":[-1,-1]
    }
]
Search Products by Tags
Find more information regarding searching with tags here​
Parameters
Request
Response
Query Parameters
Type
Description
tags
string
Values of tags to retrieve.
size
number
Number of items to retrieve. Default is 10.
page
number
Which page to retrieve. Default is 0.
sort
string
Field used for sorting results. Default is created.
from_date
number
Start date, timestamp format. Default is None.
to_date
number
End date, timestamp format. Default is None.
date_filter
string
Date field used to filter results. Default is created.
lat
number
Define the latitude.
lng
number
Define the longitude.
include_deleted
boolean
If true, deleted products are also listed.
GET /products/tags?tags=Phone HTTP/1.1
Content-Type: application/json
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
HTTP/1.1 200 OK
Content-Type: application/json
​
[
    {
        "_id": {
            "$oid": "5a04552cd57ba2056e2f2d7b"
        },
        "name": "Apple iPhone 5 32GB",
        "default_position": [
            -1,
            -1
        ],
        "max_distance": 0,
        "main_product": true,
        "tags": [
            "name: Apple iPhone 5 32GB",
            "model: iPhone 5 32GB",
            "brand: Apple",
            "type: Phone"
        ],
        "price_change_percentage": 0,
        "price": 578,
        "modified": {
            "$date": 1511531313212
        },
        "company": {
            "$oid": "59ce1e0a9d3bde0006fa45a9"
        },
        "path": "/",
        "business_rules": [],
        "currency": "NOK",
        "active": true,
        "created": {
            "$date": 1510233388436
        },
        "vat": 0,
        "properties": {},
        "company_take": -1,
        "parents": [],
        "_sub_products": [
            {
                "$oid": "5a181f96d57ba21af74388f3"
            }
        ],
        "_cls": "Product",
        "deleted": true
    },
    {
        "_id": {
            "$oid": "5a04552dd57ba2056e2f2d7c"
        },
        "name": "Apple iPhone 5 64GB",
        "default_position": [
            -1,
            -1
        ],
        "max_distance": 0,
        "main_product": true,
        "tags": [
            "name: Apple iPhone 5 64GB",
            "model: iPhone 5 64GB",
            "brand: Apple",
            "type: Phone"
        ],
        "price_change_percentage": 0,
        "price": 658,
        "modified": {
            "$date": 1511531316451
        },
        "company": {
            "$oid": "59ce1e0a9d3bde0006fa45a9"
        },
        "path": "/",
        "business_rules": [],
        "currency": "NOK",
        "active": true,
        "created": {
            "$date": 1510233389215
        },
        "vat": 0,
        "properties": {},
        "company_take": -1,
        "parents": [],
        "_sub_products": [
            {
                "$oid": "5a181fa3d57ba21af74388fd"
            },
            {
                "$oid": "5a181fa3d57ba21af74388fe"
            }
        ],
        "_cls": "Product",
        "deleted": true
    }
]

Building Blocks - Previous

Users

Resources

Last updated last month

Attribute	Type	Description
`name`	`string`	The name of the product.
`currency`	`string`	Three letter currency code in standard ISO 4217 format.
`price`	`number`	The price of the product.
`description`	`string`	A full description of the product.
`short_description`	`string`	A brief description of the product.
`main_product`	`boolean`	Flag that marks whether or not it is a main product. Default is `true`, indicating it is a main product.
`_sub_products`	`array`	A list of sub products under the main product.
`parents`	`array`	The sub product’s parent.
`default_position`	`array`	The geo position for the product.
`tags`	`array`	List of tags associated with the product.
`properties`	`object`	The product’s properties.
`vat`	`number`	The percentage of VAT in the product price, as a decimal between 0.0 and 0.1, e.g. 0.25 = 25%.

Query Parameters	Type	Description
`size`	`number`	Number of items to retrieve. Default is 10.
`page`	`number`	Which page to retrieve. Default is 0.
`sort`	`string`	Field used for sorting results. Default is `created.`
`from_date`	`number`	Start date, `timestamp` format. Default is `None.`
`to_date`	`number`	End date, `timestamp` format. Default is `None.`
`date_filter`	`string`	Date field used to filter results. Default is `created.`
`lat`	`number`	Define the latitude.
`lng`	`number`	Define the longitude.
`all`	`boolean`	If `true`, get all products and sub-products.
`include_deleted`	`boolean`	If `true`, deleted products are also listed.

Query Parameters	Type	Description
`query`	`string`	What you want to search for, e.g., name, description, or id.
`size`	`number`	Number of items to retrieve. Default is 10.
`page`	`number`	Which page to retrieve. Default is 0.
`sort`	`string`	Field used for sorting results. Default is `created.`
`from_date`	`number`	Start date, `timestamp` format. Default is `None.`
`to_date`	`number`	End date, `timestamp` format. Default is `None.`
`date_filter`	`string`	Date field used to filter results. Default is `created.`
`lat`	`number`	Define the latitude.
`lng`	`number`	Define the longitude.
`include_deleted`	`boolean`	If `true`, deleted products are also listed.

Query Parameters	Type	Description
`tags`	`string`	Values of tags to retrieve.
`size`	`number`	Number of items to retrieve. Default is 10.
`page`	`number`	Which page to retrieve. Default is 0.
`sort`	`string`	Field used for sorting results. Default is `created.`
`from_date`	`number`	Start date, `timestamp` format. Default is `None.`
`to_date`	`number`	End date, `timestamp` format. Default is `None.`
`date_filter`	`string`	Date field used to filter results. Default is `created.`
`lat`	`number`	Define the latitude.
`lng`	`number`	Define the longitude.
`include_deleted`	`boolean`	If `true`, deleted products are also listed.

Path Parameter	Type	Description
`product_id`	`string`	The product’s ID.