---
title: "documents.bulk-edit"
method: POST
path: "/capabilities/documents.bulk-edit"
tags: ["Capabilities"]
---

# documents.bulk-edit

`POST /capabilities/documents.bulk-edit`

Bulk edit documents. Supports dry-run preview (default) and execute modes. Preview returns matching documents with proposed changes and available merchants/categories for context.

## Request body

- object
  - `documentIds` string[] — Exact document IDs to edit. Use this for deterministic single-document or hand-picked multi-document edits.
  - `query` string — Search query to find documents (optional)
  - `merchant` string — Specific merchant to filter for editing
  - `category` string — Specific category to filter for editing
  - `where` object — Typed filter clause for targeted bulk edits. Allowed fields: id, amount, docDate, merchant, category, docType, invoiceId, receiptId, preferredCurrency, currency, paymentStatus, paymentMethod, paymentMethodEnding, fromEmail, toEmail, summary, expenseLocation.primary.countryCode, expenseLocation.primary.country, expenseLocation.primary.city, expenseLocation.primary.stateOrProvince, expenseLocation.primary.kind, taxAmount, subtotal, isRecurring, recurringType, entityId. Allowed ops: eq, ne, gt, gte, lt, lte, in, nin, regex, exists.
    - `logic` 'and' | 'or'
    - `conditions` object[], required
      - `field` 'id' | 'amount' | 'docDate' | 'merchant' | 'category' | 'docType' | 'invoiceId' | 'receiptId' | 'preferredCurrency' | 'currency' | 'paymentStatus' | 'paymentMethod' | 'paymentMethodEnding' | 'fromEmail' | 'toEmail' | 'summary' | 'expenseLocation.primary.countryCode' | 'expenseLocation.primary.country' | 'expenseLocation.primary.city' | 'expenseLocation.primary.stateOrProvince' | 'expenseLocation.primary.kind' | 'taxAmount' | 'subtotal' | 'isRecurring' | 'recurringType' | 'entityId', required
      - `op` 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'regex' | 'exists', required
      - `value` unknown
  - `changes` object, required — Changes to apply to matching documents
    - `merchant` string — New vendor/supplier/merchant name to apply. Not for 'Billed to'.
    - `category` string — New category to apply
    - `entityId` union — Business entity ID to assign to matching documents. Use null to clear it.
      - string
      - 'null', nullable
    - `paymentStatus` 'paid' | 'unpaid' | 'partial' | 'refunded' | 'unknown' — New payment status to apply
    - `labels` string[] — Replace labels with this exact set
    - `shouldClearLabels` boolean — If true, remove all labels from matching documents
  - `dryRun` boolean — If true, shows preview without making changes. If false, executes the bulk edit.

## Response `200`

Successful response

- object
  - `success` boolean
  - `code` integer
  - `data` object
    - `result` object — Capability-specific result

## Other responses

- `400` — Invalid input
- `401` — Authentication required
- `404` — Resource not found

---

[API](https://skmtc.net/receiptor/apis/receiptor-ai-api.md) · [All operations](https://skmtc.net/receiptor/apis/receiptor-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/receiptor/receiptor-ai-api/versions/da17f0eb65a2/schema)