Orders

Order Object

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	The currency will be define by the Item(s). 3 letter ISO currency code as defined by ISO 4217.
pickup_address	object	Address used to pickup a pac
delivery_address	object	Address used for delivery.
delivery_status	string	See delivery statuses. Default is PENDING.
delivery_time	object	Expected arrival time for delivery, timestampformat.
pickup_time	object	Expected arrival time for pickup, timestampformat.
order_status	string	See order statuses. Default is CREATED.
items	array	List of items in an order.
human_id	string	Human readable ID that identifies the order easily, e.g. 3AG7UA.
payments	array	List of Payment objects associated with the order.
resources	array	The resources in the order.
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	Associated subscription referenced by subscription_id.
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	See Coupon for more info on the payment method 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 EUR

Product A's final price:

40 * (1 - 0.1) * 2 = 72

Product B's (with sub product B1) final price:

(10 + 5) * (1 - 0.0) * 1 = 15

Order Total Amount:

72 + 15 = 87

Order Items

Changes since API version 2019-02-01

2020-03-13 - New attribute `reserved_price`

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.

We are deprecating the old image_urland replacing it with Image Object

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	A Productunique ID.
quantity	number	The quantity of the product.
sub_products	array	An array of sub-product ID’s associated in the order.
name	string	The Product's name
price	float	The Product's price
reserved_price	float	The Product's reserved price
final_price	float	Calculated value: (price * (1 - discount)) * quantity
discount	float	The Product's discount. A decimal value between 0 and 1, e.g. 0.25 = 25%.
vat	float	The Product's vat. A decimal value between 0 and 1, e.g. 0.25 = 25%.
currency	string	The Product's currency

Percentages are calculated on your behalf when creating an Order Item through the Dashboard.

Order Arguments and Statuses

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

Possible Values	Description
created	Shows orders by date of creation
delivery	Shows orders by delivery time

order_status

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

delivery_status

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

User Role

Create an Order

Parameters

Body Parameters	Type	Description
delivery_address	object	Address used for delivery.
items*	array	List of items associated with an order.
subscription*	object	Associated subscription referenced by subscription_id.
billing_address	object	Address used for billing purposes.
pickup_address	object	Address used to pickup a package.
delivery_status	int	See delivery statuses. Default is PENDING.
delivery_time	int	Expected arrival time for delivery, timestampformat.
pickup_time	string	Expected arrival time for pickup, timestampformat.
note	string	Note field.
resources	array	The resources in the order.
coupon	string	A Coupon ID or code

Either theitemsor the subscriptionparameter should be included in the request.

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

Response

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

Update an Order*

Parameters

Path Parameter	Type	Description
order_id	string	ID of the queried order.

Body Parameters	Type	Description
resources	array	An array of resources associated with the order.

Request

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

Response

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.

Retrieve an Order*

Parameters

Path Parameter	Type	Description
order_id	string	ID of the queried order.

Request

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

Response

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

List all Orders*

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

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	Return orders with a specific order status.
delivery_status	string	Return orders with a specific delivery status.
sort	string	Field used for sorting results.

Request

GET /orders 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

[
    {
      "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}
   }
]

Search Orders*

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

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	Return orders with a specific order status.
delivery_status	string	Return orders with a specific delivery status.
sort	string	Field used for sorting results.

Request

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

Response

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

Cancel an Order*

Orders that haven't been completed or delivered can be cancelled.

Parameters

Path Parameter	Type	Description
order_id	string	ID of the queried order.

Request

POST /orders/<order_id>/cancel 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

{
   "units":1,
   "delivery_status":"ACCEPTED",
   "currency":"NOK",
   "human_id":"51Q4LN",
   "payments":[],
   "modified":{"$date":1495196003948},
   "top_up_amount":0.0,
   "order_status":"CANCELED",
   "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}
}

Admin Role

*Paths listed above and denoted with a star are accessible to both Users and Admins. Additional Admin Role paths are listed below.

Create an Order

In order to create a new Standard Order or Recurring Order as an Admin you must specify the User. This means that user is required field.

Parameters

Body Parameters	Type	Description
user	string	ID of the User associated with the order.
delivery_address	object	Address used for delivery.
billing_address	object	Address used for billing purposes
pickup_address	object	Addressused to pickup a package.
delivery_status	string	See delivery statuses. Default is PENDING
delivery_time	int	Expected arrival time for delivery, timestampformat.
pickup_time	int	Expected arrival time for pickup, timestampformat.
items	string	List of Items associated with an order.
note	string	Note field.
resources	array	The Resources in the order.
subscription	string	Associated Subscription referenced by a Subscription ID
coupon	string	A Coupon ID or code

Request

POST /orders HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev

{
  "user": "57ee9c72d76d431f85111432",
  "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"
}

Response

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

Update Items in an Order*

Parameters

Path Parameter	Type	Description
order_id	string	ID of the queried order.

Body Parameters	Type	Description
user	string	ID of the User associated with the order.
items	array	List of items associated with an order.

Request

PUT /orders/<order_id>/items HTTP/1.1
Content-Type: application/json
authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev

[
    {
        "product": "5a2948b0d57ba22d228b1767",
        "quantity": 2
    }
]

Response

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": 2,
    "modified": {
        "$date": 1553674870324
    },
    "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": 2100,
    "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": "5a2948b0d57ba22d228b1767"},
            "sub_products": [],
            "quantity": 2,
            "name": "name of the product",
            "price": 2100,
            "final_price": 2100,
            "discount": 0.5,
            "vat": 0.0,
            "currency": "NOK"
        }
    ],
    "units": 1,
    "company": {
        "$oid": "59ce1e0a9d3bde0006fa45a9"
    },
    "resources": [],
    "payments": [],
    "override_company_take": -1,
    "human_id": "2DX29Y",
    "currency": "NOK",
    "accounting_reference": "3533HW7"
}