> ## 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 orders by status, by payment method, or every order in a date range

> Exactly one listing mode per request, chosen by which filter you send:

- `status` — orders in that status, narrowed by `startCreatedAt`/`endCreatedAt`.
- `paymentMethod` — how orders were settled (`STRIPE`, `CASH`, `EXTERNAL`, `COMP`, `MIXED`, `LEGACY`), narrowed by `startSettledAt`/`endSettledAt`. This is the reconciliation read: "what did we take in cash last month".
- neither — every order, narrowed by `startCreatedAt`/`endCreatedAt`.

Sending both `status` and `paymentMethod` is a 400, as is a date range belonging to the other mode (`startSettledAt` without `paymentMethod`, or `startCreatedAt` with it) — each index carries only one date, so the pairing is not a preference.

⚠️ The no-filter mode reads an index whose key attributes are written only when an order is created, so every order created before this feature shipped, and every order migrated from MarketBox v1, is MISSING from it until a backfill runs. An empty or short page there does not mean the project has no orders — list by `status` when you need completeness over historical data.

Paginate with `limit` and `cursor`; `nextCursor: null` is the last page. A cursor belongs to the filter set that minted it — replaying one after switching listing mode is rejected with a 400 `BAD_REQUEST` ("Invalid cursor") rather than silently returning the wrong page, so start a fresh request instead. To list one client's orders, use `GET /projects/{projectId}/clients/{clientId}/orders`.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/projects/{projectId}/orders
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}/orders:
    get:
      tags:
        - Orders
      summary: List orders by status, by payment method, or every order in a date range
      description: >-
        Exactly one listing mode per request, chosen by which filter you send:


        - `status` — orders in that status, narrowed by
        `startCreatedAt`/`endCreatedAt`.

        - `paymentMethod` — how orders were settled (`STRIPE`, `CASH`,
        `EXTERNAL`, `COMP`, `MIXED`, `LEGACY`), narrowed by
        `startSettledAt`/`endSettledAt`. This is the reconciliation read: "what
        did we take in cash last month".

        - neither — every order, narrowed by `startCreatedAt`/`endCreatedAt`.


        Sending both `status` and `paymentMethod` is a 400, as is a date range
        belonging to the other mode (`startSettledAt` without `paymentMethod`,
        or `startCreatedAt` with it) — each index carries only one date, so the
        pairing is not a preference.


        ⚠️ The no-filter mode reads an index whose key attributes are written
        only when an order is created, so every order created before this
        feature shipped, and every order migrated from MarketBox v1, is MISSING
        from it until a backfill runs. An empty or short page there does not
        mean the project has no orders — list by `status` when you need
        completeness over historical data.


        Paginate with `limit` and `cursor`; `nextCursor: null` is the last page.
        A cursor belongs to the filter set that minted it — replaying one after
        switching listing mode is rejected with a 400 `BAD_REQUEST` ("Invalid
        cursor") rather than silently returning the wrong page, so start a fresh
        request instead. To list one client's orders, use `GET
        /projects/{projectId}/clients/{clientId}/orders`.
      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:
              - DRAFT
              - PENDING
              - PAID
              - CANCELLED
            description: >-
              List only orders in this status. Mutually exclusive with
              `paymentMethod`; with neither, every order in the created-date
              window is listed.
            example: PAID
          required: false
          description: >-
            List only orders in this status. Mutually exclusive with
            `paymentMethod`; with neither, every order in the created-date
            window is listed.
          name: status
          in: query
        - schema:
            type: string
            enum:
              - STRIPE
              - CASH
              - EXTERNAL
              - COMP
              - MIXED
              - LEGACY
            description: >-
              List by how the order was settled. This mode reads a settled-date
              index, so pair it with `startSettledAt`/`endSettledAt` and never
              with the created-date parameters. Only settled orders carry a
              payment method, so DRAFT and PENDING orders never appear in this
              mode; a settled order later CANCELLED (refunded or not) still
              does, with its `status`. Mutually exclusive with `status`.
            example: CASH
          required: false
          description: >-
            List by how the order was settled. This mode reads a settled-date
            index, so pair it with `startSettledAt`/`endSettledAt` and never
            with the created-date parameters. Only settled orders carry a
            payment method, so DRAFT and PENDING orders never appear in this
            mode; a settled order later CANCELLED (refunded or not) still does,
            with its `status`. Mutually exclusive with `status`.
          name: paymentMethod
          in: query
        - schema:
            type: string
            format: date-time
            description: >-
              Inclusive lower bound on `createdAt`, as an ISO 8601 instant.
              Valid in the `status` and no-filter modes only.
            example: '2026-09-01T00:00:00.000Z'
          required: false
          description: >-
            Inclusive lower bound on `createdAt`, as an ISO 8601 instant. Valid
            in the `status` and no-filter modes only.
          name: startCreatedAt
          in: query
        - schema:
            type: string
            format: date-time
            description: >-
              Upper bound on `createdAt`, as an ISO 8601 instant, EXCLUSIVE of
              the instant itself — pass the next period's start to cover a whole
              day or month. Valid in the `status` and no-filter modes only.
            example: '2026-10-01T00:00:00.000Z'
          required: false
          description: >-
            Upper bound on `createdAt`, as an ISO 8601 instant, EXCLUSIVE of the
            instant itself — pass the next period's start to cover a whole day
            or month. Valid in the `status` and no-filter modes only.
          name: endCreatedAt
          in: query
        - schema:
            type: string
            format: date-time
            description: >-
              Inclusive lower bound on `settledAt`, as an ISO 8601 instant.
              Requires `paymentMethod`.
            example: '2026-09-01T00:00:00.000Z'
          required: false
          description: >-
            Inclusive lower bound on `settledAt`, as an ISO 8601 instant.
            Requires `paymentMethod`.
          name: startSettledAt
          in: query
        - schema:
            type: string
            format: date-time
            description: >-
              Upper bound on `settledAt`, as an ISO 8601 instant, EXCLUSIVE of
              the instant itself — pass the next period's start to cover a whole
              day or month. Requires `paymentMethod`.
            example: '2026-10-01T00:00:00.000Z'
          required: false
          description: >-
            Upper bound on `settledAt`, as an ISO 8601 instant, EXCLUSIVE of the
            instant itself — pass the next period's start to cover a whole day
            or month. Requires `paymentMethod`.
          name: endSettledAt
          in: query
        - schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
            description: >-
              Maximum rows to return in `data`, 1–200. Defaults to 50. Values
              outside the range return 400. A page can still hold fewer rows
              than requested, so treat `nextCursor: null` as the only
              end-of-results signal and never stop on a page that merely looks
              short.
            example: 50
          required: false
          description: >-
            Maximum rows to return in `data`, 1–200. Defaults to 50. Values
            outside the range return 400. A page can still hold fewer rows than
            requested, so treat `nextCursor: null` as the only end-of-results
            signal and never stop on a page that merely looks short.
          name: limit
          in: query
        - schema:
            type: string
            description: >-
              Opaque pagination token from a previous response's `nextCursor`.
              Treat it as a magic string — never parse or construct one. A
              cursor is only valid for the same filters that produced it, and
              `nextCursor: null` means the last page.
          required: false
          description: >-
            Opaque pagination token from a previous response's `nextCursor`.
            Treat it as a magic string — never parse or construct one. A cursor
            is only valid for the same filters that produced it, and
            `nextCursor: null` means the last page.
          name: cursor
          in: query
      responses:
        '200':
          description: Orders list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
                  nextCursor:
                    type: string
                    nullable: true
                required:
                  - data
                  - nextCursor
        '400':
          description: >-
            Invalid cursor or limit; both status and paymentMethod; or a date
            range paired with the wrong listing mode
          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'
components:
  schemas:
    Order:
      type: object
      properties:
        projectId:
          type: string
        tenantId:
          type: string
        orderId:
          type: string
        clientId:
          type: string
        currency:
          type: string
          minLength: 3
          maxLength: 3
        subtotal:
          $ref: '#/components/schemas/Money'
        feeTotal:
          $ref: '#/components/schemas/Money'
        tax:
          $ref: '#/components/schemas/Money'
        total:
          $ref: '#/components/schemas/Money'
        amountPaid:
          $ref: '#/components/schemas/Money'
        amountRefunded:
          $ref: '#/components/schemas/Money'
        status:
          type: string
          enum:
            - DRAFT
            - PENDING
            - PAID
            - CANCELLED
        statusUpdatedAt:
          type: string
          format: date-time
        cancellationReason:
          type: string
          nullable: true
        cancelledBy:
          type: string
          nullable: true
        paymentMethod:
          type: string
          enum:
            - STRIPE
            - CASH
            - EXTERNAL
            - COMP
            - MIXED
            - LEGACY
        settledAt:
          type: string
          format: date-time
        amountComped:
          $ref: '#/components/schemas/Money'
        pricingRegion:
          type: object
          nullable: true
          properties:
            country:
              type: string
              nullable: true
            state:
              type: string
              nullable: true
            postalCode:
              type: string
              nullable: true
        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".
        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
        - orderId
        - clientId
        - currency
        - subtotal
        - tax
        - total
        - amountPaid
        - amountRefunded
        - status
        - statusUpdatedAt
        - 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
    Money:
      type: object
      properties:
        amount:
          type: integer
          minimum: 0
        currency:
          type: string
          minLength: 1
          maxLength: 3
      required:
        - amount
        - currency
  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.