> ## 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 transactions (filter by order, client, or status)

> The money ledger for the project, newest first, for reconciliation and payment history.

The filters are not combinable, and this is the mistake to avoid: exactly one of `orderId`, `clientId` and `status` takes effect, in that order of precedence, and the others are ignored without an error. Sending `orderId` with `status=FAILED` returns EVERY transaction on that order, failed or not — so filter by status client-side when you also need one of the others. With none of the three set, the whole project is listed. `startDate` and `endDate` are the exception: they narrow whichever of the four queries runs.

Results are paginated with an opaque cursor that is only valid for the same filters that produced it. Both settled and unsettled rows come back, so sum only `status: "SUCCEEDED"` when computing what was actually collected — a PENDING Stripe row is an intent, not money.

The ledger is append-only, so a correction is always a NEW row pointing at the one it corrects through `relatedTransactionId`, never an edit. Amounts are always positive; the `kind` carries the direction. A `REFUND` offsets a `PAYMENT`, and a `CREDIT_REVERSAL` offsets the `CREDIT_REDEMPTION` of a package session that was cancelled and returned to its package — so package credit actually used is redemptions minus reversals. Neither credit kind is money: both have `source: "PACKAGE_CREDIT"`. A consumer switching exhaustively on `kind` should tolerate values it does not know.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/projects/{projectId}/transactions
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}/transactions:
    get:
      tags:
        - Transactions
      summary: List transactions (filter by order, client, or status)
      description: >-
        The money ledger for the project, newest first, for reconciliation and
        payment history.


        The filters are not combinable, and this is the mistake to avoid:
        exactly one of `orderId`, `clientId` and `status` takes effect, in that
        order of precedence, and the others are ignored without an error.
        Sending `orderId` with `status=FAILED` returns EVERY transaction on that
        order, failed or not — so filter by status client-side when you also
        need one of the others. With none of the three set, the whole project is
        listed. `startDate` and `endDate` are the exception: they narrow
        whichever of the four queries runs.


        Results are paginated with an opaque cursor that is only valid for the
        same filters that produced it. Both settled and unsettled rows come
        back, so sum only `status: "SUCCEEDED"` when computing what was actually
        collected — a PENDING Stripe row is an intent, not money.


        The ledger is append-only, so a correction is always a NEW row pointing
        at the one it corrects through `relatedTransactionId`, never an edit.
        Amounts are always positive; the `kind` carries the direction. A
        `REFUND` offsets a `PAYMENT`, and a `CREDIT_REVERSAL` offsets the
        `CREDIT_REDEMPTION` of a package session that was cancelled and returned
        to its package — so package credit actually used is redemptions minus
        reversals. Neither credit kind is money: both have `source:
        "PACKAGE_CREDIT"`. A consumer switching exhaustively on `kind` should
        tolerate values it does not know.
      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
          required: false
          name: orderId
          in: query
        - schema:
            type: string
            minLength: 1
          required: false
          name: clientId
          in: query
        - schema:
            type: string
            enum:
              - PENDING
              - SUCCEEDED
              - FAILED
              - CANCELED
          required: false
          name: status
          in: query
        - schema:
            type: string
            format: date-time
          required: false
          name: startDate
          in: query
        - schema:
            type: string
            format: date-time
          required: false
          name: endDate
          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: Transactions
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        projectId:
                          type: string
                        tenantId:
                          type: string
                        transactionId:
                          type: string
                        kind:
                          type: string
                          enum:
                            - PAYMENT
                            - REFUND
                            - CREDIT_REDEMPTION
                            - ADJUSTMENT
                            - CREDIT_REVERSAL
                        source:
                          type: string
                          enum:
                            - STRIPE
                            - CASH
                            - EXTERNAL
                            - PACKAGE_CREDIT
                            - COMP
                        status:
                          type: string
                          enum:
                            - PENDING
                            - SUCCEEDED
                            - FAILED
                            - CANCELED
                        amount:
                          $ref: '#/components/schemas/Money'
                        platformFee:
                          allOf:
                            - $ref: '#/components/schemas/Money'
                            - nullable: true
                        relatedTransactionId:
                          type: string
                          nullable: true
                        orderId:
                          type: string
                        orderItemId:
                          type: string
                          nullable: true
                        allocationId:
                          type: string
                          nullable: true
                        bookingId:
                          type: string
                          nullable: true
                        clientId:
                          type: string
                          nullable: true
                        stripePaymentIntentId:
                          type: string
                          nullable: true
                        stripeChargeId:
                          type: string
                          nullable: true
                        stripeRefundId:
                          type: string
                          nullable: true
                        stripeAccountId:
                          type: string
                          nullable: true
                        connectChargeType:
                          type: string
                          nullable: true
                          enum:
                            - DIRECT
                        failureCode:
                          type: string
                          nullable: true
                        failureMessage:
                          type: string
                          nullable: true
                        note:
                          type: string
                          nullable: true
                        disputeId:
                          type: string
                          nullable: true
                          description: >-
                            The Stripe dispute (chargeback) id, when the client
                            disputed this card payment with their bank. Set by
                            MarketBox from Stripe's events, never by a request.
                            The transaction's `status` stays SUCCEEDED while it
                            is disputed.
                        disputeStatus:
                          type: string
                          nullable: true
                          enum:
                            - needs_response
                            - under_review
                            - won
                            - lost
                            - null
                          description: >-
                            Where the dispute stands: `needs_response` (evidence
                            is due in Stripe), `under_review` (the bank is
                            deciding), `won` (the money stays), or `lost` (the
                            money was taken back). Null or absent when the
                            payment was never disputed. An inquiry that closes
                            without a chargeback reads `won`. Respond to a
                            dispute in Stripe: the API cannot.
                        channel:
                          type: string
                          enum:
                            - BACKOFFICE
                            - OPEN_API
                            - STRIPE_WEBHOOK
                            - SCHEDULER
                            - ORDER_CASCADE
                            - MIGRATION
                        reason:
                          type: string
                          nullable: true
                        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
                        - transactionId
                        - kind
                        - source
                        - status
                        - amount
                        - orderId
                        - deleted
                        - version
                        - createdAt
                        - updatedAt
                        - createdBy
                        - updatedBy
                  nextCursor:
                    type: string
                    nullable: true
                required:
                  - data
                  - nextCursor
        '400':
          description: Invalid query/cursor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
components:
  schemas:
    Money:
      type: object
      properties:
        amount:
          type: integer
          minimum: 0
        currency:
          type: string
          minLength: 1
          maxLength: 3
      required:
        - amount
        - currency
    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.