Authentication
Authorization: Bearer <HALLIFY_PREORDER_MANAGE_TOKEN>Guest-owned capability for managing a preorder.
Parameters
originHeader · OptionalActual browser Origin. Required for drafts and manage grants with classified CANONICAL or STOREFRONT issuance and must match their recorded issuance and current authority. Widget continuations retain their original frame Origin and parent binding; the draft or manage capability authorizes continuation without a fresh widget bootstrap proof. Existing records with NULL issuance metadata retain their legacy channel-origin rules.
stringFull definition
{ "type": "string", "maxLength": 2048, "example": "example" }
Responses
200Returns the guest-visible preorder projection and current revision.
PreorderPublicManageResultDto
Full definition
{
"$ref": "#/components/schemas/PreorderPublicManageResultDto"
}Example response · 200 · application/json
{
"fulfillmentId": "0a81282f-ea3b-40be-8ef7-4ad39e32ea88",
"orderId": "f3127edf-ce4f-4da7-8be5-81b962024e6c",
"revision": 1,
"status": "DRAFT",
"serviceMode": "DINE_IN",
"partySize": 1,
"scheduledFor": "2026-01-15T12:00:00.000Z",
"venue": {
"id": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0",
"name": "Example name",
"timeZone": "Asia/Tbilisi"
},
"channel": {
"publicHandle": "example",
"salesChannelId": "ff0fa725-ba44-4e7a-82bb-a15650e0a0cc",
"termsVersion": "example",
"privacyVersion": "example"
},
"contact": null,
"deposit": {
"status": "NOT_REQUIRED",
"requiredAmount": "1.00",
"paidAmount": "1.00",
"dueAt": null
},
"delivery": {
"zoneId": null,
"feeAmount": "1.00"
},
"items": [
{
"clientLineId": "example-id",
"id": "9fbff223-7cc1-4311-8644-0bd59ff2477a",
"menuVersionId": null,
"salesChannelId": null,
"menuItemId": null,
"menuVariantId": null,
"name": "Example name",
"rootItemStructureKind": "SINGLE_ITEM",
"itemStructureExecutionMode": "DIRECT_ITEM",
"effectiveExecutionMode": "DIRECT_ITEM",
"quantity": 1,
"billableQuantity": 1,
"unitPrice": "1.00",
"totalAmount": "1.00",
"specialRequest": null,
"serviceFlags": [
"example"
],
"allergenCodes": [
"EXAMPLE"
],
"kitchenStatus": "PENDING",
"modifiers": [
{
"optionId": null,
"groupName": "Example name",
"optionName": "Example name",
"priceDelta": "1.00",
"allergenCodes": [
"EXAMPLE"
]
}
],
"components": [
{
"id": "cada95b5-09b4-4bdd-8379-2e6df6ee6198",
"operationalRole": "GUEST_SELECTION",
"name": "Example name",
"menuVariantId": null,
"quantity": 1,
"componentGroupId": "example-id",
"componentGroupName": "Example name",
"componentChoiceId": "example-id",
"componentQuantity": 1,
"componentUpcharge": "1.00",
"componentIsDefault": true,
"kitchenStatus": "PENDING",
"modifiers": [
{
"optionId": null,
"groupName": "Example name",
"optionName": "Example name",
"priceDelta": "1.00",
"allergenCodes": [
"EXAMPLE"
]
}
]
}
]
}
],
"allowedActions": {
"cancel": true,
"reschedule": true,
"changeRequest": true
},
"generatedAt": "2026-01-15T12:00:00.000Z"
}401Rejects a missing, malformed, expired, revoked, or invalid preorderManageToken credential at the owning domain boundary.
TranslatedErrorDto
Full definition
{
"$ref": "#/components/schemas/TranslatedErrorDto"
}Example response · 401 · application/json
{
"statusCode": 401,
"error": "errors:http.unauthorized",
"code": "HTTP_UNAUTHORIZED",
"message": "errors:http.unauthorized",
"translationKey": "errors:http.unauthorized"
}Schemas
PreorderPublicManageResultDto
Returns the guest-visible preorder projection and current revision.
paymentActorReferenceOptionalNonsecret stable payment UI partition for this native actor and fulfillment. Present only for a verified initial public EXCHANGE and original CREATE acceptance lineage. This is neither a credential nor payment authority; missing or unprovable lineage returns null.
string · nullFull definition
{ "type": "string", "nullable": true, "pattern": "^[a-f0-9]{64}$", "minLength": 64, "maxLength": 64, "description": "Nonsecret stable payment UI partition for this native actor and fulfillment. Present only for a verified initial public EXCHANGE and original CREATE acceptance lineage. This is neither a credential nor payment authority; missing or unprovable lineage returns null.", "example": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" }fulfillmentIdRequiredHallify UUID identifying fulfillment associated with preorder public manage.
string · uuidFull definition
{ "type": "string", "format": "uuid", "description": "Hallify UUID identifying fulfillment associated with preorder public manage.", "example": "0a81282f-ea3b-40be-8ef7-4ad39e32ea88" }orderIdRequiredHallify UUID identifying order associated with preorder public manage.
string · uuidFull definition
{ "type": "string", "format": "uuid", "description": "Hallify UUID identifying order associated with preorder public manage.", "example": "f3127edf-ce4f-4da7-8be5-81b962024e6c" }revisionRequiredMonotonic optimistic-concurrency revision for preorder public manage. Accepted values enforce minimum 1.
integerFull definition
{ "type": "integer", "minimum": 1, "description": "Monotonic optimistic-concurrency revision for preorder public manage. Accepted values enforce minimum 1.", "example": 1 }statusRequiredCurrent lifecycle status of preorder public manage; allowed values are DRAFT, HELD, CONFIRMED, IN_PREPARATION, READY_FOR_HANDOFF, OUT_FOR_DELIVERY, COMPLETED, CANCELED, EXPIRED.
stringFull definition
{ "type": "string", "enum": [ "DRAFT", "HELD", "CONFIRMED", "IN_PREPARATION", "READY_FOR_HANDOFF", "OUT_FOR_DELIVERY", "COMPLETED", "CANCELED", "EXPIRED" ], "description": "Current lifecycle status of preorder public manage; allowed values are DRAFT, HELD, CONFIRMED, IN_PREPARATION, READY_FOR_HANDOFF, OUT_FOR_DELIVERY, COMPLETED, CANCELED, EXPIRED.", "example": "DRAFT" }serviceModeRequiredAllowed service mode for preorder public manage: DINE_IN, PICKUP, DELIVERY, CATERING.
stringFull definition
{ "type": "string", "enum": [ "DINE_IN", "PICKUP", "DELIVERY", "CATERING" ], "description": "Allowed service mode for preorder public manage: DINE_IN, PICKUP, DELIVERY, CATERING.", "example": "DINE_IN" }partySizeRequiredWhole-number party size recorded for preorder public manage. Accepted values enforce minimum 1.
integerFull definition
{ "type": "integer", "minimum": 1, "description": "Whole-number party size recorded for preorder public manage. Accepted values enforce minimum 1.", "example": 1 }scheduledForRequiredRFC 3339 timestamp for scheduled for; offsets represent the same absolute instant.
string · date-timeFull definition
{ "type": "string", "format": "date-time", "description": "RFC 3339 timestamp for scheduled for; offsets represent the same absolute instant.", "example": "2026-01-15T12:00:00.000Z" }timingModeOptionalExplicit customer timing intent bound to the retained native draft, quote or order. Omitted for legacy scheduled records.
stringFull definition
{ "type": "string", "enum": [ "ASAP", "SCHEDULED" ], "description": "Explicit customer timing intent bound to the retained native draft, quote or order. Omitted for legacy scheduled records.", "example": "ASAP" }venueRequiredVenue details embedded in preorder public manage containing id, name, and time zone.
objectFull definition
{ "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Hallify UUID identifying preorder public manage venue.", "example": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0" }, "name": { "type": "string", "description": "Human-readable name for preorder public manage venue.", "example": "Example name" }, "timeZone": { "type": "string", "description": "IANA time-zone identifier used to interpret venue-local dates and times for preorder public manage venue.", "example": "Asia/Tbilisi" } }, "required": [ "id", "name", "timeZone" ], "description": "Venue details embedded in preorder public manage containing id, name, and time zone.", "example": { "id": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0", "name": "Example name", "timeZone": "Asia/Tbilisi" } }channelRequiredChannel details embedded in preorder public manage containing public handle, sales channel id, terms version, and privacy version.
objectFull definition
{ "type": "object", "properties": { "publicHandle": { "type": "string", "description": "Public handle for preorder public manage channel.", "example": "example" }, "salesChannelId": { "type": "string", "format": "uuid", "description": "Hallify UUID identifying sales channel associated with preorder public manage channel.", "example": "ff0fa725-ba44-4e7a-82bb-a15650e0a0cc" }, "termsVersion": { "type": "string", "description": "Terms version for preorder public manage channel.", "example": "example" }, "privacyVersion": { "type": "string", "description": "Privacy version for preorder public manage channel.", "example": "example" } }, "required": [ "publicHandle", "salesChannelId", "termsVersion", "privacyVersion" ], "description": "Channel details embedded in preorder public manage containing public handle, sales channel id, terms version, and privacy version.", "example": { "publicHandle": "example", "salesChannelId": "ff0fa725-ba44-4e7a-82bb-a15650e0a0cc", "termsVersion": "example", "privacyVersion": "example" } }contactRequiredContact details embedded in preorder public manage containing contact name, contact phone, contact email, address line1, address line2, and city. Null means no value is recorded for this representation.
object · nullFull definition
{ "type": "object", "nullable": true, "properties": { "contactName": { "type": "string", "description": "Human-readable contact name for preorder public manage contact.", "example": "Example name" }, "contactPhone": { "type": "string", "nullable": true, "description": "Telephone number recorded for contact phone in preorder public manage contact. Null means no value is recorded for this representation.", "example": "+995555000000" }, "contactEmail": { "type": "string", "nullable": true, "description": "Email address recorded for contact email in preorder public manage contact. Null means no value is recorded for this representation.", "format": "email", "example": "user@example.test" }, "addressLine1": { "type": "string", "nullable": true, "description": "Primary street-address line for preorder public manage contact. Null means no value is recorded for this representation.", "example": "example" }, "addressLine2": { "type": "string", "nullable": true, "description": "Optional secondary address details such as unit, floor, or building for preorder public manage contact. Null means no value is recorded for this representation.", "example": "example" }, "city": { "type": "string", "nullable": true, "description": "City or locality recorded for the address represented by preorder public manage contact. Null means no value is recorded for this representation.", "example": "example" }, "region": { "type": "string", "nullable": true, "description": "Region, state, or administrative subdivision recorded for preorder public manage contact. Null means no value is recorded for this representation.", "example": "example" }, "postalCode": { "type": "string", "nullable": true, "description": "Stable postal code used to classify or address preorder public manage contact. Null means no value is recorded for this representation.", "example": "EXAMPLE" }, "countryCode": { "type": "string", "nullable": true, "description": "Stable country code used to classify or address preorder public manage contact. Null means no value is recorded for this representation.", "example": "GE" }, "administrativeDivisionId": { "type": "string", "format": "uuid", "nullable": true, "description": "Hallify UUID identifying administrative division associated with preorder public manage contact. Null means no value is recorded for this representation.", "example": "c8efbc76-614d-4a79-8f15-db6d48283d46" }, "localityId": { "type": "string", "format": "uuid", "nullable": true, "description": "Hallify UUID identifying locality associated with preorder public manage contact. Null means no value is recorded for this representation.", "example": "1bfa5864-39f3-4647-8093-42aea5d9d046" }, "postalCodeId": { "type": "string", "format": "uuid", "nullable": true, "description": "Hallify UUID identifying postal code associated with preorder public manage contact. Null means no value is recorded for this representation.", "example": "7424d59b-d459-4e7b-8cbc-7f5222274f26" }, "latitude": { "type": "number", "nullable": true, "description": "Fraction-capable numeric latitude recorded for preorder public manage contact. Null means no value is recorded for this representation.", "example": 41.7151 }, "longitude": { "type": "number", "nullable": true, "description": "Fraction-capable numeric longitude recorded for preorder public manage contact. Null means no value is recorded for this representation.", "example": 44.8271 }, "coordinateSource": { "type": "string", "nullable": true, "enum": [ "STAFF", "EXTERNAL_CLIENT", "GEOREFERENCE_CENTROID", null ], "description": "Allowed coordinate source for preorder public manage contact: STAFF, EXTERNAL_CLIENT, GEOREFERENCE_CENTROID. Null means no value is recorded for this representation.", "example": "STAFF" }, "coordinateAccuracy": { "type": "integer", "minimum": 0, "maximum": 10, "nullable": true, "description": "Whole-number coordinate accuracy recorded for preorder public manage contact. Accepted values enforce minimum 0 and maximum 10. Null means no value is recorded for this representation.", "example": 0 }, "deliveryInstructions": { "type": "string", "nullable": true, "description": "Delivery instructions for preorder public manage contact. Null means no value is recorded for this representation.", "example": "example" } }, "required": [ "contactName", "contactPhone", "contactEmail", "addressLine1", "addressLine2", "city", "region", "postalCode", "countryCode", "administrativeDivisionId", "localityId", "postalCodeId", "latitude", "longitude", "coordinateSource", "coordinateAccuracy", "deliveryInstructions" ], "description": "Contact details embedded in preorder public manage containing contact name, contact phone, contact email, address line1, address line2, and city. Null means no value is recorded for this representation.", "example": { "contactName": "Example name", "contactPhone": null, "contactEmail": null, "addressLine1": null, "addressLine2": null, "city": null, "region": null, "postalCode": null, "countryCode": null, "administrativeDivisionId": null, "localityId": null, "postalCodeId": null, "latitude": null, "longitude": null, "coordinateSource": null, "coordinateAccuracy": null, "deliveryInstructions": null } }depositRequiredDeposit details embedded in preorder public manage containing status, required amount, paid amount, and due at.
objectFull definition
{ "type": "object", "properties": { "status": { "type": "string", "enum": [ "NOT_REQUIRED", "REQUIRED", "PARTIALLY_PAID", "PAID", "OVERDUE" ], "description": "Current lifecycle status of preorder public manage deposit; allowed values are NOT_REQUIRED, REQUIRED, PARTIALLY_PAID, PAID, OVERDUE.", "example": "NOT_REQUIRED" }, "requiredAmount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Decimal monetary required amount serialized as a string in the currency identified by the financial document or policy that embeds preorder public manage deposit; zero is a recorded amount, not absence.", "example": "1.00" }, "paidAmount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Decimal monetary paid amount serialized as a string in the currency identified by the financial document or policy that embeds preorder public manage deposit; zero is a recorded amount, not absence.", "example": "1.00" }, "dueAt": { "type": "string", "format": "date-time", "nullable": true, "description": "RFC 3339 timestamp for due at; offsets represent the same absolute instant. Null means no value is recorded for this representation.", "example": "2026-12-31T18:00:00.000Z" } }, "required": [ "status", "requiredAmount", "paidAmount", "dueAt" ], "description": "Deposit details embedded in preorder public manage containing status, required amount, paid amount, and due at.", "example": { "status": "NOT_REQUIRED", "requiredAmount": "1.00", "paidAmount": "1.00", "dueAt": null } }deliveryRequiredDelivery details embedded in preorder public manage containing zone id and fee amount.
objectFull definition
{ "type": "object", "properties": { "zoneId": { "type": "string", "format": "uuid", "nullable": true, "description": "Hallify UUID identifying zone associated with preorder public manage delivery. Null means no value is recorded for this representation.", "example": "f6864a47-6a06-4534-8879-1bfd5a7ed49b" }, "feeAmount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Decimal monetary fee amount serialized as a string in the currency identified by the financial document or policy that embeds preorder public manage delivery; zero is a recorded amount, not absence.", "example": "1.00" }, "method": { "type": "string", "enum": [ "SELF", "UBER_DIRECT", "WOLT_DRIVE" ], "description": "Immutable delivery method from the current accepted customer quote, including before courier dispatch. Omitted for legacy orders without an accepted quote pair, whose delivery method is SELF.", "example": "SELF" }, "tracking": { "type": "object", "nullable": true, "description": "Verified courier progress for the current accepted customer quote pair, or null before any shipment exists. It is independent of the meal and deposit lifecycle.", "properties": { "shipmentId": { "type": "string", "format": "uuid", "description": "Shipment belonging to the current accepted quote pair.", "example": "107f0aae-41ba-4259-84aa-b07de763733f" }, "revision": { "type": "integer", "minimum": 1, "description": "Monotonic courier projection revision.", "example": 1 }, "provider": { "type": "string", "enum": [ "UBER_DIRECT", "WOLT_DRIVE" ], "description": "Delivery provider retained in the accepted delivery demand.", "example": "UBER_DIRECT" }, "state": { "type": "string", "enum": [ "PREPARED", "DISPATCHING", "UNKNOWN", "CONFIRMED", "PICKUP_STARTED", "PICKED_UP", "IN_TRANSIT", "DELIVERED", "CANCELED", "NOT_DELIVERED", "RETURNING", "RETURNED", "REJECTED", "RECONCILIATION_REQUIRED" ], "description": "Verified courier lifecycle, including explicit uncertainty and reconciliation states.", "example": "PREPARED" }, "trackingUrl": { "type": "string", "nullable": true, "format": "uri", "maxLength": 2048, "description": "Verified HTTPS tracking URL, or null when unavailable or withheld by the owning privacy boundary.", "example": "https://example.test/resource" }, "pickupEta": { "type": "string", "format": "date-time", "nullable": true, "description": "Latest provider pickup estimate as a UTC instant, or null.", "example": "2026-01-15T12:00:00.000Z" }, "dropoffEtaMin": { "type": "string", "format": "date-time", "nullable": true, "description": "Earliest provider dropoff estimate as a UTC instant, or null.", "example": "2026-01-15T12:00:00.000Z" }, "dropoffEtaMax": { "type": "string", "format": "date-time", "nullable": true, "description": "Latest provider dropoff estimate as a UTC instant, or null.", "example": "2026-01-15T12:00:00.000Z" }, "requiresAttention": { "type": "boolean", "description": "Courier evidence or native application requires staff attention; it grants no payment or meal-cancellation authority.", "example": true } }, "required": [ "shipmentId", "revision", "provider", "state", "trackingUrl", "pickupEta", "dropoffEtaMin", "dropoffEtaMax", "requiresAttention" ], "example": { "shipmentId": "107f0aae-41ba-4259-84aa-b07de763733f", "revision": 1, "provider": "UBER_DIRECT", "state": "PREPARED", "trackingUrl": null, "pickupEta": null, "dropoffEtaMin": null, "dropoffEtaMax": null, "requiresAttention": true } } }, "required": [ "zoneId", "feeAmount" ], "description": "Delivery details embedded in preorder public manage containing zone id and fee amount.", "example": { "zoneId": null, "feeAmount": "1.00" } }itemsRequiredItems returned in the preorder public manage collection.
arrayFull definition
{ "type": "array", "items": { "type": "object", "properties": { "clientLineId": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Opaque identifier for client line associated with preorder public manage item; clients must not assume UUID syntax. Accepted values enforce minimum length 1 and maximum length 80.", "example": "example-id" }, "id": { "type": "string", "format": "uuid", "description": "Hallify UUID identifying preorder public manage item.", "example": "9fbff223-7cc1-4311-8644-0bd59ff2477a" }, "menuVersionId": { "type": "string", "format": "uuid", "nullable": true, "description": "Hallify UUID identifying menu version associated with preorder public manage item. Null means no value is recorded for this representation.", "example": "490ccfcb-caa6-472e-836a-a8416e8cee92" }, "salesChannelId": { "type": "string", "format": "uuid", "nullable": true, "description": "Hallify UUID identifying sales channel associated with preorder public manage item. Null means no value is recorded for this representation.", "example": "ff0fa725-ba44-4e7a-82bb-a15650e0a0cc" }, "menuItemId": { "type": "string", "format": "uuid", "nullable": true, "description": "Hallify UUID identifying menu item associated with preorder public manage item. Null means no value is recorded for this representation.", "example": "16ee6f36-c0cb-4311-85e8-2d2b3edea0fd" }, "menuVariantId": { "type": "string", "format": "uuid", "nullable": true, "description": "Hallify UUID identifying menu variant associated with preorder public manage item. Null means no value is recorded for this representation.", "example": "94389946-e5d8-4fba-8358-e3a9c8a04b11" }, "name": { "type": "string", "description": "Human-readable name for preorder public manage item.", "example": "Example name" }, "rootItemStructureKind": { "type": "string", "enum": [ "SINGLE_ITEM", "SIZED_PORTIONED", "COMBO_MEAL_DEAL", "FIXED_PRICE_COURSE_MENU", "BUILD_YOUR_OWN", "BUNDLE_KIT", "MEASURED", "OPEN_PRICE", "CATERING_PREORDER", "CUSTOM" ], "description": "Allowed root item structure kind for preorder public manage item: SINGLE_ITEM, SIZED_PORTIONED, COMBO_MEAL_DEAL, FIXED_PRICE_COURSE_MENU, BUILD_YOUR_OWN, BUNDLE_KIT, MEASURED, OPEN_PRICE, CATERING_PREORDER, CUSTOM.", "example": "SINGLE_ITEM" }, "itemStructureExecutionMode": { "type": "string", "enum": [ "DIRECT_ITEM", "SELLABLE_VERSION", "COMPONENT_GROUPS", "COURSE_SEQUENCE", "GUIDED_STAGES", "BUNDLE_SECTIONS", "MEASURED_QUANTITY", "OPEN_PRICE_ENTRY", "PREORDER_PACKAGE", "CUSTOM_POLICY" ], "description": "Allowed item structure execution mode for preorder public manage item: DIRECT_ITEM, SELLABLE_VERSION, COMPONENT_GROUPS, COURSE_SEQUENCE, GUIDED_STAGES, BUNDLE_SECTIONS, MEASURED_QUANTITY, OPEN_PRICE_ENTRY, PREORDER_PACKAGE, CUSTOM_POLICY.", "example": "DIRECT_ITEM" }, "effectiveExecutionMode": { "type": "string", "enum": [ "DIRECT_ITEM", "SELLABLE_VERSION", "COMPONENT_GROUPS", "COURSE_SEQUENCE", "GUIDED_STAGES", "BUNDLE_SECTIONS", "MEASURED_QUANTITY", "OPEN_PRICE_ENTRY", "PREORDER_PACKAGE", "CUSTOM_POLICY" ], "description": "Allowed effective execution mode for preorder public manage item: DIRECT_ITEM, SELLABLE_VERSION, COMPONENT_GROUPS, COURSE_SEQUENCE, GUIDED_STAGES, BUNDLE_SECTIONS, MEASURED_QUANTITY, OPEN_PRICE_ENTRY, PREORDER_PACKAGE, CUSTOM_POLICY.", "example": "DIRECT_ITEM" }, "quantity": { "type": "integer", "minimum": 0, "description": "Whole-number quantity measured in the unit established by the item or line that embeds preorder public manage item. Accepted values enforce minimum 0.", "example": 1 }, "billableQuantity": { "type": "integer", "minimum": 0, "description": "Whole-number billable quantity measured in the unit established by the item or line that embeds preorder public manage item. Accepted values enforce minimum 0.", "example": 1 }, "unitPrice": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Decimal monetary unit price serialized as a string in the currency identified by the financial document or policy that embeds preorder public manage item; zero is a recorded amount, not absence.", "example": "1.00" }, "totalAmount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Decimal monetary total amount serialized as a string in the currency identified by the financial document or policy that embeds preorder public manage item; zero is a recorded amount, not absence.", "example": "1.00" }, "specialRequest": { "type": "string", "nullable": true, "description": "Special request for preorder public manage item. Null means no value is recorded for this representation.", "example": "example" }, "serviceFlags": { "type": "array", "items": { "type": "string", "example": "example" }, "description": "Service flags values included as service flags in preorder public manage item.", "example": [ "example" ] }, "allergenCodes": { "type": "array", "items": { "type": "string", "example": "EXAMPLE" }, "description": "Allergen codes values included as allergen codes in preorder public manage item.", "example": [ "EXAMPLE" ] }, "kitchenStatus": { "type": "string", "example": "PENDING", "description": "Current lifecycle status of preorder public manage item." }, "modifiers": { "type": "array", "items": { "type": "object", "properties": { "optionId": { "type": "string", "format": "uuid", "nullable": true, "description": "Hallify UUID identifying option associated with preorder public manage item modifiers item. Null means no value is recorded for this representation.", "example": "c3152e09-81b4-4a57-8893-2eca47cc44e8" }, "groupName": { "type": "string", "description": "Human-readable group name for preorder public manage item modifiers item.", "example": "Example name" }, "optionName": { "type": "string", "description": "Human-readable option name for preorder public manage item modifiers item.", "example": "Example name" }, "priceDelta": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Decimal monetary price delta serialized as a string in the currency identified by the financial document or policy that embeds preorder public manage item modifiers item; zero is a recorded amount, not absence.", "example": "1.00" }, "allergenCodes": { "type": "array", "items": { "type": "string", "example": "EXAMPLE" }, "description": "Allergen codes values included as allergen codes in preorder public manage item modifiers item.", "example": [ "EXAMPLE" ] } }, "required": [ "optionId", "groupName", "optionName", "priceDelta", "allergenCodes" ], "example": { "optionId": null, "groupName": "Example name", "optionName": "Example name", "priceDelta": "1.00", "allergenCodes": [ "EXAMPLE" ] } }, "description": "Modifiers included as modifiers in preorder public manage item.", "example": [ { "optionId": null, "groupName": "Example name", "optionName": "Example name", "priceDelta": "1.00", "allergenCodes": [ "EXAMPLE" ] } ] }, "components": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Hallify UUID identifying preorder public manage item components item.", "example": "cada95b5-09b4-4bdd-8379-2e6df6ee6198" }, "operationalRole": { "type": "string", "enum": [ "GUEST_SELECTION", "ASSEMBLY" ], "description": "Allowed operational role for preorder public manage item components item: GUEST_SELECTION, ASSEMBLY.", "example": "GUEST_SELECTION" }, "name": { "type": "string", "description": "Human-readable name for preorder public manage item components item.", "example": "Example name" }, "menuVariantId": { "type": "string", "format": "uuid", "nullable": true, "description": "Hallify UUID identifying menu variant associated with preorder public manage item components item. Null means no value is recorded for this representation.", "example": "94389946-e5d8-4fba-8358-e3a9c8a04b11" }, "quantity": { "type": "integer", "minimum": 0, "description": "Whole-number quantity measured in the unit established by the item or line that embeds preorder public manage item components item. Accepted values enforce minimum 0.", "example": 1 }, "componentGroupId": { "type": "string", "description": "Opaque identifier for component group associated with preorder public manage item components item; clients must not assume UUID syntax.", "example": "example-id" }, "componentGroupName": { "type": "string", "description": "Human-readable component group name for preorder public manage item components item.", "example": "Example name" }, "componentChoiceId": { "type": "string", "description": "Opaque identifier for component choice associated with preorder public manage item components item; clients must not assume UUID syntax.", "example": "example-id" }, "componentQuantity": { "type": "number", "minimum": 0, "description": "Fraction-capable component quantity measured in the unit established by the item or line that embeds preorder public manage item components item. Accepted values enforce minimum 0.", "example": 1 }, "componentUpcharge": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Decimal monetary component upcharge serialized as a string in the currency identified by the financial document or policy that embeds preorder public manage item components item; zero is a recorded amount, not absence.", "example": "1.00" }, "componentIsDefault": { "type": "boolean", "description": "Whether this component is selected by default when a new item configuration is created.", "example": true }, "kitchenStatus": { "type": "string", "example": "PENDING", "description": "Current lifecycle status of preorder public manage item components item." }, "modifiers": { "type": "array", "items": { "type": "object", "properties": { "optionId": { "type": "string", "format": "uuid", "nullable": true, "description": "Hallify UUID identifying option associated with preorder public manage item components item modifiers item. Null means no value is recorded for this representation.", "example": "c3152e09-81b4-4a57-8893-2eca47cc44e8" }, "groupName": { "type": "string", "description": "Human-readable group name for preorder public manage item components item modifiers item.", "example": "Example name" }, "optionName": { "type": "string", "description": "Human-readable option name for preorder public manage item components item modifiers item.", "example": "Example name" }, "priceDelta": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Decimal monetary price delta serialized as a string in the currency identified by the financial document or policy that embeds preorder public manage item components item modifiers item; zero is a recorded amount, not absence.", "example": "1.00" }, "allergenCodes": { "type": "array", "items": { "type": "string", "example": "EXAMPLE" }, "description": "Allergen codes values included as allergen codes in preorder public manage item components item modifiers item.", "example": [ "EXAMPLE" ] } }, "required": [ "optionId", "groupName", "optionName", "priceDelta", "allergenCodes" ], "example": { "optionId": null, "groupName": "Example name", "optionName": "Example name", "priceDelta": "1.00", "allergenCodes": [ "EXAMPLE" ] } }, "description": "Modifiers included as modifiers in preorder public manage item components item.", "example": [ { "optionId": null, "groupName": "Example name", "optionName": "Example name", "priceDelta": "1.00", "allergenCodes": [ "EXAMPLE" ] } ] } }, "required": [ "id", "operationalRole", "name", "menuVariantId", "quantity", "componentGroupId", "componentGroupName", "componentChoiceId", "componentQuantity", "componentUpcharge", "componentIsDefault", "kitchenStatus", "modifiers" ], "example": { "id": "cada95b5-09b4-4bdd-8379-2e6df6ee6198", "operationalRole": "GUEST_SELECTION", "name": "Example name", "menuVariantId": null, "quantity": 1, "componentGroupId": "example-id", "componentGroupName": "Example name", "componentChoiceId": "example-id", "componentQuantity": 1, "componentUpcharge": "1.00", "componentIsDefault": true, "kitchenStatus": "PENDING", "modifiers": [ { "optionId": null, "groupName": "Example name", "optionName": "Example name", "priceDelta": "1.00", "allergenCodes": [ "EXAMPLE" ] } ] } }, "description": "Components included as components in preorder public manage item.", "example": [ { "id": "cada95b5-09b4-4bdd-8379-2e6df6ee6198", "operationalRole": "GUEST_SELECTION", "name": "Example name", "menuVariantId": null, "quantity": 1, "componentGroupId": "example-id", "componentGroupName": "Example name", "componentChoiceId": "example-id", "componentQuantity": 1, "componentUpcharge": "1.00", "componentIsDefault": true, "kitchenStatus": "PENDING", "modifiers": [ { "optionId": null, "groupName": "Example name", "optionName": "Example name", "priceDelta": "1.00", "allergenCodes": [ "EXAMPLE" ] } ] } ] } }, "required": [ "clientLineId", "id", "menuVersionId", "salesChannelId", "menuItemId", "menuVariantId", "name", "rootItemStructureKind", "itemStructureExecutionMode", "effectiveExecutionMode", "quantity", "billableQuantity", "unitPrice", "totalAmount", "specialRequest", "serviceFlags", "allergenCodes", "kitchenStatus", "modifiers", "components" ], "example": { "clientLineId": "example-id", "id": "9fbff223-7cc1-4311-8644-0bd59ff2477a", "menuVersionId": null, "salesChannelId": null, "menuItemId": null, "menuVariantId": null, "name": "Example name", "rootItemStructureKind": "SINGLE_ITEM", "itemStructureExecutionMode": "DIRECT_ITEM", "effectiveExecutionMode": "DIRECT_ITEM", "quantity": 1, "billableQuantity": 1, "unitPrice": "1.00", "totalAmount": "1.00", "specialRequest": null, "serviceFlags": [ "example" ], "allergenCodes": [ "EXAMPLE" ], "kitchenStatus": "PENDING", "modifiers": [ { "optionId": null, "groupName": "Example name", "optionName": "Example name", "priceDelta": "1.00", "allergenCodes": [ "EXAMPLE" ] } ], "components": [ { "id": "cada95b5-09b4-4bdd-8379-2e6df6ee6198", "operationalRole": "GUEST_SELECTION", "name": "Example name", "menuVariantId": null, "quantity": 1, "componentGroupId": "example-id", "componentGroupName": "Example name", "componentChoiceId": "example-id", "componentQuantity": 1, "componentUpcharge": "1.00", "componentIsDefault": true, "kitchenStatus": "PENDING", "modifiers": [ { "optionId": null, "groupName": "Example name", "optionName": "Example name", "priceDelta": "1.00", "allergenCodes": [ "EXAMPLE" ] } ] } ] } }, "description": "Items returned in the preorder public manage collection.", "example": [ { "clientLineId": "example-id", "id": "9fbff223-7cc1-4311-8644-0bd59ff2477a", "menuVersionId": null, "salesChannelId": null, "menuItemId": null, "menuVariantId": null, "name": "Example name", "rootItemStructureKind": "SINGLE_ITEM", "itemStructureExecutionMode": "DIRECT_ITEM", "effectiveExecutionMode": "DIRECT_ITEM", "quantity": 1, "billableQuantity": 1, "unitPrice": "1.00", "totalAmount": "1.00", "specialRequest": null, "serviceFlags": [ "example" ], "allergenCodes": [ "EXAMPLE" ], "kitchenStatus": "PENDING", "modifiers": [ { "optionId": null, "groupName": "Example name", "optionName": "Example name", "priceDelta": "1.00", "allergenCodes": [ "EXAMPLE" ] } ], "components": [ { "id": "cada95b5-09b4-4bdd-8379-2e6df6ee6198", "operationalRole": "GUEST_SELECTION", "name": "Example name", "menuVariantId": null, "quantity": 1, "componentGroupId": "example-id", "componentGroupName": "Example name", "componentChoiceId": "example-id", "componentQuantity": 1, "componentUpcharge": "1.00", "componentIsDefault": true, "kitchenStatus": "PENDING", "modifiers": [ { "optionId": null, "groupName": "Example name", "optionName": "Example name", "priceDelta": "1.00", "allergenCodes": [ "EXAMPLE" ] } ] } ] } ] }allowedActionsRequiredAllowed actions details embedded in preorder public manage containing cancel, reschedule, and change request.
objectFull definition
{ "type": "object", "properties": { "cancel": { "type": "boolean", "description": "Whether the caller may cancel; false means the action is unavailable in the current lifecycle and permission context.", "example": true }, "reschedule": { "type": "boolean", "description": "Whether the caller may reschedule; false means the action is unavailable in the current lifecycle and permission context.", "example": true }, "changeRequest": { "type": "boolean", "description": "Whether the caller may change request; false means the action is unavailable in the current lifecycle and permission context.", "example": true } }, "required": [ "cancel", "reschedule", "changeRequest" ], "description": "Allowed actions details embedded in preorder public manage containing cancel, reschedule, and change request.", "example": { "cancel": true, "reschedule": true, "changeRequest": true } }generatedAtRequiredRFC 3339 timestamp for generated at; offsets represent the same absolute instant.
string · date-timeFull definition
{ "type": "string", "format": "date-time", "description": "RFC 3339 timestamp for generated at; offsets represent the same absolute instant.", "example": "2026-01-15T12:00:00.000Z" }
Full definition
{
"type": "object",
"properties": {
"paymentActorReference": {
"type": "string",
"nullable": true,
"pattern": "^[a-f0-9]{64}$",
"minLength": 64,
"maxLength": 64,
"description": "Nonsecret stable payment UI partition for this native actor and fulfillment. Present only for a verified initial public EXCHANGE and original CREATE acceptance lineage. This is neither a credential nor payment authority; missing or unprovable lineage returns null.",
"example": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
},
"fulfillmentId": {
"type": "string",
"format": "uuid",
"description": "Hallify UUID identifying fulfillment associated with preorder public manage.",
"example": "0a81282f-ea3b-40be-8ef7-4ad39e32ea88"
},
"orderId": {
"type": "string",
"format": "uuid",
"description": "Hallify UUID identifying order associated with preorder public manage.",
"example": "f3127edf-ce4f-4da7-8be5-81b962024e6c"
},
"revision": {
"type": "integer",
"minimum": 1,
"description": "Monotonic optimistic-concurrency revision for preorder public manage. Accepted values enforce minimum 1.",
"example": 1
},
"status": {
"type": "string",
"enum": [
"DRAFT",
"HELD",
"CONFIRMED",
"IN_PREPARATION",
"READY_FOR_HANDOFF",
"OUT_FOR_DELIVERY",
"COMPLETED",
"CANCELED",
"EXPIRED"
],
"description": "Current lifecycle status of preorder public manage; allowed values are DRAFT, HELD, CONFIRMED, IN_PREPARATION, READY_FOR_HANDOFF, OUT_FOR_DELIVERY, COMPLETED, CANCELED, EXPIRED.",
"example": "DRAFT"
},
"serviceMode": {
"type": "string",
"enum": [
"DINE_IN",
"PICKUP",
"DELIVERY",
"CATERING"
],
"description": "Allowed service mode for preorder public manage: DINE_IN, PICKUP, DELIVERY, CATERING.",
"example": "DINE_IN"
},
"partySize": {
"type": "integer",
"minimum": 1,
"description": "Whole-number party size recorded for preorder public manage. Accepted values enforce minimum 1.",
"example": 1
},
"scheduledFor": {
"type": "string",
"format": "date-time",
"description": "RFC 3339 timestamp for scheduled for; offsets represent the same absolute instant.",
"example": "2026-01-15T12:00:00.000Z"
},
"timingMode": {
"type": "string",
"enum": [
"ASAP",
"SCHEDULED"
],
"description": "Explicit customer timing intent bound to the retained native draft, quote or order. Omitted for legacy scheduled records.",
"example": "ASAP"
},
"venue": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Hallify UUID identifying preorder public manage venue.",
"example": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0"
},
"name": {
"type": "string",
"description": "Human-readable name for preorder public manage venue.",
"example": "Example name"
},
"timeZone": {
"type": "string",
"description": "IANA time-zone identifier used to interpret venue-local dates and times for preorder public manage venue.",
"example": "Asia/Tbilisi"
}
},
"required": [
"id",
"name",
"timeZone"
],
"description": "Venue details embedded in preorder public manage containing id, name, and time zone.",
"example": {
"id": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0",
"name": "Example name",
"timeZone": "Asia/Tbilisi"
}
},
"channel": {
"type": "object",
"properties": {
"publicHandle": {
"type": "string",
"description": "Public handle for preorder public manage channel.",
"example": "example"
},
"salesChannelId": {
"type": "string",
"format": "uuid",
"description": "Hallify UUID identifying sales channel associated with preorder public manage channel.",
"example": "ff0fa725-ba44-4e7a-82bb-a15650e0a0cc"
},
"termsVersion": {
"type": "string",
"description": "Terms version for preorder public manage channel.",
"example": "example"
},
"privacyVersion": {
"type": "string",
"description": "Privacy version for preorder public manage channel.",
"example": "example"
}
},
"required": [
"publicHandle",
"salesChannelId",
"termsVersion",
"privacyVersion"
],
"description": "Channel details embedded in preorder public manage containing public handle, sales channel id, terms version, and privacy version.",
"example": {
"publicHandle": "example",
"salesChannelId": "ff0fa725-ba44-4e7a-82bb-a15650e0a0cc",
"termsVersion": "example",
"privacyVersion": "example"
}
},
"contact": {
"type": "object",
"nullable": true,
"properties": {
"contactName": {
"type": "string",
"description": "Human-readable contact name for preorder public manage contact.",
"example": "Example name"
},
"contactPhone": {
"type": "string",
"nullable": true,
"description": "Telephone number recorded for contact phone in preorder public manage contact. Null means no value is recorded for this representation.",
"example": "+995555000000"
},
"contactEmail": {
"type": "string",
"nullable": true,
"description": "Email address recorded for contact email in preorder public manage contact. Null means no value is recorded for this representation.",
"format": "email",
"example": "user@example.test"
},
"addressLine1": {
"type": "string",
"nullable": true,
"description": "Primary street-address line for preorder public manage contact. Null means no value is recorded for this representation.",
"example": "example"
},
"addressLine2": {
"type": "string",
"nullable": true,
"description": "Optional secondary address details such as unit, floor, or building for preorder public manage contact. Null means no value is recorded for this representation.",
"example": "example"
},
"city": {
"type": "string",
"nullable": true,
"description": "City or locality recorded for the address represented by preorder public manage contact. Null means no value is recorded for this representation.",
"example": "example"
},
"region": {
"type": "string",
"nullable": true,
"description": "Region, state, or administrative subdivision recorded for preorder public manage contact. Null means no value is recorded for this representation.",
"example": "example"
},
"postalCode": {
"type": "string",
"nullable": true,
"description": "Stable postal code used to classify or address preorder public manage contact. Null means no value is recorded for this representation.",
"example": "EXAMPLE"
},
"countryCode": {
"type": "string",
"nullable": true,
"description": "Stable country code used to classify or address preorder public manage contact. Null means no value is recorded for this representation.",
"example": "GE"
},
"administrativeDivisionId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Hallify UUID identifying administrative division associated with preorder public manage contact. Null means no value is recorded for this representation.",
"example": "c8efbc76-614d-4a79-8f15-db6d48283d46"
},
"localityId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Hallify UUID identifying locality associated with preorder public manage contact. Null means no value is recorded for this representation.",
"example": "1bfa5864-39f3-4647-8093-42aea5d9d046"
},
"postalCodeId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Hallify UUID identifying postal code associated with preorder public manage contact. Null means no value is recorded for this representation.",
"example": "7424d59b-d459-4e7b-8cbc-7f5222274f26"
},
"latitude": {
"type": "number",
"nullable": true,
"description": "Fraction-capable numeric latitude recorded for preorder public manage contact. Null means no value is recorded for this representation.",
"example": 41.7151
},
"longitude": {
"type": "number",
"nullable": true,
"description": "Fraction-capable numeric longitude recorded for preorder public manage contact. Null means no value is recorded for this representation.",
"example": 44.8271
},
"coordinateSource": {
"type": "string",
"nullable": true,
"enum": [
"STAFF",
"EXTERNAL_CLIENT",
"GEOREFERENCE_CENTROID",
null
],
"description": "Allowed coordinate source for preorder public manage contact: STAFF, EXTERNAL_CLIENT, GEOREFERENCE_CENTROID. Null means no value is recorded for this representation.",
"example": "STAFF"
},
"coordinateAccuracy": {
"type": "integer",
"minimum": 0,
"maximum": 10,
"nullable": true,
"description": "Whole-number coordinate accuracy recorded for preorder public manage contact. Accepted values enforce minimum 0 and maximum 10. Null means no value is recorded for this representation.",
"example": 0
},
"deliveryInstructions": {
"type": "string",
"nullable": true,
"description": "Delivery instructions for preorder public manage contact. Null means no value is recorded for this representation.",
"example": "example"
}
},
"required": [
"contactName",
"contactPhone",
"contactEmail",
"addressLine1",
"addressLine2",
"city",
"region",
"postalCode",
"countryCode",
"administrativeDivisionId",
"localityId",
"postalCodeId",
"latitude",
"longitude",
"coordinateSource",
"coordinateAccuracy",
"deliveryInstructions"
],
"description": "Contact details embedded in preorder public manage containing contact name, contact phone, contact email, address line1, address line2, and city. Null means no value is recorded for this representation.",
"example": {
"contactName": "Example name",
"contactPhone": null,
"contactEmail": null,
"addressLine1": null,
"addressLine2": null,
"city": null,
"region": null,
"postalCode": null,
"countryCode": null,
"administrativeDivisionId": null,
"localityId": null,
"postalCodeId": null,
"latitude": null,
"longitude": null,
"coordinateSource": null,
"coordinateAccuracy": null,
"deliveryInstructions": null
}
},
"deposit": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"NOT_REQUIRED",
"REQUIRED",
"PARTIALLY_PAID",
"PAID",
"OVERDUE"
],
"description": "Current lifecycle status of preorder public manage deposit; allowed values are NOT_REQUIRED, REQUIRED, PARTIALLY_PAID, PAID, OVERDUE.",
"example": "NOT_REQUIRED"
},
"requiredAmount": {
"type": "string",
"pattern": "^\\d+\\.\\d{2}$",
"description": "Decimal monetary required amount serialized as a string in the currency identified by the financial document or policy that embeds preorder public manage deposit; zero is a recorded amount, not absence.",
"example": "1.00"
},
"paidAmount": {
"type": "string",
"pattern": "^\\d+\\.\\d{2}$",
"description": "Decimal monetary paid amount serialized as a string in the currency identified by the financial document or policy that embeds preorder public manage deposit; zero is a recorded amount, not absence.",
"example": "1.00"
},
"dueAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "RFC 3339 timestamp for due at; offsets represent the same absolute instant. Null means no value is recorded for this representation.",
"example": "2026-12-31T18:00:00.000Z"
}
},
"required": [
"status",
"requiredAmount",
"paidAmount",
"dueAt"
],
"description": "Deposit details embedded in preorder public manage containing status, required amount, paid amount, and due at.",
"example": {
"status": "NOT_REQUIRED",
"requiredAmount": "1.00",
"paidAmount": "1.00",
"dueAt": null
}
},
"delivery": {
"type": "object",
"properties": {
"zoneId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Hallify UUID identifying zone associated with preorder public manage delivery. Null means no value is recorded for this representation.",
"example": "f6864a47-6a06-4534-8879-1bfd5a7ed49b"
},
"feeAmount": {
"type": "string",
"pattern": "^\\d+\\.\\d{2}$",
"description": "Decimal monetary fee amount serialized as a string in the currency identified by the financial document or policy that embeds preorder public manage delivery; zero is a recorded amount, not absence.",
"example": "1.00"
},
"method": {
"type": "string",
"enum": [
"SELF",
"UBER_DIRECT",
"WOLT_DRIVE"
],
"description": "Immutable delivery method from the current accepted customer quote, including before courier dispatch. Omitted for legacy orders without an accepted quote pair, whose delivery method is SELF.",
"example": "SELF"
},
"tracking": {
"type": "object",
"nullable": true,
"description": "Verified courier progress for the current accepted customer quote pair, or null before any shipment exists. It is independent of the meal and deposit lifecycle.",
"properties": {
"shipmentId": {
"type": "string",
"format": "uuid",
"description": "Shipment belonging to the current accepted quote pair.",
"example": "107f0aae-41ba-4259-84aa-b07de763733f"
},
"revision": {
"type": "integer",
"minimum": 1,
"description": "Monotonic courier projection revision.",
"example": 1
},
"provider": {
"type": "string",
"enum": [
"UBER_DIRECT",
"WOLT_DRIVE"
],
"description": "Delivery provider retained in the accepted delivery demand.",
"example": "UBER_DIRECT"
},
"state": {
"type": "string",
"enum": [
"PREPARED",
"DISPATCHING",
"UNKNOWN",
"CONFIRMED",
"PICKUP_STARTED",
"PICKED_UP",
"IN_TRANSIT",
"DELIVERED",
"CANCELED",
"NOT_DELIVERED",
"RETURNING",
"RETURNED",
"REJECTED",
"RECONCILIATION_REQUIRED"
],
"description": "Verified courier lifecycle, including explicit uncertainty and reconciliation states.",
"example": "PREPARED"
},
"trackingUrl": {
"type": "string",
"nullable": true,
"format": "uri",
"maxLength": 2048,
"description": "Verified HTTPS tracking URL, or null when unavailable or withheld by the owning privacy boundary.",
"example": "https://example.test/resource"
},
"pickupEta": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Latest provider pickup estimate as a UTC instant, or null.",
"example": "2026-01-15T12:00:00.000Z"
},
"dropoffEtaMin": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Earliest provider dropoff estimate as a UTC instant, or null.",
"example": "2026-01-15T12:00:00.000Z"
},
"dropoffEtaMax": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Latest provider dropoff estimate as a UTC instant, or null.",
"example": "2026-01-15T12:00:00.000Z"
},
"requiresAttention": {
"type": "boolean",
"description": "Courier evidence or native application requires staff attention; it grants no payment or meal-cancellation authority.",
"example": true
}
},
"required": [
"shipmentId",
"revision",
"provider",
"state",
"trackingUrl",
"pickupEta",
"dropoffEtaMin",
"dropoffEtaMax",
"requiresAttention"
],
"example": {
"shipmentId": "107f0aae-41ba-4259-84aa-b07de763733f",
"revision": 1,
"provider": "UBER_DIRECT",
"state": "PREPARED",
"trackingUrl": null,
"pickupEta": null,
"dropoffEtaMin": null,
"dropoffEtaMax": null,
"requiresAttention": true
}
}
},
"required": [
"zoneId",
"feeAmount"
],
"description": "Delivery details embedded in preorder public manage containing zone id and fee amount.",
"example": {
"zoneId": null,
"feeAmount": "1.00"
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"clientLineId": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"description": "Opaque identifier for client line associated with preorder public manage item; clients must not assume UUID syntax. Accepted values enforce minimum length 1 and maximum length 80.",
"example": "example-id"
},
"id": {
"type": "string",
"format": "uuid",
"description": "Hallify UUID identifying preorder public manage item.",
"example": "9fbff223-7cc1-4311-8644-0bd59ff2477a"
},
"menuVersionId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Hallify UUID identifying menu version associated with preorder public manage item. Null means no value is recorded for this representation.",
"example": "490ccfcb-caa6-472e-836a-a8416e8cee92"
},
"salesChannelId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Hallify UUID identifying sales channel associated with preorder public manage item. Null means no value is recorded for this representation.",
"example": "ff0fa725-ba44-4e7a-82bb-a15650e0a0cc"
},
"menuItemId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Hallify UUID identifying menu item associated with preorder public manage item. Null means no value is recorded for this representation.",
"example": "16ee6f36-c0cb-4311-85e8-2d2b3edea0fd"
},
"menuVariantId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Hallify UUID identifying menu variant associated with preorder public manage item. Null means no value is recorded for this representation.",
"example": "94389946-e5d8-4fba-8358-e3a9c8a04b11"
},
"name": {
"type": "string",
"description": "Human-readable name for preorder public manage item.",
"example": "Example name"
},
"rootItemStructureKind": {
"type": "string",
"enum": [
"SINGLE_ITEM",
"SIZED_PORTIONED",
"COMBO_MEAL_DEAL",
"FIXED_PRICE_COURSE_MENU",
"BUILD_YOUR_OWN",
"BUNDLE_KIT",
"MEASURED",
"OPEN_PRICE",
"CATERING_PREORDER",
"CUSTOM"
],
"description": "Allowed root item structure kind for preorder public manage item: SINGLE_ITEM, SIZED_PORTIONED, COMBO_MEAL_DEAL, FIXED_PRICE_COURSE_MENU, BUILD_YOUR_OWN, BUNDLE_KIT, MEASURED, OPEN_PRICE, CATERING_PREORDER, CUSTOM.",
"example": "SINGLE_ITEM"
},
"itemStructureExecutionMode": {
"type": "string",
"enum": [
"DIRECT_ITEM",
"SELLABLE_VERSION",
"COMPONENT_GROUPS",
"COURSE_SEQUENCE",
"GUIDED_STAGES",
"BUNDLE_SECTIONS",
"MEASURED_QUANTITY",
"OPEN_PRICE_ENTRY",
"PREORDER_PACKAGE",
"CUSTOM_POLICY"
],
"description": "Allowed item structure execution mode for preorder public manage item: DIRECT_ITEM, SELLABLE_VERSION, COMPONENT_GROUPS, COURSE_SEQUENCE, GUIDED_STAGES, BUNDLE_SECTIONS, MEASURED_QUANTITY, OPEN_PRICE_ENTRY, PREORDER_PACKAGE, CUSTOM_POLICY.",
"example": "DIRECT_ITEM"
},
"effectiveExecutionMode": {
"type": "string",
"enum": [
"DIRECT_ITEM",
"SELLABLE_VERSION",
"COMPONENT_GROUPS",
"COURSE_SEQUENCE",
"GUIDED_STAGES",
"BUNDLE_SECTIONS",
"MEASURED_QUANTITY",
"OPEN_PRICE_ENTRY",
"PREORDER_PACKAGE",
"CUSTOM_POLICY"
],
"description": "Allowed effective execution mode for preorder public manage item: DIRECT_ITEM, SELLABLE_VERSION, COMPONENT_GROUPS, COURSE_SEQUENCE, GUIDED_STAGES, BUNDLE_SECTIONS, MEASURED_QUANTITY, OPEN_PRICE_ENTRY, PREORDER_PACKAGE, CUSTOM_POLICY.",
"example": "DIRECT_ITEM"
},
"quantity": {
"type": "integer",
"minimum": 0,
"description": "Whole-number quantity measured in the unit established by the item or line that embeds preorder public manage item. Accepted values enforce minimum 0.",
"example": 1
},
"billableQuantity": {
"type": "integer",
"minimum": 0,
"description": "Whole-number billable quantity measured in the unit established by the item or line that embeds preorder public manage item. Accepted values enforce minimum 0.",
"example": 1
},
"unitPrice": {
"type": "string",
"pattern": "^\\d+\\.\\d{2}$",
"description": "Decimal monetary unit price serialized as a string in the currency identified by the financial document or policy that embeds preorder public manage item; zero is a recorded amount, not absence.",
"example": "1.00"
},
"totalAmount": {
"type": "string",
"pattern": "^\\d+\\.\\d{2}$",
"description": "Decimal monetary total amount serialized as a string in the currency identified by the financial document or policy that embeds preorder public manage item; zero is a recorded amount, not absence.",
"example": "1.00"
},
"specialRequest": {
"type": "string",
"nullable": true,
"description": "Special request for preorder public manage item. Null means no value is recorded for this representation.",
"example": "example"
},
"serviceFlags": {
"type": "array",
"items": {
"type": "string",
"example": "example"
},
"description": "Service flags values included as service flags in preorder public manage item.",
"example": [
"example"
]
},
"allergenCodes": {
"type": "array",
"items": {
"type": "string",
"example": "EXAMPLE"
},
"description": "Allergen codes values included as allergen codes in preorder public manage item.",
"example": [
"EXAMPLE"
]
},
"kitchenStatus": {
"type": "string",
"example": "PENDING",
"description": "Current lifecycle status of preorder public manage item."
},
"modifiers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"optionId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Hallify UUID identifying option associated with preorder public manage item modifiers item. Null means no value is recorded for this representation.",
"example": "c3152e09-81b4-4a57-8893-2eca47cc44e8"
},
"groupName": {
"type": "string",
"description": "Human-readable group name for preorder public manage item modifiers item.",
"example": "Example name"
},
"optionName": {
"type": "string",
"description": "Human-readable option name for preorder public manage item modifiers item.",
"example": "Example name"
},
"priceDelta": {
"type": "string",
"pattern": "^\\d+\\.\\d{2}$",
"description": "Decimal monetary price delta serialized as a string in the currency identified by the financial document or policy that embeds preorder public manage item modifiers item; zero is a recorded amount, not absence.",
"example": "1.00"
},
"allergenCodes": {
"type": "array",
"items": {
"type": "string",
"example": "EXAMPLE"
},
"description": "Allergen codes values included as allergen codes in preorder public manage item modifiers item.",
"example": [
"EXAMPLE"
]
}
},
"required": [
"optionId",
"groupName",
"optionName",
"priceDelta",
"allergenCodes"
],
"example": {
"optionId": null,
"groupName": "Example name",
"optionName": "Example name",
"priceDelta": "1.00",
"allergenCodes": [
"EXAMPLE"
]
}
},
"description": "Modifiers included as modifiers in preorder public manage item.",
"example": [
{
"optionId": null,
"groupName": "Example name",
"optionName": "Example name",
"priceDelta": "1.00",
"allergenCodes": [
"EXAMPLE"
]
}
]
},
"components": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Hallify UUID identifying preorder public manage item components item.",
"example": "cada95b5-09b4-4bdd-8379-2e6df6ee6198"
},
"operationalRole": {
"type": "string",
"enum": [
"GUEST_SELECTION",
"ASSEMBLY"
],
"description": "Allowed operational role for preorder public manage item components item: GUEST_SELECTION, ASSEMBLY.",
"example": "GUEST_SELECTION"
},
"name": {
"type": "string",
"description": "Human-readable name for preorder public manage item components item.",
"example": "Example name"
},
"menuVariantId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Hallify UUID identifying menu variant associated with preorder public manage item components item. Null means no value is recorded for this representation.",
"example": "94389946-e5d8-4fba-8358-e3a9c8a04b11"
},
"quantity": {
"type": "integer",
"minimum": 0,
"description": "Whole-number quantity measured in the unit established by the item or line that embeds preorder public manage item components item. Accepted values enforce minimum 0.",
"example": 1
},
"componentGroupId": {
"type": "string",
"description": "Opaque identifier for component group associated with preorder public manage item components item; clients must not assume UUID syntax.",
"example": "example-id"
},
"componentGroupName": {
"type": "string",
"description": "Human-readable component group name for preorder public manage item components item.",
"example": "Example name"
},
"componentChoiceId": {
"type": "string",
"description": "Opaque identifier for component choice associated with preorder public manage item components item; clients must not assume UUID syntax.",
"example": "example-id"
},
"componentQuantity": {
"type": "number",
"minimum": 0,
"description": "Fraction-capable component quantity measured in the unit established by the item or line that embeds preorder public manage item components item. Accepted values enforce minimum 0.",
"example": 1
},
"componentUpcharge": {
"type": "string",
"pattern": "^\\d+\\.\\d{2}$",
"description": "Decimal monetary component upcharge serialized as a string in the currency identified by the financial document or policy that embeds preorder public manage item components item; zero is a recorded amount, not absence.",
"example": "1.00"
},
"componentIsDefault": {
"type": "boolean",
"description": "Whether this component is selected by default when a new item configuration is created.",
"example": true
},
"kitchenStatus": {
"type": "string",
"example": "PENDING",
"description": "Current lifecycle status of preorder public manage item components item."
},
"modifiers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"optionId": {
"type": "string",
"format": "uuid",
"nullable": true,
"description": "Hallify UUID identifying option associated with preorder public manage item components item modifiers item. Null means no value is recorded for this representation.",
"example": "c3152e09-81b4-4a57-8893-2eca47cc44e8"
},
"groupName": {
"type": "string",
"description": "Human-readable group name for preorder public manage item components item modifiers item.",
"example": "Example name"
},
"optionName": {
"type": "string",
"description": "Human-readable option name for preorder public manage item components item modifiers item.",
"example": "Example name"
},
"priceDelta": {
"type": "string",
"pattern": "^\\d+\\.\\d{2}$",
"description": "Decimal monetary price delta serialized as a string in the currency identified by the financial document or policy that embeds preorder public manage item components item modifiers item; zero is a recorded amount, not absence.",
"example": "1.00"
},
"allergenCodes": {
"type": "array",
"items": {
"type": "string",
"example": "EXAMPLE"
},
"description": "Allergen codes values included as allergen codes in preorder public manage item components item modifiers item.",
"example": [
"EXAMPLE"
]
}
},
"required": [
"optionId",
"groupName",
"optionName",
"priceDelta",
"allergenCodes"
],
"example": {
"optionId": null,
"groupName": "Example name",
"optionName": "Example name",
"priceDelta": "1.00",
"allergenCodes": [
"EXAMPLE"
]
}
},
"description": "Modifiers included as modifiers in preorder public manage item components item.",
"example": [
{
"optionId": null,
"groupName": "Example name",
"optionName": "Example name",
"priceDelta": "1.00",
"allergenCodes": [
"EXAMPLE"
]
}
]
}
},
"required": [
"id",
"operationalRole",
"name",
"menuVariantId",
"quantity",
"componentGroupId",
"componentGroupName",
"componentChoiceId",
"componentQuantity",
"componentUpcharge",
"componentIsDefault",
"kitchenStatus",
"modifiers"
],
"example": {
"id": "cada95b5-09b4-4bdd-8379-2e6df6ee6198",
"operationalRole": "GUEST_SELECTION",
"name": "Example name",
"menuVariantId": null,
"quantity": 1,
"componentGroupId": "example-id",
"componentGroupName": "Example name",
"componentChoiceId": "example-id",
"componentQuantity": 1,
"componentUpcharge": "1.00",
"componentIsDefault": true,
"kitchenStatus": "PENDING",
"modifiers": [
{
"optionId": null,
"groupName": "Example name",
"optionName": "Example name",
"priceDelta": "1.00",
"allergenCodes": [
"EXAMPLE"
]
}
]
}
},
"description": "Components included as components in preorder public manage item.",
"example": [
{
"id": "cada95b5-09b4-4bdd-8379-2e6df6ee6198",
"operationalRole": "GUEST_SELECTION",
"name": "Example name",
"menuVariantId": null,
"quantity": 1,
"componentGroupId": "example-id",
"componentGroupName": "Example name",
"componentChoiceId": "example-id",
"componentQuantity": 1,
"componentUpcharge": "1.00",
"componentIsDefault": true,
"kitchenStatus": "PENDING",
"modifiers": [
{
"optionId": null,
"groupName": "Example name",
"optionName": "Example name",
"priceDelta": "1.00",
"allergenCodes": [
"EXAMPLE"
]
}
]
}
]
}
},
"required": [
"clientLineId",
"id",
"menuVersionId",
"salesChannelId",
"menuItemId",
"menuVariantId",
"name",
"rootItemStructureKind",
"itemStructureExecutionMode",
"effectiveExecutionMode",
"quantity",
"billableQuantity",
"unitPrice",
"totalAmount",
"specialRequest",
"serviceFlags",
"allergenCodes",
"kitchenStatus",
"modifiers",
"components"
],
"example": {
"clientLineId": "example-id",
"id": "9fbff223-7cc1-4311-8644-0bd59ff2477a",
"menuVersionId": null,
"salesChannelId": null,
"menuItemId": null,
"menuVariantId": null,
"name": "Example name",
"rootItemStructureKind": "SINGLE_ITEM",
"itemStructureExecutionMode": "DIRECT_ITEM",
"effectiveExecutionMode": "DIRECT_ITEM",
"quantity": 1,
"billableQuantity": 1,
"unitPrice": "1.00",
"totalAmount": "1.00",
"specialRequest": null,
"serviceFlags": [
"example"
],
"allergenCodes": [
"EXAMPLE"
],
"kitchenStatus": "PENDING",
"modifiers": [
{
"optionId": null,
"groupName": "Example name",
"optionName": "Example name",
"priceDelta": "1.00",
"allergenCodes": [
"EXAMPLE"
]
}
],
"components": [
{
"id": "cada95b5-09b4-4bdd-8379-2e6df6ee6198",
"operationalRole": "GUEST_SELECTION",
"name": "Example name",
"menuVariantId": null,
"quantity": 1,
"componentGroupId": "example-id",
"componentGroupName": "Example name",
"componentChoiceId": "example-id",
"componentQuantity": 1,
"componentUpcharge": "1.00",
"componentIsDefault": true,
"kitchenStatus": "PENDING",
"modifiers": [
{
"optionId": null,
"groupName": "Example name",
"optionName": "Example name",
"priceDelta": "1.00",
"allergenCodes": [
"EXAMPLE"
]
}
]
}
]
}
},
"description": "Items returned in the preorder public manage collection.",
"example": [
{
"clientLineId": "example-id",
"id": "9fbff223-7cc1-4311-8644-0bd59ff2477a",
"menuVersionId": null,
"salesChannelId": null,
"menuItemId": null,
"menuVariantId": null,
"name": "Example name",
"rootItemStructureKind": "SINGLE_ITEM",
"itemStructureExecutionMode": "DIRECT_ITEM",
"effectiveExecutionMode": "DIRECT_ITEM",
"quantity": 1,
"billableQuantity": 1,
"unitPrice": "1.00",
"totalAmount": "1.00",
"specialRequest": null,
"serviceFlags": [
"example"
],
"allergenCodes": [
"EXAMPLE"
],
"kitchenStatus": "PENDING",
"modifiers": [
{
"optionId": null,
"groupName": "Example name",
"optionName": "Example name",
"priceDelta": "1.00",
"allergenCodes": [
"EXAMPLE"
]
}
],
"components": [
{
"id": "cada95b5-09b4-4bdd-8379-2e6df6ee6198",
"operationalRole": "GUEST_SELECTION",
"name": "Example name",
"menuVariantId": null,
"quantity": 1,
"componentGroupId": "example-id",
"componentGroupName": "Example name",
"componentChoiceId": "example-id",
"componentQuantity": 1,
"componentUpcharge": "1.00",
"componentIsDefault": true,
"kitchenStatus": "PENDING",
"modifiers": [
{
"optionId": null,
"groupName": "Example name",
"optionName": "Example name",
"priceDelta": "1.00",
"allergenCodes": [
"EXAMPLE"
]
}
]
}
]
}
]
},
"allowedActions": {
"type": "object",
"properties": {
"cancel": {
"type": "boolean",
"description": "Whether the caller may cancel; false means the action is unavailable in the current lifecycle and permission context.",
"example": true
},
"reschedule": {
"type": "boolean",
"description": "Whether the caller may reschedule; false means the action is unavailable in the current lifecycle and permission context.",
"example": true
},
"changeRequest": {
"type": "boolean",
"description": "Whether the caller may change request; false means the action is unavailable in the current lifecycle and permission context.",
"example": true
}
},
"required": [
"cancel",
"reschedule",
"changeRequest"
],
"description": "Allowed actions details embedded in preorder public manage containing cancel, reschedule, and change request.",
"example": {
"cancel": true,
"reschedule": true,
"changeRequest": true
}
},
"generatedAt": {
"type": "string",
"format": "date-time",
"description": "RFC 3339 timestamp for generated at; offsets represent the same absolute instant.",
"example": "2026-01-15T12:00:00.000Z"
}
},
"required": [
"fulfillmentId",
"orderId",
"revision",
"status",
"serviceMode",
"partySize",
"scheduledFor",
"venue",
"channel",
"contact",
"deposit",
"delivery",
"items",
"allowedActions",
"generatedAt"
],
"description": "Returns the guest-visible preorder projection and current revision.",
"example": {
"fulfillmentId": "0a81282f-ea3b-40be-8ef7-4ad39e32ea88",
"orderId": "f3127edf-ce4f-4da7-8be5-81b962024e6c",
"revision": 1,
"status": "DRAFT",
"serviceMode": "DINE_IN",
"partySize": 1,
"scheduledFor": "2026-01-15T12:00:00.000Z",
"venue": {
"id": "fbc6db41-f1c2-4f74-862d-210bd28ee2a0",
"name": "Example name",
"timeZone": "Asia/Tbilisi"
},
"channel": {
"publicHandle": "example",
"salesChannelId": "ff0fa725-ba44-4e7a-82bb-a15650e0a0cc",
"termsVersion": "example",
"privacyVersion": "example"
},
"contact": null,
"deposit": {
"status": "NOT_REQUIRED",
"requiredAmount": "1.00",
"paidAmount": "1.00",
"dueAt": null
},
"delivery": {
"zoneId": null,
"feeAmount": "1.00"
},
"items": [
{
"clientLineId": "example-id",
"id": "9fbff223-7cc1-4311-8644-0bd59ff2477a",
"menuVersionId": null,
"salesChannelId": null,
"menuItemId": null,
"menuVariantId": null,
"name": "Example name",
"rootItemStructureKind": "SINGLE_ITEM",
"itemStructureExecutionMode": "DIRECT_ITEM",
"effectiveExecutionMode": "DIRECT_ITEM",
"quantity": 1,
"billableQuantity": 1,
"unitPrice": "1.00",
"totalAmount": "1.00",
"specialRequest": null,
"serviceFlags": [
"example"
],
"allergenCodes": [
"EXAMPLE"
],
"kitchenStatus": "PENDING",
"modifiers": [
{
"optionId": null,
"groupName": "Example name",
"optionName": "Example name",
"priceDelta": "1.00",
"allergenCodes": [
"EXAMPLE"
]
}
],
"components": [
{
"id": "cada95b5-09b4-4bdd-8379-2e6df6ee6198",
"operationalRole": "GUEST_SELECTION",
"name": "Example name",
"menuVariantId": null,
"quantity": 1,
"componentGroupId": "example-id",
"componentGroupName": "Example name",
"componentChoiceId": "example-id",
"componentQuantity": 1,
"componentUpcharge": "1.00",
"componentIsDefault": true,
"kitchenStatus": "PENDING",
"modifiers": [
{
"optionId": null,
"groupName": "Example name",
"optionName": "Example name",
"priceDelta": "1.00",
"allergenCodes": [
"EXAMPLE"
]
}
]
}
]
}
],
"allowedActions": {
"cancel": true,
"reschedule": true,
"changeRequest": true
},
"generatedAt": "2026-01-15T12:00:00.000Z"
}
}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"
}