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

> The supplier’s alerts — new, moved and cancelled bookings — newest first, as the bell in the MarketBox dashboard lists them, read by the same code from the same inbox. Each row carries a `target` naming what it is about (`{ kind: "booking", bookingId }`); map it to your own page, since alerts hold no URL. `readAt` is absent while unread. Alerts are kept 90 days. Paginated with `limit` (1–100, default 20) and an opaque `cursor`; a cursor from another `filter` is 400 `INVALID_CURSOR`. Requires the API key and the supplier’s user token.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/projects/{projectId}/suppliers/me/alerts
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/alerts:
    get:
      tags:
        - Supplier plane
      summary: List the signed-in supplier’s alerts
      description: >-
        The supplier’s alerts — new, moved and cancelled bookings — newest
        first, as the bell in the MarketBox dashboard lists them, read by the
        same code from the same inbox. Each row carries a `target` naming what
        it is about (`{ kind: "booking", bookingId }`); map it to your own page,
        since alerts hold no URL. `readAt` is absent while unread. Alerts are
        kept 90 days. Paginated with `limit` (1–100, default 20) and an opaque
        `cursor`; a cursor from another `filter` is 400 `INVALID_CURSOR`.
        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
            enum:
              - unread
              - all
            default: all
            description: >-
              `unread` for the unread alerts only; `all` (the default) for every
              alert.
            example: unread
          required: false
          description: >-
            `unread` for the unread alerts only; `all` (the default) for every
            alert.
          name: filter
          in: query
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            description: >-
              Maximum alerts to return in `data`, 1–100. Defaults to 20. Values
              outside the range return 400. Treat `nextCursor: null` as the only
              end-of-results signal.
            example: 20
          required: false
          description: >-
            Maximum alerts to return in `data`, 1–100. Defaults to 20. Values
            outside the range return 400. Treat `nextCursor: null` as the only
            end-of-results signal.
          name: limit
          in: query
        - schema:
            type: string
            minLength: 1
            description: >-
              Opaque token from a previous response’s `nextCursor`. Valid only
              for the same `filter` that produced it; any other cursor is 400
              `INVALID_CURSOR` — request the first page again without it.
            example: eyJwayI6InByal8wMSJ9
          required: false
          description: >-
            Opaque token from a previous response’s `nextCursor`. Valid only for
            the same `filter` that produced it; any other cursor is 400
            `INVALID_CURSOR` — request the first page again without it.
          name: cursor
          in: query
      responses:
        '200':
          description: A page of alerts
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        alertId:
                          type: string
                          description: Unique id of this alert.
                          example: alr_01kv60qge5eh59ap0gw0pqrrys
                        kind:
                          type: string
                          enum:
                            - ORDER_PAID
                            - REVIEW_RECEIVED
                            - INVITATION_ACCEPTED
                            - EMAIL_FAILED
                            - LESSON_ASSIGNED
                            - LESSON_MOVED
                            - LESSON_CANCELLED
                            - LESSON_REMINDER
                            - REVIEW_REQUESTED
                            - PAYMENT_NEEDS_REVIEW
                          description: >-
                            What happened. The `LESSON_*` names are stored
                            identifiers; each concerns a booking. A supplier
                            receives `LESSON_ASSIGNED` (a booking assigned to
                            them), `LESSON_MOVED` (one of their bookings moved)
                            and `LESSON_CANCELLED` (one of their bookings
                            cancelled). Clients receive `LESSON_REMINDER` (a
                            booking is coming up) and `REVIEW_REQUESTED`; staff
                            receive `ORDER_PAID`, `REVIEW_RECEIVED`,
                            `INVITATION_ACCEPTED` and `EMAIL_FAILED`.
                          example: LESSON_MOVED
                        audience:
                          type: string
                          enum:
                            - STAFF
                            - SUPPLIER
                            - CLIENT
                          description: Which of the caller's inboxes this alert is in.
                          example: SUPPLIER
                        createdAt:
                          type: string
                          description: ISO 8601 time the alert was written.
                          example: '2026-09-26T14:05:00.000Z'
                        occurredAt:
                          type: string
                          description: >-
                            ISO 8601 time the event itself happened. Shown in
                            the panel.
                          example: '2026-09-26T14:04:58.000Z'
                        readAt:
                          type: string
                          description: >-
                            ISO 8601 time the caller read it. Absent while
                            unread.
                          example: '2026-09-26T15:00:00.000Z'
                        resolvedAt:
                          type: string
                          description: >-
                            ISO 8601 time the underlying item was dealt with
                            elsewhere.
                          example: '2026-09-27T09:12:00.000Z'
                        target:
                          oneOf:
                            - type: object
                              properties:
                                kind:
                                  type: string
                                  enum:
                                    - booking
                                bookingId:
                                  type: string
                                  minLength: 1
                              required:
                                - kind
                                - bookingId
                              description: 'One booking: its detail page.'
                            - type: object
                              properties:
                                kind:
                                  type: string
                                  enum:
                                    - order
                                orderId:
                                  type: string
                                  minLength: 1
                              required:
                                - kind
                                - orderId
                              description: 'One order: its detail page.'
                            - type: object
                              properties:
                                kind:
                                  type: string
                                  enum:
                                    - email
                                emailId:
                                  type: string
                                  minLength: 1
                                bookingId:
                                  type: string
                                  minLength: 1
                              required:
                                - kind
                                - emailId
                              description: >-
                                One sent email, and the booking it was about
                                when known.
                            - type: object
                              properties:
                                kind:
                                  type: string
                                  enum:
                                    - review
                                supplierId:
                                  type: string
                                  minLength: 1
                              required:
                                - kind
                              description: >-
                                The review list, filtered to one supplier when
                                known.
                            - type: object
                              properties:
                                kind:
                                  type: string
                                  enum:
                                    - team
                              required:
                                - kind
                              description: 'The team: the project’s suppliers and staff.'
                            - type: object
                              properties:
                                kind:
                                  type: string
                                  enum:
                                    - settings
                                area:
                                  type: string
                                  enum:
                                    - payments
                              required:
                                - kind
                                - area
                              description: The project’s payment settings.
                            - type: object
                              properties:
                                kind:
                                  type: string
                                  enum:
                                    - bookings
                                filter:
                                  type: string
                                  enum:
                                    - awaiting
                                    - disputed
                              required:
                                - kind
                                - filter
                              description: >-
                                The project’s bookings list, filtered to those
                                awaiting a report or disputed.
                            - type: object
                              properties:
                                kind:
                                  type: string
                                  enum:
                                    - myAppointments
                                filter:
                                  type: string
                                  enum:
                                    - awaiting
                              required:
                                - kind
                                - filter
                              description: >-
                                The supplier’s own bookings list, filtered to
                                those awaiting their report.
                          description: >-
                            What the alert links to, as data rather than a URL:
                            map it to your own page. `kind` names the page.
                          example:
                            kind: booking
                            bookingId: bk_01kv60qge5eh59ap0gw0pqrrys
                        payload:
                          type: object
                          properties:
                            clientName:
                              type: string
                              description: Display name of the client the alert is about.
                              example: Jordan Lee
                            supplierName:
                              type: string
                              description: Display name of the supplier the alert is about.
                              example: Sam Rivera
                            serviceName:
                              type: string
                              description: Name of the service booked.
                              example: Private swim lesson
                            startUtc:
                              type: string
                              format: date-time
                              description: >-
                                Booking start as a UTC instant. Render it in
                                `zone`.
                              example: '2026-10-02T14:00:00.000Z'
                            zone:
                              type: string
                              minLength: 1
                              description: >-
                                The booking's home IANA zone, which `startUtc`
                                is displayed in.
                              example: America/Toronto
                            count:
                              type: integer
                              minimum: 0
                              description: >-
                                A quantity the copy needs — e.g. the number of
                                bookings on a new order.
                              example: 4
                            emailType:
                              type: string
                              enum:
                                - BOOKING_CONFIRMATION
                                - BOOKING_REMINDER
                                - LEAVE_RATING
                                - LEAVE_RATING_FOLLOWUP
                                - SUPPLIER_LEAVE_RATING
                                - SUPPLIER_LEAVE_RATING_FOLLOWUP
                                - SUPPLIER_AGENDA
                                - BOOKING_CANCELLED
                                - SUPPLIER_BOOKING_CANCELLED
                                - BOOKING_UPDATED
                                - BOOKING_TIME_OFFER
                                - SUPPLIER_NEW_BOOKING
                                - ORDER_CANCELLED
                                - SUPPLIER_ORDER_CANCELLED
                                - INVITATION
                              description: Which email failed, on EMAIL_FAILED.
                              example: BOOKING_CONFIRMATION
                            ratingStars:
                              type: integer
                              minimum: 1
                              maximum: 5
                              description: Stars on REVIEW_RECEIVED.
                              example: 5
                            inviteeName:
                              type: string
                              description: >-
                                Display name of the person who accepted, on
                                INVITATION_ACCEPTED.
                              example: Sam Rivera
                            paymentReason:
                              type: string
                              enum:
                                - DISPUTE_OPENED
                                - DISPUTE_WON
                                - DISPUTE_LOST
                                - PAID_ON_CANCELLED_ORDER
                                - ORDER_OVERPAID
                                - REFUND_FAILED
                              description: >-
                                Why the payment needs review, on
                                PAYMENT_NEEDS_REVIEW.
                              example: DISPUTE_OPENED
                          description: >-
                            Display fields snapshotted when the alert was
                            written. All optional.
                      required:
                        - alertId
                        - kind
                        - audience
                        - createdAt
                        - occurredAt
                        - target
                        - payload
                  nextCursor:
                    type: string
                    nullable: true
                    description: Cursor for the next page; `null` on the last page.
                    example: null
                required:
                  - data
                  - nextCursor
        '400':
          description: >-
            An invalid `filter` or `limit`, or a cursor that is not valid for
            this list (INVALID_CURSOR)
          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)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      security:
        - ApiKeyAuth: []
          EndUserBearer: []
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`.
    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.