> ## Documentation Index
> Fetch the complete documentation index at: https://developers.qomon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a transaction bundle

> Create a transaction bundle grouping one or more transactions with optional memberships and donations. The bundle is recorded in the space associated with the API key. At least one transaction is required.

**One API key = one space.** The bundle is recorded in the space of the API key you use. The payer contact can belong to a different space.

**Payer vs. beneficiary:** `contact_id` in `transactions` is the payer; `contact_id` in `memberships` or `donations` is the beneficiary. They can differ (Tiers Payant).

**Required before creating:** retrieve `payment_method_kinds` and `default_status_id` from `GET /v1/transaction_settings`; membership price IDs from `GET /v1/membership_prices`; donation price IDs from `GET /v1/donation_prices`.

**`external_transaction_id`** must be a plain integer — string suffixes are not supported.


## OpenAPI

````yaml /src/autogen/donation-membership-transaction-openapi3.0.yaml post /v1/transaction_bundles
openapi: 3.1.0
info:
  description: >-
    This OpenAPI 3.1 specification describes the public API of the Qomon
    platform. It is generated from the code and serves both as documentation for
    API consumers and as a contract for future development.
  title: Qomon API Reference
  version: 0.0.1
servers:
  - description: Production
    url: https://incoming.qomon.app
security:
  - bearerAuth: []
tags:
  - description: >-
      Create, read, update, and delete transaction bundles. A bundle is a single
      payment event grouping one or more transactions with optional donations
      and memberships.
    name: Transaction bundles
  - description: >-
      Read individual transactions (the payment legs of a bundle) with
      server-side filtering by date, amount, status, payment method and
      campaign, plus a contact's full transaction history.
    name: Transactions
  - description: >-
      List donations directly, filtered by donation date, contact, price or
      amount — without fetching whole bundles.
    name: Donations
  - description: >-
      List memberships directly, filtered by start/end/creation date, contact,
      price or amount.
    name: Memberships
  - description: >-
      Read-only configuration resources: transaction settings, statuses,
      donation and membership prices, and code campaigns.
    name: Settings and configuration
paths:
  /v1/transaction_bundles:
    post:
      tags:
        - Transaction bundles
      summary: Create a transaction bundle
      description: >-
        Create a transaction bundle grouping one or more transactions with
        optional memberships and donations. The bundle is recorded in the space
        associated with the API key. At least one transaction is required.
      operationId: create-transaction-bundle
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataEnvelopeTransactionBundle'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusEnvelopeTransactionBundle'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
components:
  schemas:
    DataEnvelopeTransactionBundle:
      additionalProperties: true
      properties:
        data:
          $ref: '#/components/schemas/TransactionBundle'
      required:
        - data
      type: object
    StatusEnvelopeTransactionBundle:
      additionalProperties: true
      properties:
        data:
          $ref: '#/components/schemas/TransactionBundle'
        status:
          description: Operation result.
          examples:
            - success
          type: string
      required:
        - status
        - data
      type: object
    ErrorModel:
      additionalProperties: true
      properties:
        detail:
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
          examples:
            - Property foo is required but is missing.
          type: string
        errors:
          description: Optional list of individual error details
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type:
            - array
            - 'null'
        instance:
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem.
          examples:
            - https://example.com/error-log/abc123
          format: uri
          type: string
        status:
          description: HTTP status code
          examples:
            - 400
          format: int64
          type: integer
        title:
          description: >-
            A short, human-readable summary of the problem type. This value
            should not change between occurrences of the error.
          examples:
            - Bad Request
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          examples:
            - https://example.com/errors/example
          format: uri
          type: string
      type: object
    TransactionBundle:
      additionalProperties: true
      properties:
        CreatedAt:
          description: Creation timestamp.
          format: date-time
          type: string
        UpdatedAt:
          description: Last update timestamp.
          format: date-time
          type: string
        donations:
          description: >-
            Array of donations in the bundle. Optional - only include if the
            bundle contains donations.
          items:
            $ref: '#/components/schemas/Donation'
          type:
            - array
            - 'null'
        group_id:
          description: ID of the group (espace) the transaction bundle belongs to.
          format: int64
          minimum: 0
          readOnly: true
          type: integer
        id:
          description: Unique identifier.
          format: int64
          minimum: 0
          type: integer
        memberships:
          description: >-
            Array of memberships in the bundle. Optional - only include if the
            bundle contains memberships.
          items:
            $ref: '#/components/schemas/Membership'
          type:
            - array
            - 'null'
        summary:
          additionalProperties: {}
          description: Summary object (read-only, automatically calculated).
          type: object
        transactions:
          description: >-
            Array of transactions in the bundle. At least one transaction is
            typically required.
          items:
            $ref: '#/components/schemas/Transaction'
          type:
            - array
            - 'null'
      type: object
    ErrorDetail:
      additionalProperties: true
      properties:
        location:
          description: >-
            Where the error occurred, e.g. 'body.items[3].tags' or
            'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
    Donation:
      additionalProperties: true
      properties:
        CreatedAt:
          description: Creation timestamp.
          format: date-time
          type: string
        UpdatedAt:
          description: Last update timestamp.
          format: date-time
          type: string
        affectation:
          description: Optional affectation code.
          type: string
        amount:
          default: 0
          description: Amount in cents.
          examples:
            - 2500
          format: int64
          minimum: 0
          type: integer
        amount_initial:
          description: Initial amount in cents.
          examples:
            - 2500
          format: int64
          minimum: 0
          type: integer
        comment:
          description: Optional comment.
          type: string
        contact:
          $ref: '#/components/schemas/ContactForTransaction'
          description: Associated contact.
        contact_id:
          description: Contact ID - required for donations.
          format: int64
          minimum: 0
          type: integer
        currency:
          description: Currency code.
          examples:
            - eur
          type: string
        date:
          description: Donation date (ISO 8601 format).
          format: date-time
          type: string
        donation_price_id:
          description: Donation price ID (must exist in group's donation prices).
          format: int64
          minimum: 0
          type: integer
        id:
          description: Donation ID (for updates, omit for new donations).
          format: int64
          minimum: 0
          type: integer
      required:
        - amount
        - date
        - contact_id
      type: object
    Membership:
      additionalProperties: true
      properties:
        CreatedAt:
          description: Creation timestamp.
          format: date-time
          type: string
        UpdatedAt:
          description: Last update timestamp.
          format: date-time
          type: string
        amount:
          default: 0
          description: Amount in cents.
          examples:
            - 3000
          format: int64
          minimum: 0
          type: integer
        amount_initial:
          description: Initial amount in cents.
          examples:
            - 3000
          format: int64
          minimum: 0
          type: integer
        comment:
          description: Optional comment.
          type: string
        contact:
          $ref: '#/components/schemas/ContactForTransaction'
          description: Associated contact.
        contact_id:
          description: Contact ID - required for memberships.
          format: int64
          minimum: 0
          type: integer
        currency:
          description: Currency code.
          examples:
            - eur
          type: string
        end_date:
          description: Membership end date (ISO 8601 format).
          format: date-time
          type: string
        id:
          description: Membership ID (for updates, omit for new memberships).
          format: int64
          minimum: 0
          type: integer
        membership_price_id:
          description: Membership price ID (must exist in group's membership prices).
          format: int64
          minimum: 0
          type: integer
        rolling_year:
          description: Optional rolling year.
          type: boolean
        start_date:
          description: Membership start date (ISO 8601 format).
          format: date-time
          type: string
      required:
        - amount
        - contact_id
      type: object
    Transaction:
      additionalProperties: true
      properties:
        CreatedAt:
          description: Creation timestamp.
          format: date-time
          type: string
        UpdatedAt:
          description: Last update timestamp.
          format: date-time
          type: string
        amount:
          default: 0
          description: Amount in cents.
          examples:
            - 5000
          format: int64
          minimum: 0
          type: integer
        code_campaign:
          description: Optional campaign code (must exist in group's campaigns).
          type: string
        comment:
          description: Optional comment.
          type: string
        comment_date:
          description: Optional comment date.
          format: date-time
          type: string
        contact_id:
          description: Contact ID - required for transactions.
          format: int64
          minimum: 0
          type: integer
        currency:
          description: Currency code.
          examples:
            - eur
          type: string
        date:
          description: Transaction date (ISO 8601 format).
          format: date-time
          type:
            - string
            - 'null'
        delivered_at:
          description: Optional delivery date.
          format: date-time
          type: string
        delivery_token:
          description: Optional delivery token.
          type: string
        external_transaction_id:
          description: Optional external transaction ID.
          format: int64
          minimum: 0
          type: integer
        group_id:
          description: ID of the group (espace) the transaction belongs to.
          format: int64
          minimum: 0
          readOnly: true
          type: integer
        id:
          description: Transaction ID (for updates, omit for new transactions).
          format: int64
          minimum: 0
          type: integer
        payment_method:
          additionalProperties: {}
          description: Additional payment method details (JSON object).
          type: object
        payment_method_kind:
          description: >-
            Payment method type (e.g., 'card', 'check', 'cash', 'transfer').
            Must match allowed payment methods for the group.
          type: string
        reimbursed_amount:
          description: Reimbursed amount in cents.
          format: int64
          minimum: 0
          type: integer
        status_id:
          description: >-
            Transaction status identifier. Use an ID from GET
            /v1/transaction_statuses, or default_status_id from GET
            /v1/transaction_settings.
          format: int64
          minimum: 0
          type: integer
        transaction_bundle_id:
          description: Bundle identifier.
          format: int64
          minimum: 0
          type: integer
        unpaid_amount:
          description: Unpaid amount in cents.
          format: int64
          minimum: 0
          type: integer
      required:
        - contact_id
        - date
        - amount
      type: object
    ContactForTransaction:
      additionalProperties: true
      properties:
        firstname:
          description: Contact first name.
          type: string
        group_id:
          description: ID of the group the contact belongs to.
          format: int64
          minimum: 0
          readOnly: true
          type: integer
        id:
          description: Unique identifier.
          format: int64
          minimum: 0
          type: integer
        membership_code:
          description: Membership code.
          type: string
        membership_number:
          description: Membership number.
          format: int64
          minimum: 0
          type: integer
        surname:
          description: Contact surname.
          type: string
      required:
        - id
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: opaque
      description: >-
        OAuth2 access token. Pass the token in the Authorization header as
        `Bearer <token>`. The token is looked up in Redis to resolve the caller
        identity.
      scheme: bearer
      type: http

````