Bookings

Decline booking

Acts on behalf of the venue at a granted location.

Esta página aún no está disponible en tu idioma.

POSThttps://api.maple.inc/v1/bookings/{bookingId}/declineAPI key

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.

Authorization

Send your API key as Authorization: Bearer <key>: mpk_test_… against the sandbox (https://api.staging.maple.inc/v1), mpk_live_… against production. See Authentication. The samples read the key from MAPLE_KEY and the base URL from MAPLE_BASE, as set up in the Quickstart.

Parameters

bookingId string path required

Request body

application/json, required.

expected_version integer or null

Optimistic concurrency: the version you last read. A booking that moved on since answers 409 stale_version with details.expected/actual.

Responses

200 OK

object string required

Always booking.
id string required

Opaque, prefixed bkg_….
livemode boolean required
created number required
version number required
location_id string required
status string required

One of requested, confirmed, seated, completed, declined_by_venue, cancelled_by_guest, cancelled_by_venue, cancelled_unattributed, no_show.
service_state string or null required
confirmation_code string required
starts_at string required

ISO-8601 UTC instant.
starts_at_local string required

Venue wall-clock, YYYY-MM-DDTHH:MM.
service_date string required

The venue service day the booking belongs to, YYYY-MM-DD.
duration_minutes number or null required

Turn duration; null on provider-managed bookings, where Maple never invents one.
party_size number required
guest object required
guest.first_name string or null required
guest.last_name string or null required
guest.phone string or null required

E.164, when the guest left one.
guest.phone_last_four string or null required
guest.email string or null required
notes string or null required

The guest-facing note; venue-internal notes are never exposed.
channel string required

The channel the booking originated on, e.g. api_partner, voice_ai, internal.
provider string required

One of maple, opentable, resy, sevenrooms.
cancellation_policy object or null required
cancellation_policy.type string required
cancellation_policy.currency string or null required

ISO-4217.
cancellation_policy.policy_text string or null required
cancellation_policy.tiers object[] required
cancellation_policy.tiers[].within_hours_before_start number required
cancellation_policy.tiers[].basis string required

per_party or per_person.
cancellation_policy.tiers[].amount_cents number or null required
cancellation_policy.tiers[].percent_bps number or null required

Basis points of the party value, when the fee is a percentage.
cancellation_policy.deposit object or null required
cancellation_policy.deposit.amount_cents number required
cancellation_policy.deposit.currency string required
cancellation_policy.deposit.basis string required
experience object or null required

The experience booked (prix fixe, ticketed seating), or null for a standard reservation.
experience.id string required
experience.name string or null required

Null when Maple has not seen the name.
updated_at string required

ISO-8601 UTC instant.

Errors

400 Bad request DeveloperApiBadRequest
401 Unauthorized DeveloperApiUnauthorized
403 Forbidden DeveloperApiForbidden
404 Not found DeveloperApiNotFound
409 Conflict DeveloperApiConflict
422 Unprocessable DeveloperApiUnprocessable
429 Too many requests DeveloperApiRateLimited

Every error body names the error in _tag, explains it in message, and says where to report it in feedback. See Errors.

A 429 also sends Retry-After: Seconds to wait before retrying; also returned as retry_after in the body.

Decline booking

curl "$MAPLE_BASE/bookings/bkg_123/decline" \
  -H "Authorization: Bearer $MAPLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expected_version":1}'

import os
import requests

r = requests.post(
    f"{os.environ['MAPLE_BASE']}/bookings/bkg_123/decline",
    headers={"Authorization": f"Bearer {os.environ['MAPLE_KEY']}"},
    json={
        "expected_version": 1,
    },
    timeout=30,
)
r.raise_for_status()
print(r.json())

const res = await fetch(`${process.env.MAPLE_BASE}/bookings/bkg_123/decline`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAPLE_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "expected_version": 1
  }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
console.log(await res.json());

{
  "object": "booking",
  "id": "string",
  "livemode": true,
  "created": 1.5,
  "version": 1.5,
  "location_id": "str_123",
  "status": "requested",
  "service_state": "expected",
  "confirmation_code": "string",
  "starts_at": "string",
  "starts_at_local": "2026-11-20T18:00",
  "service_date": "string",
  "duration_minutes": 1.5,
  "party_size": 1.5,
  "guest": {
    "first_name": "Ada",
    "last_name": "Lovelace",
    "phone": "+15555550123",
    "phone_last_four": "string",
    "email": "guest@example.com"
  },
  "notes": "string",
  "channel": "string",
  "provider": "maple",
  "cancellation_policy": {
    "type": "string",
    "currency": "USD",
    "policy_text": "string",
    "tiers": [
      {
        "within_hours_before_start": 1.5,
        "basis": "string",
        "amount_cents": 1.5,
        "percent_bps": 1.5
      }
    ],
    "deposit": {
      "amount_cents": 1.5,
      "currency": "USD",
      "basis": "string"
    }
  },
  "experience": {
    "id": "string",
    "name": "string"
  },
  "updated_at": "string"
}

{
  "_tag": "DeveloperApiBadRequest",
  "code": "string",
  "message": "string",
  "feedback": "string"
}