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:

  1. Main products can have many sub-products.

  2. A sub-product can have many main, aka parent, products.

  3. A sub-product can not have any sub-products of its own.

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

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

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

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

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

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

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

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.

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>]
}
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":"/"
}