Create an order

POST

/orders

const url = 'https://example.com/orders';
const options = {
  method: 'POST',
  headers: {
    cookie: '__Host-bottle.session_token=<__Host-bottle.session_token>',
    'Content-Type': 'application/json'
  },
  body: '{"status":"placed","customerId":"019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f","deliveryAddressId":"019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f","deliverToName":"example","deliverToAddress":"example","deliveryOptionId":"019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f","paymentMethod":"on_account","billingOwner":"bottle","fulfilment":"delivery","pricesIncludeVat":true,"pricingAudience":"consumer","includeSurcharge":true,"surchargeChoice":"usual","wantedOn":"2026-04-15","notes":"example","customerReference":"example","lines":[{"productId":"019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f","quantity":1,"unitPrice":1,"priceIncludesVat":true,"faultySwap":true}],"cylinderChargesReviewed":true,"collect":[{"productId":"019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f","quantity":1}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/orders \
  --header 'Content-Type: application/json' \
  --cookie __Host-bottle.session_token=<__Host-bottle.session_token> \
  --data '{ "status": "placed", "customerId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "deliveryAddressId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "deliverToName": "example", "deliverToAddress": "example", "deliveryOptionId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "paymentMethod": "on_account", "billingOwner": "bottle", "fulfilment": "delivery", "pricesIncludeVat": true, "pricingAudience": "consumer", "includeSurcharge": true, "surchargeChoice": "usual", "wantedOn": "2026-04-15", "notes": "example", "customerReference": "example", "lines": [ { "productId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "quantity": 1, "unitPrice": 1, "priceIncludesVat": true, "faultySwap": true } ], "cylinderChargesReviewed": true, "collect": [ { "productId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "quantity": 1 } ] }'

Against a saved customer, or a one-off with a name and address. Each line may name its own price; otherwise the rate agreed with that customer applies, and the list price where none has been.

Authorizations

sessionCookie
orders:write
apiKey
orders:write

Request Body^required

application/json

object

status

string

Allowed values: placed draft

customerId

UUID v7

string format: uuid

Example

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

deliveryAddressId

UUID v7

string format: uuid

Example

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

deliverToName

string | null

<= 200 characters

deliverToAddress

string | null

<= 2000 characters

deliveryOptionId

UUID v7

string format: uuid

Example

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

paymentMethod

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

billingOwner

Bottle: Bottle invoices and takes payment as usual. elsewhere: already invoiced or paid outside Bottle. Bottle sends no invoice or payment link, drivers collect nothing, and the payment method is kept as on_account.

string

Allowed values: bottle elsewhere

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

pricesIncludeVat

boolean

pricingAudience

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

string

Allowed values: consumer trade

includeSurcharge

boolean

surchargeChoice

string

Allowed values: usual add remove

wantedOn

string | null format: date

notes

string | null

<= 2000 characters

customerReference

string | null

<= 100 characters

lines

required

Array<object>

<= 200 items

object

productId

required

UUID v7

string format: uuid

Example

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

quantity

required

integer

> 0 <= 1000

unitPrice

integer

priceIncludesVat

boolean

faultySwap

boolean

cylinderChargesReviewed

boolean

collect

Array<object>

<= 200 items

object

productId

required

UUID v7

string format: uuid

Example

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

quantity

required

integer

> 0 <= 1000

Responses

201

Taken

application/json

object

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

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

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

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

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

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

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

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

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

Example

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

Not signed in

application/json

object

error

required

string

message

required

string

Example

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

403

Not a member, or without the permission this needs

application/json

object

error

required

string

message

required

string

Example

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

422

Validation failed, or a line names something not sold

application/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"
    }
  ]
}

Create an order

Authorizations

Request Bodyrequired

Example

Example

Example

Example

Example

Responses

201

Example

401

Example

403

Example

422

Example

Request Body^required