Skip to content
Bottle

Move stock between yards

POST
/stock/transfers
curl --request POST \
  --url https://example.com/stock/transfers \
  --header 'Content-Type: application/json' \
  --cookie bottle.session_token=<bottle.session_token> \
  --data '{ "fromLocationId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "toLocationId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "method": "recorded", "lines": [ { "productId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "condition": "full", "quantity": 1 } ], "plannedFor": "2026-04-15", "roundId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f", "happenedAt": "2026-04-15T12:00:00Z", "carrierName": "example", "carrierReference": "example", "note": "example" }'

Two ways. recorded is a transfer that has already happened: received in one step at happenedAt, which may be in the past but not the future, with both ends in the ledger at that time. carrier is one a courier or the supplier is taking: it starts as planned and is moved on with the advance call. round is carried on one of the business’s own vans: give the roundId, which must still be planned, and the van calls at both yards as ordinary stops, or collects with its morning load when it leaves from the yard the stock is in. Both ends must be yards of this business, not somebody’s home.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
fromLocationId
required

UUID v7

string format: uuid
Example
019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f
toLocationId
required

UUID v7

string format: uuid
Example
019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f
method
required
string
Allowed values: recorded carrier round
lines
required
Array<object>
>= 1 items <= 200 items
object
productId
required

UUID v7

string format: uuid
Example
019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f
condition
required
string
Allowed values: full empty
quantity
required
integer
> 0 <= 100000
plannedFor
string format: date
roundId

UUID v7

string format: uuid
Example
019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f
happenedAt
string format: date-time
carrierName
string | null
<= 120 characters
carrierReference
string | null
<= 120 characters
note
string | null
<= 500 characters

Responses

Section titled “Responses”

201

Section titled “201”

The transfer, with its lines and every stage it has been through

Media typeapplication/json
object
id
required

UUID v7

string format: uuid
fromLocationId
required

UUID v7

string format: uuid
fromName
required
string
toLocationId
required

UUID v7

string format: uuid
toName
required
string
method
required
string
Allowed values: recorded carrier round
status
required
string
Allowed values: planned awaiting_collection in_transit received cancelled
roundId
required

UUID v7

string | null format: uuid
plannedFor
string | null format: date
proofs
Array<object>
object
leg
required
string
Allowed values: collection drop
kind
required
string
Allowed values: signature left_safe
signedBy
required
string | null
url
required
string
createdAt
required
string format: date-time
round
object
id
required

UUID v7

string format: uuid
roundDate
required
string format: date
vehicleName
required
string | null
driverName
required
string | null
carrierName
required
string | null
carrierReference
required
string | null
note
required
string | null
lines
required
Array<object>
object
productId
required

UUID v7

string format: uuid
productName
required
string
condition
required
string
Allowed values: full empty
quantity
required
integer
> 0
history
required
Array<object>
object
status
required
string
Allowed values: planned awaiting_collection in_transit received cancelled
at
required
string format: date-time
byName
required
string | null
createdByName
required
string | null
createdAt
required
string format: date-time
Example
{
  "id": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f",
  "fromLocationId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f",
  "toLocationId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f",
  "method": "recorded",
  "status": "planned",
  "roundId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f",
  "proofs": [
    {
      "leg": "collection",
      "kind": "signature"
    }
  ],
  "round": {
    "id": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f"
  },
  "lines": [
    {
      "productId": "019205d1-6e7a-7c3b-9f6e-3a2b1c0d9e8f",
      "condition": "full"
    }
  ],
  "history": [
    {
      "status": "planned"
    }
  ]
}

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

404

Section titled “404”

A product, yard or transfer that is not this business’s

Media typeapplication/json
object
error
required
string
message
required
string
Example
{
  "error": "not_found",
  "message": "Customer not found"
}

409

Section titled “409”

The transfer is not at a stage that allows this

Media typeapplication/json
object
error
required
string
message
required
string
Example
{
  "error": "not_found",
  "message": "Customer not found"
}

422

Section titled “422”

Validation failed

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