> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomarketbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Change a booking status

> Moves the booking through its lifecycle. The `status` enum on the request body is the authoritative list of what a caller may ASK for — it is narrower than the `status` on the response, because `SCHEDULED` and `DISPUTED` are states a booking is put into by the platform and can only be observed, never requested.

Which of the settable statuses your key may actually use also depends on where the booking is now and on the capacity of the caller. An API key cannot resolve a dispute, and cannot reverse a settled booking back to `AWAITING_CONFIRMATION`: both decide between two accounts of what happened, and are reserved for an operator in the MarketBox console. Nor can it cancel a booking that is `AWAITING_CONFIRMATION`: the session has taken place, and cancelling it would void the supplier's claim to be paid. Settle it instead (`COMPLETED` or a no-show).

`NO_SHOW` can no longer be SET. Use `CLIENT_NO_SHOW` or `SUPPLIER_NO_SHOW`, which record which side was absent; sending `NO_SHOW` returns a 400 naming the value. It remains a status a booking can CARRY and is still returned by every read: bookings recorded before the split keep it indefinitely and are not being migrated, because nobody ever recorded which party failed to show and we will not guess. A consumer switching exhaustively on booking status must keep handling it.

A transition the booking cannot make from where it currently stands is a 400 naming that current status, so a rejection tells you what to retry from. Returns 409 if the booking changed underneath you.

Cancelling releases the supplier time and settles the order item the booking drew on, atomically with the status change. For a PACKAGE session the credit goes back to the order item by default (`quantityRemaining` rises by the quantity the session used, and a `CREDIT_REVERSAL` transaction is recorded against the original `CREDIT_REDEMPTION`). Send `creditTreatment: "FORFEIT"` to keep the session spent instead — a late cancellation, say; `"RETURN"` states the default explicitly. A booking made against a single-session order item holds no reusable credit: cancelling it closes its allocation and returns no quantity, and sending `creditTreatment` for one is a 422 `NO_SESSION_CREDIT` with nothing cancelled. `creditTreatment` is only valid with `CANCELLED`. This route never moves money.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/projects/{projectId}/bookings/{bookingId}/status
openapi: 3.0.0
info:
  title: MarketBox 2.0 Open API
  version: 1.0.0
  description: >-
    The MarketBox public API for building booking experiences. Core model:
    create an order, then draw its order items down into bookings. Single
    bookings reference an order item per service line; package bookings draw one
    PACKAGE item down across N sessions. To schedule a package, build a slate
    (POST /availability/package-slate) and book it by slateId (POST
    /orders/{orderId}/package-bookings). See the guides for end-to-end
    walkthroughs.
  contact:
    name: MarketBox support
servers:
  - url: https://apiv2.gomarketbox.com
    description: MarketBox Open API
security:
  - ApiKeyAuth: []
paths:
  /v1/projects/{projectId}/bookings/{bookingId}/status:
    post:
      tags:
        - Bookings
      summary: Change a booking status
      description: >-
        Moves the booking through its lifecycle. The `status` enum on the
        request body is the authoritative list of what a caller may ASK for — it
        is narrower than the `status` on the response, because `SCHEDULED` and
        `DISPUTED` are states a booking is put into by the platform and can only
        be observed, never requested.


        Which of the settable statuses your key may actually use also depends on
        where the booking is now and on the capacity of the caller. An API key
        cannot resolve a dispute, and cannot reverse a settled booking back to
        `AWAITING_CONFIRMATION`: both decide between two accounts of what
        happened, and are reserved for an operator in the MarketBox console. Nor
        can it cancel a booking that is `AWAITING_CONFIRMATION`: the session has
        taken place, and cancelling it would void the supplier's claim to be
        paid. Settle it instead (`COMPLETED` or a no-show).


        `NO_SHOW` can no longer be SET. Use `CLIENT_NO_SHOW` or
        `SUPPLIER_NO_SHOW`, which record which side was absent; sending
        `NO_SHOW` returns a 400 naming the value. It remains a status a booking
        can CARRY and is still returned by every read: bookings recorded before
        the split keep it indefinitely and are not being migrated, because
        nobody ever recorded which party failed to show and we will not guess. A
        consumer switching exhaustively on booking status must keep handling it.


        A transition the booking cannot make from where it currently stands is a
        400 naming that current status, so a rejection tells you what to retry
        from. Returns 409 if the booking changed underneath you.


        Cancelling releases the supplier time and settles the order item the
        booking drew on, atomically with the status change. For a PACKAGE
        session the credit goes back to the order item by default
        (`quantityRemaining` rises by the quantity the session used, and a
        `CREDIT_REVERSAL` transaction is recorded against the original
        `CREDIT_REDEMPTION`). Send `creditTreatment: "FORFEIT"` to keep the
        session spent instead — a late cancellation, say; `"RETURN"` states the
        default explicitly. A booking made against a single-session order item
        holds no reusable credit: cancelling it closes its allocation and
        returns no quantity, and sending `creditTreatment` for one is a 422
        `NO_SESSION_CREDIT` with nothing cancelled. `creditTreatment` is only
        valid with `CANCELLED`. This route never moves money.
      parameters:
        - schema:
            type: string
            minLength: 1
            description: >-
              The project (tenant) that owns the resource. Every resource in
              this API is scoped to a project, and your API key is restricted to
              the projects it was issued for — a project outside that scope
              returns 403.
            example: prj_01kv60qgnef2kt3pvqgwmkbzfr
          required: true
          description: >-
            The project (tenant) that owns the resource. Every resource in this
            API is scoped to a project, and your API key is restricted to the
            projects it was issued for — a project outside that scope returns
            403.
          name: projectId
          in: path
        - schema:
            type: string
            minLength: 1
            description: >-
              The booking — one scheduled unit of service occupying supplier
              time.
            example: bk_01kv7q41n2hbqxwm03ymn7bxl9
          required: true
          description: The booking — one scheduled unit of service occupying supplier time.
          name: bookingId
          in: path
      requestBody:
        description: New status
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum:
                    - STARTED
                    - AWAITING_CONFIRMATION
                    - COMPLETED
                    - CANCELLED
                    - CLIENT_NO_SHOW
                    - SUPPLIER_NO_SHOW
                cancellationReason:
                  type: string
                  minLength: 1
                  description: >-
                    Required when status is CANCELLED; omitting it then is a
                    400. Why the booking was cancelled.
                creditTreatment:
                  type: string
                  enum:
                    - RETURN
                    - FORFEIT
                  description: >-
                    CANCELLED only. What happens to a package session credit:
                    RETURN (the default when omitted) puts the session back on
                    the order item; FORFEIT keeps it spent. Sending it for a
                    booking that is not a package session is a 422
                    NO_SESSION_CREDIT.
                  example: FORFEIT
              required:
                - status
      responses:
        '200':
          description: Updated booking
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Booking'
                required:
                  - data
        '400':
          description: Invalid transition or validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: API key cannot access this project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Booking not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '409':
          description: Version conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '422':
          description: >-
            `creditTreatment` was sent for a booking with no session credit;
            nothing was cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
components:
  schemas:
    Booking:
      type: object
      properties:
        projectId:
          type: string
        tenantId:
          type: string
        bookingId:
          type: string
        seriesId:
          type: string
          nullable: true
        occurrenceLocalDate:
          type: string
          nullable: true
        isException:
          type: boolean
        supplierId:
          type: string
          nullable: true
        clientId:
          type: string
        packageOrderItemId:
          type: string
          nullable: true
        bookingStartUtc:
          type: string
          format: date-time
        bookingEndUtc:
          type: string
          format: date-time
        bookingTz:
          type: string
        bookingLocalDate:
          type: string
        bookingLocalStartTime:
          type: string
        bookingLocalEndTime:
          type: string
        bookingLocalEndDate:
          type: string
        locale:
          type: string
        attribution:
          type: object
          properties:
            searchId:
              type: string
              minLength: 1
              maxLength: 128
              description: >-
                The `searchId` of the MarketBox search response the buyer booked
                from — the `X-MB-Search-Id` header / body field of every search
                route. Stored as given; a value MarketBox never issued is kept
                but not trusted.
              example: srch_01k7q3x9h4e8rb2d6m0z5a7c1n
            sessionKey:
              type: string
              minLength: 1
              maxLength: 64
              description: >-
                The same opaque per-session key you send with site events, at
                most 64 characters. Never an email, IP or user id.
              example: sess-example-01
            surface:
              type: string
              enum:
                - home
                - results
                - listing
                - site_search
                - profile
                - widget
                - assistant
                - other
              description: Where on your site the buyer started the purchase.
              example: results
          additionalProperties: false
          description: >-
            Which search and site session this purchase came from. Optional; set
            once on the order and copied onto every booking it funds. See the
            search-log guide, "Booking attribution".
        locationType:
          type: string
          enum:
            - PHYSICAL
            - VIRTUAL
            - TRAVEL_ZONE
        locationId:
          type: string
          nullable: true
        latitude:
          type: number
          nullable: true
        longitude:
          type: number
          nullable: true
        address:
          $ref: '#/components/schemas/Address'
        capacity:
          type: integer
          minimum: 0
          exclusiveMinimum: true
        participantCount:
          type: integer
          minimum: 0
        waitlistCount:
          type: integer
          minimum: 0
        isGroupBooking:
          type: boolean
        status:
          type: string
          enum:
            - SCHEDULED
            - STARTED
            - AWAITING_CONFIRMATION
            - DISPUTED
            - COMPLETED
            - CANCELLED
            - CLIENT_NO_SHOW
            - SUPPLIER_NO_SHOW
            - NO_SHOW
        statusUpdatedAt:
          type: string
          format: date-time
        statusUpdatedBy:
          type: string
        statusUpdatedByCapacity:
          type: string
          enum:
            - ADMIN
            - SUPPLIER
            - CLIENT
            - SYSTEM
            - API
        cancellationReason:
          type: string
          nullable: true
        cancelledBy:
          type: string
          nullable: true
        cancellationInitiatedBy:
          type: string
          enum:
            - CLIENT
            - SUPPLIER
            - BUSINESS
        cancellationReasonCode:
          type: string
          enum:
            - CLIENT_REQUESTED
            - CLIENT_UNWELL
            - SUPPLIER_UNAVAILABLE
            - WEATHER
            - FACILITY_UNAVAILABLE
            - BOOKED_IN_ERROR
            - OTHER
        creditTreatment:
          type: string
          enum:
            - RETURN
            - FORFEIT
            - REFUND_ORIGINAL_PAYMENT
            - NOT_APPLICABLE
        durationOverrideMinutes:
          type: integer
          minimum: 0
          exclusiveMinimum: true
          maximum: 1440
        durationOverrideReason:
          type: string
          minLength: 1
          maxLength: 500
        counts:
          type: object
          properties:
            services:
              type: integer
              minimum: 0
            notes:
              type: integer
              minimum: 0
            participants:
              type: integer
              minimum: 0
          required:
            - services
            - notes
            - participants
        deleted:
          type: boolean
        version:
          type: integer
          minimum: 0
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        createdBy:
          type: string
        updatedBy:
          type: string
      required:
        - projectId
        - tenantId
        - bookingId
        - supplierId
        - clientId
        - bookingStartUtc
        - bookingEndUtc
        - bookingTz
        - bookingLocalDate
        - bookingLocalStartTime
        - bookingLocalEndTime
        - bookingLocalEndDate
        - locationType
        - locationId
        - latitude
        - longitude
        - address
        - capacity
        - participantCount
        - waitlistCount
        - isGroupBooking
        - status
        - statusUpdatedAt
        - counts
        - deleted
        - version
        - createdAt
        - updatedAt
        - createdBy
        - updatedBy
    ErrorMessage:
      type: object
      properties:
        code:
          type: string
          description: Stable machine-readable error code, e.g. NOT_FOUND.
        message:
          type: string
          description: Human-readable description of what went wrong.
        statusCode:
          type: integer
          description: The HTTP status code of this response.
        requestId:
          type: string
          description: >-
            The id of this request, also returned as the X-Request-Id header.
            Quote it in a support ticket.
      required:
        - code
        - message
        - statusCode
        - requestId
      example:
        code: NOT_FOUND
        message: Booking not found
        statusCode: 404
        requestId: a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10
    Address:
      type: object
      nullable: true
      properties:
        addressOneLine:
          type: string
          minLength: 1
          description: The whole address on one line, as a person would write it.
          example: 10 Main St, Toronto, ON M5V 1A1, Canada
        streetNumber:
          type: string
          minLength: 1
          description: The street number.
          example: '10'
        streetName:
          type: string
          minLength: 1
          description: The street name.
          example: Main St
        city:
          type: string
          minLength: 1
          description: The city or town.
          example: Toronto
        state:
          type: string
          minLength: 1
          description: The state, province or region; an ISO 3166-2 code when one matches.
          example: 'ON'
        country:
          type: string
          minLength: 1
          description: The country; ISO 3166-1 alpha-2, alpha-3 or the English name.
          example: CA
        zipCode:
          type: string
          minLength: 1
          description: The postal or ZIP code, in any national format.
          example: M5V 1A1
        unitNumber:
          type: string
          nullable: true
          description: The unit, suite or apartment, if any.
          example: 4B
      required:
        - addressOneLine
        - streetNumber
        - streetName
        - city
        - state
        - country
        - zipCode
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key minted in the MarketBox dashboard. Scope is restricted to the
        projects you select at creation time. Every route needs the key's
        standard API access (`*`) except `POST /v1/projects/{projectId}/events`,
        which needs `events:write`; a key without `*` is refused with 403
        `CAPABILITY_NOT_GRANTED`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.