# Create a check
Source: https://www.desktopaccountingapi.com/docs/api/reference/operations/qbdcheckscreate/

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

Operation ID: `qbd.checks.create`. Tag: Checks.

Creates a check in QuickBooks Desktop and returns it. Send an `Idempotency-Key` header so a retry after a network error never creates a second check (the SDKs do this for you). See [Idempotency and safe retries](https://www.desktopaccountingapi.com/docs/guides/idempotency/).

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

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

- `bankAccountId` (string, required): ID of the bank account for this check. 1–36 characters; example `80000001-1234567890`.
- `payeeId` (string): ID of the payee for this check. 1–36 characters; example `80000001-1234567890`.
- `refNumber` (string): Reference number of this check, such as an invoice or check number. Case-sensitive. max 11 characters.
- `transactionDate` (string (date)): Date of this check (YYYY-MM-DD). example `2026-10-05`.
- `memo` (string): Internal memo for this check; shown in reports, not on printed forms. max 4095 characters.
- `address` (object (QbdAddressCreateInput)): Address details for this check.
  - `line1` (string): First address line. max 41 characters.
  - `line2` (string): Second address line. max 41 characters.
  - `line3` (string): Third address line. max 41 characters.
  - `line4` (string): Fourth address line. max 41 characters.
  - `line5` (string): Fifth address line. max 41 characters.
  - `city` (string): City or locality. max 31 characters.
  - `state` (string): State, province or region. max 21 characters.
  - `postalCode` (string): Postal or ZIP code. max 13 characters.
  - `country` (string): Country. max 31 characters.
  - `note` (string): Note for this vendor address. max 41 characters.
- `isQueuedForPrint` (boolean): Whether this check is in the queue of forms to print.
- `exchangeRate` (number): Exchange rate from this check's currency to the home currency.
- `externalId` (string (uuid)): Your own UUID for this check, stored by QuickBooks so you can match records with your system.
- `applyToTransactions` (array of object (QbdApplyCheckToTxnInput)): Apply to transactions entries for this check.
  - `transactionId` (string, required): ID of the transaction. 1–36 characters; example `80000001-1234567890`.
  - `amount` (string): Amount as a decimal string. example `1250.00`.
- `expenseLines` (array of object (QbdExpenseLineCreateInput)): Expense lines entries for this check.
  - `accountId` (string): ID of the account for this expense line. 1–36 characters; example `80000001-1234567890`.
  - `amount` (string): Amount as a decimal string. example `1250.00`.
  - `memo` (string): Internal memo for this expense line; shown in reports, not on printed forms. max 4095 characters.
  - `payeeId` (string): ID of the payee for this expense line. 1–36 characters; example `80000001-1234567890`.
  - `classId` (string): ID of the class for this expense line. 1–36 characters; example `80000001-1234567890`.
  - `billingStatus` (string): Whether this line can be billed to a customer. one of `billable`, `not_billable`, `has_been_billed`.
  - `salesRepresentativeId` (string): ID of the sales representative for this expense line. 1–36 characters; example `80000001-1234567890`.
  - `customFields` (array of object (QbdCustomFieldCreateInput)): Custom field values QuickBooks stores on this expense line.
    - `ownerId` (string, required): Owner of the custom field: "0" for public fields shown in the QuickBooks UI.
    - `name` (string, required): Name of this custom field, unique within its parent level. max 31 characters.
    - `value` (string, required): Value.
- `itemLines` (array of object (QbdItemLineCreateInput)): Item lines entries for this check.
  - `itemId` (string): ID of the item for this item line. 1–36 characters; example `80000001-1234567890`.
  - `inventorySiteId` (string): ID of the inventory site for this item line. 1–36 characters; example `80000001-1234567890`.
  - `inventorySiteLocationId` (string): ID of the inventory site location for this item line. 1–36 characters; example `80000001-1234567890`.
  - `serialNumber` (string): Serial number of this item line. Cannot be combined with lotNumber. max 4095 characters.
  - `lotNumber` (string): Lot number of this item line. Cannot be combined with serialNumber. max 40 characters.
  - `expirationDate` (string): Expiration date of this item line. max 1099 characters.
  - `description` (string): Description of this item line. max 4095 characters.
  - `quantity` (number): Quantity of the item.
  - `unitOfMeasure` (string): Unit of measure for the quantity. max 31 characters.
  - `cost` (string): Cost of this item line. Decimal string with up to 5 decimal places. example `19.99`.
  - `amount` (string): Amount as a decimal string. example `1250.00`.
  - `customerId` (string): ID of the customer for this item line. 1–36 characters; example `80000001-1234567890`.
  - `classId` (string): ID of the class for this item line. 1–36 characters; example `80000001-1234567890`.
  - `billingStatus` (string): Whether this line can be billed to a customer. one of `billable`, `not_billable`, `has_been_billed`.
  - `overrideItemAccountId` (string): ID of the override item account for this item line. 1–36 characters; example `80000001-1234567890`.
  - `salesRepresentativeId` (string): ID of the sales representative for this item line. 1–36 characters; example `80000001-1234567890`.
  - `customFields` (array of object (QbdCustomFieldCreateInput)): Custom field values QuickBooks stores on this item line.
    - `ownerId` (string, required): Owner of the custom field: "0" for public fields shown in the QuickBooks UI.
    - `name` (string, required): Name of this custom field, unique within its parent level. max 31 characters.
    - `value` (string, required): Value.
- `itemGroupLines` (array of object (QbdItemGroupLineCreateInput)): Item group lines entries for this check.
  - `itemGroupId` (string, required): ID of the item group for this item group line. 1–36 characters; example `80000001-1234567890`.
  - `quantity` (number): Quantity of the item.
  - `unitOfMeasure` (string): Unit of measure for the quantity. max 31 characters.
  - `inventorySiteId` (string): ID of the inventory site for this item group line. 1–36 characters; example `80000001-1234567890`.
  - `inventorySiteLocationId` (string): ID of the inventory site location for this item group line. 1–36 characters; example `80000001-1234567890`.
  - `customFields` (array of object (QbdCustomFieldCreateInput)): Custom field values QuickBooks stores on this item group line.
    - `ownerId` (string, required): Owner of the custom field: "0" for public fields shown in the QuickBooks UI.
    - `name` (string, required): Name of this custom field, unique within its parent level. max 31 characters.
    - `value` (string, required): Value.

Minimal example:

```json
{
  "bankAccountId": "80000001-1234567890"
}
```

## Responses

### 201

The created check.

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

- `id` (string, required): QuickBooks-assigned ID of this check.
- `objectType` (string, required): Type of this object. one of `qbd_check`.
- `createdAt` (string (date-time), required): When this check was created, as an ISO 8601 date-time with the QuickBooks computer's UTC offset. example `2026-10-05T09:14:03-07:00`.
- `updatedAt` (string (date-time), required): When this check was last changed, as an ISO 8601 date-time with the QuickBooks computer's UTC offset. example `2026-10-05T09:14:03-07:00`.
- `revisionNumber` (string, required): Current revision of this check. Send it unchanged when updating; a stale value is rejected.
- `transactionNumber` (integer, nullable, required): Sequential transaction number QuickBooks assigns internally.
- `bankAccount` (object (QbdReference), nullable, required): The bank account for this check.
  - `id` (string, nullable, required): QuickBooks ID of the referenced object.
  - `fullName` (string, nullable, required): Full name of the referenced object at the time of the response.
- `payee` (object (QbdReference), nullable, required): The payee for this check.
  - `id` (string, nullable, required): QuickBooks ID of the referenced object.
  - `fullName` (string, nullable, required): Full name of the referenced object at the time of the response.
- `refNumber` (string, nullable, required): Reference number of this check, such as an invoice or check number. Case-sensitive.
- `transactionDate` (string (date), nullable, required): Date of this check (YYYY-MM-DD). example `2026-10-05`.
- `amount` (string, nullable, required): Amount as a decimal string. example `1250.00`.
- `currency` (object (QbdReference), nullable, required): Currency of this check.
  - `id` (string, nullable, required): QuickBooks ID of the referenced object.
  - `fullName` (string, nullable, required): Full name of the referenced object at the time of the response.
- `exchangeRate` (number, nullable, required): Exchange rate from this check's currency to the home currency.
- `amountInHomeCurrency` (string, nullable, required): Amount in home currency of this check. Decimal string with up to 2 decimal places. example `1250.00`.
- `memo` (string, nullable, required): Internal memo for this check; shown in reports, not on printed forms.
- `address` (object (QbdAddress), nullable, required): Address details for this check.
  - `line1` (string, nullable, required): First address line.
  - `line2` (string, nullable, required): Second address line.
  - `line3` (string, nullable, required): Third address line.
  - `line4` (string, nullable, required): Fourth address line.
  - `line5` (string, nullable, required): Fifth address line.
  - `city` (string, nullable, required): City or locality.
  - `state` (string, nullable, required): State, province or region.
  - `postalCode` (string, nullable, required): Postal or ZIP code.
  - `country` (string, nullable, required): Country.
  - `note` (string, nullable, required): Note for this address.
- `isPending` (boolean, nullable, required): Whether this check is pending (not yet final) and does not post to accounts.
- `isQueuedForPrint` (boolean, nullable, required): Whether this check is in the queue of forms to print.
- `externalId` (string (uuid), nullable, required): Your own UUID for this check, stored by QuickBooks so you can match records with your system.
- `linkedTransactions` (array of object (QbdLinkedTransaction), required): Transactions linked to this check, such as payments applied to it.
  - `id` (string, nullable, required): QuickBooks-assigned ID of this linked transaction.
  - `objectType` (string, required): Type of this object. one of `qbd_linked_transaction`.
  - `transactionType` (string, nullable, required): Transaction type of this linked transaction. one of `ar_refund_credit_card`, `bill`, `bill_payment_check`, `bill_payment_credit_card`, `build_assembly`, `charge`, `check`, `credit_card_charge`, `credit_card_credit`, `credit_memo`, `deposit`, `estimate`, `inventory_adjustment`, `invoice`, `item_receipt`, `journal_entry`, `liability_adjustment`, `paycheck`, `payroll_liability_check`, `purchase_order`, `receive_payment`, `sales_order`, `sales_receipt`, `sales_tax_payment_check`, `transfer`, `vendor_credit`, `ytd_adjustment` (open: accept unknown values).
  - `transactionDate` (string (date), nullable, required): Date of this linked transaction (YYYY-MM-DD). example `2026-10-05`.
  - `refNumber` (string, nullable, required): Reference number of this linked transaction, such as an invoice or check number. Case-sensitive.
  - `linkType` (string, nullable, required): Link type of this linked transaction. one of `amount`, `quantity` (open: accept unknown values).
  - `amount` (string, nullable, required): Amount as a decimal string. example `1250.00`.
- `expenseLines` (array of object (QbdExpenseLine), required): Expense lines entries for this check.
  - `id` (string, nullable, required): QuickBooks-assigned ID of this expense line.
  - `objectType` (string, required): Type of this object. one of `qbd_expense_line`.
  - `account` (object (QbdReference), nullable, required): The account for this expense line.
    - `id` (string, nullable, required): QuickBooks ID of the referenced object.
    - `fullName` (string, nullable, required): Full name of the referenced object at the time of the response.
  - `amount` (string, nullable, required): Amount as a decimal string. example `1250.00`.
  - `memo` (string, nullable, required): Internal memo for this expense line; shown in reports, not on printed forms.
  - `payee` (object (QbdReference), nullable, required): The payee for this expense line.
    - `id` (string, nullable, required): QuickBooks ID of the referenced object.
    - `fullName` (string, nullable, required): Full name of the referenced object at the time of the response.
  - `class` (object (QbdReference), nullable, required): The class for this expense line.
    - `id` (string, nullable, required): QuickBooks ID of the referenced object.
    - `fullName` (string, nullable, required): Full name of the referenced object at the time of the response.
  - `billingStatus` (string, nullable, required): Whether this line can be billed to a customer. one of `billable`, `not_billable`, `has_been_billed` (open: accept unknown values).
  - `salesRepresentative` (object (QbdReference), nullable, required): The sales representative for this expense line.
    - `id` (string, nullable, required): QuickBooks ID of the referenced object.
    - `fullName` (string, nullable, required): Full name of the referenced object at the time of the response.
  - `customFields` (array of object (QbdCustomField), required): Custom field values QuickBooks stores on this expense line.
    - `ownerId` (string, nullable, required): Owner of the custom field: "0" for public fields shown in the QuickBooks UI.
    - `name` (string, nullable, required): Name of this custom field, unique within its parent level.
    - `type` (string, nullable, required): Type. one of `amount_type`, `date_time_type`, `integer_type`, `percent_type`, `price_type`, `quantity_type`, `string_1024_type`, `string_255_type` (open: accept unknown values).
    - `value` (string, nullable, required): Value.
- `itemLines` (array of object (QbdItemLine), required): Item lines entries for this check.
  - `id` (string, nullable, required): QuickBooks-assigned ID of this item line.
  - `objectType` (string, required): Type of this object. one of `qbd_item_line`.
  - `item` (object (QbdReference), nullable, required): The item for this item line.
    - `id` (string, nullable, required): QuickBooks ID of the referenced object.
    - `fullName` (string, nullable, required): Full name of the referenced object at the time of the response.
  - `inventorySite` (object (QbdReference), nullable, required): The inventory site for this item line.
    - `id` (string, nullable, required): QuickBooks ID of the referenced object.
    - `fullName` (string, nullable, required): Full name of the referenced object at the time of the response.
  - `inventorySiteLocation` (object (QbdReference), nullable, required): The inventory site location for this item line.
    - `id` (string, nullable, required): QuickBooks ID of the referenced object.
    - `fullName` (string, nullable, required): Full name of the referenced object at the time of the response.
  - `serialNumber` (string, nullable, required): Serial number of this item line.
  - `lotNumber` (string, nullable, required): Lot number of this item line.
  - `expirationDate` (string, nullable, required): Expiration date of this item line.
  - `description` (string, nullable, required): Description of this item line.
  - `quantity` (number, nullable, required): Quantity of the item.
  - `unitOfMeasure` (string, nullable, required): Unit of measure for the quantity.
  - `overrideUnitOfMeasureSet` (object (QbdReference), nullable, required): Unit of measure set that overrides the item default on this line.
    - `id` (string, nullable, required): QuickBooks ID of the referenced object.
    - `fullName` (string, nullable, required): Full name of the referenced object at the time of the response.
  - `cost` (string, nullable, required): Cost of this item line. Decimal string with up to 5 decimal places. example `19.99`.
  - `amount` (string, nullable, required): Amount as a decimal string. example `1250.00`.
  - `customer` (object (QbdReference), nullable, required): The customer for this item line.
    - `id` (string, nullable, required): QuickBooks ID of the referenced object.
    - `fullName` (string, nullable, required): Full name of the referenced object at the time of the response.
  - `class` (object (QbdReference), nullable, required): The class for this item line.
    - `id` (string, nullable, required): QuickBooks ID of the referenced object.
    - `fullName` (string, nullable, required): Full name of the referenced object at the time of the response.
  - `billingStatus` (string, nullable, required): Whether this line can be billed to a customer. one of `billable`, `not_billable`, `has_been_billed` (open: accept unknown values).
  - `salesRepresentative` (object (QbdReference), nullable, required): The sales representative for this item line.
    - `id` (string, nullable, required): QuickBooks ID of the referenced object.
    - `fullName` (string, nullable, required): Full name of the referenced object at the time of the response.
  - `customFields` (array of object (QbdCustomField), required): Custom field values QuickBooks stores on this item line.
    - `ownerId` (string, nullable, required): Owner of the custom field: "0" for public fields shown in the QuickBooks UI.
    - `name` (string, nullable, required): Name of this custom field, unique within its parent level.
    - `type` (string, nullable, required): Type. one of `amount_type`, `date_time_type`, `integer_type`, `percent_type`, `price_type`, `quantity_type`, `string_1024_type`, `string_255_type` (open: accept unknown values).
    - `value` (string, nullable, required): Value.
- `itemGroupLines` (array of object (QbdItemGroupLine), required): Item group lines entries for this check.
  - `id` (string, nullable, required): QuickBooks-assigned ID of this item group line.
  - `objectType` (string, required): Type of this object. one of `qbd_item_group_line`.
  - `itemGroup` (object (QbdReference), nullable, required): The item group for this item group line.
    - `id` (string, nullable, required): QuickBooks ID of the referenced object.
    - `fullName` (string, nullable, required): Full name of the referenced object at the time of the response.
  - `description` (string, nullable, required): Description of this item group line.
  - `quantity` (number, nullable, required): Quantity of the item.
  - `unitOfMeasure` (string, nullable, required): Unit of measure for the quantity.
  - `overrideUnitOfMeasureSet` (object (QbdReference), nullable, required): Unit of measure set that overrides the item default on this line.
    - `id` (string, nullable, required): QuickBooks ID of the referenced object.
    - `fullName` (string, nullable, required): Full name of the referenced object at the time of the response.
  - `totalAmount` (string, nullable, required): Total amount of this item group line as a decimal string. example `1250.00`.
  - `itemLines` (array of object (QbdItemLine), required): Item lines entries for this item group line.
    - `id` (string, nullable, required): QuickBooks-assigned ID of this item line.
    - `objectType` (string, required): Type of this object. one of `qbd_item_line`.
    - `item` (object (QbdReference), nullable, required): The item for this item line.
    - `inventorySite` (object (QbdReference), nullable, required): The inventory site for this item line.
    - `inventorySiteLocation` (object (QbdReference), nullable, required): The inventory site location for this item line.
    - `serialNumber` (string, nullable, required): Serial number of this item line.
    - `lotNumber` (string, nullable, required): Lot number of this item line.
    - `expirationDate` (string, nullable, required): Expiration date of this item line.
    - `description` (string, nullable, required): Description of this item line.
    - `quantity` (number, nullable, required): Quantity of the item.
    - `unitOfMeasure` (string, nullable, required): Unit of measure for the quantity.
    - `overrideUnitOfMeasureSet` (object (QbdReference), nullable, required): Unit of measure set that overrides the item default on this line.
    - `cost` (string, nullable, required): Cost of this item line. Decimal string with up to 5 decimal places. example `19.99`.
    - `amount` (string, nullable, required): Amount as a decimal string. example `1250.00`.
    - `customer` (object (QbdReference), nullable, required): The customer for this item line.
    - `class` (object (QbdReference), nullable, required): The class for this item line.
    - `billingStatus` (string, nullable, required): Whether this line can be billed to a customer. one of `billable`, `not_billable`, `has_been_billed` (open: accept unknown values).
    - `salesRepresentative` (object (QbdReference), nullable, required): The sales representative for this item line.
    - `customFields` (array of object (QbdCustomField), required): Custom field values QuickBooks stores on this item line.
  - `customFields` (array of object (QbdCustomField), required): Custom field values QuickBooks stores on this item group line.
    - `ownerId` (string, nullable, required): Owner of the custom field: "0" for public fields shown in the QuickBooks UI.
    - `name` (string, nullable, required): Name of this custom field, unique within its parent level.
    - `type` (string, nullable, required): Type. one of `amount_type`, `date_time_type`, `integer_type`, `percent_type`, `price_type`, `quantity_type`, `string_1024_type`, `string_255_type` (open: accept unknown values).
    - `value` (string, nullable, required): Value.
- `customFields` (array of object (QbdCustomField), required): Custom field values QuickBooks stores on this check.
  - `ownerId` (string, nullable, required): Owner of the custom field: "0" for public fields shown in the QuickBooks UI.
  - `name` (string, nullable, required): Name of this custom field, unique within its parent level.
  - `type` (string, nullable, required): Type. one of `amount_type`, `date_time_type`, `integer_type`, `percent_type`, `price_type`, `quantity_type`, `string_1024_type`, `string_255_type` (open: accept unknown values).
  - `value` (string, nullable, required): Value.

### 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`). `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`, `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"`) and values the API read leniently from a damaged company file. 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. one of `QBD_WARNING`, `QBD_VALUE_UNREADABLE`, `QBD_MARKUP_REPAIRED` (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`, `wrong_company_file`, `write_recovery_pending`, `behind_other_requests`, `quickbooks_processing`, `session_interrupted`, `same_connector_two_computers`, `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`, `REQUEST_NOT_CANCELABLE`, `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`, `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_DUPLICATE_NAME`, `QBD_REVISION_NUMBER_STALE`, `QBD_OBJECT_IN_USE`, `QBD_FEATURE_NOT_ENABLED`, `QBD_INSUFFICIENT_PERMISSION`, `QBD_RESPONSE_TOO_LARGE`, `QBD_OPERATION_UNSUPPORTED`, `QBD_RESPONSE_UNREADABLE`, `REQUEST_TIMEOUT_NOT_SENT`, `REQUEST_EXPIRED`, `REQUEST_CANCELED`, `QBD_REQUEST_TIMEOUT`, `QBD_WRITE_OUTCOME_UNKNOWN`, `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. `null` for codes that appear only on a request resource (`REQUEST_EXPIRED`, `REQUEST_CANCELED`). 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_PARAMETER`, `UNKNOWN_PARAMETER`, `INVALID_JSON`, `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`, `PERMISSION_DENIED`, `QBD_INSUFFICIENT_PERMISSION`, `API_KEY_READ_ONLY`.
- `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`, `QBD_COMPANY_FILE_MISMATCH`, `QBD_DUPLICATE_NAME`, `QBD_OBJECT_IN_USE`.
- `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_REQUEST_ERROR`, `QBD_FEATURE_NOT_ENABLED`, `IDEMPOTENCY_KEY_REUSED`, `QBD_REFERENCE_NOT_FOUND`.
- `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`.
- `504`: The request timed out. Codes: `REQUEST_TIMEOUT_NOT_SENT`, `QBD_REQUEST_TIMEOUT`.