Templates and Attributes

Now you can extend our existing models with attributes that match your specific business logic.

Templates and Attributes are still in beta. Please use them with caution. Currently, Templates can only use the Product model, but we'll be releasing it for Resources, Users, Coupons, Orders, Payments, Subscriptions and Plans. 
Template Object
Templates let you create the attributes you need for your specific use case.  Create a Template of a Product and give it any attributes you need that aren't included in the existing, default Product Object list of attributes. 
Attributes
Type
Description
name
string
The name of the template.
model
string
The model this template is going to use. Current choices:Product
attributes
array
Definitions of the attributes you want to add.
Attribute Definitions
Attributes
Type
Description
key
string
The name of the attribute.
kind
string
The type of attribute. Choices:string, url,email,int,float,boolean
human_id
string
Read only, human readable id for each attribute you create.
Create a Template
Parameters
Request
Response
Parameters
Body Parameters
Type
Description
name
string
The name of the template.
model
string
The model this template is going to use.
attributes
array
Definitions of the attributes you want to add.
Request
POST /templates HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
​
{
    "name": "Android Phone",
    "model": "Product",
    "attributes": [
        {
            "key": "RAM_size",
            "kind": "int"
        },{
            "key": "OS_version",
            "kind": "string"
        },{
            "key": "dual_SIM",
            "kind": "boolean"
        }
    ]
}
Response
HTTP/1.1 200 OK
Content-type: application/json
​
{
    "_id":{"$oid":"591ee163b70e2a10acb653a7"},
    "name": "Android Phone",
    "model": "Product",
    "attributes": [
        {
            "key": "RAM_size",
            "kind": "int",
            "human_id": "3DR29S"
        },{
            "key": "OS_version",
            "kind": "string",
            "human_id": "TY13PR"
        },{
            "key": "dual_SIM",
            "kind": "boolean",
            "human_id": "5O9P3C"
        }
    ]
}
While this feature is in beta, we only support 1 Template per model.
Update a Template*
Parameters
Request
Response
Parameters
Path Parameter
Type
Description
template_id
string
ID of the queried order.
Body Parameters
Type
Description
name
string
The name of the template.
model
string
Which model is going to use this template.
attributes
array
Definitions of the attributes you want to add.
Request
PUT /templates/591ee163b70e2a10acb653a7 HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
​
{
    "name": "My new name for Android Phone Template",
    "attributes": [
        {
            "key": "RAM_size",
            "kind": "int",
            "human_id": "3DR29S"
        },{
            "key": "OS_version",
            "kind": "string",
            "human_id": "TY13PR"
        },{
            "key": "dual_SIM",
            "kind": "boolean",
            "human_id": "5O9P3C"
        },{
            "key": "phone_screen",
            "kind": "float"
        }
    ]
}
Response
HTTP/1.1 200 OK
Content-type: application/json
​
{
    "_id":{"$oid":"591ee163b70e2a10acb653a7"},
    "name": "My new name for Android Phone Template",
    "model": "Product",
    "attributes": [
        {
            "key": "RAM_size",
            "kind": "int",
            "human_id": "3DR29S"
        },{
            "key": "OS_version",
            "kind": "string",
            "human_id": "TY13PR"
        },{
            "key": "dual_SIM",
            "kind": "boolean",
            "human_id": "5O9P3C"
        },{
            "key": "phone_screen",
            "kind": "float"
        }
    ]
}
There are some restrictions on updating the templates.
You can edit the name of the template.
You can add more attributes to the template.
You can not change the model of the template.
You can not remove attributes from the template.
You can not edit an attribute's key or kindin the template.
When updating a template, you need to send existing attributes with their human_id .
List all Templates
Parameters
Request
Response
Parameters
Query Parameters
Type
Description
size
number
Number of items to retrieve.
page
number
Which page to retrieve. Default is 10.
sort
string
Field used for sorting results. Default is created.
from_date
number
Start date, timestamp format. Default is current date minus 15 days.
to_date
number
End date, timestamp format. Default is current date plus 15 days.
date_filter
string
Date field used to filter results. Default is created.
Request
GET /templates 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":"591ee163b70e2a10acb653a7"},
    "name": "Android Phone",
    "model": "Product",
    "attributes": [
        {
            "key": "RAM_size",
            "kind": "int",
            "human_id": "3DR29S"
        },{
            "key": "OS_version",
            "kind": "string",
            "human_id": "TY13PR"
        },{
            "key": "dual_SIM",
            "kind": "boolean",
            "human_id": "5O9P3C"
        }
    ]
}
]
Delete a Template
Parameters
Request
Response
Parameters
Path Parameter
Type
Description
template_id
string
ID of the queried order.
Request
DELETE /templates/591ee163b70e2a10acb653a7 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":"591ee163b70e2a10acb653a7"},
    "name": "Android Phone",
    "model": "Product",
    "attributes": [
        {
            "key": "RAM_size",
            "kind": "int",
            "human_id": "3DR29S"
        },{
            "key": "OS_version",
            "kind": "string",
            "human_id": "TY13PR"
        },{
            "key": "dual_SIM",
            "kind": "boolean",
            "human_id": "5O9P3C"
        }
    ],
    "deleted":true
}
When you delete a template, all the related attributes will be deleted from all instances of that model.
How to use Attributes
This is very easy! You can add, update or remove attributes via your POSTor PUT request's body.
Request
Response
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"
​
    "attributes": {
        "RAM_size": 6,
        "OS_version": "7.1.0",
        "dual_SIM": false
    }
}
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",
​
    "attributes": {
        "RAM_size": 6,
        "OS_version": "7.1.0",
        "dual_SIM": false
    }
}

Nuts & Bolts - Previous

Images

Next - Building Blocks

Users

Last updated 5 months ago

Attributes	Type	Description
`name`	`string`	The name of the template.
`model`	`string`	The model this template is going to use. Current choices:`Product`
`attributes`	`array`	Definitions of the attributes you want to add.

Attributes	Type	Description
`key`	`string`	The name of the attribute.
`kind`	`string`	The type of attribute. Choices:`string`, `url`,`email`,`int`,`float`,`boolean`
`human_id`	`string`	Read only, human readable id for each attribute you create.

Query Parameters	Type	Description
`size`	`number`	Number of items to retrieve.
`page`	`number`	Which page to retrieve. Default is 10.
`sort`	`string`	Field used for sorting results. Default is `created.`
`from_date`	`number`	Start date, `timestamp` format. Default is current date minus 15 days.
`to_date`	`number`	End date, `timestamp` format. Default is current date plus 15 days.
`date_filter`	`string`	Date field used to filter results. Default is `created.`

Body Parameters	Type	Description
`name`	`string`	The name of the template.
`model`	`string`	The model this template is going to use.
`attributes`	`array`	Definitions of the attributes you want to add.

Path Parameter	Type	Description
`template_id`	`string`	ID of the queried order.