Correct how many of each item were delivered, and the empties collected

POST

/orders/{id}/delivery-correction

const url = 'https://example.com/orders/019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f/delivery-correction';
const options = {
  method: 'POST',
  headers: {
    cookie: '__Host-bottle.session_token=<__Host-bottle.session_token>',
    'Content-Type': 'application/json'
  },
  body: '{"expectedUpdatedAt":"2026-04-15T12:00:00Z","reason":"example","lines":[],"empties":[{"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/019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f/delivery-correction \
  --header 'Content-Type: application/json' \
  --cookie __Host-bottle.session_token=<__Host-bottle.session_token> \
  --data '{ "expectedUpdatedAt": "2026-04-15T12:00:00Z", "reason": "example", "lines": [], "empties": [ { "productId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "quantity": 1 } ] }'

For a delivery recorded wrongly at the door. Sets how many of each named line were handed over, from nought up to what was ordered less anything refused or removed. The stock moves back onto the vehicle, or off it, as a correction with the reason, so stock and the customer’s cylinder balance follow. A delivered order with anything taken back is open again with the rest to deliver, and its own unpaid invoice is cancelled so the usual one is raised once the rest is delivered or removed. Money already taken stays against the order. Send empties to correct the empty cylinders collected, as the new total for each product. Leave it out to keep the recorded empties. Name at least one line or one product of empties. Changing empties is refused once a deposit refund or a refund due is on the order. If more empties came back than cylinders went out, the deposit refund due is recorded. Every change is kept with who made it and why. On an order a shop or another system bills, only the empties can be corrected, and no deposit refund is recorded. Owners and admins only: drivers cannot correct a delivery.

Authorizations

sessionCookie
orders:write
apiKey
orders:write

Parameters

Path Parameters

required

UUID v7

string format: uuid

Example

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

UUID v7

Request Body^required

application/json

object

expectedUpdatedAt

required

The order’s updatedAt as last read. The correction is refused if the order has changed since.

string format: date-time

reason

required

Why the recorded delivery was wrong. Kept with the correction.

string

>= 1 characters <= 500 characters

lines

Array<object>

default: <= 200 items

object

lineId

required

The order line to correct.

string format: uuid

Example

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

deliveredQuantity

required

How many of this line were handed over: the new total, not a change.

integer

<= 10000

empties

Array<object>

<= 200 items

object

productId

required

The cylinder product collected.

string format: uuid

Example

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

quantity

required

How many empties of it were collected: the new total, not a change.

integer

<= 10000

Responses

200

Corrected order

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

404

Not found

application/json

object

error

required

string

message

required

string

Example

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

409

Order changed, nothing delivered yet, or billed on a period invoice

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

Correct how many of each item were delivered, and the empties collected

Authorizations

Parameters

Path Parameters

Example

Request Bodyrequired

Example

Example

Responses

200

Example

401

Example

403

Example

404

Example

409

Example

422

Example

Request Body^required