Authentication
x-hallify-widget-context: <HALLIFY_STOREFRONT_WIDGET_CONTEXT>Short-lived server-authenticated widget presentation proof. It binds the configured frame origin to the exact verified parent binding and connection authority. Widget new demand requires this proof; existing native capabilities remain separate and retain their original authority and deadlines.
Parameters
publicHandlePath · RequiredOpaque public channel handle used to resolve one venue’s published guest-facing configuration; it is not a credential.
stringFull definition
{ "type": "string", "example": "example" }intentIdPath · RequiredHallify UUID whose ownership is validated against every parent tenant and aggregate in this route before the selected resource is exposed or changed.
string · uuidFull definition
{ "type": "string", "format": "uuid", "example": "9b6163a8-afea-4877-818b-8e2ae28a2845" }idempotency-keyHeader · RequiredRequired idempotency key, up to 128 characters
stringFull definition
{ "type": "string", "minLength": 1, "maxLength": 128, "example": "example" }originHeader · OptionalActual browser request Origin used for current presentation authorization. New demand and Storefront-bound continuations require it. Canonical Hallify browser requests use the origin configured by HALLIFY_PUBLIC_APP_URL. This header provides request context and does not authenticate a caller or replace the applicable guest credential.
string · uriFull definition
{ "type": "string", "format": "uri", "maxLength": 2048, "example": "https://example.test/resource" }x-hallify-connection-idHeader · OptionalOptional nonsecret connection locator for initial public channel resolution. It never grants authority or replaces an issued grant snapshot.
string · uuidFull definition
{ "type": "string", "format": "uuid", "minLength": 36, "maxLength": 36, "example": "9b6163a8-afea-4877-818b-8e2ae28a2845" }
Request body
Required
Validates the contact code and atomically converts the unexpired intent into its reservation or waitlist record, consuming any capacity hold.
application/json
VerifyPublicIntentDto
Full definition
{
"$ref": "#/components/schemas/VerifyPublicIntentDto"
}Responses
200Returns the original committed reservation or waitlist receipt and manage capability, separately from the current authorized management context.
ReservationPublicVerifyIntentResultDto
Full definition
{
"$ref": "#/components/schemas/ReservationPublicVerifyIntentResultDto"
}Example response · 200 · application/json
{
"kind": "RESERVATION",
"entityId": "6b288694-8b6d-49cd-8007-264ca7224921",
"referenceCode": "EXAMPLE",
"revision": 1,
"status": "REQUESTED",
"eventIds": [
"6825b43e-93d6-4f3b-8171-c1661099fae8"
],
"manageToken": "synthetic-example-credential",
"manageTokenExpiresAt": "2026-12-31T18:00:00.000Z",
"currentState": "AVAILABLE",
"current": {
"venue": {
"id": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0",
"name": "Example name",
"timeZone": "Asia/Tbilisi"
},
"publicChannel": {
"id": "3db2ed63-9466-4829-81aa-e4959a2279b0",
"publicHandle": "example",
"status": "DRAFT"
},
"servicePeriod": {
"id": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8",
"name": "Example name",
"bookingMode": "INSTANT"
},
"source": {
"kind": "RESERVATION",
"entityId": "6b288694-8b6d-49cd-8007-264ca7224921",
"venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
"publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
"presentation": {
"kind": "CANONICAL",
"connectionId": null,
"resourceId": null,
"origin": null
}
},
"grantExpiresAt": "2026-12-31T18:00:00.000Z",
"serverTime": "2026-01-15T12:00:00.000Z",
"pendingAgreement": null,
"guarantee": null,
"kind": "RESERVATION",
"id": "a42073ae-5313-4ace-86d8-86fb33fde1a9",
"referenceCode": "EXAMPLE",
"revision": 1,
"status": "REQUESTED",
"partySize": 1,
"scheduledAt": "2026-01-15T12:00:00.000Z",
"endsAt": "2026-12-31T18:00:00.000Z",
"allowedActions": [
"CONFIRM"
]
}
}402Commercial coverage is required for new demand, or this operation has no original commercial admission evidence. Existing authorized reads and financial recovery remain available.
TranslatedErrorDto
Full definition
{
"$ref": "#/components/schemas/TranslatedErrorDto"
}Example response · 402 · application/json
{
"statusCode": 402,
"error": "errors:http.failure",
"code": "HTTP_402",
"message": "errors:http.failure",
"translationKey": "errors:http.failure"
}409Idempotency key is already in progress or was reused with a different payload
IdempotencyConflictError
Full definition
{
"$ref": "#/components/schemas/IdempotencyConflictError"
}Example response · 409 · application/json
{
"statusCode": 409,
"error": "errors:http.conflict",
"code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
"message": "errors:idempotency.inProgress",
"translationKey": "errors:idempotency.inProgress"
}503Authoritative commercial state is unavailable or cannot be read within its bounded source contract. Retry the same operation after recovery.
TranslatedErrorDto
Full definition
{
"$ref": "#/components/schemas/TranslatedErrorDto"
}Example response · 503 · application/json
{
"statusCode": 503,
"error": "errors:http.serviceUnavailable",
"code": "HTTP_SERVICE_UNAVAILABLE",
"message": "errors:http.serviceUnavailable",
"translationKey": "errors:http.serviceUnavailable"
}Schemas
VerifyPublicIntentDto
Validates the contact code and atomically converts the unexpired intent into its reservation or waitlist record, consuming any capacity hold.
codeRequiredStable code used to classify or address verify public intent.
stringFull definition
{ "type": "string", "pattern": "^\\d{6}$", "description": "Stable code used to classify or address verify public intent.", "example": "000001" }
Full definition
{
"type": "object",
"properties": {
"code": {
"type": "string",
"pattern": "^\\d{6}$",
"description": "Stable code used to classify or address verify public intent.",
"example": "000001"
}
},
"required": [
"code"
],
"description": "Validates the contact code and atomically converts the unexpired intent into its reservation or waitlist record, consuming any capacity hold.",
"example": {
"code": "000001"
}
}ReservationPublicVerifyIntentResultDto
Verified booking or waitlist result and its guest management capability.
Full definition
{
"description": "Verified booking or waitlist result and its guest management capability.",
"oneOf": [
{
"type": "object",
"description": "Verified reservation intent result.",
"required": [
"kind",
"entityId",
"referenceCode",
"revision",
"status",
"eventIds",
"manageToken",
"manageTokenExpiresAt",
"currentState",
"current"
],
"properties": {
"kind": {
"type": "string",
"description": "Kind of the created guest-managed entity.",
"enum": [
"RESERVATION"
],
"example": "RESERVATION"
},
"entityId": {
"type": "string",
"description": "Created reservation or waitlist entry identifier.",
"format": "uuid",
"example": "6b288694-8b6d-49cd-8007-264ca7224921"
},
"referenceCode": {
"type": "string",
"description": "Guest-facing reference code.",
"example": "EXAMPLE"
},
"revision": {
"type": "integer",
"description": "Current entity revision.",
"example": 1
},
"status": {
"type": "string",
"description": "Resulting booking or waitlist status.",
"enum": [
"REQUESTED",
"BOOKED",
"CONFIRMED",
"ARRIVED",
"SEATED",
"CANCELED",
"NO_SHOW",
"DECLINED",
"EXPIRED"
],
"example": "REQUESTED"
},
"eventIds": {
"type": "array",
"description": "Events emitted by this command.",
"items": {
"type": "string",
"description": "Reservation activity event identifier.",
"format": "uuid",
"example": "6825b43e-93d6-4f3b-8171-c1661099fae8"
},
"example": [
"6825b43e-93d6-4f3b-8171-c1661099fae8"
]
},
"manageToken": {
"type": "string",
"description": "Sensitive guest capability for subsequent management requests. Use the documented guest authorization header; never log it.",
"example": "synthetic-example-credential"
},
"manageTokenExpiresAt": {
"type": "string",
"description": "Expiry of the guest management capability.",
"format": "date-time",
"example": "2026-12-31T18:00:00.000Z"
},
"currentState": {
"type": "string",
"enum": [
"AVAILABLE",
"UNAVAILABLE"
],
"description": "Whether separate current management enrichment is available. This never changes the original committed receipt or issues another grant.",
"example": "AVAILABLE"
},
"current": {
"description": "Separate current authorized management view, or null when the original grant is no longer usable or current enrichment is unavailable. Historical receipt fields and the original token remain unchanged.",
"oneOf": [
{
"description": "Current guest-safe management view under the exact native READ grant and current presentation authority. It is separate from an immutable original command receipt.",
"oneOf": [
{
"type": "object",
"description": "Current reservation context and capability-scoped native lifecycle actions.",
"additionalProperties": false,
"required": [
"kind",
"id",
"referenceCode",
"revision",
"status",
"partySize",
"scheduledAt",
"endsAt",
"venue",
"publicChannel",
"servicePeriod",
"source",
"grantExpiresAt",
"serverTime",
"allowedActions",
"guarantee",
"pendingAgreement"
],
"properties": {
"venue": {
"type": "object",
"description": "Current native venue display and scheduling context.",
"additionalProperties": false,
"required": [
"id",
"name",
"timeZone"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Owning venue UUID.",
"example": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0"
},
"name": {
"type": "string",
"description": "Current public venue name.",
"example": "Example name"
},
"timeZone": {
"type": "string",
"description": "Native venue IANA time zone.",
"example": "Asia/Tbilisi"
}
},
"example": {
"id": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0",
"name": "Example name",
"timeZone": "Asia/Tbilisi"
}
},
"publicChannel": {
"type": "object",
"description": "The owner record's native public channel, independent of the storefront presentation handle. Its current status does not replace continuation authorization.",
"additionalProperties": false,
"required": [
"id",
"publicHandle",
"status"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Native channel UUID.",
"example": "3db2ed63-9466-4829-81aa-e4959a2279b0"
},
"publicHandle": {
"type": "string",
"description": "Native reservation channel handle.",
"example": "example"
},
"status": {
"type": "string",
"description": "Current native public-channel lifecycle.",
"enum": [
"DRAFT",
"ACTIVE",
"PAUSED"
],
"example": "DRAFT"
}
},
"example": {
"id": "3db2ed63-9466-4829-81aa-e4959a2279b0",
"publicHandle": "example",
"status": "DRAFT"
}
},
"servicePeriod": {
"type": "object",
"description": "Current native service-period identity and booking mode.",
"additionalProperties": false,
"required": [
"id",
"name",
"bookingMode"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Native service-period UUID.",
"example": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8"
},
"name": {
"type": "string",
"description": "Current service-period name.",
"example": "Example name"
},
"bookingMode": {
"type": "string",
"description": "Current service-period mode; it does not rewrite an original booking receipt.",
"enum": [
"INSTANT",
"REQUEST"
],
"example": "INSTANT"
}
},
"example": {
"id": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8",
"name": "Example name",
"bookingMode": "INSTANT"
}
},
"source": {
"type": "object",
"description": "Nonsecret exact native owner tuple and the original grant presentation. These identifiers do not grant authority or permit switching origins, connections or capabilities.",
"additionalProperties": false,
"required": [
"kind",
"entityId",
"venueId",
"publicChannelId",
"presentation"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"RESERVATION",
"WAITLIST"
],
"description": "Native owner kind.",
"example": "RESERVATION"
},
"entityId": {
"type": "string",
"format": "uuid",
"description": "Exact reservation or waitlist owner UUID.",
"example": "6b288694-8b6d-49cd-8007-264ca7224921"
},
"venueId": {
"type": "string",
"format": "uuid",
"description": "Native owner venue UUID.",
"example": "0604de3a-da74-4ad5-89f6-2dfe000d5391"
},
"publicChannelId": {
"type": "string",
"format": "uuid",
"description": "Native owner channel UUID.",
"example": "9bee613d-3322-4a03-8b9f-8a6259984eee"
},
"presentation": {
"type": "object",
"description": "Immutable issuance classification. CANONICAL has null Storefront fields; STOREFRONT retains the exact original connection, attached resource and request Origin.",
"additionalProperties": false,
"required": [
"kind",
"connectionId",
"resourceId",
"origin"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"CANONICAL",
"STOREFRONT"
],
"description": "Original grant issuance context.",
"example": "CANONICAL"
},
"connectionId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Original Storefront connection UUID, or null for canonical issuance.",
"example": "2fde64d5-54a3-47d0-800f-a015f92a8878"
},
"resourceId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Original attached Storefront resource UUID, or null for canonical issuance.",
"example": "d5b5eb29-9b8d-4d6f-8f4f-6f0e58f32568"
},
"origin": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "Exact original Storefront browser Origin, or null for canonical issuance.",
"example": "https://example.test/resource"
}
},
"example": {
"kind": "CANONICAL",
"connectionId": null,
"resourceId": null,
"origin": null
}
}
},
"example": {
"kind": "RESERVATION",
"entityId": "6b288694-8b6d-49cd-8007-264ca7224921",
"venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
"publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
"presentation": {
"kind": "CANONICAL",
"connectionId": null,
"resourceId": null,
"origin": null
}
}
},
"grantExpiresAt": {
"type": "string",
"format": "date-time",
"description": "Original native manage-capability expiry; reading does not renew it.",
"example": "2026-12-31T18:00:00.000Z"
},
"serverTime": {
"type": "string",
"format": "date-time",
"description": "Server instant used for current action and claim-deadline eligibility.",
"example": "2026-01-15T12:00:00.000Z"
},
"pendingAgreement": {
"type": "object",
"description": "Current pending proposal or accepted continuation, or null; it has not changed the actual native slot before activation.",
"additionalProperties": false,
"required": [
"id",
"action",
"state",
"revision",
"planHash",
"expiresAt",
"scheduledAt",
"endsAt",
"partySize",
"servicePeriodId",
"offer",
"activatedAgreementVersion",
"activatedReservationRevision"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Native agreement change UUID.",
"example": "5a694cf6-acf7-40fd-81e6-92ec0fa6c91f"
},
"action": {
"type": "string",
"enum": [
"CHANGE",
"RESTORE"
],
"description": "Explicit proposed native action.",
"example": "CHANGE"
},
"state": {
"type": "string",
"enum": [
"PENDING",
"ACCEPTED",
"ACTIVATED",
"EXPIRED",
"SUPERSEDED"
],
"description": "Current native continuation state.",
"example": "PENDING"
},
"revision": {
"type": "integer",
"minimum": 1,
"description": "Current native proposal revision.",
"example": 1
},
"planHash": {
"type": "string",
"pattern": "^[0-9a-f]{64}$",
"description": "Exact frozen slot and terms digest.",
"example": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
},
"expiresAt": {
"type": "string",
"format": "date-time",
"description": "Fixed activation deadline.",
"example": "2026-12-31T18:00:00.000Z"
},
"scheduledAt": {
"type": "string",
"format": "date-time",
"description": "Exact proposed scheduled instant.",
"example": "2026-01-15T12:00:00.000Z"
},
"endsAt": {
"type": "string",
"format": "date-time",
"description": "Exact proposed visit end instant.",
"example": "2026-12-31T18:00:00.000Z"
},
"partySize": {
"type": "integer",
"minimum": 1,
"maximum": 99,
"description": "Exact proposed guest count.",
"example": 1
},
"servicePeriodId": {
"type": "string",
"format": "uuid",
"description": "Proposed native service period.",
"example": "4846c409-f4df-40f6-81cc-1d7157a5c646"
},
"offer": {
"type": "object",
"description": "Server-computed guarantee proposal with its terms and digest. NONE or a party below the configured threshold requires no guarantee.",
"additionalProperties": false,
"required": [
"required",
"terms",
"termsHash"
],
"properties": {
"required": {
"type": "boolean",
"description": "Whether this exact slot and party require a guarantee.",
"example": true
},
"terms": {
"type": "object",
"description": "Exact accepted terms, or null when no guarantee applies.",
"additionalProperties": false,
"required": [
"schema",
"version",
"venueId",
"publicChannelId",
"servicePeriodId",
"servicePeriodRevision",
"kind",
"amountBasis",
"unitAmount",
"totalAmount",
"currency",
"currencyMinorUnit",
"partySize",
"scheduledAt",
"dueAt",
"freeCancellationAt",
"noShowAfter",
"forfeitOnLateCancellation",
"forfeitOnNoShow",
"termsVersion",
"privacyVersion"
],
"properties": {
"schema": {
"type": "string",
"enum": [
"hallify.reservation-guarantee.terms"
],
"description": "Canonical native terms schema.",
"example": "hallify.reservation-guarantee.terms"
},
"version": {
"type": "integer",
"enum": [
1
],
"description": "Canonical native terms version.",
"example": 1
},
"venueId": {
"type": "string",
"format": "uuid",
"description": "Native venue UUID.",
"example": "0604de3a-da74-4ad5-89f6-2dfe000d5391"
},
"publicChannelId": {
"type": "string",
"format": "uuid",
"description": "Native reservation channel UUID.",
"example": "9bee613d-3322-4a03-8b9f-8a6259984eee"
},
"servicePeriodId": {
"type": "string",
"format": "uuid",
"description": "Selected native service-period UUID.",
"example": "4846c409-f4df-40f6-81cc-1d7157a5c646"
},
"servicePeriodRevision": {
"type": "integer",
"minimum": 1,
"description": "Accepted native service-period revision.",
"example": 1
},
"kind": {
"type": "string",
"enum": [
"DEPOSIT",
"CARD_HOLD",
"PREPAID"
],
"description": "Original accepted guarantee kind.",
"example": "DEPOSIT"
},
"amountBasis": {
"type": "string",
"enum": [
"FIXED",
"PER_GUEST"
],
"description": "Original amount calculation basis.",
"example": "FIXED"
},
"unitAmount": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,9})\\.[0-9]{2}$",
"description": "Exact two-decimal amount per booking or guest.",
"example": "1.00"
},
"totalAmount": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,9})\\.[0-9]{2}$",
"description": "Exact two-decimal accepted total principal, with no tip.",
"example": "1.00"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "Original native currency; no conversion is performed.",
"example": "GEL"
},
"currencyMinorUnit": {
"type": "integer",
"enum": [
2
],
"description": "Native monetary scale.",
"example": 2
},
"partySize": {
"type": "integer",
"minimum": 1,
"maximum": 99,
"description": "Exact accepted party size.",
"example": 1
},
"scheduledAt": {
"type": "string",
"format": "date-time",
"description": "Exact scheduled UTC slot instant.",
"example": "2026-01-15T12:00:00.000Z"
},
"dueAt": {
"type": "string",
"format": "date-time",
"description": "Exact payment deadline before conversion and collection.",
"example": "2026-12-31T18:00:00.000Z"
},
"freeCancellationAt": {
"type": "string",
"format": "date-time",
"description": "Exact free-cancellation cutoff.",
"example": "2026-01-15T12:00:00.000Z"
},
"noShowAfter": {
"type": "string",
"format": "date-time",
"description": "Earliest no-show forfeiture instant under the accepted grace rule.",
"example": "2026-01-15T12:00:00.000Z"
},
"forfeitOnLateCancellation": {
"type": "boolean",
"description": "Accepted permission for explicit staff late-cancellation forfeiture.",
"example": true
},
"forfeitOnNoShow": {
"type": "boolean",
"description": "Accepted permission for explicit staff no-show forfeiture; no automatic card debit.",
"example": true
},
"termsVersion": {
"type": "string",
"description": "Accepted public terms version.",
"example": "example"
},
"privacyVersion": {
"type": "string",
"description": "Accepted privacy notice version.",
"example": "example"
}
},
"nullable": true,
"example": {
"schema": "hallify.reservation-guarantee.terms",
"version": 1,
"venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
"publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
"servicePeriodId": "4846c409-f4df-40f6-81cc-1d7157a5c646",
"servicePeriodRevision": 1,
"kind": "DEPOSIT",
"amountBasis": "FIXED",
"unitAmount": "1.00",
"totalAmount": "1.00",
"currency": "GEL",
"currencyMinorUnit": 2,
"partySize": 1,
"scheduledAt": "2026-01-15T12:00:00.000Z",
"dueAt": "2026-12-31T18:00:00.000Z",
"freeCancellationAt": "2026-01-15T12:00:00.000Z",
"noShowAfter": "2026-01-15T12:00:00.000Z",
"forfeitOnLateCancellation": true,
"forfeitOnNoShow": true,
"termsVersion": "example",
"privacyVersion": "example"
}
},
"termsHash": {
"type": "string",
"pattern": "^[0-9a-f]{64}$",
"nullable": true,
"description": "Canonical accepted terms digest, or null when no guarantee applies.",
"example": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
}
},
"example": {
"required": true,
"terms": null,
"termsHash": null
}
},
"activatedAgreementVersion": {
"type": "integer",
"minimum": 1,
"nullable": true,
"description": "Actual activated agreement version, or null before activation.",
"example": 1
},
"activatedReservationRevision": {
"type": "integer",
"minimum": 1,
"nullable": true,
"description": "Actual native revision recorded by activation, or null.",
"example": 1
}
},
"nullable": true,
"example": {
"id": "5a694cf6-acf7-40fd-81e6-92ec0fa6c91f",
"action": "CHANGE",
"state": "PENDING",
"revision": 1,
"planHash": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
"expiresAt": "2026-12-31T18:00:00.000Z",
"scheduledAt": "2026-01-15T12:00:00.000Z",
"endsAt": "2026-12-31T18:00:00.000Z",
"partySize": 1,
"servicePeriodId": "4846c409-f4df-40f6-81cc-1d7157a5c646",
"offer": {
"required": true,
"terms": null,
"termsHash": null
},
"activatedAgreementVersion": null,
"activatedReservationRevision": null
}
},
"guarantee": {
"type": "object",
"nullable": true,
"description": "Actual native guarantee and its immutable original accepted terms, or null when no obligation exists.",
"required": [
"id",
"kind",
"status",
"amount",
"currency",
"dueAt",
"termsHash",
"terms",
"authorizationExpiresAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Actual native guarantee UUID.",
"example": "d8c59877-4141-422c-8bcd-eb23a54e43ad"
},
"kind": {
"type": "string",
"enum": [
"DEPOSIT",
"CARD_HOLD",
"PREPAID"
],
"description": "Original guarantee kind.",
"example": "DEPOSIT"
},
"status": {
"type": "string",
"enum": [
"PENDING",
"SATISFIED",
"WAIVED",
"EXPIRED",
"REFUNDED",
"FORFEITED"
],
"description": "Current native guarantee lifecycle.",
"example": "PENDING"
},
"amount": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,9})\\.[0-9]{2}$",
"description": "Original exact native guarantee principal.",
"example": "1.00"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "Original native currency.",
"example": "GEL"
},
"dueAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Original payment deadline, or null for legacy evidence.",
"example": "2026-12-31T18:00:00.000Z"
},
"termsHash": {
"type": "string",
"pattern": "^[0-9a-f]{64}$",
"nullable": true,
"description": "Immutable accepted terms digest, or null for legacy evidence.",
"example": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
},
"terms": {
"type": "object",
"description": "Original accepted native guarantee terms, or null for legacy evidence.",
"additionalProperties": false,
"required": [
"schema",
"version",
"venueId",
"publicChannelId",
"servicePeriodId",
"servicePeriodRevision",
"kind",
"amountBasis",
"unitAmount",
"totalAmount",
"currency",
"currencyMinorUnit",
"partySize",
"scheduledAt",
"dueAt",
"freeCancellationAt",
"noShowAfter",
"forfeitOnLateCancellation",
"forfeitOnNoShow",
"termsVersion",
"privacyVersion"
],
"properties": {
"schema": {
"type": "string",
"enum": [
"hallify.reservation-guarantee.terms"
],
"description": "Canonical native terms schema.",
"example": "hallify.reservation-guarantee.terms"
},
"version": {
"type": "integer",
"enum": [
1
],
"description": "Canonical native terms version.",
"example": 1
},
"venueId": {
"type": "string",
"format": "uuid",
"description": "Native venue UUID.",
"example": "0604de3a-da74-4ad5-89f6-2dfe000d5391"
},
"publicChannelId": {
"type": "string",
"format": "uuid",
"description": "Native reservation channel UUID.",
"example": "9bee613d-3322-4a03-8b9f-8a6259984eee"
},
"servicePeriodId": {
"type": "string",
"format": "uuid",
"description": "Selected native service-period UUID.",
"example": "4846c409-f4df-40f6-81cc-1d7157a5c646"
},
"servicePeriodRevision": {
"type": "integer",
"minimum": 1,
"description": "Accepted native service-period revision.",
"example": 1
},
"kind": {
"type": "string",
"enum": [
"DEPOSIT",
"CARD_HOLD",
"PREPAID"
],
"description": "Original accepted guarantee kind.",
"example": "DEPOSIT"
},
"amountBasis": {
"type": "string",
"enum": [
"FIXED",
"PER_GUEST"
],
"description": "Original amount calculation basis.",
"example": "FIXED"
},
"unitAmount": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,9})\\.[0-9]{2}$",
"description": "Exact two-decimal amount per booking or guest.",
"example": "1.00"
},
"totalAmount": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,9})\\.[0-9]{2}$",
"description": "Exact two-decimal accepted total principal, with no tip.",
"example": "1.00"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "Original native currency; no conversion is performed.",
"example": "GEL"
},
"currencyMinorUnit": {
"type": "integer",
"enum": [
2
],
"description": "Native monetary scale.",
"example": 2
},
"partySize": {
"type": "integer",
"minimum": 1,
"maximum": 99,
"description": "Exact accepted party size.",
"example": 1
},
"scheduledAt": {
"type": "string",
"format": "date-time",
"description": "Exact scheduled UTC slot instant.",
"example": "2026-01-15T12:00:00.000Z"
},
"dueAt": {
"type": "string",
"format": "date-time",
"description": "Exact payment deadline before conversion and collection.",
"example": "2026-12-31T18:00:00.000Z"
},
"freeCancellationAt": {
"type": "string",
"format": "date-time",
"description": "Exact free-cancellation cutoff.",
"example": "2026-01-15T12:00:00.000Z"
},
"noShowAfter": {
"type": "string",
"format": "date-time",
"description": "Earliest no-show forfeiture instant under the accepted grace rule.",
"example": "2026-01-15T12:00:00.000Z"
},
"forfeitOnLateCancellation": {
"type": "boolean",
"description": "Accepted permission for explicit staff late-cancellation forfeiture.",
"example": true
},
"forfeitOnNoShow": {
"type": "boolean",
"description": "Accepted permission for explicit staff no-show forfeiture; no automatic card debit.",
"example": true
},
"termsVersion": {
"type": "string",
"description": "Accepted public terms version.",
"example": "example"
},
"privacyVersion": {
"type": "string",
"description": "Accepted privacy notice version.",
"example": "example"
}
},
"nullable": true,
"example": {
"schema": "hallify.reservation-guarantee.terms",
"version": 1,
"venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
"publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
"servicePeriodId": "4846c409-f4df-40f6-81cc-1d7157a5c646",
"servicePeriodRevision": 1,
"kind": "DEPOSIT",
"amountBasis": "FIXED",
"unitAmount": "1.00",
"totalAmount": "1.00",
"currency": "GEL",
"currencyMinorUnit": 2,
"partySize": 1,
"scheduledAt": "2026-01-15T12:00:00.000Z",
"dueAt": "2026-12-31T18:00:00.000Z",
"freeCancellationAt": "2026-01-15T12:00:00.000Z",
"noShowAfter": "2026-01-15T12:00:00.000Z",
"forfeitOnLateCancellation": true,
"forfeitOnNoShow": true,
"termsVersion": "example",
"privacyVersion": "example"
}
},
"authorizationExpiresAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Proven PSP authorization expiry, or null without authenticated evidence.",
"example": "2026-12-31T18:00:00.000Z"
}
},
"example": {
"id": "d8c59877-4141-422c-8bcd-eb23a54e43ad",
"kind": "DEPOSIT",
"status": "PENDING",
"amount": "1.00",
"currency": "GEL",
"dueAt": null,
"termsHash": null,
"terms": null,
"authorizationExpiresAt": null
}
},
"kind": {
"type": "string",
"enum": [
"RESERVATION"
],
"description": "Native owner kind.",
"example": "RESERVATION"
},
"id": {
"type": "string",
"format": "uuid",
"description": "Capability-owned reservation UUID.",
"example": "a42073ae-5313-4ace-86d8-86fb33fde1a9"
},
"referenceCode": {
"type": "string",
"description": "Guest-facing reference code.",
"example": "EXAMPLE"
},
"revision": {
"type": "integer",
"minimum": 1,
"description": "Current native reservation revision.",
"example": 1
},
"status": {
"type": "string",
"enum": [
"REQUESTED",
"BOOKED",
"CONFIRMED",
"ARRIVED",
"SEATED",
"CANCELED",
"NO_SHOW",
"DECLINED",
"EXPIRED"
],
"description": "Current native reservation lifecycle.",
"example": "REQUESTED"
},
"partySize": {
"type": "integer",
"minimum": 1,
"maximum": 99,
"description": "Current number of guests.",
"example": 1
},
"scheduledAt": {
"type": "string",
"format": "date-time",
"description": "Current scheduled arrival instant.",
"example": "2026-01-15T12:00:00.000Z"
},
"endsAt": {
"type": "string",
"format": "date-time",
"description": "Current scheduled reservation end.",
"example": "2026-12-31T18:00:00.000Z"
},
"allowedActions": {
"type": "array",
"description": "Actions currently allowed by lifecycle and grant scopes. Execution still rechecks revision, presentation, commercial admission, rules and capacity.",
"uniqueItems": true,
"maxItems": 3,
"items": {
"type": "string",
"enum": [
"CONFIRM",
"CHANGE",
"CANCEL"
],
"description": "Available native guest command.",
"example": "CONFIRM"
},
"example": [
"CONFIRM"
]
}
},
"example": {
"venue": {
"id": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0",
"name": "Example name",
"timeZone": "Asia/Tbilisi"
},
"publicChannel": {
"id": "3db2ed63-9466-4829-81aa-e4959a2279b0",
"publicHandle": "example",
"status": "DRAFT"
},
"servicePeriod": {
"id": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8",
"name": "Example name",
"bookingMode": "INSTANT"
},
"source": {
"kind": "RESERVATION",
"entityId": "6b288694-8b6d-49cd-8007-264ca7224921",
"venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
"publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
"presentation": {
"kind": "CANONICAL",
"connectionId": null,
"resourceId": null,
"origin": null
}
},
"grantExpiresAt": "2026-12-31T18:00:00.000Z",
"serverTime": "2026-01-15T12:00:00.000Z",
"pendingAgreement": null,
"guarantee": null,
"kind": "RESERVATION",
"id": "a42073ae-5313-4ace-86d8-86fb33fde1a9",
"referenceCode": "EXAMPLE",
"revision": 1,
"status": "REQUESTED",
"partySize": 1,
"scheduledAt": "2026-01-15T12:00:00.000Z",
"endsAt": "2026-12-31T18:00:00.000Z",
"allowedActions": [
"CONFIRM"
]
}
},
{
"type": "object",
"description": "Current waitlist context, safe wait estimate and capability-scoped native lifecycle actions.",
"additionalProperties": false,
"required": [
"kind",
"id",
"referenceCode",
"revision",
"status",
"partySize",
"claimExpiresAt",
"quotedWaitMinMinutes",
"quotedWaitMaxMinutes",
"estimatedSeatAt",
"venue",
"publicChannel",
"servicePeriod",
"source",
"grantExpiresAt",
"serverTime",
"allowedActions"
],
"properties": {
"venue": {
"type": "object",
"description": "Current native venue display and scheduling context.",
"additionalProperties": false,
"required": [
"id",
"name",
"timeZone"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Owning venue UUID.",
"example": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0"
},
"name": {
"type": "string",
"description": "Current public venue name.",
"example": "Example name"
},
"timeZone": {
"type": "string",
"description": "Native venue IANA time zone.",
"example": "Asia/Tbilisi"
}
},
"example": {
"id": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0",
"name": "Example name",
"timeZone": "Asia/Tbilisi"
}
},
"publicChannel": {
"type": "object",
"description": "The owner record's native public channel, independent of the storefront presentation handle. Its current status does not replace continuation authorization.",
"additionalProperties": false,
"required": [
"id",
"publicHandle",
"status"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Native channel UUID.",
"example": "3db2ed63-9466-4829-81aa-e4959a2279b0"
},
"publicHandle": {
"type": "string",
"description": "Native reservation channel handle.",
"example": "example"
},
"status": {
"type": "string",
"description": "Current native public-channel lifecycle.",
"enum": [
"DRAFT",
"ACTIVE",
"PAUSED"
],
"example": "DRAFT"
}
},
"example": {
"id": "3db2ed63-9466-4829-81aa-e4959a2279b0",
"publicHandle": "example",
"status": "DRAFT"
}
},
"servicePeriod": {
"type": "object",
"description": "Current native service-period identity and booking mode.",
"additionalProperties": false,
"required": [
"id",
"name",
"bookingMode"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Native service-period UUID.",
"example": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8"
},
"name": {
"type": "string",
"description": "Current service-period name.",
"example": "Example name"
},
"bookingMode": {
"type": "string",
"description": "Current service-period mode; it does not rewrite an original booking receipt.",
"enum": [
"INSTANT",
"REQUEST"
],
"example": "INSTANT"
}
},
"example": {
"id": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8",
"name": "Example name",
"bookingMode": "INSTANT"
}
},
"source": {
"type": "object",
"description": "Nonsecret exact native owner tuple and the original grant presentation. These identifiers do not grant authority or permit switching origins, connections or capabilities.",
"additionalProperties": false,
"required": [
"kind",
"entityId",
"venueId",
"publicChannelId",
"presentation"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"RESERVATION",
"WAITLIST"
],
"description": "Native owner kind.",
"example": "RESERVATION"
},
"entityId": {
"type": "string",
"format": "uuid",
"description": "Exact reservation or waitlist owner UUID.",
"example": "6b288694-8b6d-49cd-8007-264ca7224921"
},
"venueId": {
"type": "string",
"format": "uuid",
"description": "Native owner venue UUID.",
"example": "0604de3a-da74-4ad5-89f6-2dfe000d5391"
},
"publicChannelId": {
"type": "string",
"format": "uuid",
"description": "Native owner channel UUID.",
"example": "9bee613d-3322-4a03-8b9f-8a6259984eee"
},
"presentation": {
"type": "object",
"description": "Immutable issuance classification. CANONICAL has null Storefront fields; STOREFRONT retains the exact original connection, attached resource and request Origin.",
"additionalProperties": false,
"required": [
"kind",
"connectionId",
"resourceId",
"origin"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"CANONICAL",
"STOREFRONT"
],
"description": "Original grant issuance context.",
"example": "CANONICAL"
},
"connectionId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Original Storefront connection UUID, or null for canonical issuance.",
"example": "2fde64d5-54a3-47d0-800f-a015f92a8878"
},
"resourceId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Original attached Storefront resource UUID, or null for canonical issuance.",
"example": "d5b5eb29-9b8d-4d6f-8f4f-6f0e58f32568"
},
"origin": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "Exact original Storefront browser Origin, or null for canonical issuance.",
"example": "https://example.test/resource"
}
},
"example": {
"kind": "CANONICAL",
"connectionId": null,
"resourceId": null,
"origin": null
}
}
},
"example": {
"kind": "RESERVATION",
"entityId": "6b288694-8b6d-49cd-8007-264ca7224921",
"venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
"publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
"presentation": {
"kind": "CANONICAL",
"connectionId": null,
"resourceId": null,
"origin": null
}
}
},
"grantExpiresAt": {
"type": "string",
"format": "date-time",
"description": "Original native manage-capability expiry; reading does not renew it.",
"example": "2026-12-31T18:00:00.000Z"
},
"serverTime": {
"type": "string",
"format": "date-time",
"description": "Server instant used for current action and claim-deadline eligibility.",
"example": "2026-01-15T12:00:00.000Z"
},
"kind": {
"type": "string",
"enum": [
"WAITLIST"
],
"description": "Native owner kind.",
"example": "WAITLIST"
},
"id": {
"type": "string",
"format": "uuid",
"description": "Capability-owned waitlist entry UUID.",
"example": "a7476fce-e842-42a4-896a-c23b0e88b420"
},
"referenceCode": {
"type": "string",
"description": "Guest-facing reference code.",
"example": "EXAMPLE"
},
"revision": {
"type": "integer",
"minimum": 1,
"description": "Current native waitlist revision.",
"example": 1
},
"status": {
"type": "string",
"enum": [
"WAITING",
"NOTIFIED",
"CLAIMED",
"SKIPPED",
"SEATED",
"CANCELED",
"NO_SHOW"
],
"description": "Current native waitlist lifecycle.",
"example": "WAITING"
},
"partySize": {
"type": "integer",
"minimum": 1,
"maximum": 99,
"description": "Current number of guests.",
"example": 1
},
"claimExpiresAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Native accepted-offer claim deadline, or null without a current window.",
"example": "2026-12-31T18:00:00.000Z"
},
"quotedWaitMinMinutes": {
"type": "integer",
"nullable": true,
"description": "Current native minimum wait estimate in minutes, or null when unknown.",
"example": 0
},
"quotedWaitMaxMinutes": {
"type": "integer",
"nullable": true,
"description": "Current native maximum wait estimate in minutes, or null when unknown.",
"example": 0
},
"estimatedSeatAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Current native estimated seating instant, or null when unknown.",
"example": "2026-01-15T12:00:00.000Z"
},
"allowedActions": {
"type": "array",
"description": "Actions currently allowed by lifecycle, grant scopes and the native claim deadline. CLAIM changes the waitlist to CLAIMED and does not create a reservation.",
"uniqueItems": true,
"maxItems": 2,
"items": {
"type": "string",
"enum": [
"CLAIM",
"CANCEL"
],
"description": "Available native guest waitlist command.",
"example": "CLAIM"
},
"example": [
"CLAIM"
]
}
},
"example": {
"venue": {
"id": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0",
"name": "Example name",
"timeZone": "Asia/Tbilisi"
},
"publicChannel": {
"id": "3db2ed63-9466-4829-81aa-e4959a2279b0",
"publicHandle": "example",
"status": "DRAFT"
},
"servicePeriod": {
"id": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8",
"name": "Example name",
"bookingMode": "INSTANT"
},
"source": {
"kind": "RESERVATION",
"entityId": "6b288694-8b6d-49cd-8007-264ca7224921",
"venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
"publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
"presentation": {
"kind": "CANONICAL",
"connectionId": null,
"resourceId": null,
"origin": null
}
},
"grantExpiresAt": "2026-12-31T18:00:00.000Z",
"serverTime": "2026-01-15T12:00:00.000Z",
"kind": "WAITLIST",
"id": "a7476fce-e842-42a4-896a-c23b0e88b420",
"referenceCode": "EXAMPLE",
"revision": 1,
"status": "WAITING",
"partySize": 1,
"claimExpiresAt": null,
"quotedWaitMinMinutes": null,
"quotedWaitMaxMinutes": null,
"estimatedSeatAt": null,
"allowedActions": [
"CLAIM"
]
}
}
],
"example": {
"venue": {
"id": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0",
"name": "Example name",
"timeZone": "Asia/Tbilisi"
},
"publicChannel": {
"id": "3db2ed63-9466-4829-81aa-e4959a2279b0",
"publicHandle": "example",
"status": "DRAFT"
},
"servicePeriod": {
"id": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8",
"name": "Example name",
"bookingMode": "INSTANT"
},
"source": {
"kind": "RESERVATION",
"entityId": "6b288694-8b6d-49cd-8007-264ca7224921",
"venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
"publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
"presentation": {
"kind": "CANONICAL",
"connectionId": null,
"resourceId": null,
"origin": null
}
},
"grantExpiresAt": "2026-12-31T18:00:00.000Z",
"serverTime": "2026-01-15T12:00:00.000Z",
"pendingAgreement": null,
"guarantee": null,
"kind": "RESERVATION",
"id": "a42073ae-5313-4ace-86d8-86fb33fde1a9",
"referenceCode": "EXAMPLE",
"revision": 1,
"status": "REQUESTED",
"partySize": 1,
"scheduledAt": "2026-01-15T12:00:00.000Z",
"endsAt": "2026-12-31T18:00:00.000Z",
"allowedActions": [
"CONFIRM"
]
}
},
{
"type": "object",
"additionalProperties": false,
"nullable": true,
"enum": [
null
],
"description": "No current authorized management view is available.",
"example": null
}
],
"example": {
"venue": {
"id": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0",
"name": "Example name",
"timeZone": "Asia/Tbilisi"
},
"publicChannel": {
"id": "3db2ed63-9466-4829-81aa-e4959a2279b0",
"publicHandle": "example",
"status": "DRAFT"
},
"servicePeriod": {
"id": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8",
"name": "Example name",
"bookingMode": "INSTANT"
},
"source": {
"kind": "RESERVATION",
"entityId": "6b288694-8b6d-49cd-8007-264ca7224921",
"venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
"publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
"presentation": {
"kind": "CANONICAL",
"connectionId": null,
"resourceId": null,
"origin": null
}
},
"grantExpiresAt": "2026-12-31T18:00:00.000Z",
"serverTime": "2026-01-15T12:00:00.000Z",
"pendingAgreement": null,
"guarantee": null,
"kind": "RESERVATION",
"id": "a42073ae-5313-4ace-86d8-86fb33fde1a9",
"referenceCode": "EXAMPLE",
"revision": 1,
"status": "REQUESTED",
"partySize": 1,
"scheduledAt": "2026-01-15T12:00:00.000Z",
"endsAt": "2026-12-31T18:00:00.000Z",
"allowedActions": [
"CONFIRM"
]
}
}
},
"example": {
"kind": "RESERVATION",
"entityId": "6b288694-8b6d-49cd-8007-264ca7224921",
"referenceCode": "EXAMPLE",
"revision": 1,
"status": "REQUESTED",
"eventIds": [
"6825b43e-93d6-4f3b-8171-c1661099fae8"
],
"manageToken": "synthetic-example-credential",
"manageTokenExpiresAt": "2026-12-31T18:00:00.000Z",
"currentState": "AVAILABLE",
"current": {
"venue": {
"id": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0",
"name": "Example name",
"timeZone": "Asia/Tbilisi"
},
"publicChannel": {
"id": "3db2ed63-9466-4829-81aa-e4959a2279b0",
"publicHandle": "example",
"status": "DRAFT"
},
"servicePeriod": {
"id": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8",
"name": "Example name",
"bookingMode": "INSTANT"
},
"source": {
"kind": "RESERVATION",
"entityId": "6b288694-8b6d-49cd-8007-264ca7224921",
"venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
"publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
"presentation": {
"kind": "CANONICAL",
"connectionId": null,
"resourceId": null,
"origin": null
}
},
"grantExpiresAt": "2026-12-31T18:00:00.000Z",
"serverTime": "2026-01-15T12:00:00.000Z",
"pendingAgreement": null,
"guarantee": null,
"kind": "RESERVATION",
"id": "a42073ae-5313-4ace-86d8-86fb33fde1a9",
"referenceCode": "EXAMPLE",
"revision": 1,
"status": "REQUESTED",
"partySize": 1,
"scheduledAt": "2026-01-15T12:00:00.000Z",
"endsAt": "2026-12-31T18:00:00.000Z",
"allowedActions": [
"CONFIRM"
]
}
}
},
{
"type": "object",
"description": "Verified waitlist intent result.",
"required": [
"kind",
"entityId",
"referenceCode",
"revision",
"status",
"eventIds",
"manageToken",
"manageTokenExpiresAt",
"currentState",
"current"
],
"properties": {
"kind": {
"type": "string",
"description": "Kind of the created guest-managed entity.",
"enum": [
"WAITLIST"
],
"example": "WAITLIST"
},
"entityId": {
"type": "string",
"description": "Created reservation or waitlist entry identifier.",
"format": "uuid",
"example": "6b288694-8b6d-49cd-8007-264ca7224921"
},
"referenceCode": {
"type": "string",
"description": "Guest-facing reference code.",
"example": "EXAMPLE"
},
"revision": {
"type": "integer",
"description": "Current entity revision.",
"example": 1
},
"status": {
"type": "string",
"description": "Resulting booking or waitlist status.",
"enum": [
"WAITING",
"NOTIFIED",
"CLAIMED",
"SKIPPED",
"SEATED",
"CANCELED",
"NO_SHOW"
],
"example": "WAITING"
},
"eventIds": {
"type": "array",
"description": "Events emitted by this command.",
"items": {
"type": "string",
"description": "Reservation activity event identifier.",
"format": "uuid",
"example": "6825b43e-93d6-4f3b-8171-c1661099fae8"
},
"example": [
"6825b43e-93d6-4f3b-8171-c1661099fae8"
]
},
"manageToken": {
"type": "string",
"description": "Sensitive guest capability for subsequent management requests. Use the documented guest authorization header; never log it.",
"example": "synthetic-example-credential"
},
"manageTokenExpiresAt": {
"type": "string",
"description": "Expiry of the guest management capability.",
"format": "date-time",
"example": "2026-12-31T18:00:00.000Z"
},
"currentState": {
"type": "string",
"enum": [
"AVAILABLE",
"UNAVAILABLE"
],
"description": "Whether separate current management enrichment is available. This never changes the original committed receipt or issues another grant.",
"example": "AVAILABLE"
},
"current": {
"description": "Separate current authorized management view, or null when the original grant is no longer usable or current enrichment is unavailable. Historical receipt fields and the original token remain unchanged.",
"oneOf": [
{
"description": "Current guest-safe management view under the exact native READ grant and current presentation authority. It is separate from an immutable original command receipt.",
"oneOf": [
{
"type": "object",
"description": "Current reservation context and capability-scoped native lifecycle actions.",
"additionalProperties": false,
"required": [
"kind",
"id",
"referenceCode",
"revision",
"status",
"partySize",
"scheduledAt",
"endsAt",
"venue",
"publicChannel",
"servicePeriod",
"source",
"grantExpiresAt",
"serverTime",
"allowedActions",
"guarantee",
"pendingAgreement"
],
"properties": {
"venue": {
"type": "object",
"description": "Current native venue display and scheduling context.",
"additionalProperties": false,
"required": [
"id",
"name",
"timeZone"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Owning venue UUID.",
"example": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0"
},
"name": {
"type": "string",
"description": "Current public venue name.",
"example": "Example name"
},
"timeZone": {
"type": "string",
"description": "Native venue IANA time zone.",
"example": "Asia/Tbilisi"
}
},
"example": {
"id": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0",
"name": "Example name",
"timeZone": "Asia/Tbilisi"
}
},
"publicChannel": {
"type": "object",
"description": "The owner record's native public channel, independent of the storefront presentation handle. Its current status does not replace continuation authorization.",
"additionalProperties": false,
"required": [
"id",
"publicHandle",
"status"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Native channel UUID.",
"example": "3db2ed63-9466-4829-81aa-e4959a2279b0"
},
"publicHandle": {
"type": "string",
"description": "Native reservation channel handle.",
"example": "example"
},
"status": {
"type": "string",
"description": "Current native public-channel lifecycle.",
"enum": [
"DRAFT",
"ACTIVE",
"PAUSED"
],
"example": "DRAFT"
}
},
"example": {
"id": "3db2ed63-9466-4829-81aa-e4959a2279b0",
"publicHandle": "example",
"status": "DRAFT"
}
},
"servicePeriod": {
"type": "object",
"description": "Current native service-period identity and booking mode.",
"additionalProperties": false,
"required": [
"id",
"name",
"bookingMode"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Native service-period UUID.",
"example": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8"
},
"name": {
"type": "string",
"description": "Current service-period name.",
"example": "Example name"
},
"bookingMode": {
"type": "string",
"description": "Current service-period mode; it does not rewrite an original booking receipt.",
"enum": [
"INSTANT",
"REQUEST"
],
"example": "INSTANT"
}
},
"example": {
"id": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8",
"name": "Example name",
"bookingMode": "INSTANT"
}
},
"source": {
"type": "object",
"description": "Nonsecret exact native owner tuple and the original grant presentation. These identifiers do not grant authority or permit switching origins, connections or capabilities.",
"additionalProperties": false,
"required": [
"kind",
"entityId",
"venueId",
"publicChannelId",
"presentation"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"RESERVATION",
"WAITLIST"
],
"description": "Native owner kind.",
"example": "RESERVATION"
},
"entityId": {
"type": "string",
"format": "uuid",
"description": "Exact reservation or waitlist owner UUID.",
"example": "6b288694-8b6d-49cd-8007-264ca7224921"
},
"venueId": {
"type": "string",
"format": "uuid",
"description": "Native owner venue UUID.",
"example": "0604de3a-da74-4ad5-89f6-2dfe000d5391"
},
"publicChannelId": {
"type": "string",
"format": "uuid",
"description": "Native owner channel UUID.",
"example": "9bee613d-3322-4a03-8b9f-8a6259984eee"
},
"presentation": {
"type": "object",
"description": "Immutable issuance classification. CANONICAL has null Storefront fields; STOREFRONT retains the exact original connection, attached resource and request Origin.",
"additionalProperties": false,
"required": [
"kind",
"connectionId",
"resourceId",
"origin"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"CANONICAL",
"STOREFRONT"
],
"description": "Original grant issuance context.",
"example": "CANONICAL"
},
"connectionId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Original Storefront connection UUID, or null for canonical issuance.",
"example": "2fde64d5-54a3-47d0-800f-a015f92a8878"
},
"resourceId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Original attached Storefront resource UUID, or null for canonical issuance.",
"example": "d5b5eb29-9b8d-4d6f-8f4f-6f0e58f32568"
},
"origin": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "Exact original Storefront browser Origin, or null for canonical issuance.",
"example": "https://example.test/resource"
}
},
"example": {
"kind": "CANONICAL",
"connectionId": null,
"resourceId": null,
"origin": null
}
}
},
"example": {
"kind": "RESERVATION",
"entityId": "6b288694-8b6d-49cd-8007-264ca7224921",
"venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
"publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
"presentation": {
"kind": "CANONICAL",
"connectionId": null,
"resourceId": null,
"origin": null
}
}
},
"grantExpiresAt": {
"type": "string",
"format": "date-time",
"description": "Original native manage-capability expiry; reading does not renew it.",
"example": "2026-12-31T18:00:00.000Z"
},
"serverTime": {
"type": "string",
"format": "date-time",
"description": "Server instant used for current action and claim-deadline eligibility.",
"example": "2026-01-15T12:00:00.000Z"
},
"pendingAgreement": {
"type": "object",
"description": "Current pending proposal or accepted continuation, or null; it has not changed the actual native slot before activation.",
"additionalProperties": false,
"required": [
"id",
"action",
"state",
"revision",
"planHash",
"expiresAt",
"scheduledAt",
"endsAt",
"partySize",
"servicePeriodId",
"offer",
"activatedAgreementVersion",
"activatedReservationRevision"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Native agreement change UUID.",
"example": "5a694cf6-acf7-40fd-81e6-92ec0fa6c91f"
},
"action": {
"type": "string",
"enum": [
"CHANGE",
"RESTORE"
],
"description": "Explicit proposed native action.",
"example": "CHANGE"
},
"state": {
"type": "string",
"enum": [
"PENDING",
"ACCEPTED",
"ACTIVATED",
"EXPIRED",
"SUPERSEDED"
],
"description": "Current native continuation state.",
"example": "PENDING"
},
"revision": {
"type": "integer",
"minimum": 1,
"description": "Current native proposal revision.",
"example": 1
},
"planHash": {
"type": "string",
"pattern": "^[0-9a-f]{64}$",
"description": "Exact frozen slot and terms digest.",
"example": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
},
"expiresAt": {
"type": "string",
"format": "date-time",
"description": "Fixed activation deadline.",
"example": "2026-12-31T18:00:00.000Z"
},
"scheduledAt": {
"type": "string",
"format": "date-time",
"description": "Exact proposed scheduled instant.",
"example": "2026-01-15T12:00:00.000Z"
},
"endsAt": {
"type": "string",
"format": "date-time",
"description": "Exact proposed visit end instant.",
"example": "2026-12-31T18:00:00.000Z"
},
"partySize": {
"type": "integer",
"minimum": 1,
"maximum": 99,
"description": "Exact proposed guest count.",
"example": 1
},
"servicePeriodId": {
"type": "string",
"format": "uuid",
"description": "Proposed native service period.",
"example": "4846c409-f4df-40f6-81cc-1d7157a5c646"
},
"offer": {
"type": "object",
"description": "Server-computed guarantee proposal with its terms and digest. NONE or a party below the configured threshold requires no guarantee.",
"additionalProperties": false,
"required": [
"required",
"terms",
"termsHash"
],
"properties": {
"required": {
"type": "boolean",
"description": "Whether this exact slot and party require a guarantee.",
"example": true
},
"terms": {
"type": "object",
"description": "Exact accepted terms, or null when no guarantee applies.",
"additionalProperties": false,
"required": [
"schema",
"version",
"venueId",
"publicChannelId",
"servicePeriodId",
"servicePeriodRevision",
"kind",
"amountBasis",
"unitAmount",
"totalAmount",
"currency",
"currencyMinorUnit",
"partySize",
"scheduledAt",
"dueAt",
"freeCancellationAt",
"noShowAfter",
"forfeitOnLateCancellation",
"forfeitOnNoShow",
"termsVersion",
"privacyVersion"
],
"properties": {
"schema": {
"type": "string",
"enum": [
"hallify.reservation-guarantee.terms"
],
"description": "Canonical native terms schema.",
"example": "hallify.reservation-guarantee.terms"
},
"version": {
"type": "integer",
"enum": [
1
],
"description": "Canonical native terms version.",
"example": 1
},
"venueId": {
"type": "string",
"format": "uuid",
"description": "Native venue UUID.",
"example": "0604de3a-da74-4ad5-89f6-2dfe000d5391"
},
"publicChannelId": {
"type": "string",
"format": "uuid",
"description": "Native reservation channel UUID.",
"example": "9bee613d-3322-4a03-8b9f-8a6259984eee"
},
"servicePeriodId": {
"type": "string",
"format": "uuid",
"description": "Selected native service-period UUID.",
"example": "4846c409-f4df-40f6-81cc-1d7157a5c646"
},
"servicePeriodRevision": {
"type": "integer",
"minimum": 1,
"description": "Accepted native service-period revision.",
"example": 1
},
"kind": {
"type": "string",
"enum": [
"DEPOSIT",
"CARD_HOLD",
"PREPAID"
],
"description": "Original accepted guarantee kind.",
"example": "DEPOSIT"
},
"amountBasis": {
"type": "string",
"enum": [
"FIXED",
"PER_GUEST"
],
"description": "Original amount calculation basis.",
"example": "FIXED"
},
"unitAmount": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,9})\\.[0-9]{2}$",
"description": "Exact two-decimal amount per booking or guest.",
"example": "1.00"
},
"totalAmount": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,9})\\.[0-9]{2}$",
"description": "Exact two-decimal accepted total principal, with no tip.",
"example": "1.00"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "Original native currency; no conversion is performed.",
"example": "GEL"
},
"currencyMinorUnit": {
"type": "integer",
"enum": [
2
],
"description": "Native monetary scale.",
"example": 2
},
"partySize": {
"type": "integer",
"minimum": 1,
"maximum": 99,
"description": "Exact accepted party size.",
"example": 1
},
"scheduledAt": {
"type": "string",
"format": "date-time",
"description": "Exact scheduled UTC slot instant.",
"example": "2026-01-15T12:00:00.000Z"
},
"dueAt": {
"type": "string",
"format": "date-time",
"description": "Exact payment deadline before conversion and collection.",
"example": "2026-12-31T18:00:00.000Z"
},
"freeCancellationAt": {
"type": "string",
"format": "date-time",
"description": "Exact free-cancellation cutoff.",
"example": "2026-01-15T12:00:00.000Z"
},
"noShowAfter": {
"type": "string",
"format": "date-time",
"description": "Earliest no-show forfeiture instant under the accepted grace rule.",
"example": "2026-01-15T12:00:00.000Z"
},
"forfeitOnLateCancellation": {
"type": "boolean",
"description": "Accepted permission for explicit staff late-cancellation forfeiture.",
"example": true
},
"forfeitOnNoShow": {
"type": "boolean",
"description": "Accepted permission for explicit staff no-show forfeiture; no automatic card debit.",
"example": true
},
"termsVersion": {
"type": "string",
"description": "Accepted public terms version.",
"example": "example"
},
"privacyVersion": {
"type": "string",
"description": "Accepted privacy notice version.",
"example": "example"
}
},
"nullable": true,
"example": {
"schema": "hallify.reservation-guarantee.terms",
"version": 1,
"venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
"publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
"servicePeriodId": "4846c409-f4df-40f6-81cc-1d7157a5c646",
"servicePeriodRevision": 1,
"kind": "DEPOSIT",
"amountBasis": "FIXED",
"unitAmount": "1.00",
"totalAmount": "1.00",
"currency": "GEL",
"currencyMinorUnit": 2,
"partySize": 1,
"scheduledAt": "2026-01-15T12:00:00.000Z",
"dueAt": "2026-12-31T18:00:00.000Z",
"freeCancellationAt": "2026-01-15T12:00:00.000Z",
"noShowAfter": "2026-01-15T12:00:00.000Z",
"forfeitOnLateCancellation": true,
"forfeitOnNoShow": true,
"termsVersion": "example",
"privacyVersion": "example"
}
},
"termsHash": {
"type": "string",
"pattern": "^[0-9a-f]{64}$",
"nullable": true,
"description": "Canonical accepted terms digest, or null when no guarantee applies.",
"example": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
}
},
"example": {
"required": true,
"terms": null,
"termsHash": null
}
},
"activatedAgreementVersion": {
"type": "integer",
"minimum": 1,
"nullable": true,
"description": "Actual activated agreement version, or null before activation.",
"example": 1
},
"activatedReservationRevision": {
"type": "integer",
"minimum": 1,
"nullable": true,
"description": "Actual native revision recorded by activation, or null.",
"example": 1
}
},
"nullable": true,
"example": {
"id": "5a694cf6-acf7-40fd-81e6-92ec0fa6c91f",
"action": "CHANGE",
"state": "PENDING",
"revision": 1,
"planHash": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
"expiresAt": "2026-12-31T18:00:00.000Z",
"scheduledAt": "2026-01-15T12:00:00.000Z",
"endsAt": "2026-12-31T18:00:00.000Z",
"partySize": 1,
"servicePeriodId": "4846c409-f4df-40f6-81cc-1d7157a5c646",
"offer": {
"required": true,
"terms": null,
"termsHash": null
},
"activatedAgreementVersion": null,
"activatedReservationRevision": null
}
},
"guarantee": {
"type": "object",
"nullable": true,
"description": "Actual native guarantee and its immutable original accepted terms, or null when no obligation exists.",
"required": [
"id",
"kind",
"status",
"amount",
"currency",
"dueAt",
"termsHash",
"terms",
"authorizationExpiresAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Actual native guarantee UUID.",
"example": "d8c59877-4141-422c-8bcd-eb23a54e43ad"
},
"kind": {
"type": "string",
"enum": [
"DEPOSIT",
"CARD_HOLD",
"PREPAID"
],
"description": "Original guarantee kind.",
"example": "DEPOSIT"
},
"status": {
"type": "string",
"enum": [
"PENDING",
"SATISFIED",
"WAIVED",
"EXPIRED",
"REFUNDED",
"FORFEITED"
],
"description": "Current native guarantee lifecycle.",
"example": "PENDING"
},
"amount": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,9})\\.[0-9]{2}$",
"description": "Original exact native guarantee principal.",
"example": "1.00"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "Original native currency.",
"example": "GEL"
},
"dueAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Original payment deadline, or null for legacy evidence.",
"example": "2026-12-31T18:00:00.000Z"
},
"termsHash": {
"type": "string",
"pattern": "^[0-9a-f]{64}$",
"nullable": true,
"description": "Immutable accepted terms digest, or null for legacy evidence.",
"example": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
},
"terms": {
"type": "object",
"description": "Original accepted native guarantee terms, or null for legacy evidence.",
"additionalProperties": false,
"required": [
"schema",
"version",
"venueId",
"publicChannelId",
"servicePeriodId",
"servicePeriodRevision",
"kind",
"amountBasis",
"unitAmount",
"totalAmount",
"currency",
"currencyMinorUnit",
"partySize",
"scheduledAt",
"dueAt",
"freeCancellationAt",
"noShowAfter",
"forfeitOnLateCancellation",
"forfeitOnNoShow",
"termsVersion",
"privacyVersion"
],
"properties": {
"schema": {
"type": "string",
"enum": [
"hallify.reservation-guarantee.terms"
],
"description": "Canonical native terms schema.",
"example": "hallify.reservation-guarantee.terms"
},
"version": {
"type": "integer",
"enum": [
1
],
"description": "Canonical native terms version.",
"example": 1
},
"venueId": {
"type": "string",
"format": "uuid",
"description": "Native venue UUID.",
"example": "0604de3a-da74-4ad5-89f6-2dfe000d5391"
},
"publicChannelId": {
"type": "string",
"format": "uuid",
"description": "Native reservation channel UUID.",
"example": "9bee613d-3322-4a03-8b9f-8a6259984eee"
},
"servicePeriodId": {
"type": "string",
"format": "uuid",
"description": "Selected native service-period UUID.",
"example": "4846c409-f4df-40f6-81cc-1d7157a5c646"
},
"servicePeriodRevision": {
"type": "integer",
"minimum": 1,
"description": "Accepted native service-period revision.",
"example": 1
},
"kind": {
"type": "string",
"enum": [
"DEPOSIT",
"CARD_HOLD",
"PREPAID"
],
"description": "Original accepted guarantee kind.",
"example": "DEPOSIT"
},
"amountBasis": {
"type": "string",
"enum": [
"FIXED",
"PER_GUEST"
],
"description": "Original amount calculation basis.",
"example": "FIXED"
},
"unitAmount": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,9})\\.[0-9]{2}$",
"description": "Exact two-decimal amount per booking or guest.",
"example": "1.00"
},
"totalAmount": {
"type": "string",
"pattern": "^(0|[1-9][0-9]{0,9})\\.[0-9]{2}$",
"description": "Exact two-decimal accepted total principal, with no tip.",
"example": "1.00"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "Original native currency; no conversion is performed.",
"example": "GEL"
},
"currencyMinorUnit": {
"type": "integer",
"enum": [
2
],
"description": "Native monetary scale.",
"example": 2
},
"partySize": {
"type": "integer",
"minimum": 1,
"maximum": 99,
"description": "Exact accepted party size.",
"example": 1
},
"scheduledAt": {
"type": "string",
"format": "date-time",
"description": "Exact scheduled UTC slot instant.",
"example": "2026-01-15T12:00:00.000Z"
},
"dueAt": {
"type": "string",
"format": "date-time",
"description": "Exact payment deadline before conversion and collection.",
"example": "2026-12-31T18:00:00.000Z"
},
"freeCancellationAt": {
"type": "string",
"format": "date-time",
"description": "Exact free-cancellation cutoff.",
"example": "2026-01-15T12:00:00.000Z"
},
"noShowAfter": {
"type": "string",
"format": "date-time",
"description": "Earliest no-show forfeiture instant under the accepted grace rule.",
"example": "2026-01-15T12:00:00.000Z"
},
"forfeitOnLateCancellation": {
"type": "boolean",
"description": "Accepted permission for explicit staff late-cancellation forfeiture.",
"example": true
},
"forfeitOnNoShow": {
"type": "boolean",
"description": "Accepted permission for explicit staff no-show forfeiture; no automatic card debit.",
"example": true
},
"termsVersion": {
"type": "string",
"description": "Accepted public terms version.",
"example": "example"
},
"privacyVersion": {
"type": "string",
"description": "Accepted privacy notice version.",
"example": "example"
}
},
"nullable": true,
"example": {
"schema": "hallify.reservation-guarantee.terms",
"version": 1,
"venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
"publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
"servicePeriodId": "4846c409-f4df-40f6-81cc-1d7157a5c646",
"servicePeriodRevision": 1,
"kind": "DEPOSIT",
"amountBasis": "FIXED",
"unitAmount": "1.00",
"totalAmount": "1.00",
"currency": "GEL",
"currencyMinorUnit": 2,
"partySize": 1,
"scheduledAt": "2026-01-15T12:00:00.000Z",
"dueAt": "2026-12-31T18:00:00.000Z",
"freeCancellationAt": "2026-01-15T12:00:00.000Z",
"noShowAfter": "2026-01-15T12:00:00.000Z",
"forfeitOnLateCancellation": true,
"forfeitOnNoShow": true,
"termsVersion": "example",
"privacyVersion": "example"
}
},
"authorizationExpiresAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Proven PSP authorization expiry, or null without authenticated evidence.",
"example": "2026-12-31T18:00:00.000Z"
}
},
"example": {
"id": "d8c59877-4141-422c-8bcd-eb23a54e43ad",
"kind": "DEPOSIT",
"status": "PENDING",
"amount": "1.00",
"currency": "GEL",
"dueAt": null,
"termsHash": null,
"terms": null,
"authorizationExpiresAt": null
}
},
"kind": {
"type": "string",
"enum": [
"RESERVATION"
],
"description": "Native owner kind.",
"example": "RESERVATION"
},
"id": {
"type": "string",
"format": "uuid",
"description": "Capability-owned reservation UUID.",
"example": "a42073ae-5313-4ace-86d8-86fb33fde1a9"
},
"referenceCode": {
"type": "string",
"description": "Guest-facing reference code.",
"example": "EXAMPLE"
},
"revision": {
"type": "integer",
"minimum": 1,
"description": "Current native reservation revision.",
"example": 1
},
"status": {
"type": "string",
"enum": [
"REQUESTED",
"BOOKED",
"CONFIRMED",
"ARRIVED",
"SEATED",
"CANCELED",
"NO_SHOW",
"DECLINED",
"EXPIRED"
],
"description": "Current native reservation lifecycle.",
"example": "REQUESTED"
},
"partySize": {
"type": "integer",
"minimum": 1,
"maximum": 99,
"description": "Current number of guests.",
"example": 1
},
"scheduledAt": {
"type": "string",
"format": "date-time",
"description": "Current scheduled arrival instant.",
"example": "2026-01-15T12:00:00.000Z"
},
"endsAt": {
"type": "string",
"format": "date-time",
"description": "Current scheduled reservation end.",
"example": "2026-12-31T18:00:00.000Z"
},
"allowedActions": {
"type": "array",
"description": "Actions currently allowed by lifecycle and grant scopes. Execution still rechecks revision, presentation, commercial admission, rules and capacity.",
"uniqueItems": true,
"maxItems": 3,
"items": {
"type": "string",
"enum": [
"CONFIRM",
"CHANGE",
"CANCEL"
],
"description": "Available native guest command.",
"example": "CONFIRM"
},
"example": [
"CONFIRM"
]
}
},
"example": {
"venue": {
"id": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0",
"name": "Example name",
"timeZone": "Asia/Tbilisi"
},
"publicChannel": {
"id": "3db2ed63-9466-4829-81aa-e4959a2279b0",
"publicHandle": "example",
"status": "DRAFT"
},
"servicePeriod": {
"id": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8",
"name": "Example name",
"bookingMode": "INSTANT"
},
"source": {
"kind": "RESERVATION",
"entityId": "6b288694-8b6d-49cd-8007-264ca7224921",
"venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
"publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
"presentation": {
"kind": "CANONICAL",
"connectionId": null,
"resourceId": null,
"origin": null
}
},
"grantExpiresAt": "2026-12-31T18:00:00.000Z",
"serverTime": "2026-01-15T12:00:00.000Z",
"pendingAgreement": null,
"guarantee": null,
"kind": "RESERVATION",
"id": "a42073ae-5313-4ace-86d8-86fb33fde1a9",
"referenceCode": "EXAMPLE",
"revision": 1,
"status": "REQUESTED",
"partySize": 1,
"scheduledAt": "2026-01-15T12:00:00.000Z",
"endsAt": "2026-12-31T18:00:00.000Z",
"allowedActions": [
"CONFIRM"
]
}
},
{
"type": "object",
"description": "Current waitlist context, safe wait estimate and capability-scoped native lifecycle actions.",
"additionalProperties": false,
"required": [
"kind",
"id",
"referenceCode",
"revision",
"status",
"partySize",
"claimExpiresAt",
"quotedWaitMinMinutes",
"quotedWaitMaxMinutes",
"estimatedSeatAt",
"venue",
"publicChannel",
"servicePeriod",
"source",
"grantExpiresAt",
"serverTime",
"allowedActions"
],
"properties": {
"venue": {
"type": "object",
"description": "Current native venue display and scheduling context.",
"additionalProperties": false,
"required": [
"id",
"name",
"timeZone"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Owning venue UUID.",
"example": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0"
},
"name": {
"type": "string",
"description": "Current public venue name.",
"example": "Example name"
},
"timeZone": {
"type": "string",
"description": "Native venue IANA time zone.",
"example": "Asia/Tbilisi"
}
},
"example": {
"id": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0",
"name": "Example name",
"timeZone": "Asia/Tbilisi"
}
},
"publicChannel": {
"type": "object",
"description": "The owner record's native public channel, independent of the storefront presentation handle. Its current status does not replace continuation authorization.",
"additionalProperties": false,
"required": [
"id",
"publicHandle",
"status"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Native channel UUID.",
"example": "3db2ed63-9466-4829-81aa-e4959a2279b0"
},
"publicHandle": {
"type": "string",
"description": "Native reservation channel handle.",
"example": "example"
},
"status": {
"type": "string",
"description": "Current native public-channel lifecycle.",
"enum": [
"DRAFT",
"ACTIVE",
"PAUSED"
],
"example": "DRAFT"
}
},
"example": {
"id": "3db2ed63-9466-4829-81aa-e4959a2279b0",
"publicHandle": "example",
"status": "DRAFT"
}
},
"servicePeriod": {
"type": "object",
"description": "Current native service-period identity and booking mode.",
"additionalProperties": false,
"required": [
"id",
"name",
"bookingMode"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Native service-period UUID.",
"example": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8"
},
"name": {
"type": "string",
"description": "Current service-period name.",
"example": "Example name"
},
"bookingMode": {
"type": "string",
"description": "Current service-period mode; it does not rewrite an original booking receipt.",
"enum": [
"INSTANT",
"REQUEST"
],
"example": "INSTANT"
}
},
"example": {
"id": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8",
"name": "Example name",
"bookingMode": "INSTANT"
}
},
"source": {
"type": "object",
"description": "Nonsecret exact native owner tuple and the original grant presentation. These identifiers do not grant authority or permit switching origins, connections or capabilities.",
"additionalProperties": false,
"required": [
"kind",
"entityId",
"venueId",
"publicChannelId",
"presentation"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"RESERVATION",
"WAITLIST"
],
"description": "Native owner kind.",
"example": "RESERVATION"
},
"entityId": {
"type": "string",
"format": "uuid",
"description": "Exact reservation or waitlist owner UUID.",
"example": "6b288694-8b6d-49cd-8007-264ca7224921"
},
"venueId": {
"type": "string",
"format": "uuid",
"description": "Native owner venue UUID.",
"example": "0604de3a-da74-4ad5-89f6-2dfe000d5391"
},
"publicChannelId": {
"type": "string",
"format": "uuid",
"description": "Native owner channel UUID.",
"example": "9bee613d-3322-4a03-8b9f-8a6259984eee"
},
"presentation": {
"type": "object",
"description": "Immutable issuance classification. CANONICAL has null Storefront fields; STOREFRONT retains the exact original connection, attached resource and request Origin.",
"additionalProperties": false,
"required": [
"kind",
"connectionId",
"resourceId",
"origin"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"CANONICAL",
"STOREFRONT"
],
"description": "Original grant issuance context.",
"example": "CANONICAL"
},
"connectionId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Original Storefront connection UUID, or null for canonical issuance.",
"example": "2fde64d5-54a3-47d0-800f-a015f92a8878"
},
"resourceId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Original attached Storefront resource UUID, or null for canonical issuance.",
"example": "d5b5eb29-9b8d-4d6f-8f4f-6f0e58f32568"
},
"origin": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "Exact original Storefront browser Origin, or null for canonical issuance.",
"example": "https://example.test/resource"
}
},
"example": {
"kind": "CANONICAL",
"connectionId": null,
"resourceId": null,
"origin": null
}
}
},
"example": {
"kind": "RESERVATION",
"entityId": "6b288694-8b6d-49cd-8007-264ca7224921",
"venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
"publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
"presentation": {
"kind": "CANONICAL",
"connectionId": null,
"resourceId": null,
"origin": null
}
}
},
"grantExpiresAt": {
"type": "string",
"format": "date-time",
"description": "Original native manage-capability expiry; reading does not renew it.",
"example": "2026-12-31T18:00:00.000Z"
},
"serverTime": {
"type": "string",
"format": "date-time",
"description": "Server instant used for current action and claim-deadline eligibility.",
"example": "2026-01-15T12:00:00.000Z"
},
"kind": {
"type": "string",
"enum": [
"WAITLIST"
],
"description": "Native owner kind.",
"example": "WAITLIST"
},
"id": {
"type": "string",
"format": "uuid",
"description": "Capability-owned waitlist entry UUID.",
"example": "a7476fce-e842-42a4-896a-c23b0e88b420"
},
"referenceCode": {
"type": "string",
"description": "Guest-facing reference code.",
"example": "EXAMPLE"
},
"revision": {
"type": "integer",
"minimum": 1,
"description": "Current native waitlist revision.",
"example": 1
},
"status": {
"type": "string",
"enum": [
"WAITING",
"NOTIFIED",
"CLAIMED",
"SKIPPED",
"SEATED",
"CANCELED",
"NO_SHOW"
],
"description": "Current native waitlist lifecycle.",
"example": "WAITING"
},
"partySize": {
"type": "integer",
"minimum": 1,
"maximum": 99,
"description": "Current number of guests.",
"example": 1
},
"claimExpiresAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Native accepted-offer claim deadline, or null without a current window.",
"example": "2026-12-31T18:00:00.000Z"
},
"quotedWaitMinMinutes": {
"type": "integer",
"nullable": true,
"description": "Current native minimum wait estimate in minutes, or null when unknown.",
"example": 0
},
"quotedWaitMaxMinutes": {
"type": "integer",
"nullable": true,
"description": "Current native maximum wait estimate in minutes, or null when unknown.",
"example": 0
},
"estimatedSeatAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Current native estimated seating instant, or null when unknown.",
"example": "2026-01-15T12:00:00.000Z"
},
"allowedActions": {
"type": "array",
"description": "Actions currently allowed by lifecycle, grant scopes and the native claim deadline. CLAIM changes the waitlist to CLAIMED and does not create a reservation.",
"uniqueItems": true,
"maxItems": 2,
"items": {
"type": "string",
"enum": [
"CLAIM",
"CANCEL"
],
"description": "Available native guest waitlist command.",
"example": "CLAIM"
},
"example": [
"CLAIM"
]
}
},
"example": {
"venue": {
"id": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0",
"name": "Example name",
"timeZone": "Asia/Tbilisi"
},
"publicChannel": {
"id": "3db2ed63-9466-4829-81aa-e4959a2279b0",
"publicHandle": "example",
"status": "DRAFT"
},
"servicePeriod": {
"id": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8",
"name": "Example name",
"bookingMode": "INSTANT"
},
"source": {
"kind": "RESERVATION",
"entityId": "6b288694-8b6d-49cd-8007-264ca7224921",
"venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
"publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
"presentation": {
"kind": "CANONICAL",
"connectionId": null,
"resourceId": null,
"origin": null
}
},
"grantExpiresAt": "2026-12-31T18:00:00.000Z",
"serverTime": "2026-01-15T12:00:00.000Z",
"kind": "WAITLIST",
"id": "a7476fce-e842-42a4-896a-c23b0e88b420",
"referenceCode": "EXAMPLE",
"revision": 1,
"status": "WAITING",
"partySize": 1,
"claimExpiresAt": null,
"quotedWaitMinMinutes": null,
"quotedWaitMaxMinutes": null,
"estimatedSeatAt": null,
"allowedActions": [
"CLAIM"
]
}
}
],
"example": {
"venue": {
"id": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0",
"name": "Example name",
"timeZone": "Asia/Tbilisi"
},
"publicChannel": {
"id": "3db2ed63-9466-4829-81aa-e4959a2279b0",
"publicHandle": "example",
"status": "DRAFT"
},
"servicePeriod": {
"id": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8",
"name": "Example name",
"bookingMode": "INSTANT"
},
"source": {
"kind": "RESERVATION",
"entityId": "6b288694-8b6d-49cd-8007-264ca7224921",
"venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
"publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
"presentation": {
"kind": "CANONICAL",
"connectionId": null,
"resourceId": null,
"origin": null
}
},
"grantExpiresAt": "2026-12-31T18:00:00.000Z",
"serverTime": "2026-01-15T12:00:00.000Z",
"pendingAgreement": null,
"guarantee": null,
"kind": "RESERVATION",
"id": "a42073ae-5313-4ace-86d8-86fb33fde1a9",
"referenceCode": "EXAMPLE",
"revision": 1,
"status": "REQUESTED",
"partySize": 1,
"scheduledAt": "2026-01-15T12:00:00.000Z",
"endsAt": "2026-12-31T18:00:00.000Z",
"allowedActions": [
"CONFIRM"
]
}
},
{
"type": "object",
"additionalProperties": false,
"nullable": true,
"enum": [
null
],
"description": "No current authorized management view is available.",
"example": null
}
],
"example": {
"venue": {
"id": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0",
"name": "Example name",
"timeZone": "Asia/Tbilisi"
},
"publicChannel": {
"id": "3db2ed63-9466-4829-81aa-e4959a2279b0",
"publicHandle": "example",
"status": "DRAFT"
},
"servicePeriod": {
"id": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8",
"name": "Example name",
"bookingMode": "INSTANT"
},
"source": {
"kind": "RESERVATION",
"entityId": "6b288694-8b6d-49cd-8007-264ca7224921",
"venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
"publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
"presentation": {
"kind": "CANONICAL",
"connectionId": null,
"resourceId": null,
"origin": null
}
},
"grantExpiresAt": "2026-12-31T18:00:00.000Z",
"serverTime": "2026-01-15T12:00:00.000Z",
"pendingAgreement": null,
"guarantee": null,
"kind": "RESERVATION",
"id": "a42073ae-5313-4ace-86d8-86fb33fde1a9",
"referenceCode": "EXAMPLE",
"revision": 1,
"status": "REQUESTED",
"partySize": 1,
"scheduledAt": "2026-01-15T12:00:00.000Z",
"endsAt": "2026-12-31T18:00:00.000Z",
"allowedActions": [
"CONFIRM"
]
}
}
},
"example": {
"kind": "WAITLIST",
"entityId": "6b288694-8b6d-49cd-8007-264ca7224921",
"referenceCode": "EXAMPLE",
"revision": 1,
"status": "WAITING",
"eventIds": [
"6825b43e-93d6-4f3b-8171-c1661099fae8"
],
"manageToken": "synthetic-example-credential",
"manageTokenExpiresAt": "2026-12-31T18:00:00.000Z",
"currentState": "AVAILABLE",
"current": {
"venue": {
"id": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0",
"name": "Example name",
"timeZone": "Asia/Tbilisi"
},
"publicChannel": {
"id": "3db2ed63-9466-4829-81aa-e4959a2279b0",
"publicHandle": "example",
"status": "DRAFT"
},
"servicePeriod": {
"id": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8",
"name": "Example name",
"bookingMode": "INSTANT"
},
"source": {
"kind": "RESERVATION",
"entityId": "6b288694-8b6d-49cd-8007-264ca7224921",
"venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
"publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
"presentation": {
"kind": "CANONICAL",
"connectionId": null,
"resourceId": null,
"origin": null
}
},
"grantExpiresAt": "2026-12-31T18:00:00.000Z",
"serverTime": "2026-01-15T12:00:00.000Z",
"pendingAgreement": null,
"guarantee": null,
"kind": "RESERVATION",
"id": "a42073ae-5313-4ace-86d8-86fb33fde1a9",
"referenceCode": "EXAMPLE",
"revision": 1,
"status": "REQUESTED",
"partySize": 1,
"scheduledAt": "2026-01-15T12:00:00.000Z",
"endsAt": "2026-12-31T18:00:00.000Z",
"allowedActions": [
"CONFIRM"
]
}
}
}
],
"example": {
"kind": "RESERVATION",
"entityId": "6b288694-8b6d-49cd-8007-264ca7224921",
"referenceCode": "EXAMPLE",
"revision": 1,
"status": "REQUESTED",
"eventIds": [
"6825b43e-93d6-4f3b-8171-c1661099fae8"
],
"manageToken": "synthetic-example-credential",
"manageTokenExpiresAt": "2026-12-31T18:00:00.000Z",
"currentState": "AVAILABLE",
"current": {
"venue": {
"id": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0",
"name": "Example name",
"timeZone": "Asia/Tbilisi"
},
"publicChannel": {
"id": "3db2ed63-9466-4829-81aa-e4959a2279b0",
"publicHandle": "example",
"status": "DRAFT"
},
"servicePeriod": {
"id": "9c73cff6-cdc4-44f1-80c7-f0668753d7a8",
"name": "Example name",
"bookingMode": "INSTANT"
},
"source": {
"kind": "RESERVATION",
"entityId": "6b288694-8b6d-49cd-8007-264ca7224921",
"venueId": "0604de3a-da74-4ad5-89f6-2dfe000d5391",
"publicChannelId": "9bee613d-3322-4a03-8b9f-8a6259984eee",
"presentation": {
"kind": "CANONICAL",
"connectionId": null,
"resourceId": null,
"origin": null
}
},
"grantExpiresAt": "2026-12-31T18:00:00.000Z",
"serverTime": "2026-01-15T12:00:00.000Z",
"pendingAgreement": null,
"guarantee": null,
"kind": "RESERVATION",
"id": "a42073ae-5313-4ace-86d8-86fb33fde1a9",
"referenceCode": "EXAMPLE",
"revision": 1,
"status": "REQUESTED",
"partySize": 1,
"scheduledAt": "2026-01-15T12:00:00.000Z",
"endsAt": "2026-12-31T18:00:00.000Z",
"allowedActions": [
"CONFIRM"
]
}
}
}TranslatedErrorDto
Stable error envelope emitted by the global HTTP exception boundary. Domain-specific machine data, when present, is nested under details.
statusCodeRequiredHTTP status code repeated from the response.
integerFull definition
{ "type": "integer", "description": "HTTP status code repeated from the response.", "example": 400 }errorRequiredTranslation key for the HTTP category, such as errors:http.conflict. The specific cause is identified by code and translationKey.
stringFull definition
{ "type": "string", "description": "Translation key for the HTTP category, such as errors:http.conflict. The specific cause is identified by code and translationKey.", "example": "errors.request.invalid" }codeRequiredStable machine-readable domain code, or an HTTP_* fallback when no domain code is provided. Branch on this field and the HTTP status; localized wording never controls retries or business decisions.
stringFull definition
{ "type": "string", "example": "HTTP_BAD_REQUEST", "description": "Stable machine-readable domain code, or an HTTP_* fallback when no domain code is provided. Branch on this field and the HTTP status; localized wording never controls retries or business decisions." }messageRequiredTranslation key, identical to translationKey. The API does not return localized display text. Resolve the key and translationValues in the consuming application.
stringFull definition
{ "type": "string", "example": "errors:http.badRequest", "description": "Translation key, identical to translationKey. The API does not return localized display text. Resolve the key and translationValues in the consuming application." }translationKeyRequiredCanonical translation key, identical to message. Status-specific errors:http.* keys cover unspecified failures. Public keys and EN/RU explanations are listed in Developers; unknown keys require a localized client fallback.
stringFull definition
{ "type": "string", "example": "errors:http.badRequest", "description": "Canonical translation key, identical to message. Status-specific errors:http.* keys cover unspecified failures. Public keys and EN/RU explanations are listed in Developers; unknown keys require a localized client fallback." }translationValuesOptionalOptional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.
objectFull definition
{ "type": "object", "additionalProperties": { "oneOf": [ { "type": "string", "example": "example" }, { "type": "number", "example": 0 }, { "type": "boolean", "example": true } ], "example": "example" }, "description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.", "example": { "exampleKey": "example" } }validationErrorsOptionalField validation failures with translation keys and stable validator codes. Submitted values and raw validator text are not included.
arrayFull definition
{ "description": "Field validation failures with translation keys and stable validator codes. Submitted values and raw validator text are not included.", "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorDto" }, "example": [ { "field": "email", "translationKey": "validation:isEmail", "code": "isEmail", "message": "validation:isEmail" } ] }detailsOptionalOptional domain-specific blocker or validation details
oneOfFull definition
{ "description": "Optional domain-specific blocker or validation details", "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" }, "example": [ "example" ] }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "example": { "exampleKey": "example" } } ], "example": [ "example" ] }
Full definition
{
"type": "object",
"properties": {
"statusCode": {
"type": "integer",
"description": "HTTP status code repeated from the response.",
"example": 400
},
"error": {
"type": "string",
"description": "Translation key for the HTTP category, such as errors:http.conflict. The specific cause is identified by code and translationKey.",
"example": "errors.request.invalid"
},
"code": {
"type": "string",
"example": "HTTP_BAD_REQUEST",
"description": "Stable machine-readable domain code, or an HTTP_* fallback when no domain code is provided. Branch on this field and the HTTP status; localized wording never controls retries or business decisions."
},
"message": {
"type": "string",
"example": "errors:http.badRequest",
"description": "Translation key, identical to translationKey. The API does not return localized display text. Resolve the key and translationValues in the consuming application."
},
"translationKey": {
"type": "string",
"example": "errors:http.badRequest",
"description": "Canonical translation key, identical to message. Status-specific errors:http.* keys cover unspecified failures. Public keys and EN/RU explanations are listed in Developers; unknown keys require a localized client fallback."
},
"translationValues": {
"type": "object",
"additionalProperties": {
"oneOf": [
{
"type": "string",
"example": "example"
},
{
"type": "number",
"example": 0
},
{
"type": "boolean",
"example": true
}
],
"example": "example"
},
"description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.",
"example": {
"exampleKey": "example"
}
},
"validationErrors": {
"description": "Field validation failures with translation keys and stable validator codes. Submitted values and raw validator text are not included.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ValidationErrorDto"
},
"example": [
{
"field": "email",
"translationKey": "validation:isEmail",
"code": "isEmail",
"message": "validation:isEmail"
}
]
},
"details": {
"description": "Optional domain-specific blocker or validation details",
"oneOf": [
{
"type": "array",
"items": {
"$ref": "#/components/schemas/JsonValue"
},
"example": [
"example"
]
},
{
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/JsonValue"
},
"example": {
"exampleKey": "example"
}
}
],
"example": [
"example"
]
}
},
"required": [
"statusCode",
"error",
"code",
"message",
"translationKey"
],
"description": "Stable error envelope emitted by the global HTTP exception boundary. Domain-specific machine data, when present, is nested under details.",
"example": {
"statusCode": 400,
"error": "errors:http.badRequest",
"code": "HTTP_BAD_REQUEST",
"message": "errors:http.badRequest",
"translationKey": "errors:http.badRequest"
}
}ValidationErrorDto
Field validation failure with a field path, stable validator code and a translation key. Human-readable text belongs to the consuming application.
fieldRequiredPublic field path. Nested properties and array indices are separated by dots.
stringFull definition
{ "type": "string", "example": "email", "description": "Public field path. Nested properties and array indices are separated by dots." }translationKeyRequiredTranslation key for this validator, identical to message. Resolve it using a client dictionary; see the public Developers error catalog.
stringFull definition
{ "type": "string", "example": "validation:isEmail", "description": "Translation key for this validator, identical to message. Resolve it using a client dictionary; see the public Developers error catalog." }codeRequiredStable validator identifier for this field failure. Custom validators may define additional identifiers.
stringFull definition
{ "type": "string", "example": "isEmail", "description": "Stable validator identifier for this field failure. Custom validators may define additional identifiers." }messageRequiredTranslation key describing this field validation failure, identical to translationKey. Submitted values and validator prose are not included.
stringFull definition
{ "type": "string", "example": "validation:isEmail", "description": "Translation key describing this field validation failure, identical to translationKey. Submitted values and validator prose are not included." }translationValuesOptionalOptional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.
objectFull definition
{ "type": "object", "additionalProperties": { "oneOf": [ { "type": "string", "example": "example" }, { "type": "number", "example": 0 }, { "type": "boolean", "example": true } ], "example": "example" }, "description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.", "example": { "exampleKey": "example" } }
Full definition
{
"type": "object",
"properties": {
"field": {
"type": "string",
"example": "email",
"description": "Public field path. Nested properties and array indices are separated by dots."
},
"translationKey": {
"type": "string",
"example": "validation:isEmail",
"description": "Translation key for this validator, identical to message. Resolve it using a client dictionary; see the public Developers error catalog."
},
"code": {
"type": "string",
"example": "isEmail",
"description": "Stable validator identifier for this field failure. Custom validators may define additional identifiers."
},
"message": {
"type": "string",
"example": "validation:isEmail",
"description": "Translation key describing this field validation failure, identical to translationKey. Submitted values and validator prose are not included."
},
"translationValues": {
"type": "object",
"additionalProperties": {
"oneOf": [
{
"type": "string",
"example": "example"
},
{
"type": "number",
"example": 0
},
{
"type": "boolean",
"example": true
}
],
"example": "example"
},
"description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.",
"example": {
"exampleKey": "example"
}
}
},
"required": [
"field",
"translationKey",
"code",
"message"
],
"description": "Field validation failure with a field path, stable validator code and a translation key. Human-readable text belongs to the consuming application.",
"example": {
"field": "email",
"translationKey": "validation:isEmail",
"code": "isEmail",
"message": "validation:isEmail"
}
}JsonValue
Recursively JSON-safe value used only where the owning contract intentionally allows free-form structured data.
Full definition
{
"oneOf": [
{
"type": "string",
"nullable": true,
"example": "example"
},
{
"type": "number",
"example": 0
},
{
"type": "boolean",
"example": true
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/JsonValue"
},
"example": [
"example"
]
},
{
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/JsonValue"
},
"example": {
"exampleKey": "example"
}
}
],
"description": "Recursively JSON-safe value used only where the owning contract intentionally allows free-form structured data.",
"example": "example"
}IdempotencyConflictError
Idempotency key is already in progress or was reused with a different payload.
Full definition
{
"example": {
"statusCode": 409,
"error": "errors:http.conflict",
"code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
"message": "errors:idempotency.inProgress",
"translationKey": "errors:idempotency.inProgress"
},
"allOf": [
{
"$ref": "#/components/schemas/TranslatedErrorDto"
},
{
"type": "object",
"required": [
"code"
],
"properties": {
"statusCode": {
"type": "integer",
"enum": [
409
],
"description": "HTTP 409 conflict status.",
"example": 409
},
"code": {
"type": "string",
"enum": [
"IDEMPOTENCY_REQUEST_NOT_READY",
"IDEMPOTENCY_KEY_PAYLOAD_MISMATCH",
"IDEMPOTENCY_REQUEST_IN_PROGRESS",
"IDEMPOTENCY_SCOPE_INCOMPLETE"
],
"description": "Allowed code for idempotency conflict error: IDEMPOTENCY_REQUEST_NOT_READY, IDEMPOTENCY_KEY_PAYLOAD_MISMATCH, IDEMPOTENCY_REQUEST_IN_PROGRESS, IDEMPOTENCY_SCOPE_INCOMPLETE.",
"example": "IDEMPOTENCY_REQUEST_NOT_READY"
}
},
"example": {
"code": "IDEMPOTENCY_REQUEST_NOT_READY"
}
}
],
"description": "Idempotency key is already in progress or was reused with a different payload."
}