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.
Changes since API version 2019-02-01
Due a consistent issue, the image
field became an Image
Object.
We are deprecating the old image_url
and replacing it with image.
Attribute | Type | Description |
|
| The name of the product. |
|
| Human readable ID that identifies the order easily, e.g. |
|
| Three letter currency code in standard ISO 4217 format. |
|
| The price of the product. |
|
| The discount of the product, as a decimal between 0.0 and 0.1, e.g. 0.25 = 25%. |
|
| 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. |
|
| The percentage of VAT in the product price, as a decimal between 0.0 and 0.1, e.g. 0.25 = 25%. |
|
| A full description of the product. |
|
| A brief description of the product. |
|
| Flag that marks whether or not it is a main product. Default is |
|
| A list of sub products under the main product. |
|
| The sub product’s parent. |
|
| List of tags associated with the product. |
|
| Dynamic product properties, supports any valid JSON. |
|
| The main |
|
| List of |
|
| URL for the product. Default is set to '/'. |
|
| 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%.
Attributes | Descriptions |
| Defines the type of media included. We only support |
| The path or URL of your image. |
| The name of the image. |
| 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. |
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.
Path Parameter | Type | Description |
|
| The product’s ID. |
GET /products/<product_id> HTTP/1.1Content-Type: application/jsonX-Builton-Api-Key: <builton-api-key>Host: api.builton.dev
HTTP/1.1 200 OKContent-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]}
Query Parameters | Type | Description |
|
| Number of items to retrieve. Default is 10. |
|
| Which page to retrieve. Default is 0. |
|
| Field used for sorting results. Default is |
|
| Start date, |
|
| End date, |
|
| Date field used to filter results. Default is |
|
| Define the latitude. |
|
| Define the longitude. |
|
| If |
|
| If |
GET /products HTTP/1.1Content-Type: application/jsonX-Builton-Api-Key: <builton-api-key>Host: api.builton.dev
HTTP/1.1 200 OKContent-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]}]
Query Parameters | Type | Description |
|
| What you want to search for, e.g., name, description, or id. |
|
| Number of items to retrieve. Default is 10. |
|
| Which page to retrieve. Default is 0. |
|
| Field used for sorting results. Default is |
|
| Start date, |
|
| End date, |
|
| Date field used to filter results. Default is |
|
| Define the latitude. |
|
| Define the longitude. |
|
| If |
GET /products/search?query=description HTTP/1.1Content-Type: application/jsonX-Builton-Api-Key: <builton-api-key>Host: api.builton.dev
HTTP/1.1 200 OKContent-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]}]
Find more information regarding searching with tags here​
Query Parameters | Type | Description |
|
| Values of tags to retrieve. |
|
| Number of items to retrieve. Default is 10. |
|
| Which page to retrieve. Default is 0. |
|
| Field used for sorting results. Default is |
|
| Start date, |
|
| End date, |
|
| Date field used to filter results. Default is |
|
| Define the latitude. |
|
| Define the longitude. |
|
| If |
GET /products/tags?tags=Phone HTTP/1.1Content-Type: application/jsonX-Builton-Api-Key: <builton-api-key>Host: api.builton.dev
HTTP/1.1 200 OKContent-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}]
*Paths listed above and denoted with a star are accessible to both Users and Admins. Additional Admin Role paths are listed below.
Body Parameter | Type | Description |
|
| The name of the product. |
|
| The price of the product. |
|
| The discount of the product, as a decimal between 0.0 and 0.1, e.g. 0.25 = 25%. |
|
| Three letter currency doe in standard ISO 4217 format. |
|
| The percentage of VAT in the product price, as a decimal between 0.0 and 0.1, e.g. 0.25 = 25%. |
|
| A full description of the product. |
|
| A brief description of the product. |
|
| Flag that marks whether or not it is a main product. Default is |
|
| List of sub-products under the product. Default is set to [ ]. |
|
| List of tags associated with the product. |
|
| The product's properties. |
|
| An |
|
| List of |
|
| An external reference, e.q: ID from Shopify or Magento |
POST /products HTTP/1.1Content-Type: application/jsonAuthorization: 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 OKContent-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:
POST /products HTTP/1.1Content-Type: application/jsonX-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 OKContent-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"}]}
A product can have multiple sub-products associated with it. These are found in the field _sub_products
.
To get an Image ID you have to create it in amount. Here you will find how to create an Image object.
PUT /products/<product-id> HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <service-account-key>X-Builton-Api-Key: <builton-api-key>Host: api.builton.dev​{"image": "5d1dfd344c5274000bb346d9"}
HTTP/1.1 200 OKContent-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
Path Parameters | Type | Description |
|
| Product ID of main product. |
Body Parameters | Type | Description |
|
| Array of sub-product ids to associate with main product. |
PUT /products/5c7fc967383117000d193a91/sub_products HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <service-account-key>X-Builton-Api-Key: <builton-api-key>Host: api.builton.dev​{"add": [<product_id>, <product_id>]}
HTTP/1.1 200 OKContent-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":"/"}