PrimeCal Reservations Create v2

primecal_reservations_create_v2 creates a reservation with UTC timestamps, logical timezone metadata, and MCP-friendly structured error payloads.

Request Parameters

Field	Type	Required	Notes
startTime	string	Yes	ISO 8601 timestamp.
endTime	string	Yes	ISO 8601 timestamp.
resourceTypeId	number	No	Optional when the selected resources imply one resource type.
resourceId	number	No	Single concrete resource.
resourceIds	number[]	No	Multiple concrete resources of the same resource type.
quantity	number	No	Defaults to 1.
notes	string	No	Optional reservation notes.
customerInfo	object	No	Optional structured customer info.
userTimezone	string	No	Optional IANA timezone override for local input interpretation.

Success Response

{
  "id": 501,
  "startTime": "2032-04-20T10:00:00.000Z",
  "endTime": "2032-04-20T11:00:00.000Z",
  "timezone": "Europe/Budapest",
  "quantity": 1,
  "resourceCount": 1,
  "status": "confirmed",
  "paymentStatus": "not_required",
  "paymentRequired": false,
  "quotedAmount": 0,
  "quotedCurrency": null,
  "resourceTypeId": 13,
  "resourceTypeName": "Consultation Room",
  "resourceId": 40,
  "resourceName": "Room A",
  "resourceIds": [40]
}

Conflict Error Contract

PrimeCal returns 409 Conflict with a structured MCP error body:

{
  "errorCode": "RESERVATION_CONFLICT",
  "message": "The requested slot is no longer available.",
  "conflictingReservationId": "91",
  "nextAvailableSlot": {
    "startTime": "2032-04-20T11:00:00.000Z",
    "endTime": "2032-04-20T12:00:00.000Z",
    "timezone": "Europe/Budapest"
  }
}

Payment Error Contract

PrimeCal returns 402 Payment Required when the resource type requires a payment flow that MCP create cannot complete directly:

{
  "errorCode": "PAYMENT_REQUIRED",
  "message": "Payment is required to complete this reservation.",
  "paymentRequiredAmount": 4200,
  "currency": "USD"
}

Notes

• PrimeCal never exposes raw gateway responses or payment tokens in MCP errors.
• nextAvailableSlot is advisory and already normalized to UTC timestamps plus logical timezone.
• userTimezone affects input interpretation only. Success and error timestamps remain UTC.

Screenshot Placeholder

TODO: add Chrome MCP screenshots for a successful booking flow and a conflict error state under docs/assets/agents/.