Orders
Not that you need the concept of an Order explained to you, but we're going to do it anyway. It is what is made when a User picks a bunch of things, or just one, that they want to buy.
The
total_amount
is set by the items
and the resources
. See sections below for more details.An order can include only one currency, which means you can not create an order containing two products with two different currencies. Otherwise, you will get the following error:
Error code 400, message: An order can not have products with different currencies
Attributes | Type | Description |
currency | string | |
pickup_address | object | Address used to pickup a pac |
delivery_address | object | Address used for delivery. |
delivery_status | string | |
delivery_time | object | Expected arrival time for delivery, timestamp format. |
pickup_time | object | Expected arrival time for pickup, timestamp format. |
order_status | string | |
items | array | |
human_id | string | Human readable ID that identifies the order easily, e.g. 3AG7UA. |
payments | array | |
resources | array | |
total_amount | float | Amount with two decimals. e.g., 12.34. The amount is automatically calculated based on the items in the order. |
total_quantity | number | Total number of products in an order, e.g. 3 spoons and 2 forks = 5 products. |
units | number | Number of product 'types' in an order, e.g. 3 spoons and 2 forks = 2 product units. |
accounting_reference | string | An accounting reference ID. |
subscription | object | |
user | object | User associated with order (current user if order is created by a non-admin). |
note | string | A note of the order. |
coupons | object |
Total Amount Calculation
How we calculate the
total_amount
is a little complicated due to the flexibility of our products' (and sub products') prices and discounts. However, we keep it simple for you. Just usesum(items.final_price)
to calculate total_amount
.An
item
is a product and any sub_products that are included with that product. When you get the final_price
for that item,
this is the equation:(item.price + sum(sub_products.price)) * (1 - item.discount) * item.quantity
To show you an example of an order that includes a product and a product along with its sub product, consider the following:
Product A
id = productA
price = 40
discount = 0.10
currency = EUR
Product B
id = productB
price = 10
discount = 0
currency = EUR
Sub Product B1 (for Product B)
id = subProductB1
price = 5
discount = 0
currency = EUR
If we make an order for two Product As with a 10% discount and one Product B with Sub Product B1:
Create an Order
{
"items": [
{
"product": "productA",
"quantity": 2
},
{
"product": "productB",
"quantity": 1,
"sub_products": ["subProductB1"]
}
],
[...]
}
The
total_amount
will be: 87 EUR40 * (1 - 0.1) * 2 = 72
(10 + 5) * (1 - 0.0) * 1 = 15
72 + 15 = 87
Changes since API version
2019-02-01
Since we implemented a new Payment type,
Reserved Payment
, we introduced this new attribute. It is used to calculate the amount of a Reserved Payment
when it is in an Order
.The attribute
items
in the Order Object is where you put the products
your user wants to buy. These items are stored in an array. Each item has the below attributes. See Updating Items in an Order for more details on how this is used.All the followings attributes are not editable:
name
, price
, final_price
, discount
, vat
, currency
.
The goal of these attributes it's to take a snapshot the product
at the moment the order
is created.
Updating a product later will not affect the orders containing it.Attributes | Type | Description |
product | string | |
quantity | number | The quantity of the product. |
sub_products | array | An array of sub-product ID’s associated in the order. |
name | string | |
price | float | |
reserved_price | float | |
final_price | float | Calculated value: (price * (1 - discount)) * quantity |
discount | float | |
vat | float | |
currency | string |
Percentages are calculated on your behalf when creating an Order Item through the Dashboard.
The table below shows possible values for the attributes
date_filter
, order_status
, and delivery_status
used in the Order Object and various order methods.date_filter
order_status
delivery_status
Possible Values | Description |
created | Shows orders by date of creation |
delivery | Shows orders by delivery time |
Possible Values | Description |
CREATED | Order is created |
PROCESSING | Order is being processed |
DECLINED | Order is declined for some reason |
FAILED | Order has failed for some reason |
SUCCESS | Order has succeeded |
CANCELLED | Order is cancelled |
Possible Values | Description |
CREATED | Delivery is created |
PENDING | Delivery is pending |
PROCESSING | Delivery is being processed |
ASSIGNING | Delivery has been assigned to a provider |
PICKUP_STARTED | Pickup from customer has been sent |
PICKUP_ARRIVED | Pickup from customer is complete |
DROPOFF_STARTED | Dropoff to customer has been sent |
DROPOFF_ARRIVED | Dropoff to customer is complete |
CANCELLED | Delivery is cancelled |
DONE | Delivery task is done |
UNKNOWN | Delivery is unknown |
QUEUED | Delivery is in queue |
Parameters
Request
Response
Body Parameters | Type | Description |
delivery_address | object | Address used for delivery. |
items * | array | |
subscription * | object | |
billing_address | object | Address used for billing purposes. |
pickup_address | object | Address used to pickup a package. |
delivery_status | int | |
delivery_time | int | Expected arrival time for delivery, timestamp format. |
pickup_time | string | Expected arrival time for pickup, timestamp format. |
note | string | Note field. |
resources | array | |
coupon | string |
Either the
items
or the subscription
parameter should be included in the request.POST /orders HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"items": [
{
"product": "5703fce3308714000dea1ff1",
"quantity": 1
},
{
"product": "5703fcde308714000dea1fe8",
"quantity": 3
}
],
"delivery_time": 1472022000000,
"delivery_address": {
"city": "Oslo",
"geo": [
59.9294087,
10.7643042
],
"zip_code": "0557",
"street_name": "Christies gate 34A",
"country": "Norway"
},
"billing_address": {
"city": "Oslo",
"geo": [
59.9294087,
10.7643042
],
"zip_code": "0557",
"street_name": "Christies gate 34A",
"country": "Norway"
},
"note": "some type of note"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"created": {"$date": 1488475795244},
"company": {"$oid": "586faf7445ed910006373513"},
"delivery_address": {
"city": "Oslo",
"geo": [
59.9294087,
10.7643042
],
"zip_code": "0557",
"street_name": "Christies gate 34A",
"country": "Norway"
},
"billing_address": {
"city": "Oslo",
"geo": [
59.9294087,
10.7643042
],
"zip_code": "0557",
"street_name": "Christies gate 34A",
"country": "Norway"
},
"_id": {"$oid": "58b85693d76d439fdacea41b"},
"total_amount": 40.0,
"delivery_time": {"$date": 1472022000000},
"note": "some type of note",
"total_quantity": 4,
"order_status": "CREATED",
"items": [
{
"product": "5703fce3308714000dea1ff1",
"quantity": 1,
"name": "name of the product",
"price": 20,
"final_price": 10,
"discount": 0.5,
"vat": 0.0,
"currency": "NOK"
},
{
"product": "5703fcde308714000dea1fe8",
"quantity": 3,
"name": "name of the product",
"price": 10,
"final_price": 30,
"discount": 0.0,
"vat": 0.0,
"currency": "NOK"
}
],
"user": {"$oid": "57ee9c72d76d431f85111432"},
"units": 2,
"delivery_status": "PENDING",
"modified": {"$date": 1488475795244},
"currency": "NOK"
}
Parameters
Request
Response
Path Parameter | Type | Description |
order_id | string | ID of the queried order. |
Body Parameters | Type | Description |
resources | array |
PUT /orders/<order_id> HTTP/1.1
Content-Type: application/json
authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"note": "Delivery before 4PM"
}
HTTP/1.1 200 OK
Content-type: application/json
{
"user": {
"$oid": "5a2fd321ca79e20013ffc7bc"
},
"delivery_status": "PENDING",
"note": "Delivery before 4PM",
"created": {
"$date": 1552311677532
},
"_id": {
"$oid": "5c86657da4e8ad0009430245"
},
"total_quantity": 4,
"modified": {
"$date": 1553673658490
},
"order_status": "CREATED",
"top_up_vat": 0.25,
"delivery_address": {
"street_name": "Christies gate 34A",
"country": "Norway",
"zip_code": "0557",
"alias": "",
"service": "google",
"city": "Oslo",
"geo": [
59.9294087,
10.7643042
]
},
"total_amount": 40,
"billing_address": {
"street_name": "Christies gate 34A",
"country": "Norway",
"zip_code": "0557",
"alias": "",
"service": "google",
"city": "Oslo",
"geo": [
59.9294087,
10.7643042
]
},
"top_up_amount": 0,
"deleted": false,
"items": [
{
"product": {"$oid": "5703fce3308714000dea1ff1"},
"quantity": 1,
"name": "name of the product",
"price": 20,
"final_price": 10,
"discount": 0.5,
"vat": 0.0,
"currency": "NOK"
},
{
"product": "5703fcde308714000dea1fe8",
"quantity": 3,
"name": "name of the product",
"price": 10,
"final_price": 30,
"discount": 0.0,
"vat": 0.0,
"currency": "NOK"
}
],
"units": 2,
"company": {
"$oid": "59ce1e0a9d3bde0006fa45a9"
},
"resources": [],
"payments": [],
"override_company_take": -1,
"human_id": "2DX29Y",
"currency": "NOK",
"accounting_reference": "3533HW7"
}
Important: Updating the list of
items
overwrites the current list instead of adding additional items
to it.Parameters
Request
Response
Path Parameter | Type | Description |
order_id | string | ID of the queried order. |
GET /orders/<order_id> 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":1,
"delivery_status":"ACCEPTED",
"currency":"NOK",
"human_id":"51Q4LN",
"payments":[],
"modified":{"$date":1495196003948},
"top_up_amount":0.0,
"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":[],
"resources": [],
"items":[
{
"quantity":60,
"product": {"$oid": "5a2948b0d57ba22d228b1767"},
"name": "name of the product",
"price": 20,
"final_price": 120,
"discount": 0.0,
"vat": 0.0,
"currency": "NOK"
}
],
"note":"",
"created":{"$date":1495264401233},
"delivery_address":{
"city":"Danielsen",
"service":"google",
"alias":"",
"country":"Paraguay",
"zip_code":"0556",
"state":"Oslo",
"street_name":"Iversenstien 7"
},
"total_quantity":60,
"_id":{"$oid":"591ee163b70e2a10acb653a7"},
"total_amount":1200.0,
"override_company_take":-1.0,
"user":{...},
"delivery_time":{"$date":1497009600000}
}
Retrieves a list of all Orders associated with the current user (or all users if called from an Admin Role). It is also possible to filter the search using pagination.
Parameters
Request
Response
Query Parameters | Type | Description |
from_date | number | Start date, timestamp format. Default is None . |
to_date | number | End date, timestamp format. Default is None . |
date_filter | string | Date field used to filter results. Default is CREATED . |
size | number | Number of items to retrieve. Default is 10. |
page | number | Which page to retrieve. Default is 0. |
order_status | string | |
delivery_status | string | |
sort | string | Field used for sorting results. |
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":1,
"delivery_status":"ACCEPTED",
"currency":"NOK",
"human_id":"51Q4LN",
"payments":[],
"modified":{"$date":1495196003948},
"top_up_amount":0.0,
"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":[],
"resources": [],
"items":[
{
"quantity":60,
"product": {"$oid": "5a2948b0d57ba22d228b1767"},
"name": "name of the product",
"price": 20,
"final_price": 120,
"discount": 0.0,
"vat": 0.0,
"currency": "NOK"
}
],
"note":"",
"created":{"$date":1495264401233},
"delivery_address":{
"city":"Danielsen",
"service":"google",
"alias":"",
"country":"Paraguay",
"zip_code":"0556",
"state":"Oslo",
"street_name":"Iversenstien 7"
},
"total_quantity":60,
"_id":{"$oid":"591ee163b70e2a10acb653a7"},
"total_amount":1200.0,
"override_company_take":-1.0,
"user":{...},
"delivery_time":{"$date":1497009600000}
}
]
Retrieves a list of all Orders associated with the search parameters for the current user. It is possible to search for
_id
or human_id
associated with the current user's orders.Parameters
Request
Response
Query Parameters | Type | Description |
query | string | The search query. One of human_id, user name or id |
from_date | number | Start date, timestamp format. Default is None . |
to_date | number | End date, timestamp format. Default is None . |
date_filter | string | Date field used to filter results. Default is CREATED . |
size | number | Number of items to retrieve. Default is 10. |
page | number | Which page to retrieve. Default is 0. |
order_status | string | |
delivery_status | string | |
sort | string | Field used for sorting results. |
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":1,
"delivery_status":"ACCEPTED",
"currency":"NOK",
"human_id":"51Q4LN",
"payments":[],
"modified":{"$date":1495196003948},
"top_up_amount":0.0,
"order_status":"CREATED",
"company":{"$oid":"591ee15db70e2a10acb65362"},
"billing_address":{
"city":"Danielsen",
"service":"google",
"