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

# Create a supplier review (1–5 star rating with optional comment)

> Records a rating against a supplier and folds it into that supplier's running average in the same atomic write, so the aggregate never disagrees with the rows behind it.

Treat this as permanent. There is no update or delete route, so a review posted by mistake moves the supplier's average for good — validate on your side before calling. Nothing is deduplicated and no booking is required: the same reviewer can post repeatedly, and each submission counts again, so enforce "one review per completed booking" yourself if that is your intent. `reviewerId` is optional and stored as given; it is not authenticated or checked against the client who was served.

`bookingId` is optional and links the review to a booking. Supplying it stops MarketBox's rating follow-up emails for that booking — omit it and the client keeps being nudged to rate a booking they have already reviewed. It is stored as given and is **not** validated: an id that does not exist, or belongs to another project or another client, is accepted and simply links to nothing. It does not deduplicate either — two reviews carrying the same `bookingId` both count.

`ratingStars` must be a whole number from 1 to 5, and `reviewText` is optional and capped at 5000 characters. The supplier must exist in this project, or 404.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/projects/{projectId}/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}/reviews:
    post:
      tags:
        - Reviews
      summary: Create a supplier review (1–5 star rating with optional comment)
      description: >-
        Records a rating against a supplier and folds it into that supplier's
        running average in the same atomic write, so the aggregate never
        disagrees with the rows behind it.


        Treat this as permanent. There is no update or delete route, so a review
        posted by mistake moves the supplier's average for good — validate on
        your side before calling. Nothing is deduplicated and no booking is
        required: the same reviewer can post repeatedly, and each submission
        counts again, so enforce "one review per completed booking" yourself if
        that is your intent. `reviewerId` is optional and stored as given; it is
        not authenticated or checked against the client who was served.


        `bookingId` is optional and links the review to a booking. Supplying it
        stops MarketBox's rating follow-up emails for that booking — omit it and
        the client keeps being nudged to rate a booking they have already
        reviewed. It is stored as given and is **not** validated: an id that
        does not exist, or belongs to another project or another client, is
        accepted and simply links to nothing. It does not deduplicate either —
        two reviews carrying the same `bookingId` both count.


        `ratingStars` must be a whole number from 1 to 5, and `reviewText` is
        optional and capped at 5000 characters. The supplier must exist in this
        project, or 404.
      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
      requestBody:
        description: Review data
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                supplierId:
                  type: string
                  minLength: 1
                ratingStars:
                  type: integer
                  minimum: 1
                  maximum: 5
                reviewText:
                  type: string
                  maxLength: 5000
                reviewerId:
                  type: string
                bookingId:
                  type: string
                  description: >-
                    Optional booking this review is about. Supplying it links
                    the review to that booking and stops the rating follow-up
                    emails for it. Stored as given and not validated against the
                    booking, and it does not deduplicate.
                  example: bk_01kv60qge5eh59ap0gw0pqrrys
              required:
                - supplierId
                - 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: Supplier not found
          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.