Skip to content
Bottle

List orders

GET
/orders
curl --request GET \
  --url 'https://example.com/orders?status=draft&excludeCancelled=true&excludeRefunded=true&customerId=019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f&unassigned=true&deliveryStage=waiting&fulfilment=delivery&shopId=019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f&paid=yes&late=true&sort=placed&order=asc&limit=50&offset=0' \
  --cookie __Host-bottle.session_token=<__Host-bottle.session_token>

Filter by order status, current delivery stage, customer, whether an order is still unassigned, or the day it is wanted.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
q

Customer name, order reference, invoice number or product name.

string
<= 80 characters

Customer name, order reference, invoice number or product name.

status
string
Allowed values: draft placed delivered cancelled
excludeCancelled

Exclude cancelled orders before counting and pagination.

string
Allowed values: true false

Exclude cancelled orders before counting and pagination.

excludeRefunded

Exclude orders with a full or partial shop refund or a recorded Bottle refund.

string
Allowed values: true false

Exclude orders with a full or partial shop refund or a recorded Bottle refund.

customerId

UUID v7

string format: uuid

Example 

019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f

UUID v7

ids

Only these orders: up to 200 order ids, separated by commas. Ids from another business are ignored.

string

Only these orders: up to 200 order ids, separated by commas. Ids from another business are ignored.

invoiceIds

Only the orders on these invoices: up to 200 invoice ids, separated by commas. Covers both an invoice raised for one order and a weekly, monthly or quarterly invoice that billed several.

string

Only the orders on these invoices: up to 200 invoice ids, separated by commas. Covers both an invoice raised for one order and a weekly, monthly or quarterly invoice that billed several.

wantedOn

The day they are wanted.

string format: date

The day they are wanted.

unassigned

Only orders that are not currently on a round.

string
Allowed values: true false

Only orders that are not currently on a round.

deliveryStage

Only open deliveries waiting to be planned, assigned to a planned round, or currently out.

string
Allowed values: waiting planned out

Only open deliveries waiting to be planned, assigned to a planned round, or currently out.

createdFrom

Placed on or after this day.

string format: date

Placed on or after this day.

createdTo

Placed on or before this day.

string format: date

Placed on or before this day.

fulfilment

Delivery: goes on a round. collection: the customer picks it up from the yard; never planned onto a van, and comes off stock when marked collected.

string
Allowed values: delivery collection

Delivery: goes on a round. collection: the customer picks it up from the yard; never planned onto a van, and comes off stock when marked collected.

shopId

Only orders that came from this connected shop.

string format: uuid

Example 

019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f

Only orders that came from this connected shop.

paid

Whether they have been paid for. ‘no’ is orders that still owe money: not on account, not cancelled, not marked paid.

string
Allowed values: yes no

Whether they have been paid for. ‘no’ is orders that still owe money: not on account, not cancelled, not marked paid.

late

Only placed orders wanted on a day already gone.

string
Allowed values: true false

Only placed orders wanted on a day already gone.

deliveredOn

Only orders delivered or collected on this day.

string format: date

Only orders delivered or collected on this day.

sort

What to put the list in order by: placed (when it was taken, the default), wanted (the day wanted) or customer (the customer name).

string
Allowed values: placed wanted customer

What to put the list in order by: placed (when it was taken, the default), wanted (the day wanted) or customer (the customer name).

order

Which way. Placed is newest first unless asc; wanted is soonest first and customer A to Z unless desc.

string
Allowed values: asc desc

Which way. Placed is newest first unless asc; wanted is soonest first and customer A to Z unless desc.

limit
integer
default: 50 >= 1 <= 200
offset
integer | null
0

Responses

Section titled “Responses”

200

Section titled “200”

Orders

Media typeapplication/json
object
items
required
Array<object>
object
id
required

UUID v7

string format: uuid
customerId
required

UUID v7

string | null format: uuid
customerName
required
string | null
pricingAudience

Consumer: use consumer list prices. trade: use trade prices where set. Agreed rates, customer price lists and price rules still take priority.

string | null
Allowed values: consumer trade
deliveryAddressId
required

UUID v7

string | null format: uuid
deliverToName
required
string | null
deliverToAddress
required
string | null
deliverToEmail
string | null
deliverToPhone
string | null
location
required
object
latitude
required
number
>= -90 <= 90
longitude
required
number
>= -180 <= 180
placement
string
Allowed values: drop door street postcode none
roundId
required

UUID v7

string | null format: uuid
round
object
id
required

UUID v7

string format: uuid
date
required
string format: date
status
required
string
Allowed values: planned out done
driverName
required
string | null
vehicleName
required
string | null
deliveredBy
object
roundId
required

UUID v7

string format: uuid
date
required
string format: date
driverName
required
string | null
vehicleName
required
string | null
failedDrop

The drop that failed, while the order is open, for delivery and not back on a round. Only the full order fills it: not the items of GET /orders.

object
reason
required
string
Allowed values: nobody_in no_access refused customer_cancelled wrong_day wrong_address nothing_to_leave price_problem payment_problem other
note
required
string | null
failedAt
required
string format: date-time
roundId
required

UUID v7

string format: uuid
date
required
string format: date
driverName
required
string | null
vehicleName
required
string | null
status
required
string
Allowed values: draft placed delivered cancelled
fulfilment
required

Delivery: goes on a round. collection: the customer picks it up from the yard; never planned onto a van, and comes off stock when marked collected.

string
Allowed values: delivery collection
source
required
string
shopId

UUID v7

string | null format: uuid
shopName
string | null
externalRef
required
string | null
customerReference
required
string | null
<= 100 characters
billingOwner

Bottle: Bottle owns invoicing and payment. shop: the connected shop owns both, so Bottle must only fulfil the order. elsewhere: the business invoiced or took payment outside Bottle, so Bottle only fulfils the order.

string
default: bottle
Allowed values: bottle shop elsewhere
shopSnapshot
object
payment
required
string
refundedPence
required
integer
fees
required
Array<object>
object
name
required
string
netPence
required
integer
vatPence
required
integer
grossPence
required
integer
items
required
Array<object>
object
name
required
string
quantity
required
integer
> 0
netPence
required
integer
vatPence
required
integer
grossPence
required
integer
trackingRef
required
string
leaveInstruction
required
string | null
Allowed values: none neighbour safe_place
leaveDetail
required
string | null
deliveryOptionId
required

UUID v7

string | null format: uuid
deliveryOptionName
required
string | null
expectedFrom
required
string | null format: date
expectedTo
required
string | null format: date
deliveryChargePence
required
integer
deliveryChargeIncludesVat
required
boolean
surchargeName
required
string | null
surchargeUnitPence
required
integer
surchargeQuantity
required
integer
surchargeAppliesTo
required
string
Allowed values: all_orders all_cylinders gas_types products
surchargeChargeBy
required
string
Allowed values: per_order per_item
surchargeTargetIds
required
Array<string>
surchargePence
required
integer
surchargeIncludesVat
required
boolean
paymentMethod
required

On_account: billed later, nothing to collect. link: a payment link raised in the accounting system. cash: the driver takes it at the door.

string
Allowed values: on_account link cash
cylinderCharge
string
Allowed values: deposit rent both
wantedOn
required
string | null format: date
notes
required
string | null
lines
required
Array<object>
object
id
required

UUID v7

string format: uuid
productId
required

UUID v7

string format: uuid
productName
required
string
quantity
required
integer
> 0
unitPrice
required

Pence, as agreed when the order was written, and as typed.

integer
priceIncludesVat
required
boolean
total
required
integer
netPence
required
integer
vatPence
required
integer
grossPence
required
integer
deliveredQuantity
required
integer
cancelledQuantity
required
integer
faultySwap
boolean
collect
required
Array<object>
object
productId
required

UUID v7

string format: uuid
productName
required
string
quantity
required
integer
> 0
returned
Array<object>
object
productId
required

UUID v7

string format: uuid
productName
required
string
quantity
required
integer
> 0
total
required
integer
netPence
required
integer
vatPence
required
integer
grossPence
required
integer
refundDue
required
integer
refundSettledAt
required
string | null format: date-time
refundLines
Array<object>
object
quantity
required
integer
refundPence
required
integer
explanation
required
string
credited
required
boolean
availableDepositRefund
object
totalPence
required
integer
> 0
lines
required
Array<object>
object
depositProductId
required

UUID v7

string format: uuid
cylinderProductId
required

UUID v7

string | null format: uuid
depositName
required
string
quantity
required
integer
> 0
refundPence
required
integer
> 0
explanation
required
string
depositRefundNeedsBalanceConfirmation
boolean
depositRefundNotDue
boolean
paidAt
required
string | null format: date-time
receivedPence
integer
balanceDuePence
integer
payments
Array<object>
object
id
required
string
amountPence
required
integer
> 0
method
required
string
Allowed values: cash transfer card other online
receivedAt
required
string format: date-time
reference
required
string | null
canVoid
required
boolean
voidedAt
required
string | null format: date-time
cashLocation
string | null
Allowed values: office driver
cashDriverUserId
string | null
cashDriverName
string | null
paidVia
required
string | null
Allowed values: online stripe office shop cash transfer card other
paymentProvider
required
string | null
paymentLink
required
string | null format: uri
invoice
required
object
id
required

UUID v7

string format: uuid
number
required
string
status
required
string
Allowed values: sent paid void
canEmailPaymentLink
required
boolean
paymentRequestedAt
required
string | null format: date-time
deliveredAt
required
string | null format: date-time
deliveryMethod

Own_driver: the business’s own driver delivered it. delivery_partner: another company delivered it for the business.

string | null
Allowed values: own_driver delivery_partner
partnerDelivery
object
id
required

UUID v7

string format: uuid
partnerId
required

UUID v7

string format: uuid
partnerName
required
string
deliveryDate
required
string format: date
setAt
required
string format: date-time
sentAt
required
string | null format: date-time
sentVia
required
string | null
Allowed values: email csv
sentBy
string | null
edited
Array<string>
Allowed values: products address notes contact
downloadedAt
string | null format: date-time
downloadedBy
string | null
deliveryCorrections
Array<object>
object
id
required

UUID v7

string format: uuid
kind
required
string
Allowed values: delivered empties
lineId
required

UUID v7

string | null format: uuid
productName
required
string
fromQuantity
required
integer
toQuantity
required
integer
reason
required
string
byName
required
string | null
at
required
string format: date-time
deliveryProofs
Array<object>
object
kind
required
string
Allowed values: signature left_safe
signedBy
required
string | null
note
required
string | null
imageUrl
required
string | null
driverName
required
string | null
vehicleName
required
string | null
createdAt
required
string format: date-time
deliveryNotes
Array<object>
object
id
required

UUID v7

string format: uuid
orderId
required

UUID v7

string format: uuid
note
required
string
driverName
required
string | null
createdAt
required
string format: date-time
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
total
required
integer

Example 

{
  "items": [
    {
      "id": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f",
      "customerId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f",
      "pricingAudience": "consumer",
      "deliveryAddressId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f",
      "placement": "drop",
      "roundId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f",
      "round": {
        "id": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f",
        "status": "planned"
      },
      "deliveredBy": {
        "roundId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f"
      },
      "failedDrop": {
        "reason": "nobody_in",
        "roundId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f"
      },
      "status": "draft",
      "fulfilment": "delivery",
      "source": "office",
      "shopId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f",
      "billingOwner": "bottle",
      "trackingRef": "7K3M9QWXZ2",
      "leaveInstruction": "none",
      "deliveryOptionId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f",
      "surchargeAppliesTo": "all_orders",
      "surchargeChargeBy": "per_order",
      "surchargeTargetIds": [
        "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f"
      ],
      "paymentMethod": "on_account",
      "cylinderCharge": "deposit",
      "lines": [
        {
          "id": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f",
          "productId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f",
          "productName": "19kg propane"
        }
      ],
      "collect": [
        {
          "productId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f",
          "productName": "19kg propane"
        }
      ],
      "returned": [
        {
          "productId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f",
          "productName": "19kg propane"
        }
      ],
      "availableDepositRefund": {
        "lines": [
          {
            "depositProductId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f",
            "cylinderProductId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f"
          }
        ]
      },
      "payments": [
        {
          "method": "cash",
          "cashLocation": "office"
        }
      ],
      "paidVia": "online",
      "invoice": {
        "id": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f",
        "number": "INV-BTL00042",
        "status": "sent"
      },
      "deliveryMethod": "own_driver",
      "partnerDelivery": {
        "id": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f",
        "partnerId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f",
        "sentVia": "email",
        "edited": [
          "products"
        ]
      },
      "deliveryCorrections": [
        {
          "id": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f",
          "kind": "delivered",
          "lineId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f"
        }
      ],
      "deliveryProofs": [
        {
          "kind": "signature"
        }
      ],
      "deliveryNotes": [
        {
          "id": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f",
          "orderId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f"
        }
      ]
    }
  ]
}

401

Section titled “401”

Not signed in

Media typeapplication/json
object
error
required
string
message
required
string

Example 

{
  "error": "not_found",
  "message": "Customer not found"
}

403

Section titled “403”

Not a member, or without the permission this needs

Media typeapplication/json
object
error
required
string
message
required
string

Example 

{
  "error": "not_found",
  "message": "Customer not found"
}

422

Section titled “422”

Validation failed, or a line names something not sold

Media typeapplication/json
object
error
required
string
Allowed values: validation
message
required
string
issues
required
Array<object>
object
path
required
string
message
required
string

Example 

{
  "error": "validation",
  "issues": [
    {
      "path": "email",
      "message": "Invalid email"
    }
  ]
}