Retrieve Items

Where is that thing?

You can usually retrieve items from all our Building Blocks in two ways. Either with a straight GET call or using the more advanced GET request, search. Check the respective Building Block for detailed examples.

You can use filtering, pagination and sorting to navigate through the ginormous lists you'll get if you, for example, GET /products and you have a million products.

Filter by date
Pagination
Sorting

Parameter

Type

Description

from_date

number

Start date, in timestamp format. Default is none.

to_date

number

End date, in timestamp format. Default is none.

date_filter

string

Date field used to filter results. Default is CREATED.

Parameter

Type

Description

size

number

Number of items to retrieve. Default is 10.

page

number

Which page to retrieve. Default is 0.

Parameter

Type

Description

sort

string

Field used for sorting results.

List Items

This is a straight GET call to our APIs. Here's an example that lists all your Orders, but it works the same for all the Building Blocks.

Note: You may not need the Authorization header to retrieve certain items. For example, you'd want to be able to show your products to people without requiring them to have a valid JWT. I.e., you don't have to sign in to search Amazon's website. Your user's payment methods, on the other hand, would require it.

Request
Response
GET /orders HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"units":2,
"delivery_status":"ACCEPTED",
"currency":"NOK",
"human_id":"51Q4LN",
"payments":[],
"modified":{"$date":1495196003948},
"top_up_amount":0.0,
"stripe_charge_id":"",
"order_status":"CREATED",
"company":{"$oid":"591ee15db70e2a10acb65362"},
"billing_address":{
"city":"Danielsen",
"service":"google",
"alias":"",
"country":"Paraguay",
"zip_code":"0556",
"state":"Oslo",
"street_name":"Iversenstien 7"
},
"deliveries":[],
"items":[
{
"quantity":60,
"discount":0.9,
"product":{
"properties":{},
"parents":[],
"path":"/",
"default_position":[-1, -1],
"created":{"$date":1494479087000},
"_id":{"$oid":"591ee15eb70e2a10acb65374"},
"tags":[],
"max_distance":0,
"main_product":true,
"modified":{"$date":1495195998969},
"deleted":false,
"name":"Ivar",
"vat":0.0,
"company":{"$oid":"591ee15db70e2a10acb65362"},
"active":true,
"_cls":"Product",
"currency":"USD",
"company_take":-1.0,
"_sub_products":[],
"business_rules":[],
"price":100.0
}
}
],
"note":"",
"created":{"$date":1495264401233},
"delivery_address":{
"city":"Danielsen",
"service":"google",
"alias":"",
"country":"Paraguay",
"zip_code":"0556",
"state":"Oslo",
"street_name":"Iversenstien 7"
},
"total_quantity":120,
"_id":{"$oid":"591ee163b70e2a10acb653a7"},
"total_amount":1200.0,
"stripe_refund_id":"",
"override_company_take":-1.0,
"user":{...},
"delivery_time":{"$date":1497009600000}
}
]

Search for Items

This method allows you to retrieve a list of items, like user_name or account_number, that match a search query without specifying that you are searching for user_name or account_number. Check the respective Building Block for detailed examples, but here's an example of searching for a particular order.

Request
Response
GET /orders/search?query=51Q4LN HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"units":2,
"delivery_status":"ACCEPTED",
"currency":"NOK",
"human_id":"51Q4LN",
"payments":[],
"modified":{"$date":1495196003948},
"top_up_amount":0.0,
"stripe_charge_id":"",
"order_status":"CREATED",
"company":{"$oid":"591ee15db70e2a10acb65362"},
"billing_address":{
"city":"Danielsen",
"service":"google",
"alias":"",
"country":"Paraguay",
"zip_code":"0556",
"state":"Oslo",
"street_name":"Iversenstien 7"
},
"deliveries":[],
"items":[
{
"quantity":60,
"discount":0.9,
"product":{
"properties":{},
"parents":[],
"path":"/",
"default_position":[-1, -1],
"created":{"$date":1494479087000},
"_id":{"$oid":"591ee15eb70e2a10acb65374"},
"tags":[],
"max_distance":0,
"main_product":true,
"modified":{"$date":1495195998969},
"deleted":false,
"name":"Ivar",
"vat":0.0,
"company":{"$oid":"591ee15db70e2a10acb65362"},
"active":true,
"_cls":"Product",
"currency":"USD",
"company_take":-1.0,
"_sub_products":[],
"business_rules":[],
"price":100.0
}
}
],
"note":"",
"created":{"$date":1495264401233},
"delivery_address":{
"city":"Danielsen",
"service":"google",
"alias":"",
"country":"Paraguay",
"zip_code":"0556",
"state":"Oslo",
"street_name":"Iversenstien 7"
},
"total_quantity":120,
"_id":{"$oid":"591ee163b70e2a10acb653a7"},
"total_amount":1200.0,
"stripe_refund_id":"",
"override_company_take":-1.0,
"user":{...},
"delivery_time":{"$date":1497009600000}
}
]

Search by Tag

The Building Blocks Users, Products and Resources can all have tags added to them.

There are three ways to search by tag. You can search for:

  1. Any item that has that tag, even if they have other tags, too. E.g. all items that have glove as a tag . Code: ?tags=tag_1

  2. Items that have multiple tags. E.g. all items that have glove and black as a tag. Code: ?tags=tag_1+tag_2

  3. Items that have only one tag. E.g. a really boring glove that has no other tags. Code: ?tags=tag_1+

You can combine these into complex searches.

e.g.: ?tags=glove+red,skis+,socks

The above would return all products that have both red and glove tags, all products that only are tagged with ski, and all the socks.