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

# Record a manual (cash/external/comp) transaction against an order

> Books money that moved outside Stripe — cash at the door, a bank transfer, a comped session. Card payments do not belong here: `source` accepts only CASH, EXTERNAL and COMP, and STRIPE is rejected, because Stripe rows are created by the payment-intent flow and settled by webhook. `kind: "REFUND"` is likewise rejected; refunds are not yet supported.

The two kinds behave differently and the difference is easy to miss. PAYMENT adds to the order's `amountPaid` in the same atomic write, so it changes what the order still owes. ADJUSTMENT records a ledger row and leaves `amountPaid` alone — use it for corrections you want visible in history without moving the balance. Either way the row is written SUCCEEDED immediately, with no pending state to poll.

`amount.currency` must equal the order's currency exactly or the call is a 400; the order's currency is fixed at creation and cannot be converted here. A 409 means the order changed between this call reading it and writing — re-read the order and retry, rather than assuming the payment was recorded. `clientId` defaults to the order's client.

`source: "COMP"` REQUIRES `reason` — a waived charge with no justification on the ledger is refused with a 400. Record why the charge was waived ("Service recovery — late supplier"), not that it was waived; the row already says that.

Send `idempotencyKey` on any recording you might retry. The same key on the same order returns the row the FIRST call created, as HTTP 200 with `replayed: true`, instead of recording the money a second time; a first recording is 201 with `replayed: false`. Branch on the status or on `replayed` — never on "a 2xx means I just took a payment". A key belongs to one order and does not expire.

The order settles as a consequence of this write, not through a separate call: once the ledger covers the order's total the order moves to `PAID` in the same atomic write, with `settledAt` and `paymentMethod` stamped on it. `PAID` cannot be asked for directly — `POST /orders/{orderId}/status` answers a `PAID` target with a 409.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/projects/{projectId}/orders/{orderId}/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}/orders/{orderId}/transactions:
    post:
      tags:
        - Transactions
      summary: Record a manual (cash/external/comp) transaction against an order
      description: >-
        Books money that moved outside Stripe — cash at the door, a bank
        transfer, a comped session. Card payments do not belong here: `source`
        accepts only CASH, EXTERNAL and COMP, and STRIPE is rejected, because
        Stripe rows are created by the payment-intent flow and settled by
        webhook. `kind: "REFUND"` is likewise rejected; refunds are not yet
        supported.


        The two kinds behave differently and the difference is easy to miss.
        PAYMENT adds to the order's `amountPaid` in the same atomic write, so it
        changes what the order still owes. ADJUSTMENT records a ledger row and
        leaves `amountPaid` alone — use it for corrections you want visible in
        history without moving the balance. Either way the row is written
        SUCCEEDED immediately, with no pending state to poll.


        `amount.currency` must equal the order's currency exactly or the call is
        a 400; the order's currency is fixed at creation and cannot be converted
        here. A 409 means the order changed between this call reading it and
        writing — re-read the order and retry, rather than assuming the payment
        was recorded. `clientId` defaults to the order's client.


        `source: "COMP"` REQUIRES `reason` — a waived charge with no
        justification on the ledger is refused with a 400. Record why the charge
        was waived ("Service recovery — late supplier"), not that it was waived;
        the row already says that.


        Send `idempotencyKey` on any recording you might retry. The same key on
        the same order returns the row the FIRST call created, as HTTP 200 with
        `replayed: true`, instead of recording the money a second time; a first
        recording is 201 with `replayed: false`. Branch on the status or on
        `replayed` — never on "a 2xx means I just took a payment". A key belongs
        to one order and does not expire.


        The order settles as a consequence of this write, not through a separate
        call: once the ledger covers the order's total the order moves to `PAID`
        in the same atomic write, with `settledAt` and `paymentMethod` stamped
        on it. `PAID` cannot be asked for directly — `POST
        /orders/{orderId}/status` answers a `PAID` target with a 409.
      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
            description: >-
              The order — the commercial record. Order items are drawn down into
              bookings.
            example: ord_01kv8m92p4jcrywn14znp8cym0
          required: true
          description: >-
            The order — the commercial record. Order items are drawn down into
            bookings.
          name: orderId
          in: path
      requestBody:
        description: Manual transaction data
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                kind:
                  type: string
                  enum:
                    - PAYMENT
                    - ADJUSTMENT
                source:
                  type: string
                  enum:
                    - CASH
                    - EXTERNAL
                    - COMP
                amount:
                  $ref: '#/components/schemas/Money'
                clientId:
                  type: string
                  minLength: 1
                note:
                  type: string
                  minLength: 1
                  maxLength: 500
                reason:
                  type: string
                  minLength: 1
                  maxLength: 500
                  description: Why the charge was waived. REQUIRED when source is COMP.
                  example: Service recovery — late supplier
                idempotencyKey:
                  type: string
                  minLength: 1
                  maxLength: 128
                  description: >-
                    Replay guard. The same key on the same order returns the row
                    the first call created instead of recording the money twice.
                  example: 9f8c0f7a-1f3f-4c8e-9a2b-6c7d8e9f0a1b
              required:
                - kind
                - source
                - amount
      responses:
        '200':
          description: Replay of an earlier idempotencyKey — the original row, unchanged
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    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
                  replayed:
                    type: boolean
                    enum:
                      - true
                required:
                  - data
                  - replayed
        '201':
          description: Transaction recorded
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    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
                  replayed:
                    type: boolean
                    enum:
                      - false
                required:
                  - data
                  - replayed
        '400':
          description: Validation error / currency mismatch / a COMP with no reason
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Order or client not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '409':
          description: >-
            Order modified concurrently (VERSION_CONFLICT), or a replay whose
            original row could not be read
            (TRANSACTION_IDEMPOTENCY_RECORD_MISSING — terminal, do not retry)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '422':
          description: >-
            A SUCCEEDED PAYMENT, or an ADJUSTMENT with source COMP, on a
            CANCELLED order (ORDER_NOT_PAYABLE). A REFUND, or any other
            ADJUSTMENT, is still recorded
          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.