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.
A sub-product can not be purchased without it's parent product.
Product Object
Changes since API version 2019-02-01
2019-09-18 - `image` type changed to Object
Due a consistent issue, the imagefield became an Image Object.
2019-09-02 - `image_url` Deprecated
We are deprecating the old image_urland replacing it with image.
Attribute
Type
Description
name
string
The name of the product.
human_id
string
Human readable ID that identifies the order easily, e.g. 3AG7UA.
currency
string
Three letter currency code in standard ISO 4217 format.
price
number
The price of the product.
discount
float
The discount of the product, as a decimal between 0.0 and 0.1,  e.g. 0.25 = 25%.
final_price
float
The price of the product calculated with the discount.
It will help you to not calculate the price wrongly because of round or something else. 
vat
number
The percentage of VAT in the product price, as a decimal between 0.0 and 0.1,  e.g. 0.25 = 25%.
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.
tags
array
List of tags associated with the product.
properties
object
Dynamic product properties, supports any valid JSON.
image
object
The main Image object for this product.
media
array
List of Medium.
path
string
URL for the product. Default is set to '/'.
external_reference
string
An external reference, e.q: ID from Shopify or Magento.
Note: A Main Product is the same thing as a Parent Product.
When creating a Product using the dashboard, the VAT amount should be given as a percentage, e.g. 25 = 25%.  When using the API, the VAT amount should be given as a number between 0 and 1, e.g. 0.25 = 25%.
Medium Object
Attributes
Descriptions
kind
Defines the type of media included. We only support image for now but more coming soon.
url
The path or URL of your image.
name
The name of the image.
human_id
A readable ID that is usable for a human.  It's a string 6 characters long that is created automatically when the Product is saved.  It can also be set manually.
User Role
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.
Retrieve a Product*
Parameters
Request
Response
Parameters
Path Parameter
Type
Description
product_id
string
The product’s ID.
Request
GET /products/<product_id> HTTP/1.1
Content-Type: application/json
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
Response
HTTP/1.1 200 OK
Content-Type: application/json
​
{  
   "_cls":"Product",
   "parents":[],
   "tags":["fuzz", "Foo", "Bar"],
   "price":3.14,
   "discount": 0.0,
   "final_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
Parameters
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.
Request
GET /products HTTP/1.1
Content-Type: application/json
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
Response
HTTP/1.1 200 OK
Content-Type: application/json
​
[  
    {
       "_cls":"Product",
       "parents":[],
       "tags":["fuzz", "Foo", "Bar"],
       "price":3.14,
       "discount": 0.0,
       "final_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
Parameters
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.
Request
GET /products/search?query=description HTTP/1.1
Content-Type: application/json
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
Response
HTTP/1.1 200 OK
Content-Type: application/json
​
[
    {
       "_cls":"Product",
       "parents":[],
       "tags":["fuzz", "Foo", "Bar"],
       "price":3.14,
       "discount": 0.0,
       "final_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
Parameters
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.
Request
GET /products/tags?tags=Phone HTTP/1.1
Content-Type: application/json
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
Response
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,
        "discount": 0.0,
        "final_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
    }
]
Admin Role
*Paths listed above and denoted with a star are accessible to both Users and Admins. Additional Admin Role paths are listed below.
Create a Product
Parameters
Request
Response
Parameters
Body Parameter
Type
Description
name
string
The name of the product.
price
number
The price of the product.
discount
float
The discount of the product, as a decimal between 0.0 and 0.1,  e.g. 0.25 = 25%.
currency
string
Three letter currency doe in standard ISO 4217 format.
vat
number
The percentage of VAT in the product price, as a decimal between 0.0 and 0.1, e.g. 0.25 = 25%.
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 trueindicating it is a main product.
_sub_product
array
List of sub-products under the product. Default is set to [ ].
tags
array
List of tags associated with the product.
properties
object
The product's properties.
image
string
An Image ID for the product
media
object
List of Medium.
external_reference
string
An external reference, e.q: ID from Shopify or Magento
Request
POST /products HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
​
{
    "description": "It is a test product",
    "currency": "NOK",
    "price": 3.14,
    "name": "Product Name",
    "vat": 0.15,
    "external_reference": "123456abcd"
}
Response
HTTP/1.1 200 OK
Content-Type: application/json
​
{  
   "_id": {"$oid": "5c7fc967383117000d193a91"},
   "max_distance":0,
   "created":{  
      "$date":1492777046366
   },
   "default_position":[-1, -1],
   "_cls":"Product",
   "description":"",
   "modified":{  
      "$date":1492777046369
   },
   "_sub_products":[],
   "name":"Product Name",
   "properties":{},
   "price":3.14,
   "active":false,
   "tags":[],
   "vat": 0.15,
   "company":{"$oid":"57ee9c71d76d431f8511142f"},
   "deleted":false,
   "company_take":-1.0,
   "parents":[],
   "main_product":true,
   "currency":"NOK",
   "path":"/",
   "external_reference": "123456abcd"
}
When creating a product with Media you could use one of two ways. You can define a  Medium object or provide an Image id. In the case you provide an Image id we will create a Medium object for you. This way, you can be sure that when you get a list of Media you will have it in a consistent manner. The same should work when updating your products. Below, you can see an example:
Request
Response
Request
POST /products HTTP/1.1
Content-Type: application/json
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
​
{
    "name": "awesome product",
    "price": 42.42,
    "currency": "NOK",
    "media": [
        {
            "kind": "image",
            "url": "https://unsplash.com/photos/MNFy7m7w9PQ",
            "name": "My Awesome Image"
        }, 
        {
            "image": "5a2a837a9bb92800137cb16f"
        }
    ]
    
}
Response
HTTP/1.1 200 OK
Content-Type: application/json
​
{  
   "_id": {"$oid": "5c7fc967383117000d193a91"},
   "max_distance":0,
   "created":{  
      "$date":1492777046366
   },
   "default_position":[-1, -1],
   "_cls":"Product",
   "description":"",
   "modified":{  
      "$date":1492777046369
   },
   "_sub_products":[],
   "name":"awesome product",
   "properties":{},
   "price":42.42,
   "active":false,
   "tags":[],
   "vat": 0.0,
   "company":{"$oid":"57ee9c71d76d431f8511142f"},
   "deleted":false,
   "company_take":-1.0,
   "parents":[],
   "main_product":true,
   "currency":"NOK",
   "path":"/",
   "media": [
        {
            "kind": "image",
            "url": "https://unsplash.com/photos/MNFy7m7w9PQ",
            "name": "My Awesome Image",
            "human_id": "NzpX63"
        },
        {
            "kind": "image",
            "url": "https://builton.cdn/images/5a2a837a9bb92800137cb16f",
            "name": "Image title",
            "human_id": "WapY62"
        }
    ]
}
Add a Sub-Product to Product
A product can have multiple sub-products associated with it. These are found in the field _sub_products.
Update a Product with an Image
To get an Image ID you have to create it in amount. Here you will find how to create an Image object.
Request
Response
Request
PUT /products/<product-id> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
​
{
	"image": "5d1dfd344c5274000bb346d9"
}
Response
HTTP/1.1 200 OK
Content-Type: application/json
​
{  
   "_id": {"$oid": "5c7fc967383117000d193a91"},
   "max_distance":0,
   "created":{  
      "$date":1492777046366
   },
   "default_position":[-1, -1],
   "_cls":"Product",
   "description":"",
   "modified":{  
      "$date":1492777046369
   },
   "_sub_products":[],
   "name":"Product Name",
   "properties":{},
   "price":3.14,
   "active":false,
   "tags":[],
   "vat": 0.15,
   "company":{"$oid":"57ee9c71d76d431f8511142f"},
   "deleted":false,
   "company_take":-1.0,
   "parents":[],
   "main_product":true,
   "currency":"NOK",
   "path":"/",
   "external_reference": "123456abcd",
   "image": {
        "$oid": "5d1dfd344c5274000bb346d9"
    }
}
reate a Product with Media
Parameters
Request
Response
Parameters
Path Parameters
Type
Description
<product_id>
string
Product ID of main product.
Body Parameters
Type
Description
add
array
Array of sub-product ids to associate with main product.
Request
PUT /products/5c7fc967383117000d193a91/sub_products HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
​
{
    "add": [<product_id>, <product_id>]
}
Response
HTTP/1.1 200 OK
Content-Type: application/json
​
{  
   "_id": {"$oid": "5c7fc967383117000d193a91"},
   "max_distance":0,
   "created":{  
      "$date":1492777046366
   },
   "default_position":[-1, -1],
   "_cls":"Product",
   "description":"",
   "modified":{  
      "$date":1492777046369
   },
   "_sub_products":[{"$oid": "5cee4feceec872503d9a17e5"}, 
                     {"$oid": "5cee4feceec872503d9a17e7"}],
   "name":"Product Name",
   "properties":{},
   "price":3.14,
   "discount": 0.0,
   "final_price": 3.14,
   "active":false,
   "tags":[],
   "vat": 0.15,
   "company":{"$oid":"57ee9c71d76d431f8511142f"},
   "deleted":false,
   "company_take":-1.0,
   "parents":[],
   "main_product":true,
   "currency":"NOK",
   "path":"/"
}

Building Blocks - Previous

Users

Resources

Last updated 5 months ago

Attribute	Type	Description
`name`	`string`	The name of the product.
`human_id`	`string`	Human readable ID that identifies the order easily, e.g. `3AG7UA.`
`currency`	`string`	Three letter currency code in standard ISO 4217 format.
`price`	`number`	The price of the product.
`discount`	`float`	The discount of the product, as a decimal between 0.0 and 0.1, e.g. 0.25 = 25%.
`final_price`	`float`	The price of the product calculated with the discount. It will help you to not calculate the price wrongly because of round or something else.
`vat`	`number`	The percentage of VAT in the product price, as a decimal between 0.0 and 0.1, e.g. 0.25 = 25%.
`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.
`tags`	`array`	List of tags associated with the product.
`properties`	`object`	Dynamic product properties, supports any valid JSON.
`image`	`object`	The main `Image` object for this product.
`media`	`array`	List of `Medium`.
`path`	`string`	URL for the product. Default is set to '/'.
`external_reference`	`string`	An external reference, e.q: ID from Shopify or Magento.

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.

Body Parameter	Type	Description
`name`	`string`	The name of the product.
`price`	`number`	The price of the product.
`discount`	`float`	The discount of the product, as a decimal between 0.0 and 0.1, e.g. 0.25 = 25%.
`currency`	`string`	Three letter currency doe in standard ISO 4217 format.
`vat`	`number`	The percentage of VAT in the product price, as a decimal between 0.0 and 0.1, e.g. 0.25 = 25%.
`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_product`	`array`	List of sub-products under the product. Default is set to [ ].
`tags`	`array`	List of tags associated with the product.
`properties`	`object`	The product's properties.
`image`	`string`	An `Image` ID for the product
`media`	`object`	List of `Medium`.
`external_reference`	`string`	An external reference, e.q: ID from Shopify or Magento

Attributes	Descriptions
`kind`	Defines the type of media included. We only support `image` for now but more coming soon.
`url`	The path or URL of your image.
`name`	The name of the image.
`human_id`	A readable ID that is usable for a human. It's a string 6 characters long that is created automatically when the Product is saved. It can also be set manually.

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

Path Parameters	Type	Description
`<product_id>`	`string`	Product ID of main product.

Body Parameters	Type	Description
`add`	`array`	Array of sub-product ids to associate with main product.