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

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

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

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

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

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