Documentation
Booking
booking.deposit_policy
REST
ShippingPOST /api/v1/booking/deposit_policyMCP tool
Livebooking.deposit_policyExposed on: REST API · Booking MCP server. Part of the Booking domain.
This capability answers to an older id too
booking.deposit_due still resolves here, on every surface, so an integration written against it keeps working. New code should use booking.deposit_policy.Operating contract
THE CALL TO MAKE BEFORE READING A PRICE BACK TO A CUSTOMER. It prices a whole visit for one vehicle size and says exactly what has to be paid to hold it.
bookable is the answer that matters. False means this shop has not priced one of these services for that vehicle size, and booking.book will refuse it — say the shop will confirm the price and offer to take their details instead of inventing a number.
deposit_due is what the customer pays now; total is the whole job. A deposit is a percentage of the total with a dollar floor, so on a small job the floor is what applies.
live_card_payment false means the shop follows up with a payment link rather than taking a card during the booking — the appointment is still made, so do not tell the customer it failed.
Prices are in the shop's currency (shop.profile), before tax.
Who may call it
- Permission
- NoneThe storefront's own pricing answer, computed from the public menu and the shop's published deposit policy. It moves no money and reads no customer record.
- Plan
- Every planNo plan gate. Available on every Service VIN plan.
- Retries
naturalNaturally idempotent — running it twice leaves the same world as running it once. A retrying integration needs no key.- Rate class
readCounted against the read budget — the widest of the four.
Input
| Field | Type | Description |
|---|---|---|
| service_idsrequired | string[] | The services to book, as `id` values from booking.services. One id books one service; several book one visit covering all of them, and the slot is sized for the whole visit. |
| vehicle_typerequired | string | The customer's vehicle size, one of `vehicle_types` from booking.services. One of:car, truck, suv, van, coupe, motorcycle, commercial, exotic |
Output
| Field | Type | Description |
|---|---|---|
| currency | string | — |
| bookable | boolean | — |
| total | number | null | — |
| deposit_due | number | — |
| deposit_required | boolean | — |
| deposit_percent | number | — |
| deposit_flat | number | — |
| live_card_payment | boolean | — |
| lines | object[] | — |
| lines[].service_id | string | — |
| lines[].name | string | — |
| lines[].price | number | null | — |
| lines[].duration_minutes | number | null | — |
| lines[].priced | boolean | — |
Examples
Built from this capability's own schema — required fields and the ones carrying a default, and nothing invented. Paste one and it validates.
export SERVICEVIN_API_KEY=svk_live_…
curl -X POST https://www.servicevin.com/api/v1/booking/deposit_policy \
-H "Authorization: Bearer $SERVICEVIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"service_ids":["…"],"vehicle_type":"car"}'const res = await fetch("https://www.servicevin.com/api/v1/booking/deposit_policy", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SERVICEVIN_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"service_ids": [
"…"
],
"vehicle_type": "car"
}),
});
// Success and failure are both envelopes. Switch on error.code, never
// on error.message — the codes are stable, the messages are for people.
const payload = await res.json();
if (!res.ok) throw new Error(payload.error.code);
const data = payload.data;import os, requests
res = requests.post(
"https://www.servicevin.com/api/v1/booking/deposit_policy",
headers={"Authorization": f"Bearer {os.environ['SERVICEVIN_API_KEY']}"},
json={
"service_ids": [
"…"
],
"vehicle_type": "car"
},
timeout=30,
)
payload = res.json()
if not res.ok:
raise RuntimeError(payload["error"]["code"])
data = payload["data"]{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "booking.deposit_policy",
"arguments": {
"service_ids": [
"…"
],
"vehicle_type": "car"
}
}
}Refusals
The four gates run in this order on every surface, and the order is not arbitrary — see Authentication.
| Status | Code | When |
|---|---|---|
| 404 | not_found | The id is unknown, or the feature is not enabled for this account. Deliberately the same answer for both. |
| 422 | validation_error | An argument was wrong. The message names the field. |
| 429 | rate_limited | Too many read calls. Back off and retry. |
| 500 | internal_error | Something failed on our side. Nothing was changed. |