Repository navigation
v0.8.0
- A read that was sent, interrupted (for example when QuickBooks closed unexpectedly, HRESULT 0x80040402) and queued for its automatic retry now ends with
QBD_READ_INTERRUPTED(502,details.reason,details.retry,details.firstSentAt) when the retry is not sent in time. It answered504 REQUEST_TIMEOUT_NOT_SENTwithsentAt: null. A request'ssentAtis no longer reset to null by the retry. - New diagnosis cause
quickbooks_closed_unexpectedly: QuickBooks returned an error instead of a result (0x80040402 when it crashed) and the Web Connector, still running with a stuck update lock, has not checked in since. It ranks aboveweb_connector_closed.diagnosis.connector.lastSeenAtnow counts the calls of a session that ended, not only the last check-in. - Breaking:
qbd.unitOfMeasureSets.deleteis removed. QuickBooks answered status 1000 and Intuit documents that a unit of measure set cannot be deleted;DELETE /v1/quickbooks-desktop/unit-of-measure-sets/{id}now answers422 QBD_OPERATION_UNSUPPORTEDwith alternatives (make the set inactive in QuickBooks Desktop) and sends nothing. - Breaking:
qbd.fixedAssetItems.createrequiresassetAccountId. QuickBooks rejects a fixed asset item without an asset account (status 3180), although the qbXML schema marks it optional. - Creating or updating a public custom field definition (
ownerId"0") accepts onlycustomer,vendor,employeeanditeminassignToObjectsandremoveFromObjects; other values answer400 INVALID_PARAMETERbefore anything is sent. QuickBooks refused them with status 3351. - A QuickBooks status 3231 for a request that was alone in its message set carries
details.onlyRequestInMessageSet: trueand says no earlier request caused it. Lead requests and class merges have documented incompatibilities (status 3231 and 3500 on QuickBooks Enterprise 24). - Breaking: a list-object delete (
qbd.<list>.delete, QuickBooksListDel) no longer always answersdeleted: true. QuickBooks Desktop can accept the delete and keep the object, inactive and readable by its ID (Enterprise 24 did this in every test). The API reads the object back in the same request:deletedis true only when QuickBooks no longer returns it; otherwisedeletedis false,deactivatedis true when it is now inactive, andisActiveholds its state. The result types gaindeactivatedandisActive. QBD_REQUEST_ERRORon a read (for example a payroll report QuickBooks refused with status 3262) has the end-user text "QuickBooks Desktop could not provide this information." It said "did not accept this change".errors.jsondocumentsreadUserFacingMessage.- Breaking: custom field definition update and delete take the definition name as the path parameter
definitionName(it wasname). - Breaking: one fallback type per union. An item or entity of a kind this SDK does not model, whether QuickBooks returned a kind the API does not model (
objectTypeqbd_unrecognized_item) or the API added a kind after this SDK version, is anUnrecognizedItem/UnrecognizedEntitywith the shared fields plusqbxmlElementandfields; itsobjectTypeis a plain string.UnknownItemandUnknownEntityare gone. - Breaking: identical enums share one type, used on requests and responses alike, for example
AssignToObject(alsoCustomFieldDefinition.assignToObjects),LeadStatus,ToDoType,ToDoPriority,ClearedStatus,BillingStatus,CustomFieldOperation,TransactionKindandOutcome. The per-operation names (LeadCreateInputStatus,CustomFieldDefinitionCreateInputAssignToObject,RequestListParamsStatu, ...) are gone. - Breaking: type renames:
LeadContactsCreateInput/LeadContactsUpdateInput/LeadContactsareLeadContactCreateInput/LeadContactUpdateInput/LeadContact;DeletedCustomFieldDefinitionisCustomFieldDefinitionDeleted; the result oftransactions.updateClearedStatusisTransactionClearedStatus, whoseclearedStatusis aClearedStatus. - Breaking: to-do list parameters lose the name filters (a to-do has no name), and
payrollWageItems.listno longer takescursor(the list is never paginated; any cursor was refused). IntegrationConnection(an end user'sintegrationConnections) carriesendUserId,disabledandsetupCompletedAt, likeEndUserConnection, which has everyIntegrationConnectionfield plusinstallsandcompanyFileMismatches.- The
createdAtandupdatedAtof every*Voidedresult are date-times. CursorExpired'sreasonis a typed set (idle_timeout,session_ended,quickbooks_restarted,evicted, or a value added later). The cursor-expired error stays a subclass of the invalid-request error, because the API classifiesCURSOR_EXPIREDasINVALID_REQUEST_ERROR; catch it first when you handle the two differently.- Breaking:
confirmon deletes and merges is typedtrueand required, so a call without it does not compile. TransactionCustomFieldValueInputextendsCustomFieldValueInput, andCustomerMergeInputextendsListMergeInput.- New exported type
CursorExpiredReason. - Breaking: a list-object delete's
deletedanddeactivatedcan be null: QuickBooks accepted the delete but reading the record back failed. The request then succeeds withoutcomeapplied and a newQBD_DELETE_NOT_VERIFIEDwarning; do not send the delete again. A failed write the API verified as applied keepsoutcomeapplied and is not retryable. - List-object delete results gain
retainedBecause:multi_user_modewhen QuickBooks kept the record because the company file was open in multi-user mode (it deletes in single-user mode). - New error code
QBD_REQUIRES_SINGLE_USER_MODE(409, not retryable, outcomenot_applied): merges and custom field definition deletes are refused before sending while the company file is open in multi-user mode, and custom field values QuickBooks refuses there (status 3180 or 3120) map to it.integrationConnections[].companyFile.fileMode(single_user/multi_user) shows the mode of the last session. - A lead request QuickBooks does not process (status 3231, even a plain lead list) answers
422 QBD_OPERATION_UNSUPPORTEDwith alternatives instead ofQBD_REQUEST_ERROR. qbd.vehicleMileage.deletereads the trip first: an unknown ID answers404 QBD_OBJECT_NOT_FOUND; an existing trip answers422 QBD_OPERATION_UNSUPPORTED(QuickBooks refuses the delete with status 3160 even on a fresh company file) without sending the delete.- The
quickbooks_closed_unexpectedlydiagnosis needs QuickBooks' "Unexpected error" (HRESULT 0x80040402) in a session the Web Connector never closed, and silence since its last contact; its steps first have the end user check that QuickBooks closed and no other application is updating. - Batches (
qbd.batch) follow the same rules: a list-delete member reads the record back (deleted,deactivated,retainedBecause, and aQBD_DELETE_NOT_VERIFIEDmember warning when the read-back failed), a batch holding a merge or custom field definition delete is refused with409 QBD_REQUIRES_SINGLE_USER_MODEin multi-user mode (details.indexnames the member), a lead member QuickBooks does not process isQBD_OPERATION_UNSUPPORTED, a vehicle mileage delete member is refused with422 QBD_OPERATION_UNSUPPORTED, and batch delete and merge members requireconfirmlike the typed calls. - Breaking: a batch member for custom field definition update or delete takes
pathParams.definitionName(waspathParams.name), as the typed calls do. - A custom field definition delete reads the owner's definitions back in the same request:
CustomFieldDefinitionDeletedgainsdeleted(true only when the definition is gone, false when QuickBooks kept it, null when the read-back failed with aQBD_DELETE_NOT_VERIFIEDwarning) andretainedBecause(multi_user_modeorunknown), on the typed call and as a batch member. QBD_REQUIRES_SINGLE_USER_MODEnow needs QuickBooks' own evidence: a custom field value refused with another 3180/3120 message keeps its code (for example not found, orQBD_TRANSIENT_ERRORfor a record modified by another user); a generic data-extension refusal in multi-user mode keeps its code withdetails.possibleCause: multi_user_mode.- A batch member QuickBooks refused is
not_appliedin its result and its error, whatever other members did; a lead member undercontinueOnErrorafter another member failed isQBD_OPERATION_UNSUPPORTED, notnot_processed; the vehicle mileage refusal carriesdetails.index. - New error code
QBD_REAUTHORIZATION_REQUIRED(ErrorCode.QBD_REAUTHORIZATION_REQUIRED):503, not retryable. QuickBooks answered the Web Connector with 0x80040435 and asks its Admin to reauthorize the application in Edit > Preferences > Integrated Applications; nothing was sent. It answeredQBD_CONNECTION_ERROR. New diagnosis causequickbooks_reauthorization_required. - A company file QuickBooks cannot reach at its stored location (0x80040408 for a path on a drive letter other than C:, usually a disconnected mapped network drive, or for the same path twice in a row) answers
QBD_COMPANY_FILE_NOT_FOUNDwithdetails.reasonpath_unreachable,details.pathKindanddetails.refusals, and the new diagnosis causecompany_file_not_foundranks first. It answeredQBD_WRONG_COMPANY_FILE_OPEN("a different company file is open"). - A QuickBooks status 3170 whose message says the record is in use, locked or being edited answers
409 QBD_OBJECT_IN_USEwith therecord_in_usediagnosis (not retryable for a deletion). It answered422 QBD_REQUEST_ERROR. QuickBooks does not lock every open record, so the documentation no longer promises that an open window blocks a change. - A payment item or job type name that is already in use answers
409 QBD_DUPLICATE_NAMEwithparamname(QuickBooks status 3180). It answered422 QBD_REQUEST_ERROR. qbd.customFieldDefinitions.listwithout filters returns the public definitions (ownerId"0"); it returned none.ownerIdstogether withassignToObjectslists the definitions of those owners assigned to those record types, private ones included; the combination was refused.- Vehicle mileage
createdAtandupdatedAtare date-times: midnight UTC when QuickBooks reports only a date. They were plain dates, which the Java SDK could not parse. - A single request ends its Web Connector session as soon as QuickBooks answers it, so QuickBooks no longer counts the application as using the company file for 2 seconds afterwards; only a request sent within 30 seconds of another keeps the session open for the next one.
All versions: CHANGELOG.md.