> ## 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.

# Review a booking, in either direction

> Records one side of a booking rating the other, and folds the rating into the rated party's running average in the same atomic write. Both parties are read off the booking in the URL — the body carries **no ids at all**, so a review can only ever be attributed to the supplier and client who were actually on that booking.

`direction` picks who is rating whom. `CLIENT_TO_SUPPLIER` is the client rating the supplier; `SUPPLIER_TO_CLIENT` is the supplier rating the client. The response tells you which party the review is *about* without re-deriving it: `subjectType` is `SUPPLIER` or `CLIENT`, and `subjectId` is that party's id.

**The booking does not have to be COMPLETED.** Nothing in MarketBox moves a booking to COMPLETED automatically — the status is only ever set deliberately — so requiring it would make this endpoint unusable for most tenants. Any booking is reviewable except a CANCELLED one, which returns 422. A booking with no supplier assigned is a legal state, but there is no supplier to rate or to rate from, so it also returns 422.

At most **one review per booking per direction**, enforced by a uniqueness item written inside the same transaction rather than by a read beforehand — two simultaneous submits cannot both win. A second review in the same direction returns 409 `REVIEW_ALREADY_EXISTS`. Reviews posted through the older project-level `POST /reviews` route carry no such guard, so this endpoint also runs a best-effort index lookup first and will report 409 for one it can see; that lookup reads an eventually-consistent index, so treat it as a courtesy rather than the guarantee.

Treat a review as permanent — there is no update or delete route, and the average it moved stays moved.

The response carries best-effort display names (`supplierName`, `clientName`) resolved from the two profiles, so a hosted review page can render a name without a second call. A counterparty whose profile cannot be resolved keeps its bare id and the corresponding name is absent. No email address is returned for either party.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/projects/{projectId}/bookings/{bookingId}/reviews
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}/reviews:
    post:
      tags:
        - Reviews
      summary: Review a booking, in either direction
      description: >-
        Records one side of a booking rating the other, and folds the rating
        into the rated party's running average in the same atomic write. Both
        parties are read off the booking in the URL — the body carries **no ids
        at all**, so a review can only ever be attributed to the supplier and
        client who were actually on that booking.


        `direction` picks who is rating whom. `CLIENT_TO_SUPPLIER` is the client
        rating the supplier; `SUPPLIER_TO_CLIENT` is the supplier rating the
        client. The response tells you which party the review is *about* without
        re-deriving it: `subjectType` is `SUPPLIER` or `CLIENT`, and `subjectId`
        is that party's id.


        **The booking does not have to be COMPLETED.** Nothing in MarketBox
        moves a booking to COMPLETED automatically — the status is only ever set
        deliberately — so requiring it would make this endpoint unusable for
        most tenants. Any booking is reviewable except a CANCELLED one, which
        returns 422. A booking with no supplier assigned is a legal state, but
        there is no supplier to rate or to rate from, so it also returns 422.


        At most **one review per booking per direction**, enforced by a
        uniqueness item written inside the same transaction rather than by a
        read beforehand — two simultaneous submits cannot both win. A second
        review in the same direction returns 409 `REVIEW_ALREADY_EXISTS`.
        Reviews posted through the older project-level `POST /reviews` route
        carry no such guard, so this endpoint also runs a best-effort index
        lookup first and will report 409 for one it can see; that lookup reads
        an eventually-consistent index, so treat it as a courtesy rather than
        the guarantee.


        Treat a review as permanent — there is no update or delete route, and
        the average it moved stays moved.


        The response carries best-effort display names (`supplierName`,
        `clientName`) resolved from the two profiles, so a hosted review page
        can render a name without a second call. A counterparty whose profile
        cannot be resolved keeps its bare id and the corresponding name is
        absent. No email address is returned for either party.
      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: Review data
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                direction:
                  type: string
                  enum:
                    - CLIENT_TO_SUPPLIER
                    - SUPPLIER_TO_CLIENT
                  description: >-
                    Which way the review points. CLIENT_TO_SUPPLIER is the
                    client rating the supplier; SUPPLIER_TO_CLIENT is the
                    supplier rating the client.
                  example: CLIENT_TO_SUPPLIER
                ratingStars:
                  type: integer
                  minimum: 1
                  maximum: 5
                  description: Whole-star rating from 1 to 5.
                  example: 5
                reviewText:
                  type: string
                  maxLength: 5000
                  description: Optional free-text comment, up to 5000 characters.
                  example: Turned up on time and was a pleasure to work with.
              required:
                - direction
                - ratingStars
      responses:
        '201':
          description: Review created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      reviewId:
                        type: string
                      supplierId:
                        type: string
                      clientId:
                        type: string
                      projectId:
                        type: string
                      ratingStars:
                        type: integer
                      reviewText:
                        type: string
                      reviewerId:
                        type: string
                      bookingId:
                        type: string
                      direction:
                        type: string
                        enum:
                          - CLIENT_TO_SUPPLIER
                          - SUPPLIER_TO_CLIENT
                      subjectType:
                        type: string
                        enum:
                          - SUPPLIER
                          - CLIENT
                      subjectId:
                        type: string
                      createdAt:
                        type: string
                      supplierName:
                        type: string
                      clientName:
                        type: string
                    required:
                      - reviewId
                      - supplierId
                      - projectId
                      - ratingStars
                      - direction
                      - subjectType
                      - subjectId
                      - createdAt
                required:
                  - data
        '400':
          description: Validation error
          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: This side has already reviewed this booking
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '422':
          description: Booking is cancelled, or has no supplier to review
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
components:
  schemas:
    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
  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.