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