{ "openapi": "3.1.0", "info": { "title": "Maple Developer API", "version": "0.0.1", "description": "Public API for POS and platform partners to integrate with Maple: granted locations and connections, the order loop (validation, notification, accept/deny, status updates), payment-link visibility, menu publishing, and HMAC-signed webhooks. Authenticate every request with a Bearer API key (`mpk_test_…` / `mpk_live_…`). The credential determines the environment: test-mode credentials only see test data, live-mode credentials only see live data." }, "paths": { "/ping": { "get": { "tags": ["General"], "operationId": "developer-api.ping", "parameters": [], "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["developer_api_status"] }, "status": { "type": "string", "enum": ["ok"] }, "version": { "type": "string" } }, "required": ["object", "status", "version"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } } }, "description": "Unauthenticated readiness probe for the Developer API.", "summary": "Developer API status" } }, "/me": { "get": { "tags": ["General"], "operationId": "developer-api.me", "parameters": [], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["developer_app"] }, "id": { "type": "string" }, "name": { "type": "string" }, "environment": { "type": "string", "enum": ["test", "live"] }, "scopes": { "type": "array", "items": { "type": "string" } } }, "required": ["object", "id", "name", "environment", "scopes"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Returns the developer app and effective scopes for the authenticated credential.", "summary": "Current app" } }, "/locations": { "get": { "tags": ["Locations"], "operationId": "developer-api.listLocations", "parameters": [], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": ["location"] }, "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": ["active", "inactive", "paused"] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postal_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["line1", "line2", "city", "region", "postal_code", "country"], "additionalProperties": false } }, "required": ["object", "id", "name", "status", "timezone", "phone", "address"], "additionalProperties": false } } }, "required": ["object", "data"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Lists the locations the authenticated app has been granted access to.", "summary": "List locations" } }, "/locations/{locationId}": { "get": { "tags": ["Locations"], "operationId": "developer-api.getLocation", "parameters": [ { "name": "locationId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["location"] }, "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": ["active", "inactive", "paused"] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "type": "object", "properties": { "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postal_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["line1", "line2", "city", "region", "postal_code", "country"], "additionalProperties": false } }, "required": ["object", "id", "name", "status", "timezone", "phone", "address"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Returns a single location the authenticated app has been granted access to.", "summary": "Get location" } }, "/locations/{locationId}/connection": { "post": { "tags": ["Connections"], "operationId": "developer-api.createConnection", "parameters": [ { "name": "locationId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["connection"] }, "location_id": { "type": "string" }, "status": { "type": "string", "enum": ["active", "inactive"] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": ["object", "location_id", "status", "created_at", "updated_at"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "409": { "description": "DeveloperApiConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiConflict" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Connects the app to a granted location as its POS receiver, provisioning and activating the integration.", "summary": "Create connection" }, "get": { "tags": ["Connections"], "operationId": "developer-api.getConnection", "parameters": [ { "name": "locationId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["connection"] }, "location_id": { "type": "string" }, "status": { "type": "string", "enum": ["active", "inactive"] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": ["object", "location_id", "status", "created_at", "updated_at"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Returns the app's connection to a granted location, if one exists.", "summary": "Get connection" }, "delete": { "tags": ["Connections"], "operationId": "developer-api.deleteConnection", "parameters": [ { "name": "locationId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["connection.deleted"] }, "location_id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [true] } }, "required": ["object", "location_id", "deleted"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Disconnects the app from a location, removing the Developer API connection (the location can then be connected to a different POS).", "summary": "Delete connection" } }, "/locations/{locationId}/menu": { "get": { "tags": ["Menu"], "operationId": "developer-api.getLocationMenu", "parameters": [ { "name": "locationId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "catalogId": { "type": "string" }, "storePublicId": { "type": "string" }, "versionId": { "type": "string" }, "currency": { "type": "string" }, "locale": { "type": "string" }, "timezone": { "type": "string" }, "currencies": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "exponent": { "type": "integer" }, "cashRoundingMinor": { "type": "integer" }, "roundingMode": { "type": "string", "enum": ["half_up", "half_even", "half_down", "up", "down", "ceiling", "floor"] } }, "required": ["currency"], "additionalProperties": false } }, "taxCategories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" } }, "required": ["name"], "additionalProperties": false } }, "taxRates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "taxCategoryId": { "type": "string" }, "method": { "type": "string", "enum": ["percentage", "flat", "bracket"] }, "percentage": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "flatAmount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "brackets": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "to": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "tax": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false } }, "required": ["from", "tax"], "additionalProperties": false } }, "base": { "type": "string", "enum": [ "price", "price_plus_prior_taxes", "weight", "volume", "quantity", "alcohol_content" ] }, "inclusion": { "type": "string", "enum": ["exclusive", "inclusive", "context_resolved"] }, "compoundOnTaxRateIds": { "type": "array", "items": { "type": "string" } }, "tenderExemptions": { "type": "array", "items": { "type": "string", "enum": ["ebt", "snap", "wic"] } }, "condition": { "type": "object", "properties": { "minPrice": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "maxPrice": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "jurisdiction": { "type": "string" }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": ["key", "value"], "additionalProperties": false } } }, "additionalProperties": false }, "hiddenFromCustomer": { "type": "boolean" } }, "required": ["name"], "additionalProperties": false } }, "fees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "feeType": { "type": "string", "enum": [ "delivery", "service_charge", "bag", "bottle_deposit", "crv", "small_order", "processing_pass_through", "deposit", "security_hold", "no_show_fee", "cancellation_fee", "auto_gratuity", "non_cash_adjustment", "other" ] }, "calculation": { "type": "object", "properties": { "base": { "type": "string", "enum": [ "flat", "per_unit", "percentage_of_line", "percentage_of_subtotal", "post_discount", "post_tax_total" ] }, "amount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "percentage": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "eligibleProductSetId": { "type": "string" }, "excludedProductSetIds": { "type": "array", "items": { "type": "string" } } }, "required": ["base"], "additionalProperties": false }, "taxCategoryId": { "type": "string" }, "refundable": { "type": "boolean" }, "autoApply": { "type": "object", "properties": { "byGuestCountGte": { "type": "integer" }, "byFulfillmentMode": { "type": "array", "items": { "type": "string", "enum": ["dine_in", "takeout", "delivery", "pickup", "curbside", "shipping"] } } }, "additionalProperties": false }, "containers": { "type": "array", "items": { "type": "object", "properties": { "containerSizeMl": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "amount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false } }, "required": ["amount"], "additionalProperties": false } } }, "required": ["name", "feeType", "calculation"], "additionalProperties": false } }, "productSets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "itemIdsAny": { "type": "array", "items": { "type": "string" } }, "itemIdsAll": { "type": "array", "items": { "type": "string" } }, "allProducts": { "type": "boolean" }, "quantityExact": { "type": "integer" }, "quantityMin": { "type": "integer" }, "quantityMax": { "type": "integer" } }, "additionalProperties": false } }, "discounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "benefitType": { "type": "string", "enum": ["percentage", "amount", "set_price", "free_item", "bxgy", "free_fee"] }, "amount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "percentage": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "maximumAmount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "benefitTargetProductSetId": { "type": "string" }, "lineSelection": { "type": "string", "enum": ["least_expensive", "most_expensive"] }, "bxgy": { "type": "object", "properties": { "buyProductSetId": { "type": "string" }, "buyQuantity": { "type": "integer" }, "getProductSetId": { "type": "string" }, "getQuantity": { "type": "integer" }, "getBenefit": { "type": "string", "enum": ["free", "percentage", "set_price", "amount"] }, "getBenefitAmount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "getBenefitPercentage": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "customerChoosesReward": { "type": "boolean" }, "excludeStrategy": { "type": "string", "enum": ["least_expensive", "most_expensive"] } }, "required": [ "buyProductSetId", "buyQuantity", "getProductSetId", "getQuantity", "getBenefit" ], "additionalProperties": false }, "freeFeeTargets": { "type": "array", "items": { "type": "string", "enum": [ "delivery", "service_charge", "bag", "bottle_deposit", "crv", "small_order", "processing_pass_through", "deposit", "security_hold", "no_show_fee", "cancellation_fee", "auto_gratuity", "non_cash_adjustment", "other" ] } }, "modifiesTaxBasis": { "type": "boolean" } }, "required": ["name", "benefitType"], "additionalProperties": false } }, "promotions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "discountId": { "type": "string" }, "applicationMode": { "type": "string", "enum": ["automatic", "coupon", "manual"] }, "eligibility": { "type": "object", "properties": { "minimumOrderSubtotal": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "matchProductSetId": { "type": "string" }, "excludeProductSetId": { "type": "string" } }, "additionalProperties": false }, "availability": { "type": "object", "properties": { "windows": { "type": "array", "items": { "type": "object", "properties": { "dayOfWeek": { "type": "integer" }, "startTime": { "type": "string" }, "endTime": { "type": "string" } }, "required": ["dayOfWeek", "startTime", "endTime"], "additionalProperties": false } } }, "required": ["windows"], "additionalProperties": false }, "validFrom": { "type": "string" }, "validUntil": { "type": "string" }, "stacking": { "type": "object", "properties": { "mode": { "type": "string", "enum": ["exclusive", "additive", "best_of", "ordered"] }, "priority": { "type": "integer" } }, "required": ["mode"], "additionalProperties": false }, "redemption": { "type": "object", "properties": { "maxUsesTotal": { "type": "integer" }, "maxUsesPerCustomer": { "type": "integer" } }, "additionalProperties": false } }, "required": ["name", "discountId"], "additionalProperties": false } }, "coupons": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "code": { "type": "string" }, "promotionId": { "type": "string" }, "maxRedemptions": { "type": "integer" }, "perCustomerLimit": { "type": "integer" }, "expiresAt": { "type": "string" } }, "required": ["code", "promotionId"], "additionalProperties": false } }, "modifierGroups": { "type": "array", "items": { "$ref": "#/components/schemas/Suspend_" } }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "availability": { "type": "object", "properties": { "windows": { "type": "array", "items": { "type": "object", "properties": { "dayOfWeek": { "type": "integer" }, "startTime": { "type": "string" }, "endTime": { "type": "string" } }, "required": ["dayOfWeek", "startTime", "endTime"], "additionalProperties": false } } }, "required": ["windows"], "additionalProperties": false }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "variations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "object", "properties": { "amount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "priceType": { "type": "string", "enum": ["fixed", "variable", "per_unit", "bulk"] }, "taxInclusive": { "type": "boolean" }, "currencyPrices": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "taxInclusive": { "type": "boolean" } }, "required": ["amount"], "additionalProperties": false } }, "openBounds": { "type": "object", "properties": { "min": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "max": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "presets": { "type": "array", "items": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false } } }, "additionalProperties": false }, "bulkTiers": { "type": "array", "items": { "type": "object", "properties": { "minQuantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false } }, "required": ["minQuantity", "unitPrice"], "additionalProperties": false } }, "measurementUnit": { "type": "object", "properties": { "unit": { "type": "string" }, "precision": { "type": "integer" } }, "required": ["unit"], "additionalProperties": false }, "compareAtAmount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false } }, "additionalProperties": false }, "sku": { "type": "string" }, "barcodes": { "type": "array", "items": { "type": "string" } }, "modifierGroups": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "groupId": { "type": "string" }, "minSelections": { "type": "integer" }, "maxSelections": { "type": "integer" }, "minUniqueSelections": { "type": "integer" }, "maxUniqueSelections": { "type": "integer" }, "freeSelectionCount": { "type": "integer" }, "chargeKeptDefaults": { "type": "boolean" }, "allowedQuantities": { "type": "array", "items": { "type": "integer" } }, "optionDefaults": { "type": "array", "items": { "type": "object", "properties": { "optionId": { "type": "string" }, "defaultQuantity": { "type": "integer" } }, "required": ["optionId", "defaultQuantity"], "additionalProperties": false } }, "externalId": { "not": {} }, "name": { "not": {} }, "options": { "not": {} } }, "required": ["groupId"], "additionalProperties": false }, { "$ref": "#/components/schemas/Suspend_" } ] } }, "dietaryLabels": { "type": "array", "items": { "type": "string" } }, "allergens": { "type": "array", "items": { "type": "string" } }, "calorieCount": { "type": "integer" }, "stockStatus": { "type": "string", "enum": ["in_stock", "out_of_stock", "low_stock"] } }, "required": ["externalId", "name", "price"], "additionalProperties": false } }, "modifierGroups": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "groupId": { "type": "string" }, "minSelections": { "type": "integer" }, "maxSelections": { "type": "integer" }, "minUniqueSelections": { "type": "integer" }, "maxUniqueSelections": { "type": "integer" }, "freeSelectionCount": { "type": "integer" }, "chargeKeptDefaults": { "type": "boolean" }, "allowedQuantities": { "type": "array", "items": { "type": "integer" } }, "optionDefaults": { "type": "array", "items": { "type": "object", "properties": { "optionId": { "type": "string" }, "defaultQuantity": { "type": "integer" } }, "required": ["optionId", "defaultQuantity"], "additionalProperties": false } }, "externalId": { "not": {} }, "name": { "not": {} }, "options": { "not": {} } }, "required": ["groupId"], "additionalProperties": false }, { "$ref": "#/components/schemas/Suspend_" } ] } }, "taxCategoryId": { "type": "string" }, "taxRateIds": { "type": "array", "items": { "type": "string" } }, "feeIds": { "type": "array", "items": { "type": "string" } }, "dietaryLabels": { "type": "array", "items": { "type": "string" } }, "allergens": { "type": "array", "items": { "type": "string" } }, "calorieCount": { "type": "integer" }, "availability": { "type": "object", "properties": { "windows": { "type": "array", "items": { "type": "object", "properties": { "dayOfWeek": { "type": "integer" }, "startTime": { "type": "string" }, "endTime": { "type": "string" } }, "required": ["dayOfWeek", "startTime", "endTime"], "additionalProperties": false } } }, "required": ["windows"], "additionalProperties": false }, "stockStatus": { "type": "string", "enum": ["in_stock", "out_of_stock", "low_stock"] } }, "required": ["externalId", "name", "variations"], "additionalProperties": false } } }, "required": ["externalId", "name", "items"], "additionalProperties": false } } }, "required": [ "catalogId", "storePublicId", "versionId", "currency", "currencies", "taxCategories", "taxRates", "fees", "productSets", "discounts", "promotions", "coupons", "modifierGroups", "categories" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "The location's current published menu: categories, items, and variations (prices in integer minor units), shared modifier groups, and tax/fee/discount definitions. Every object echoes the `externalId` you published it under. Requires `menus:read` and an active connection to the location.", "summary": "Get location menu" }, "post": { "tags": ["Menu"], "operationId": "developer-api.publishLocationMenu", "parameters": [ { "name": "locationId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "catalogId": { "type": "string" }, "storePublicId": { "type": "string" }, "versionId": { "type": "string" }, "currency": { "type": "string" }, "locale": { "type": "string" }, "timezone": { "type": "string" }, "currencies": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "exponent": { "type": "integer" }, "cashRoundingMinor": { "type": "integer" }, "roundingMode": { "type": "string", "enum": ["half_up", "half_even", "half_down", "up", "down", "ceiling", "floor"] } }, "required": ["currency"], "additionalProperties": false } }, "taxCategories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" } }, "required": ["name"], "additionalProperties": false } }, "taxRates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "taxCategoryId": { "type": "string" }, "method": { "type": "string", "enum": ["percentage", "flat", "bracket"] }, "percentage": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "flatAmount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "brackets": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "to": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "tax": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false } }, "required": ["from", "tax"], "additionalProperties": false } }, "base": { "type": "string", "enum": [ "price", "price_plus_prior_taxes", "weight", "volume", "quantity", "alcohol_content" ] }, "inclusion": { "type": "string", "enum": ["exclusive", "inclusive", "context_resolved"] }, "compoundOnTaxRateIds": { "type": "array", "items": { "type": "string" } }, "tenderExemptions": { "type": "array", "items": { "type": "string", "enum": ["ebt", "snap", "wic"] } }, "condition": { "type": "object", "properties": { "minPrice": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "maxPrice": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "jurisdiction": { "type": "string" }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": ["key", "value"], "additionalProperties": false } } }, "additionalProperties": false }, "hiddenFromCustomer": { "type": "boolean" } }, "required": ["name"], "additionalProperties": false } }, "fees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "feeType": { "type": "string", "enum": [ "delivery", "service_charge", "bag", "bottle_deposit", "crv", "small_order", "processing_pass_through", "deposit", "security_hold", "no_show_fee", "cancellation_fee", "auto_gratuity", "non_cash_adjustment", "other" ] }, "calculation": { "type": "object", "properties": { "base": { "type": "string", "enum": [ "flat", "per_unit", "percentage_of_line", "percentage_of_subtotal", "post_discount", "post_tax_total" ] }, "amount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "percentage": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "eligibleProductSetId": { "type": "string" }, "excludedProductSetIds": { "type": "array", "items": { "type": "string" } } }, "required": ["base"], "additionalProperties": false }, "taxCategoryId": { "type": "string" }, "refundable": { "type": "boolean" }, "autoApply": { "type": "object", "properties": { "byGuestCountGte": { "type": "integer" }, "byFulfillmentMode": { "type": "array", "items": { "type": "string", "enum": ["dine_in", "takeout", "delivery", "pickup", "curbside", "shipping"] } } }, "additionalProperties": false }, "containers": { "type": "array", "items": { "type": "object", "properties": { "containerSizeMl": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "amount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false } }, "required": ["amount"], "additionalProperties": false } } }, "required": ["name", "feeType", "calculation"], "additionalProperties": false } }, "productSets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "itemIdsAny": { "type": "array", "items": { "type": "string" } }, "itemIdsAll": { "type": "array", "items": { "type": "string" } }, "allProducts": { "type": "boolean" }, "quantityExact": { "type": "integer" }, "quantityMin": { "type": "integer" }, "quantityMax": { "type": "integer" } }, "additionalProperties": false } }, "discounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "benefitType": { "type": "string", "enum": ["percentage", "amount", "set_price", "free_item", "bxgy", "free_fee"] }, "amount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "percentage": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "maximumAmount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "benefitTargetProductSetId": { "type": "string" }, "lineSelection": { "type": "string", "enum": ["least_expensive", "most_expensive"] }, "bxgy": { "type": "object", "properties": { "buyProductSetId": { "type": "string" }, "buyQuantity": { "type": "integer" }, "getProductSetId": { "type": "string" }, "getQuantity": { "type": "integer" }, "getBenefit": { "type": "string", "enum": ["free", "percentage", "set_price", "amount"] }, "getBenefitAmount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "getBenefitPercentage": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "customerChoosesReward": { "type": "boolean" }, "excludeStrategy": { "type": "string", "enum": ["least_expensive", "most_expensive"] } }, "required": [ "buyProductSetId", "buyQuantity", "getProductSetId", "getQuantity", "getBenefit" ], "additionalProperties": false }, "freeFeeTargets": { "type": "array", "items": { "type": "string", "enum": [ "delivery", "service_charge", "bag", "bottle_deposit", "crv", "small_order", "processing_pass_through", "deposit", "security_hold", "no_show_fee", "cancellation_fee", "auto_gratuity", "non_cash_adjustment", "other" ] } }, "modifiesTaxBasis": { "type": "boolean" } }, "required": ["name", "benefitType"], "additionalProperties": false } }, "promotions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "discountId": { "type": "string" }, "applicationMode": { "type": "string", "enum": ["automatic", "coupon", "manual"] }, "eligibility": { "type": "object", "properties": { "minimumOrderSubtotal": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "matchProductSetId": { "type": "string" }, "excludeProductSetId": { "type": "string" } }, "additionalProperties": false }, "availability": { "type": "object", "properties": { "windows": { "type": "array", "items": { "type": "object", "properties": { "dayOfWeek": { "type": "integer" }, "startTime": { "type": "string" }, "endTime": { "type": "string" } }, "required": ["dayOfWeek", "startTime", "endTime"], "additionalProperties": false } } }, "required": ["windows"], "additionalProperties": false }, "validFrom": { "type": "string" }, "validUntil": { "type": "string" }, "stacking": { "type": "object", "properties": { "mode": { "type": "string", "enum": ["exclusive", "additive", "best_of", "ordered"] }, "priority": { "type": "integer" } }, "required": ["mode"], "additionalProperties": false }, "redemption": { "type": "object", "properties": { "maxUsesTotal": { "type": "integer" }, "maxUsesPerCustomer": { "type": "integer" } }, "additionalProperties": false } }, "required": ["name", "discountId"], "additionalProperties": false } }, "coupons": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "code": { "type": "string" }, "promotionId": { "type": "string" }, "maxRedemptions": { "type": "integer" }, "perCustomerLimit": { "type": "integer" }, "expiresAt": { "type": "string" } }, "required": ["code", "promotionId"], "additionalProperties": false } }, "modifierGroups": { "type": "array", "items": { "$ref": "#/components/schemas/Suspend_" } }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "availability": { "type": "object", "properties": { "windows": { "type": "array", "items": { "type": "object", "properties": { "dayOfWeek": { "type": "integer" }, "startTime": { "type": "string" }, "endTime": { "type": "string" } }, "required": ["dayOfWeek", "startTime", "endTime"], "additionalProperties": false } } }, "required": ["windows"], "additionalProperties": false }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "variations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "object", "properties": { "amount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "priceType": { "type": "string", "enum": ["fixed", "variable", "per_unit", "bulk"] }, "taxInclusive": { "type": "boolean" }, "currencyPrices": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "taxInclusive": { "type": "boolean" } }, "required": ["amount"], "additionalProperties": false } }, "openBounds": { "type": "object", "properties": { "min": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "max": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "presets": { "type": "array", "items": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false } } }, "additionalProperties": false }, "bulkTiers": { "type": "array", "items": { "type": "object", "properties": { "minQuantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false } }, "required": ["minQuantity", "unitPrice"], "additionalProperties": false } }, "measurementUnit": { "type": "object", "properties": { "unit": { "type": "string" }, "precision": { "type": "integer" } }, "required": ["unit"], "additionalProperties": false }, "compareAtAmount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false } }, "additionalProperties": false }, "sku": { "type": "string" }, "barcodes": { "type": "array", "items": { "type": "string" } }, "modifierGroups": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "groupId": { "type": "string" }, "minSelections": { "type": "integer" }, "maxSelections": { "type": "integer" }, "minUniqueSelections": { "type": "integer" }, "maxUniqueSelections": { "type": "integer" }, "freeSelectionCount": { "type": "integer" }, "chargeKeptDefaults": { "type": "boolean" }, "allowedQuantities": { "type": "array", "items": { "type": "integer" } }, "optionDefaults": { "type": "array", "items": { "type": "object", "properties": { "optionId": { "type": "string" }, "defaultQuantity": { "type": "integer" } }, "required": ["optionId", "defaultQuantity"], "additionalProperties": false } }, "externalId": { "not": {} }, "name": { "not": {} }, "options": { "not": {} } }, "required": ["groupId"], "additionalProperties": false }, { "$ref": "#/components/schemas/Suspend_" } ] } }, "dietaryLabels": { "type": "array", "items": { "type": "string" } }, "allergens": { "type": "array", "items": { "type": "string" } }, "calorieCount": { "type": "integer" }, "stockStatus": { "type": "string", "enum": ["in_stock", "out_of_stock", "low_stock"] } }, "required": ["externalId", "name", "price"], "additionalProperties": false } }, "modifierGroups": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "groupId": { "type": "string" }, "minSelections": { "type": "integer" }, "maxSelections": { "type": "integer" }, "minUniqueSelections": { "type": "integer" }, "maxUniqueSelections": { "type": "integer" }, "freeSelectionCount": { "type": "integer" }, "chargeKeptDefaults": { "type": "boolean" }, "allowedQuantities": { "type": "array", "items": { "type": "integer" } }, "optionDefaults": { "type": "array", "items": { "type": "object", "properties": { "optionId": { "type": "string" }, "defaultQuantity": { "type": "integer" } }, "required": ["optionId", "defaultQuantity"], "additionalProperties": false } }, "externalId": { "not": {} }, "name": { "not": {} }, "options": { "not": {} } }, "required": ["groupId"], "additionalProperties": false }, { "$ref": "#/components/schemas/Suspend_" } ] } }, "taxCategoryId": { "type": "string" }, "taxRateIds": { "type": "array", "items": { "type": "string" } }, "feeIds": { "type": "array", "items": { "type": "string" } }, "dietaryLabels": { "type": "array", "items": { "type": "string" } }, "allergens": { "type": "array", "items": { "type": "string" } }, "calorieCount": { "type": "integer" }, "availability": { "type": "object", "properties": { "windows": { "type": "array", "items": { "type": "object", "properties": { "dayOfWeek": { "type": "integer" }, "startTime": { "type": "string" }, "endTime": { "type": "string" } }, "required": ["dayOfWeek", "startTime", "endTime"], "additionalProperties": false } } }, "required": ["windows"], "additionalProperties": false }, "stockStatus": { "type": "string", "enum": ["in_stock", "out_of_stock", "low_stock"] } }, "required": ["externalId", "name", "variations"], "additionalProperties": false } } }, "required": ["externalId", "name", "items"], "additionalProperties": false } } }, "required": [ "catalogId", "storePublicId", "versionId", "currency", "currencies", "taxCategories", "taxRates", "fees", "productSets", "discounts", "promotions", "coupons", "modifierGroups", "categories" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Publishes the full menu document for a connected location. Validation is all-or-nothing (a 400 lists every issue); the document is applied as a diff against the current menu, so an identical re-publish is a no-op and object identities stay stable across publishes by their `externalId`. Returns the resulting menu. Requires `menus:write` and an active connection to the location.", "summary": "Publish location menu", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string" }, "locale": { "type": "string" }, "timezone": { "type": "string" }, "currencies": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "exponent": { "type": "integer" }, "cashRoundingMinor": { "type": "integer" }, "roundingMode": { "type": "string", "enum": ["half_up", "half_even", "half_down", "up", "down", "ceiling", "floor"] } }, "required": ["currency"], "additionalProperties": false } }, "taxCategories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" } }, "required": ["name"], "additionalProperties": false } }, "taxRates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "taxCategoryId": { "type": "string" }, "method": { "type": "string", "enum": ["percentage", "flat", "bracket"] }, "percentage": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "flatAmount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "brackets": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "to": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "tax": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false } }, "required": ["from", "tax"], "additionalProperties": false } }, "base": { "type": "string", "enum": ["price", "price_plus_prior_taxes", "weight", "volume", "quantity", "alcohol_content"] }, "inclusion": { "type": "string", "enum": ["exclusive", "inclusive", "context_resolved"] }, "compoundOnTaxRateIds": { "type": "array", "items": { "type": "string" } }, "tenderExemptions": { "type": "array", "items": { "type": "string", "enum": ["ebt", "snap", "wic"] } }, "condition": { "type": "object", "properties": { "minPrice": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "maxPrice": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "jurisdiction": { "type": "string" }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": ["key", "value"], "additionalProperties": false } } }, "additionalProperties": false }, "hiddenFromCustomer": { "type": "boolean" } }, "required": ["name"], "additionalProperties": false } }, "fees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "feeType": { "type": "string", "enum": [ "delivery", "service_charge", "bag", "bottle_deposit", "crv", "small_order", "processing_pass_through", "deposit", "security_hold", "no_show_fee", "cancellation_fee", "auto_gratuity", "non_cash_adjustment", "other" ] }, "calculation": { "type": "object", "properties": { "base": { "type": "string", "enum": [ "flat", "per_unit", "percentage_of_line", "percentage_of_subtotal", "post_discount", "post_tax_total" ] }, "amount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "percentage": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "eligibleProductSetId": { "type": "string" }, "excludedProductSetIds": { "type": "array", "items": { "type": "string" } } }, "required": ["base"], "additionalProperties": false }, "taxCategoryId": { "type": "string" }, "refundable": { "type": "boolean" }, "autoApply": { "type": "object", "properties": { "byGuestCountGte": { "type": "integer" }, "byFulfillmentMode": { "type": "array", "items": { "type": "string", "enum": ["dine_in", "takeout", "delivery", "pickup", "curbside", "shipping"] } } }, "additionalProperties": false }, "containers": { "type": "array", "items": { "type": "object", "properties": { "containerSizeMl": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "amount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false } }, "required": ["amount"], "additionalProperties": false } } }, "required": ["name", "feeType", "calculation"], "additionalProperties": false } }, "productSets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "itemIdsAny": { "type": "array", "items": { "type": "string" } }, "itemIdsAll": { "type": "array", "items": { "type": "string" } }, "allProducts": { "type": "boolean" }, "quantityExact": { "type": "integer" }, "quantityMin": { "type": "integer" }, "quantityMax": { "type": "integer" } }, "additionalProperties": false } }, "discounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "benefitType": { "type": "string", "enum": ["percentage", "amount", "set_price", "free_item", "bxgy", "free_fee"] }, "amount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "percentage": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "maximumAmount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "benefitTargetProductSetId": { "type": "string" }, "lineSelection": { "type": "string", "enum": ["least_expensive", "most_expensive"] }, "bxgy": { "type": "object", "properties": { "buyProductSetId": { "type": "string" }, "buyQuantity": { "type": "integer" }, "getProductSetId": { "type": "string" }, "getQuantity": { "type": "integer" }, "getBenefit": { "type": "string", "enum": ["free", "percentage", "set_price", "amount"] }, "getBenefitAmount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "getBenefitPercentage": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "customerChoosesReward": { "type": "boolean" }, "excludeStrategy": { "type": "string", "enum": ["least_expensive", "most_expensive"] } }, "required": [ "buyProductSetId", "buyQuantity", "getProductSetId", "getQuantity", "getBenefit" ], "additionalProperties": false }, "freeFeeTargets": { "type": "array", "items": { "type": "string", "enum": [ "delivery", "service_charge", "bag", "bottle_deposit", "crv", "small_order", "processing_pass_through", "deposit", "security_hold", "no_show_fee", "cancellation_fee", "auto_gratuity", "non_cash_adjustment", "other" ] } }, "modifiesTaxBasis": { "type": "boolean" } }, "required": ["name", "benefitType"], "additionalProperties": false } }, "promotions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "discountId": { "type": "string" }, "applicationMode": { "type": "string", "enum": ["automatic", "coupon", "manual"] }, "eligibility": { "type": "object", "properties": { "minimumOrderSubtotal": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "matchProductSetId": { "type": "string" }, "excludeProductSetId": { "type": "string" } }, "additionalProperties": false }, "availability": { "type": "object", "properties": { "windows": { "type": "array", "items": { "type": "object", "properties": { "dayOfWeek": { "type": "integer" }, "startTime": { "type": "string" }, "endTime": { "type": "string" } }, "required": ["dayOfWeek", "startTime", "endTime"], "additionalProperties": false } } }, "required": ["windows"], "additionalProperties": false }, "validFrom": { "type": "string" }, "validUntil": { "type": "string" }, "stacking": { "type": "object", "properties": { "mode": { "type": "string", "enum": ["exclusive", "additive", "best_of", "ordered"] }, "priority": { "type": "integer" } }, "required": ["mode"], "additionalProperties": false }, "redemption": { "type": "object", "properties": { "maxUsesTotal": { "type": "integer" }, "maxUsesPerCustomer": { "type": "integer" } }, "additionalProperties": false } }, "required": ["name", "discountId"], "additionalProperties": false } }, "coupons": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "code": { "type": "string" }, "promotionId": { "type": "string" }, "maxRedemptions": { "type": "integer" }, "perCustomerLimit": { "type": "integer" }, "expiresAt": { "type": "string" } }, "required": ["code", "promotionId"], "additionalProperties": false } }, "modifierGroups": { "type": "array", "items": { "$ref": "#/components/schemas/Suspend_" } }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "availability": { "type": "object", "properties": { "windows": { "type": "array", "items": { "type": "object", "properties": { "dayOfWeek": { "type": "integer" }, "startTime": { "type": "string" }, "endTime": { "type": "string" } }, "required": ["dayOfWeek", "startTime", "endTime"], "additionalProperties": false } } }, "required": ["windows"], "additionalProperties": false }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "variations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "object", "properties": { "amount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "priceType": { "type": "string", "enum": ["fixed", "variable", "per_unit", "bulk"] }, "taxInclusive": { "type": "boolean" }, "currencyPrices": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "taxInclusive": { "type": "boolean" } }, "required": ["amount"], "additionalProperties": false } }, "openBounds": { "type": "object", "properties": { "min": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "max": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "presets": { "type": "array", "items": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false } } }, "additionalProperties": false }, "bulkTiers": { "type": "array", "items": { "type": "object", "properties": { "minQuantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false } }, "required": ["minQuantity", "unitPrice"], "additionalProperties": false } }, "measurementUnit": { "type": "object", "properties": { "unit": { "type": "string" }, "precision": { "type": "integer" } }, "required": ["unit"], "additionalProperties": false }, "compareAtAmount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false } }, "additionalProperties": false }, "sku": { "type": "string" }, "barcodes": { "type": "array", "items": { "type": "string" } }, "modifierGroups": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "groupId": { "type": "string" }, "minSelections": { "type": "integer" }, "maxSelections": { "type": "integer" }, "minUniqueSelections": { "type": "integer" }, "maxUniqueSelections": { "type": "integer" }, "freeSelectionCount": { "type": "integer" }, "chargeKeptDefaults": { "type": "boolean" }, "allowedQuantities": { "type": "array", "items": { "type": "integer" } }, "optionDefaults": { "type": "array", "items": { "type": "object", "properties": { "optionId": { "type": "string" }, "defaultQuantity": { "type": "integer" } }, "required": ["optionId", "defaultQuantity"], "additionalProperties": false } }, "externalId": { "not": {} }, "name": { "not": {} }, "options": { "not": {} } }, "required": ["groupId"], "additionalProperties": false }, { "$ref": "#/components/schemas/Suspend_" } ] } }, "dietaryLabels": { "type": "array", "items": { "type": "string" } }, "allergens": { "type": "array", "items": { "type": "string" } }, "calorieCount": { "type": "integer" }, "stockStatus": { "type": "string", "enum": ["in_stock", "out_of_stock", "low_stock"] } }, "required": ["externalId", "name", "price"], "additionalProperties": false } }, "modifierGroups": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "groupId": { "type": "string" }, "minSelections": { "type": "integer" }, "maxSelections": { "type": "integer" }, "minUniqueSelections": { "type": "integer" }, "maxUniqueSelections": { "type": "integer" }, "freeSelectionCount": { "type": "integer" }, "chargeKeptDefaults": { "type": "boolean" }, "allowedQuantities": { "type": "array", "items": { "type": "integer" } }, "optionDefaults": { "type": "array", "items": { "type": "object", "properties": { "optionId": { "type": "string" }, "defaultQuantity": { "type": "integer" } }, "required": ["optionId", "defaultQuantity"], "additionalProperties": false } }, "externalId": { "not": {} }, "name": { "not": {} }, "options": { "not": {} } }, "required": ["groupId"], "additionalProperties": false }, { "$ref": "#/components/schemas/Suspend_" } ] } }, "taxCategoryId": { "type": "string" }, "taxRateIds": { "type": "array", "items": { "type": "string" } }, "feeIds": { "type": "array", "items": { "type": "string" } }, "dietaryLabels": { "type": "array", "items": { "type": "string" } }, "allergens": { "type": "array", "items": { "type": "string" } }, "calorieCount": { "type": "integer" }, "availability": { "type": "object", "properties": { "windows": { "type": "array", "items": { "type": "object", "properties": { "dayOfWeek": { "type": "integer" }, "startTime": { "type": "string" }, "endTime": { "type": "string" } }, "required": ["dayOfWeek", "startTime", "endTime"], "additionalProperties": false } } }, "required": ["windows"], "additionalProperties": false }, "stockStatus": { "type": "string", "enum": ["in_stock", "out_of_stock", "low_stock"] } }, "required": ["externalId", "name", "variations"], "additionalProperties": false } } }, "required": ["externalId", "name", "items"], "additionalProperties": false } } }, "required": ["currency", "categories"], "additionalProperties": false } } }, "required": true } } }, "/locations/{locationId}/delivery_zones": { "get": { "tags": ["Delivery zones"], "operationId": "developer-api.listDeliveryZones", "parameters": [ { "name": "locationId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": ["delivery_zone"] }, "id": { "type": "string" }, "location_id": { "type": "string" }, "name": { "type": "string" }, "zone_type": { "type": "string", "enum": ["polygon", "circle"] }, "polygon": { "type": "object", "properties": { "type": { "type": "string", "enum": ["Polygon"] }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "prefixItems": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] } ], "maxItems": 2, "minItems": 2 } } } }, "required": ["type", "coordinates"], "additionalProperties": false, "description": "A GeoJSON Polygon. Coordinates are `[longitude, latitude]` rings; the first ring must be closed." }, "radius_miles": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "delivery_fee_cents": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "min_order_cents": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "max_distance_miles": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "is_active": { "type": "boolean" }, "priority": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "object", "id", "location_id", "name", "zone_type", "polygon", "radius_miles", "delivery_fee_cents", "min_order_cents", "max_distance_miles", "is_active", "priority", "created_at", "updated_at" ], "additionalProperties": false, "description": "A delivery zone. `delivery_fee_cents` and `min_order_cents` are integer USD cents; `created_at` / `updated_at` are ISO 8601 timestamps." } } }, "required": ["object", "data"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Lists the active delivery zones for a connected location. Requires `delivery_zones:read` and an active connection to the location.", "summary": "List delivery zones" }, "post": { "tags": ["Delivery zones"], "operationId": "developer-api.createDeliveryZone", "parameters": [ { "name": "locationId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "A delivery zone. `delivery_fee_cents` and `min_order_cents` are integer USD cents; `created_at` / `updated_at` are ISO 8601 timestamps.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["delivery_zone"] }, "id": { "type": "string" }, "location_id": { "type": "string" }, "name": { "type": "string" }, "zone_type": { "type": "string", "enum": ["polygon", "circle"] }, "polygon": { "type": "object", "properties": { "type": { "type": "string", "enum": ["Polygon"] }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "prefixItems": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] } ], "maxItems": 2, "minItems": 2 } } } }, "required": ["type", "coordinates"], "additionalProperties": false, "description": "A GeoJSON Polygon. Coordinates are `[longitude, latitude]` rings; the first ring must be closed." }, "radius_miles": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "delivery_fee_cents": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "min_order_cents": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "max_distance_miles": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "is_active": { "type": "boolean" }, "priority": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "object", "id", "location_id", "name", "zone_type", "polygon", "radius_miles", "delivery_fee_cents", "min_order_cents", "max_distance_miles", "is_active", "priority", "created_at", "updated_at" ], "additionalProperties": false, "description": "A delivery zone. `delivery_fee_cents` and `min_order_cents` are integer USD cents; `created_at` / `updated_at` are ISO 8601 timestamps." } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Creates a delivery zone for a connected location. Zone names must be unique per location. Requires `delivery_zones:write` and an active connection to the location.", "summary": "Create delivery zone", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "allOf": [ { "pattern": "^\\S[\\s\\S]*\\S$|^\\S$|^$" }, { "minLength": 1 } ] }, "polygon": { "type": "object", "properties": { "type": { "type": "string", "enum": ["Polygon"] }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "prefixItems": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] } ], "maxItems": 2, "minItems": 2 } } } }, "required": ["type", "coordinates"], "additionalProperties": false, "description": "A GeoJSON Polygon. Coordinates are `[longitude, latitude]` rings; the first ring must be closed." }, "delivery_fee_cents": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "min_order_cents": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, { "type": "null" } ] }, "max_distance_miles": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, { "type": "null" } ] }, "is_active": { "type": "boolean" }, "priority": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "zone_type": { "type": "string", "enum": ["polygon", "circle"] }, "radius_miles": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, { "type": "null" } ] } }, "required": ["name", "polygon"], "additionalProperties": false } } }, "required": true } } }, "/locations/{locationId}/delivery_zones/{zoneId}": { "get": { "tags": ["Delivery zones"], "operationId": "developer-api.getDeliveryZone", "parameters": [ { "name": "locationId", "in": "path", "schema": { "type": "string" }, "required": true }, { "name": "zoneId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "A delivery zone. `delivery_fee_cents` and `min_order_cents` are integer USD cents; `created_at` / `updated_at` are ISO 8601 timestamps.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["delivery_zone"] }, "id": { "type": "string" }, "location_id": { "type": "string" }, "name": { "type": "string" }, "zone_type": { "type": "string", "enum": ["polygon", "circle"] }, "polygon": { "type": "object", "properties": { "type": { "type": "string", "enum": ["Polygon"] }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "prefixItems": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] } ], "maxItems": 2, "minItems": 2 } } } }, "required": ["type", "coordinates"], "additionalProperties": false, "description": "A GeoJSON Polygon. Coordinates are `[longitude, latitude]` rings; the first ring must be closed." }, "radius_miles": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "delivery_fee_cents": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "min_order_cents": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "max_distance_miles": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "is_active": { "type": "boolean" }, "priority": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "object", "id", "location_id", "name", "zone_type", "polygon", "radius_miles", "delivery_fee_cents", "min_order_cents", "max_distance_miles", "is_active", "priority", "created_at", "updated_at" ], "additionalProperties": false, "description": "A delivery zone. `delivery_fee_cents` and `min_order_cents` are integer USD cents; `created_at` / `updated_at` are ISO 8601 timestamps." } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Returns a single delivery zone belonging to a connected location. Requires `delivery_zones:read` and an active connection to the location.", "summary": "Get delivery zone" }, "patch": { "tags": ["Delivery zones"], "operationId": "developer-api.updateDeliveryZone", "parameters": [ { "name": "locationId", "in": "path", "schema": { "type": "string" }, "required": true }, { "name": "zoneId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "A delivery zone. `delivery_fee_cents` and `min_order_cents` are integer USD cents; `created_at` / `updated_at` are ISO 8601 timestamps.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["delivery_zone"] }, "id": { "type": "string" }, "location_id": { "type": "string" }, "name": { "type": "string" }, "zone_type": { "type": "string", "enum": ["polygon", "circle"] }, "polygon": { "type": "object", "properties": { "type": { "type": "string", "enum": ["Polygon"] }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "prefixItems": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] } ], "maxItems": 2, "minItems": 2 } } } }, "required": ["type", "coordinates"], "additionalProperties": false, "description": "A GeoJSON Polygon. Coordinates are `[longitude, latitude]` rings; the first ring must be closed." }, "radius_miles": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "delivery_fee_cents": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "min_order_cents": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "max_distance_miles": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "is_active": { "type": "boolean" }, "priority": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "object", "id", "location_id", "name", "zone_type", "polygon", "radius_miles", "delivery_fee_cents", "min_order_cents", "max_distance_miles", "is_active", "priority", "created_at", "updated_at" ], "additionalProperties": false, "description": "A delivery zone. `delivery_fee_cents` and `min_order_cents` are integer USD cents; `created_at` / `updated_at` are ISO 8601 timestamps." } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Updates a delivery zone belonging to a connected location; only the provided fields change. Requires `delivery_zones:write` and an active connection to the location.", "summary": "Update delivery zone", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "allOf": [ { "pattern": "^\\S[\\s\\S]*\\S$|^\\S$|^$" }, { "minLength": 1 } ] }, { "type": "null" } ] }, "polygon": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["Polygon"] }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "prefixItems": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] } ], "maxItems": 2, "minItems": 2 } } } }, "required": ["type", "coordinates"], "additionalProperties": false, "description": "A GeoJSON Polygon. Coordinates are `[longitude, latitude]` rings; the first ring must be closed." }, { "type": "null" } ] }, "delivery_fee_cents": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "min_order_cents": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, { "type": "null" } ] }, "max_distance_miles": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, { "type": "null" } ] }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "priority": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "zone_type": { "anyOf": [ { "type": "string", "enum": ["polygon", "circle"] }, { "type": "null" } ] }, "radius_miles": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, { "type": "null" } ] } }, "additionalProperties": false } } }, "required": true } }, "delete": { "tags": ["Delivery zones"], "operationId": "developer-api.deleteDeliveryZone", "parameters": [ { "name": "locationId", "in": "path", "schema": { "type": "string" }, "required": true }, { "name": "zoneId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["delivery_zone"] }, "id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [true] } }, "required": ["object", "id", "deleted"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Deactivates a delivery zone belonging to a connected location. Requires `delivery_zones:write` and an active connection to the location.", "summary": "Delete delivery zone" } }, "/locations/{locationId}/delivery_zones/check": { "post": { "tags": ["Delivery zones"], "operationId": "developer-api.checkDeliveryZoneAddress", "parameters": [ { "name": "locationId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["delivery_zone_check"] }, "in_zone": { "type": "boolean" }, "zone": { "anyOf": [ { "type": "object", "properties": { "object": { "type": "string", "enum": ["delivery_zone"] }, "id": { "type": "string" }, "location_id": { "type": "string" }, "name": { "type": "string" }, "zone_type": { "type": "string", "enum": ["polygon", "circle"] }, "polygon": { "type": "object", "properties": { "type": { "type": "string", "enum": ["Polygon"] }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "prefixItems": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] } ], "maxItems": 2, "minItems": 2 } } } }, "required": ["type", "coordinates"], "additionalProperties": false, "description": "A GeoJSON Polygon. Coordinates are `[longitude, latitude]` rings; the first ring must be closed." }, "radius_miles": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "delivery_fee_cents": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "min_order_cents": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "max_distance_miles": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "is_active": { "type": "boolean" }, "priority": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "object", "id", "location_id", "name", "zone_type", "polygon", "radius_miles", "delivery_fee_cents", "min_order_cents", "max_distance_miles", "is_active", "priority", "created_at", "updated_at" ], "additionalProperties": false, "description": "A delivery zone. `delivery_fee_cents` and `min_order_cents` are integer USD cents; `created_at` / `updated_at` are ISO 8601 timestamps." }, { "type": "null" } ] }, "delivery_fee_cents": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] } }, "required": ["object", "in_zone", "zone", "delivery_fee_cents"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Checks whether a coordinate falls inside any active delivery zone of a connected location and returns the matching zone and delivery fee. Requires `delivery_zones:read` and an active connection to the location.", "summary": "Check delivery zone coverage", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "latitude": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "longitude": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] } }, "required": ["latitude", "longitude"], "additionalProperties": false } } }, "required": true } } }, "/webhook_event_types": { "get": { "tags": ["Webhooks"], "operationId": "developer-api.listWebhookEventTypes", "parameters": [], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": ["webhook_event_type"] }, "type": { "type": "string" }, "description": { "type": "string" } }, "required": ["object", "type", "description"], "additionalProperties": false } } }, "required": ["object", "data"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Lists the event types a webhook subscription can subscribe to.", "summary": "List webhook event types" } }, "/webhook_subscriptions": { "post": { "tags": ["Webhooks"], "operationId": "developer-api.createWebhookSubscription", "parameters": [], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["webhook_subscription.created"] }, "subscription": { "type": "object", "properties": { "object": { "type": "string", "enum": ["webhook_subscription"] }, "id": { "type": "string" }, "environment": { "type": "string", "enum": ["test", "live"] }, "notification_url": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": ["enabled", "disabled"] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "object", "id", "environment", "notification_url", "event_types", "status", "created_at", "updated_at" ], "additionalProperties": false }, "signing_secret": { "type": "string", "description": "One-time HMAC-SHA256 signing secret (`mwhsec_…`) used to verify webhook deliveries. Store it now; it is never shown again." } }, "required": ["object", "subscription", "signing_secret"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Subscribes a notification URL to event types. Returns the HMAC signing secret once.", "summary": "Create webhook subscription", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "notification_url": { "type": "string", "allOf": [ { "pattern": "^\\S[\\s\\S]*\\S$|^\\S$|^$" }, { "minLength": 1 } ] }, "event_types": { "type": "array", "items": { "type": "string" } } }, "required": ["notification_url", "event_types"], "additionalProperties": false } } }, "required": true } }, "get": { "tags": ["Webhooks"], "operationId": "developer-api.listWebhookSubscriptions", "parameters": [], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": ["webhook_subscription"] }, "id": { "type": "string" }, "environment": { "type": "string", "enum": ["test", "live"] }, "notification_url": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": ["enabled", "disabled"] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "object", "id", "environment", "notification_url", "event_types", "status", "created_at", "updated_at" ], "additionalProperties": false } } }, "required": ["object", "data"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Lists the app's webhook subscriptions in the credential's environment.", "summary": "List webhook subscriptions" } }, "/webhook_subscriptions/{subscriptionId}": { "get": { "tags": ["Webhooks"], "operationId": "developer-api.getWebhookSubscription", "parameters": [ { "name": "subscriptionId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["webhook_subscription"] }, "id": { "type": "string" }, "environment": { "type": "string", "enum": ["test", "live"] }, "notification_url": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": ["enabled", "disabled"] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "object", "id", "environment", "notification_url", "event_types", "status", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Retrieves a single webhook subscription owned by the app.", "summary": "Get webhook subscription" }, "patch": { "tags": ["Webhooks"], "operationId": "developer-api.updateWebhookSubscription", "parameters": [ { "name": "subscriptionId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["webhook_subscription"] }, "id": { "type": "string" }, "environment": { "type": "string", "enum": ["test", "live"] }, "notification_url": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": ["enabled", "disabled"] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "object", "id", "environment", "notification_url", "event_types", "status", "created_at", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Updates the notification URL, subscribed event types, or enabled/disabled status. The signing secret is unchanged.", "summary": "Update webhook subscription", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "notification_url": { "anyOf": [ { "type": "string", "allOf": [ { "pattern": "^\\S[\\s\\S]*\\S$|^\\S$|^$" }, { "minLength": 1 } ] }, { "type": "null" } ] }, "event_types": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": ["enabled", "disabled"] }, { "type": "null" } ] } }, "additionalProperties": false } } }, "required": true } }, "delete": { "tags": ["Webhooks"], "operationId": "developer-api.deleteWebhookSubscription", "parameters": [ { "name": "subscriptionId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["webhook_subscription.deleted"] }, "id": { "type": "string" }, "deleted": { "type": "boolean", "enum": [true] } }, "required": ["object", "id", "deleted"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Permanently deletes the subscription; pending deliveries are abandoned.", "summary": "Delete webhook subscription" } }, "/webhook_subscriptions/{subscriptionId}/test": { "post": { "tags": ["Webhooks"], "operationId": "developer-api.testWebhookSubscription", "parameters": [ { "name": "subscriptionId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["webhook_test_result"] }, "event_id": { "type": "string" }, "delivered": { "type": "boolean" }, "response_status": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] } }, "required": ["object", "event_id", "delivered", "response_status"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "description": "DeveloperApiInternalError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiInternalError" } } } } }, "description": "Delivers a synthetic `webhook.test` event to the subscription and returns the delivery result.", "summary": "Send test webhook" } }, "/webhook_events": { "get": { "tags": ["Webhooks"], "operationId": "developer-api.listWebhookEvents", "parameters": [], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "id": { "type": "string" }, "type": { "type": "string" }, "environment": { "type": "string", "enum": ["test", "live"] }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "data": { "type": "object" } }, "required": ["object", "id", "type", "environment", "created", "data"], "additionalProperties": false } } }, "required": ["object", "data"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "The app's event ledger (most recent first, up to 50). Useful for reconciliation and debugging missed deliveries.", "summary": "List webhook events" } }, "/webhook_events/{eventId}": { "get": { "tags": ["Webhooks"], "operationId": "developer-api.getWebhookEvent", "parameters": [ { "name": "eventId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "id": { "type": "string" }, "type": { "type": "string" }, "environment": { "type": "string", "enum": ["test", "live"] }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "data": { "type": "object" } }, "required": ["object", "id", "type", "environment", "created", "data"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Retrieves a single event from the ledger, including its `data` payload.", "summary": "Get webhook event" } }, "/webhook_events/{eventId}/replay": { "post": { "tags": ["Webhooks"], "operationId": "developer-api.replayWebhookEvent", "parameters": [ { "name": "eventId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["event"] }, "id": { "type": "string" }, "type": { "type": "string" }, "environment": { "type": "string", "enum": ["test", "live"] }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "data": { "type": "object" } }, "required": ["object", "id", "type", "environment", "created", "data"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Re-delivers the event to currently-matching subscriptions, skipping any already delivered for this event (idempotent).", "summary": "Replay webhook event" } }, "/orders": { "get": { "tags": ["Orders"], "operationId": "developer-api.listOrders", "parameters": [ { "name": "since", "in": "query", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "required": false }, { "name": "starting_after", "in": "query", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "required": false }, { "name": "limit", "in": "query", "schema": { "anyOf": [ { "type": "string", "allOf": [ { "pattern": "^[+-]?\\d*\\.?\\d+(?:[Ee][+-]?\\d+)?$" } ] }, { "type": "null" } ] }, "required": false } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": ["order"] }, "id": { "type": "string" }, "livemode": { "type": "boolean", "description": "True when the order belongs to the live environment; false for test-mode data." }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "status": { "type": "string" }, "payment_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "location_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fulfillment_type": { "type": "string" }, "scheduled_for": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Customer-selected completion time (ISO 8601, UTC) for scheduled orders; null for ASAP orders. Prepare the order for this time, not on receipt." }, "delivery_address": { "anyOf": [ { "type": "object", "properties": { "street": { "type": "string" }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["street", "unit", "city", "state", "zip", "notes"], "additionalProperties": false, "description": "The customer delivery address. `notes` contains the delivery instructions. All fields are present when an address is available." }, { "type": "null" } ], "description": "The delivery address for delivery orders, including delivery instructions; null for pickup orders or when no stored address is available." }, "customer": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Customer phone number in E.164 format (e.g. +14155552671); null when the customer provided none." }, "phone_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last four digits of the customer phone number." } }, "required": ["name", "phone", "phone_last_four"], "additionalProperties": false }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "menu_entity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quantity": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "base_price": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "tax": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "modifiers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "menu_entity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quantity": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "price": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] } }, "required": ["name", "menu_entity_id", "quantity", "price"], "additionalProperties": false, "description": "A selected modifier. `price` is the price change in integer USD cents." } } }, "required": ["name", "menu_entity_id", "quantity", "base_price", "tax", "modifiers"], "additionalProperties": false, "description": "An order line item. `base_price` (per unit, before modifiers) and `tax` are integer USD cents. `menu_entity_id` is the external id the partner published for the menu entity, when known." } }, "totals": { "type": "object", "properties": { "currency": { "type": "string" }, "subtotal": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "tax": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "surcharge": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "tip": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "delivery_fee": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "delivery_tip": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "total": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] } }, "required": [ "currency", "subtotal", "tax", "surcharge", "tip", "delivery_fee", "delivery_tip", "total" ], "additionalProperties": false, "description": "All amounts in integer USD cents. `total` = subtotal + tax + surcharge + tip + delivery fees." }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment": { "type": "object", "properties": { "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_link_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["provider", "status", "payment_link_url"], "additionalProperties": false } }, "required": [ "object", "id", "livemode", "created", "status", "payment_status", "location_id", "fulfillment_type", "scheduled_for", "delivery_address", "customer", "line_items", "totals", "external_id", "payment" ], "additionalProperties": false } }, "has_more": { "type": "boolean" } }, "required": ["object", "data", "has_more"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Lists orders for the locations the app is connected to as POS receiver. Without `since`, results are newest first. With `since`, results drain oldest first from that exclusive checkpoint; while `has_more` is true, repeat with `starting_after` set to the last order id from the previous page. `starting_after` must be an order owned by the app and requires `since`. Set a page size from 1 to 100. Money is in integer cents; line-item modifiers reflect the directly-selected (first-level) options.", "summary": "List orders" } }, "/orders/{orderId}": { "get": { "tags": ["Orders"], "operationId": "developer-api.getOrder", "parameters": [ { "name": "orderId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["order"] }, "id": { "type": "string" }, "livemode": { "type": "boolean", "description": "True when the order belongs to the live environment; false for test-mode data." }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "status": { "type": "string" }, "payment_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "location_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fulfillment_type": { "type": "string" }, "scheduled_for": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Customer-selected completion time (ISO 8601, UTC) for scheduled orders; null for ASAP orders. Prepare the order for this time, not on receipt." }, "delivery_address": { "anyOf": [ { "type": "object", "properties": { "street": { "type": "string" }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["street", "unit", "city", "state", "zip", "notes"], "additionalProperties": false, "description": "The customer delivery address. `notes` contains the delivery instructions. All fields are present when an address is available." }, { "type": "null" } ], "description": "The delivery address for delivery orders, including delivery instructions; null for pickup orders or when no stored address is available." }, "customer": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Customer phone number in E.164 format (e.g. +14155552671); null when the customer provided none." }, "phone_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last four digits of the customer phone number." } }, "required": ["name", "phone", "phone_last_four"], "additionalProperties": false }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "menu_entity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quantity": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "base_price": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "tax": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "modifiers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "menu_entity_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quantity": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "price": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] } }, "required": ["name", "menu_entity_id", "quantity", "price"], "additionalProperties": false, "description": "A selected modifier. `price` is the price change in integer USD cents." } } }, "required": ["name", "menu_entity_id", "quantity", "base_price", "tax", "modifiers"], "additionalProperties": false, "description": "An order line item. `base_price` (per unit, before modifiers) and `tax` are integer USD cents. `menu_entity_id` is the external id the partner published for the menu entity, when known." } }, "totals": { "type": "object", "properties": { "currency": { "type": "string" }, "subtotal": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "tax": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "surcharge": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "tip": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "delivery_fee": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "delivery_tip": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "total": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] } }, "required": [ "currency", "subtotal", "tax", "surcharge", "tip", "delivery_fee", "delivery_tip", "total" ], "additionalProperties": false, "description": "All amounts in integer USD cents. `total` = subtotal + tax + surcharge + tip + delivery fees." }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment": { "type": "object", "properties": { "provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_link_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["provider", "status", "payment_link_url"], "additionalProperties": false } }, "required": [ "object", "id", "livemode", "created", "status", "payment_status", "location_id", "fulfillment_type", "scheduled_for", "delivery_address", "customer", "line_items", "totals", "external_id", "payment" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Returns a single order if it belongs to a location the app is connected to.", "summary": "Get order" } }, "/orders/{orderId}/resend": { "post": { "tags": ["Orders"], "operationId": "developer-api.resendOrder", "parameters": [ { "name": "orderId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["order_resend"] }, "order_id": { "type": "string" }, "status": { "type": "string", "enum": ["received"] } }, "required": ["object", "order_id", "status"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Publishes a fresh order.notification only for a live order owned by the app connection that missed its webhook. Terminal orders cannot be resent or revived; reconcile them with GET /v1/orders?since=... and GET /v1/orders/{orderId}.", "summary": "Resend order" } }, "/orders/{orderId}/accept": { "post": { "tags": ["Orders"], "operationId": "developer-api.acceptOrder", "parameters": [ { "name": "orderId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["order_decision"] }, "order_id": { "type": "string" }, "decision": { "type": "string", "enum": ["accept", "deny", "ready", "complete", "cancel", "status"] }, "status": { "type": "string", "enum": ["received"] } }, "required": ["object", "order_id", "decision", "status"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Partner accepts the order; the order is finalized and the customer confirmed.", "summary": "Accept order" } }, "/orders/{orderId}/deny": { "post": { "tags": ["Orders"], "operationId": "developer-api.denyOrder", "parameters": [ { "name": "orderId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["order_decision"] }, "order_id": { "type": "string" }, "decision": { "type": "string", "enum": ["accept", "deny", "ready", "complete", "cancel", "status"] }, "status": { "type": "string", "enum": ["received"] } }, "required": ["object", "order_id", "decision", "status"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Partner rejects the order; it is rejected and any payment reversed.", "summary": "Deny order", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "allOf": [ { "pattern": "^\\S[\\s\\S]*\\S$|^\\S$|^$" }, { "minLength": 1 } ] }, { "type": "null" } ] } }, "additionalProperties": false } } }, "required": true } } }, "/orders/{orderId}/ready": { "post": { "tags": ["Orders"], "operationId": "developer-api.markOrderReady", "parameters": [ { "name": "orderId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["order_decision"] }, "order_id": { "type": "string" }, "decision": { "type": "string", "enum": ["accept", "deny", "ready", "complete", "cancel", "status"] }, "status": { "type": "string", "enum": ["received"] } }, "required": ["object", "order_id", "decision", "status"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Partner marks the order ready for pickup/handoff.", "summary": "Mark order ready" } }, "/orders/{orderId}/complete": { "post": { "tags": ["Orders"], "operationId": "developer-api.completeOrder", "parameters": [ { "name": "orderId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["order_decision"] }, "order_id": { "type": "string" }, "decision": { "type": "string", "enum": ["accept", "deny", "ready", "complete", "cancel", "status"] }, "status": { "type": "string", "enum": ["received"] } }, "required": ["object", "order_id", "decision", "status"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Partner marks the order fulfilled.", "summary": "Complete order" } }, "/orders/{orderId}/cancel": { "post": { "tags": ["Orders"], "operationId": "developer-api.cancelOrder", "parameters": [ { "name": "orderId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["order_decision"] }, "order_id": { "type": "string" }, "decision": { "type": "string", "enum": ["accept", "deny", "ready", "complete", "cancel", "status"] }, "status": { "type": "string", "enum": ["received"] } }, "required": ["object", "order_id", "decision", "status"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Partner cancels the order.", "summary": "Cancel order", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "allOf": [ { "pattern": "^\\S[\\s\\S]*\\S$|^\\S$|^$" }, { "minLength": 1 } ] }, { "type": "null" } ] } }, "additionalProperties": false } } }, "required": true } } }, "/orders/{orderId}/status": { "post": { "tags": ["Orders"], "operationId": "developer-api.updateOrderStatus", "parameters": [ { "name": "orderId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["order_decision"] }, "order_id": { "type": "string" }, "decision": { "type": "string", "enum": ["accept", "deny", "ready", "complete", "cancel", "status"] }, "status": { "type": "string", "enum": ["received"] } }, "required": ["object", "order_id", "decision", "status"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Partner reports an order status transition (e.g. ready, in delivery, fulfilled).", "summary": "Update order status", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["ACCEPTED", "READY", "IN_DELIVERY", "FULFILLED", "REJECTED", "STORE_CANCELLED"] } }, "required": ["status"], "additionalProperties": false } } }, "required": true } } }, "/orders/{orderId}/validation_result": { "post": { "tags": ["Orders"], "operationId": "developer-api.submitOrderValidationResult", "parameters": [ { "name": "orderId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["order_validation"] }, "id": { "type": "string" }, "livemode": { "type": "boolean" }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "order": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "valid", "invalid", "expired"] }, "expires_at": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "partner_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "allOf": [ { "pattern": "^\\S[\\s\\S]*\\S$|^\\S$|^$" }, { "minLength": 1 } ] }, "explanation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "item_external_ids": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": ["code"], "additionalProperties": false }, { "type": "null" } ] }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "object", "id", "livemode", "created", "order", "status", "expires_at", "partner_reference", "reason", "warnings" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Partner reports whether an order can be accepted (item availability, pricing feasibility, POS injectability). Echo the `validation_id` from the `order.validation_requested` event so the result is bound to that attempt — a result naming an expired/older attempt is rejected (404). A valid result lets Maple send the order notification; invalid blocks it. Results expire; Maple revalidates (a new `validation_id`) before final submission.", "summary": "Submit order validation result", "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "validation_id": { "type": "string", "allOf": [ { "pattern": "^\\S[\\s\\S]*\\S$|^\\S$|^$" }, { "minLength": 1 } ] }, "status": { "type": "string", "enum": ["valid"] }, "partner_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "warnings": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": ["validation_id", "status"], "additionalProperties": false }, { "type": "object", "properties": { "validation_id": { "type": "string", "allOf": [ { "pattern": "^\\S[\\s\\S]*\\S$|^\\S$|^$" }, { "minLength": 1 } ] }, "status": { "type": "string", "enum": ["invalid"] }, "reason": { "type": "object", "properties": { "code": { "type": "string", "allOf": [ { "pattern": "^\\S[\\s\\S]*\\S$|^\\S$|^$" }, { "minLength": 1 } ] }, "explanation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "item_external_ids": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": ["code"], "additionalProperties": false } }, "required": ["validation_id", "status", "reason"], "additionalProperties": false } ] } } }, "required": true } } }, "/bookings/{bookingId}/confirm": { "post": { "tags": ["Bookings"], "operationId": "developer-api-bookings.confirmBooking", "parameters": [ { "name": "bookingId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["booking"] }, "id": { "type": "string", "description": "Opaque, prefixed `bkg_…`." }, "livemode": { "type": "boolean" }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "version": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "location_id": { "type": "string" }, "status": { "type": "string", "enum": [ "requested", "confirmed", "seated", "completed", "declined_by_venue", "cancelled_by_guest", "cancelled_by_venue", "cancelled_unattributed", "no_show" ] }, "service_state": { "anyOf": [ { "type": "string", "enum": ["expected", "arrived", "partially_seated", "fully_seated", "left"] }, { "type": "null" } ] }, "confirmation_code": { "type": "string" }, "starts_at": { "type": "string", "description": "ISO-8601 UTC instant." }, "starts_at_local": { "type": "string", "description": "Venue wall-clock, `YYYY-MM-DDTHH:MM`." }, "service_date": { "type": "string", "description": "The venue service day the booking belongs to, `YYYY-MM-DD`." }, "duration_minutes": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ], "description": "Turn duration; null on provider-managed bookings, where Maple never invents one." }, "party_size": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "guest": { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "E.164, when the guest left one." }, "phone_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["first_name", "last_name", "phone", "phone_last_four", "email"], "additionalProperties": false }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The guest-facing note; venue-internal notes are never exposed." }, "channel": { "type": "string", "description": "The channel the booking originated on, e.g. `api_partner`, `voice_ai`, `internal`." }, "provider": { "type": "string", "enum": ["maple", "opentable", "resy", "sevenrooms"] }, "cancellation_policy": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-4217." }, "policy_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "within_hours_before_start": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "basis": { "type": "string", "description": "`per_party` or `per_person`." }, "amount_cents": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "percent_bps": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ], "description": "Basis points of the party value, when the fee is a percentage." } }, "required": ["within_hours_before_start", "basis", "amount_cents", "percent_bps"], "additionalProperties": false } }, "deposit": { "anyOf": [ { "type": "object", "properties": { "amount_cents": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "currency": { "type": "string" }, "basis": { "type": "string" } }, "required": ["amount_cents", "currency", "basis"], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["type", "currency", "policy_text", "tiers", "deposit"], "additionalProperties": false }, { "type": "null" } ] }, "experience": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Null when Maple has not seen the name." } }, "required": ["id", "name"], "additionalProperties": false }, { "type": "null" } ], "description": "The experience booked (prix fixe, ticketed seating), or null for a standard reservation." }, "updated_at": { "type": "string", "description": "ISO-8601 UTC instant." } }, "required": [ "object", "id", "livemode", "created", "version", "location_id", "status", "service_state", "confirmation_code", "starts_at", "starts_at_local", "service_date", "duration_minutes", "party_size", "guest", "notes", "channel", "provider", "cancellation_policy", "experience", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "409": { "description": "DeveloperApiConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiConflict" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Acts on behalf of the venue at a granted location. Requires bookings:manage. Returns the full booking; stale versions answer 409 stale_version, illegal transitions 409 illegal_transition with details.from_status, and unsupported providers 422 capability_unsupported.", "summary": "Confirm booking", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "expected_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Optimistic concurrency: the `version` you last read. A booking that moved on since answers 409 `stale_version` with `details.expected`/`actual`." } }, "additionalProperties": false } } }, "required": true } } }, "/bookings/{bookingId}/decline": { "post": { "tags": ["Bookings"], "operationId": "developer-api-bookings.declineBooking", "parameters": [ { "name": "bookingId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["booking"] }, "id": { "type": "string", "description": "Opaque, prefixed `bkg_…`." }, "livemode": { "type": "boolean" }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "version": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "location_id": { "type": "string" }, "status": { "type": "string", "enum": [ "requested", "confirmed", "seated", "completed", "declined_by_venue", "cancelled_by_guest", "cancelled_by_venue", "cancelled_unattributed", "no_show" ] }, "service_state": { "anyOf": [ { "type": "string", "enum": ["expected", "arrived", "partially_seated", "fully_seated", "left"] }, { "type": "null" } ] }, "confirmation_code": { "type": "string" }, "starts_at": { "type": "string", "description": "ISO-8601 UTC instant." }, "starts_at_local": { "type": "string", "description": "Venue wall-clock, `YYYY-MM-DDTHH:MM`." }, "service_date": { "type": "string", "description": "The venue service day the booking belongs to, `YYYY-MM-DD`." }, "duration_minutes": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ], "description": "Turn duration; null on provider-managed bookings, where Maple never invents one." }, "party_size": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "guest": { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "E.164, when the guest left one." }, "phone_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["first_name", "last_name", "phone", "phone_last_four", "email"], "additionalProperties": false }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The guest-facing note; venue-internal notes are never exposed." }, "channel": { "type": "string", "description": "The channel the booking originated on, e.g. `api_partner`, `voice_ai`, `internal`." }, "provider": { "type": "string", "enum": ["maple", "opentable", "resy", "sevenrooms"] }, "cancellation_policy": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-4217." }, "policy_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "within_hours_before_start": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "basis": { "type": "string", "description": "`per_party` or `per_person`." }, "amount_cents": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "percent_bps": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ], "description": "Basis points of the party value, when the fee is a percentage." } }, "required": ["within_hours_before_start", "basis", "amount_cents", "percent_bps"], "additionalProperties": false } }, "deposit": { "anyOf": [ { "type": "object", "properties": { "amount_cents": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "currency": { "type": "string" }, "basis": { "type": "string" } }, "required": ["amount_cents", "currency", "basis"], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["type", "currency", "policy_text", "tiers", "deposit"], "additionalProperties": false }, { "type": "null" } ] }, "experience": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Null when Maple has not seen the name." } }, "required": ["id", "name"], "additionalProperties": false }, { "type": "null" } ], "description": "The experience booked (prix fixe, ticketed seating), or null for a standard reservation." }, "updated_at": { "type": "string", "description": "ISO-8601 UTC instant." } }, "required": [ "object", "id", "livemode", "created", "version", "location_id", "status", "service_state", "confirmation_code", "starts_at", "starts_at_local", "service_date", "duration_minutes", "party_size", "guest", "notes", "channel", "provider", "cancellation_policy", "experience", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "409": { "description": "DeveloperApiConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiConflict" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Acts on behalf of the venue at a granted location. Requires bookings:manage. Returns the full booking; stale versions answer 409 stale_version, illegal transitions 409 illegal_transition with details.from_status, and unsupported providers 422 capability_unsupported.", "summary": "Decline booking", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "expected_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Optimistic concurrency: the `version` you last read. A booking that moved on since answers 409 `stale_version` with `details.expected`/`actual`." } }, "additionalProperties": false } } }, "required": true } } }, "/bookings/{bookingId}/seat": { "post": { "tags": ["Bookings"], "operationId": "developer-api-bookings.seatBooking", "parameters": [ { "name": "bookingId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["booking"] }, "id": { "type": "string", "description": "Opaque, prefixed `bkg_…`." }, "livemode": { "type": "boolean" }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "version": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "location_id": { "type": "string" }, "status": { "type": "string", "enum": [ "requested", "confirmed", "seated", "completed", "declined_by_venue", "cancelled_by_guest", "cancelled_by_venue", "cancelled_unattributed", "no_show" ] }, "service_state": { "anyOf": [ { "type": "string", "enum": ["expected", "arrived", "partially_seated", "fully_seated", "left"] }, { "type": "null" } ] }, "confirmation_code": { "type": "string" }, "starts_at": { "type": "string", "description": "ISO-8601 UTC instant." }, "starts_at_local": { "type": "string", "description": "Venue wall-clock, `YYYY-MM-DDTHH:MM`." }, "service_date": { "type": "string", "description": "The venue service day the booking belongs to, `YYYY-MM-DD`." }, "duration_minutes": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ], "description": "Turn duration; null on provider-managed bookings, where Maple never invents one." }, "party_size": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "guest": { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "E.164, when the guest left one." }, "phone_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["first_name", "last_name", "phone", "phone_last_four", "email"], "additionalProperties": false }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The guest-facing note; venue-internal notes are never exposed." }, "channel": { "type": "string", "description": "The channel the booking originated on, e.g. `api_partner`, `voice_ai`, `internal`." }, "provider": { "type": "string", "enum": ["maple", "opentable", "resy", "sevenrooms"] }, "cancellation_policy": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-4217." }, "policy_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "within_hours_before_start": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "basis": { "type": "string", "description": "`per_party` or `per_person`." }, "amount_cents": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "percent_bps": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ], "description": "Basis points of the party value, when the fee is a percentage." } }, "required": ["within_hours_before_start", "basis", "amount_cents", "percent_bps"], "additionalProperties": false } }, "deposit": { "anyOf": [ { "type": "object", "properties": { "amount_cents": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "currency": { "type": "string" }, "basis": { "type": "string" } }, "required": ["amount_cents", "currency", "basis"], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["type", "currency", "policy_text", "tiers", "deposit"], "additionalProperties": false }, { "type": "null" } ] }, "experience": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Null when Maple has not seen the name." } }, "required": ["id", "name"], "additionalProperties": false }, { "type": "null" } ], "description": "The experience booked (prix fixe, ticketed seating), or null for a standard reservation." }, "updated_at": { "type": "string", "description": "ISO-8601 UTC instant." } }, "required": [ "object", "id", "livemode", "created", "version", "location_id", "status", "service_state", "confirmation_code", "starts_at", "starts_at_local", "service_date", "duration_minutes", "party_size", "guest", "notes", "channel", "provider", "cancellation_policy", "experience", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "409": { "description": "DeveloperApiConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiConflict" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Acts on behalf of the venue at a granted location. Requires bookings:manage. Returns the full booking; stale versions answer 409 stale_version, illegal transitions 409 illegal_transition with details.from_status, and unsupported providers 422 capability_unsupported.", "summary": "Seat booking", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "expected_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Optimistic concurrency: the `version` you last read. A booking that moved on since answers 409 `stale_version` with `details.expected`/`actual`." } }, "additionalProperties": false } } }, "required": true } } }, "/bookings/{bookingId}/complete": { "post": { "tags": ["Bookings"], "operationId": "developer-api-bookings.completeBooking", "parameters": [ { "name": "bookingId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["booking"] }, "id": { "type": "string", "description": "Opaque, prefixed `bkg_…`." }, "livemode": { "type": "boolean" }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "version": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "location_id": { "type": "string" }, "status": { "type": "string", "enum": [ "requested", "confirmed", "seated", "completed", "declined_by_venue", "cancelled_by_guest", "cancelled_by_venue", "cancelled_unattributed", "no_show" ] }, "service_state": { "anyOf": [ { "type": "string", "enum": ["expected", "arrived", "partially_seated", "fully_seated", "left"] }, { "type": "null" } ] }, "confirmation_code": { "type": "string" }, "starts_at": { "type": "string", "description": "ISO-8601 UTC instant." }, "starts_at_local": { "type": "string", "description": "Venue wall-clock, `YYYY-MM-DDTHH:MM`." }, "service_date": { "type": "string", "description": "The venue service day the booking belongs to, `YYYY-MM-DD`." }, "duration_minutes": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ], "description": "Turn duration; null on provider-managed bookings, where Maple never invents one." }, "party_size": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "guest": { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "E.164, when the guest left one." }, "phone_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["first_name", "last_name", "phone", "phone_last_four", "email"], "additionalProperties": false }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The guest-facing note; venue-internal notes are never exposed." }, "channel": { "type": "string", "description": "The channel the booking originated on, e.g. `api_partner`, `voice_ai`, `internal`." }, "provider": { "type": "string", "enum": ["maple", "opentable", "resy", "sevenrooms"] }, "cancellation_policy": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-4217." }, "policy_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "within_hours_before_start": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "basis": { "type": "string", "description": "`per_party` or `per_person`." }, "amount_cents": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "percent_bps": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ], "description": "Basis points of the party value, when the fee is a percentage." } }, "required": ["within_hours_before_start", "basis", "amount_cents", "percent_bps"], "additionalProperties": false } }, "deposit": { "anyOf": [ { "type": "object", "properties": { "amount_cents": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "currency": { "type": "string" }, "basis": { "type": "string" } }, "required": ["amount_cents", "currency", "basis"], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["type", "currency", "policy_text", "tiers", "deposit"], "additionalProperties": false }, { "type": "null" } ] }, "experience": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Null when Maple has not seen the name." } }, "required": ["id", "name"], "additionalProperties": false }, { "type": "null" } ], "description": "The experience booked (prix fixe, ticketed seating), or null for a standard reservation." }, "updated_at": { "type": "string", "description": "ISO-8601 UTC instant." } }, "required": [ "object", "id", "livemode", "created", "version", "location_id", "status", "service_state", "confirmation_code", "starts_at", "starts_at_local", "service_date", "duration_minutes", "party_size", "guest", "notes", "channel", "provider", "cancellation_policy", "experience", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "409": { "description": "DeveloperApiConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiConflict" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Acts on behalf of the venue at a granted location. Requires bookings:manage. Returns the full booking; stale versions answer 409 stale_version, illegal transitions 409 illegal_transition with details.from_status, and unsupported providers 422 capability_unsupported.", "summary": "Complete booking", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "expected_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Optimistic concurrency: the `version` you last read. A booking that moved on since answers 409 `stale_version` with `details.expected`/`actual`." } }, "additionalProperties": false } } }, "required": true } } }, "/bookings/{bookingId}/no_show": { "post": { "tags": ["Bookings"], "operationId": "developer-api-bookings.markBookingNoShow", "parameters": [ { "name": "bookingId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["booking"] }, "id": { "type": "string", "description": "Opaque, prefixed `bkg_…`." }, "livemode": { "type": "boolean" }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "version": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "location_id": { "type": "string" }, "status": { "type": "string", "enum": [ "requested", "confirmed", "seated", "completed", "declined_by_venue", "cancelled_by_guest", "cancelled_by_venue", "cancelled_unattributed", "no_show" ] }, "service_state": { "anyOf": [ { "type": "string", "enum": ["expected", "arrived", "partially_seated", "fully_seated", "left"] }, { "type": "null" } ] }, "confirmation_code": { "type": "string" }, "starts_at": { "type": "string", "description": "ISO-8601 UTC instant." }, "starts_at_local": { "type": "string", "description": "Venue wall-clock, `YYYY-MM-DDTHH:MM`." }, "service_date": { "type": "string", "description": "The venue service day the booking belongs to, `YYYY-MM-DD`." }, "duration_minutes": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ], "description": "Turn duration; null on provider-managed bookings, where Maple never invents one." }, "party_size": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "guest": { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "E.164, when the guest left one." }, "phone_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["first_name", "last_name", "phone", "phone_last_four", "email"], "additionalProperties": false }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The guest-facing note; venue-internal notes are never exposed." }, "channel": { "type": "string", "description": "The channel the booking originated on, e.g. `api_partner`, `voice_ai`, `internal`." }, "provider": { "type": "string", "enum": ["maple", "opentable", "resy", "sevenrooms"] }, "cancellation_policy": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-4217." }, "policy_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "within_hours_before_start": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "basis": { "type": "string", "description": "`per_party` or `per_person`." }, "amount_cents": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "percent_bps": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ], "description": "Basis points of the party value, when the fee is a percentage." } }, "required": ["within_hours_before_start", "basis", "amount_cents", "percent_bps"], "additionalProperties": false } }, "deposit": { "anyOf": [ { "type": "object", "properties": { "amount_cents": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "currency": { "type": "string" }, "basis": { "type": "string" } }, "required": ["amount_cents", "currency", "basis"], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["type", "currency", "policy_text", "tiers", "deposit"], "additionalProperties": false }, { "type": "null" } ] }, "experience": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Null when Maple has not seen the name." } }, "required": ["id", "name"], "additionalProperties": false }, { "type": "null" } ], "description": "The experience booked (prix fixe, ticketed seating), or null for a standard reservation." }, "updated_at": { "type": "string", "description": "ISO-8601 UTC instant." } }, "required": [ "object", "id", "livemode", "created", "version", "location_id", "status", "service_state", "confirmation_code", "starts_at", "starts_at_local", "service_date", "duration_minutes", "party_size", "guest", "notes", "channel", "provider", "cancellation_policy", "experience", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "409": { "description": "DeveloperApiConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiConflict" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Acts on behalf of the venue at a granted location. Requires bookings:manage. Returns the full booking; stale versions answer 409 stale_version, illegal transitions 409 illegal_transition with details.from_status, and unsupported providers 422 capability_unsupported.", "summary": "Mark booking no-show", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "expected_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Optimistic concurrency: the `version` you last read. A booking that moved on since answers 409 `stale_version` with `details.expected`/`actual`." } }, "additionalProperties": false } } }, "required": true } } }, "/locations/{locationId}/booking_floor": { "get": { "tags": ["Bookings"], "operationId": "developer-api-bookings.getBookingFloor", "parameters": [ { "name": "locationId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["booking_floor"] }, "location_id": { "type": "string" }, "livemode": { "type": "boolean" }, "as_of": { "type": "string" }, "time_zone": { "type": "string" }, "tables": { "type": "array", "items": { "type": "object", "properties": { "unit_id": { "type": "string" }, "area_id": { "type": "string" }, "area_name": { "type": "string" }, "seats": { "type": "object", "properties": { "min": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": ["min", "max"], "additionalProperties": false }, "listed": { "type": "boolean" }, "state": { "type": "string", "enum": ["free", "seated", "reserved", "held", "maintenance"] }, "current": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": ["booking", "hold"] }, "booking_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "party_size": { "type": "integer" }, "started_at": { "type": "string" }, "ends_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "guest": { "anyOf": [ { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["first_name", "last_name", "phone_last_four"], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["kind", "booking_id", "party_size", "started_at", "ends_at", "guest"], "additionalProperties": false }, { "type": "null" } ] }, "next": { "anyOf": [ { "type": "object", "properties": { "booking_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "starts_at": { "type": "string" }, "party_size": { "type": "integer" } }, "required": ["booking_id", "starts_at", "party_size"], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["unit_id", "area_id", "area_name", "seats", "listed", "state", "current", "next"], "additionalProperties": false } }, "areas": { "type": "array", "items": { "type": "object", "properties": { "area_id": { "type": "string" }, "name": { "type": "string" }, "capacity": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "seats_in_use": { "type": "integer" } }, "required": ["area_id", "name", "capacity", "seats_in_use"], "additionalProperties": false } }, "summary": { "type": "object", "properties": { "tables_total": { "type": "integer" }, "tables_busy": { "type": "integer" }, "tables_out_of_service": { "type": "integer" }, "off_plan_parties": { "type": "integer" } }, "required": ["tables_total", "tables_busy", "tables_out_of_service", "off_plan_parties"], "additionalProperties": false } }, "required": ["object", "location_id", "livemode", "as_of", "time_zone", "tables", "areas", "summary"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Reads the live native floor, including current parties, holds, and the next claim within 24 hours. Requires bookings:read. Guest contact is limited to names and the last four phone digits. Read on demand or poll no more often than every 15 seconds; booking webhooks signal changes.", "summary": "Get booking floor" } }, "/locations/{locationId}/booking_configuration": { "get": { "tags": ["Bookings"], "operationId": "developer-api-bookings.getBookingConfiguration", "parameters": [ { "name": "locationId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeZone": { "type": "string" }, "currency": { "type": "string", "allOf": [ { "pattern": "^[A-Z]{3}$" } ] }, "areas": { "type": "array", "items": { "type": "object", "properties": { "poolId": { "type": "string", "allOf": [ { "minLength": 1 } ] }, "name": { "type": "string", "allOf": [ { "minLength": 1 } ] }, "kind": { "anyOf": [ { "type": "string", "enum": ["seat", "room", "generic"] }, { "type": "null" } ] }, "units": { "type": "array", "items": { "type": "object", "properties": { "unitId": { "type": "string", "allOf": [ { "minLength": 1 } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seats": { "type": "object", "properties": { "min": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 1 } ] }, { "type": "null" } ] }, "max": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 1 } ] }, { "type": "null" } ] } }, "additionalProperties": false }, "tags": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": ["unitId", "seats"], "additionalProperties": false }, "allOf": [ { "minItems": 1 } ] }, "combinations": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "unitIds": { "type": "array", "items": { "type": "string", "allOf": [ { "minLength": 1 } ] }, "allOf": [ { "minItems": 2 } ] }, "seats": { "type": "object", "properties": { "min": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 1 } ] }, { "type": "null" } ] }, "max": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 1 } ] }, { "type": "null" } ] } }, "additionalProperties": false } }, "required": ["unitIds", "seats"], "additionalProperties": false } }, { "type": "null" } ] } }, "required": ["poolId", "name", "units"], "additionalProperties": false }, "allOf": [ { "minItems": 1 } ] }, "turnBands": { "type": "array", "items": { "type": "object", "properties": { "minGuests": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 1 } ] }, { "type": "null" } ] }, "maxGuests": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 1 } ] }, { "type": "null" } ] }, "minutes": { "type": "integer", "allOf": [ { "minimum": 1 } ] } }, "required": ["minutes"], "additionalProperties": false }, "allOf": [ { "minItems": 1 } ] }, "shifts": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "enum": ["MON", "TUE", "WED", "THU", "FRI", "SAT", "SUN"] }, "start": { "type": "string", "allOf": [ { "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" } ] }, "end": { "type": "string", "allOf": [ { "pattern": "^(?:(?:[01]\\d|2[0-3]):[0-5]\\d|24:00)$" } ] } }, "required": ["day", "start", "end"], "additionalProperties": false }, "allOf": [ { "minItems": 1 } ] }, "pacing": { "anyOf": [ { "type": "object", "properties": { "intervalMinutes": { "type": "integer", "allOf": [ { "minimum": 1 } ] }, "maxCovers": { "type": "integer", "allOf": [ { "minimum": 1 } ] }, "enforcement": { "type": "string", "enum": ["hard", "soft"] } }, "required": ["intervalMinutes", "maxCovers", "enforcement"], "additionalProperties": false }, { "type": "null" } ] }, "bookingPolicy": { "anyOf": [ { "type": "object", "properties": { "minLeadMinutes": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 0 } ] }, { "type": "null" } ] }, "maxHorizonDays": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 1 } ] }, { "type": "null" } ] }, "slotAlignment": { "anyOf": [ { "type": "string", "enum": ["service_duration", "quarter_hourly", "half_hourly", "hourly"] }, { "type": "null" } ] }, "autoConfirm": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "cancellationPolicy": { "anyOf": [ { "type": "object", "properties": { "requiresCardOnFile": { "type": "boolean" }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "withinHoursBeforeStart": { "type": "integer", "allOf": [ { "minimum": 0 } ] }, "basis": { "type": "string", "enum": ["flat", "percent_of_subtotal", "full"] }, "flatAmountMinor": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 0 } ] }, { "type": "null" } ] }, "percentBps": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 0, "maximum": 10000 } ] }, { "type": "null" } ] } }, "required": ["withinHoursBeforeStart", "basis"], "additionalProperties": false } }, "rescheduleCutoffHours": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "policyText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["requiresCardOnFile", "tiers"], "additionalProperties": false }, { "type": "null" } ] }, "closedDates": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "revision": { "type": "string", "description": "Content revision of the configuration. Send it back as `expected_revision` to publish safely." }, "object": { "type": "string", "enum": ["booking_configuration"] }, "location_id": { "type": "string" }, "version_id": { "type": "string" }, "published_at": { "type": "string" }, "livemode": { "type": "boolean" } }, "required": [ "timeZone", "currency", "areas", "turnBands", "shifts", "revision", "object", "location_id", "version_id", "published_at", "livemode" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Reads the native booking configuration from the effective catalog, with its content `revision`. Requires bookings:read and a location grant. Returns 404 when no configuration has been authored.", "summary": "Get booking configuration" }, "post": { "tags": ["Bookings"], "operationId": "developer-api-bookings.publishBookingConfiguration", "parameters": [ { "name": "locationId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "timeZone": { "type": "string" }, "currency": { "type": "string", "allOf": [ { "pattern": "^[A-Z]{3}$" } ] }, "areas": { "type": "array", "items": { "type": "object", "properties": { "poolId": { "type": "string", "allOf": [ { "minLength": 1 } ] }, "name": { "type": "string", "allOf": [ { "minLength": 1 } ] }, "kind": { "anyOf": [ { "type": "string", "enum": ["seat", "room", "generic"] }, { "type": "null" } ] }, "units": { "type": "array", "items": { "type": "object", "properties": { "unitId": { "type": "string", "allOf": [ { "minLength": 1 } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seats": { "type": "object", "properties": { "min": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 1 } ] }, { "type": "null" } ] }, "max": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 1 } ] }, { "type": "null" } ] } }, "additionalProperties": false }, "tags": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": ["unitId", "seats"], "additionalProperties": false }, "allOf": [ { "minItems": 1 } ] }, "combinations": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "unitIds": { "type": "array", "items": { "type": "string", "allOf": [ { "minLength": 1 } ] }, "allOf": [ { "minItems": 2 } ] }, "seats": { "type": "object", "properties": { "min": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 1 } ] }, { "type": "null" } ] }, "max": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 1 } ] }, { "type": "null" } ] } }, "additionalProperties": false } }, "required": ["unitIds", "seats"], "additionalProperties": false } }, { "type": "null" } ] } }, "required": ["poolId", "name", "units"], "additionalProperties": false }, "allOf": [ { "minItems": 1 } ] }, "turnBands": { "type": "array", "items": { "type": "object", "properties": { "minGuests": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 1 } ] }, { "type": "null" } ] }, "maxGuests": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 1 } ] }, { "type": "null" } ] }, "minutes": { "type": "integer", "allOf": [ { "minimum": 1 } ] } }, "required": ["minutes"], "additionalProperties": false }, "allOf": [ { "minItems": 1 } ] }, "shifts": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "enum": ["MON", "TUE", "WED", "THU", "FRI", "SAT", "SUN"] }, "start": { "type": "string", "allOf": [ { "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" } ] }, "end": { "type": "string", "allOf": [ { "pattern": "^(?:(?:[01]\\d|2[0-3]):[0-5]\\d|24:00)$" } ] } }, "required": ["day", "start", "end"], "additionalProperties": false }, "allOf": [ { "minItems": 1 } ] }, "pacing": { "anyOf": [ { "type": "object", "properties": { "intervalMinutes": { "type": "integer", "allOf": [ { "minimum": 1 } ] }, "maxCovers": { "type": "integer", "allOf": [ { "minimum": 1 } ] }, "enforcement": { "type": "string", "enum": ["hard", "soft"] } }, "required": ["intervalMinutes", "maxCovers", "enforcement"], "additionalProperties": false }, { "type": "null" } ] }, "bookingPolicy": { "anyOf": [ { "type": "object", "properties": { "minLeadMinutes": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 0 } ] }, { "type": "null" } ] }, "maxHorizonDays": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 1 } ] }, { "type": "null" } ] }, "slotAlignment": { "anyOf": [ { "type": "string", "enum": ["service_duration", "quarter_hourly", "half_hourly", "hourly"] }, { "type": "null" } ] }, "autoConfirm": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "cancellationPolicy": { "anyOf": [ { "type": "object", "properties": { "requiresCardOnFile": { "type": "boolean" }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "withinHoursBeforeStart": { "type": "integer", "allOf": [ { "minimum": 0 } ] }, "basis": { "type": "string", "enum": ["flat", "percent_of_subtotal", "full"] }, "flatAmountMinor": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 0 } ] }, { "type": "null" } ] }, "percentBps": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 0, "maximum": 10000 } ] }, { "type": "null" } ] } }, "required": ["withinHoursBeforeStart", "basis"], "additionalProperties": false } }, "rescheduleCutoffHours": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "policyText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["requiresCardOnFile", "tiers"], "additionalProperties": false }, { "type": "null" } ] }, "closedDates": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "revision": { "type": "string", "description": "Content revision of the configuration. Send it back as `expected_revision` to publish safely." }, "object": { "type": "string", "enum": ["booking_configuration"] }, "location_id": { "type": "string" }, "version_id": { "type": "string" }, "published_at": { "type": "string" }, "livemode": { "type": "boolean" } }, "required": [ "timeZone", "currency", "areas", "turnBands", "shifts", "revision", "object", "location_id", "version_id", "published_at", "livemode" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "409": { "description": "DeveloperApiConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiConflict" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Replaces the booking configuration while preserving menu objects. Requires bookings:configure, a location grant, and the bookings-public-api rollout flag. An identical document is a content-addressed no-op. Provider-managed locations are unsupported. A location without a connection can be configured, but publishing does not enable bookings or change its rollout flags. Send the `revision` you read as `expected_revision` so a configuration changed since (a manager editing it in the Maple dashboard, or another app) answers 409 `stale_configuration` instead of being overwritten.", "summary": "Publish booking configuration", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "timeZone": { "type": "string" }, "currency": { "type": "string", "allOf": [ { "pattern": "^[A-Z]{3}$" } ] }, "areas": { "type": "array", "items": { "type": "object", "properties": { "poolId": { "type": "string", "allOf": [ { "minLength": 1 } ] }, "name": { "type": "string", "allOf": [ { "minLength": 1 } ] }, "kind": { "anyOf": [ { "type": "string", "enum": ["seat", "room", "generic"] }, { "type": "null" } ] }, "units": { "type": "array", "items": { "type": "object", "properties": { "unitId": { "type": "string", "allOf": [ { "minLength": 1 } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seats": { "type": "object", "properties": { "min": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 1 } ] }, { "type": "null" } ] }, "max": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 1 } ] }, { "type": "null" } ] } }, "additionalProperties": false }, "tags": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": ["unitId", "seats"], "additionalProperties": false }, "allOf": [ { "minItems": 1 } ] }, "combinations": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "unitIds": { "type": "array", "items": { "type": "string", "allOf": [ { "minLength": 1 } ] }, "allOf": [ { "minItems": 2 } ] }, "seats": { "type": "object", "properties": { "min": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 1 } ] }, { "type": "null" } ] }, "max": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 1 } ] }, { "type": "null" } ] } }, "additionalProperties": false } }, "required": ["unitIds", "seats"], "additionalProperties": false } }, { "type": "null" } ] } }, "required": ["poolId", "name", "units"], "additionalProperties": false }, "allOf": [ { "minItems": 1 } ] }, "turnBands": { "type": "array", "items": { "type": "object", "properties": { "minGuests": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 1 } ] }, { "type": "null" } ] }, "maxGuests": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 1 } ] }, { "type": "null" } ] }, "minutes": { "type": "integer", "allOf": [ { "minimum": 1 } ] } }, "required": ["minutes"], "additionalProperties": false }, "allOf": [ { "minItems": 1 } ] }, "shifts": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "enum": ["MON", "TUE", "WED", "THU", "FRI", "SAT", "SUN"] }, "start": { "type": "string", "allOf": [ { "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" } ] }, "end": { "type": "string", "allOf": [ { "pattern": "^(?:(?:[01]\\d|2[0-3]):[0-5]\\d|24:00)$" } ] } }, "required": ["day", "start", "end"], "additionalProperties": false }, "allOf": [ { "minItems": 1 } ] }, "pacing": { "anyOf": [ { "type": "object", "properties": { "intervalMinutes": { "type": "integer", "allOf": [ { "minimum": 1 } ] }, "maxCovers": { "type": "integer", "allOf": [ { "minimum": 1 } ] }, "enforcement": { "type": "string", "enum": ["hard", "soft"] } }, "required": ["intervalMinutes", "maxCovers", "enforcement"], "additionalProperties": false }, { "type": "null" } ] }, "bookingPolicy": { "anyOf": [ { "type": "object", "properties": { "minLeadMinutes": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 0 } ] }, { "type": "null" } ] }, "maxHorizonDays": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 1 } ] }, { "type": "null" } ] }, "slotAlignment": { "anyOf": [ { "type": "string", "enum": ["service_duration", "quarter_hourly", "half_hourly", "hourly"] }, { "type": "null" } ] }, "autoConfirm": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "cancellationPolicy": { "anyOf": [ { "type": "object", "properties": { "requiresCardOnFile": { "type": "boolean" }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "withinHoursBeforeStart": { "type": "integer", "allOf": [ { "minimum": 0 } ] }, "basis": { "type": "string", "enum": ["flat", "percent_of_subtotal", "full"] }, "flatAmountMinor": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 0 } ] }, { "type": "null" } ] }, "percentBps": { "anyOf": [ { "type": "integer", "allOf": [ { "minimum": 0, "maximum": 10000 } ] }, { "type": "null" } ] } }, "required": ["withinHoursBeforeStart", "basis"], "additionalProperties": false } }, "rescheduleCutoffHours": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "policyText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["requiresCardOnFile", "tiers"], "additionalProperties": false }, { "type": "null" } ] }, "closedDates": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "expected_revision": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ], "description": "The `revision` you read. The publish is refused with 409 `stale_configuration` if the configuration changed since (for example, a manager edited it in the Maple dashboard). `null` = you expect no configuration yet. Omit to replace it unconditionally." } }, "required": ["timeZone", "currency", "areas", "turnBands", "shifts"], "additionalProperties": false } } }, "required": true } } }, "/locations/{locationId}/booking_blackouts": { "put": { "tags": ["Bookings"], "operationId": "developer-api-bookings.setBookingBlackouts", "parameters": [ { "name": "locationId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["booking_blackouts"] }, "location_id": { "type": "string" }, "blackout_dates": { "type": "array", "items": { "type": "object", "properties": { "start_date": { "type": "string", "description": "First blocked day, venue-local `YYYY-MM-DD`." }, "end_date": { "type": "string", "description": "Last blocked day, inclusive, venue-local `YYYY-MM-DD`." }, "start_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Venue-local `HH:MM` the block starts on `start_date`; null blocks from the start of that day." }, "end_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Venue-local `HH:MM` the block ends on `end_date`, inclusive; null blocks through the end of that day." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The venue’s note, e.g. “Private event”." } }, "required": ["start_date", "end_date", "start_time", "end_time", "reason"], "additionalProperties": false }, "description": "In start order." }, "revision": { "type": "string", "description": "The list’s revision. Send it as `expected_revision` on your next write to refuse one that would overwrite a change made since." } }, "required": ["object", "location_id", "blackout_dates", "revision"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "409": { "description": "DeveloperApiConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiConflict" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Replaces the location’s whole list of blackout windows: days or part-days when it takes no reservations, such as a private event. Maple enforces them for native and provider-managed locations alike: availability omits the slots, and a quote taken earlier is refused when held, booked, or used for a change (409 `slot_unavailable` natively, 422 `date_blocked` for provider-managed locations). Existing bookings inside a new window are not cancelled, and walk-ins and waitlist seating are not blocked: a blackout stops reservations only. The venue edits the same list in its dashboard: read `blackout_dates` and `blackout_dates_revision` on the booking profile, and send the revision as `expected_revision` so a list changed since answers 409 `stale_blackout_dates` instead of being overwritten. Invalid ranges answer 400 `invalid_blackout_dates`. Requires `bookings:configure`.", "summary": "Replace booking blackout dates", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "blackout_dates": { "type": "array", "items": { "type": "object", "properties": { "start_date": { "type": "string", "description": "First blocked day, venue-local `YYYY-MM-DD`." }, "end_date": { "type": "string", "description": "Last blocked day, inclusive, venue-local `YYYY-MM-DD`." }, "start_time": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ], "description": "Venue-local `HH:MM` the block starts on `start_date`; omit or null to block from the start of the day." }, "end_time": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ], "description": "Venue-local `HH:MM` the block ends on `end_date`, inclusive; omit or null to block through the end of the day." }, "reason": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ], "description": "A note for the venue’s staff, at most 200 characters." } }, "required": ["start_date", "end_date"], "additionalProperties": false }, "description": "The location’s whole list, at most 100 ranges. An empty list clears every blackout." }, "expected_revision": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The `blackout_dates_revision` (or `revision`) you last read. A list changed since answers 409 `stale_blackout_dates` and nothing is written. Omit it to replace the list regardless." } }, "required": ["blackout_dates"], "additionalProperties": false } } }, "required": true } } }, "/locations/{locationId}/booking_profile": { "get": { "tags": ["Bookings"], "operationId": "developer-api-bookings.getBookingProfile", "parameters": [ { "name": "locationId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["booking_profile"] }, "location_id": { "type": "string" }, "livemode": { "type": "boolean", "description": "True when read with a live credential; test credentials only ever see test-mode data." }, "enabled": { "type": "boolean", "description": "True when this location accepts partner bookings through the Developer API right now. When false, every other bookings endpoint for the location returns `bookings_not_enabled`." }, "provider": { "anyOf": [ { "type": "string", "enum": ["maple", "opentable", "resy", "sevenrooms"] }, { "type": "null" } ], "description": "The provider behind the location’s booking connection, or null when none is configured." }, "capabilities": { "type": "object", "properties": { "hold_release": { "type": "boolean", "description": "Whether `DELETE /booking_holds/{holdId}` releases capacity early (provider locks only expire)." }, "confirm_decline": { "type": "boolean", "description": "Whether the venue verbs `confirm` and `decline` are accepted for this location." }, "seat": { "type": "boolean", "description": "Whether the venue verb `seat` is accepted for this location." }, "no_show": { "type": "boolean", "description": "Whether the venue verb `no_show` is accepted for this location." }, "window_lookup": { "type": "boolean", "description": "Whether bookings can be listed by time window (provider-managed stores only expose lookups by guest)." }, "floor_status": { "type": "boolean", "description": "Whether the live floor (`GET /locations/{locationId}/booking_floor`) is available — Maple-native stores only." }, "experiences": { "type": "boolean", "description": "Whether availability lists experiences (prix fixe, ticketed seatings) and `experience_id` narrows a search to one. Offered where the provider lists them (OpenTable); Maple-native locations do not offer experiences yet." } }, "required": [ "hold_release", "confirm_decline", "seat", "no_show", "window_lookup", "floor_status", "experiences" ], "additionalProperties": false }, "blackout_dates": { "type": "array", "items": { "type": "object", "properties": { "start_date": { "type": "string", "description": "First blocked day, venue-local `YYYY-MM-DD`." }, "end_date": { "type": "string", "description": "Last blocked day, inclusive, venue-local `YYYY-MM-DD`." }, "start_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Venue-local `HH:MM` the block starts on `start_date`; null blocks from the start of that day." }, "end_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Venue-local `HH:MM` the block ends on `end_date`, inclusive; null blocks through the end of that day." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The venue’s note, e.g. “Private event”." } }, "required": ["start_date", "end_date", "start_time", "end_time", "reason"], "additionalProperties": false }, "description": "Windows when the location takes no reservations, in start order (walk-ins and waitlist seating are unaffected). Availability omits slots inside them. A quote taken before a window was added is refused when held, booked, or used for a change: 409 `slot_unavailable` at Maple-native locations, whose engine also withholds seatings that would run into a window, and 422 `date_blocked` at provider-managed ones." }, "blackout_dates_revision": { "type": "string", "description": "The revision of `blackout_dates`. Send it as `expected_revision` to `PUT /booking_blackouts` so the write is refused (409 `stale_blackout_dates`) if the venue changed the list since you read it." }, "hold_ttl_seconds": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ], "description": "How long a hold taken through `POST /booking_holds` claims capacity before it expires, when Maple enforces the hold lifetime. Null when the location’s provider owns hold expiry (read `expires_at` on each hold) or no provider is configured." } }, "required": [ "object", "location_id", "livemode", "enabled", "provider", "capabilities", "blackout_dates", "blackout_dates_revision", "hold_ttl_seconds" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Whether a granted location accepts partner bookings right now, which provider serves it, the capability set its provider declares (hold release, venue verbs, time-window listing, live floor), and the hold TTL. Read this before calling any other bookings endpoint: `enabled: false` means the location is not bookable through the Developer API yet, and a `false` capability is what the matching verb answers with `capability_unsupported`. Requires `bookings:read`.", "summary": "Get booking profile" } }, "/bookings": { "get": { "tags": ["Bookings"], "operationId": "developer-api-bookings.listBookings", "parameters": [ { "name": "location_id", "in": "query", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Restrict to one granted location. Default: every location the app is granted." }, "required": false }, { "name": "start", "in": "query", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601 instant. With `end`, lists bookings whose slot starts in [start, end) — at most 31 days. Default window: now to now + 7 days." }, "required": false }, { "name": "end", "in": "query", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601 instant, exclusive. Required with `start`." }, "required": false }, { "name": "updated_since", "in": "query", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601 instant, exclusive checkpoint. Drains bookings updated after it oldest-first — the catch-up path after downtime. Mutually exclusive with `start`/`end`." }, "required": false }, { "name": "status", "in": "query", "schema": { "anyOf": [ { "type": "string", "enum": [ "requested", "confirmed", "seated", "completed", "declined_by_venue", "cancelled_by_guest", "cancelled_by_venue", "cancelled_unattributed", "no_show" ] }, { "type": "null" } ] }, "required": false }, { "name": "phone", "in": "query", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Find a guest’s bookings by the phone on the booking. E.164, or a US number without +1 and with any formatting; it is normalized before matching. Requires `location_id`. Without a window, matches bookings at any time." }, "required": false }, { "name": "confirmation_code", "in": "query", "schema": { "anyOf": [ { "type": "string", "allOf": [ { "minLength": 1 }, { "maxLength": 64 } ] }, { "type": "null" } ], "description": "Find a booking by the `confirmation_code` the guest was given, exactly as the booking shows it. Requires `location_id`. Without a window, matches bookings at any time." }, "required": false }, { "name": "starting_after", "in": "query", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The previous page’s `next_cursor` (opaque). Omit for the first page." }, "required": false }, { "name": "limit", "in": "query", "schema": { "anyOf": [ { "type": "string", "allOf": [ { "pattern": "^[+-]?\\d*\\.?\\d+(?:[Ee][+-]?\\d+)?$" } ] }, { "type": "null" } ], "description": "Page size, 1–100. Default 20." }, "required": false } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": ["booking"] }, "id": { "type": "string", "description": "Opaque, prefixed `bkg_…`." }, "livemode": { "type": "boolean" }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "version": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "location_id": { "type": "string" }, "status": { "type": "string", "enum": [ "requested", "confirmed", "seated", "completed", "declined_by_venue", "cancelled_by_guest", "cancelled_by_venue", "cancelled_unattributed", "no_show" ] }, "service_state": { "anyOf": [ { "type": "string", "enum": ["expected", "arrived", "partially_seated", "fully_seated", "left"] }, { "type": "null" } ] }, "confirmation_code": { "type": "string" }, "starts_at": { "type": "string", "description": "ISO-8601 UTC instant." }, "starts_at_local": { "type": "string", "description": "Venue wall-clock, `YYYY-MM-DDTHH:MM`." }, "service_date": { "type": "string", "description": "The venue service day the booking belongs to, `YYYY-MM-DD`." }, "duration_minutes": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ], "description": "Turn duration; null on provider-managed bookings, where Maple never invents one." }, "party_size": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "guest": { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "E.164, when the guest left one." }, "phone_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["first_name", "last_name", "phone", "phone_last_four", "email"], "additionalProperties": false }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The guest-facing note; venue-internal notes are never exposed." }, "channel": { "type": "string", "description": "The channel the booking originated on, e.g. `api_partner`, `voice_ai`, `internal`." }, "provider": { "type": "string", "enum": ["maple", "opentable", "resy", "sevenrooms"] }, "cancellation_policy": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-4217." }, "policy_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "within_hours_before_start": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "basis": { "type": "string", "description": "`per_party` or `per_person`." }, "amount_cents": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "percent_bps": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ], "description": "Basis points of the party value, when the fee is a percentage." } }, "required": ["within_hours_before_start", "basis", "amount_cents", "percent_bps"], "additionalProperties": false } }, "deposit": { "anyOf": [ { "type": "object", "properties": { "amount_cents": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "currency": { "type": "string" }, "basis": { "type": "string" } }, "required": ["amount_cents", "currency", "basis"], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["type", "currency", "policy_text", "tiers", "deposit"], "additionalProperties": false }, { "type": "null" } ] }, "experience": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Null when Maple has not seen the name." } }, "required": ["id", "name"], "additionalProperties": false }, { "type": "null" } ], "description": "The experience booked (prix fixe, ticketed seating), or null for a standard reservation." }, "updated_at": { "type": "string", "description": "ISO-8601 UTC instant." } }, "required": [ "object", "id", "livemode", "created", "version", "location_id", "status", "service_state", "confirmation_code", "starts_at", "starts_at_local", "service_date", "duration_minutes", "party_size", "guest", "notes", "channel", "provider", "cancellation_policy", "experience", "updated_at" ], "additionalProperties": false } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next page — pass it back as `starting_after`. Null on the last page. It encodes the position observed on this page, so it stays correct even if the last booking changes in between." } }, "required": ["object", "data", "has_more", "next_cursor"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Lists bookings across the locations the app is granted (or one `location_id`). Two modes: a bounded slot window (`start`/`end`, at most 31 days, default the next 7 days) ordered by slot start, or `updated_since`, which drains bookings updated after an exclusive checkpoint oldest-first so a partner can catch up after downtime. Page with `limit` and the previous page’s `next_cursor` as `starting_after`; `has_more` says whether another page exists. Ties on the ordering timestamp never skip or repeat, and a booking that changes between pages simply re-enters the feed. Take the next `updated_since` checkpoint from the newest `updated_at` you have processed minus a few seconds of overlap and dedupe by `id` + `version`: a booking committed after your drain can carry an `updated_at` set when its transaction began. To find the booking a guest is calling about, pass `location_id` with `phone` and/or `confirmation_code`: without a window this matches bookings at any time, ordered by slot start; add `start`/`end` to narrow it. At a provider-managed location a lookup with `phone` first checks the provider, so a reservation made directly there is found; a code-only lookup covers the reservations Maple already knows about. A lookup without `location_id` answers 400 `location_required`, an unusable phone 400 `invalid_phone`. Locations the bookings surface is not switched on for are omitted (an explicit `location_id` answers 422 `bookings_not_enabled`). Requires `bookings:read`.", "summary": "List bookings" }, "post": { "tags": ["Bookings"], "operationId": "developer-api-bookings.createBooking", "parameters": [], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["booking"] }, "id": { "type": "string", "description": "Opaque, prefixed `bkg_…`." }, "livemode": { "type": "boolean" }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "version": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "location_id": { "type": "string" }, "status": { "type": "string", "enum": [ "requested", "confirmed", "seated", "completed", "declined_by_venue", "cancelled_by_guest", "cancelled_by_venue", "cancelled_unattributed", "no_show" ] }, "service_state": { "anyOf": [ { "type": "string", "enum": ["expected", "arrived", "partially_seated", "fully_seated", "left"] }, { "type": "null" } ] }, "confirmation_code": { "type": "string" }, "starts_at": { "type": "string", "description": "ISO-8601 UTC instant." }, "starts_at_local": { "type": "string", "description": "Venue wall-clock, `YYYY-MM-DDTHH:MM`." }, "service_date": { "type": "string", "description": "The venue service day the booking belongs to, `YYYY-MM-DD`." }, "duration_minutes": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ], "description": "Turn duration; null on provider-managed bookings, where Maple never invents one." }, "party_size": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "guest": { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "E.164, when the guest left one." }, "phone_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["first_name", "last_name", "phone", "phone_last_four", "email"], "additionalProperties": false }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The guest-facing note; venue-internal notes are never exposed." }, "channel": { "type": "string", "description": "The channel the booking originated on, e.g. `api_partner`, `voice_ai`, `internal`." }, "provider": { "type": "string", "enum": ["maple", "opentable", "resy", "sevenrooms"] }, "cancellation_policy": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-4217." }, "policy_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "within_hours_before_start": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "basis": { "type": "string", "description": "`per_party` or `per_person`." }, "amount_cents": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "percent_bps": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ], "description": "Basis points of the party value, when the fee is a percentage." } }, "required": ["within_hours_before_start", "basis", "amount_cents", "percent_bps"], "additionalProperties": false } }, "deposit": { "anyOf": [ { "type": "object", "properties": { "amount_cents": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "currency": { "type": "string" }, "basis": { "type": "string" } }, "required": ["amount_cents", "currency", "basis"], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["type", "currency", "policy_text", "tiers", "deposit"], "additionalProperties": false }, { "type": "null" } ] }, "experience": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Null when Maple has not seen the name." } }, "required": ["id", "name"], "additionalProperties": false }, { "type": "null" } ], "description": "The experience booked (prix fixe, ticketed seating), or null for a standard reservation." }, "updated_at": { "type": "string", "description": "ISO-8601 UTC instant." } }, "required": [ "object", "id", "livemode", "created", "version", "location_id", "status", "service_state", "confirmation_code", "starts_at", "starts_at_local", "service_date", "duration_minutes", "party_size", "guest", "notes", "channel", "provider", "cancellation_policy", "experience", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "409": { "description": "DeveloperApiConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiConflict" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Books the party a hold claims, synchronously, and returns the full `booking`. The location is the hold’s. `status` follows the venue’s acceptance mode (`confirmed`, or `requested` where the venue confirms by hand) and `version` starts at 0. A guest contact is required on this channel. Writes carry a body-level idempotency_key. Native and provider writes replay the same booking without reapplying the mutation. An uncertain provider result answers 409 operation_in_progress; retry the same key and body. If details.reason is replay_window_expired, contact support with the operation id rather than issuing a new key. Typed refusals: 409 `hold_expired` / `hold_consumed` / `overlapping_booking` / `idempotency_key_reused`; 422 `guest_contact_required`, `payment_instrument_required`, `provider_rejected`; 400 `invalid_phone`. Requires `bookings:write`.", "summary": "Create booking", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "hold_id": { "type": "string", "description": "The hold to book from (`POST /booking_holds`)." }, "slot_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional for existing integrations. The persisted hold supplies the authoritative quote for native and provider-managed locations." }, "guest": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "type": "string", "description": "E.164. A partner booking must carry a reachable guest contact; the venue contacts the guest here." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["first_name", "last_name", "phone"], "additionalProperties": false }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The guest’s note to the venue." }, "intake_answers": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "question_ref": { "type": "string", "description": "The venue’s intake question reference." }, "answer": { "anyOf": [ { "type": "string" }, { "type": "boolean" }, { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "array", "items": { "type": "string" } } ], "description": "Free text, yes/no, a number, or the chosen option references — per the question’s kind." } }, "required": ["question_ref", "answer"], "additionalProperties": false } }, { "type": "null" } ], "description": "Structured intake for native bookings. OpenTable does not support these answers and returns 422 capability_unsupported instead of dropping them." }, "idempotency_key": { "type": "string", "allOf": [ { "minLength": 1 }, { "maxLength": 255, "description": "Your unique key for this write (body-level, scoped to your app). Retrying with the same key and the same request replays the same booking; the same key with a different request answers 409 `idempotency_key_reused`." } ] } }, "required": ["hold_id", "guest", "idempotency_key"], "additionalProperties": false } } }, "required": true } } }, "/bookings/{bookingId}": { "get": { "tags": ["Bookings"], "operationId": "developer-api-bookings.getBooking", "parameters": [ { "name": "bookingId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["booking"] }, "id": { "type": "string", "description": "Opaque, prefixed `bkg_…`." }, "livemode": { "type": "boolean" }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "version": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "location_id": { "type": "string" }, "status": { "type": "string", "enum": [ "requested", "confirmed", "seated", "completed", "declined_by_venue", "cancelled_by_guest", "cancelled_by_venue", "cancelled_unattributed", "no_show" ] }, "service_state": { "anyOf": [ { "type": "string", "enum": ["expected", "arrived", "partially_seated", "fully_seated", "left"] }, { "type": "null" } ] }, "confirmation_code": { "type": "string" }, "starts_at": { "type": "string", "description": "ISO-8601 UTC instant." }, "starts_at_local": { "type": "string", "description": "Venue wall-clock, `YYYY-MM-DDTHH:MM`." }, "service_date": { "type": "string", "description": "The venue service day the booking belongs to, `YYYY-MM-DD`." }, "duration_minutes": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ], "description": "Turn duration; null on provider-managed bookings, where Maple never invents one." }, "party_size": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "guest": { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "E.164, when the guest left one." }, "phone_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["first_name", "last_name", "phone", "phone_last_four", "email"], "additionalProperties": false }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The guest-facing note; venue-internal notes are never exposed." }, "channel": { "type": "string", "description": "The channel the booking originated on, e.g. `api_partner`, `voice_ai`, `internal`." }, "provider": { "type": "string", "enum": ["maple", "opentable", "resy", "sevenrooms"] }, "cancellation_policy": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-4217." }, "policy_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "within_hours_before_start": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "basis": { "type": "string", "description": "`per_party` or `per_person`." }, "amount_cents": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "percent_bps": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ], "description": "Basis points of the party value, when the fee is a percentage." } }, "required": ["within_hours_before_start", "basis", "amount_cents", "percent_bps"], "additionalProperties": false } }, "deposit": { "anyOf": [ { "type": "object", "properties": { "amount_cents": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "currency": { "type": "string" }, "basis": { "type": "string" } }, "required": ["amount_cents", "currency", "basis"], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["type", "currency", "policy_text", "tiers", "deposit"], "additionalProperties": false }, { "type": "null" } ] }, "experience": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Null when Maple has not seen the name." } }, "required": ["id", "name"], "additionalProperties": false }, { "type": "null" } ], "description": "The experience booked (prix fixe, ticketed seating), or null for a standard reservation." }, "updated_at": { "type": "string", "description": "ISO-8601 UTC instant." } }, "required": [ "object", "id", "livemode", "created", "version", "location_id", "status", "service_state", "confirmation_code", "starts_at", "starts_at_local", "service_date", "duration_minutes", "party_size", "guest", "notes", "channel", "provider", "cancellation_policy", "experience", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Returns a single booking if it belongs to a location the app is granted. The same shape is embedded in `booking.*` webhook payloads. Requires `bookings:read`.", "summary": "Get booking" } }, "/locations/{locationId}/booking_availability": { "get": { "tags": ["Bookings"], "operationId": "developer-api-bookings.getBookingAvailability", "parameters": [ { "name": "locationId", "in": "path", "schema": { "type": "string" }, "required": true }, { "name": "party_size", "in": "query", "schema": { "type": "string", "allOf": [ { "pattern": "^[+-]?\\d*\\.?\\d+(?:[Ee][+-]?\\d+)?$" } ] }, "required": true }, { "name": "start", "in": "query", "schema": { "type": "string", "description": "Venue-local wall-clock start of the search window, `YYYY-MM-DDTHH:MM`." }, "required": true }, { "name": "end", "in": "query", "schema": { "type": "string", "description": "Venue-local wall-clock end of the search window, `YYYY-MM-DDTHH:MM`, at most 31 days after `start`." }, "required": true }, { "name": "changing_booking_id", "in": "query", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reschedule mode: exclude this booking’s own claim from occupancy so its current slot (or a neighbour) can be re-quoted. The resulting `slot_token` is what `POST /bookings/{id}/change` takes." }, "required": false }, { "name": "experience_id", "in": "query", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only this experience’s slots (an `experience.id` from an earlier search). Where the location does not offer experiences (`capabilities.experiences` false) it answers 422 `capability_unsupported`." }, "required": false } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["list"] }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": ["booking_slot"] }, "slot_token": { "type": "string" }, "starts_at": { "type": "string" }, "starts_at_local": { "type": "string" }, "duration_minutes": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "area": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["ref", "name"], "additionalProperties": false }, { "type": "null" } ], "description": "The seating area the slot is quoted in, when the provider names one." }, "cancellation_policy": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-4217." }, "policy_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "within_hours_before_start": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "basis": { "type": "string", "description": "`per_party` or `per_person`." }, "amount_cents": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "percent_bps": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ], "description": "Basis points of the party value, when the fee is a percentage." } }, "required": ["within_hours_before_start", "basis", "amount_cents", "percent_bps"], "additionalProperties": false } }, "deposit": { "anyOf": [ { "type": "object", "properties": { "amount_cents": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "currency": { "type": "string" }, "basis": { "type": "string" } }, "required": ["amount_cents", "currency", "basis"], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["type", "currency", "policy_text", "tiers", "deposit"], "additionalProperties": false }, { "type": "null" } ] }, "experience": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "The experience id; pass it as `experience_id` to search only its slots." }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prepayment_required": { "type": "boolean", "description": "The experience asks for payment up front. Maple cannot take payment yet, so holding such a slot answers 422 `payment_instrument_required`: show it, but offer a standard slot to book." } }, "required": ["id", "name", "description", "prepayment_required"], "additionalProperties": false }, { "type": "null" } ], "description": "The experience this slot books, or null for a standard reservation. The slot token is bound to it: holding and booking the slot books the experience." } }, "required": [ "object", "slot_token", "starts_at", "starts_at_local", "duration_minutes", "area", "cancellation_policy", "experience" ], "additionalProperties": false } } }, "required": ["object", "data"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "409": { "description": "DeveloperApiConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiConflict" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Bookable slots for a party at a granted location inside a venue-local window (at most 31 days), in start order. Standard slots have `experience: null`; where the location offers experiences, their slots are listed too, each naming its `experience`, and `experience_id` narrows the search to one. Every slot carries an opaque signed `slot_token`: pass it unchanged to `POST /booking_holds`, never rebuild slot parameters yourself. Quotes are bound to the partner channel and expire after 15 minutes. Typed outcomes (`party_size_out_of_bounds` with the bounds, `outside_booking_window`, `large_party_inquiry_required` with the venue’s inquiry contact, `bookings_not_enabled`) come back as 422 with a `code`. Requires `bookings:read`.", "summary": "Search booking availability" } }, "/booking_holds": { "post": { "tags": ["Bookings"], "operationId": "developer-api-bookings.createBookingHold", "parameters": [], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["booking_hold"] }, "id": { "type": "string", "description": "Opaque. `bkh_…` for a hold in Maple’s ledger; at a provider-managed location, the provider’s own hold token. Round-trip it unchanged." }, "livemode": { "type": "boolean" }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "location_id": { "type": "string" }, "starts_at": { "type": "string", "description": "ISO-8601 UTC instant of the held slot." }, "party_size": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "expires_at": { "type": "string", "description": "ISO-8601 UTC instant after which the hold no longer claims capacity." } }, "required": [ "object", "id", "livemode", "created", "location_id", "starts_at", "party_size", "expires_at" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "409": { "description": "DeveloperApiConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiConflict" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiRateLimited1" }, { "$ref": "#/components/schemas/DeveloperApiRateLimited" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Claims a quoted slot’s capacity until `expires_at` (see the location’s `hold_ttl_seconds`), so the party can be booked with `POST /bookings`. The location is the one the token was quoted for and must be granted to the app. A slot whose capacity is gone answers 409 `slot_unavailable`; a tampered or stale token 400 `invalid_slot_token` / `expired_slot_token`. Each app may have ten live or pending holds per location, enforced atomically for native and provider holds. All hold IDs use bkh_; only the creating app can release or consume them. Over quota answers 429 with retry_after and Retry-After. Pending provider acquisitions answer 409 operation_in_progress; replay the same token. Requires `bookings:write`.", "summary": "Hold a slot", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "slot_token": { "type": "string", "description": "A `slot_token` from a booking availability search, unchanged." } }, "required": ["slot_token"], "additionalProperties": false } } }, "required": true } } }, "/booking_holds/{holdId}": { "delete": { "tags": ["Bookings"], "operationId": "developer-api-bookings.releaseBookingHold", "parameters": [ { "name": "holdId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["booking_hold.released"] }, "id": { "type": "string" }, "released": { "type": "boolean", "enum": [true] } }, "required": ["object", "id", "released"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "409": { "description": "DeveloperApiConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiConflict" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Releases a hold early so its capacity is offered again. Idempotent: releasing a hold that already expired or was released succeeds; a hold already consumed by a booking answers 409 `hold_consumed`. Unknown holds and holds owned by another app return 404. Provider-managed locations cannot release early: the call succeeds without changing the lock or quota usage; expiry or consumption frees it. Requires `bookings:write`.", "summary": "Release a hold" } }, "/bookings/{bookingId}/change": { "post": { "tags": ["Bookings"], "operationId": "developer-api-bookings.changeBooking", "parameters": [ { "name": "bookingId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["booking"] }, "id": { "type": "string", "description": "Opaque, prefixed `bkg_…`." }, "livemode": { "type": "boolean" }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "version": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "location_id": { "type": "string" }, "status": { "type": "string", "enum": [ "requested", "confirmed", "seated", "completed", "declined_by_venue", "cancelled_by_guest", "cancelled_by_venue", "cancelled_unattributed", "no_show" ] }, "service_state": { "anyOf": [ { "type": "string", "enum": ["expected", "arrived", "partially_seated", "fully_seated", "left"] }, { "type": "null" } ] }, "confirmation_code": { "type": "string" }, "starts_at": { "type": "string", "description": "ISO-8601 UTC instant." }, "starts_at_local": { "type": "string", "description": "Venue wall-clock, `YYYY-MM-DDTHH:MM`." }, "service_date": { "type": "string", "description": "The venue service day the booking belongs to, `YYYY-MM-DD`." }, "duration_minutes": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ], "description": "Turn duration; null on provider-managed bookings, where Maple never invents one." }, "party_size": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "guest": { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "E.164, when the guest left one." }, "phone_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["first_name", "last_name", "phone", "phone_last_four", "email"], "additionalProperties": false }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The guest-facing note; venue-internal notes are never exposed." }, "channel": { "type": "string", "description": "The channel the booking originated on, e.g. `api_partner`, `voice_ai`, `internal`." }, "provider": { "type": "string", "enum": ["maple", "opentable", "resy", "sevenrooms"] }, "cancellation_policy": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-4217." }, "policy_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "within_hours_before_start": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "basis": { "type": "string", "description": "`per_party` or `per_person`." }, "amount_cents": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "percent_bps": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ], "description": "Basis points of the party value, when the fee is a percentage." } }, "required": ["within_hours_before_start", "basis", "amount_cents", "percent_bps"], "additionalProperties": false } }, "deposit": { "anyOf": [ { "type": "object", "properties": { "amount_cents": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "currency": { "type": "string" }, "basis": { "type": "string" } }, "required": ["amount_cents", "currency", "basis"], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["type", "currency", "policy_text", "tiers", "deposit"], "additionalProperties": false }, { "type": "null" } ] }, "experience": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Null when Maple has not seen the name." } }, "required": ["id", "name"], "additionalProperties": false }, { "type": "null" } ], "description": "The experience booked (prix fixe, ticketed seating), or null for a standard reservation." }, "updated_at": { "type": "string", "description": "ISO-8601 UTC instant." } }, "required": [ "object", "id", "livemode", "created", "version", "location_id", "status", "service_state", "confirmation_code", "starts_at", "starts_at_local", "service_date", "duration_minutes", "party_size", "guest", "notes", "channel", "provider", "cancellation_policy", "experience", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "409": { "description": "DeveloperApiConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiConflict" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Moves a booking using a native reschedule quote (changing_booking_id), or an ordinary provider availability quote, and returns the updated booking. Provider writes claim the mirrored version before I/O; a competing or uncertain write answers 409 operation_in_progress. Retry the same key and body; completed replays bypass the old expected_version. Pass `expected_version` to refuse a change on a booking that moved on (409 `stale_version`). A booking the venue’s policy no longer lets the guest change answers 409 `not_changeable` with `details.reason`; a slot whose capacity is gone 409 `slot_unavailable`. Requires `bookings:write`.", "summary": "Change booking", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "slot_token": { "type": "string", "description": "A slot_token for the booking’s location: a reschedule search with changing_booking_id for native bookings, or an ordinary availability quote for provider-managed bookings." }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Replaces the guest’s note for native bookings. OpenTable note changes return 422 capability_unsupported." }, "expected_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Optimistic concurrency: the `version` you last read. A booking that moved on since answers 409 `stale_version` with `details.expected`/`actual`." }, "idempotency_key": { "type": "string", "allOf": [ { "minLength": 1 }, { "maxLength": 255, "description": "Your unique key for this write (body-level, scoped to your app). Retrying with the same key and the same request replays the same booking; the same key with a different request answers 409 `idempotency_key_reused`." } ] } }, "required": ["slot_token", "idempotency_key"], "additionalProperties": false } } }, "required": true } } }, "/locations/{locationId}/walk_ins": { "post": { "tags": ["Bookings"], "operationId": "developer-api-bookings.createWalkInBooking", "parameters": [ { "name": "locationId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["booking"] }, "id": { "type": "string", "description": "Opaque, prefixed `bkg_…`." }, "livemode": { "type": "boolean" }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "version": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "location_id": { "type": "string" }, "status": { "type": "string", "enum": [ "requested", "confirmed", "seated", "completed", "declined_by_venue", "cancelled_by_guest", "cancelled_by_venue", "cancelled_unattributed", "no_show" ] }, "service_state": { "anyOf": [ { "type": "string", "enum": ["expected", "arrived", "partially_seated", "fully_seated", "left"] }, { "type": "null" } ] }, "confirmation_code": { "type": "string" }, "starts_at": { "type": "string", "description": "ISO-8601 UTC instant." }, "starts_at_local": { "type": "string", "description": "Venue wall-clock, `YYYY-MM-DDTHH:MM`." }, "service_date": { "type": "string", "description": "The venue service day the booking belongs to, `YYYY-MM-DD`." }, "duration_minutes": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ], "description": "Turn duration; null on provider-managed bookings, where Maple never invents one." }, "party_size": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "guest": { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "E.164, when the guest left one." }, "phone_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["first_name", "last_name", "phone", "phone_last_four", "email"], "additionalProperties": false }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The guest-facing note; venue-internal notes are never exposed." }, "channel": { "type": "string", "description": "The channel the booking originated on, e.g. `api_partner`, `voice_ai`, `internal`." }, "provider": { "type": "string", "enum": ["maple", "opentable", "resy", "sevenrooms"] }, "cancellation_policy": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-4217." }, "policy_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "within_hours_before_start": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "basis": { "type": "string", "description": "`per_party` or `per_person`." }, "amount_cents": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "percent_bps": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ], "description": "Basis points of the party value, when the fee is a percentage." } }, "required": ["within_hours_before_start", "basis", "amount_cents", "percent_bps"], "additionalProperties": false } }, "deposit": { "anyOf": [ { "type": "object", "properties": { "amount_cents": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "currency": { "type": "string" }, "basis": { "type": "string" } }, "required": ["amount_cents", "currency", "basis"], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["type", "currency", "policy_text", "tiers", "deposit"], "additionalProperties": false }, { "type": "null" } ] }, "experience": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Null when Maple has not seen the name." } }, "required": ["id", "name"], "additionalProperties": false }, { "type": "null" } ], "description": "The experience booked (prix fixe, ticketed seating), or null for a standard reservation." }, "updated_at": { "type": "string", "description": "ISO-8601 UTC instant." } }, "required": [ "object", "id", "livemode", "created", "version", "location_id", "status", "service_state", "confirmation_code", "starts_at", "starts_at_local", "service_date", "duration_minutes", "party_size", "guest", "notes", "channel", "provider", "cancellation_policy", "experience", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "409": { "description": "DeveloperApiConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiConflict" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Seats a party that just arrived at the earliest table that fits it now, as the venue, and returns the `booking` (`status: seated`, `channel: walk_in`). Maple picks the table; there is no force-book. No table free now answers 409 `slot_unavailable` (its message names the next opening). Retry-safe under `idempotency_key`: a retry returns the same booking. Maple-native locations only (422 `capability_unsupported` otherwise). Requires `bookings:manage`.", "summary": "Seat a walk-in", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "party_size": { "type": "integer", "allOf": [ { "minimum": 1 } ] }, "guest": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "type": "string", "allOf": [ { "pattern": "^\\+?[\\d\\s().-]+$" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["first_name", "phone"], "additionalProperties": false }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The guest’s note to the venue." }, "idempotency_key": { "type": "string", "allOf": [ { "minLength": 1 }, { "maxLength": 255, "description": "Your unique key for this walk-in, scoped to your app across all its locations. Retrying with the same key and the same request returns the same booking, even though its table is now taken; the same key with a different request, including another location, answers 409 `idempotency_key_reused`." } ] } }, "required": ["party_size", "guest", "idempotency_key"], "additionalProperties": false } } }, "required": true } } }, "/bookings/{bookingId}/cancel": { "post": { "tags": ["Bookings"], "operationId": "developer-api-bookings.cancelBooking", "parameters": [ { "name": "bookingId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["booking"] }, "id": { "type": "string", "description": "Opaque, prefixed `bkg_…`." }, "livemode": { "type": "boolean" }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "version": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "location_id": { "type": "string" }, "status": { "type": "string", "enum": [ "requested", "confirmed", "seated", "completed", "declined_by_venue", "cancelled_by_guest", "cancelled_by_venue", "cancelled_unattributed", "no_show" ] }, "service_state": { "anyOf": [ { "type": "string", "enum": ["expected", "arrived", "partially_seated", "fully_seated", "left"] }, { "type": "null" } ] }, "confirmation_code": { "type": "string" }, "starts_at": { "type": "string", "description": "ISO-8601 UTC instant." }, "starts_at_local": { "type": "string", "description": "Venue wall-clock, `YYYY-MM-DDTHH:MM`." }, "service_date": { "type": "string", "description": "The venue service day the booking belongs to, `YYYY-MM-DD`." }, "duration_minutes": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ], "description": "Turn duration; null on provider-managed bookings, where Maple never invents one." }, "party_size": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "guest": { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "E.164, when the guest left one." }, "phone_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["first_name", "last_name", "phone", "phone_last_four", "email"], "additionalProperties": false }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The guest-facing note; venue-internal notes are never exposed." }, "channel": { "type": "string", "description": "The channel the booking originated on, e.g. `api_partner`, `voice_ai`, `internal`." }, "provider": { "type": "string", "enum": ["maple", "opentable", "resy", "sevenrooms"] }, "cancellation_policy": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-4217." }, "policy_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "within_hours_before_start": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "basis": { "type": "string", "description": "`per_party` or `per_person`." }, "amount_cents": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "percent_bps": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ], "description": "Basis points of the party value, when the fee is a percentage." } }, "required": ["within_hours_before_start", "basis", "amount_cents", "percent_bps"], "additionalProperties": false } }, "deposit": { "anyOf": [ { "type": "object", "properties": { "amount_cents": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "currency": { "type": "string" }, "basis": { "type": "string" } }, "required": ["amount_cents", "currency", "basis"], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["type", "currency", "policy_text", "tiers", "deposit"], "additionalProperties": false }, { "type": "null" } ] }, "experience": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Null when Maple has not seen the name." } }, "required": ["id", "name"], "additionalProperties": false }, { "type": "null" } ], "description": "The experience booked (prix fixe, ticketed seating), or null for a standard reservation." }, "updated_at": { "type": "string", "description": "ISO-8601 UTC instant." } }, "required": [ "object", "id", "livemode", "created", "version", "location_id", "status", "service_state", "confirmation_code", "starts_at", "starts_at_local", "service_date", "duration_minutes", "party_size", "guest", "notes", "channel", "provider", "cancellation_policy", "experience", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "409": { "description": "DeveloperApiConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiConflict" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Cancels a booking on the guest’s behalf, synchronously, and returns it as `cancelled_by_guest`; its capacity is offered again. Pass `expected_version` to refuse a cancel on a booking that moved on (409 `stale_version`). A booking the venue’s policy no longer lets the guest cancel answers 409 `not_cancellable` with `details.reason`. Requires `bookings:write`.", "summary": "Cancel booking", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "expected_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Optimistic concurrency: the `version` you last read. A booking that moved on since answers 409 `stale_version` with `details.expected`/`actual`." }, "idempotency_key": { "type": "string", "allOf": [ { "minLength": 1 }, { "maxLength": 255, "description": "Your unique key for this write (body-level, scoped to your app). Retrying with the same key and the same request replays the same booking; the same key with a different request answers 409 `idempotency_key_reused`." } ] } }, "required": ["idempotency_key"], "additionalProperties": false } } }, "required": true } } }, "/bookings/{bookingId}/venue_cancel": { "post": { "tags": ["Bookings"], "operationId": "developer-api-bookings.venueCancelBooking", "parameters": [ { "name": "bookingId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["booking"] }, "id": { "type": "string", "description": "Opaque, prefixed `bkg_…`." }, "livemode": { "type": "boolean" }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "version": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "location_id": { "type": "string" }, "status": { "type": "string", "enum": [ "requested", "confirmed", "seated", "completed", "declined_by_venue", "cancelled_by_guest", "cancelled_by_venue", "cancelled_unattributed", "no_show" ] }, "service_state": { "anyOf": [ { "type": "string", "enum": ["expected", "arrived", "partially_seated", "fully_seated", "left"] }, { "type": "null" } ] }, "confirmation_code": { "type": "string" }, "starts_at": { "type": "string", "description": "ISO-8601 UTC instant." }, "starts_at_local": { "type": "string", "description": "Venue wall-clock, `YYYY-MM-DDTHH:MM`." }, "service_date": { "type": "string", "description": "The venue service day the booking belongs to, `YYYY-MM-DD`." }, "duration_minutes": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ], "description": "Turn duration; null on provider-managed bookings, where Maple never invents one." }, "party_size": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "guest": { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "E.164, when the guest left one." }, "phone_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["first_name", "last_name", "phone", "phone_last_four", "email"], "additionalProperties": false }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The guest-facing note; venue-internal notes are never exposed." }, "channel": { "type": "string", "description": "The channel the booking originated on, e.g. `api_partner`, `voice_ai`, `internal`." }, "provider": { "type": "string", "enum": ["maple", "opentable", "resy", "sevenrooms"] }, "cancellation_policy": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-4217." }, "policy_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "within_hours_before_start": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "basis": { "type": "string", "description": "`per_party` or `per_person`." }, "amount_cents": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ] }, "percent_bps": { "anyOf": [ { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, { "type": "null" } ], "description": "Basis points of the party value, when the fee is a percentage." } }, "required": ["within_hours_before_start", "basis", "amount_cents", "percent_bps"], "additionalProperties": false } }, "deposit": { "anyOf": [ { "type": "object", "properties": { "amount_cents": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "currency": { "type": "string" }, "basis": { "type": "string" } }, "required": ["amount_cents", "currency", "basis"], "additionalProperties": false }, { "type": "null" } ] } }, "required": ["type", "currency", "policy_text", "tiers", "deposit"], "additionalProperties": false }, { "type": "null" } ] }, "experience": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Null when Maple has not seen the name." } }, "required": ["id", "name"], "additionalProperties": false }, { "type": "null" } ], "description": "The experience booked (prix fixe, ticketed seating), or null for a standard reservation." }, "updated_at": { "type": "string", "description": "ISO-8601 UTC instant." } }, "required": [ "object", "id", "livemode", "created", "version", "location_id", "status", "service_state", "confirmation_code", "starts_at", "starts_at_local", "service_date", "duration_minutes", "party_size", "guest", "notes", "channel", "provider", "cancellation_policy", "experience", "updated_at" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "409": { "description": "DeveloperApiConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiConflict" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Cancels a booking on the venue’s behalf, for host-stand and POS apps, and returns it as `cancelled_by_venue`; its capacity is offered again. The guest’s cancellation window does not apply. Pass `expected_version` to refuse a cancel on a booking that moved on (409 `stale_version`); a booking that is seated or finished answers 409 `not_cancellable`. Retry-safe under `idempotency_key`. Maple-native bookings only (422 `capability_unsupported` otherwise). Requires `bookings:manage`.", "summary": "Cancel booking as the venue", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "expected_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Optimistic concurrency: the `version` you last read. A booking that moved on since answers 409 `stale_version` with `details.expected`/`actual`." }, "idempotency_key": { "type": "string", "allOf": [ { "minLength": 1 }, { "maxLength": 255, "description": "Your unique key for this write (body-level, scoped to your app). Retrying with the same key and the same request replays the same booking; the same key with a different request answers 409 `idempotency_key_reused`." } ] } }, "required": ["idempotency_key"], "additionalProperties": false } } }, "required": true } } }, "/locations/{locationId}/waitlist": { "get": { "tags": ["Waitlist"], "operationId": "developer-api-waitlist.getWaitlist", "parameters": [ { "name": "locationId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["waitlist"] }, "location_id": { "type": "string" }, "livemode": { "type": "boolean" }, "open": { "type": "boolean", "description": "Whether remote parties may join. The venue can still add parties in person while it is closed." }, "entries": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": ["waitlist_entry"] }, "id": { "type": "string", "description": "Opaque, prefixed `bkw_…`." }, "livemode": { "type": "boolean" }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "location_id": { "type": "string" }, "status": { "type": "string", "enum": [ "waiting", "notified", "on_my_way", "seated", "removed_by_guest", "removed_by_venue", "expired_no_response" ] }, "party_size": { "type": "integer" }, "position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "1-based place in the queue while the entry is active; null once it is seated, removed, or expired." }, "quoted_wait": { "anyOf": [ { "type": "object", "properties": { "parties_ahead": { "type": "integer" }, "wait_minutes": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "required": ["min", "max"], "additionalProperties": false } }, "required": ["parties_ahead", "wait_minutes"], "additionalProperties": false }, { "type": "null" } ], "description": "The wait quoted when the party joined, refreshed when it is notified. Null when none could be quoted." }, "joined_at": { "type": "string", "description": "ISO-8601 UTC instant." }, "notified_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601 UTC instant the table-ready text was sent." }, "booking_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The walk-in booking created when the party was seated; read it with `GET /bookings/{bookingId}`." }, "channel": { "type": "string", "description": "The channel the party joined on, e.g. `api_partner`, `voice_ai`, `internal`." }, "guest": { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "E.164, when the guest left one." }, "phone_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["first_name", "last_name", "phone", "phone_last_four", "email"], "additionalProperties": false } }, "required": [ "object", "id", "livemode", "created", "location_id", "status", "party_size", "position", "quoted_wait", "joined_at", "notified_at", "booking_id", "channel", "guest" ], "additionalProperties": false }, "description": "The active queue, first in line first." } }, "required": ["object", "location_id", "livemode", "open", "entries"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "The active queue at a granted location, first in line first, and whether remote parties may join. Requires bookings:read. Maple-native locations only; other providers answer 422 capability_unsupported.", "summary": "Get waitlist" } }, "/locations/{locationId}/waitlist_estimate": { "get": { "tags": ["Waitlist"], "operationId": "developer-api-waitlist.getWaitlistEstimate", "parameters": [ { "name": "locationId", "in": "path", "schema": { "type": "string" }, "required": true }, { "name": "party_size", "in": "query", "schema": { "type": "string", "allOf": [ { "pattern": "^[+-]?\\d*\\.?\\d+(?:[Ee][+-]?\\d+)?$" } ] }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["waitlist_estimate"] }, "location_id": { "type": "string" }, "livemode": { "type": "boolean" }, "party_size": { "type": "integer" }, "parties_ahead": { "type": "integer" }, "wait_minutes": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "required": ["min", "max"], "additionalProperties": false } }, "required": ["object", "location_id", "livemode", "party_size", "parties_ahead", "wait_minutes"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "The wait a new party of `party_size` would be quoted now: the parties ahead that compete for the same tables and a minutes band, never a single number. Parties above 50 answer 422 party_size_out_of_bounds. Requires bookings:read.", "summary": "Estimate the wait" } }, "/locations/{locationId}/waitlist/open": { "post": { "tags": ["Waitlist"], "operationId": "developer-api-waitlist.openWaitlist", "parameters": [ { "name": "locationId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["waitlist"] }, "location_id": { "type": "string" }, "livemode": { "type": "boolean" }, "open": { "type": "boolean", "description": "Whether remote parties may join. The venue can still add parties in person while it is closed." }, "entries": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": ["waitlist_entry"] }, "id": { "type": "string", "description": "Opaque, prefixed `bkw_…`." }, "livemode": { "type": "boolean" }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "location_id": { "type": "string" }, "status": { "type": "string", "enum": [ "waiting", "notified", "on_my_way", "seated", "removed_by_guest", "removed_by_venue", "expired_no_response" ] }, "party_size": { "type": "integer" }, "position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "1-based place in the queue while the entry is active; null once it is seated, removed, or expired." }, "quoted_wait": { "anyOf": [ { "type": "object", "properties": { "parties_ahead": { "type": "integer" }, "wait_minutes": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "required": ["min", "max"], "additionalProperties": false } }, "required": ["parties_ahead", "wait_minutes"], "additionalProperties": false }, { "type": "null" } ], "description": "The wait quoted when the party joined, refreshed when it is notified. Null when none could be quoted." }, "joined_at": { "type": "string", "description": "ISO-8601 UTC instant." }, "notified_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601 UTC instant the table-ready text was sent." }, "booking_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The walk-in booking created when the party was seated; read it with `GET /bookings/{bookingId}`." }, "channel": { "type": "string", "description": "The channel the party joined on, e.g. `api_partner`, `voice_ai`, `internal`." }, "guest": { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "E.164, when the guest left one." }, "phone_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["first_name", "last_name", "phone", "phone_last_four", "email"], "additionalProperties": false } }, "required": [ "object", "id", "livemode", "created", "location_id", "status", "party_size", "position", "quoted_wait", "joined_at", "notified_at", "booking_id", "channel", "guest" ], "additionalProperties": false }, "description": "The active queue, first in line first." } }, "required": ["object", "location_id", "livemode", "open", "entries"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Lets remote parties join. Idempotent. Returns the waitlist. Requires bookings:manage.", "summary": "Open the waitlist" } }, "/locations/{locationId}/waitlist/close": { "post": { "tags": ["Waitlist"], "operationId": "developer-api-waitlist.closeWaitlist", "parameters": [ { "name": "locationId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["waitlist"] }, "location_id": { "type": "string" }, "livemode": { "type": "boolean" }, "open": { "type": "boolean", "description": "Whether remote parties may join. The venue can still add parties in person while it is closed." }, "entries": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "enum": ["waitlist_entry"] }, "id": { "type": "string", "description": "Opaque, prefixed `bkw_…`." }, "livemode": { "type": "boolean" }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "location_id": { "type": "string" }, "status": { "type": "string", "enum": [ "waiting", "notified", "on_my_way", "seated", "removed_by_guest", "removed_by_venue", "expired_no_response" ] }, "party_size": { "type": "integer" }, "position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "1-based place in the queue while the entry is active; null once it is seated, removed, or expired." }, "quoted_wait": { "anyOf": [ { "type": "object", "properties": { "parties_ahead": { "type": "integer" }, "wait_minutes": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "required": ["min", "max"], "additionalProperties": false } }, "required": ["parties_ahead", "wait_minutes"], "additionalProperties": false }, { "type": "null" } ], "description": "The wait quoted when the party joined, refreshed when it is notified. Null when none could be quoted." }, "joined_at": { "type": "string", "description": "ISO-8601 UTC instant." }, "notified_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601 UTC instant the table-ready text was sent." }, "booking_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The walk-in booking created when the party was seated; read it with `GET /bookings/{bookingId}`." }, "channel": { "type": "string", "description": "The channel the party joined on, e.g. `api_partner`, `voice_ai`, `internal`." }, "guest": { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "E.164, when the guest left one." }, "phone_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["first_name", "last_name", "phone", "phone_last_four", "email"], "additionalProperties": false } }, "required": [ "object", "id", "livemode", "created", "location_id", "status", "party_size", "position", "quoted_wait", "joined_at", "notified_at", "booking_id", "channel", "guest" ], "additionalProperties": false }, "description": "The active queue, first in line first." } }, "required": ["object", "location_id", "livemode", "open", "entries"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Stops remote parties from joining; parties already waiting stay in line. Idempotent. Returns the waitlist. Requires bookings:manage.", "summary": "Close the waitlist" } }, "/waitlist_entries": { "post": { "tags": ["Waitlist"], "operationId": "developer-api-waitlist.createWaitlistEntry", "parameters": [], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["waitlist_entry"] }, "id": { "type": "string", "description": "Opaque, prefixed `bkw_…`." }, "livemode": { "type": "boolean" }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "location_id": { "type": "string" }, "status": { "type": "string", "enum": [ "waiting", "notified", "on_my_way", "seated", "removed_by_guest", "removed_by_venue", "expired_no_response" ] }, "party_size": { "type": "integer" }, "position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "1-based place in the queue while the entry is active; null once it is seated, removed, or expired." }, "quoted_wait": { "anyOf": [ { "type": "object", "properties": { "parties_ahead": { "type": "integer" }, "wait_minutes": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "required": ["min", "max"], "additionalProperties": false } }, "required": ["parties_ahead", "wait_minutes"], "additionalProperties": false }, { "type": "null" } ], "description": "The wait quoted when the party joined, refreshed when it is notified. Null when none could be quoted." }, "joined_at": { "type": "string", "description": "ISO-8601 UTC instant." }, "notified_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601 UTC instant the table-ready text was sent." }, "booking_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The walk-in booking created when the party was seated; read it with `GET /bookings/{bookingId}`." }, "channel": { "type": "string", "description": "The channel the party joined on, e.g. `api_partner`, `voice_ai`, `internal`." }, "guest": { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "E.164, when the guest left one." }, "phone_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["first_name", "last_name", "phone", "phone_last_four", "email"], "additionalProperties": false } }, "required": [ "object", "id", "livemode", "created", "location_id", "status", "party_size", "position", "quoted_wait", "joined_at", "notified_at", "booking_id", "channel", "guest" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "409": { "description": "DeveloperApiConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiConflict" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Adds a party to the end of the queue and returns its entry with its position and quoted wait. A closed waitlist answers 409 waitlist_closed; a phone Maple cannot text, such as one with an extension, answers 400. Requires bookings:write.", "summary": "Add a party to the waitlist", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "location_id": { "type": "string", "description": "A granted location." }, "party_size": { "type": "integer", "allOf": [ { "minimum": 1 } ] }, "guest": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "type": "string", "allOf": [ { "pattern": "^\\+?[\\d\\s().-]+$" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["first_name", "phone"], "additionalProperties": false }, "idempotency_key": { "type": "string", "allOf": [ { "minLength": 1 }, { "maxLength": 255, "description": "Your unique key for this join, scoped to your app across all its locations. Retrying with the same key and the same request returns the same entry; the same key with a different request, including another location, answers 409 `idempotency_key_reused`." } ] } }, "required": ["location_id", "party_size", "guest", "idempotency_key"], "additionalProperties": false } } }, "required": true } } }, "/waitlist_entries/{entryId}": { "get": { "tags": ["Waitlist"], "operationId": "developer-api-waitlist.getWaitlistEntry", "parameters": [ { "name": "entryId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["waitlist_entry"] }, "id": { "type": "string", "description": "Opaque, prefixed `bkw_…`." }, "livemode": { "type": "boolean" }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "location_id": { "type": "string" }, "status": { "type": "string", "enum": [ "waiting", "notified", "on_my_way", "seated", "removed_by_guest", "removed_by_venue", "expired_no_response" ] }, "party_size": { "type": "integer" }, "position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "1-based place in the queue while the entry is active; null once it is seated, removed, or expired." }, "quoted_wait": { "anyOf": [ { "type": "object", "properties": { "parties_ahead": { "type": "integer" }, "wait_minutes": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "required": ["min", "max"], "additionalProperties": false } }, "required": ["parties_ahead", "wait_minutes"], "additionalProperties": false }, { "type": "null" } ], "description": "The wait quoted when the party joined, refreshed when it is notified. Null when none could be quoted." }, "joined_at": { "type": "string", "description": "ISO-8601 UTC instant." }, "notified_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601 UTC instant the table-ready text was sent." }, "booking_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The walk-in booking created when the party was seated; read it with `GET /bookings/{bookingId}`." }, "channel": { "type": "string", "description": "The channel the party joined on, e.g. `api_partner`, `voice_ai`, `internal`." }, "guest": { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "E.164, when the guest left one." }, "phone_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["first_name", "last_name", "phone", "phone_last_four", "email"], "additionalProperties": false } }, "required": [ "object", "id", "livemode", "created", "location_id", "status", "party_size", "position", "quoted_wait", "joined_at", "notified_at", "booking_id", "channel", "guest" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiBadRequest" } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "One entry in any status, if it belongs to a granted location. Requires bookings:read.", "summary": "Get waitlist entry" } }, "/waitlist_entries/{entryId}/cancel": { "post": { "tags": ["Waitlist"], "operationId": "developer-api-waitlist.cancelWaitlistEntry", "parameters": [ { "name": "entryId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["waitlist_entry"] }, "id": { "type": "string", "description": "Opaque, prefixed `bkw_…`." }, "livemode": { "type": "boolean" }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "location_id": { "type": "string" }, "status": { "type": "string", "enum": [ "waiting", "notified", "on_my_way", "seated", "removed_by_guest", "removed_by_venue", "expired_no_response" ] }, "party_size": { "type": "integer" }, "position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "1-based place in the queue while the entry is active; null once it is seated, removed, or expired." }, "quoted_wait": { "anyOf": [ { "type": "object", "properties": { "parties_ahead": { "type": "integer" }, "wait_minutes": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "required": ["min", "max"], "additionalProperties": false } }, "required": ["parties_ahead", "wait_minutes"], "additionalProperties": false }, { "type": "null" } ], "description": "The wait quoted when the party joined, refreshed when it is notified. Null when none could be quoted." }, "joined_at": { "type": "string", "description": "ISO-8601 UTC instant." }, "notified_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601 UTC instant the table-ready text was sent." }, "booking_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The walk-in booking created when the party was seated; read it with `GET /bookings/{bookingId}`." }, "channel": { "type": "string", "description": "The channel the party joined on, e.g. `api_partner`, `voice_ai`, `internal`." }, "guest": { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "E.164, when the guest left one." }, "phone_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["first_name", "last_name", "phone", "phone_last_four", "email"], "additionalProperties": false } }, "required": [ "object", "id", "livemode", "created", "location_id", "status", "party_size", "position", "quoted_wait", "joined_at", "notified_at", "booking_id", "channel", "guest" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "409": { "description": "DeveloperApiConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiConflict" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Takes the party out of line on the guest’s behalf and returns the entry as `removed_by_guest`. An entry that already left the queue is returned unchanged. Requires bookings:write.", "summary": "Cancel waitlist entry" } }, "/waitlist_entries/{entryId}/notify": { "post": { "tags": ["Waitlist"], "operationId": "developer-api-waitlist.notifyWaitlistEntry", "parameters": [ { "name": "entryId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["waitlist_entry"] }, "id": { "type": "string", "description": "Opaque, prefixed `bkw_…`." }, "livemode": { "type": "boolean" }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "location_id": { "type": "string" }, "status": { "type": "string", "enum": [ "waiting", "notified", "on_my_way", "seated", "removed_by_guest", "removed_by_venue", "expired_no_response" ] }, "party_size": { "type": "integer" }, "position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "1-based place in the queue while the entry is active; null once it is seated, removed, or expired." }, "quoted_wait": { "anyOf": [ { "type": "object", "properties": { "parties_ahead": { "type": "integer" }, "wait_minutes": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "required": ["min", "max"], "additionalProperties": false } }, "required": ["parties_ahead", "wait_minutes"], "additionalProperties": false }, { "type": "null" } ], "description": "The wait quoted when the party joined, refreshed when it is notified. Null when none could be quoted." }, "joined_at": { "type": "string", "description": "ISO-8601 UTC instant." }, "notified_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601 UTC instant the table-ready text was sent." }, "booking_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The walk-in booking created when the party was seated; read it with `GET /bookings/{bookingId}`." }, "channel": { "type": "string", "description": "The channel the party joined on, e.g. `api_partner`, `voice_ai`, `internal`." }, "guest": { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "E.164, when the guest left one." }, "phone_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["first_name", "last_name", "phone", "phone_last_four", "email"], "additionalProperties": false } }, "required": [ "object", "id", "livemode", "created", "location_id", "status", "party_size", "position", "quoted_wait", "joined_at", "notified_at", "booking_id", "channel", "guest" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "409": { "description": "DeveloperApiConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiConflict" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Tells a waiting party their table is ready: Maple texts the guest and the entry becomes `notified`. If the guest does not respond within the venue’s response window, the entry expires as `expired_no_response`. An entry that is no longer waiting is returned unchanged. A location where Maple is not texting guests (not rolled out yet, or the location turned guest texts off) answers 422 guest_messaging_unavailable. Requires bookings:manage.", "summary": "Notify waitlist entry" } }, "/waitlist_entries/{entryId}/seat": { "post": { "tags": ["Waitlist"], "operationId": "developer-api-waitlist.seatWaitlistEntry", "parameters": [ { "name": "entryId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["waitlist_entry"] }, "id": { "type": "string", "description": "Opaque, prefixed `bkw_…`." }, "livemode": { "type": "boolean" }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "location_id": { "type": "string" }, "status": { "type": "string", "enum": [ "waiting", "notified", "on_my_way", "seated", "removed_by_guest", "removed_by_venue", "expired_no_response" ] }, "party_size": { "type": "integer" }, "position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "1-based place in the queue while the entry is active; null once it is seated, removed, or expired." }, "quoted_wait": { "anyOf": [ { "type": "object", "properties": { "parties_ahead": { "type": "integer" }, "wait_minutes": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "required": ["min", "max"], "additionalProperties": false } }, "required": ["parties_ahead", "wait_minutes"], "additionalProperties": false }, { "type": "null" } ], "description": "The wait quoted when the party joined, refreshed when it is notified. Null when none could be quoted." }, "joined_at": { "type": "string", "description": "ISO-8601 UTC instant." }, "notified_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601 UTC instant the table-ready text was sent." }, "booking_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The walk-in booking created when the party was seated; read it with `GET /bookings/{bookingId}`." }, "channel": { "type": "string", "description": "The channel the party joined on, e.g. `api_partner`, `voice_ai`, `internal`." }, "guest": { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "E.164, when the guest left one." }, "phone_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["first_name", "last_name", "phone", "phone_last_four", "email"], "additionalProperties": false } }, "required": [ "object", "id", "livemode", "created", "location_id", "status", "party_size", "position", "quoted_wait", "joined_at", "notified_at", "booking_id", "channel", "guest" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "409": { "description": "DeveloperApiConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiConflict" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Seats an active party at the earliest table that fits it right now and returns the entry as `seated` with the created walk-in `booking_id`. No table free now answers 409 slot_unavailable; an entry that already left the queue answers 409 illegal_transition. Requires bookings:manage.", "summary": "Seat waitlist entry" } }, "/waitlist_entries/{entryId}/remove": { "post": { "tags": ["Waitlist"], "operationId": "developer-api-waitlist.removeWaitlistEntry", "parameters": [ { "name": "entryId", "in": "path", "schema": { "type": "string" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["waitlist_entry"] }, "id": { "type": "string", "description": "Opaque, prefixed `bkw_…`." }, "livemode": { "type": "boolean" }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "location_id": { "type": "string" }, "status": { "type": "string", "enum": [ "waiting", "notified", "on_my_way", "seated", "removed_by_guest", "removed_by_venue", "expired_no_response" ] }, "party_size": { "type": "integer" }, "position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "1-based place in the queue while the entry is active; null once it is seated, removed, or expired." }, "quoted_wait": { "anyOf": [ { "type": "object", "properties": { "parties_ahead": { "type": "integer" }, "wait_minutes": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" } }, "required": ["min", "max"], "additionalProperties": false } }, "required": ["parties_ahead", "wait_minutes"], "additionalProperties": false }, { "type": "null" } ], "description": "The wait quoted when the party joined, refreshed when it is notified. Null when none could be quoted." }, "joined_at": { "type": "string", "description": "ISO-8601 UTC instant." }, "notified_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601 UTC instant the table-ready text was sent." }, "booking_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The walk-in booking created when the party was seated; read it with `GET /bookings/{bookingId}`." }, "channel": { "type": "string", "description": "The channel the party joined on, e.g. `api_partner`, `voice_ai`, `internal`." }, "guest": { "type": "object", "properties": { "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "E.164, when the guest left one." }, "phone_last_four": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["first_name", "last_name", "phone", "phone_last_four", "email"], "additionalProperties": false } }, "required": [ "object", "id", "livemode", "created", "location_id", "status", "party_size", "position", "quoted_wait", "joined_at", "notified_at", "booking_id", "channel", "guest" ], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "403": { "description": "DeveloperApiForbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiForbidden" } } } }, "404": { "description": "DeveloperApiNotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiNotFound" } } } }, "409": { "description": "DeveloperApiConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiConflict" } } } }, "422": { "description": "DeveloperApiUnprocessable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnprocessable" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiRateLimited" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Takes the party out of line on the venue’s behalf and returns the entry as `removed_by_venue`. An entry that already left the queue is returned unchanged. Requires bookings:manage.", "summary": "Remove waitlist entry" } }, "/feedback": { "post": { "tags": ["Feedback"], "operationId": "developer-api-feedback.createFeedback", "parameters": [], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": ["feedback"] }, "id": { "type": "string" }, "livemode": { "type": "boolean" }, "created": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "kind": { "type": "string", "enum": ["bug", "missing_capability", "docs_wrong", "unclear_error", "other"] }, "summary": { "type": "string" }, "request_ids": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": ["received"] } }, "required": ["object", "id", "livemode", "created", "kind", "summary", "request_ids", "status"], "additionalProperties": false } } } }, "400": { "description": "DeveloperApiBadRequest", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiBadRequest" }, { "$ref": "#/components/schemas/DeveloperApiBadRequest" } ] } } } }, "401": { "description": "DeveloperApiUnauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperApiUnauthorized" } } } }, "429": { "description": "DeveloperApiRateLimited", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DeveloperApiRateLimited1" }, { "$ref": "#/components/schemas/DeveloperApiRateLimited" } ] } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying; also returned as retry_after in the body.", "schema": { "type": "integer", "minimum": 1 } } } } }, "description": "Tells Maple about a bug, a missing capability, wrong docs, or an error you could not act on. Cite the `request_ids` involved so we can see what you sent. Maple copies its request history for ids it recognizes and keeps any other id as given, so a report is never refused over an id. Any credential may send feedback; no scope is required. Each app may send 20 per environment per hour; beyond that the API answers 429 with `Retry-After`. Maple reads feedback every week. Nothing changes automatically when you send it, and you get no reply through the API. This contract will not break: fields and `kind` values may be added, never removed, renamed, or made required.", "summary": "Send feedback", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": ["bug", "missing_capability", "docs_wrong", "unclear_error", "other"], "description": "`bug`: the API did something wrong. `missing_capability`: you needed something the API cannot do. `docs_wrong`: the docs or reference disagree with the API. `unclear_error`: an error did not tell you what to change. `other`: anything else." }, "summary": { "type": "string", "allOf": [ { "pattern": "^\\S[\\s\\S]*\\S$|^\\S$|^$" }, { "minLength": 1 }, { "maxLength": 200 }, { "pattern": "^[^\\u0000]*$" }, { "pattern": "^[^\\u0000-\\u001F\\u007F-\\u009F\\u2028\\u2029]*$", "description": "One line, at most 200 characters." } ] }, "attempted": { "anyOf": [ { "type": "string", "allOf": [ { "pattern": "^\\S[\\s\\S]*\\S$|^\\S$|^$" }, { "minLength": 1 }, { "maxLength": 4000 }, { "pattern": "^[^\\u0000]*$" } ] }, { "type": "null" } ], "description": "What you were trying to do, as a goal (for example, \"seat a walk-in party of four\"). Leave it out when the feedback is not about a task." }, "expected": { "anyOf": [ { "type": "string", "allOf": [ { "pattern": "^\\S[\\s\\S]*\\S$|^\\S$|^$" }, { "minLength": 1 }, { "maxLength": 4000 }, { "pattern": "^[^\\u0000]*$" } ] }, { "type": "null" } ], "description": "What you expected the API to do." }, "observed": { "anyOf": [ { "type": "string", "allOf": [ { "pattern": "^\\S[\\s\\S]*\\S$|^\\S$|^$" }, { "minLength": 1 }, { "maxLength": 4000 }, { "pattern": "^[^\\u0000]*$" } ] }, { "type": "null" } ], "description": "What the API did instead." }, "endpoint": { "anyOf": [ { "type": "string", "allOf": [ { "pattern": "^\\S[\\s\\S]*\\S$|^\\S$|^$" }, { "minLength": 1 }, { "maxLength": 200 }, { "pattern": "^[^\\u0000]*$" } ] }, { "type": "null" } ], "description": "The method and path this is about, for example `POST /v1/waitlist_entries`." }, "request_ids": { "anyOf": [ { "type": "array", "items": { "type": "string", "allOf": [ { "pattern": "^\\S[\\s\\S]*\\S$|^\\S$|^$" }, { "minLength": 1 }, { "maxLength": 200 }, { "pattern": "^[^\\u0000]*$" } ] }, "allOf": [ { "maxItems": 10 } ] }, { "type": "null" } ], "description": "Up to ten ids of the requests this is about, usually the `x-request-id` response header. Maple copies what its request history holds for ids this app made in this environment in the last seven days; any other id is kept as you sent it." } }, "required": ["kind", "summary"], "additionalProperties": false } } }, "required": true } } } }, "components": { "schemas": { "DeveloperApiBadRequest": { "type": "object", "properties": { "_tag": { "type": "string", "enum": ["DeveloperApiBadRequest"] }, "code": { "type": "string" }, "message": { "type": "string" }, "feedback": { "type": "string", "description": "Where to report this error if it does not tell you what to change." } }, "required": ["_tag", "message", "feedback"], "additionalProperties": false }, "DeveloperApiUnauthorized": { "type": "object", "properties": { "_tag": { "type": "string", "enum": ["DeveloperApiUnauthorized"] }, "message": { "type": "string" }, "feedback": { "type": "string", "description": "Where to report this error if it does not tell you what to change." } }, "required": ["_tag", "message", "feedback"], "additionalProperties": false }, "DeveloperApiRateLimited": { "type": "object", "properties": { "_tag": { "type": "string", "enum": ["DeveloperApiRateLimited"] }, "message": { "type": "string" }, "retry_after": { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, "feedback": { "type": "string", "description": "Where to report this error if it does not tell you what to change." } }, "required": ["_tag", "message", "retry_after", "feedback"], "additionalProperties": false }, "DeveloperApiForbidden": { "type": "object", "properties": { "_tag": { "type": "string", "enum": ["DeveloperApiForbidden"] }, "code": { "type": "string", "enum": ["insufficient_scope", "wrong_environment"] }, "message": { "type": "string" }, "feedback": { "type": "string", "description": "Where to report this error if it does not tell you what to change." } }, "required": ["_tag", "code", "message", "feedback"], "additionalProperties": false }, "DeveloperApiNotFound": { "type": "object", "properties": { "_tag": { "type": "string", "enum": ["DeveloperApiNotFound"] }, "message": { "type": "string" }, "feedback": { "type": "string", "description": "Where to report this error if it does not tell you what to change." } }, "required": ["_tag", "message", "feedback"], "additionalProperties": false }, "DeveloperApiConflict": { "type": "object", "properties": { "_tag": { "type": "string", "enum": ["DeveloperApiConflict"] }, "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" }, "feedback": { "type": "string", "description": "Where to report this error if it does not tell you what to change." } }, "required": ["_tag", "message", "feedback"], "additionalProperties": false }, "Suspend_": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "inputType": { "type": "string", "enum": ["options", "text"] }, "minSelections": { "type": "integer" }, "maxSelections": { "type": "integer" }, "minUniqueSelections": { "type": "integer" }, "maxUniqueSelections": { "type": "integer" }, "freeSelectionCount": { "type": "integer" }, "chargeKeptDefaults": { "type": "boolean" }, "allowedQuantities": { "type": "array", "items": { "type": "integer" } }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "object", "properties": { "amount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "priceType": { "type": "string", "enum": ["fixed", "variable", "per_unit", "bulk"] }, "taxInclusive": { "type": "boolean" }, "currencyPrices": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "taxInclusive": { "type": "boolean" } }, "required": ["amount"], "additionalProperties": false } }, "openBounds": { "type": "object", "properties": { "min": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "max": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false }, "presets": { "type": "array", "items": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false } } }, "additionalProperties": false }, "bulkTiers": { "type": "array", "items": { "type": "object", "properties": { "minQuantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false } }, "required": ["minQuantity", "unitPrice"], "additionalProperties": false } }, "measurementUnit": { "type": "object", "properties": { "unit": { "type": "string" }, "precision": { "type": "integer" } }, "required": ["unit"], "additionalProperties": false }, "compareAtAmount": { "type": "object", "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" } }, "required": ["amountMinor", "currency"], "additionalProperties": false } }, "additionalProperties": false }, "defaultQuantity": { "type": "integer" }, "minQuantity": { "type": "integer" }, "maxQuantity": { "type": "integer" }, "taxCategoryId": { "type": "string" }, "taxRateIds": { "type": "array", "items": { "type": "string" } }, "dietaryLabels": { "type": "array", "items": { "type": "string" } }, "allergens": { "type": "array", "items": { "type": "string" } }, "stockStatus": { "type": "string", "enum": ["in_stock", "out_of_stock", "low_stock"] }, "modifierGroups": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "groupId": { "type": "string" }, "minSelections": { "type": "integer" }, "maxSelections": { "type": "integer" }, "minUniqueSelections": { "type": "integer" }, "maxUniqueSelections": { "type": "integer" }, "freeSelectionCount": { "type": "integer" }, "chargeKeptDefaults": { "type": "boolean" }, "allowedQuantities": { "type": "array", "items": { "type": "integer" } }, "optionDefaults": { "type": "array", "items": { "type": "object", "properties": { "optionId": { "type": "string" }, "defaultQuantity": { "type": "integer" } }, "required": ["optionId", "defaultQuantity"], "additionalProperties": false } }, "externalId": { "not": {} }, "name": { "not": {} }, "options": { "not": {} } }, "required": ["groupId"], "additionalProperties": false }, { "$ref": "#/components/schemas/Suspend_" } ] } } }, "required": ["externalId", "name"], "additionalProperties": false } }, "textMaxLength": { "type": "integer" }, "groupId": { "not": {} } }, "required": ["externalId", "name", "minSelections", "maxSelections"], "additionalProperties": false }, "DeveloperApiInternalError": { "type": "object", "properties": { "_tag": { "type": "string", "enum": ["DeveloperApiInternalError"] }, "message": { "type": "string" }, "feedback": { "type": "string", "description": "Where to report this error if it does not tell you what to change." } }, "required": ["_tag", "message", "feedback"], "additionalProperties": false }, "DeveloperApiUnprocessable": { "type": "object", "properties": { "_tag": { "type": "string", "enum": ["DeveloperApiUnprocessable"] }, "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" }, "feedback": { "type": "string", "description": "Where to report this error if it does not tell you what to change." } }, "required": ["_tag", "code", "message", "feedback"], "additionalProperties": false }, "DeveloperApiRateLimited1": { "type": "object", "properties": { "_tag": { "type": "string", "enum": ["DeveloperApiRateLimited"] }, "message": { "type": "string" }, "retry_after": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": ["NaN"] }, { "type": "string", "enum": ["Infinity"] }, { "type": "string", "enum": ["-Infinity"] } ] }, { "type": "string", "enum": ["Infinity", "-Infinity", "NaN"] } ] }, "feedback": { "type": "string", "description": "Where to report this error if it does not tell you what to change." } }, "required": ["_tag", "message", "retry_after", "feedback"], "additionalProperties": false } }, "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "API key — `mpk_test_…` for the sandbox, `mpk_live_…` for production. Issued by Maple during partner onboarding." } } }, "security": [], "tags": [ { "name": "General", "description": "Service status and credential introspection." }, { "name": "Locations", "description": "The restaurant locations your app has been granted access to." }, { "name": "Connections", "description": "Become (or stop being) a granted location’s order receiver." }, { "name": "Menu", "description": "Publish and read a connected location’s menu." }, { "name": "Delivery zones", "description": "Manage a connected location’s delivery zones and check whether a coordinate is deliverable." }, { "name": "Orders", "description": "The order loop: read orders, submit validation results, and decide orders." }, { "name": "Bookings", "description": "Bookings (rolling out per location): a location’s booking profile, availability, holds, bookings, walk-ins, venue verbs, configuration, and live floor." }, { "name": "Waitlist", "description": "A Maple-native location’s walk-up waitlist: the queue and wait estimate, joining, and venue actions." }, { "name": "Webhooks", "description": "Event-type catalog, subscriptions, the event ledger, and replay." }, { "name": "Feedback", "description": "Tell Maple about a bug, a missing capability, wrong docs, or an error you could not act on." } ], "servers": [ { "url": "https://api.maple.inc/v1", "description": "Production" }, { "url": "https://api.staging.maple.inc/v1", "description": "Sandbox (development and testing)" } ] }