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

2020-03-13 - New attribute `reserved_price`

Since we implemented a new Payment kind, Reserved Payment, we introduce this new attribute. It is used to calculate the amount of a Reserved Payment when it is in an Order.

2019-09-18 - `image` type changed to Object

image type changed to Image Object.

2019-09-02 - `image_url` Deprecated

We are deprecating the old image_urland replacing it with Image Object

Product objects now support Attributes! This is a new way of extending the functionality of objects so they fit your specific use case. Check out "Templates and Attributes" for more detailed information.

Attributes	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.
reserved_price	number	The price of the product used for a Reserved Payment. minimum value 0.
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 should be used to get the final price with the correct rounding.
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.
attributes	object	See "Templates and Attributes".

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 human readable ID. 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

Path Parameters	Type	Description
<product_id>	string	Product ID

HTTP

Request --

GET /products/5d2ed67ef1fc02000a6223e4 HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev

Response --

HTTP/1.1 200 OK
Content-Type: application/json

{
    '_id': {'$oid': '5d2ed67ef1fc02000a6223e4'},
    'name': 'Adidas - Falcon W',
    'short_description': 'Falcon W',
    'price': 1337,
    [...]
}

Core SDK / Node SDK

builton.products.get('5d2ed67ef1fc02000a6223e4').then(console.log);

/*
Product {
  id: '5d2ed67ef1fc02000a6223e4',
  name: 'Adidas - Falcon W',
  short_description: 'Falcon W',
  price: 1337,
  [...]
*/

Get List of All Products*

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.

HTTP

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

[
    {
        '_id': {'$oid': '5d2ed67ef1fc02000a6223e4'},
        'name': 'Adidas - Falcon W',
        'short_description': 'Falcon W',
        'price': 1337,
        [...]
    }
]

Core SDK / Node SDK

builton.products.get().then(page => {
  console.log(page.current); // First page
});

/*
[
  Product {
    id: '5d2ed67ef1fc02000a6223e4',
    name: 'Adidas - Falcon W',
    short_description: 'Falcon W',
    price: 1337,
    [...]
  }
]
*/

Search Products by Keywords*

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.

HTTP

Request --

GET /products/search?query=Adidas 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': '5d2ed67ef1fc02000a6223e4'},
        'name': 'Adidas - Falcon W',
        'short_description': 'Falcon W',
        'price': 1337,
        [...]
    }
]

Core SDK / Node SDK

builton.products
  .search('Adidas')
  .then(page => {
    console.log(page.current); // First page
  });

/*
[
  Product {
    id: '5d2ed67ef1fc02000a6223e4',
    name: 'Adidas - Falcon W',
    short_description: 'Falcon W',
    price: 1337,
    [...]
  }
]
*/

Search Products by Tags*

Find more information regarding searching with tags here

Parameters

Query Parameters	Type	Description
tags	string	Values of tags to search for, comma separated.
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.

HTTP

Request --

GET /products/tags?tags=adidas,men 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': '5d2ed67ef1fc02000a6223e4'},
        'name': 'Adidas - Falcon W',
        'short_description': 'Falcon W',
        'price': 1337,
        [...]
    }
]

Core SDK / Node SDK

builton.products
  .get({urlParams: {tags: ['adidas', 'men']}})
  .then(page => {
    console.log(page.current); // First page
  });

/*
[
  Product {
    id: '5d2ed67ef1fc02000a6223e4',
    name: 'Adidas - Falcon W',
    short_description: 'Falcon W',
    price: 1337,
    [...]
  }
]
*/

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

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
attributes	object	Attributes you want to add. For more explanation see "Templates and Attributes"

HTTP

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

{
    'name': 'Adidas - Falcon W',
    'price': 1337,
    'currency': 'NOK',
    'vat': 0.15
}

Response --

HTTP/1.1 200 OK
Content-Type: application/json

{
    '_id': {'$oid': '5d2ed67ef1fc02000a6223e4'},
    'name': 'Adidas - Falcon W',
    'price': 1337,
    [...]
}

Node SDK

builton.products
  .create({
    name: 'Adidas - Falcon W',
    price: 1337,
    currency: 'NOK',
    vat: 0.15
  }})
  .then(console.log);

/*
Product {
  id: '5d2ed67ef1fc02000a6223e4',
  name: 'Adidas - Falcon W',
  price: 1337,
  [...]
}
*/

Update the Sub-Products in a Product

A product can have multiple sub-products associated with it. These are found in the field _sub_products.

Parameters

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

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

HTTP

Request --

PUT /products/5c7fc967383117000d193a91 HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev

{
  '_sub_products': [<product_id>, <product_id>]
}

Response --

HTTP/1.1 200 OK
Content-Type: application/json

{  
   '_id': {'$oid': '5c7fc967383117000d193a91'},
   '_sub_products':[{'$oid': '5cee4feceec872503d9a17e5'}, 
                     {'$oid': '5cee4feceec872503d9a17e7'}],
    [...]
}

Node SDK

builton.products
  .update('5c7fc967383117000d193a91', {
    '_sub_products': ['5cee4feceec872503d9a17e5', '5cee4feceec872503d9a17e5']
  }})
  .then(console.log);

/*
Product {
  id: '5d2ed67ef1fc02000a6223e4',
  _sub_products: [{'$oid': '5cee4feceec872503d9a17e5'}, 
                   {'$oid': '5cee4feceec872503d9a17e7'}],
}
*/

Update a Product with an Image

To get an Image ID you have to create an image. Head up to the image documentation to learn how to do so.

Parameters

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

Body Parameters	Type	Description
image	string	Image ID.

HTTP

Request --

PUT /products/5d2ed67ef1fc02000a6223e4 HTTP/1.1
Content-Type: application/json
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'},
   'image': {
        '$oid': '5d1dfd344c5274000bb346d9'
    }
    [...]
}

Node SDK

builton.products
  .update('5d2ed67ef1fc02000a6223e4', {
    'image': '5d1dfd344c5274000bb346d9'
  }})
  .then(console.log);

/*
Product {
  id: '5d2ed67ef1fc02000a6223e4',
 'image': {
    '$oid': '5d1dfd344c5274000bb346d9'
  }
}
*/

Update a Product with a Medium

When creating or updating 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. We currently only support Media of type Image.

Parameters

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

Body Parameters	Type	Description
media	object	List of Medium.

HTTP

Request --

PUT /products/5d2ed67ef1fc02000a6223e4 HTTP/1.1
Content-Type: application/json
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev

{
    'media': [
        {
            'kind': 'image',
            'url': 'https://placekitten.com/1408/987',
            'name': 'kitten'
        }, 
        {
            'image': '5a2a837a9bb92800137cb16f'
        }
    ]
}

Response --

HTTP/1.1 200 OK
Content-Type: application/json

{
   '_id': {'$oid': '5c7fc967383117000d193a91'},
   'media': [
        {
            'kind': 'image',
            'url': 'https://placekitten.com/1408/987',
            'name': 'kitten',
            'human_id': 'NzpX63'
        },
        {
            'kind': 'image',
            'url': 'https://builton.cdn/images/5a2a837a9bb92800137cb16f',
            'name': 'Image title',
            'human_id': 'WapY62'
        }
    ],
    [...]
}

Node SDK

builton.products
  .update('5d2ed67ef1fc02000a6223e4', {
    'media': [
      {
        'kind': 'image',
        'url': 'https://placekitten.com/1408/987',
        'name': 'kitten'
      }, 
      {
        'image': '5a2a837a9bb92800137cb16f'
      }
    ]
  }})
  .then(console.log);

/*
Product {
  id: '5d2ed67ef1fc02000a6223e4',
  media: [
    {
      kind: 'image',
      url: 'https://placekitten.com/1408/987',
      name: 'kitten',
      human_id: 'NzpX63'
    },
    {
      kind: 'image',
      url: 'https://builton.cdn/images/5a2a837a9bb92800137cb16f',
      name: 'Image title',
      human_id: 'WapY62'
    }
  ],
  [...]
}
*/