# Run several operations in one round trip
Source: https://www.desktopaccountingapi.com/docs/api/reference/operations/qbdbatch/

`POST https://api.desktopaccountingapi.com/v1/quickbooks-desktop/batch`

Operation ID: `qbd.batch`. Tag: Batch.

Runs up to 25 typed QuickBooks Desktop operations together: they go to QuickBooks as one qbXML message set in one Web Connector round trip, in order, and the response holds one typed result per member. Each member is validated exactly like its own endpoint before anything is queued; an invalid member fails the whole call with `400` and `param` naming it (for example `requests[2].body.name`).

With `onError: stopOnError` (the default) QuickBooks skips every member after the first failure (`not_processed`); with `continueOnError` every member runs. A list member runs as one query of at most `limit` records (`cursor` is not accepted). A read-only key may batch reads only.

Writes: send one `Idempotency-Key` for the whole batch. If the response from QuickBooks is lost, the call fails with `QBD_WRITE_OUTCOME_UNKNOWN` and `details.members` lists every member: each write member is `unknown` (never resend it blindly), and a read member never proves that a write applied. Billing counts the batch like the same requests sent one by one. See [Batch requests](https://www.desktopaccountingapi.com/docs/guides/batch/).

Authentication: `Authorization: Bearer <secret key>`.

Example request:

```sh
curl -X POST https://api.desktopaccountingapi.com/v1/quickbooks-desktop/batch \
  -H "Authorization: Bearer $DAAPI_SECRET_KEY" \
  -H "Daapi-End-User-Id: $DAAPI_END_USER_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"onError":"continueOnError","requests":[{"operationId":"qbd.customers.create","body":{"name":"Acme Supply"}},{"operationId":"qbd.invoices.list","query":{"limit":10}},{"operationId":"qbd.invoices.retrieve","pathParams":{"id":"80000001-1234567890"}}]}'
```

## Headers

- `Daapi-End-User-Id` (string, required): The end user whose QuickBooks company file this request uses. `Conductor-End-User-Id` is accepted as an alias. example `eu_01j9x4m6v4c8k2t7q0r5s3w1zb`.
- `Daapi-Timeout-Seconds` (integer): How long to wait for QuickBooks, in seconds (1–300). `Conductor-Timeout-Seconds` is accepted as an alias. Default 90, or 60 for the health check. If the request has not been sent by then it is canceled (`504 REQUEST_TIMEOUT_NOT_SENT`); if it was sent it keeps running (`504 QBD_REQUEST_TIMEOUT`). 1 to 300; example `90`.
- `Prefer` (string): Send `respond-async` to get `202 Accepted` with a request resource immediately instead of waiting for QuickBooks. always `"respond-async"`; example `respond-async`.
- `Daapi-Queue-Ttl-Seconds` (integer): Async only: the latest time, in seconds from now (10 to 86400), the request may still be sent to QuickBooks. Default 3600. 10 to 86400; example `3600`.
- `Idempotency-Key` (string): Makes a write safe to retry. Repeating a key with the same request attaches to or replays the original instead of creating a second one. 1–255 printable ASCII characters, retained 7 days. Reusing a key with a different request returns `422 IDEMPOTENCY_KEY_REUSED`. 1–255 characters; example `6f1c2a0e-1f7e-4c55-9a7a-0b2d2c9e3a10`.

## Request body (application/json, required)

- `onError` (string): `stopOnError` (default): when a member fails, QuickBooks skips every later member (`not_processed`). `continueOnError`: every member runs regardless of earlier failures. one of `stopOnError`, `continueOnError`; example `stopOnError`.
- `requests` (array of object, required): The members, 1 to 25, run in this order in one QuickBooks message set. 1–25 items.
  - `operationId` (string, required): The typed QuickBooks Desktop operation this member runs. one of `qbd.accountTaxLines.list`, `qbd.accounts.create`, `qbd.accounts.delete`, `qbd.accounts.list`, `qbd.accounts.merge`, `qbd.accounts.retrieve`, `qbd.accounts.setCustomField`, `qbd.accounts.update`, `qbd.billCheckPayments.create`, `qbd.billCheckPayments.delete`, `qbd.billCheckPayments.list`, `qbd.billCheckPayments.retrieve`, `qbd.billCheckPayments.setCustomField`, `qbd.billCheckPayments.update`, `qbd.billCheckPayments.void`, `qbd.billCreditCardPayments.create`, `qbd.billCreditCardPayments.delete`, `qbd.billCreditCardPayments.list`, `qbd.billCreditCardPayments.retrieve`, `qbd.billCreditCardPayments.setCustomField`, `qbd.billCreditCardPayments.void`, `qbd.billingRates.create`, `qbd.billingRates.delete`, `qbd.billingRates.list`, `qbd.billingRates.retrieve`, `qbd.bills.create`, `qbd.bills.delete`, `qbd.bills.list`, `qbd.bills.retrieve`, `qbd.bills.setCustomField`, `qbd.bills.update`, `qbd.bills.void`, `qbd.billsToPay.list`, `qbd.buildAssemblies.create`, `qbd.buildAssemblies.delete`, `qbd.buildAssemblies.list`, `qbd.buildAssemblies.retrieve`, `qbd.buildAssemblies.setCustomField`, `qbd.buildAssemblies.update`, `qbd.checks.create`, `qbd.checks.delete`, `qbd.checks.list`, `qbd.checks.retrieve`, `qbd.checks.setCustomField`, `qbd.checks.update`, `qbd.checks.void`, `qbd.classes.create`, `qbd.classes.delete`, `qbd.classes.list`, `qbd.classes.merge`, `qbd.classes.retrieve`, `qbd.classes.update`, `qbd.company.retrieve`, `qbd.creditCardCharges.create`, `qbd.creditCardCharges.delete`, `qbd.creditCardCharges.list`, `qbd.creditCardCharges.retrieve`, `qbd.creditCardCharges.setCustomField`, `qbd.creditCardCharges.update`, `qbd.creditCardCharges.void`, `qbd.creditCardCredits.create`, `qbd.creditCardCredits.delete`, `qbd.creditCardCredits.list`, `qbd.creditCardCredits.retrieve`, `qbd.creditCardCredits.setCustomField`, `qbd.creditCardCredits.update`, `qbd.creditCardCredits.void`, `qbd.creditCardRefunds.create`, `qbd.creditCardRefunds.delete`, `qbd.creditCardRefunds.list`, `qbd.creditCardRefunds.retrieve`, `qbd.creditCardRefunds.setCustomField`, `qbd.creditCardRefunds.void`, `qbd.creditMemos.create`, `qbd.creditMemos.delete`, `qbd.creditMemos.list`, `qbd.creditMemos.retrieve`, `qbd.creditMemos.setCustomField`, `qbd.creditMemos.update`, `qbd.creditMemos.void`, `qbd.currencies.create`, `qbd.currencies.delete`, `qbd.currencies.list`, `qbd.currencies.retrieve`, `qbd.currencies.update`, `qbd.customFieldDefinitions.create`, `qbd.customFieldDefinitions.delete`, `qbd.customFieldDefinitions.list`, `qbd.customFieldDefinitions.update`, `qbd.customerMessages.create`, `qbd.customerMessages.delete`, `qbd.customerMessages.list`, `qbd.customerMessages.retrieve`, `qbd.customerTypes.create`, `qbd.customerTypes.delete`, `qbd.customerTypes.list`, `qbd.customerTypes.retrieve`, `qbd.customers.create`, `qbd.customers.delete`, `qbd.customers.list`, `qbd.customers.merge`, `qbd.customers.retrieve`, `qbd.customers.setCustomField`, `qbd.customers.update`, `qbd.dateDrivenTerms.create`, `qbd.dateDrivenTerms.delete`, `qbd.dateDrivenTerms.list`, `qbd.dateDrivenTerms.retrieve`, `qbd.deletedListObjects.list`, `qbd.deletedTransactions.list`, `qbd.deposits.create`, `qbd.deposits.delete`, `qbd.deposits.list`, `qbd.deposits.retrieve`, `qbd.deposits.setCustomField`, `qbd.deposits.update`, `qbd.deposits.void`, `qbd.discountItems.create`, `qbd.discountItems.delete`, `qbd.discountItems.list`, `qbd.discountItems.merge`, `qbd.discountItems.retrieve`, `qbd.discountItems.setCustomField`, `qbd.discountItems.update`, `qbd.employees.create`, `qbd.employees.delete`, `qbd.employees.list`, `qbd.employees.retrieve`, `qbd.employees.setCustomField`, `qbd.employees.update`, `qbd.entities.list`, `qbd.entities.retrieve`, `qbd.estimates.create`, `qbd.estimates.delete`, `qbd.estimates.list`, `qbd.estimates.retrieve`, `qbd.estimates.setCustomField`, `qbd.estimates.update`, `qbd.fixedAssetItems.create`, `qbd.fixedAssetItems.delete`, `qbd.fixedAssetItems.list`, `qbd.fixedAssetItems.retrieve`, `qbd.fixedAssetItems.setCustomField`, `qbd.fixedAssetItems.update`, `qbd.inventoryAdjustments.create`, `qbd.inventoryAdjustments.delete`, `qbd.inventoryAdjustments.list`, `qbd.inventoryAdjustments.retrieve`, `qbd.inventoryAdjustments.setCustomField`, `qbd.inventoryAdjustments.update`, `qbd.inventoryAdjustments.void`, `qbd.inventoryAssemblyItems.canBuild`, `qbd.inventoryAssemblyItems.create`, `qbd.inventoryAssemblyItems.delete`, `qbd.inventoryAssemblyItems.list`, `qbd.inventoryAssemblyItems.retrieve`, `qbd.inventoryAssemblyItems.setCustomField`, `qbd.inventoryAssemblyItems.update`, `qbd.inventoryItems.create`, `qbd.inventoryItems.delete`, `qbd.inventoryItems.list`, `qbd.inventoryItems.merge`, `qbd.inventoryItems.retrieve`, `qbd.inventoryItems.setCustomField`, `qbd.inventoryItems.update`, `qbd.inventorySites.create`, `qbd.inventorySites.delete`, `qbd.inventorySites.list`, `qbd.inventorySites.retrieve`, `qbd.inventorySites.update`, `qbd.inventoryTransfers.create`, `qbd.inventoryTransfers.delete`, `qbd.inventoryTransfers.list`, `qbd.inventoryTransfers.retrieve`, `qbd.inventoryTransfers.update`, `qbd.invoices.create`, `qbd.invoices.delete`, `qbd.invoices.list`, `qbd.invoices.retrieve`, `qbd.invoices.setCustomField`, `qbd.invoices.update`, `qbd.invoices.void`, `qbd.itemGroups.create`, `qbd.itemGroups.delete`, `qbd.itemGroups.list`, `qbd.itemGroups.merge`, `qbd.itemGroups.retrieve`, `qbd.itemGroups.setCustomField`, `qbd.itemGroups.update`, `qbd.itemReceipts.create`, `qbd.itemReceipts.delete`, `qbd.itemReceipts.list`, `qbd.itemReceipts.retrieve`, `qbd.itemReceipts.setCustomField`, `qbd.itemReceipts.update`, `qbd.itemReceipts.void`, `qbd.itemSites.list`, `qbd.itemSites.retrieve`, `qbd.items.list`, `qbd.items.retrieve`, `qbd.jobTypes.create`, `qbd.jobTypes.delete`, `qbd.jobTypes.list`, `qbd.jobTypes.retrieve`, `qbd.journalEntries.create`, `qbd.journalEntries.delete`, `qbd.journalEntries.list`, `qbd.journalEntries.retrieve`, `qbd.journalEntries.setCustomField`, `qbd.journalEntries.update`, `qbd.journalEntries.void`, `qbd.leads.create`, `qbd.leads.list`, `qbd.leads.retrieve`, `qbd.leads.update`, `qbd.nonInventoryItems.create`, `qbd.nonInventoryItems.delete`, `qbd.nonInventoryItems.list`, `qbd.nonInventoryItems.merge`, `qbd.nonInventoryItems.retrieve`, `qbd.nonInventoryItems.setCustomField`, `qbd.nonInventoryItems.update`, `qbd.otherChargeItems.create`, `qbd.otherChargeItems.delete`, `qbd.otherChargeItems.list`, `qbd.otherChargeItems.merge`, `qbd.otherChargeItems.retrieve`, `qbd.otherChargeItems.setCustomField`, `qbd.otherChargeItems.update`, `qbd.otherNames.create`, `qbd.otherNames.delete`, `qbd.otherNames.list`, `qbd.otherNames.retrieve`, `qbd.otherNames.setCustomField`, `qbd.otherNames.update`, `qbd.paymentItems.create`, `qbd.paymentItems.delete`, `qbd.paymentItems.list`, `qbd.paymentItems.merge`, `qbd.paymentItems.retrieve`, `qbd.paymentItems.setCustomField`, `qbd.paymentItems.update`, `qbd.paymentMethods.create`, `qbd.paymentMethods.delete`, `qbd.paymentMethods.list`, `qbd.paymentMethods.retrieve`, `qbd.paymentsToDeposit.list`, `qbd.payrollNonWageItems.delete`, `qbd.payrollNonWageItems.list`, `qbd.payrollNonWageItems.retrieve`, `qbd.payrollWageItems.create`, `qbd.payrollWageItems.delete`, `qbd.payrollWageItems.list`, `qbd.payrollWageItems.retrieve`, `qbd.payrollWageItems.update`, `qbd.preferences.retrieve`, `qbd.priceLevels.create`, `qbd.priceLevels.delete`, `qbd.priceLevels.list`, `qbd.priceLevels.retrieve`, `qbd.priceLevels.update`, `qbd.purchaseOrders.create`, `qbd.purchaseOrders.delete`, `qbd.purchaseOrders.list`, `qbd.purchaseOrders.retrieve`, `qbd.purchaseOrders.setCustomField`, `qbd.purchaseOrders.update`, `qbd.receivePayments.create`, `qbd.receivePayments.delete`, `qbd.receivePayments.list`, `qbd.receivePayments.retrieve`, `qbd.receivePayments.setCustomField`, `qbd.receivePayments.update`, `qbd.reports.aging`, `qbd.reports.budgetSummary`, `qbd.reports.customDetail`, `qbd.reports.customSummary`, `qbd.reports.generalDetail`, `qbd.reports.generalSummary`, `qbd.reports.job`, `qbd.reports.payrollDetail`, `qbd.reports.payrollSummary`, `qbd.reports.time`, `qbd.salesOrders.create`, `qbd.salesOrders.delete`, `qbd.salesOrders.list`, `qbd.salesOrders.retrieve`, `qbd.salesOrders.setCustomField`, `qbd.salesOrders.update`, `qbd.salesReceipts.create`, `qbd.salesReceipts.delete`, `qbd.salesReceipts.list`, `qbd.salesReceipts.retrieve`, `qbd.salesReceipts.setCustomField`, `qbd.salesReceipts.update`, `qbd.salesReceipts.void`, `qbd.salesRepresentatives.create`, `qbd.salesRepresentatives.delete`, `qbd.salesRepresentatives.list`, `qbd.salesRepresentatives.retrieve`, `qbd.salesRepresentatives.update`, `qbd.salesTaxCodes.create`, `qbd.salesTaxCodes.delete`, `qbd.salesTaxCodes.list`, `qbd.salesTaxCodes.retrieve`, `qbd.salesTaxCodes.update`, `qbd.salesTaxGroupItems.create`, `qbd.salesTaxGroupItems.delete`, `qbd.salesTaxGroupItems.list`, `qbd.salesTaxGroupItems.merge`, `qbd.salesTaxGroupItems.retrieve`, `qbd.salesTaxGroupItems.setCustomField`, `qbd.salesTaxGroupItems.update`, `qbd.salesTaxItems.create`, `qbd.salesTaxItems.delete`, `qbd.salesTaxItems.list`, `qbd.salesTaxItems.merge`, `qbd.salesTaxItems.retrieve`, `qbd.salesTaxItems.setCustomField`, `qbd.salesTaxItems.update`, `qbd.salesTaxPaymentChecks.create`, `qbd.salesTaxPaymentChecks.delete`, `qbd.salesTaxPaymentChecks.list`, `qbd.salesTaxPaymentChecks.retrieve`, `qbd.salesTaxPaymentChecks.setCustomField`, `qbd.salesTaxPaymentChecks.update`, `qbd.serviceItems.create`, `qbd.serviceItems.delete`, `qbd.serviceItems.list`, `qbd.serviceItems.merge`, `qbd.serviceItems.retrieve`, `qbd.serviceItems.setCustomField`, `qbd.serviceItems.update`, `qbd.shippingMethods.create`, `qbd.shippingMethods.delete`, `qbd.shippingMethods.list`, `qbd.shippingMethods.retrieve`, `qbd.standardTerms.create`, `qbd.standardTerms.delete`, `qbd.standardTerms.list`, `qbd.standardTerms.retrieve`, `qbd.statementCharges.create`, `qbd.statementCharges.delete`, `qbd.statementCharges.list`, `qbd.statementCharges.retrieve`, `qbd.statementCharges.setCustomField`, `qbd.statementCharges.update`, `qbd.statementCharges.void`, `qbd.subtotalItems.create`, `qbd.subtotalItems.delete`, `qbd.subtotalItems.list`, `qbd.subtotalItems.merge`, `qbd.subtotalItems.retrieve`, `qbd.subtotalItems.setCustomField`, `qbd.subtotalItems.update`, `qbd.templates.list`, `qbd.timeTrackingActivities.create`, `qbd.timeTrackingActivities.delete`, `qbd.timeTrackingActivities.list`, `qbd.timeTrackingActivities.retrieve`, `qbd.timeTrackingActivities.update`, `qbd.toDos.create`, `qbd.toDos.delete`, `qbd.toDos.list`, `qbd.toDos.retrieve`, `qbd.toDos.update`, `qbd.transactions.list`, `qbd.transactions.retrieve`, `qbd.transactions.updateClearedStatus`, `qbd.transfers.create`, `qbd.transfers.list`, `qbd.transfers.retrieve`, `qbd.transfers.update`, `qbd.unitOfMeasureSets.create`, `qbd.unitOfMeasureSets.delete`, `qbd.unitOfMeasureSets.list`, `qbd.unitOfMeasureSets.retrieve`, `qbd.vehicleMileage.create`, `qbd.vehicleMileage.delete`, `qbd.vehicleMileage.list`, `qbd.vehicleMileage.retrieve`, `qbd.vehicles.create`, `qbd.vehicles.delete`, `qbd.vehicles.list`, `qbd.vehicles.retrieve`, `qbd.vehicles.update`, `qbd.vendorCredits.create`, `qbd.vendorCredits.delete`, `qbd.vendorCredits.list`, `qbd.vendorCredits.retrieve`, `qbd.vendorCredits.setCustomField`, `qbd.vendorCredits.update`, `qbd.vendorCredits.void`, `qbd.vendorTypes.create`, `qbd.vendorTypes.delete`, `qbd.vendorTypes.list`, `qbd.vendorTypes.retrieve`, `qbd.vendors.create`, `qbd.vendors.delete`, `qbd.vendors.list`, `qbd.vendors.merge`, `qbd.vendors.retrieve`, `qbd.vendors.setCustomField`, `qbd.vendors.update`, `qbd.workersCompCodes.create`, `qbd.workersCompCodes.delete`, `qbd.workersCompCodes.list`, `qbd.workersCompCodes.retrieve`, `qbd.workersCompCodes.update`.
  - `pathParams` (object): The operation's path parameters, for example `{"id": "80000001-1234567890"}`. Required when its path has one.
  - `query` (object): The operation's query parameters as JSON values (booleans, numbers, arrays). `cursor` is not accepted: a list runs as one query of at most `limit` records.
  - `body` (object): The operation's JSON request body, when it takes one.

Minimal example:

```json
{
  "onError": "continueOnError",
  "requests": [
    {
      "operationId": "qbd.customers.create",
      "body": {
        "name": "Acme Supply"
      }
    },
    {
      "operationId": "qbd.invoices.list",
      "query": {
        "limit": 10
      }
    },
    {
      "operationId": "qbd.invoices.retrieve",
      "pathParams": {
        "id": "80000001-1234567890"
      }
    }
  ]
}
```

## Responses

### 200

QuickBooks answered the batch: one result per member.

Body (application/json): object.

- `objectType` (string, required): Always `qbd_batch`. one of `qbd_batch`.
- `onError` (string, required): The error mode the batch ran with. one of `stopOnError`, `continueOnError` (open: accept unknown values).
- `outcome` (string, required): Whether a write took effect: `applied` (QuickBooks confirmed it), `not_applied` (it certainly did not happen), `pending` (sent, still processing), `unknown` (sent, result could not be confirmed) or `not_applicable` (a read). one of `applied`, `not_applied`, `pending`, `unknown`, `not_applicable` (open: accept unknown values).
- `results` (array of object, required): One result per member, in request order.
  - `index` (integer, required): Position in `requests` (0-based). example `0`.
  - `operationId` (string, required): The operation of the member this result belongs to.
  - `status` (string, required): `succeeded`: QuickBooks carried the request out (`data` holds the result). `failed`: QuickBooks rejected it, or its result could not be read (`error`). `not_processed`: an earlier member failed under `stopOnError` and QuickBooks skipped this one (`QBD_REQUEST_NOT_PROCESSED`, status 3231); nothing was applied. `unknown`: a write whose result could not be confirmed because the response was lost (`QBD_WRITE_OUTCOME_UNKNOWN`); never resend it blindly. one of `succeeded`, `failed`, `not_processed`, `unknown` (open: accept unknown values).
  - `outcome` (string, required): Whether this member changed the company file: `applied`, `not_applied` (rejected or skipped), `unknown` (a write whose response was lost) or `not_applicable` (a read). `pending` appears only on the request resource of a batch still in QuickBooks. one of `applied`, `not_applied`, `pending`, `unknown`, `not_applicable` (open: accept unknown values).
  - `data` (object, nullable, required): The result the member's operation returns on its own (see its reference page), when `status` is `succeeded`; otherwise null. A list member returns `objectType`, `url`, `data` and `limitReached`.
  - `error` (object (Error), nullable, required): Set unless `status` is `succeeded`.
    - `type` (string, required): Error category. Use it to choose between retrying, fixing the request and asking the end user to act. one of `INVALID_REQUEST_ERROR`, `AUTHENTICATION_ERROR`, `PERMISSION_ERROR`, `BILLING_ERROR`, `RATE_LIMIT_ERROR`, `INTEGRATION_CONNECTION_ERROR`, `INTEGRATION_ERROR`, `OUTCOME_UNKNOWN_ERROR`, `INTERNAL_ERROR` (open: accept unknown values).
    - `code` (string, required): Stable error code from the error catalog. New codes may be added; a code's meaning never changes. one of `INVALID_JSON`, `INVALID_PARAMETER`, `UNKNOWN_PARAMETER`, `UNKNOWN_HEADER`, `DECIMAL_PRECISION_EXCEEDED`, `STRING_TOO_LONG`, `UNSUPPORTED_CHARACTER`, `FIELD_NOT_CLEARABLE`, `END_USER_ID_MISSING`, `PAYLOAD_TOO_LARGE`, `IDEMPOTENCY_KEY_INVALID`, `IDEMPOTENCY_KEY_REUSED`, `CURSOR_INVALID`, `CURSOR_PARAMS_MISMATCH`, `CURSOR_EXPIRED`, `RESOURCE_MISSING`, `ROUTE_NOT_FOUND`, `REQUEST_NOT_CANCELABLE`, `COMPANY_FILE_RESET_BUSY`, `PASSTHROUGH_INVALID_QBXML`, `QBD_FIELD_UNSUPPORTED_BY_VERSION`, `QBD_REGION_UNSUPPORTED`, `API_KEY_MISSING`, `API_KEY_INVALID`, `PUBLISHABLE_KEY_INVALID`, `PUBLISHABLE_KEY_PROJECT_MISMATCH`, `TEST_COMPANY_FILE_LIMIT_REACHED`, `API_KEY_READ_ONLY`, `PERMISSION_DENIED`, `BILLING_REQUIRED`, `PAYMENT_FAILED`, `RATE_LIMITED`, `CONNECTION_QUEUE_FULL`, `WEBHOOK_ENDPOINT_LIMIT_REACHED`, `CHANGE_FEED_SUBSCRIPTION_LIMIT_REACHED`, `INTEGRATION_CONNECTION_NOT_SET_UP`, `INTEGRATION_CONNECTION_NOT_ACTIVE`, `INTEGRATION_CONNECTION_DISABLED`, `QBD_CONNECTION_ERROR`, `QBD_CANNOT_START`, `QBD_STARTING`, `QBD_MODAL_DIALOG_OPEN`, `QBD_QUICKBOOKS_NOT_RESPONDING`, `QBD_WRONG_COMPANY_FILE_OPEN`, `QBD_COMPANY_FILE_MISMATCH`, `QBD_COMPANY_FILE_NOT_FOUND`, `QBD_FILE_MODE_CONFLICT`, `QBD_ADMIN_REQUIRED`, `QBD_ACCESS_NOT_GRANTED`, `QBD_VERSION_UNSUPPORTED`, `QBD_REQUEST_ERROR`, `QBD_OBJECT_NOT_FOUND`, `QBD_REFERENCE_NOT_FOUND`, `QBD_SALES_TAX_THROUGH_DATE_TOO_EARLY`, `QBD_DUPLICATE_NAME`, `QBD_REVISION_NUMBER_STALE`, `QBD_OBJECT_IN_USE`, `QBD_TRANSIENT_ERROR`, `QBD_FEATURE_NOT_ENABLED`, `QBD_INSUFFICIENT_PERMISSION`, `QBD_RESPONSE_TOO_LARGE`, `QBD_OPERATION_UNSUPPORTED`, `QBD_RESPONSE_UNAVAILABLE`, `QBD_RESPONSE_UNREADABLE`, `REQUEST_TIMEOUT_NOT_SENT`, `REQUEST_EXPIRED`, `REQUEST_CANCELED`, `QBD_REQUEST_TIMEOUT`, `QBD_WRITE_OUTCOME_UNKNOWN`, `QBD_REQUEST_NOT_PROCESSED`, `QBD_READ_INTERRUPTED`, `INTERNAL_ERROR`, `SERVICE_UNAVAILABLE` (open: accept unknown values); example `QBD_MODAL_DIALOG_OPEN`.
    - `message` (string, required): Developer-facing explanation. May include IDs and field paths; never includes secrets.
    - `userFacingMessage` (string, required): A message that is safe to show to the end user.
    - `httpStatusCode` (integer, nullable, required): HTTP status of the response. Every code defines one; on a request resource it is the status a synchronous call returns for the same error (for example 409 for `REQUEST_CANCELED`, 504 for `REQUEST_EXPIRED`). Nullable for compatibility only. example `503`.
    - `integrationCode` (string, nullable, required): Native QuickBooks code when one exists: a qbXML statusCode (`"3200"`), an HRESULT (`"0x80040414"`) or a Web Connector code. example `0x80040414`.
    - `requestId` (string, required): The `Daapi-Request-Id` of this response. Include it when contacting support. example `req_01j9x4m6v4c8k2t7q0r5s3w1zd`.
    - `cause` (string, required): Why this error happens.
    - `fixes` (array of object (ErrorFix), required): Ordered actions that resolve the error, each with the responsible actor.
    - `docsUrl` (string (uri), required): Documentation section for this code. example `https://www.desktopaccountingapi.com/docs/errors/#qbd_modal_dialog_open`.
    - `retryable` (boolean, required): Repeating the identical request (with the same Idempotency-Key for writes) can succeed without changes. Also sent as the `Daapi-Should-Retry` header.
    - `outcome` (string, required): Whether a write took effect: `applied` (QuickBooks confirmed it), `not_applied` (it certainly did not happen), `pending` (sent, still processing), `unknown` (sent, result could not be confirmed) or `not_applicable` (a read). one of `applied`, `not_applied`, `pending`, `unknown`, `not_applicable` (open: accept unknown values).
    - `param` (string, nullable, required): Request field, query parameter or header the error refers to, when known. example `companyName`.
    - `details` (object, required): Code-specific details, documented per code in the error catalog.
  - `recoveredObjectId` (string, nullable, required): The QuickBooks ID of the object this member created, when the batch outcome was uncertain (the response was lost) and the API later found the object in QuickBooks by its `externalId`. `data` is null then: retrieve the object by this ID. Null otherwise. Never resend a member that has one.
  - `warnings` (array of object (RequestWarning), required): Warnings for this member.
    - `code` (string, required): `QBD_WARNING` for a QuickBooks warning status; `QBD_VALUE_UNREADABLE` when a value in the response was garbled and is returned as null; `QBD_MARKUP_REPAIRED` when malformed XML text was kept as text; `QBD_PERSONAL_DATA_WITHHELD` when QuickBooks did not share a personal-data field (an employee's `ssn`) because the integration may not access personal data; the value is null whether or not the file has one. Each code is described on the error reference page under Warnings. one of `QBD_WARNING`, `QBD_VALUE_UNREADABLE`, `QBD_MARKUP_REPAIRED`, `QBD_PERSONAL_DATA_WITHHELD` (open: accept unknown values).
    - `statusCode` (integer, nullable, required): qbXML statusCode of a QuickBooks warning; null for warnings about the response data.
    - `message` (string, required): What happened, including the text QuickBooks sent for unreadable values.
    - `path` (string, nullable, required): Where in `result` the affected value is, such as `data[2].lines[0].amount`; null for QuickBooks warning statuses.

### 202

Accepted in async mode (`Prefer: respond-async`). Poll `Location` or wait for a webhook; the request's `result` holds the success body.

Body (application/json): object (Request).

- `id` (string, required): Unique identifier for the request. example `req_01j9x4m6v4c8k2t7q0r5s3w1zd`.
- `objectType` (string, required): Always `request`. one of `request`.
- `createdAt` (string (date-time), required): When the request was received. UTC, ISO 8601 with milliseconds. example `2026-10-05T16:03:59.002Z`.
- `projectId` (string, required): Unique identifier for the project. example `proj_01j9x4m6v4c8k2t7q0r5s3w1zf`.
- `endUserId` (string, required): Unique identifier for the end user. example `eu_01j9x4m6v4c8k2t7q0r5s3w1zb`.
- `connectionId` (string, nullable, required): The connection that carried the request; null when the call was rejected before the end user had a connection (no setup link created yet). example `conn_01j9x4m6v4c8k2t7q0r5s3w1zc`.
- `operationId` (string, required): The API operation, for example `endUsers.passthrough` or `qbd.healthCheck`. example `qbd.healthCheck`.
- `method` (string, required): HTTP method of the original call. example `GET`.
- `path` (string, required): Path of the original call. example `/v1/quickbooks-desktop/health-check`.
- `mode` (string, required): `sync` when the caller waited for the result. one of `sync`, `async` (open: accept unknown values).
- `status` (string, required): `queued`: accepted and waiting for its turn or the next Web Connector check-in. `waiting_for_connection`: async request waiting for an offline connection. `sent`: handed to QuickBooks; it can no longer be canceled. `succeeded` and `failed` are final. `canceled`: canceled before it was sent. `outcome_unknown`: a write was sent and its result could not be confirmed. one of `queued`, `waiting_for_connection`, `sent`, `succeeded`, `failed`, `canceled`, `outcome_unknown` (open: accept unknown values).
- `outcome` (string, required): Whether a write took effect: `applied` (QuickBooks confirmed it), `not_applied` (it certainly did not happen), `pending` (sent, still processing), `unknown` (sent, result could not be confirmed) or `not_applicable` (a read). one of `applied`, `not_applied`, `pending`, `unknown`, `not_applicable` (open: accept unknown values).
- `sentAt` (string, nullable, required): When the request was handed to the Web Connector. UTC, ISO 8601.
- `completedAt` (string, nullable, required): When the request reached a final status. UTC, ISO 8601.
- `durationMs` (integer, nullable, required): Milliseconds from creation to completion.
- `idempotencyKeyPresent` (boolean, required): Whether the call sent an Idempotency-Key.
- `previousRequestId` (string, nullable, required): An earlier request with the same Idempotency-Key that ended before reaching QuickBooks.
- `waitingReason` (string, nullable, required): Why a queued request is waiting. `quickbooks_not_responding`: the Web Connector started a session but QuickBooks has not answered it (usually a QuickBooks dialog is open; see `diagnosis`). `file_mode_conflict`: the company file was held in single-user mode or by another program; the connection opens QuickBooks again at the `retryAt` of the `file_mode_conflict` diagnosis cause, and the request runs then unless its deadline or queue TTL expires first. `null` once the request was sent. one of `awaiting_check_in`, `behind_other_requests`, `opening_company_file`, `quickbooks_starting`, `connector_offline`, `quickbooks_unavailable`, `quickbooks_not_responding`, `write_recovery_pending`, `file_mode_conflict`, `null` (open: accept unknown values).
- `queuePosition` (integer, nullable, required): Position in this connection's queue (1 = next), while queued.
- `queueTtlExpiresAt` (string, nullable, required): Async requests only: the latest time the request may still be sent. UTC, ISO 8601.
- `timings` (object, required): Where the time went.
  - `queuedMs` (integer, nullable, required): Milliseconds from creation until the request was sent to QuickBooks.
  - `quickbooksMs` (integer, nullable, required): Milliseconds from sending until QuickBooks answered.
  - `totalMs` (integer, nullable, required): Milliseconds from creation to completion.
- `quickbooks` (object, required): Native QuickBooks details.
  - `qbxmlVersion` (string, nullable, required): qbXML version used.
  - `messageSetId` (string, nullable, required): qbXML `newMessageSetID` sent with a write.
  - `statusCode` (integer, nullable, required): qbXML statusCode of the first response element.
  - `statusSeverity` (string, nullable, required): qbXML statusSeverity (`Info`, `Warn` or `Error`).
- `warnings` (array of object (RequestWarning), required): QuickBooks warnings (`statusSeverity="Warn"`), values the API read leniently from a damaged company file, and personal-data fields QuickBooks did not share. The response body never drops a record for these; affected values are null.
  - `code` (string, required): `QBD_WARNING` for a QuickBooks warning status; `QBD_VALUE_UNREADABLE` when a value in the response was garbled and is returned as null; `QBD_MARKUP_REPAIRED` when malformed XML text was kept as text; `QBD_PERSONAL_DATA_WITHHELD` when QuickBooks did not share a personal-data field (an employee's `ssn`) because the integration may not access personal data; the value is null whether or not the file has one. Each code is described on the error reference page under Warnings. one of `QBD_WARNING`, `QBD_VALUE_UNREADABLE`, `QBD_MARKUP_REPAIRED`, `QBD_PERSONAL_DATA_WITHHELD` (open: accept unknown values).
  - `statusCode` (integer, nullable, required): qbXML statusCode of a QuickBooks warning; null for warnings about the response data.
  - `message` (string, required): What happened, including the text QuickBooks sent for unreadable values.
  - `path` (string, nullable, required): Where in `result` the affected value is, such as `data[2].lines[0].amount`; null for QuickBooks warning statuses.
- `recovered` (boolean, required): `true` when an `outcome_unknown` write was resolved by asking QuickBooks for its stored result.
- `timeline` (array of object (RequestTimelineEntry), required): Lifecycle steps in order.
  - `at` (string (date-time), required): When the step happened. UTC, ISO 8601 with milliseconds. example `2026-10-05T16:03:59.002Z`.
  - `status` (string, required): Step, usually a status (`queued`, `waiting`, `sent`, `succeeded`, `diagnosed`, ...).
  - `detail` (string, nullable, required): Extra detail, for example the waiting reason or diagnosis cause.
  - `elapsedMs` (integer, required): Milliseconds since the request was created.
- `diagnosis` (object (RequestDiagnosis), nullable, required): Probable causes while the request waits or runs long, and for requests that timed out or expired before they were sent; `null` otherwise.
  - `at` (string (date-time), required): When the diagnosis was made. UTC, ISO 8601 with milliseconds. example `2026-10-05T16:03:59.002Z`.
  - `summary` (string, required): The most likely cause in one line. example `QuickBooks Desktop probably has a dialog window open.`.
  - `connector` (object, required): What the server observed about the end user's Web Connector.
    - `lastSeenAt` (string, nullable, required): Last sign of the Web Connector (a check-in or a call inside a session). UTC, ISO 8601.
    - `lastCheckInAt` (string, nullable, required): Last Web Connector check-in. UTC, ISO 8601.
    - `checkInIntervalSeconds` (integer, nullable, required): Typical interval between recent check-ins, in seconds.
    - `silentForSeconds` (integer, nullable, required): Seconds since `lastSeenAt`.
    - `sessionOpen` (boolean, required): Whether a Web Connector session is open now.
    - `sessionOpenedAt` (string, nullable, required): When the open session started. UTC, ISO 8601.
    - `quickbooksAnswered` (boolean, nullable, required): Whether QuickBooks answered the open session; `null` without a session.
    - `silentSessions` (integer, required): Recent consecutive sessions in which QuickBooks never answered.
    - `lastConnectionErrorCode` (string, nullable, required): Error code of the latest QuickBooks connection error, while it persists.
  - `probableCauses` (array of object (DiagnosisCause), required): Probable causes, most likely first.
    - `code` (string, required): Stable cause code. New codes may be added. one of `quickbooks_modal_dialog`, `web_connector_registration_lost`, `quickbooks_starting`, `other_web_connector_app`, `web_connector_closed`, `computer_offline`, `web_connector_schedule_changed`, `quickbooks_closed_no_unattended_access`, `quickbooks_unavailable`, `file_mode_conflict`, `wrong_company_file`, `write_recovery_pending`, `behind_other_requests`, `quickbooks_processing`, `session_interrupted`, `same_connector_two_computers`, `record_in_use`, `awaiting_check_in` (open: accept unknown values); example `quickbooks_modal_dialog`.
    - `likelihood` (string, required): How strongly the observations point at this cause. one of `high`, `medium`, `low` (open: accept unknown values).
    - `summary` (string, required): One-line description of the cause.
    - `explanation` (string, required): What the server observed and why it points at this cause.
    - `fixes` (array of object (ErrorFix), required): Actions that resolve the cause, each with the responsible actor.
    - `details` (object, required): Cause-specific observations, for example `connectionErrorCode` or `silentForMs`.
    - `docsUrl` (string (uri), required): Troubleshooting section for this cause.
- `error` (object (Error), nullable, required): The error, when the request failed, was canceled, timed out or has an unknown outcome.
  - `type` (string, required): Error category. Use it to choose between retrying, fixing the request and asking the end user to act. one of `INVALID_REQUEST_ERROR`, `AUTHENTICATION_ERROR`, `PERMISSION_ERROR`, `BILLING_ERROR`, `RATE_LIMIT_ERROR`, `INTEGRATION_CONNECTION_ERROR`, `INTEGRATION_ERROR`, `OUTCOME_UNKNOWN_ERROR`, `INTERNAL_ERROR` (open: accept unknown values).
  - `code` (string, required): Stable error code from the error catalog. New codes may be added; a code's meaning never changes. one of `INVALID_JSON`, `INVALID_PARAMETER`, `UNKNOWN_PARAMETER`, `UNKNOWN_HEADER`, `DECIMAL_PRECISION_EXCEEDED`, `STRING_TOO_LONG`, `UNSUPPORTED_CHARACTER`, `FIELD_NOT_CLEARABLE`, `END_USER_ID_MISSING`, `PAYLOAD_TOO_LARGE`, `IDEMPOTENCY_KEY_INVALID`, `IDEMPOTENCY_KEY_REUSED`, `CURSOR_INVALID`, `CURSOR_PARAMS_MISMATCH`, `CURSOR_EXPIRED`, `RESOURCE_MISSING`, `ROUTE_NOT_FOUND`, `REQUEST_NOT_CANCELABLE`, `COMPANY_FILE_RESET_BUSY`, `PASSTHROUGH_INVALID_QBXML`, `QBD_FIELD_UNSUPPORTED_BY_VERSION`, `QBD_REGION_UNSUPPORTED`, `API_KEY_MISSING`, `API_KEY_INVALID`, `PUBLISHABLE_KEY_INVALID`, `PUBLISHABLE_KEY_PROJECT_MISMATCH`, `TEST_COMPANY_FILE_LIMIT_REACHED`, `API_KEY_READ_ONLY`, `PERMISSION_DENIED`, `BILLING_REQUIRED`, `PAYMENT_FAILED`, `RATE_LIMITED`, `CONNECTION_QUEUE_FULL`, `WEBHOOK_ENDPOINT_LIMIT_REACHED`, `CHANGE_FEED_SUBSCRIPTION_LIMIT_REACHED`, `INTEGRATION_CONNECTION_NOT_SET_UP`, `INTEGRATION_CONNECTION_NOT_ACTIVE`, `INTEGRATION_CONNECTION_DISABLED`, `QBD_CONNECTION_ERROR`, `QBD_CANNOT_START`, `QBD_STARTING`, `QBD_MODAL_DIALOG_OPEN`, `QBD_QUICKBOOKS_NOT_RESPONDING`, `QBD_WRONG_COMPANY_FILE_OPEN`, `QBD_COMPANY_FILE_MISMATCH`, `QBD_COMPANY_FILE_NOT_FOUND`, `QBD_FILE_MODE_CONFLICT`, `QBD_ADMIN_REQUIRED`, `QBD_ACCESS_NOT_GRANTED`, `QBD_VERSION_UNSUPPORTED`, `QBD_REQUEST_ERROR`, `QBD_OBJECT_NOT_FOUND`, `QBD_REFERENCE_NOT_FOUND`, `QBD_SALES_TAX_THROUGH_DATE_TOO_EARLY`, `QBD_DUPLICATE_NAME`, `QBD_REVISION_NUMBER_STALE`, `QBD_OBJECT_IN_USE`, `QBD_TRANSIENT_ERROR`, `QBD_FEATURE_NOT_ENABLED`, `QBD_INSUFFICIENT_PERMISSION`, `QBD_RESPONSE_TOO_LARGE`, `QBD_OPERATION_UNSUPPORTED`, `QBD_RESPONSE_UNAVAILABLE`, `QBD_RESPONSE_UNREADABLE`, `REQUEST_TIMEOUT_NOT_SENT`, `REQUEST_EXPIRED`, `REQUEST_CANCELED`, `QBD_REQUEST_TIMEOUT`, `QBD_WRITE_OUTCOME_UNKNOWN`, `QBD_REQUEST_NOT_PROCESSED`, `QBD_READ_INTERRUPTED`, `INTERNAL_ERROR`, `SERVICE_UNAVAILABLE` (open: accept unknown values); example `QBD_MODAL_DIALOG_OPEN`.
  - `message` (string, required): Developer-facing explanation. May include IDs and field paths; never includes secrets.
  - `userFacingMessage` (string, required): A message that is safe to show to the end user.
  - `httpStatusCode` (integer, nullable, required): HTTP status of the response. Every code defines one; on a request resource it is the status a synchronous call returns for the same error (for example 409 for `REQUEST_CANCELED`, 504 for `REQUEST_EXPIRED`). Nullable for compatibility only. example `503`.
  - `integrationCode` (string, nullable, required): Native QuickBooks code when one exists: a qbXML statusCode (`"3200"`), an HRESULT (`"0x80040414"`) or a Web Connector code. example `0x80040414`.
  - `requestId` (string, required): The `Daapi-Request-Id` of this response. Include it when contacting support. example `req_01j9x4m6v4c8k2t7q0r5s3w1zd`.
  - `cause` (string, required): Why this error happens.
  - `fixes` (array of object (ErrorFix), required): Ordered actions that resolve the error, each with the responsible actor.
    - `actor` (string, required): Who can apply the fix. one of `developer`, `end_user`, `support` (open: accept unknown values).
    - `action` (string, required): What to do.
  - `docsUrl` (string (uri), required): Documentation section for this code. example `https://www.desktopaccountingapi.com/docs/errors/#qbd_modal_dialog_open`.
  - `retryable` (boolean, required): Repeating the identical request (with the same Idempotency-Key for writes) can succeed without changes. Also sent as the `Daapi-Should-Retry` header.
  - `outcome` (string, required): Whether a write took effect: `applied` (QuickBooks confirmed it), `not_applied` (it certainly did not happen), `pending` (sent, still processing), `unknown` (sent, result could not be confirmed) or `not_applicable` (a read). one of `applied`, `not_applied`, `pending`, `unknown`, `not_applicable` (open: accept unknown values).
  - `param` (string, nullable, required): Request field, query parameter or header the error refers to, when known. example `companyName`.
  - `details` (object, required): Code-specific details, documented per code in the error catalog.
- `result` (any): The response body the original call returned (or would have returned) on success; `null` otherwise.
- `resultExpired` (boolean, required): `true` when the result existed but is past the payload retention period (15 days, or 24 hours with payload capture off).

### Errors

Every error body is the error object described at https://www.desktopaccountingapi.com/docs/errors/.

- `400`: The request is invalid. Codes: `UNKNOWN_HEADER`, `END_USER_ID_MISSING`, `INVALID_JSON`, `INVALID_PARAMETER`, `UNKNOWN_PARAMETER`, `DECIMAL_PRECISION_EXCEEDED`, `STRING_TOO_LONG`, `UNSUPPORTED_CHARACTER`, `FIELD_NOT_CLEARABLE`, `IDEMPOTENCY_KEY_INVALID`.
- `401`: The API key is missing or invalid. Codes: `API_KEY_MISSING`, `API_KEY_INVALID`.
- `402`: Billing blocks production data requests. Codes: `BILLING_REQUIRED`, `PAYMENT_FAILED`.
- `403`: The operation is not permitted. Codes: `INTEGRATION_CONNECTION_DISABLED`, `API_KEY_READ_ONLY`, `TEST_COMPANY_FILE_LIMIT_REACHED`.
- `404`: The object does not exist in this project. Codes: `RESOURCE_MISSING`.
- `409`: The request conflicts with the current state. Codes: `INTEGRATION_CONNECTION_NOT_SET_UP`.
- `413`: The request body is too large. Codes: `PAYLOAD_TOO_LARGE`.
- `422`: The request is well formed but cannot be processed. Codes: `QBD_FIELD_UNSUPPORTED_BY_VERSION`, `QBD_REGION_UNSUPPORTED`, `QBD_OPERATION_UNSUPPORTED`, `IDEMPOTENCY_KEY_REUSED`, `QBD_REQUEST_ERROR`, `QBD_RESPONSE_TOO_LARGE`.
- `429`: Too many requests. Codes: `RATE_LIMITED`, `CONNECTION_QUEUE_FULL`.
- `500`: Unexpected server error. Codes: `INTERNAL_ERROR`.
- `502`: The result could not be confirmed. Codes: `QBD_READ_INTERRUPTED`, `QBD_WRITE_OUTCOME_UNKNOWN`.
- `503`: QuickBooks Desktop or the service is not available. Codes: `SERVICE_UNAVAILABLE`, `INTEGRATION_CONNECTION_NOT_ACTIVE`, `QBD_CONNECTION_ERROR`, `QBD_CANNOT_START`, `QBD_STARTING`, `QBD_MODAL_DIALOG_OPEN`, `QBD_QUICKBOOKS_NOT_RESPONDING`, `QBD_WRONG_COMPANY_FILE_OPEN`, `QBD_COMPANY_FILE_NOT_FOUND`, `QBD_FILE_MODE_CONFLICT`, `QBD_ADMIN_REQUIRED`, `QBD_ACCESS_NOT_GRANTED`, `QBD_VERSION_UNSUPPORTED`, `QBD_RESPONSE_UNAVAILABLE`.
- `504`: The request timed out. Codes: `REQUEST_TIMEOUT_NOT_SENT`, `QBD_REQUEST_TIMEOUT`.