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

# Bulk Update Transactions API

> Update the accounting fields of every Breezing transaction matching a filter in one background task, with no limit on the number of rows.



## OpenAPI

````yaml POST /transactions/bulk-update
openapi: 3.1.0
info:
  title: Breezing Public API
  version: 1.0.0
  description: >-
    Crypto accounting API for programmatic access and AI agents. Authenticate
    with an API key using the Authorization header: `Bearer brz_...`
servers:
  - url: https://api.breezing.io/v1
security:
  - BearerAuth: []
paths:
  /transactions/bulk-update:
    post:
      tags:
        - Transactions
      summary: Update every transaction matching a filter (background task)
      description: >-
        Filter-scoped twin of the id based endpoint: targets every transaction
        matching `filters` instead of an explicit id list, so it covers any
        number of rows. Runs in the background and returns `{ taskId, count }`;
        poll GET /tasks?id=<taskId>. Returns 409 TASK_IN_PROGRESS while the same
        kind of batch task is running for this company.


        Writes the given accounting fields verbatim to every matching UNLOCKED
        row (the dashboard select-all batch edit). Financial and ledger identity
        fields are not available here, because their sign and contact resolution
        depend on each row: use PATCH /transactions for those. skipNglReason is
        required when skipNgl is true. Writes to Breezing only: nothing reaches
        Xero, QuickBooks or Bexio until a sync runs.
      parameters:
        - schema:
            type: string
            description: >-
              Organization ID. Use GET /v1/companies to discover available
              org/company pairs.
            example: '1'
          required: true
          description: >-
            Organization ID. Use GET /v1/companies to discover available
            org/company pairs.
          name: orgId
          in: query
        - schema:
            type: string
            description: >-
              Company ID. Use GET /v1/companies to discover available companies
              and their access levels.
            example: '1'
          required: true
          description: >-
            Company ID. Use GET /v1/companies to discover available companies
            and their access levels.
          name: companyId
          in: query
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkUpdateBody'
      responses:
        '200':
          description: Background task created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      taskId:
                        type: number
                        description: >-
                          The background task. Poll GET /tasks?id=<taskId> until
                          it leaves "pending"/"progress"; a "done" task
                          disappears from that list.
                      count:
                        type: number
                        nullable: true
                        description: >-
                          Rows the task will process, as counted when it was
                          created.
                    required:
                      - taskId
                      - count
                required:
                  - success
                  - data
        '400':
          description: Invalid body
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                required:
                  - success
                  - error
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                required:
                  - success
                  - error
        '403':
          description: >-
            API key has no access to this company, has read-only access where
            write was required, or the company subscription is inactive
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                required:
                  - success
                  - error
        '409':
          description: >-
            The same kind of task is already running for this company
            (TASK_IN_PROGRESS)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                required:
                  - success
                  - error
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                required:
                  - success
                  - error
      security:
        - BearerAuth: []
components:
  schemas:
    BulkUpdateBody:
      type: object
      properties:
        filters:
          allOf:
            - $ref: '#/components/schemas/BulkTransactionFilters'
            - description: >-
                Which transactions the action targets. Same filters as GET
                /transactions. An empty object targets every transaction of the
                company (spam excluded by default). Lock state is not a filter
                here: update, lock and automatic repricing only ever touch
                unlocked rows, unlock only touches locked rows.
        updates:
          $ref: '#/components/schemas/BulkUpdateFields'
      required:
        - filters
        - updates
    BulkTransactionFilters:
      type: object
      properties:
        walletId:
          type: integer
          minimum: 0
          exclusiveMinimum: true
          description: Only transactions of this wallet. Use GET /wallets to find IDs.
        status:
          type: string
          enum:
            - notStarted
            - reviewRequired
            - reconciled
            - manuallyReconciled
            - paid
            - synced
          description: Only transactions in this status.
        account:
          type: string
          description: Only transactions with exactly this contra account code.
        hasAccount:
          type: boolean
          description: >-
            false = only transactions without a contra account (uncategorized),
            true = only categorized ones. Ignored when account is set.
        isSpam:
          type: string
          enum:
            - 'true'
            - 'false'
            - all
          default: 'false'
          description: >-
            Spam filter (default "false"). "all" includes spam rows, "true"
            targets only spam rows.
        dateFrom:
          type: integer
          minimum: 0
          exclusiveMinimum: true
          description: Start of the date window (unix seconds).
        dateTo:
          type: integer
          minimum: 0
          exclusiveMinimum: true
          description: >-
            End of the date window (unix seconds). Defaults to now when only
            dateFrom is set.
    BulkUpdateFields:
      type: object
      properties:
        account:
          type: string
          nullable: true
          description: >-
            Account code (numeric string). The contra (income/expense) account:
            what was this transaction for? (e.g. Sales, Legal Expense,
            Consulting Revenue). IMPORTANT: Always call company_get first to
            retrieve the chart of accounts, find the account by name, and use
            its "code" field. Never pass a free-text name like "sales".
        assetAccount:
          type: string
          nullable: true
          description: >-
            Asset account code (numeric string). The balance-sheet account for
            the token in this transaction. Required in ALL balance sheet modes.
            If the current value is "(auto)", Breezing resolves it at sync time
            from token-level or rule-based mappings. You can leave it or
            override with a specific code. IMPORTANT: Always call company_get
            first to retrieve the chart of accounts and use the numeric code.
        feeAssetAccount:
          type: string
          nullable: true
          description: >-
            Fee asset account code (numeric string). The balance-sheet account
            for the fee portion. Same rules as assetAccount: required in ALL
            balance sheet modes. If "(auto)", Breezing resolves it at sync time.
            IMPORTANT: Always call company_get first to retrieve the chart of
            accounts and use the numeric code.
        status:
          type: string
          enum:
            - notStarted
            - reviewRequired
            - reconciled
            - manuallyReconciled
            - paid
            - synced
          description: >-
            Transaction status lifecycle: notStarted (new/uncategorized) →
            reviewRequired (flagged for client review; client sees these in the
            Client Review workflow) → reconciled (categorized and verified) →
            manuallyReconciled (manually confirmed) → paid (synced to accounting
            software). Set to reviewRequired when the accountant needs the
            client to clarify a transaction.
        type:
          type: string
          nullable: true
          description: >-
            Transaction type as a freeform label, safe to overwrite. System may
            set values like "transaction" or "internal" during import, but these
            are just labels, not business logic. The isInternal boolean controls
            actual internal transfer logic. Set to any descriptive value:
            "Opening Balance", "Staking Reward", "Payment", etc.
        note:
          type: string
          nullable: true
          description: >-
            User note. Internal only, not synced to accounting software. Use
            accountingDescription for text that should appear in journal
            entries.
        accountingDescription:
          type: string
          nullable: true
          description: >-
            Description that syncs as the journal entry description in
            Xero/QuickBooks/Bexio. Use for invoice references, vendor names, or
            transaction context that should appear in the accounting software.
            Placeholders {{externalWalletName}}, {{externalWallet}} (the
            counterparty: walletTo on an out row, walletFrom otherwise),
            {{walletFromName}}, {{walletToName}}, {{walletFrom}}, {{walletTo}},
            {{token}}, {{amount}}, {{transactionId}} and {{date}} are filled
            when the journal is generated. Distinct from "note" which is
            internal only.
        vat:
          type: string
          nullable: true
          description: >-
            VAT or sales tax code as a freeform string stamped as the tax label
            on journal CSV exports. Prefer a tax rate NAME from the company's
            tax rate catalog (managed on the Invoices & Tax page) so reporting
            stays consistent (e.g. "VAT 8.1%"). Default is "no-vat". Not
            validated.
        isSpam:
          type: boolean
          description: >-
            Spam flag. Set true to hide airdrop/scam tokens from the main view
            and prevent syncing to accounting software. Breezing auto-detects
            many spam tokens; use this for any it missed.
        extraLabel:
          type: string
          nullable: true
          description: >-
            Extra label: freeform text for custom tagging or grouping, visible
            in Breezing reports.
        skipNgl:
          type: boolean
          description: >-
            Skip net gain/loss. When true, realized gain/loss is zeroed for this
            transaction (excluded from NGL and tax calculations). Use for
            non-taxable movements like wrapping, staking, or bridging. Requires
            skipNglReason when set to true. Cannot be set on internal transfers
            (isInternal=true). Setting this does NOT recalculate NGL
            automatically; run POST /ngl/calculate afterward to recompute net.
        skipNglReason:
          type: string
          nullable: true
          description: >-
            Reason net gain/loss is skipped (e.g. "Wrapping", "Staking", "Bridge
            transfer"). Required when skipNgl is set to true.
        qboClass:
          type: string
          nullable: true
          description: >-
            QuickBooks Online class ID. Syncs as the class on the journal entry
            in QuickBooks. Use the "id" returned by the QuickBooks classes
            refresh endpoint (call it first to retrieve valid class IDs). Only
            relevant when QuickBooks is linked.
        xeroTrackingCategory:
          type: string
          nullable: true
          description: >-
            Xero tracking category option ID. Syncs as the tracking category on
            the journal entry in Xero. Use the "id" returned by the Xero
            categories refresh endpoint (call it first to retrieve valid option
            IDs). Only relevant when Xero is linked.
      description: Values written to every matching row.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.