Skip to main content

Caravans

The static caravan stock: owned inventory units with make, model, year, purchase details and dimensions. Caravans can be assigned to pitches and owners (assignment happens through the dashboard's pitch-owner flows) and removed from stock. Numbers from your stock list belong in metadata.stock_number.

The caravan object​

{
"id": "cR4v4nX",
"object": "caravan",
"make": "Willerby",
"model": "Herald",
"year": "2010",
"status": "available",
"purchase_price": "",
"length_m": "",
"width_m": "",
"max_sleeping_capacity": "",
"assigned_to": { "owner_id": null, "pitch_number": null },
"removed_date": null,
"notes": null,
"created": 1793061121,
"metadata": { "stock_number": "3" }
}

status: available | assigned | removed. year is a string (matching the dashboard's model).

Endpoints​

MethodPathDescription
GET/v1/caravansList (filter: status)
POST/v1/caravansCreate one
POST/v1/caravans/bulkPaste endpoint — ingest a whole stock list
GET/v1/caravans/{id}Retrieve
PATCH/v1/caravans/{id}Update details (never status)
DELETE/v1/caravans/{id}Remove from stock (soft)

Bulk ingest (the paste endpoint)​

Send an entire stock list in one request. Every field is optional per row — stock lists often have gaps — and per-row outcomes are reported so an agent can retry only the failures:

curl -s $API/v1/caravans/bulk -H "Authorization: Bearer $KEY" \
-H "Idempotency-Key: stock-import-1" -H "Content-Type: application/json" \
-d '{
"caravans": [
{"make": "Willerby", "model": "Herald", "year": 2010,
"metadata": {"stock_number": "3", "type": "Static"}},
{"make": "Atlas", "model": "Moonstone", "year": 2006,
"metadata": {"stock_number": "2", "type": "Static"}},
{"metadata": {"stock_number": "13", "type": "Static"}}
]
}'

Rows with unknown fields land in errors with their index. Status codes: 200 when at least one row committed (check errors for the rest), 400 when every row failed.

Updates and removal​

PATCH updates details and merges metadata; it never changes status directly — assignment flows own assigned, and DELETE marks the caravan removed with a removed_date. Removing an already-removed caravan returns validation_failed.

Assigning a caravan to an owner and pitch​

Static caravans are linked to customers (pitch owners) and pitches with one PATCH call. The relation mirrors the Pitch Owners dashboard page: assigning sets the caravan to status: "assigned" with assigned_to.owner_id (a pitchOwners document id) and assigned_to.pitch_number, and writes a caravanId back-link onto the owner document so both sides always agree:

curl -s $API/v1/caravans/car_abc123 -H "Authorization: Bearer $KEY" \
-X PATCH -H "Content-Type: application/json" \
-d '{"assigned_to": {"owner_id": "ownerDocId", "pitch_number": "S04"}}'

The response returns the caravan with status: "assigned" and the resolved assigned_to. The pitch number must match the owner's own pitch — a mismatch returns invalid_request_error naming the offending parameter. Assigning an owner who already holds another caravan frees that unit back to available, and reassigning a caravan clears the previous owner's back-link; the relation is one-to-one by construction.

Unassign (owner departs, caravan returns to the resale pool):

curl -s $API/v1/caravans/car_abc123 -H "Authorization: Bearer $KEY" \
-X PATCH -H "Content-Type: application/json" \
-d '{"assigned_to": null}'

The caravan returns to status: "available", both link fields are cleared and the owner's caravanId back-link is removed.

Removed caravans cannot be assigned — reinstate them first.