Skip to content
HallifyDevelopersSearch documentation
Open Hallify
Sections

Reservations & waitlist

Get exact native guarantee terms for a selected booking slot

GET/public/reservations/{publicHandle}/guarantee-offer

Calculates the native amount, currency and absolute guarantee, cancellation and no-show deadlines for the exact slot, party and current service-period revision. This read creates no reservation, hold or charge. The guest accepts its digest when creating an intent; stale terms are rejected without repricing.

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.

Connection guide

Parameters

publicHandlePath · Required

Published native reservation channel handle.

string
Full definition
{
  "type": "string",
  "example": "example"
}
servicePeriodIdQuery · Required

Native selected service period.

string · uuid
Full definition
{
  "format": "uuid",
  "type": "string",
  "example": "9b6163a8-afea-4877-818b-8e2ae28a2845"
}
scheduledAtQuery · Required

Exact native availability slot instant.

string · date-time
Full definition
{
  "format": "date-time",
  "type": "string",
  "example": "2026-01-15T12:00:00.000Z"
}
partySizeQuery · Required

Number of guests used to select the guarantee policy and calculate any per-guest amount.

integer
Full definition
{
  "minimum": 1,
  "maximum": 99,
  "type": "integer",
  "example": 1
}
originHeader · Optional

Actual 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 · uri
Full definition
{
  "type": "string",
  "format": "uri",
  "maxLength": 2048,
  "example": "https://example.test/resource"
}
x-hallify-connection-idHeader · Optional

Optional nonsecret connection locator for initial public channel resolution. It never grants authority or replaces an issued grant snapshot.

string · uuid
Full definition
{
  "type": "string",
  "format": "uuid",
  "minLength": 36,
  "maxLength": 36,
  "example": "9b6163a8-afea-4877-818b-8e2ae28a2845"
}

Responses

200Exact native guarantee offer, or an explicit NONE result with null terms and digest.
ReservationPublicGuaranteeOfferResultDto
Full definition
{
  "$ref": "#/components/schemas/ReservationPublicGuaranteeOfferResultDto"
}
Example response · 200 · application/json
{
  "required": true,
  "terms": null,
  "termsHash": null
}

Schemas

ReservationPublicGuaranteeOfferResultDto

Server-computed guarantee proposal with its terms and digest. NONE or a party below the configured threshold requires no guarantee.

requiredRequired

Whether this exact slot and party require a guarantee.

boolean
Full definition
{
  "type": "boolean",
  "description": "Whether this exact slot and party require a guarantee.",
  "example": true
}
termsRequired

Exact accepted terms, or null when no guarantee applies.

object · null
Full definition
{
  "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"
  }
}
termsHashRequired

Canonical accepted terms digest, or null when no guarantee applies.

string · null
Full definition
{
  "type": "string",
  "pattern": "^[0-9a-f]{64}$",
  "nullable": true,
  "description": "Canonical accepted terms digest, or null when no guarantee applies.",
  "example": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
}
Full definition
{
  "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
  }
}

Hallify uses essential cookies and optional analytics.

Essential cookies keep sign-in, locale, and theme preferences working. Analytics is off until you choose to allow it.