---
title: "Cancel a booking"
method: POST
path: "/bookings/{booking_id}/cancel"
tags: ["Bookings"]
---

# Cancel a booking

`POST /bookings/{booking_id}/cancel`

## Request

- Base URL: `https://wall.marketing/api/v1`
- URL: `https://wall.marketing/api/v1/bookings/{booking_id}/cancel`
- Auth: HTTP bearer

Cancels a booking that is not paid yet. For a paid booking it asks Wall Marketing staff to cancel and refund it (a person decides).

## Path parameters

- `booking_id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `reason` string

## Response `200`

Cancelled

- Booking
  - `object` string: Always "booking".
  - `id` string: The booking_id.
  - `livemode` boolean: False in the sandbox.
  - `status` string: One of: awaiting_approval, in_review, awaiting_payment, payment_expired, scheduled, live, finished, declined, cancelled.
  - `status_reason` string, nullable: Why it is declined or cancelled, if it is.
  - `next_step` string: Plain-language instruction for what happens or what to do next.
  - `campaign_name` string: The campaign name.
  - `category` string, nullable: The advert's category.
  - `total_usd` number: Total price in US dollars.
  - `currency` string: Always "usd".
  - `quote_id` string, nullable: The quote it was booked from.
  - `creative_id` string, nullable: The artwork shown.
  - `placements` object[]: One per venue, with its dates and state.
    - `venue_id` string: The venue (screen) booked.
    - `venue_name` string: The venue's name.
    - `address` string, nullable: The venue's address.
    - `start_date` string: First day the advert shows.
    - `end_date` string: Exclusive: the first day it no longer shows.
    - `last_day` string, nullable: The last day the advert shows (YYYY-MM-DD).
    - `days` integer: Days booked.
    - `amount_usd` number: Price for this venue, in US dollars.
    - `state` string: not_started, scheduled, live, finished or removed.
  - `approval` object: The account holder's approval and any staff check.
    - `required` boolean: Whether the account holder must approve it.
    - `reasons` object[]: Why approval is needed.
      - `code` string: e.g. over_auto_approve_limit or new_venue.
      - `message` string: The reason in plain language.
    - `approved_at` string, nullable: When the account holder approved it. ISO 8601, UTC.
    - `staff_review_required` boolean: Whether Wall Marketing staff check it first (sensitive categories).
    - `reviewed_at` string, nullable: When staff checked it. ISO 8601, UTC.
  - `payment` object: Payment state.
    - `status` string: paid, awaiting_payment, expired, not_started, or simulated in the sandbox.
    - `payment_url` string, nullable: Card payment page for the account holder, while awaiting payment.
    - `payment_url_expires_at` string, nullable: When payment_url stops working. ISO 8601, UTC.
    - `last_error` string, nullable: Why the last automatic payment failed, if it did.
  - `order_reference` string, nullable: Wall Marketing's order reference once paid.
  - `cancellation_requested_at` string, nullable: When cancellation of a paid booking was requested. ISO 8601, UTC.
  - `report_url` string: Proof-of-display report (REST).
  - `created_at` string, nullable: When it was booked. ISO 8601, UTC.
  - `updated_at` string, nullable: Last change. ISO 8601, UTC.

## Other responses

- `202`: Paid: cancellation requested from staff
- `400`: Error
- `401`: Error
- `403`: Error
- `404`: Error
- `409`: Error
- `429`: Error

---

[API](https://skmtc.dev/wall/apis/wall-marketing-platform-api.md) · [All operations](https://skmtc.dev/wall/apis/wall-marketing-platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/wall/apis/wall-marketing-platform-api/revisions/290b284951e3?raw)