Repository navigation
Releases
Releases · DesktopAccountingAPI/quickbooks-desktop-java
v0.12.1
- Documentation and error text, no behavior change: on every QuickBooks list, the descriptions of
updatedAfterandupdatedBefore(1970-01-02 to 2037-12-31),transactionDateFrom(up to 2037-12-31) andtransactionDateTo(from 1970-01-01) state these limits and that the start must not be after the end. A date filter QuickBooks Desktop refuses (status 3020 or 3030) still returns422 QBD_REQUEST_ERROR. When the filters sent explain the refusal, the message names the filter and its limit,paramnames the filter anddetails.reasonisdate_range_invertedordate_out_of_range; otherwise the message is QuickBooks' own, withdetails.reasondate_filter_rejectedwhen one of these filters was sent. See the API changelog.
All versions: CHANGELOG.md.
v0.12.0
IntegrationConnection(inEndUser.integrationConnections()) andEndUserConnection(fromclient.endUsers().retrieveConnection()and the disable and enable calls) havesimulated()(boolean):truefor the hosted sample company, which answers from recordings of real QuickBooks Desktop;falsefor a company file connected through the Web Connector.- New error code
SAMPLE_COMPANY_UNSUPPORTED(422, not retryable, outcomenot_applied), thrown asInvalidRequestException: the sample company has no recorded answer for this request.details.reasonsays why,details.elementnames the qbXML element, anddetails.detailsays what works, when the request has a working alternative. The message often says what works. Nothing changes. Do not retry it. - Documentation corrections, no behavior change: on
Bill,openAmount()is the vendor's open balance as QuickBooks returns it (the same on every bill from that vendor), andamountDue()is the bill's total, which stays the same as payments are applied (isPaid()says whether it is paid). On customers, vendors, accounts and items,updatedAfterandupdatedBeforematch a record when its last edit or its last change falls in the range, soupdatedBeforecan return records whoseupdatedAt()is later; on inventory items QuickBooks compares the last edit only, so a quantity-on-hand change from a posted transaction does not matchupdatedAfter.
All versions: CHANGELOG.md.
v0.11.1
- Released in lockstep with the other Desktop Accounting API packages; no entries for this package.
All versions: CHANGELOG.md.
v0.11.0
- A list page (the first page or a later one) that gets
504 QBD_REQUEST_TIMEOUTis no longer thrown at once: the SDK long-polls the request until it ends or the call's time budget passes, like every other call and like the other SDKs, and never resends the page. It throwsRequestPendingExceptionif the request is still running at the deadline. - A write whose outcome was unknown and that the platform later recovered (request
succeeded,outcomeapplied,recovered: true,resultnull,recoveredObjectIdset) throws the newResultUnavailableExceptionfromRequestHandle.await(),RequestHandle.result()and the long poll after504 QBD_REQUEST_TIMEOUT. They threw aDaapiExceptionfrom parsing the missing result. It extendsInternalExceptionand carriesrequestId(),outcome()applied,retryable()false andrecoveredObjectId(); retrieve the object by that ID and do not send the write again. This holds also when the result is past retention (resultExpiredtrue). 500 INTERNAL_ERRORwithdetails.reasonresult_unavailable(the result is no longer available) throwsResultUnavailableException(recoveredObjectId()null) and is never retried, even whenDaapi-Should-Retrysays true. For a write that was applied (outcome: applied), never send it again and read the object instead; for a read (outcome: not_applicable), it is safe to send the read again.PriceLevelListParams.itemId(String)is an alias ofitemIds(String)with Conductor's name for this filter, so Conductor code ports unchanged. Both take one item ID; setting both to different values returns400 INVALID_PARAMETER.BatchPriceLevelListInputQueryhas the same alias for batch members.
All versions: CHANGELOG.md.
v0.10.0
- The request resource (
recoveredObjectId) names the object a write created or changed when the platform recovered that write after a lost acknowledgement. QuickBooks' response body to such a write was never received, so a request retrieved withrequests().retrieve()that showssucceeded,appliedandrecovered: truekeepsresultnull: retrieve the object by this id. It is null for every other request. A typed batch recovered that way still carries each create member's ownrecoveredObjectIdinresult; the request-level field holds the first write member's. - A list you keep reading keeps its QuickBooks session open for up to 10 minutes. The 2-minute session cap ended longer list reads with
410 CURSOR_EXPIRED(session_ended), with no way to resume. The 10-second idle window between pages is unchanged. See the Pagination guide.
All versions: CHANGELOG.md.
v0.9.1
- New error
QBD_MERGE_NOT_ALLOWED(422, not retryable, outcomenot_applied) on merges (qbd.<list>.mergeand merges sent through passthrough or a batch) when QuickBooks Desktop refuses the merge with status 3500 outside the multi-user case. It used to surface asQBD_REQUEST_ERRORwith QuickBooks' "Unknown Error".detailscarriesqbxmlStatusCode,qbxmlStatusMessage,requestElement,listMergeType,sourceId,targetId,fileMode,fileModeObservedAtandrequestId; nothing was changed. Do not retry automatically. Customer merges add the diagnosis causecustomer_merge_native_refusal, which confirms the refusal without claiming a cause; QuickBooks does not report one. - The passthrough endpoint documents
QBD_MERGE_NOT_ALLOWEDandQBD_REQUIRES_SINGLE_USER_MODEfor rawListMergeRqrequests.
All versions: CHANGELOG.md.
v0.9.0
- Released in lockstep with the other Desktop Accounting API packages; no entries for this package.
All versions: CHANGELOG.md.
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: enums are typed. Each enum (except the
ErrorCodeandErrorTypeconstants) is a final class with a constant per known value (LeadStatus.HOT),of(String)for any other value,value(),isKnown()andknown(), which returns a JavaenumwithUNRECOGNIZEDfor an exhaustiveswitch. Fields, setters and getters use it instead ofString. The SDK targets Java 11, so unions are plain interfaces, not sealed ones. - Breaking: deletes and merges take the confirmation in the constructor:
new CustomerDeleteParams(Confirm.YES),new ListMergeInput(revisionNumber, mergeIntoId, mergeIntoRevisionNumber, Confirm.YES). There is noconfirm(...)setter. CustomFieldValueInputandTransactionCustomFieldValueInputimplementCustomFieldValueInputFields;ListMergeInputandCustomerMergeInputimplementListMergeInputFields.- Breaking:
ApiException.status()returnsint(the response status, else the error'shttpStatusCode, else 0) andretryable()returnsboolean(false when the body was not JSON).CursorExpiredException.reason()returns aCursorExpiredReason. - 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. - Breaking: the batch's
onErroris the shared enum classBatchOnErroron the request and the result (BatchInput.onError(BatchOnError.CONTINUE_ON_ERROR), no longer aString); a batch member'soutcomeisOutcome, like the error's. - 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...
v0.7.0
- New
client.qbd().batch(): up to 25 typed QuickBooks Desktop operations in one Web Connector round trip. Each member is the member class of its operation (new BatchCustomerCreateInput().body(...), which setsoperationIditself) and each result is an instance of its operation's result class (BatchCustomerCreateResult, whosedata()is aCustomer), orUnknownBatchResultfor an operation added later. One idempotency key covers the batch; a lost response throwsOutcomeUnknownExceptionwithdetails().get("members")and is never retried. - A batch whose response was lost and whose create members the API later found in QuickBooks by their
externalIdreturns each such member withdata()null and the record's QuickBooks ID inrecoveredObjectId()(on every batch result, nullable), onclient.requests().retrieve()and on an idempotent replay. - New error code
QBD_REQUEST_NOT_PROCESSED(ErrorCode.QBD_REQUEST_NOT_PROCESSED):409, not retryable. QuickBooks skipped a batch member because an earlier member failed understopOnError(status 3231). - Breaking (types only): the credit card request info of receive payments is the class
QbdRequest. It was read as the request resource classRequestby mistake, so its accessors returned null. - Change feed subscriptions:
client.changeFeedSubscriptions().create(),list(),retrieve(),update()anddelete()(/v1/change-feed-subscriptions). A subscription polls every connected end user of the project for changed and deleted records of the listed resources and sendsdata.changedwebhooks with their IDs. New webhook event typeWebhookEventType.DATA_CHANGED(data.changed). New error codeCHANGE_FEED_SUBSCRIPTION_LIMIT_REACHED(422, not retryable).
All versions: CHANGELOG.md.
v0.6.0
- Breaking: the list parameters type of
qbd.classes.listis renamed fromClasseListParamstoClassListParams(the generator dropped only the final "s" of "classes"). Rename the type in your code; nothing else changes. No other type name was affected. client.webhookEndpoints().rotateSecret()works: the API now honors the Idempotency-Key the client always sends (a retry returns the same new secret without rotating twice) and answers an unknown endpoint ID with404 RESOURCE_MISSING. It answered400 INVALID_PARAMETER.- New error code
QBD_SALES_TAX_THROUGH_DATE_TOO_EARLY(ErrorCode.QBD_SALES_TAX_THROUGH_DATE_TOO_EARLY):422, not retryable. QuickBooks refused a sales tax payment check and asked for a later sales tax 'through' date (status 3140); nothing changed. If the end user records the sales tax in QuickBooks instead, read and link that check rather than creating another. It answeredQBD_REFERENCE_NOT_FOUNDonvendorId. - A sales representative initial that is already in use answers
409 QBD_DUPLICATE_NAMEwithparaminitial(QuickBooks status 3180). It answered422 QBD_REQUEST_ERROR. QBD_OBJECT_IN_USEisretryableonly when the record is open or locked in QuickBooks. A deletion or void refused because other records still use the object isretryable: false, so the client no longer treats it as worth repeating.- Status 3390 (too many open QuickBooks list iterators) is
QBD_TRANSIENT_ERRORwithdetails.reasonmax_iterators. The API now stops the QuickBooks iterator of a cursor you stop reading (after about 10 seconds idle, or when a fourth cursor list starts for the same end user), so breaking out of a list loop early no longer uses up QuickBooks' iterator limit. - Report validation:
missing_checksrequiresaccountIdsoraccountFullNames, the job detail reports requireentityIdsorentityFullNames, andphysical_inventory_worksheetrejectsreportDateMacro, each with400 INVALID_PARAMETERnaming the parameter. Unit of measure set create rejectsisActive: false, which QuickBooks ignores. - New error code
QBD_TRANSIENT_ERROR(ErrorCode.QBD_TRANSIENT_ERROR):503, retryable, outcomenot_applied. QuickBooks was briefly busy (status 3390, or 3180 when a list was modified by another user) and changed nothing. The client retries it automatically with the same idempotency key, which now runs the write again instead of replaying the error. These answeredQBD_REQUEST_ERROR(422, not retryable).
All versions: CHANGELOG.md.