{ "info": { "title": "Brightwild Booking API", "version": "0.2.0-preview.2", "description": "Search, price and reserve Brightwild homes. Authenticate with an access token from POST /oauth/token; the application's grants decide which operations it may call. Dates are property-local; stays are half-open, 1–90 nights; a calendar covers at most 93 days. Money is integer minor units; fees include cleaning. Every response carries x-request-id; preserve it for support. Sandbox responses are simulated and never evidence of a real reservation. Guide: https://developers.brightwild.com" }, "servers": [ { "url": "https://api.brightwild.com", "description": "Production: live inventory and real reservations" }, { "url": "https://sandbox.api.brightwild.com", "description": "Sandbox: the same contract with simulated data; it never creates a real reservation" } ], "security": [ { "Application": [] } ], "components": { "securitySchemes": { "Application": { "type": "http", "scheme": "bearer", "description": "An application access token from POST /oauth/token: the application's ID and key, exchanged with OAuth client_credentials for a token of at most 15 minutes. The SDK exchanges and caches it; the key itself is sent only to the token endpoint." }, "SessionCapability": { "type": "apiKey", "in": "header", "name": "Session-Capability", "description": "The checkout's session capability, returned once when the checkout is created. A checkout ID alone grants no access." } } }, "openapi": "3.1.1", "paths": { "/v1/site": { "get": { "operationId": "distribution.site.get", "summary": "Read the application's site", "description": "The brand, discovery mode, collections, public policies and standards of the catalog the application is bound to, and the capabilities it may use.", "tags": [ "distribution" ], "parameters": [ { "name": "X-Booking-Consumer", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "web", "agent", "cli", "staff" ] }, "description": "Host-reported measurement provenance; not consent, identity or authority. Missing provenance stays unknown." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "environment": { "enum": [ "simulation", "test", "live" ], "type": "string" }, "discovery": { "enum": [ "brand", "portfolio" ], "type": "string" }, "capabilities": { "type": "array", "items": { "enum": [ "catalog", "search", "quotes", "checkout", "signals" ], "type": "string" } }, "collections": { "type": "array", "items": { "type": "object", "properties": { "collectionId": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "collectionId", "slug", "name", "description" ] } }, "policies": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "body": { "type": "string" } }, "required": [ "label", "body" ] } }, "standards": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "body": { "type": "string" } }, "required": [ "label", "body" ] } } }, "required": [ "name", "slug", "environment", "discovery", "capabilities", "collections", "policies", "standards" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "forbidden" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "conflict", "invalid_state" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "412": { "description": "412", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "precondition_failed" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "422": { "description": "422", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "policy_restricted" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "internal" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unavailable", "not_configured" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unresolved" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } } } } }, "/v1/listings": { "get": { "operationId": "distribution.listing.list", "summary": "Browse published listings", "description": "Published Listing content, in a stable order. Content alone does not establish availability.", "tags": [ "distribution" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^[A-Za-z0-9_-]+$" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "collectionId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Booking-Consumer", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "web", "agent", "cli", "staff" ] }, "description": "Host-reported measurement provenance; not consent, identity or authority. Missing provenance stays unknown." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "listingId": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "blurb": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "collectionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "timeZone": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "destination": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sleeps": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0 }, { "type": "null" } ] }, "bedrooms": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "bathrooms": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "alt": { "type": "string" } }, "required": [ "url", "alt" ] } }, "amenities": { "type": "array", "items": { "type": "string" } }, "policies": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "body": { "type": "string" } }, "required": [ "label", "body" ] } }, "spaces": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isPrivate": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "beds": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0 } }, "required": [ "type", "quantity" ] } } }, "required": [ "type", "name", "isPrivate", "beds" ] } }, "geo": { "anyOf": [ { "type": "object", "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "latitude", "longitude" ] }, { "type": "null" } ] }, "indexable": { "type": "boolean" } }, "required": [ "listingId", "slug", "name", "description", "blurb", "collectionId", "timeZone", "destination", "sleeps", "bedrooms", "bathrooms", "images", "amenities", "policies", "spaces", "geo", "indexable" ] } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] }, "meta": { "type": "object", "properties": { "asOf": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completeness": { "enum": [ "complete", "partial", "unavailable" ], "type": "string" }, "definitionVersion": { "type": "string", "minLength": 1 }, "sections": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "asOf": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completeness": { "enum": [ "complete", "partial", "unavailable" ], "type": "string" } }, "required": [ "asOf", "completeness" ] } } }, "required": [ "asOf", "completeness", "definitionVersion" ] } }, "required": [ "items", "nextCursor", "meta" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "forbidden" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "conflict", "invalid_state" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "412": { "description": "412", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "precondition_failed" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "422": { "description": "422", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "policy_restricted" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "internal" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unavailable", "not_configured" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unresolved" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } } } } }, "/v1/listings/{listingId}": { "get": { "operationId": "distribution.listing.get", "summary": "Read one published listing", "tags": [ "distribution" ], "parameters": [ { "name": "listingId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Booking-Consumer", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "web", "agent", "cli", "staff" ] }, "description": "Host-reported measurement provenance; not consent, identity or authority. Missing provenance stays unknown." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "listingId": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "blurb": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "collectionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "timeZone": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "destination": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sleeps": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0 }, { "type": "null" } ] }, "bedrooms": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "bathrooms": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "alt": { "type": "string" } }, "required": [ "url", "alt" ] } }, "amenities": { "type": "array", "items": { "type": "string" } }, "policies": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "body": { "type": "string" } }, "required": [ "label", "body" ] } }, "spaces": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isPrivate": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "beds": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0 } }, "required": [ "type", "quantity" ] } } }, "required": [ "type", "name", "isPrivate", "beds" ] } }, "geo": { "anyOf": [ { "type": "object", "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "latitude", "longitude" ] }, { "type": "null" } ] }, "indexable": { "type": "boolean" } }, "required": [ "listingId", "slug", "name", "description", "blurb", "collectionId", "timeZone", "destination", "sleeps", "bedrooms", "bathrooms", "images", "amenities", "policies", "spaces", "geo", "indexable" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "forbidden" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "conflict", "invalid_state" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "412": { "description": "412", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "precondition_failed" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "422": { "description": "422", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "policy_restricted" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "internal" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unavailable", "not_configured" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unresolved" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } } } } }, "/v1/listings/search": { "post": { "operationId": "distribution.listing.search", "summary": "Search live availability", "description": "Listings available for exact dates and party, with the live stay total where the provider returned one. A result is not a hold or an accepted quote.", "tags": [ "distribution" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "checkIn": { "type": "string", "format": "date" }, "checkOut": { "type": "string", "format": "date" }, "party": { "type": "object", "properties": { "adults": { "type": "integer", "minimum": 1, "maximum": 30 }, "children": { "type": "integer", "minimum": 0, "maximum": 29 }, "infants": { "type": "integer", "minimum": 0, "maximum": 10 }, "pets": { "type": "integer", "minimum": 0, "maximum": 10 } }, "required": [ "adults", "children", "infants", "pets" ], "additionalProperties": false }, "journey": { "type": "object", "properties": { "visitorId": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string", "format": "uuid" }, "consent": { "enum": [ "not_required", "granted", "denied" ], "type": "string" }, "userAgent": { "type": "string", "maxLength": 512 }, "campaign": { "type": "object", "properties": { "channel": { "type": "string", "minLength": 1, "maxLength": 200 }, "utmSource": { "type": "string", "minLength": 1, "maxLength": 200 }, "utmMedium": { "type": "string", "minLength": 1, "maxLength": 200 }, "utmCampaign": { "type": "string", "minLength": 1, "maxLength": 200 }, "utmContent": { "type": "string", "minLength": 1, "maxLength": 200 }, "utmTerm": { "type": "string", "minLength": 1, "maxLength": 200 }, "advertisingClickIds": { "type": "object", "properties": { "dclid": { "type": "string", "minLength": 1, "maxLength": 200 }, "fbclid": { "type": "string", "minLength": 1, "maxLength": 200 }, "gbraid": { "type": "string", "minLength": 1, "maxLength": 200 }, "gclid": { "type": "string", "minLength": 1, "maxLength": 200 }, "li_fat_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "msclkid": { "type": "string", "minLength": 1, "maxLength": 200 }, "ttclid": { "type": "string", "minLength": 1, "maxLength": 200 }, "wbraid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false } }, "additionalProperties": false }, "correlationId": { "type": "string", "format": "uuid" }, "route": { "enum": [ "home", "search", "listing", "checkout", "confirmation" ], "type": "string" }, "referrerOrigin": { "type": "string", "maxLength": 256, "format": "uri" }, "deviceClass": { "enum": [ "mobile", "tablet", "desktop", "unknown" ], "type": "string" } }, "required": [ "visitorId", "consent" ], "additionalProperties": false }, "collectionId": { "type": "string", "format": "uuid" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "cursor": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^[A-Za-z0-9_-]+$" } }, "required": [ "checkIn", "checkOut", "party" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "listing": { "type": "object", "properties": { "listingId": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "blurb": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "collectionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "timeZone": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "destination": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sleeps": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0 }, { "type": "null" } ] }, "bedrooms": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "bathrooms": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "alt": { "type": "string" } }, "required": [ "url", "alt" ] } }, "amenities": { "type": "array", "items": { "type": "string" } }, "policies": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "body": { "type": "string" } }, "required": [ "label", "body" ] } }, "spaces": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isPrivate": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "beds": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0 } }, "required": [ "type", "quantity" ] } } }, "required": [ "type", "name", "isPrivate", "beds" ] } }, "geo": { "anyOf": [ { "type": "object", "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "latitude", "longitude" ] }, { "type": "null" } ] }, "indexable": { "type": "boolean" } }, "required": [ "listingId", "slug", "name", "description", "blurb", "collectionId", "timeZone", "destination", "sleeps", "bedrooms", "bathrooms", "images", "amenities", "policies", "spaces", "geo", "indexable" ] }, "total": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] } }, "required": [ "listing", "total" ] } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] }, "searchObservationId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "meta": { "type": "object", "properties": { "asOf": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completeness": { "enum": [ "complete", "partial", "unavailable" ], "type": "string" }, "definitionVersion": { "type": "string", "minLength": 1 }, "sections": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "asOf": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completeness": { "enum": [ "complete", "partial", "unavailable" ], "type": "string" } }, "required": [ "asOf", "completeness" ] } } }, "required": [ "asOf", "completeness", "definitionVersion" ] } }, "required": [ "items", "nextCursor", "searchObservationId", "meta" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "forbidden" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "conflict", "invalid_state" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "412": { "description": "412", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "precondition_failed" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "422": { "description": "422", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "policy_restricted" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "internal" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unavailable", "not_configured" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unresolved" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } } }, "parameters": [ { "name": "X-Booking-Consumer", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "web", "agent", "cli", "staff" ] }, "description": "Host-reported measurement provenance; not consent, identity or authority. Missing provenance stays unknown." } ] } }, "/v1/listings/{listingId}/calendar": { "get": { "operationId": "inventory.calendar.get", "summary": "Read a listing's live calendar", "description": "Live open dates and minimum nights for a published Listing, at most 93 days. Availability is not a reservation.", "tags": [ "inventory" ], "parameters": [ { "name": "listingId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "startDate", "in": "query", "required": true, "schema": { "type": "string", "format": "date" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "endDate", "in": "query", "required": true, "schema": { "type": "string", "format": "date" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Booking-Consumer", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "web", "agent", "cli", "staff" ] }, "description": "Host-reported measurement provenance; not consent, identity or authority. Missing provenance stays unknown." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "listingId": { "type": "string", "format": "uuid" }, "timeZone": { "type": "string" }, "days": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "available": { "type": "boolean" }, "minimumNights": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0 }, { "type": "null" } ] } }, "required": [ "date", "available", "minimumNights" ] } }, "meta": { "type": "object", "properties": { "asOf": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completeness": { "enum": [ "complete", "partial", "unavailable" ], "type": "string" }, "definitionVersion": { "type": "string", "minLength": 1 }, "sections": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "asOf": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completeness": { "enum": [ "complete", "partial", "unavailable" ], "type": "string" } }, "required": [ "asOf", "completeness" ] } } }, "required": [ "asOf", "completeness", "definitionVersion" ] } }, "required": [ "listingId", "timeZone", "days", "meta" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "forbidden" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "conflict", "invalid_state" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "412": { "description": "412", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "precondition_failed" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "422": { "description": "422", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "policy_restricted" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "internal" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unavailable", "not_configured" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unresolved" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } } } } }, "/v1/quotes": { "post": { "operationId": "reservation.quote.create", "summary": "Quote a stay", "description": "Prices one Listing for exact dates and party under its current policy. The quote expires; checkout needs a current quote and the guest's acceptance of its terms.", "tags": [ "reservation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteId": { "type": "string", "format": "uuid" }, "listingId": { "type": "string", "format": "uuid" }, "checkIn": { "type": "string", "format": "date" }, "checkOut": { "type": "string", "format": "date" }, "party": { "type": "object", "properties": { "adults": { "type": "integer", "minimum": 1, "maximum": 30 }, "children": { "type": "integer", "minimum": 0, "maximum": 29 }, "infants": { "type": "integer", "minimum": 0, "maximum": 10 }, "pets": { "type": "integer", "minimum": 0, "maximum": 10 } }, "required": [ "adults", "children", "infants", "pets" ], "additionalProperties": false }, "couponCode": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "quoteId", "listingId", "checkIn", "checkOut", "party" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteId": { "type": "string", "format": "uuid" }, "selection": { "type": "object", "properties": { "listingId": { "type": "string", "format": "uuid" }, "checkIn": { "type": "string", "format": "date" }, "checkOut": { "type": "string", "format": "date" }, "party": { "type": "object", "properties": { "adults": { "type": "integer", "minimum": 1, "maximum": 30 }, "children": { "type": "integer", "minimum": 0, "maximum": 29 }, "infants": { "type": "integer", "minimum": 0, "maximum": 10 }, "pets": { "type": "integer", "minimum": 0, "maximum": 10 } }, "required": [ "adults", "children", "infants", "pets" ] } }, "required": [ "listingId", "checkIn", "checkOut", "party" ] }, "timeZone": { "type": "string", "minLength": 1 }, "expiresAt": { "type": "string", "format": "date-time" }, "charges": { "type": "object", "properties": { "accommodation": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "fees": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "cleaning": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "taxes": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "total": { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, "dueNow": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "schedule": { "type": "array", "items": { "type": "object", "properties": { "dueOn": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "amount": { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] } }, "required": [ "dueOn", "amount" ] } } }, "required": [ "accommodation", "fees", "cleaning", "taxes", "total", "dueNow", "schedule" ] }, "terms": { "type": "object", "properties": { "version": { "type": "string", "minLength": 1 }, "policies": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "body": { "type": "string" } }, "required": [ "label", "body" ] } } }, "required": [ "version", "policies" ] }, "nextActions": { "type": "array", "items": { "enum": [ "create_checkout", "refresh_quote" ], "type": "string" } }, "meta": { "type": "object", "properties": { "asOf": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completeness": { "enum": [ "complete", "partial", "unavailable" ], "type": "string" }, "definitionVersion": { "type": "string", "minLength": 1 }, "sections": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "asOf": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completeness": { "enum": [ "complete", "partial", "unavailable" ], "type": "string" } }, "required": [ "asOf", "completeness" ] } } }, "required": [ "asOf", "completeness", "definitionVersion" ] } }, "required": [ "quoteId", "selection", "timeZone", "expiresAt", "charges", "terms", "nextActions", "meta" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "forbidden" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "conflict", "invalid_state" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "412": { "description": "412", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "precondition_failed" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "422": { "description": "422", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "policy_restricted" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "internal" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unavailable", "not_configured" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unresolved" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } } }, "parameters": [ { "name": "X-Booking-Consumer", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "web", "agent", "cli", "staff" ] }, "description": "Host-reported measurement provenance; not consent, identity or authority. Missing provenance stays unknown." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,255}$" }, "description": "For a caller that cannot send the new resource's ID: the API derives the ID from the key. Send one or the other." } ] } }, "/v1/checkouts": { "post": { "operationId": "reservation.checkout.create", "summary": "Start a checkout from a quote", "description": "Creates the checkout and its session capability, the only credential that reaches it afterwards. Keep the capability server-side.", "tags": [ "reservation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "checkoutId": { "type": "string", "format": "uuid" }, "quoteId": { "type": "string", "format": "uuid" }, "journey": { "type": "object", "properties": { "visitorId": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string", "format": "uuid" }, "consent": { "enum": [ "not_required", "granted", "denied" ], "type": "string" }, "userAgent": { "type": "string", "maxLength": 512 }, "campaign": { "type": "object", "properties": { "channel": { "type": "string", "minLength": 1, "maxLength": 200 }, "utmSource": { "type": "string", "minLength": 1, "maxLength": 200 }, "utmMedium": { "type": "string", "minLength": 1, "maxLength": 200 }, "utmCampaign": { "type": "string", "minLength": 1, "maxLength": 200 }, "utmContent": { "type": "string", "minLength": 1, "maxLength": 200 }, "utmTerm": { "type": "string", "minLength": 1, "maxLength": 200 }, "advertisingClickIds": { "type": "object", "properties": { "dclid": { "type": "string", "minLength": 1, "maxLength": 200 }, "fbclid": { "type": "string", "minLength": 1, "maxLength": 200 }, "gbraid": { "type": "string", "minLength": 1, "maxLength": 200 }, "gclid": { "type": "string", "minLength": 1, "maxLength": 200 }, "li_fat_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "msclkid": { "type": "string", "minLength": 1, "maxLength": 200 }, "ttclid": { "type": "string", "minLength": 1, "maxLength": 200 }, "wbraid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false } }, "additionalProperties": false }, "correlationId": { "type": "string", "format": "uuid" }, "route": { "enum": [ "home", "search", "listing", "checkout", "confirmation" ], "type": "string" }, "referrerOrigin": { "type": "string", "maxLength": 256, "format": "uri" }, "deviceClass": { "enum": [ "mobile", "tablet", "desktop", "unknown" ], "type": "string" } }, "required": [ "visitorId", "consent" ], "additionalProperties": false } }, "required": [ "checkoutId", "quoteId" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "checkout": { "type": "object", "properties": { "checkoutId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0 }, "quote": { "type": "object", "properties": { "quoteId": { "type": "string", "format": "uuid" }, "selection": { "type": "object", "properties": { "listingId": { "type": "string", "format": "uuid" }, "checkIn": { "type": "string", "format": "date" }, "checkOut": { "type": "string", "format": "date" }, "party": { "type": "object", "properties": { "adults": { "type": "integer", "minimum": 1, "maximum": 30 }, "children": { "type": "integer", "minimum": 0, "maximum": 29 }, "infants": { "type": "integer", "minimum": 0, "maximum": 10 }, "pets": { "type": "integer", "minimum": 0, "maximum": 10 } }, "required": [ "adults", "children", "infants", "pets" ] } }, "required": [ "listingId", "checkIn", "checkOut", "party" ] }, "timeZone": { "type": "string", "minLength": 1 }, "expiresAt": { "type": "string", "format": "date-time" }, "charges": { "type": "object", "properties": { "accommodation": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "fees": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "cleaning": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "taxes": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "total": { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, "dueNow": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "schedule": { "type": "array", "items": { "type": "object", "properties": { "dueOn": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "amount": { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] } }, "required": [ "dueOn", "amount" ] } } }, "required": [ "accommodation", "fees", "cleaning", "taxes", "total", "dueNow", "schedule" ] }, "terms": { "type": "object", "properties": { "version": { "type": "string", "minLength": 1 }, "policies": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "body": { "type": "string" } }, "required": [ "label", "body" ] } } }, "required": [ "version", "policies" ] }, "nextActions": { "type": "array", "items": { "enum": [ "create_checkout", "refresh_quote" ], "type": "string" } }, "meta": { "type": "object", "properties": { "asOf": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completeness": { "enum": [ "complete", "partial", "unavailable" ], "type": "string" }, "definitionVersion": { "type": "string", "minLength": 1 }, "sections": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "asOf": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completeness": { "enum": [ "complete", "partial", "unavailable" ], "type": "string" } }, "required": [ "asOf", "completeness" ] } } }, "required": [ "asOf", "completeness", "definitionVersion" ] } }, "required": [ "quoteId", "selection", "timeZone", "expiresAt", "charges", "terms", "nextActions", "meta" ] }, "state": { "enum": [ "needs_guest", "needs_payment", "ready", "pending", "requires_action", "uncertain", "confirmed", "failed", "expired" ], "type": "string" }, "guestComplete": { "type": "boolean" }, "paymentReady": { "type": "boolean" }, "paymentSetup": { "anyOf": [ { "type": "object", "properties": { "state": { "enum": [ "requested", "ready", "failed" ], "type": "string" }, "kind": { "enum": [ "stripe", "simulation" ], "type": "string" }, "setupReference": { "type": "string", "minLength": 1 }, "publishableKey": { "type": "string", "pattern": "^pk_(test|live)_" }, "clientSecret": { "type": "string", "minLength": 1 }, "failure": { "enum": [ "unsupported", "not_authorized", "unavailable", "unresolved" ], "type": "string" } }, "required": [ "state" ] }, { "type": "null" } ] }, "settlement": { "type": "object", "properties": { "kind": { "enum": [ "card", "partner" ], "type": "string" } }, "required": [ "kind" ], "description": "Who settles the checkout. card: the guest pays by card through the payment steps. partner: your organization collects the guest's payment under its agreement, so the checkout skips the payment steps." }, "nextActions": { "type": "array", "items": { "enum": [ "save_guest", "setup_payment", "verify_payment", "submit", "poll", "refresh_quote", "view_confirmation", "contact_support" ], "type": "string" } }, "failure": { "type": "object", "properties": { "reason": { "enum": [ "sold_out", "quote_expired", "price_changed", "policy_changed", "authority_revoked", "refused" ], "type": "string", "description": "Why the checkout ended without a reservation. sold_out: the home is no longer available for these dates. quote_expired: the quote expired before the reservation was made. price_changed: the price changed since the quote. policy_changed: the home's terms changed since the quote. authority_revoked: your application's permission to book was withdrawn before a reservation was attempted. refused: the reservation was refused. In every case no reservation was made; quote again to retry." } }, "required": [ "reason" ] } }, "required": [ "checkoutId", "version", "quote", "state", "guestComplete", "paymentReady", "paymentSetup", "settlement", "nextActions" ] }, "sessionCapability": { "type": "string", "minLength": 32, "maxLength": 512 }, "sessionExpiresAt": { "type": "string", "format": "date-time" } }, "required": [ "checkout", "sessionCapability", "sessionExpiresAt" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "forbidden" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "conflict", "invalid_state", "quote_expired" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "412": { "description": "412", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "precondition_failed" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "422": { "description": "422", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "policy_restricted" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "internal" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unavailable", "not_configured" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unresolved" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } } }, "parameters": [ { "name": "X-Booking-Consumer", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "web", "agent", "cli", "staff" ] }, "description": "Host-reported measurement provenance; not consent, identity or authority. Missing provenance stays unknown." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,255}$" }, "description": "For a caller that cannot send the new resource's ID: the API derives the ID from the key. Send one or the other." } ] } }, "/v1/checkouts/{checkoutId}": { "get": { "operationId": "reservation.checkout.get", "summary": "Read a checkout", "tags": [ "reservation" ], "parameters": [ { "name": "checkoutId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Booking-Consumer", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "web", "agent", "cli", "staff" ] }, "description": "Host-reported measurement provenance; not consent, identity or authority. Missing provenance stays unknown." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "checkoutId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0 }, "quote": { "type": "object", "properties": { "quoteId": { "type": "string", "format": "uuid" }, "selection": { "type": "object", "properties": { "listingId": { "type": "string", "format": "uuid" }, "checkIn": { "type": "string", "format": "date" }, "checkOut": { "type": "string", "format": "date" }, "party": { "type": "object", "properties": { "adults": { "type": "integer", "minimum": 1, "maximum": 30 }, "children": { "type": "integer", "minimum": 0, "maximum": 29 }, "infants": { "type": "integer", "minimum": 0, "maximum": 10 }, "pets": { "type": "integer", "minimum": 0, "maximum": 10 } }, "required": [ "adults", "children", "infants", "pets" ] } }, "required": [ "listingId", "checkIn", "checkOut", "party" ] }, "timeZone": { "type": "string", "minLength": 1 }, "expiresAt": { "type": "string", "format": "date-time" }, "charges": { "type": "object", "properties": { "accommodation": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "fees": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "cleaning": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "taxes": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "total": { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, "dueNow": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "schedule": { "type": "array", "items": { "type": "object", "properties": { "dueOn": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "amount": { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] } }, "required": [ "dueOn", "amount" ] } } }, "required": [ "accommodation", "fees", "cleaning", "taxes", "total", "dueNow", "schedule" ] }, "terms": { "type": "object", "properties": { "version": { "type": "string", "minLength": 1 }, "policies": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "body": { "type": "string" } }, "required": [ "label", "body" ] } } }, "required": [ "version", "policies" ] }, "nextActions": { "type": "array", "items": { "enum": [ "create_checkout", "refresh_quote" ], "type": "string" } }, "meta": { "type": "object", "properties": { "asOf": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completeness": { "enum": [ "complete", "partial", "unavailable" ], "type": "string" }, "definitionVersion": { "type": "string", "minLength": 1 }, "sections": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "asOf": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completeness": { "enum": [ "complete", "partial", "unavailable" ], "type": "string" } }, "required": [ "asOf", "completeness" ] } } }, "required": [ "asOf", "completeness", "definitionVersion" ] } }, "required": [ "quoteId", "selection", "timeZone", "expiresAt", "charges", "terms", "nextActions", "meta" ] }, "state": { "enum": [ "needs_guest", "needs_payment", "ready", "pending", "requires_action", "uncertain", "confirmed", "failed", "expired" ], "type": "string" }, "guestComplete": { "type": "boolean" }, "paymentReady": { "type": "boolean" }, "paymentSetup": { "anyOf": [ { "type": "object", "properties": { "state": { "enum": [ "requested", "ready", "failed" ], "type": "string" }, "kind": { "enum": [ "stripe", "simulation" ], "type": "string" }, "setupReference": { "type": "string", "minLength": 1 }, "publishableKey": { "type": "string", "pattern": "^pk_(test|live)_" }, "clientSecret": { "type": "string", "minLength": 1 }, "failure": { "enum": [ "unsupported", "not_authorized", "unavailable", "unresolved" ], "type": "string" } }, "required": [ "state" ] }, { "type": "null" } ] }, "settlement": { "type": "object", "properties": { "kind": { "enum": [ "card", "partner" ], "type": "string" } }, "required": [ "kind" ], "description": "Who settles the checkout. card: the guest pays by card through the payment steps. partner: your organization collects the guest's payment under its agreement, so the checkout skips the payment steps." }, "nextActions": { "type": "array", "items": { "enum": [ "save_guest", "setup_payment", "verify_payment", "submit", "poll", "refresh_quote", "view_confirmation", "contact_support" ], "type": "string" } }, "failure": { "type": "object", "properties": { "reason": { "enum": [ "sold_out", "quote_expired", "price_changed", "policy_changed", "authority_revoked", "refused" ], "type": "string", "description": "Why the checkout ended without a reservation. sold_out: the home is no longer available for these dates. quote_expired: the quote expired before the reservation was made. price_changed: the price changed since the quote. policy_changed: the home's terms changed since the quote. authority_revoked: your application's permission to book was withdrawn before a reservation was attempted. refused: the reservation was refused. In every case no reservation was made; quote again to retry." } }, "required": [ "reason" ] } }, "required": [ "checkoutId", "version", "quote", "state", "guestComplete", "paymentReady", "paymentSetup", "settlement", "nextActions" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "forbidden" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "conflict", "invalid_state" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "412": { "description": "412", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "precondition_failed" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "internal" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unavailable" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unresolved" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } } }, "security": [ { "Application": [], "SessionCapability": [] } ] } }, "/v1/checkouts/{checkoutId}/guest": { "patch": { "operationId": "reservation.checkout.saveGuest", "summary": "Save the guest's details", "tags": [ "reservation" ], "parameters": [ { "name": "checkoutId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Booking-Consumer", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "web", "agent", "cli", "staff" ] }, "description": "Host-reported measurement provenance; not consent, identity or authority. Missing provenance stays unknown." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0 }, "guest": { "type": "object", "properties": { "firstName": { "type": "string", "minLength": 1, "maxLength": 100 }, "lastName": { "type": "string", "minLength": 1, "maxLength": 100 }, "email": { "type": "string", "maxLength": 254, "format": "email" }, "phone": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$" } }, "required": [ "firstName", "lastName", "email", "phone" ], "additionalProperties": false } }, "required": [ "expectedVersion", "guest" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "checkoutId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0 }, "quote": { "type": "object", "properties": { "quoteId": { "type": "string", "format": "uuid" }, "selection": { "type": "object", "properties": { "listingId": { "type": "string", "format": "uuid" }, "checkIn": { "type": "string", "format": "date" }, "checkOut": { "type": "string", "format": "date" }, "party": { "type": "object", "properties": { "adults": { "type": "integer", "minimum": 1, "maximum": 30 }, "children": { "type": "integer", "minimum": 0, "maximum": 29 }, "infants": { "type": "integer", "minimum": 0, "maximum": 10 }, "pets": { "type": "integer", "minimum": 0, "maximum": 10 } }, "required": [ "adults", "children", "infants", "pets" ] } }, "required": [ "listingId", "checkIn", "checkOut", "party" ] }, "timeZone": { "type": "string", "minLength": 1 }, "expiresAt": { "type": "string", "format": "date-time" }, "charges": { "type": "object", "properties": { "accommodation": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "fees": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "cleaning": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "taxes": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "total": { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, "dueNow": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "schedule": { "type": "array", "items": { "type": "object", "properties": { "dueOn": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "amount": { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] } }, "required": [ "dueOn", "amount" ] } } }, "required": [ "accommodation", "fees", "cleaning", "taxes", "total", "dueNow", "schedule" ] }, "terms": { "type": "object", "properties": { "version": { "type": "string", "minLength": 1 }, "policies": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "body": { "type": "string" } }, "required": [ "label", "body" ] } } }, "required": [ "version", "policies" ] }, "nextActions": { "type": "array", "items": { "enum": [ "create_checkout", "refresh_quote" ], "type": "string" } }, "meta": { "type": "object", "properties": { "asOf": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completeness": { "enum": [ "complete", "partial", "unavailable" ], "type": "string" }, "definitionVersion": { "type": "string", "minLength": 1 }, "sections": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "asOf": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completeness": { "enum": [ "complete", "partial", "unavailable" ], "type": "string" } }, "required": [ "asOf", "completeness" ] } } }, "required": [ "asOf", "completeness", "definitionVersion" ] } }, "required": [ "quoteId", "selection", "timeZone", "expiresAt", "charges", "terms", "nextActions", "meta" ] }, "state": { "enum": [ "needs_guest", "needs_payment", "ready", "pending", "requires_action", "uncertain", "confirmed", "failed", "expired" ], "type": "string" }, "guestComplete": { "type": "boolean" }, "paymentReady": { "type": "boolean" }, "paymentSetup": { "anyOf": [ { "type": "object", "properties": { "state": { "enum": [ "requested", "ready", "failed" ], "type": "string" }, "kind": { "enum": [ "stripe", "simulation" ], "type": "string" }, "setupReference": { "type": "string", "minLength": 1 }, "publishableKey": { "type": "string", "pattern": "^pk_(test|live)_" }, "clientSecret": { "type": "string", "minLength": 1 }, "failure": { "enum": [ "unsupported", "not_authorized", "unavailable", "unresolved" ], "type": "string" } }, "required": [ "state" ] }, { "type": "null" } ] }, "settlement": { "type": "object", "properties": { "kind": { "enum": [ "card", "partner" ], "type": "string" } }, "required": [ "kind" ], "description": "Who settles the checkout. card: the guest pays by card through the payment steps. partner: your organization collects the guest's payment under its agreement, so the checkout skips the payment steps." }, "nextActions": { "type": "array", "items": { "enum": [ "save_guest", "setup_payment", "verify_payment", "submit", "poll", "refresh_quote", "view_confirmation", "contact_support" ], "type": "string" } }, "failure": { "type": "object", "properties": { "reason": { "enum": [ "sold_out", "quote_expired", "price_changed", "policy_changed", "authority_revoked", "refused" ], "type": "string", "description": "Why the checkout ended without a reservation. sold_out: the home is no longer available for these dates. quote_expired: the quote expired before the reservation was made. price_changed: the price changed since the quote. policy_changed: the home's terms changed since the quote. authority_revoked: your application's permission to book was withdrawn before a reservation was attempted. refused: the reservation was refused. In every case no reservation was made; quote again to retry." } }, "required": [ "reason" ] } }, "required": [ "checkoutId", "version", "quote", "state", "guestComplete", "paymentReady", "paymentSetup", "settlement", "nextActions" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "forbidden" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "conflict", "invalid_state", "quote_expired" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "412": { "description": "412", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "precondition_failed" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "internal" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unavailable", "not_configured" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unresolved" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } } }, "security": [ { "Application": [], "SessionCapability": [] } ] } }, "/v1/checkouts/{checkoutId}/promo": { "post": { "operationId": "reservation.checkout.applyPromo", "summary": "Apply a promotion code", "description": "Re-prices the checkout with the code. The new terms replace the old, so the guest accepts them again.", "tags": [ "reservation" ], "parameters": [ { "name": "checkoutId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Booking-Consumer", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "web", "agent", "cli", "staff" ] }, "description": "Host-reported measurement provenance; not consent, identity or authority. Missing provenance stays unknown." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0 }, "couponCode": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "expectedVersion", "couponCode" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "checkoutId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0 }, "quote": { "type": "object", "properties": { "quoteId": { "type": "string", "format": "uuid" }, "selection": { "type": "object", "properties": { "listingId": { "type": "string", "format": "uuid" }, "checkIn": { "type": "string", "format": "date" }, "checkOut": { "type": "string", "format": "date" }, "party": { "type": "object", "properties": { "adults": { "type": "integer", "minimum": 1, "maximum": 30 }, "children": { "type": "integer", "minimum": 0, "maximum": 29 }, "infants": { "type": "integer", "minimum": 0, "maximum": 10 }, "pets": { "type": "integer", "minimum": 0, "maximum": 10 } }, "required": [ "adults", "children", "infants", "pets" ] } }, "required": [ "listingId", "checkIn", "checkOut", "party" ] }, "timeZone": { "type": "string", "minLength": 1 }, "expiresAt": { "type": "string", "format": "date-time" }, "charges": { "type": "object", "properties": { "accommodation": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "fees": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "cleaning": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "taxes": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "total": { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, "dueNow": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "schedule": { "type": "array", "items": { "type": "object", "properties": { "dueOn": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "amount": { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] } }, "required": [ "dueOn", "amount" ] } } }, "required": [ "accommodation", "fees", "cleaning", "taxes", "total", "dueNow", "schedule" ] }, "terms": { "type": "object", "properties": { "version": { "type": "string", "minLength": 1 }, "policies": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "body": { "type": "string" } }, "required": [ "label", "body" ] } } }, "required": [ "version", "policies" ] }, "nextActions": { "type": "array", "items": { "enum": [ "create_checkout", "refresh_quote" ], "type": "string" } }, "meta": { "type": "object", "properties": { "asOf": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completeness": { "enum": [ "complete", "partial", "unavailable" ], "type": "string" }, "definitionVersion": { "type": "string", "minLength": 1 }, "sections": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "asOf": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completeness": { "enum": [ "complete", "partial", "unavailable" ], "type": "string" } }, "required": [ "asOf", "completeness" ] } } }, "required": [ "asOf", "completeness", "definitionVersion" ] } }, "required": [ "quoteId", "selection", "timeZone", "expiresAt", "charges", "terms", "nextActions", "meta" ] }, "state": { "enum": [ "needs_guest", "needs_payment", "ready", "pending", "requires_action", "uncertain", "confirmed", "failed", "expired" ], "type": "string" }, "guestComplete": { "type": "boolean" }, "paymentReady": { "type": "boolean" }, "paymentSetup": { "anyOf": [ { "type": "object", "properties": { "state": { "enum": [ "requested", "ready", "failed" ], "type": "string" }, "kind": { "enum": [ "stripe", "simulation" ], "type": "string" }, "setupReference": { "type": "string", "minLength": 1 }, "publishableKey": { "type": "string", "pattern": "^pk_(test|live)_" }, "clientSecret": { "type": "string", "minLength": 1 }, "failure": { "enum": [ "unsupported", "not_authorized", "unavailable", "unresolved" ], "type": "string" } }, "required": [ "state" ] }, { "type": "null" } ] }, "settlement": { "type": "object", "properties": { "kind": { "enum": [ "card", "partner" ], "type": "string" } }, "required": [ "kind" ], "description": "Who settles the checkout. card: the guest pays by card through the payment steps. partner: your organization collects the guest's payment under its agreement, so the checkout skips the payment steps." }, "nextActions": { "type": "array", "items": { "enum": [ "save_guest", "setup_payment", "verify_payment", "submit", "poll", "refresh_quote", "view_confirmation", "contact_support" ], "type": "string" } }, "failure": { "type": "object", "properties": { "reason": { "enum": [ "sold_out", "quote_expired", "price_changed", "policy_changed", "authority_revoked", "refused" ], "type": "string", "description": "Why the checkout ended without a reservation. sold_out: the home is no longer available for these dates. quote_expired: the quote expired before the reservation was made. price_changed: the price changed since the quote. policy_changed: the home's terms changed since the quote. authority_revoked: your application's permission to book was withdrawn before a reservation was attempted. refused: the reservation was refused. In every case no reservation was made; quote again to retry." } }, "required": [ "reason" ] } }, "required": [ "checkoutId", "version", "quote", "state", "guestComplete", "paymentReady", "paymentSetup", "settlement", "nextActions" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "forbidden" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "conflict", "invalid_state", "quote_expired" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "412": { "description": "412", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "precondition_failed" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "internal" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unavailable", "not_configured" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unresolved" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } } }, "security": [ { "Application": [], "SessionCapability": [] } ] } }, "/v1/checkouts/{checkoutId}/payment-setup": { "post": { "operationId": "reservation.checkout.setupPayment", "summary": "Request hosted card entry", "description": "Requests the payment provider's hosted-field setup for this checkout's Listing. The setup arrives asynchronously: poll the checkout until paymentSetup is ready. Card details never reach Brightwild. A partner-settled checkout takes no payment and returns payment_not_required.", "tags": [ "reservation" ], "parameters": [ { "name": "checkoutId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Booking-Consumer", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "web", "agent", "cli", "staff" ] }, "description": "Host-reported measurement provenance; not consent, identity or authority. Missing provenance stays unknown." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0 } }, "required": [ "expectedVersion" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "checkoutId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0 }, "quote": { "type": "object", "properties": { "quoteId": { "type": "string", "format": "uuid" }, "selection": { "type": "object", "properties": { "listingId": { "type": "string", "format": "uuid" }, "checkIn": { "type": "string", "format": "date" }, "checkOut": { "type": "string", "format": "date" }, "party": { "type": "object", "properties": { "adults": { "type": "integer", "minimum": 1, "maximum": 30 }, "children": { "type": "integer", "minimum": 0, "maximum": 29 }, "infants": { "type": "integer", "minimum": 0, "maximum": 10 }, "pets": { "type": "integer", "minimum": 0, "maximum": 10 } }, "required": [ "adults", "children", "infants", "pets" ] } }, "required": [ "listingId", "checkIn", "checkOut", "party" ] }, "timeZone": { "type": "string", "minLength": 1 }, "expiresAt": { "type": "string", "format": "date-time" }, "charges": { "type": "object", "properties": { "accommodation": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "fees": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "cleaning": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "taxes": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "total": { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, "dueNow": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "schedule": { "type": "array", "items": { "type": "object", "properties": { "dueOn": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "amount": { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] } }, "required": [ "dueOn", "amount" ] } } }, "required": [ "accommodation", "fees", "cleaning", "taxes", "total", "dueNow", "schedule" ] }, "terms": { "type": "object", "properties": { "version": { "type": "string", "minLength": 1 }, "policies": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "body": { "type": "string" } }, "required": [ "label", "body" ] } } }, "required": [ "version", "policies" ] }, "nextActions": { "type": "array", "items": { "enum": [ "create_checkout", "refresh_quote" ], "type": "string" } }, "meta": { "type": "object", "properties": { "asOf": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completeness": { "enum": [ "complete", "partial", "unavailable" ], "type": "string" }, "definitionVersion": { "type": "string", "minLength": 1 }, "sections": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "asOf": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completeness": { "enum": [ "complete", "partial", "unavailable" ], "type": "string" } }, "required": [ "asOf", "completeness" ] } } }, "required": [ "asOf", "completeness", "definitionVersion" ] } }, "required": [ "quoteId", "selection", "timeZone", "expiresAt", "charges", "terms", "nextActions", "meta" ] }, "state": { "enum": [ "needs_guest", "needs_payment", "ready", "pending", "requires_action", "uncertain", "confirmed", "failed", "expired" ], "type": "string" }, "guestComplete": { "type": "boolean" }, "paymentReady": { "type": "boolean" }, "paymentSetup": { "anyOf": [ { "type": "object", "properties": { "state": { "enum": [ "requested", "ready", "failed" ], "type": "string" }, "kind": { "enum": [ "stripe", "simulation" ], "type": "string" }, "setupReference": { "type": "string", "minLength": 1 }, "publishableKey": { "type": "string", "pattern": "^pk_(test|live)_" }, "clientSecret": { "type": "string", "minLength": 1 }, "failure": { "enum": [ "unsupported", "not_authorized", "unavailable", "unresolved" ], "type": "string" } }, "required": [ "state" ] }, { "type": "null" } ] }, "settlement": { "type": "object", "properties": { "kind": { "enum": [ "card", "partner" ], "type": "string" } }, "required": [ "kind" ], "description": "Who settles the checkout. card: the guest pays by card through the payment steps. partner: your organization collects the guest's payment under its agreement, so the checkout skips the payment steps." }, "nextActions": { "type": "array", "items": { "enum": [ "save_guest", "setup_payment", "verify_payment", "submit", "poll", "refresh_quote", "view_confirmation", "contact_support" ], "type": "string" } }, "failure": { "type": "object", "properties": { "reason": { "enum": [ "sold_out", "quote_expired", "price_changed", "policy_changed", "authority_revoked", "refused" ], "type": "string", "description": "Why the checkout ended without a reservation. sold_out: the home is no longer available for these dates. quote_expired: the quote expired before the reservation was made. price_changed: the price changed since the quote. policy_changed: the home's terms changed since the quote. authority_revoked: your application's permission to book was withdrawn before a reservation was attempted. refused: the reservation was refused. In every case no reservation was made; quote again to retry." } }, "required": [ "reason" ] } }, "required": [ "checkoutId", "version", "quote", "state", "guestComplete", "paymentReady", "paymentSetup", "settlement", "nextActions" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "forbidden" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "conflict", "invalid_state", "quote_expired" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "412": { "description": "412", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "precondition_failed" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "422": { "description": "422", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "payment_not_required" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "internal" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unavailable", "not_configured" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unresolved" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } } }, "security": [ { "Application": [], "SessionCapability": [] } ] } }, "/v1/checkouts/{checkoutId}/payment-method": { "post": { "operationId": "reservation.checkout.verifyPayment", "summary": "Record the verified payment method", "description": "Records the card the guest entered in the hosted fields. A partner-settled checkout takes no payment and returns payment_not_required.", "tags": [ "reservation" ], "parameters": [ { "name": "checkoutId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Booking-Consumer", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "web", "agent", "cli", "staff" ] }, "description": "Host-reported measurement provenance; not consent, identity or authority. Missing provenance stays unknown." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0 }, "setupReference": { "type": "string", "minLength": 1, "maxLength": 256 }, "paymentMethodId": { "type": "string", "maxLength": 256, "pattern": "^(pm_|sim_)[A-Za-z0-9_]+$" }, "consentAccepted": { "const": true } }, "required": [ "expectedVersion", "setupReference", "paymentMethodId", "consentAccepted" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "checkoutId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0 }, "quote": { "type": "object", "properties": { "quoteId": { "type": "string", "format": "uuid" }, "selection": { "type": "object", "properties": { "listingId": { "type": "string", "format": "uuid" }, "checkIn": { "type": "string", "format": "date" }, "checkOut": { "type": "string", "format": "date" }, "party": { "type": "object", "properties": { "adults": { "type": "integer", "minimum": 1, "maximum": 30 }, "children": { "type": "integer", "minimum": 0, "maximum": 29 }, "infants": { "type": "integer", "minimum": 0, "maximum": 10 }, "pets": { "type": "integer", "minimum": 0, "maximum": 10 } }, "required": [ "adults", "children", "infants", "pets" ] } }, "required": [ "listingId", "checkIn", "checkOut", "party" ] }, "timeZone": { "type": "string", "minLength": 1 }, "expiresAt": { "type": "string", "format": "date-time" }, "charges": { "type": "object", "properties": { "accommodation": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "fees": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "cleaning": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "taxes": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "total": { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, "dueNow": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "schedule": { "type": "array", "items": { "type": "object", "properties": { "dueOn": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "amount": { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] } }, "required": [ "dueOn", "amount" ] } } }, "required": [ "accommodation", "fees", "cleaning", "taxes", "total", "dueNow", "schedule" ] }, "terms": { "type": "object", "properties": { "version": { "type": "string", "minLength": 1 }, "policies": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "body": { "type": "string" } }, "required": [ "label", "body" ] } } }, "required": [ "version", "policies" ] }, "nextActions": { "type": "array", "items": { "enum": [ "create_checkout", "refresh_quote" ], "type": "string" } }, "meta": { "type": "object", "properties": { "asOf": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completeness": { "enum": [ "complete", "partial", "unavailable" ], "type": "string" }, "definitionVersion": { "type": "string", "minLength": 1 }, "sections": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "asOf": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completeness": { "enum": [ "complete", "partial", "unavailable" ], "type": "string" } }, "required": [ "asOf", "completeness" ] } } }, "required": [ "asOf", "completeness", "definitionVersion" ] } }, "required": [ "quoteId", "selection", "timeZone", "expiresAt", "charges", "terms", "nextActions", "meta" ] }, "state": { "enum": [ "needs_guest", "needs_payment", "ready", "pending", "requires_action", "uncertain", "confirmed", "failed", "expired" ], "type": "string" }, "guestComplete": { "type": "boolean" }, "paymentReady": { "type": "boolean" }, "paymentSetup": { "anyOf": [ { "type": "object", "properties": { "state": { "enum": [ "requested", "ready", "failed" ], "type": "string" }, "kind": { "enum": [ "stripe", "simulation" ], "type": "string" }, "setupReference": { "type": "string", "minLength": 1 }, "publishableKey": { "type": "string", "pattern": "^pk_(test|live)_" }, "clientSecret": { "type": "string", "minLength": 1 }, "failure": { "enum": [ "unsupported", "not_authorized", "unavailable", "unresolved" ], "type": "string" } }, "required": [ "state" ] }, { "type": "null" } ] }, "settlement": { "type": "object", "properties": { "kind": { "enum": [ "card", "partner" ], "type": "string" } }, "required": [ "kind" ], "description": "Who settles the checkout. card: the guest pays by card through the payment steps. partner: your organization collects the guest's payment under its agreement, so the checkout skips the payment steps." }, "nextActions": { "type": "array", "items": { "enum": [ "save_guest", "setup_payment", "verify_payment", "submit", "poll", "refresh_quote", "view_confirmation", "contact_support" ], "type": "string" } }, "failure": { "type": "object", "properties": { "reason": { "enum": [ "sold_out", "quote_expired", "price_changed", "policy_changed", "authority_revoked", "refused" ], "type": "string", "description": "Why the checkout ended without a reservation. sold_out: the home is no longer available for these dates. quote_expired: the quote expired before the reservation was made. price_changed: the price changed since the quote. policy_changed: the home's terms changed since the quote. authority_revoked: your application's permission to book was withdrawn before a reservation was attempted. refused: the reservation was refused. In every case no reservation was made; quote again to retry." } }, "required": [ "reason" ] } }, "required": [ "checkoutId", "version", "quote", "state", "guestComplete", "paymentReady", "paymentSetup", "settlement", "nextActions" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "forbidden" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "conflict", "invalid_state", "quote_expired" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "412": { "description": "412", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "precondition_failed" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "422": { "description": "422", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "payment_not_required" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "internal" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unavailable", "not_configured" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unresolved" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } } }, "security": [ { "Application": [], "SessionCapability": [] } ] } }, "/v1/checkouts/{checkoutId}/submit": { "post": { "operationId": "reservation.checkout.submit", "summary": "Request the reservation", "description": "Accepts the current terms and requests the reservation. The outcome arrives asynchronously: poll the status, never submit a new checkout. A card checkout is ready to submit once its payment method is verified; a partner-settled checkout once the guest's details are saved.", "tags": [ "reservation" ], "parameters": [ { "name": "checkoutId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Booking-Consumer", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "web", "agent", "cli", "staff" ] }, "description": "Host-reported measurement provenance; not consent, identity or authority. Missing provenance stays unknown." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0 }, "termsVersion": { "type": "string", "minLength": 1, "maxLength": 128 }, "termsAccepted": { "const": true } }, "required": [ "expectedVersion", "termsVersion", "termsAccepted" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "checkoutId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0 }, "state": { "enum": [ "needs_guest", "needs_payment", "ready", "pending", "requires_action", "uncertain", "confirmed", "failed", "expired" ], "type": "string" }, "nextActions": { "type": "array", "items": { "enum": [ "save_guest", "setup_payment", "verify_payment", "submit", "poll", "refresh_quote", "view_confirmation", "contact_support" ], "type": "string" } }, "pollAfterSeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 60 }, { "type": "null" } ] }, "failure": { "type": "object", "properties": { "reason": { "enum": [ "sold_out", "quote_expired", "price_changed", "policy_changed", "authority_revoked", "refused" ], "type": "string", "description": "Why the checkout ended without a reservation. sold_out: the home is no longer available for these dates. quote_expired: the quote expired before the reservation was made. price_changed: the price changed since the quote. policy_changed: the home's terms changed since the quote. authority_revoked: your application's permission to book was withdrawn before a reservation was attempted. refused: the reservation was refused. In every case no reservation was made; quote again to retry." } }, "required": [ "reason" ] } }, "required": [ "checkoutId", "version", "state", "nextActions", "pollAfterSeconds" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "forbidden" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "conflict", "invalid_state", "quote_expired" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "412": { "description": "412", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "precondition_failed" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "internal" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unavailable", "not_configured" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unresolved" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } } }, "security": [ { "Application": [], "SessionCapability": [] } ] } }, "/v1/checkouts/{checkoutId}/status": { "get": { "operationId": "reservation.checkout.getStatus", "summary": "Read a checkout's status", "description": "A pure read: it never advances, retries or expires the checkout.", "tags": [ "reservation" ], "parameters": [ { "name": "checkoutId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Booking-Consumer", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "web", "agent", "cli", "staff" ] }, "description": "Host-reported measurement provenance; not consent, identity or authority. Missing provenance stays unknown." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "checkoutId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0 }, "state": { "enum": [ "needs_guest", "needs_payment", "ready", "pending", "requires_action", "uncertain", "confirmed", "failed", "expired" ], "type": "string" }, "nextActions": { "type": "array", "items": { "enum": [ "save_guest", "setup_payment", "verify_payment", "submit", "poll", "refresh_quote", "view_confirmation", "contact_support" ], "type": "string" } }, "pollAfterSeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 60 }, { "type": "null" } ] }, "failure": { "type": "object", "properties": { "reason": { "enum": [ "sold_out", "quote_expired", "price_changed", "policy_changed", "authority_revoked", "refused" ], "type": "string", "description": "Why the checkout ended without a reservation. sold_out: the home is no longer available for these dates. quote_expired: the quote expired before the reservation was made. price_changed: the price changed since the quote. policy_changed: the home's terms changed since the quote. authority_revoked: your application's permission to book was withdrawn before a reservation was attempted. refused: the reservation was refused. In every case no reservation was made; quote again to retry." } }, "required": [ "reason" ] } }, "required": [ "checkoutId", "version", "state", "nextActions", "pollAfterSeconds" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "forbidden" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "conflict", "invalid_state" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "412": { "description": "412", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "precondition_failed" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "internal" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unavailable" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unresolved" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } } }, "security": [ { "Application": [], "SessionCapability": [] } ] } }, "/v1/checkouts/{checkoutId}/confirmation": { "get": { "operationId": "reservation.checkout.getConfirmation", "summary": "Read a checkout's confirmation", "tags": [ "reservation" ], "parameters": [ { "name": "checkoutId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Booking-Consumer", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "web", "agent", "cli", "staff" ] }, "description": "Host-reported measurement provenance; not consent, identity or authority. Missing provenance stays unknown." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "checkoutId": { "type": "string", "format": "uuid" }, "reference": { "type": "string" }, "state": { "const": "confirmed" }, "selection": { "type": "object", "properties": { "listingId": { "type": "string", "format": "uuid" }, "checkIn": { "type": "string", "format": "date" }, "checkOut": { "type": "string", "format": "date" }, "party": { "type": "object", "properties": { "adults": { "type": "integer", "minimum": 1, "maximum": 30 }, "children": { "type": "integer", "minimum": 0, "maximum": 29 }, "infants": { "type": "integer", "minimum": 0, "maximum": 10 }, "pets": { "type": "integer", "minimum": 0, "maximum": 10 } }, "required": [ "adults", "children", "infants", "pets" ] } }, "required": [ "listingId", "checkIn", "checkOut", "party" ] }, "charges": { "type": "object", "properties": { "accommodation": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "fees": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "cleaning": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "taxes": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "total": { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, "dueNow": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "schedule": { "type": "array", "items": { "type": "object", "properties": { "dueOn": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "amount": { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] } }, "required": [ "dueOn", "amount" ] } } }, "required": [ "accommodation", "fees", "cleaning", "taxes", "total", "dueNow", "schedule" ] }, "materialization": { "enum": [ "pending", "ready" ], "type": "string" }, "confirmedAt": { "type": "string", "format": "date-time" } }, "required": [ "checkoutId", "reference", "state", "selection", "charges", "materialization", "confirmedAt" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "forbidden" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "conflict", "invalid_state" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "412": { "description": "412", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "precondition_failed" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "internal" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unavailable" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unresolved" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } } }, "security": [ { "Application": [], "SessionCapability": [] } ] } }, "/v1/reservations/{reference}": { "get": { "operationId": "reservation.reservation.get", "summary": "Read a reservation", "description": "A reservation your application's checkout made, by its confirmation reference, as Brightwild holds it now: state, dates, party and charges, including changes the reservations team made. Read it after a webhook. A reference your application did not reserve is not_found.", "tags": [ "reservation" ], "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" } }, { "name": "X-Booking-Consumer", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "web", "agent", "cli", "staff" ] }, "description": "Host-reported measurement provenance; not consent, identity or authority. Missing provenance stays unknown." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" }, "checkoutId": { "type": "string", "format": "uuid" }, "state": { "enum": [ "confirmed", "cancelled", "pending" ], "type": "string" }, "listingId": { "type": "string", "format": "uuid" }, "checkIn": { "type": "string", "format": "date" }, "checkOut": { "type": "string", "format": "date" }, "party": { "type": "object", "properties": { "adults": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "children": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "infants": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "pets": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "adults", "children", "infants", "pets" ] }, "charges": { "type": "object", "properties": { "accommodation": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "cleaning": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "fees": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "taxes": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] }, "total": { "anyOf": [ { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "amountMinor", "currency" ] }, { "type": "null" } ] } }, "required": [ "accommodation", "cleaning", "fees", "taxes", "total" ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time" }, "materialization": { "enum": [ "pending", "ready" ], "type": "string" } }, "required": [ "reference", "checkoutId", "state", "listingId", "checkIn", "checkOut", "party", "charges", "cancelledAt", "updatedAt", "materialization" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "forbidden" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "conflict", "invalid_state" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "412": { "description": "412", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "precondition_failed" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "internal" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unavailable" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unresolved" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } } } } }, "/v1/reservation-requests": { "post": { "operationId": "reservation.reservationRequest.create", "summary": "Request a reservation", "description": "Requests the reservation for an accepted quote and its guest in one call, for an application whose partner collects the guest's payment. The quote fixes the home, dates, party and price. A quote backs one reservation: a request on a quote another request or checkout already uses is a conflict, whatever its ID. The outcome arrives asynchronously: read the request until it leaves pending, and never create another request for the same home and dates while one is pending or unresolved.", "tags": [ "reservation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reservationRequestId": { "type": "string", "format": "uuid" }, "quoteId": { "type": "string", "format": "uuid" }, "termsVersion": { "type": "string", "minLength": 1, "maxLength": 128 }, "termsAccepted": { "const": true }, "guest": { "type": "object", "properties": { "firstName": { "type": "string", "minLength": 1, "maxLength": 100 }, "lastName": { "type": "string", "minLength": 1, "maxLength": 100 }, "email": { "type": "string", "maxLength": 254, "format": "email" }, "phone": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$" } }, "required": [ "firstName", "lastName", "email", "phone" ], "additionalProperties": false }, "partnerReference": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "description": "Your own reference for the request, such as your order or confirmation number. Unique among your application's requests: another request with the same partnerReference is a conflict, and you can find a request by it." }, "journey": { "type": "object", "properties": { "visitorId": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string", "format": "uuid" }, "consent": { "enum": [ "not_required", "granted", "denied" ], "type": "string" }, "userAgent": { "type": "string", "maxLength": 512 }, "campaign": { "type": "object", "properties": { "channel": { "type": "string", "minLength": 1, "maxLength": 200 }, "utmSource": { "type": "string", "minLength": 1, "maxLength": 200 }, "utmMedium": { "type": "string", "minLength": 1, "maxLength": 200 }, "utmCampaign": { "type": "string", "minLength": 1, "maxLength": 200 }, "utmContent": { "type": "string", "minLength": 1, "maxLength": 200 }, "utmTerm": { "type": "string", "minLength": 1, "maxLength": 200 }, "advertisingClickIds": { "type": "object", "properties": { "dclid": { "type": "string", "minLength": 1, "maxLength": 200 }, "fbclid": { "type": "string", "minLength": 1, "maxLength": 200 }, "gbraid": { "type": "string", "minLength": 1, "maxLength": 200 }, "gclid": { "type": "string", "minLength": 1, "maxLength": 200 }, "li_fat_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "msclkid": { "type": "string", "minLength": 1, "maxLength": 200 }, "ttclid": { "type": "string", "minLength": 1, "maxLength": 200 }, "wbraid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false } }, "additionalProperties": false }, "correlationId": { "type": "string", "format": "uuid" }, "route": { "enum": [ "home", "search", "listing", "checkout", "confirmation" ], "type": "string" }, "referrerOrigin": { "type": "string", "maxLength": 256, "format": "uri" }, "deviceClass": { "enum": [ "mobile", "tablet", "desktop", "unknown" ], "type": "string" } }, "required": [ "visitorId", "consent" ], "additionalProperties": false } }, "required": [ "reservationRequestId", "quoteId", "termsVersion", "termsAccepted", "guest" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "reservationRequestId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0 }, "state": { "enum": [ "pending", "unresolved", "confirmed", "failed" ], "type": "string", "description": "pending: the reservation is being made. unresolved: Brightwild cannot yet tell whether it was made and is reconciling it; never create another request for the same home and dates. confirmed: the reservation was made; read it by reference. failed: no reservation was made." }, "quoteId": { "type": "string", "format": "uuid" }, "partnerReference": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "description": "Your own reference for the request, such as your order or confirmation number. Unique among your application's requests: another request with the same partnerReference is a conflict, and you can find a request by it." }, { "type": "null" } ] }, "reference": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" }, { "type": "null" } ] }, "nextActions": { "type": "array", "items": { "enum": [ "poll", "view_reservation", "create_quote", "contact_support" ], "type": "string" } }, "pollAfterSeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 60 }, { "type": "null" } ] }, "failure": { "type": "object", "properties": { "reason": { "enum": [ "sold_out", "quote_expired", "price_changed", "policy_changed", "authority_revoked", "refused" ], "type": "string", "description": "Why the checkout ended without a reservation. sold_out: the home is no longer available for these dates. quote_expired: the quote expired before the reservation was made. price_changed: the price changed since the quote. policy_changed: the home's terms changed since the quote. authority_revoked: your application's permission to book was withdrawn before a reservation was attempted. refused: the reservation was refused. In every case no reservation was made; quote again to retry." } }, "required": [ "reason" ] } }, "required": [ "reservationRequestId", "version", "state", "quoteId", "partnerReference", "reference", "nextActions", "pollAfterSeconds" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "forbidden" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "conflict", "invalid_state", "quote_expired" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "412": { "description": "412", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "precondition_failed" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "422": { "description": "422", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "policy_restricted" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "internal" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unavailable", "not_configured" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unresolved" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } } }, "parameters": [ { "name": "X-Booking-Consumer", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "web", "agent", "cli", "staff" ] }, "description": "Host-reported measurement provenance; not consent, identity or authority. Missing provenance stays unknown." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,255}$" }, "description": "For a caller that cannot send the new resource's ID: the API derives the ID from the key. Send one or the other." } ] }, "get": { "operationId": "reservation.reservationRequest.list", "summary": "List reservation requests", "description": "Your application's reservation requests, newest first, each with its outcome so far. Filter by partnerReference to find the request you named with it, such as after a lost response.", "tags": [ "reservation" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^[A-Za-z0-9_-]+$" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "partnerReference", "in": "query", "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "description": "Your own reference for the request, such as your order or confirmation number. Unique among your application's requests: another request with the same partnerReference is a conflict, and you can find a request by it." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Booking-Consumer", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "web", "agent", "cli", "staff" ] }, "description": "Host-reported measurement provenance; not consent, identity or authority. Missing provenance stays unknown." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "reservationRequestId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0 }, "state": { "enum": [ "pending", "unresolved", "confirmed", "failed" ], "type": "string", "description": "pending: the reservation is being made. unresolved: Brightwild cannot yet tell whether it was made and is reconciling it; never create another request for the same home and dates. confirmed: the reservation was made; read it by reference. failed: no reservation was made." }, "quoteId": { "type": "string", "format": "uuid" }, "partnerReference": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "description": "Your own reference for the request, such as your order or confirmation number. Unique among your application's requests: another request with the same partnerReference is a conflict, and you can find a request by it." }, { "type": "null" } ] }, "reference": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" }, { "type": "null" } ] }, "nextActions": { "type": "array", "items": { "enum": [ "poll", "view_reservation", "create_quote", "contact_support" ], "type": "string" } }, "pollAfterSeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 60 }, { "type": "null" } ] }, "failure": { "type": "object", "properties": { "reason": { "enum": [ "sold_out", "quote_expired", "price_changed", "policy_changed", "authority_revoked", "refused" ], "type": "string", "description": "Why the checkout ended without a reservation. sold_out: the home is no longer available for these dates. quote_expired: the quote expired before the reservation was made. price_changed: the price changed since the quote. policy_changed: the home's terms changed since the quote. authority_revoked: your application's permission to book was withdrawn before a reservation was attempted. refused: the reservation was refused. In every case no reservation was made; quote again to retry." } }, "required": [ "reason" ] } }, "required": [ "reservationRequestId", "version", "state", "quoteId", "partnerReference", "reference", "nextActions", "pollAfterSeconds" ] } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "forbidden" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "conflict", "invalid_state" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "412": { "description": "412", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "precondition_failed" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "internal" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unavailable" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unresolved" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } } } } }, "/v1/reservation-requests/{reservationRequestId}": { "get": { "operationId": "reservation.reservationRequest.get", "summary": "Read a reservation request", "description": "A reservation request your application made, and its outcome so far. A pure read: it never advances or retries the request. A request your application did not make is not_found.", "tags": [ "reservation" ], "parameters": [ { "name": "reservationRequestId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Booking-Consumer", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "web", "agent", "cli", "staff" ] }, "description": "Host-reported measurement provenance; not consent, identity or authority. Missing provenance stays unknown." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "reservationRequestId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0 }, "state": { "enum": [ "pending", "unresolved", "confirmed", "failed" ], "type": "string", "description": "pending: the reservation is being made. unresolved: Brightwild cannot yet tell whether it was made and is reconciling it; never create another request for the same home and dates. confirmed: the reservation was made; read it by reference. failed: no reservation was made." }, "quoteId": { "type": "string", "format": "uuid" }, "partnerReference": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "description": "Your own reference for the request, such as your order or confirmation number. Unique among your application's requests: another request with the same partnerReference is a conflict, and you can find a request by it." }, { "type": "null" } ] }, "reference": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" }, { "type": "null" } ] }, "nextActions": { "type": "array", "items": { "enum": [ "poll", "view_reservation", "create_quote", "contact_support" ], "type": "string" } }, "pollAfterSeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 60 }, { "type": "null" } ] }, "failure": { "type": "object", "properties": { "reason": { "enum": [ "sold_out", "quote_expired", "price_changed", "policy_changed", "authority_revoked", "refused" ], "type": "string", "description": "Why the checkout ended without a reservation. sold_out: the home is no longer available for these dates. quote_expired: the quote expired before the reservation was made. price_changed: the price changed since the quote. policy_changed: the home's terms changed since the quote. authority_revoked: your application's permission to book was withdrawn before a reservation was attempted. refused: the reservation was refused. In every case no reservation was made; quote again to retry." } }, "required": [ "reason" ] } }, "required": [ "reservationRequestId", "version", "state", "quoteId", "partnerReference", "reference", "nextActions", "pollAfterSeconds" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "forbidden" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "conflict", "invalid_state" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "412": { "description": "412", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "precondition_failed" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "internal" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unavailable" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unresolved" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } } } } }, "/v1/events": { "get": { "operationId": "reservation.event.list", "summary": "Read the event feed", "description": "The webhook events your application was sent, in the order Brightwild recorded them, for the last 30 days: the same events, with the same IDs, as the webhooks. Read it to catch up after an outage, passing the nextCursor of your last read. An event can appear in the feed and as a webhook; deduplicate by its id.", "tags": [ "reservation" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "^[A-Za-z0-9_-]+$" }, "allowEmptyValue": true, "allowReserved": true }, { "name": "X-Booking-Consumer", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "web", "agent", "cli", "staff" ] }, "description": "Host-reported measurement provenance; not consent, identity or authority. Missing provenance stays unknown." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "type": { "const": "reservation.confirmed" }, "schemaVersion": { "const": 1 }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "reference": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" }, "checkoutId": { "type": "string", "format": "uuid" }, "state": { "const": "confirmed" }, "confirmedAt": { "type": "string", "format": "date-time" } }, "required": [ "reference", "checkoutId", "state", "confirmedAt" ] } }, "required": [ "id", "type", "schemaVersion", "timestamp", "data" ] }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "type": { "const": "reservation.cancelled" }, "schemaVersion": { "const": 1 }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "reference": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" }, "checkoutId": { "type": "string", "format": "uuid" }, "state": { "const": "cancelled" }, "cancelledAt": { "type": "string", "format": "date-time" } }, "required": [ "reference", "checkoutId", "state", "cancelledAt" ] } }, "required": [ "id", "type", "schemaVersion", "timestamp", "data" ] }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "type": { "const": "reservation.changed" }, "schemaVersion": { "const": 1 }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "reference": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" }, "checkoutId": { "type": "string", "format": "uuid" }, "state": { "enum": [ "confirmed", "cancelled", "pending" ], "type": "string" }, "changes": { "type": "array", "minItems": 1, "items": { "enum": [ "dates", "party", "price", "listing" ], "type": "string" } }, "changedAt": { "type": "string", "format": "date-time" } }, "required": [ "reference", "checkoutId", "state", "changes", "changedAt" ] } }, "required": [ "id", "type", "schemaVersion", "timestamp", "data" ] }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$" }, "type": { "const": "checkout.resolved" }, "schemaVersion": { "const": 1 }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "checkoutId": { "type": "string", "format": "uuid" }, "state": { "enum": [ "confirmed", "failed", "expired" ], "type": "string" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "exclusiveMinimum": 0 }, "reference": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" }, { "type": "null" } ] }, "resolvedAt": { "type": "string", "format": "date-time" } }, "required": [ "checkoutId", "state", "version", "reference", "resolvedAt" ] } }, "required": [ "id", "type", "schemaVersion", "timestamp", "data" ] } ] } }, "nextCursor": { "type": "string", "minLength": 1, "maxLength": 1024 }, "hasMore": { "type": "boolean" } }, "required": [ "items", "nextCursor", "hasMore" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "forbidden" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "conflict", "invalid_state" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "412": { "description": "412", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "precondition_failed" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "422": { "description": "422", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "resync_required" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "internal" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unavailable" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unresolved" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } } } } }, "/v1/signals": { "post": { "operationId": "cdp.signal.capture", "summary": "Record a journey signal", "description": "One visitor journey observation. `signalId` is the client's event ID: a repeat records nothing more. A signal that names a checkout needs that checkout's session capability.", "tags": [ "cdp" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signalId": { "type": "string", "format": "uuid" }, "event": { "enum": [ "listing_viewed", "search_submitted", "search_viewed", "quote_viewed", "reserve_clicked", "checkout_started", "details_completed", "payment_submitted", "confirmation_viewed" ], "type": "string" }, "visitorId": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string", "format": "uuid" }, "consent": { "enum": [ "not_required", "granted", "denied" ], "type": "string" }, "userAgent": { "type": "string", "maxLength": 512 }, "campaign": { "type": "object", "properties": { "channel": { "type": "string", "minLength": 1, "maxLength": 200 }, "utmSource": { "type": "string", "minLength": 1, "maxLength": 200 }, "utmMedium": { "type": "string", "minLength": 1, "maxLength": 200 }, "utmCampaign": { "type": "string", "minLength": 1, "maxLength": 200 }, "utmContent": { "type": "string", "minLength": 1, "maxLength": 200 }, "utmTerm": { "type": "string", "minLength": 1, "maxLength": 200 }, "advertisingClickIds": { "type": "object", "properties": { "dclid": { "type": "string", "minLength": 1, "maxLength": 200 }, "fbclid": { "type": "string", "minLength": 1, "maxLength": 200 }, "gbraid": { "type": "string", "minLength": 1, "maxLength": 200 }, "gclid": { "type": "string", "minLength": 1, "maxLength": 200 }, "li_fat_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "msclkid": { "type": "string", "minLength": 1, "maxLength": 200 }, "ttclid": { "type": "string", "minLength": 1, "maxLength": 200 }, "wbraid": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false } }, "additionalProperties": false }, "correlationId": { "type": "string", "format": "uuid" }, "route": { "enum": [ "home", "search", "listing", "checkout", "confirmation" ], "type": "string" }, "referrerOrigin": { "type": "string", "maxLength": 256, "format": "uri" }, "deviceClass": { "enum": [ "mobile", "tablet", "desktop", "unknown" ], "type": "string" }, "listingId": { "type": "string", "format": "uuid" }, "quoteId": { "type": "string", "format": "uuid" }, "checkoutId": { "type": "string", "format": "uuid" }, "searchObservationId": { "type": "string", "format": "uuid" }, "occurredAt": { "type": "string", "format": "date-time" }, "search": { "type": "object", "properties": { "checkIn": { "type": "string", "format": "date" }, "checkOut": { "type": "string", "format": "date" }, "party": { "type": "object", "properties": { "adults": { "type": "integer", "minimum": 1, "maximum": 30 }, "children": { "type": "integer", "minimum": 0, "maximum": 29 }, "infants": { "type": "integer", "minimum": 0, "maximum": 10 }, "pets": { "type": "integer", "minimum": 0, "maximum": 10 } }, "required": [ "adults", "children", "infants", "pets" ], "additionalProperties": false }, "collectionId": { "type": "string", "format": "uuid" } }, "required": [ "checkIn", "checkOut", "party" ], "additionalProperties": false } }, "required": [ "signalId", "event", "visitorId", "consent" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean" } }, "required": [ "accepted" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "invalid_input" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "forbidden" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "conflict", "invalid_state" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "412": { "description": "412", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "precondition_failed" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "429": { "description": "429", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "internal" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unavailable" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "type": "string", "enum": [ "unresolved" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 }, "details": { "type": "object", "additionalProperties": true } } } } } } } } }, "parameters": [ { "name": "X-Booking-Consumer", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "web", "agent", "cli", "staff" ] }, "description": "Host-reported measurement provenance; not consent, identity or authority. Missing provenance stays unknown." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[\\x21-\\x7e]{1,255}$" }, "description": "For a caller that cannot send the new resource's ID: the API derives the ID from the key. Send one or the other." }, { "name": "Session-Capability", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required when checkoutId is supplied: the checkout's session capability." } ] } } } }