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

# List the signed-in supplier’s bookings

> Every booking assigned to the supplier the user token resolves to, in the window — the rows the MarketBox dashboard shows them under My Bookings, built by the same code. Each row carries `viewerActions` (what the supplier may do with it now, by the service’s participant settings and the server’s clock) and, with `expand`, the client as the settings allow the supplier to see them, the services, the package position, the location, the participants and the supplier’s own attendance report. Not paginated: the whole window is returned, so keep windows short (a day or a week). Requires the API key and the supplier’s user token.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/bookings
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}/suppliers/me/bookings:
    get:
      tags:
        - Supplier plane
      summary: List the signed-in supplier’s bookings
      description: >-
        Every booking assigned to the supplier the user token resolves to, in
        the window — the rows the MarketBox dashboard shows them under My
        Bookings, built by the same code. Each row carries `viewerActions` (what
        the supplier may do with it now, by the service’s participant settings
        and the server’s clock) and, with `expand`, the client as the settings
        allow the supplier to see them, the services, the package position, the
        location, the participants and the supplier’s own attendance report. Not
        paginated: the whole window is returned, so keep windows short (a day or
        a week). Requires the API key and the supplier’s user token.
      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
            format: date-time
            description: >-
              Earliest booking start to include (ISO 8601 instant, UTC). A
              single day is one day’s window.
            example: '2026-10-19T00:00:00.000Z'
          required: false
          description: >-
            Earliest booking start to include (ISO 8601 instant, UTC). A single
            day is one day’s window.
          name: startDate
          in: query
        - schema:
            type: string
            format: date-time
            description: Latest booking start to include (ISO 8601 instant, UTC).
            example: '2026-10-26T00:00:00.000Z'
          required: false
          description: Latest booking start to include (ISO 8601 instant, UTC).
          name: endDate
          in: query
        - schema:
            type: string
            enum:
              - SCHEDULED
              - STARTED
              - AWAITING_CONFIRMATION
              - DISPUTED
              - COMPLETED
              - CANCELLED
              - CLIENT_NO_SHOW
              - SUPPLIER_NO_SHOW
              - NO_SHOW
            description: Only bookings in this status.
            example: SCHEDULED
          required: false
          description: Only bookings in this status.
          name: status
          in: query
        - schema:
            type: string
            description: >-
              Comma-separated set of expansions, any order: client, services,
              package, location, participants, myReport. Each adds one optional
              key, absent unless requested. Unknown values are rejected. Every
              value except `client` requires startDate and endDate, at most 93
              days apart.
            example: client,services,location,participants,myReport
          required: false
          description: >-
            Comma-separated set of expansions, any order: client, services,
            package, location, participants, myReport. Each adds one optional
            key, absent unless requested. Unknown values are rejected. Every
            value except `client` requires startDate and endDate, at most 93
            days apart.
          name: expand
          in: query
      responses:
        '200':
          description: Bookings list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      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
                        client:
                          type: object
                          nullable: true
                          properties:
                            displayName:
                              type: string
                              description: The client as this viewer may see them.
                            email:
                              type: string
                              description: Only when the service shows suppliers the email.
                            phone:
                              type: string
                              description: Only when the service shows suppliers the phone.
                          required:
                            - displayName
                          description: >-
                            The client, as the booking’s participant settings
                            allow this viewer to see them. Present only with
                            `expand=client`; null when the profile is
                            unreachable.
                        viewerActions:
                          type: object
                          properties:
                            canCancel:
                              type: boolean
                            canReschedule:
                              type: boolean
                            blockedReason:
                              type: string
                          required:
                            - canCancel
                            - canReschedule
                          description: >-
                            What this viewer may do with the booking now, by the
                            server’s clock and the service’s participant
                            settings.
                        services:
                          type: object
                          nullable: true
                          properties:
                            name:
                              type: string
                              description: The first service’s name.
                            count:
                              type: integer
                              description: How many services the booking has.
                          required:
                            - name
                            - count
                          description: >-
                            The first service's name and how many services the
                            booking has.
                        package:
                          oneOf:
                            - type: object
                              properties:
                                credit:
                                  type: string
                                  enum:
                                    - HELD
                                position:
                                  type: integer
                                total:
                                  type: integer
                              required:
                                - credit
                                - position
                                - total
                            - type: object
                              properties:
                                credit:
                                  type: string
                                  enum:
                                    - RETURNED
                                total:
                                  type: integer
                              required:
                                - credit
                                - total
                            - nullable: true
                          description: >-
                            Where the booking sits in its package — "Booking 3
                            of 10". `HELD`: the booking holds one of the
                            package's credits (booked, delivered, or forfeited
                            by a late cancel or no-show), and `position` is its
                            1-based place among the credit-holding bookings by
                            start time. `RETURNED`: it was cancelled and its
                            credit went back on the package, so it has no place.
                            `total` is the package's PURCHASED credit count; a
                            position above it means the package holds more
                            sessions than were sold (migrated data only). Null
                            when the booking has no package, or when its credit
                            record or the purchased count is unreachable.
                        location:
                          type: object
                          nullable: true
                          properties:
                            name:
                              type: string
                              description: The location’s name — what staff call it.
                            addressOneLine:
                              type: string
                              nullable: true
                              description: Its address on one line, when known.
                          required:
                            - name
                            - addressOneLine
                          description: >-
                            The company location's name — what staff call it —
                            for PHYSICAL bookings.
                        participants:
                          type: object
                          nullable: true
                          properties:
                            labels:
                              type: array
                              nullable: true
                              items:
                                type: string
                              description: Names as this viewer may see them.
                            count:
                              type: integer
                              description: Participants this viewer may see on the booking.
                          required:
                            - labels
                            - count
                          description: >-
                            The participants this caller may see, named as the
                            service allows (client `participantDisplay`, or the
                            supplier projection). `labels: null` = show a
                            placeholder from `count`, never an empty list.
                        myReport:
                          type: object
                          nullable: true
                          properties:
                            reportable:
                              type: boolean
                              description: >-
                                Whether a new report is taken now (server
                                clock).
                            filed:
                              type: boolean
                              description: Whether this caller has filed their own report.
                            attended:
                              type: boolean
                              nullable: true
                              description: The filed answer; null when not filed.
                          required:
                            - reportable
                            - filed
                            - attended
                          description: >-
                            The caller's OWN attendance report: whether a new
                            one is taken now (server clock), whether they filed
                            one, and its answer.
                      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
                        - viewerActions
                required:
                  - data
        '400':
          description: Unknown expand value, or a missing/oversized window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: Missing or invalid API key or user token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: >-
            The API key cannot access this project (FORBIDDEN) or lacks standard
            API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no
            MarketBox account record (FORBIDDEN, "User account not found.
            Complete registration first."); or the signed-in user is not a
            member of the project (NOT_A_MEMBER), their membership has ended
            (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s
            permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they
            do not hold (ACTING_ROLE_NOT_HELD)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: >-
            The signed-in user has no supplier record here: no SUPPLIER among
            the roles they act under (NO_SUPPLIER_ROLE), or no single supplier
            record linked to them (SUPPLIER_NOT_LINKED); or no such booking of
            theirs (NOT_FOUND)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      security:
        - ApiKeyAuth: []
          EndUserBearer: []
components:
  schemas:
    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
    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`.
    EndUserBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        The signed-in person's Cognito access token, issued to this
        application's app client. Sent with the API key on the /clients/me and
        /suppliers/me routes.

````

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