Skip to main content
Documentation

Booking

booking.deposit_policy

Check the price and the deposit a booking would require
Read-onlyRead budget

REST

Shipping
POST /api/v1/booking/deposit_policy

MCP tool

Live
booking.deposit_policy

Exposed 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

FieldTypeDescription
service_idsrequiredstring[]

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_typerequiredstring

The customer's vehicle size, one of `vehicle_types` from booking.services.

One of: car, truck, suv, van, coupe, motorcycle, commercial, exotic

Output

FieldTypeDescription
currencystring

bookableboolean

totalnumber | null

deposit_duenumber

deposit_requiredboolean

deposit_percentnumber

deposit_flatnumber

live_card_paymentboolean

linesobject[]

lines[].service_idstring

lines[].namestring

lines[].pricenumber | null

lines[].duration_minutesnumber | null

lines[].pricedboolean

Examples

Built from this capability's own schema — required fields and the ones carrying a default, and nothing invented. Paste one and it validates.

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

TypeScript (fetch)
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;

Python (requests)
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"]

MCP tools/call — https://www.servicevin.com/api/mcp
{
  "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.

StatusCodeWhen
404not_foundThe id is unknown, or the feature is not enabled for this account. Deliberately the same answer for both.
422validation_errorAn argument was wrong. The message names the field.
429rate_limitedToo many read calls. Back off and retry.
500internal_errorSomething failed on our side. Nothing was changed.