Add an unplanned stop

POST

/rounds/{id}/sales

const url = 'https://example.com/rounds/019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f/sales';
const options = {
  method: 'POST',
  headers: {
    cookie: '__Host-bottle.session_token=<__Host-bottle.session_token>',
    'Content-Type': 'application/json'
  },
  body: '{"customerId":"019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f","surchargeChoice":"usual","deliverToName":"example","deliverToAddress":"example","deliveryAddressId":"019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f","newDeliveryAddress":{"name":"example","line1":"example","line2":"example","city":"example","postcode":"example","notes":"example","leaveInstruction":"none","leaveDetail":"example","dropLatitude":1,"dropLongitude":1,"placeToken":"example"},"fulfilment":"delivery","pricingAudience":"consumer","paymentMethod":"cash","lines":[{"productId":"019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f","quantity":1}],"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/rounds/019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f/sales \
  --header 'Content-Type: application/json' \
  --cookie __Host-bottle.session_token=<__Host-bottle.session_token> \
  --data '{ "customerId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "surchargeChoice": "usual", "deliverToName": "example", "deliverToAddress": "example", "deliveryAddressId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "newDeliveryAddress": { "name": "example", "line1": "example", "line2": "example", "city": "example", "postcode": "example", "notes": "example", "leaveInstruction": "none", "leaveDetail": "example", "dropLatitude": 1, "dropLongitude": 1, "placeToken": "example" }, "fulfilment": "delivery", "pricingAudience": "consumer", "paymentMethod": "cash", "lines": [ { "productId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "quantity": 1 } ], "collect": [ { "productId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "quantity": 1 } ] }'

Somebody flags the van down, a door wants more, or asks the driver to take cylinders away. Becomes an order and a stop on the end of this round. A collection-only stop has no sale or payment. Paying by link raises the invoice and makes the link straight away where the business can take card payments. Only on a round that is out. A driver may only do this on their own round.

Authorizations

sessionCookie
deliveries:write
apiKey
deliveries:write

Parameters

Path Parameters

required

UUID v7

string format: uuid

Example

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

UUID v7

Request Body^required

application/json

object

customerId

UUID v7

string format: uuid

Example

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

surchargeChoice

string

Allowed values: usual add remove

deliverToName

string

<= 200 characters

deliverToAddress

string

<= 2000 characters

deliveryAddressId

UUID v7

string format: uuid

Example

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

newDeliveryAddress

object

name

string | null

<= 80 characters

line1

required

string

>= 1 characters <= 200 characters

line2

string | null

<= 200 characters

city

string | null

<= 120 characters

postcode

string | null

<= 12 characters

notes

string | null

<= 2000 characters

leaveInstruction

string | null

Allowed values: none neighbour safe_place

leaveDetail

string | null

<= 500 characters

dropLatitude

number | null

>= -90 <= 90

dropLongitude

number | null

>= -180 <= 180

placeToken

string

<= 2000 characters

fulfilment

string

Allowed values: delivery collection

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

paymentMethod

required

string

Allowed values: cash link on_account

lines

Array<object>

<= 50 items

object

productId

required

UUID v7

string format: uuid

Example

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

quantity

required

integer

> 0 <= 1000

collect

Array<object>

<= 50 items

object

productId

required

UUID v7

string format: uuid

Example

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

quantity

required

integer

> 0 <= 1000

Responses

201

The round with the new stop on the end

application/json

object

required

UUID v7

string format: uuid

roundDate

required

string format: date

vehicleId

required

UUID v7

string | null format: uuid

vehicleName

required

string | null

driverUserId

required

string | null

driverName

required

string | null

startLocationId

required

UUID v7

string | null format: uuid

endLocationId

required

UUID v7

string | null format: uuid

yardId

required

UUID v7

string | null format: uuid

status

required

string

Allowed values: planned out done

issuedAt

required

string | null format: date-time

sentOverLimit

required

object

byKg

required

integer | null

> 0

byLitres

required

integer | null

> 0

sentBy

required

string | null

note

required

string | null

sentOverLimitReason

required

Use sentOverLimit.note.

string | null

salesRoom

object

stops

required

integer

seconds

required

integer

lines

required

Array<object>

object

productId

required

string

quantity

required

integer

> 0

cylinders

required

integer

usualCylinders

required

integer

required

number

litres

required

number

heldOrders

required

integer

stillThere

required

boolean

loadConfirmedAt

required

string | null format: date-time

van

required

object

latitude

required

number

>= -90 <= 90

longitude

required

number

>= -180 <= 180

seenAt

required

string format: date-time

distanceMetres

required

integer | null

durationSeconds

required

integer | null

departsAt

required

string | null

/^([01]\d|2[0-3]):[0-5]\d$/

fit

required

object

loadKg

required

number | null

payloadKg

required

integer | null

loadLitres

required

integer | null

volumeLitres

required

integer | null

unweighedItems

required

integer

totalSeconds

required

integer | null

departsAt

required

string | null

/^([01]\d|2[0-3]):[0-5]\d$/

backAt

required

string | null

/^([01]\d|2[0-3]):[0-5]\d$/

shiftEnd

required

string | null

/^([01]\d|2[0-3]):[0-5]\d$/

over

required

Array<string>

Allowed values: weight volume hours doorsShut

geometry

required

string | null

routedBy

required

string | null

notes

required

string | null

deliveryWindowHours

required

Any of:

number

Allowed values: 1

stops

required

Array<object>

object

accountAccess

object

unpaidInvoices

required

boolean

newOrdersBlocked

required

boolean

deliveriesBlocked

required

boolean

required

UUID v7

string format: uuid

orderId

required

UUID v7

string format: uuid

transferId

UUID v7

string | null format: uuid

transferLeg

string | null

Allowed values: collection drop

loadLocationId

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.

string | null format: uuid

collectFrom

object

usualYardId

required

UUID v7

string format: uuid

usualYardName

required

string

locationId

required

UUID v7

string | null format: uuid

address

required

object

name

required

string | null

line1

required

string

city

required

string | null

postcode

required

string

sequence

required

integer

> 0

addedAt

string format: date-time

addedOnRoad

boolean

latitude

required

number | null

longitude

required

number | null

placement

string

Allowed values: drop door street postcode none

pin

object

latitude

required

number

longitude

required

number

etaSeconds

required

integer | null

etaAt

required

string | null

/^([01]\d|2[0-3]):[0-5]\d$/

serviceSeconds

required

integer | null

waitSeconds

required

integer | null

outsideHours

required

boolean

proof

required

object

kind

required

string

Allowed values: signature left_safe

signedBy

required

string | null

note

required

string | null

url

required

string

createdAt

required

string format: date-time

lines

required

Array<object>

object

orderLineId

required

UUID v7

string format: uuid

productId

required

UUID v7

string format: uuid

productName

required

string

quantity

required

integer

> 0

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

fulfilment

required

string

Allowed values: delivery collection

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

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

Allowed values: bottle shop elsewhere

amountDuePence

required

integer

cashTakenPence

required

integer

paidAt

required

string | null format: date-time

leaveInstruction

required

string | null

Allowed values: none neighbour safe_place

leaveDetail

required

string | null

shortfallReason

required

string | null

Allowed values: not_on_vehicle damaged refused other

issue

required

string | null

Allowed values: wrong_product access complaint other

issueNote

required

string | null

completedAt

required

string | null format: date-time

failedAt

required

string | null format: date-time

failureReason

required

string | null

Allowed values: nobody_in no_access refused customer_cancelled wrong_day wrong_address nothing_to_leave price_problem payment_problem other

failureNote

required

string | null

customerName

required

string | null

customerPhone

string | null

customerContactName

string | null

customerContacts

Array<object>

object

required

UUID v7

string format: uuid

name

required

string

email

required

string format: email

phone

required

string | null

/^\+?[\d\s()-]{7,20}$/

kind

required

string

Allowed values: normal billing both

relationship

required

string | null

<= 60 characters

customerReference

string | null

driverNotes

string | null

customerNotes

The same as driverNotes, for apps before 1.2.8. Never the customer record’s notes.

string | null

deliverTo

required

Name, address and postcode in one line.

string | null

summary

required

string

orderStatus

required

string

Allowed values: placed delivered cancelled

onVan

Array<object>

object

stopId

required

UUID v7

string format: uuid

yardId

required

UUID v7

string format: uuid

yardName

required

string

lines

required

Array<object>

object

productId

required

UUID v7

string format: uuid

productName

required

string

quantity

required

integer

onVanAt

required

string format: date-time

version

required

string

createdAt

required

string format: date-time

updatedAt

required

string format: date-time

Example

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

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

The round has not left yet

application/json

object

error

required

string

message

required

string

Example

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

422

Validation failed

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

Add an unplanned stop

Authorizations

Parameters

Path Parameters

Example

Request Bodyrequired

Example

Example

Example

Example

Responses

201

Example

401

Example

403

Example

404

Example

409

Example

422

Example

Request Body^required