The caller's day, for the driver apps
const url = 'https://example.com/driver/day?date=2026-04-15&scope=day';const options = { method: 'GET', headers: {cookie: '__Host-bottle.session_token=<__Host-bottle.session_token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://example.com/driver/day?date=2026-04-15&scope=day' \ --cookie __Host-bottle.session_token=<__Host-bottle.session_token>Everything a driver needs for a day, in one answer, for the driver apps to keep on the phone and work from without signal: the rounds sent to the caller on that date with every stop, the bases they start and end at, the gas products that can be handed over, collected or sold, what is on each round’s van, and the caller’s cash in the cab. Give the date as the phone sees it, in the driver’s own time zone. Only rounds the office has sent appear. Use scope=assigned for every unfinished assigned round, regardless of its start date, plus rounds starting or completed on the requested date.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Responses
Section titled “Responses”The day
object
object
UUID v7
UUID v7
UUID v7
UUID v7
UUID v7
object
Use sentOverLimit.note.
object
object
object
object
object
object
UUID v7
UUID v7
UUID v7
Set on a stop that collects the round’s own stock from one of your yards: cylinders kept there rather than where the van loads. It has no order and no transfer; orderId carries the stop’s own id.
object
UUID v7
UUID v7
object
object
object
object
UUID v7
UUID v7
object
UUID v7
On_account: billed later, nothing to collect. link: a payment link raised in the accounting system. cash: the driver takes it at the door.
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.
object
UUID v7
The same as driverNotes, for apps before 1.2.8. Never the customer record’s notes.
Name, address and postcode in one line.
object
UUID v7
UUID v7
object
UUID v7
object
UUID v7
object
UUID v7
Pence, exactly as entered. Whether VAT is in this figure is what priceIncludesVat says; the other reading is given beside it for display.
Whether unitPrice includes VAT. False: VAT goes on top when the product is sold. True: unitPrice is the shelf price, and the VAT is worked back out of it on each line.
UnitPrice without VAT, in pence, for display. The same as unitPrice when it excludes VAT or the business is not registered; otherwise derived and rounded. Do not multiply it: amounts are worked out from unitPrice.
UnitPrice with VAT, in pence, for display. The same as unitPrice when it includes VAT or the business is not registered; otherwise derived and rounded.
VAT in basis points: 2000 is 20%, 500 is 5%, 0 is zero rated.
UUID v7
Who pays a deposit or rent where no price list or agreed amount says otherwise. both: Consumer and Trade customers (the default). consumer: everybody who is not a trade customer, signed in or not. trade: trade customers only. Meaningless on anything that is not a charge.
UUID v7
This product’s own UN number, proper shipping name and hazard class, where they differ from its gas type’s. Null follows the gas type.
object
The UN number, four digits without “UN”.
The proper shipping name from the ADR list, as on the cylinder label.
The ADR hazard class: 2.1 flammable gas, 2.2 non-flammable non-toxic gas, 2.2 (5.1) non-flammable gas that is also oxidising, 2.3 toxic gas.
What the product is. The one set on it, or when none has been, read from it: a charge makes it a deposit or hire, a gas type a cylinder, anything else other.
Whether kind was set rather than read from the product.
The description as plain text, with a blank line between paragraphs and a line per list item. Made from descriptionHtml, for search, previews and anywhere HTML cannot go.
The description with its formatting, as sanitised HTML: only p, h2, h3, strong, em, ul, ol, li, br and a. A link has only an http, https or mailto href, rel=“noopener noreferrer nofollow”, and target=“_blank” for a web address. Sanitised again on every read; still treat it as HTML from a third party.
Products picked to show under this one on the shop, in order, up to 8. Empty: the shop shows others from the same category.
On the business’s own shop. Shown there only once the shop is switched on. Never true on an archived product.
Who may buy it on the shop once published. both: everybody (the default). consumer: anybody not signed in for a trade account, so trade customers do not see it. trade: signed-in trade customers only.
On a deposit: what comes back when a cylinder is returned. Null follows the business’s own setting (invoice settings).
object
Which hire a returned cylinder is measured from. Null is latest.
What a trade customer pays, on the shop and on office orders, when no rate has been agreed with them, pence as typed. Null: the list price. A customer’s agreed rate still comes first, and price rules for trade work off this.
What one costs the business, pence without VAT. Optional; read by cost-plus price rules. Never shown to customers.
How many are on the shelf, for things sold on the shop that are not cylinders. Null is not counted: always available. Set and moved with POST /products/{id}/stock, never here. May be below nought when the product keeps selling once none are left.
At or under this count the office is told, and the shop may say low stock. Null is never.
Whether the yard’s cylinder stock keeps a figure for this product. False: the stock list marks it as not counted, rounds plan as though there are always enough, and nothing warns that it is low or has no figure. Only read on a cylinder.
How this product’s stock is recorded. quantity: as a count. individual: each cylinder by its own serial number, once Assets is open and switched on for the business. Only read on a cylinder.
How many months a fill lasts, for a tracked cylinder. Used to suggest the expiry date when stock comes in. Null: no suggestion.
The yard this cylinder is kept at, when it is not wherever a round loads. A round loading at another yard gets a stop at this one to collect what its orders need, before the doors that need it. Null for a cylinder every yard keeps. Only read on a cylinder.
What the shop does when none are left, for this product. Null follows the shop’s own rule (Settings, Shop). stop: off sale. continue: keeps selling, shown as ships when back in stock.
object
UUID v7
What the picture shows, for screen readers and search.
Of the original, in pixels.
Fits inside 200 pixels. WebP.
Fits inside 600 pixels. WebP.
Fits inside 1600 pixels. WebP.
object
The product details it has, in the order the details are listed (GET /product-details). Archived details are left out; their values are kept.
object
UUID v7
object
UUID v7
What the driver shows the police or DVSA for this product: its own UN number, proper shipping name and hazard class, else its gas type’s. Null when neither is set.
object
The UN number, four digits without “UN”.
The proper shipping name from the ADR list, as on the cylinder label.
The ADR hazard class: 2.1 flammable gas, 2.2 non-flammable non-toxic gas, 2.2 (5.1) non-flammable gas that is also oxidising, 2.3 toxic gas.
Whether these come from the product itself or its gas type.
object
object
object
UUID v7
object
object
UUID v7
UUID v7
object
UUID v7
UUID v7
object
Main_contact: the customer’s main contact. everyone: every contact on the account. ask_driver: the driver picks at the stop.
Tracked: stops where a tracked cylinder is delivered or collected. every: every stop.
object
object
UUID v7
Install: a cylinder is delivered and none is collected. refill: a cylinder is delivered and one is collected. return: a cylinder is collected and none is delivered. service: the driver services equipment. manual: only chosen by hand.
object
UUID v7
object
object
UUID v7
object
UUID v7
UUID v7
UUID v7
UUID v7
UUID v7
Example
{ "rounds": [ { "id": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "vehicleId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "startLocationId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "endLocationId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "yardId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "status": "planned", "departsAt": "07:30", "fit": { "departsAt": "07:30", "backAt": "07:30", "shiftEnd": "07:30", "over": [ "weight" ] }, "deliveryWindowHours": 1, "stops": [ { "id": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "orderId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "transferId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "transferLeg": "collection", "loadLocationId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "collectFrom": { "usualYardId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "locationId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f" }, "placement": "drop", "etaAt": "07:30", "proof": { "kind": "signature" }, "lines": [ { "orderLineId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "productId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "productName": "19kg propane" } ], "collect": [ { "productId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "productName": "19kg propane" } ], "fulfilment": "delivery", "paymentMethod": "on_account", "billingOwner": "bottle", "leaveInstruction": "none", "shortfallReason": "not_on_vehicle", "issue": "wrong_product", "failureReason": "nobody_in", "customerContacts": [ { "id": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "phone": "07700 900123", "kind": "normal", "relationship": "Accounts" } ], "summary": "3 × 19kg propane", "orderStatus": "placed" } ], "onVan": [ { "stopId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "yardId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "lines": [ { "productId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f" } ] } ] } ], "locations": [ { "id": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "kind": "depot", "name": "Yard", "postcode": "KT3 4BP", "postcodeDistrict": "KT3", "adminDistrict": "Kingston upon Thames", "adminCounty": "Surrey", "region": "London" } ], "products": [ { "id": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "name": "19kg propane", "shortCode": "19", "sku": "PROP-19", "unitPrice": 5400, "unitPriceExVat": 5400, "unitPriceIncVat": 6480, "vatRate": 2000, "charge": "deposit", "chargePeriod": "once", "chargeForProductId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "chargeForProductIds": [ "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f" ], "chargeAudience": "both", "gasTypeId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "dangerousGoods": { "unNumber": "1978", "shippingName": "PROPANE", "hazardClass": "2.1" }, "weightKg": 38.5, "volumeLitres": 60, "kind": "cylinder", "brand": "Flogas", "descriptionHtml": "<p>A <strong>13kg</strong> propane refill.</p><ul><li>Same day delivery</li></ul>", "relatedProductIds": [ "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f" ], "shopAudience": "both", "refundRule": "full", "refundCountsFrom": "latest", "stockOnHand": 12, "stockLowAt": 3, "tracking": "quantity", "homeLocationId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "whenOut": "stop", "images": [ { "id": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f" } ], "categoryIds": [ "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f" ], "links": [ { "source": "woocommerce", "externalId": "1043" } ], "details": [ { "detailId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "value": [ "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f" ] } ], "categories": [ { "id": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f" } ], "carriedAs": { "unNumber": "1978", "shippingName": "PROPANE", "hazardClass": "2.1", "from": "product" } } ], "loads": { "additionalProperty": { "items": [ { "productId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f" } ] } }, "cylinders": { "onVan": [ { "roundId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "productId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f" } ], "atStops": [ { "stopId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "productId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f" } ] }, "workReport": { "emailTo": "main_contact", "sendAfter": "tracked", "jobTypes": [ { "id": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "name": "Refill", "rule": "install" } ], "checks": [ { "id": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "name": "Gauge" } ] }, "cash": { "waiting": [ { "id": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "startedBy": "driver", "status": "waiting" } ], "takings": [ { "id": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "roundId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "orderId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "invoiceId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "handoverId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f" } ] }}Not signed in
object
Example
{ "error": "not_found", "message": "Customer not found"}Not a member, or without the permission this needs
object
Example
{ "error": "not_found", "message": "Customer not found"}Validation failed
object
object
Example
{ "error": "validation", "issues": [ { "path": "email", "message": "Invalid email" } ]}