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.

Attributes

Type

Description

currency

string

3 letter ISO currency code as defined by ISO 4217.

billing_address

object

Address used for billing purposes.

deliveries

array

Used to store the delivery history for an order.

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.

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.

payment_method

object

See Payment Methods for more info on the payment method object.

resources

array

The resources in the order.

top_up_amount

number

Extra amount added to total_amount to fulfill the company’s minimum order value.

top_up_vat

float

The VAT percentage on the top_up_amount. Decimal value from 0 to 1, e.g. 0.25 = 25%.

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.

stripe_charge_id

string

The reference ID from a Stripe charge.

stripe_refund_id

string

The reference ID from a Stripe refund.

subscription

object

Associated subscription referenced by subscription_id.

user

object

User associated with order (current user if order is created by a non-admin).

Order Items

The attribute items in the Order Object is where you put the products or resources 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.

Attributes

Type

Description

product

string

A Productunique ID.

quantity

number

The quantity of the product.

discount

number

The discount of the product.price in the order. A decimal value between 0 and 1, e.g. 0.25 = 25%.

sub_products

array

An array of sub-product ID’s associated in the order.

Percentages are calculated on your behalf when creating an Order Item through the Dashboard. When using the Dashboard, the discount amount should be given as a number between 0 and 100, e.g. 25 = 25%.

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

User Role

Create an Order

Parameters
Request
Response

Body Parameters

Type

Description

delivery_address

object

Address used for delivery.

currency

string

3 letter ISO currency code as defined by ISO 4217.

payment_method

object

See Payment Methods for more info on the payment method object.

billing_address

object

Address used for billing purposes.

delivery_status

string

See delivery statuses. Default is PENDING.

delivery_time

object

Expected arrival time for delivery, timestampformat.

items

array

List of items associated with an order.

note

string

Field used to send notes between a user and a provider.

resources

array

The resources in the order.

subscription

object

Associated subscription referenced by subscription_id.

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,
"discount": 0.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"
},
"currency": "NOK",
"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,
"discount": 0.1
},
{
"product": "5703fcde308714000dea1fe8",
"quantity": 3
}
],
"user": {"$oid": "57ee9c72d76d431f85111432"},
"units": 2,
"delivery_status": "PENDING",
"modified": {"$date": 1488475795244},
"currency": "NOK"
}

Create a Recurring Order

You can make an order a 'recurring order' by including these additional body parameters (in addition to the required parameter for a standard order): is_recurring (set to true), interval_unit, and recurring_days.

This returns a JSON with order_status defined to CREATED. Basically, we create a Recurring Order Plan and a Recurring Order Subscription for the order. See Subscriptions and Plans for more info.

Parameters
Request
Response

Body Parameters

Type

Description

delivery_address

object

Address used for delivery.

is_recurring

boolean

Default is set to false for standard orders, however this needs to be set to true to create a recurring order.

interval_unit

string

The frequency that the subscription acts upon. Choices: DAY, WEEK, MONTH, MONTH_END.

recurring_days

array

Defines the schedule for the recurring order. See Recurring Day for more info.

currency

string

3 letter ISO currency code as defined by ISO 4217.

payment_method

object

See Payment Methodor more info on the payment method object.

billing_address

object

Address used for billing purposes.

delivery_status

string

See delivery statuses. Default is PENDING.

delivery_time

object

Expected arrival time for delivery, timestampformat.

items

array

List of items associated with an order.

resources

array

The resources in the order.

subscription

object

Associated subscription referenced by subscription_id.

POST /orders HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"is_recurring": true,
"interval_unit": "WEEK",
"recurring_days": [{"day": 3, "hour": 10, "minute": 30}],
"items": [
{
"product": "5703fce3308714000dea1ff1",
"quantity": 1,
"discount": 0.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"
},
"currency": "NOK",
"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,
"discount": 0.1
},
{
"product": "5703fcde308714000dea1fe8",
"quantity": 3
}
],
"user": {"$oid": "57ee9c72d76d431f85111432"},
"units": 2,
"delivery_status": "PENDING",
"modified": {"$date": 1488475795244},
"currency": "NOK"
}

Update an Order*

Parameters
Request
Response

Path Parameter

Type

Description

order_id

string

ID of the queried order.

Body Parameters

Type

Description

billing_address

object

Address used for billing purposes.

delivery_address

object

Address used for delivery.

payment_method

object

See Payment Methodsfor more info on the payment method object.

resources

array

An array of resources associated with the order.

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
},
"stripe_refund_id": "",
"_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": 166.8,
"billing_address": {
"street_name": "Christies gate 34A",
"country": "Norway",
"zip_code": "0557",
"alias": "",
"service": "google",
"city": "Oslo",
"geo": [
59.9294087,
10.7643042
]
},
"deliveries": [],
"top_up_amount": 0,
"deleted": false,
"items": [
{
"discount": 0.1,
"product": {
"$oid": "5703fce3308714000dea1ff1"
},
"sub_products": [],
"quantity": 1
},
{
"discount": 0,
"product": {
"$oid": "5703fcde308714000dea1fe8"
},
"sub_products": [],
"quantity": 3
}
],
"stripe_charge_id": "",
"units": 2,
"company": {
"$oid": "59ce1e0a9d3bde0006fa45a9"
},
"resources": [],
"payments": [],
"override_company_take": -1,
"human_id": "2DX29Y",
"currency": "NOK",
"accounting_reference": "3533HW7"
}

Update Items in an Order*

Parameters
Request
Response

Path Parameter

Type

Description

order_id

string

ID of the queried order.

Body Parameters

Type

Description

items

array

List of items associated with an order.

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,
"discount": 0.5
}
]
HTTP/1.1 200 OK
Content-type: application/json
{
"user": {
"$oid": "5a2fd321ca79e20013ffc7bc"
},
"delivery_status": "PENDING",
"note": "Delivery before 4PM",
"created": {
"$date": 1552311677532
},
"stripe_refund_id": "",
"_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
]
},
"deliveries": [],
"top_up_amount": 0,
"deleted": false,
"items": [
{
"discount": 0.5,
"product": {
"$oid": "5a2948b0d57ba22d228b1767"
},
"sub_products": [],
"quantity": 2
}
],
"stripe_charge_id": "",
"units": 1,
"company": {
"$oid": "59ce1e0a9d3bde0006fa45a9"
},
"resources": [],
"payments": [],
"override_company_take": -1,
"human_id": "2DX29Y",
"currency": "NOK",
"accounting_reference": "3533HW7"
}

Important: Updating this list of items overwrites the current list instead of adding additional items to it.

Retrieve an Order*

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":2,
"delivery_status":"ACCEPTED",
"currency":"NOK",
"human_id":"51Q4LN",
"payments":[],
"modified":{"$date":1495196003948},
"provider":{...},
"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":[],
"resources": [],
"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}
}

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

Return orders with a specific order status.

delivery_status

string

Return orders with a specific delivery status.

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":2,
"delivery_status":"ACCEPTED",
"currency":"NOK",
"human_id":"51Q4LN",
"payments":[],
"modified":{"$date":1495196003948},
"provider":{...},
"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 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
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

Return orders with a specific order status.

delivery_status

string

Return orders with a specific delivery status.

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":2,
"delivery_status":"ACCEPTED",
"currency":"NOK",
"human_id":"51Q4LN",
"payments":[],
"modified":{"$date":1495196003948},
"provider":{...},
"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}
}
]

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.

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 both user and currency are required fields.

Parameters
Request
Response

Body Parameters

Type

Description

user

string

ID of the User associated with the order.

delivery_address

object

Address used for delivery.

currency

string

3 letter ISO currency code as defined by ISO 4217

payment_method

object

See Payment Methodor more info on the payment method object.

billing_address

object

Address used for billing purposes

delivery_status

string

See delivery statuses. Default is PENDING

delivery_time

object

Expected arrival time for delivery, timestampformat.

items

string

List of Items associated with an order.

note

string

Field used to send notes between a user and a provider

resources

array

The Resources in the order.

subscription

object

Associated Subscription referenced by a Subscription ID

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,
"discount": 0.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"
},
"currency": "NOK",
"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,
"discount": 0.1
},
{
"product": "5703fcde308714000dea1fe8",
"quantity": 3
}
],
"user": {"$oid": "57ee9c72d76d431f85111432"},
"units": 2,
"delivery_status": "PENDING",
"modified": {"$date": 1488475795244},
"currency": "NOK"
}