> ## Documentation Index > Fetch the complete documentation index at: https://docs.qubesync.com/llms.txt > Use this file to discover all available pages before exploring further. # List transactions > qbXML: `TransactionQueryRq`, from qbXML 4.0. TransactionQuery is a generic transaction query that provides functionality (e.g. filters) similar to the Advanced Find window in the QuickBooks UI. It allows you to search for transactions across different transaction types. In contrast to the other transaction-specific queries, the TransactionQuery only returns data common to all transactions, such as `txn_id`, type, dates, accountRef, and so on. This query does return condensed transactions. Accordingly, if additional and more transaction-specific data is required, a subsequent call to the desired query can be used to get that transaction-specific data. For example, the TransactionQuery can be used to present all transactions in a certain date range, then the user can select a particular transaction, say an invoice transaction. In response to this choice, you could do an InvoiceQuery to pull up all of the invoice data, similar to QuickZoom in the QuickBooks UI. **Important:** You should be aware that permissions are obeyed in this query. So, if you set the transaction type filter to “All” (or if you don’t set it at all), the query will be searching only those transaction types that are permissible types for the user currently logged in. Accordingly, if instead of “all,” you specify a transaction type that the currently logged in user isn’t permitted to access, you will get a runtime error, even if other permissible transaction types were specified as well. Finally, the transaction query is subject to sensitive data access level restrictions and payroll subscription status. Intuit's reference: [TransactionQuery](https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/transactionquery). ## OpenAPI ````yaml /api-reference/v2/openapi.json get /connections/{connection_id}/transactions openapi: 3.1.0 info: contact: email: support@qubesync.com description: > A single generic operation surface for every curated qbXML request QuBe Sync supports, driven directly off the qbXML schema -- see the [MCP server](/mcp-server) to explore available operations interactively. **Every endpoint queues a request and returns it immediately (`201`, a `QueuedRequest`).** QuickBooks Desktop is reached through the customer's Web Connector, which polls QuBe Sync, so the answer arrives seconds to minutes later. **Pass a `webhook_url` with every request**: when QuickBooks has answered, QuBe Sync POSTs the same document to it -- `state` set, `response_json` filled in -- signed with `X-QUBE-Signature` (see the Webhooks guide). `response_json` is the `{status, data}` envelope documented on each operation: `status: "success"` with `data` derived from the qbXML `*Ret` (and `warning`, QuickBooks' code and message, when it carried the request out but warned about it), or `status: "error"` with QuickBooks' own status code and message -- a QuickBooks business error is a *successful* HTTP round trip. `links.self` returns the request on demand (for a dashboard, a retry, a script); it is not the integration path. Send an `Idempotency-Key` header with each request so a call whose answer you never got can be sent again without queueing it twice. Authentication is HTTP Basic with your app's API key as the username and a blank password. Connections themselves (creating one, onboarding, its QWC file and password) are the `/connections` endpoints; every QuickBooks operation is scoped to one of them. title: QuBe Sync API (v2) version: 2.0.0 servers: - description: v2 API url: https://qubesync.com/api/v2 - description: Local development server url: https://dev.qubesync.com/api/v2 security: - apiKey: [] tags: - description: >- Creating and managing the connection (a customer's QuickBooks company file) that every request below is queued against. See the Onboarding guide. name: Connections - description: >- Queueing qbXML you wrote yourself, listing the requests queued on a connection, and discarding one the app no longer wants. A `webhook_url` on each request is the integration path (see the Webhooks guide): the listing is for a dashboard, a script, or catching up after downtime. name: Queued Requests - description: >- Finding the record in a customer's company file that a name means, even written differently: ranked matches from QuBe Sync's index of the file's names, on realtime and simulated connections. See the Matching guide. name: Matching - description: >- Endpoints for publishing workflow definitions, starting runs, and answering a run that is waiting on a decision from your app. A workflow is one JSON statechart document; see the schema at /api/v2/workflows/schema.json. name: Workflows - name: Account Tax Line Infos - name: Accounts - name: Aging Reports - name: Alerts - name: Ar Refund Credit Cards - name: Bar Codes - name: Bill Payment Checks - name: Bill Payment Credit Cards - name: Bill To Pays - name: Billing Rates - name: Bills - name: Budget Summary Reports - name: Build Assemblies - name: Charges - name: Checks - name: Classes - name: Cleared Statuses - name: Companies - name: Company Activities - name: Credit Card Charges - name: Credit Card Credits - name: Credit Memos - name: Currencies - name: Custom Detail Reports - name: Custom Summary Reports - name: Customer Msgs - name: Customer Types - name: Customers - name: Data Event Recovery Infos - name: Data Ext Defs - name: Data Exts - name: Date Driven Terms - name: Deposits - name: Employee Defaults - name: Employees - name: Entities - name: Estimates - name: Form1099 Category Account Mappings - name: General Detail Reports - name: General Summary Reports - name: Hosts - name: Inventory Adjustments - name: Inventory Sites - name: Invoices - name: Item Assemblies Can Builds - name: Item Discounts - name: Item Fixed Assets - name: Item Groups - name: Item Inventories - name: Item Inventory Assemblies - name: Item Non Inventories - name: Item Other Charges - name: Item Payments - name: Item Receipts - name: Item Sales Tax Groups - name: Item Sales Taxes - name: Item Services - name: Item Sites - name: Item Subtotals - name: Items - name: Job Reports - name: Job Types - name: Journal Entries - name: Leads - name: List Deleteds - name: List Displays - name: List Merge - name: Lists - name: Other Names - name: Paychecks - name: Payment Methods - name: Payments - name: Payroll Detail Reports - name: Payroll Item Additions - name: Payroll Item Company Contributions - name: Payroll Item Deductions - name: Payroll Item Direct Deposits - name: Payroll Item Non Wages - name: Payroll Item Taxes - name: Payroll Item Wages - name: Payroll Item Workers Compensations - name: Payroll Items - name: Payroll Last Periods - name: Payroll Liability Adjustments - name: Payroll Liability Checks - name: Payroll Prior Payments - name: Payroll Summary Reports - name: Payroll Year To Date Adjustments - name: Preferences - name: Price Levels - name: Purchase Orders - name: Qb Command Exec - name: Receive Payment To Deposits - name: Receive Payments - name: Sales Orders - name: Sales Receipts - name: Sales Reps - name: Sales Tax Codes - name: Sales Tax Payables - name: Sales Tax Payment Checks - name: Sales Tax Return Lines - name: Sales Tax Returns - name: Ship Methods - name: Special Accounts - name: Special Items - name: Standard Terms - name: Templates - name: Terms - name: Time Reports - name: Time Trackings - name: To Dos - name: Transactions - name: Transfer Inventories - name: Transfers - name: Txn Deleteds - name: Txn Displays - name: Txn Void - name: Txns - name: Unit Of Measure Sets - name: Vehicle Mileages - name: Vehicles - name: Vendor Credits - name: Vendor Types - name: Vendors - name: Workers Comp Codes paths: /connections/{connection_id}/transactions: get: tags: - Transactions summary: List transactions description: >- qbXML: `TransactionQueryRq`, from qbXML 4.0. TransactionQuery is a generic transaction query that provides functionality (e.g. filters) similar to the Advanced Find window in the QuickBooks UI. It allows you to search for transactions across different transaction types. In contrast to the other transaction-specific queries, the TransactionQuery only returns data common to all transactions, such as `txn_id`, type, dates, accountRef, and so on. This query does return condensed transactions. Accordingly, if additional and more transaction-specific data is required, a subsequent call to the desired query can be used to get that transaction-specific data. For example, the TransactionQuery can be used to present all transactions in a certain date range, then the user can select a particular transaction, say an invoice transaction. In response to this choice, you could do an InvoiceQuery to pull up all of the invoice data, similar to QuickZoom in the QuickBooks UI. **Important:** You should be aware that permissions are obeyed in this query. So, if you set the transaction type filter to “All” (or if you don’t set it at all), the query will be searching only those transaction types that are permissible types for the user currently logged in. Accordingly, if instead of “all,” you specify a transaction type that the currently logged in user isn’t permitted to access, you will get a runtime error, even if other permissible transaction types were specified as well. Finally, the transaction query is subject to sensitive data access level restrictions and payroll subscription status. Intuit's reference: [TransactionQuery](https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/transactionquery). operationId: listTransactions parameters: - description: >- The connection (a customer's QuickBooks company file) this request is queued for. in: path name: connection_id required: true schema: format: uuid type: string - description: >- Your own label for the request, sent to QuickBooks as its qbXML `requestID` and echoed in the raw answer (`response_xml`); optional, since the answer's webhook already carries the request's `id`. in: query name: request_id required: false schema: type: string - description: >- Use the `meta_data` attribute to control whether query responses include counts. Options are NoMetaData (default), MetaDataOnly (count only), and MetaDataAndResponseData (count plus objects). Counts are approximate and may vary slightly if records are created or deleted during processing. in: query name: meta_data required: false schema: enum: - MetaDataAndResponseData - MetaDataOnly - NoMetaData type: string - description: >- Page through every match: QuBe Sync asks QuickBooks for each page in turn and sends each to your `webhook_url` as it arrives, all with the same `id`. On by default, with pages of 100 records; send `iterator=true` with `max_returned` for another size. Off when you send `iterator=false` (every match in one answer) or `max_returned` alone (at most that many, in one answer). It pages a filtered query only: with `txn_id` every match comes back in one answer, so leave `iterator` out. in: query name: iterator required: false schema: type: boolean - description: >- Filters by the specified currency. Choose at most one of: `txn_id`, or the set (`currency_filter`, `max_returned`, `ref_number`, `ref_number_case_sensitive`, `ref_number_filter`, `ref_number_range_filter`, `transaction_account_filter`, `transaction_class_filter`, `transaction_date_range_filter`, `transaction_detail_level_filter`, `transaction_entity_filter`, `transaction_item_filter`, `transaction_modified_date_range_filter`, `transaction_paid_status_filter`, `transaction_posting_status_filter`, `transaction_type_filter`). Members of a set combine with each other, not with the other choices. in: query name: currency_filter required: false schema: oneOf: - properties: list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. items: type: string type: array required: - list_id title: ListID type: object - properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. items: type: string type: array required: - full_name title: FullName type: object type: object - in: query name: include_ret_element required: false schema: items: enum: - AccountRef - Amount - AmountInHomeCurrency - CurrencyRef - EntityRef - ExchangeRate - Memo - RefNumber - TimeCreated - TimeModified - TxnDate - TxnID - TxnLineID - TxnType type: string type: array - description: >- Limits the number of objects that a query returns. (To get a count of how many objects could possibly be returned, use the `meta_data` query attribute.) If you include a `max_returned` value, it must be at least 1. The page size, with `iterator=true`. Sent without `iterator`, or with `iterator=false`, it's a cap instead: at most this many records come back, in one answer, and QuickBooks doesn't say whether more matched. Choose at most one of: `txn_id`, or the set (`currency_filter`, `max_returned`, `ref_number`, `ref_number_case_sensitive`, `ref_number_filter`, `ref_number_range_filter`, `transaction_account_filter`, `transaction_class_filter`, `transaction_date_range_filter`, `transaction_detail_level_filter`, `transaction_entity_filter`, `transaction_item_filter`, `transaction_modified_date_range_filter`, `transaction_paid_status_filter`, `transaction_posting_status_filter`, `transaction_type_filter`). Members of a set combine with each other, not with the other choices. in: query name: max_returned required: false schema: minimum: 1 type: integer - description: >- `ref_number` is a user-managed transaction reference (for example, a check number). It can be edited and is not guaranteed to be globally unique. Some transaction types auto-populate `ref_number` when omitted, based on QuickBooks preferences and numbering state. Choose at most one of: `txn_id`, or the set (`currency_filter`, `max_returned`, `ref_number`, `ref_number_case_sensitive`, `ref_number_filter`, `ref_number_range_filter`, `transaction_account_filter`, `transaction_class_filter`, `transaction_date_range_filter`, `transaction_detail_level_filter`, `transaction_entity_filter`, `transaction_item_filter`, `transaction_modified_date_range_filter`, `transaction_paid_status_filter`, `transaction_posting_status_filter`, `transaction_type_filter`). Members of a set combine with each other, not with the other choices. in: query name: ref_number required: false schema: items: type: string type: array - description: >- Choose at most one of: `txn_id`, or the set (`currency_filter`, `max_returned`, `ref_number`, `ref_number_case_sensitive`, `ref_number_filter`, `ref_number_range_filter`, `transaction_account_filter`, `transaction_class_filter`, `transaction_date_range_filter`, `transaction_detail_level_filter`, `transaction_entity_filter`, `transaction_item_filter`, `transaction_modified_date_range_filter`, `transaction_paid_status_filter`, `transaction_posting_status_filter`, `transaction_type_filter`). Members of a set combine with each other, not with the other choices. in: query name: ref_number_case_sensitive required: false schema: items: type: string type: array - description: >- Filters by `ref_number` range. Numeric-only bounds are compared numerically; otherwise comparison is lexicographic. Choose at most one of: `txn_id`, or the set (`currency_filter`, `max_returned`, `ref_number`, `ref_number_case_sensitive`, `ref_number_filter`, `ref_number_range_filter`, `transaction_account_filter`, `transaction_class_filter`, `transaction_date_range_filter`, `transaction_detail_level_filter`, `transaction_entity_filter`, `transaction_item_filter`, `transaction_modified_date_range_filter`, `transaction_paid_status_filter`, `transaction_posting_status_filter`, `transaction_type_filter`). Members of a set combine with each other, not with the other choices. in: query name: ref_number_filter required: false schema: properties: match_criterion: description: The criterion to match. enum: - Contains - EndsWith - StartsWith type: string ref_number: description: >- `ref_number` is a user-managed transaction reference (for example, a check number). It can be edited and is not guaranteed to be globally unique. Some transaction types auto-populate `ref_number` when omitted, based on QuickBooks preferences and numbering state. type: string required: - match_criterion - ref_number type: object - description: >- Filters by `ref_number` range. Numeric-only bounds are compared numerically; otherwise comparison is lexicographic. Choose at most one of: `txn_id`, or the set (`currency_filter`, `max_returned`, `ref_number`, `ref_number_case_sensitive`, `ref_number_filter`, `ref_number_range_filter`, `transaction_account_filter`, `transaction_class_filter`, `transaction_date_range_filter`, `transaction_detail_level_filter`, `transaction_entity_filter`, `transaction_item_filter`, `transaction_modified_date_range_filter`, `transaction_paid_status_filter`, `transaction_posting_status_filter`, `transaction_type_filter`). Members of a set combine with each other, not with the other choices. in: query name: ref_number_range_filter required: false schema: properties: from_ref_number: description: >- The first `ref_number` in the search range. If `from_ref_number` is omitted, the range will begin with first number on the list. type: string to_ref_number: description: >- The final `ref_number` in the search range. If `to_ref_number` is omitted, the range will end with last number on the list. type: string type: object - description: >- Filters the transactions based on the `account_ref` in the transaction or transaction line using an account type filter or a specific `list_id`, or a `full_name`, or a `list_id_with_children`, or a `full_name_with_children`. To filter on transaction lines, you must specify the `transaction_detail_level_filter` with a value of either “All” or “AllExceptSummary”. Choose at most one of: `txn_id`, or the set (`currency_filter`, `max_returned`, `ref_number`, `ref_number_case_sensitive`, `ref_number_filter`, `ref_number_range_filter`, `transaction_account_filter`, `transaction_class_filter`, `transaction_date_range_filter`, `transaction_detail_level_filter`, `transaction_entity_filter`, `transaction_item_filter`, `transaction_modified_date_range_filter`, `transaction_paid_status_filter`, `transaction_posting_status_filter`, `transaction_type_filter`). Members of a set combine with each other, not with the other choices. in: query name: transaction_account_filter required: false schema: oneOf: - properties: account_type_filter: description: Allows you to report on a specific account type. enum: - APAndSalesTax - APOrCreditCard - ARAndAP - AccountsPayable - AccountsReceivable - AllowedFor1099 - Asset - BalanceSheet - Bank - BankAndARAndAPAndUF - BankAndUF - CostOfSales - CreditCard - CurrentAsset - CurrentAssetAndExpense - CurrentLiability - Equity - EquityAndIncomeAndExpense - ExpenseAndOtherExpense - FixedAsset - IncomeAndExpense - IncomeAndOtherIncome - Liability - LiabilityAndEquity - LongTermLiability - NonPosting - OrdinaryExpense - OrdinaryIncome - OrdinaryIncomeAndCOGS - OrdinaryIncomeAndExpense - OtherAsset - OtherCurrentAsset - OtherCurrentLiability - OtherExpense - OtherIncome - OtherIncomeOrExpense type: string required: - account_type_filter title: AccountTypeFilter type: object - properties: list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. items: type: string type: array required: - list_id title: ListID type: object - properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. items: type: string type: array required: - full_name title: FullName type: object - properties: list_id_with_children: description: >- Allows you to filter for data that relates to the specified object and its descendants. type: string required: - list_id_with_children title: ListIDWithChildren type: object - properties: full_name_with_children: description: >- Allows you to filter for data that relates to the specified object and its descendants. For names that don’t have children, `full_name_with_children` is exactly the same as `full_name`. type: string required: - full_name_with_children title: FullNameWithChildren type: object type: object - description: >- Filters the transactions based on the ClassRef in the transaction or transaction line by using a specific `list_id`, or a `full_name`, or a `list_id_with_children`, or a `full_name_with_children`. To filter on transaction lines, you must specify the `transaction_detail_level_filter` with a value of either “All” or “AllExceptSummary”. Choose at most one of: `txn_id`, or the set (`currency_filter`, `max_returned`, `ref_number`, `ref_number_case_sensitive`, `ref_number_filter`, `ref_number_range_filter`, `transaction_account_filter`, `transaction_class_filter`, `transaction_date_range_filter`, `transaction_detail_level_filter`, `transaction_entity_filter`, `transaction_item_filter`, `transaction_modified_date_range_filter`, `transaction_paid_status_filter`, `transaction_posting_status_filter`, `transaction_type_filter`). Members of a set combine with each other, not with the other choices. in: query name: transaction_class_filter required: false schema: oneOf: - properties: list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. items: type: string type: array required: - list_id title: ListID type: object - properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. items: type: string type: array required: - full_name title: FullName type: object - properties: list_id_with_children: description: >- Allows you to filter for data that relates to the specified object and its descendants. type: string required: - list_id_with_children title: ListIDWithChildren type: object - properties: full_name_with_children: description: >- Allows you to filter for data that relates to the specified object and its descendants. For names that don’t have children, `full_name_with_children` is exactly the same as `full_name`. type: string required: - full_name_with_children title: FullNameWithChildren type: object type: object - description: >- Filters the transactions based on the transaction’s date either by specifying a “from” and/or “to” date, or by using a `date_macro`. Choose at most one of: `txn_id`, or the set (`currency_filter`, `max_returned`, `ref_number`, `ref_number_case_sensitive`, `ref_number_filter`, `ref_number_range_filter`, `transaction_account_filter`, `transaction_class_filter`, `transaction_date_range_filter`, `transaction_detail_level_filter`, `transaction_entity_filter`, `transaction_item_filter`, `transaction_modified_date_range_filter`, `transaction_paid_status_filter`, `transaction_posting_status_filter`, `transaction_type_filter`). Members of a set combine with each other, not with the other choices. in: query name: transaction_date_range_filter required: false schema: oneOf: - not: properties: from_txn_date: false to_txn_date: false properties: from_txn_date: description: >- Selects transactions created on or after this date. Both `from_txn_date` and `to_txn_date` must be between 01/01/1901 and 12/31/9999. If you omit `from_txn_date`, it will be set to 1970-01-01 (1969-12-31 PST). format: date type: string to_txn_date: description: >- Selects transactions created on or before this date. Both `to_txn_date` and `from_txn_date` must be between 01/01/1901 and 12/31/9999. If you omit `to_txn_date`, it will be set to 2038-01-19 (2038-01-18 PST). format: date type: string title: FromTxnDate + ToTxnDate type: object - properties: date_macro: description: >- `date_macro` filters by transaction date (not last-modified date). Do not combine `date_macro` with `from_modified_date`/`to_modified_date` in the same query filter set. enum: - All - LastCalendarQuarter - LastCalendarQuarterToDate - LastCalendarYear - LastCalendarYearToDate - LastFiscalQuarter - LastFiscalQuarterToDate - LastFiscalYear - LastFiscalYearToDate - LastMonth - LastMonthToDate - LastWeek - LastWeekToDate - NextCalendarQuarter - NextCalendarYear - NextFiscalQuarter - NextFiscalYear - NextFourWeeks - NextMonth - NextWeek - ThisCalendarQuarter - ThisCalendarQuarterToDate - ThisCalendarYear - ThisCalendarYearToDate - ThisFiscalQuarter - ThisFiscalQuarterToDate - ThisFiscalYear - ThisFiscalYearToDate - ThisMonth - ThisMonthToDate - ThisWeek - ThisWeekToDate - Today - Yesterday type: string required: - date_macro title: DateMacro type: object type: object - description: >- Allows you to specify the detail level of the query results. You can specify all, summary only (the default), or all except summary. Summary only refers to the transaction as a whole, whereas all except summary refers to the transaction lines. Choose at most one of: `txn_id`, or the set (`currency_filter`, `max_returned`, `ref_number`, `ref_number_case_sensitive`, `ref_number_filter`, `ref_number_range_filter`, `transaction_account_filter`, `transaction_class_filter`, `transaction_date_range_filter`, `transaction_detail_level_filter`, `transaction_entity_filter`, `transaction_item_filter`, `transaction_modified_date_range_filter`, `transaction_paid_status_filter`, `transaction_posting_status_filter`, `transaction_type_filter`). Members of a set combine with each other, not with the other choices. in: query name: transaction_detail_level_filter required: false schema: enum: - All - AllExceptSummary - SummaryOnly type: string - description: >- Filters the transactions based on the `entity_ref` used in the transaction or transaction line by specifying an entity type filter, a `list_id`, a `full_name`, a `list_id_with_children`, or a `full_name_with_children`. If you want to filter on transaction lines you must specify the `transaction_detail_level_filter` with a value of either “All” or “AllExceptSummary”. Choose at most one of: `txn_id`, or the set (`currency_filter`, `max_returned`, `ref_number`, `ref_number_case_sensitive`, `ref_number_filter`, `ref_number_range_filter`, `transaction_account_filter`, `transaction_class_filter`, `transaction_date_range_filter`, `transaction_detail_level_filter`, `transaction_entity_filter`, `transaction_item_filter`, `transaction_modified_date_range_filter`, `transaction_paid_status_filter`, `transaction_posting_status_filter`, `transaction_type_filter`). Members of a set combine with each other, not with the other choices. in: query name: transaction_entity_filter required: false schema: oneOf: - properties: entity_type_filter: description: Allows you to report on a specific name type. enum: - Customer - Employee - OtherName - Vendor type: string required: - entity_type_filter title: EntityTypeFilter type: object - properties: list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. items: type: string type: array required: - list_id title: ListID type: object - properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. items: type: string type: array required: - full_name title: FullName type: object - properties: list_id_with_children: description: >- Allows you to filter for data that relates to the specified object and its descendants. type: string required: - list_id_with_children title: ListIDWithChildren type: object - properties: full_name_with_children: description: >- Allows you to filter for data that relates to the specified object and its descendants. For names that don’t have children, `full_name_with_children` is exactly the same as `full_name`. type: string required: - full_name_with_children title: FullNameWithChildren type: object type: object - description: >- Filters the transactions based on the ItemRef used in the transaction line using an item type filter, or a specific `list_id`, or a `full_name`, or a `list_id_with_children`, or a `full_name_with_children`. To filter on transaction lines, you must specify the `transaction_detail_level_filter` with a value of either “All” or “AllExceptSummary”. Choose at most one of: `txn_id`, or the set (`currency_filter`, `max_returned`, `ref_number`, `ref_number_case_sensitive`, `ref_number_filter`, `ref_number_range_filter`, `transaction_account_filter`, `transaction_class_filter`, `transaction_date_range_filter`, `transaction_detail_level_filter`, `transaction_entity_filter`, `transaction_item_filter`, `transaction_modified_date_range_filter`, `transaction_paid_status_filter`, `transaction_posting_status_filter`, `transaction_type_filter`). Members of a set combine with each other, not with the other choices. in: query name: transaction_item_filter required: false schema: oneOf: - properties: item_type_filter: description: Allows you to report on a specific item type. enum: - AllExceptFixedAsset - Assembly - Discount - FixedAsset - Inventory - InventoryAndAssembly - NonInventory - OtherCharge - Payment - Sales - SalesTax - Service type: string required: - item_type_filter title: ItemTypeFilter type: object - properties: list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. items: type: string type: array required: - list_id title: ListID type: object - properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. items: type: string type: array required: - full_name title: FullName type: object - properties: list_id_with_children: description: >- Allows you to filter for data that relates to the specified object and its descendants. type: string required: - list_id_with_children title: ListIDWithChildren type: object - properties: full_name_with_children: description: >- Allows you to filter for data that relates to the specified object and its descendants. For names that don’t have children, `full_name_with_children` is exactly the same as `full_name`. type: string required: - full_name_with_children title: FullNameWithChildren type: object type: object - description: >- Filters the transactions based on the transaction’s modified datetime, either by specifying a “from” and/or “to” date or by using a `date_macro`. Choose at most one of: `txn_id`, or the set (`currency_filter`, `max_returned`, `ref_number`, `ref_number_case_sensitive`, `ref_number_filter`, `ref_number_range_filter`, `transaction_account_filter`, `transaction_class_filter`, `transaction_date_range_filter`, `transaction_detail_level_filter`, `transaction_entity_filter`, `transaction_item_filter`, `transaction_modified_date_range_filter`, `transaction_paid_status_filter`, `transaction_posting_status_filter`, `transaction_type_filter`). Members of a set combine with each other, not with the other choices. in: query name: transaction_modified_date_range_filter required: false schema: oneOf: - not: properties: from_modified_date: false to_modified_date: false properties: from_modified_date: description: >- Filters results to objects modified on or after this timestamp. QuickBooks Desktop accepts 1970-01-01 through 2038-01-19T03:14:07. If only a date is provided, time defaults to 00:00:00. format: date-time type: string to_modified_date: description: >- Filters results to objects modified on or before this timestamp. QuickBooks Desktop accepts 1970-01-01 through 2038-01-19T03:14:07. If only a date is provided, time defaults to end-of-day (23:59:59). format: date-time type: string title: FromModifiedDate + ToModifiedDate type: object - properties: date_macro: description: >- `date_macro` filters by transaction date (not last-modified date). Do not combine `date_macro` with `from_modified_date`/`to_modified_date` in the same query filter set. enum: - All - LastCalendarQuarter - LastCalendarQuarterToDate - LastCalendarYear - LastCalendarYearToDate - LastFiscalQuarter - LastFiscalQuarterToDate - LastFiscalYear - LastFiscalYearToDate - LastMonth - LastMonthToDate - LastWeek - LastWeekToDate - NextCalendarQuarter - NextCalendarYear - NextFiscalQuarter - NextFiscalYear - NextFourWeeks - NextMonth - NextWeek - ThisCalendarQuarter - ThisCalendarQuarterToDate - ThisCalendarYear - ThisCalendarYearToDate - ThisFiscalQuarter - ThisFiscalQuarterToDate - ThisFiscalYear - ThisFiscalYearToDate - ThisMonth - ThisMonthToDate - ThisWeek - ThisWeekToDate - Today - Yesterday type: string required: - date_macro title: DateMacro type: object type: object - description: >- This filter allows you to search for “open” transactions, i.e. transactions with a remaining balance (for example, credits not fully applied or invoices not fully paid). Valid values are closed, open, or either, which is the default. Choose at most one of: `txn_id`, or the set (`currency_filter`, `max_returned`, `ref_number`, `ref_number_case_sensitive`, `ref_number_filter`, `ref_number_range_filter`, `transaction_account_filter`, `transaction_class_filter`, `transaction_date_range_filter`, `transaction_detail_level_filter`, `transaction_entity_filter`, `transaction_item_filter`, `transaction_modified_date_range_filter`, `transaction_paid_status_filter`, `transaction_posting_status_filter`, `transaction_type_filter`). Members of a set combine with each other, not with the other choices. in: query name: transaction_paid_status_filter required: false schema: enum: - Closed - Either - Open type: string - description: >- Allows you to filter transactions based on posting status. Valid values are posting, non-posting, or either. The default is “either.” (Posting status refers to whether QuickBooks records a transaction in one of your account registers.) Choose at most one of: `txn_id`, or the set (`currency_filter`, `max_returned`, `ref_number`, `ref_number_case_sensitive`, `ref_number_filter`, `ref_number_range_filter`, `transaction_account_filter`, `transaction_class_filter`, `transaction_date_range_filter`, `transaction_detail_level_filter`, `transaction_entity_filter`, `transaction_item_filter`, `transaction_modified_date_range_filter`, `transaction_paid_status_filter`, `transaction_posting_status_filter`, `transaction_type_filter`). Members of a set combine with each other, not with the other choices. in: query name: transaction_posting_status_filter required: false schema: enum: - Either - NonPosting - Posting type: string - description: >- Filters the transactions based on the transaction’s type. You can specify one or more transaction types in the filter. Notice that TimeTracking transactions aren’t supported. If you set the transaction type filter to “All” (or if you don’t set it at all), the query will be searching only those transaction types that are permissible types for the user currently logged in. Choose at most one of: `txn_id`, or the set (`currency_filter`, `max_returned`, `ref_number`, `ref_number_case_sensitive`, `ref_number_filter`, `ref_number_range_filter`, `transaction_account_filter`, `transaction_class_filter`, `transaction_date_range_filter`, `transaction_detail_level_filter`, `transaction_entity_filter`, `transaction_item_filter`, `transaction_modified_date_range_filter`, `transaction_paid_status_filter`, `transaction_posting_status_filter`, `transaction_type_filter`). Members of a set combine with each other, not with the other choices. in: query name: transaction_type_filter required: false schema: properties: txn_type_filter: items: enum: - ARRefundCreditCard - All - Bill - BillPaymentCheck - BillPaymentCreditCard - BuildAssembly - Charge - Check - CreditCardCharge - CreditCardCredit - CreditMemo - Deposit - Estimate - InventoryAdjustment - Invoice - ItemReceipt - JournalEntry - LiabilityAdjustment - Paycheck - PayrollLiabilityCheck - PurchaseOrder - ReceivePayment - SalesOrder - SalesReceipt - SalesTaxPaymentCheck - Transfer - VendorCredit - YTDAdjustment type: string type: array required: - txn_type_filter type: object - description: >- `txn_id` is the unique QuickBooks identifier for a transaction. Use it to reference that transaction in later requests. `txn_id` values are transaction-specific and should not be reused across unrelated transaction types. Choose at most one of: `txn_id`, or the set (`currency_filter`, `max_returned`, `ref_number`, `ref_number_case_sensitive`, `ref_number_filter`, `ref_number_range_filter`, `transaction_account_filter`, `transaction_class_filter`, `transaction_date_range_filter`, `transaction_detail_level_filter`, `transaction_entity_filter`, `transaction_item_filter`, `transaction_modified_date_range_filter`, `transaction_paid_status_filter`, `transaction_posting_status_filter`, `transaction_type_filter`). Members of a set combine with each other, not with the other choices. in: query name: txn_id required: false schema: items: type: string type: array - description: >- Where QuBe Sync POSTs the answered request (this same document with `response_json` filled in), signed with `X-QUBE-Signature`. Send one with every request: it is how answers are delivered. Optional only so a script can queue and look up `links.self` by hand. It must be an absolute http or https URL. It may not contain a username or password, and in production it may not point at localhost or a private, loopback or link-local address. A `qube listen` URL must be one of this app's. in: query name: webhook_url required: false schema: format: uri maxLength: 2048 type: string - $ref: '#/components/parameters/IdempotencyKey' responses: '201': content: application/json: schema: properties: data: allOf: - $ref: '#/components/schemas/QueuedRequest' - properties: response_json: anyOf: - $ref: >- #/components/schemas/listTransactions_response_json - type: 'null' description: '`null` until answered.' type: object required: - data type: object description: >- Queued for the connection's Web Connector. Pass `webhook_url` and QuBe Sync POSTs the answer to it once QuickBooks has answered (see the `answered` callback: its own payload, not this document). `links.self` returns this document on demand, with `response_json` filled in. headers: Idempotent-Replayed: $ref: '#/components/headers/IdempotentReplayed' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/SandboxPaused' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' callbacks: answered: '{$request.query.webhook_url}': post: description: > Verify `X-QUBE-Signature`, answer 2xx within 5 seconds, then branch on `state`: * `response_received` -- QuickBooks accepted it: `response_json` is `status: "success"` with `data`, or, when there is nothing to show, QuickBooks' `message` (a query that matched nothing is a success, not an error). When QuickBooks carried it out but warned about something, `response_json.warning` has its `code` and `message`: `530`, for one, means a field you sent is not supported by the customer's QuickBooks and was not saved. * `error` -- it is over, and QuBe Sync won't try again. With `error.error_type` `quickbooks_business_error`, QuickBooks refused the request: `response_json` is `status: "error"`, and `response_json.error.code` is the status code to branch on. A `3200` (`stale_edit_sequence`: the record changed after you read it) usually comes with the record as it stands in `response_json.error.current`, its current `edit_sequence` included. Compare it with what you read first: when nobody else changed a field your update sets, re-apply your change and send it again with that `edit_sequence`; when someone did, ask your user which value wins rather than overwriting theirs (without `current`, query the record first). Otherwise QuickBooks never answered it: `xml_error` (the request itself was rejected, and will be again as sent), `outcome_unknown` (a write the Web Connector answered with an error in place of QuickBooks' answer: it may have been applied, so look in QuickBooks before sending it again) or `unexpected_error` (the Web Connector's log says more; a query can be sent again). A connection problem never ends here; it is `retryable`, below. * `retryable` -- the Web Connector could not get it into QuickBooks (QuickBooks was not running, the company file was not open or not this connection's, or a window in QuickBooks was in the way), so nothing was applied. QuBe Sync keeps trying on the Web Connector's runs, so don't resend: show the customer `error.user_message` so they can fix it. This webhook comes when the error first appears or changes, not on every try. If you no longer want the request, discard it (`POST /connections/{connection_id}/queued-requests/{id}/discard`). * `timed_out` -- no answer came back: the customer's computer lost its connection, or QuickBooks or the Web Connector was closed, while QuickBooks had the request. QuickBooks may still have applied it, so look before sending it again. `error.error_type` is `timed_out`. * `discarded` -- your app discarded it before the Web Connector picked it up. QuickBooks never got it, so nothing was applied. `error.error_type` is `discarded`, unless it was `retryable` when you discarded it: then `error` is still the connection error that held it up. An iterated query sends one webhook per page, all with the same `id` and each with its own `page_request_id` and `page`; `iteration_state` is `done` on the last page, which can arrive before earlier ones, so the import is complete once every page from 1 to the `done` page's `page` has been handled. Deliveries can arrive out of order and, after a retry, more than once: key on `page_request_id` plus `state`. A `retryable` webhook is not final: the answer that follows carries the same `id` and `page_request_id` with a different `state`, and only a repeat of the same `state` is a duplicate. A body that would be over 1 MB comes without `response_xml`: `response_xml_omitted` is true, and `links.self` is where to GET it; `response_json` is always there. If webhooks stop arriving altogether, the Web Connector on the customer's PC has most likely stopped calling in; requests wait until it does. Intuit's guide to its errors: https://quickbooks.intuit.com/learn-support/en-us/help-article/open-programs/fix-common-web-connector-errors-quickbooks-desktop/L9slolvg0_US_en_US requestBody: content: application/json: schema: description: >- POSTed to `webhook_url` as JSON, signed with `X-QUBE-Signature` (`t=,v1=." with your app's webhook secret>`). properties: app_id: description: Your app's id. format: uuid type: string app_name: type: string error: description: >- Set when `state` is `error`, `retryable`, `timed_out` or `discarded`. `error_type` says where it failed: for a `timed_out` request it is `timed_out`, and for a `discarded` one `discarded`, unless the request was `retryable` when your app discarded it, which keeps the connection error that held it up. `user_message` is safe to show an end user; `error_code` is QuickBooks' own status code for a business error, `hresult` the Web Connector's for a connection/XML error; `debug_message` is for you. properties: debug_message: description: >- Which element of the request the value came from, when known. type: - string - 'null' error_code: description: QuickBooks' statusCode, for a business error. type: - integer - 'null' error_type: description: >- `quickbooks_business_error`: QuickBooks refused the request -- `response_json.error` has its code. `quickbooks_connection_error`: the Web Connector ran on the customer's PC but could not get the request into QuickBooks, so nothing was applied -- QuickBooks was not running, the company file was not open or not the one this connection belongs to, or a window or message box open in QuickBooks was in the way. Only the customer can fix that, and `user_message` tells them how. `xml_error`: QuickBooks could not parse the qbXML; sent again as-is, it fails again. `outcome_unknown`: a write the Web Connector answered with an error in place of QuickBooks' answer, so whether QuickBooks applied it is not known: look in QuickBooks before sending it again. `unexpected_error`: anything else; for a query, which changes nothing, sending it again is safe. `timed_out`: no answer came back -- the customer's computer lost its connection, or QuickBooks or the Web Connector was closed, while QuickBooks had the request. QuickBooks may still have applied it, so look before sending it again. `discarded`: your app discarded it before the Web Connector picked it up, so QuickBooks never got it. `response_too_large`: QuickBooks answered, but with more than QuBe Sync accepts for one answer (4 MB as the Web Connector sends it, about 3 MB of qbXML), so the answer wasn't kept and `response_json` is null. QuickBooks ran the request. Page the query (`iterator` and a smaller `max_returned`), or narrow it when QuickBooks doesn't page it; for a write, look before sending it again. Web Connector problems on the customer's PC (its password, log file, the .QWC file) never reach QuBe Sync as an error: the Web Connector just stops calling in, and requests wait. Intuit's guide for those: https://quickbooks.intuit.com/learn-support/en-us/help-article/open-programs/fix-common-web-connector-errors-quickbooks-desktop/L9slolvg0_US_en_US enum: - xml_error - quickbooks_connection_error - quickbooks_business_error - unexpected_error - response_too_large - outcome_unknown - timed_out - discarded type: string hresult: description: >- The Web Connector's HRESULT (e.g. `0x80040400`), for a connection or XML error. Informational: branch on `error_type`, not on this. type: - string - 'null' message: description: >- The raw message from QuickBooks or the Web Connector; for `timed_out` and `discarded`, which neither sent, QuBe Sync's own. type: string user_message: description: A friendly message for the end user. type: string type: - object - 'null' id: description: >- The request's id, as the 201 returned it. For an iterated query, every page carries the first page's id here. format: uuid type: string iteration_state: description: >- `continue`: more pages will follow, each its own webhook. `done`: this was the last page. `max_sandbox_iterations_reached`: a sandbox app's page limit stopped the iteration. enum: - not_applicable - continue - done - max_sandbox_iterations_reached type: string links: description: Present only with `response_xml_omitted`. properties: self: description: >- This page's request in the API, `response_xml` included. format: uri type: string type: object page: description: The page number, when iterated. type: - integer - 'null' page_request_id: description: >- This page's own id. Equal to `id` except on later pages of an iterated query. format: uuid type: string response_json: $ref: '#/components/schemas/listTransactions_response_json' response_xml: description: >- QuickBooks' raw qbXML answer. `response_json` is the same, summarized. One answer can be at most 4 MB as the Web Connector sends it, about 3 MB of qbXML; QuickBooks' answer over that isn't kept: this is null and `error.error_type` is `response_too_large`. A webhook whose body would be over 1 MB is sent without it: null, with `response_xml_omitted` true; fetch it from `links.self`. type: - string - 'null' response_xml_omitted: description: >- Present, and true, only when `response_xml` was left out to keep the body under 1 MB. `response_json` is still here; GET `links.self` for `response_xml`. type: boolean sandbox: description: Whether the app is a sandbox app. type: boolean state: description: >- `response_received`: QuickBooks accepted it; read `response_json`. `error`: it is over and QuBe Sync won't try again -- see `error`, and `response_json.error` for a QuickBooks business error; with `error_type` `outcome_unknown` a write may still have been applied, so look before sending it again. `retryable`: QuickBooks could not be reached and QuBe Sync keeps trying; show the customer `error.user_message` so they can fix it. `timed_out`: no answer came back -- the customer's computer lost its connection, or QuickBooks or the Web Connector was closed, mid-request. QuickBooks may still have applied it, so look before sending it again. `discarded`: your app discarded it before the Web Connector picked it up, so QuickBooks never got it. Both carry an `error`. enum: - response_received - error - retryable - timed_out - discarded type: string timestamp: description: Unix seconds; the same `t` the signature covers. type: integer required: - app_id - app_name - sandbox - timestamp - id - page_request_id - state - response_json - error type: object required: true responses: 2XX: description: >- Received. Anything else is retried with backoff for about 8 hours. summary: QuickBooks answered (or the request failed) method: post type: path path: '{$request.query.webhook_url}' components: parameters: IdempotencyKey: description: >- Makes a retry safe when you never got the answer to a call: a timeout, a dropped connection, a worker that crashed. Send a new key (a UUID, say) with each request you mean to make once, and the same key when you send that request again. A repeat with the key and the same method, path, query and body answers `201` with what the first call created, as it is now, marked `Idempotent-Replayed: true`, and queues nothing. The same key with a different request is a `422`. A key belongs to your app (sandbox and production apps never share one), lasts as long as what it created, and is 1 to 255 printable ASCII characters. example: 9b2f6c1e-0d4a-4f7e-8a7b-2a1c3d4e5f60 in: header name: Idempotency-Key required: false schema: maxLength: 255 minLength: 1 pattern: ^[\x20-\x7E]+$ type: string schemas: QueuedRequest: properties: error: description: >- Set when `state` is `error`, `retryable`, `timed_out` or `discarded`. `error_type` says where it failed: for a `timed_out` request it is `timed_out`, and for a `discarded` one `discarded`, unless the request was `retryable` when your app discarded it, which keeps the connection error that held it up. `user_message` is safe to show an end user; `error_code` is QuickBooks' own status code for a business error, `hresult` the Web Connector's for a connection/XML error; `debug_message` is for you. properties: debug_message: description: Which element of the request the value came from, when known. type: - string - 'null' error_code: description: QuickBooks' statusCode, for a business error. type: - integer - 'null' error_type: description: >- `quickbooks_business_error`: QuickBooks refused the request -- `response_json.error` has its code. `quickbooks_connection_error`: the Web Connector ran on the customer's PC but could not get the request into QuickBooks, so nothing was applied -- QuickBooks was not running, the company file was not open or not the one this connection belongs to, or a window or message box open in QuickBooks was in the way. Only the customer can fix that, and `user_message` tells them how. `xml_error`: QuickBooks could not parse the qbXML; sent again as-is, it fails again. `outcome_unknown`: a write the Web Connector answered with an error in place of QuickBooks' answer, so whether QuickBooks applied it is not known: look in QuickBooks before sending it again. `unexpected_error`: anything else; for a query, which changes nothing, sending it again is safe. `timed_out`: no answer came back -- the customer's computer lost its connection, or QuickBooks or the Web Connector was closed, while QuickBooks had the request. QuickBooks may still have applied it, so look before sending it again. `discarded`: your app discarded it before the Web Connector picked it up, so QuickBooks never got it. `response_too_large`: QuickBooks answered, but with more than QuBe Sync accepts for one answer (4 MB as the Web Connector sends it, about 3 MB of qbXML), so the answer wasn't kept and `response_json` is null. QuickBooks ran the request. Page the query (`iterator` and a smaller `max_returned`), or narrow it when QuickBooks doesn't page it; for a write, look before sending it again. Web Connector problems on the customer's PC (its password, log file, the .QWC file) never reach QuBe Sync as an error: the Web Connector just stops calling in, and requests wait. Intuit's guide for those: https://quickbooks.intuit.com/learn-support/en-us/help-article/open-programs/fix-common-web-connector-errors-quickbooks-desktop/L9slolvg0_US_en_US enum: - xml_error - quickbooks_connection_error - quickbooks_business_error - unexpected_error - response_too_large - outcome_unknown - timed_out - discarded type: string hresult: description: >- The Web Connector's HRESULT (e.g. `0x80040400`), for a connection or XML error. Informational: branch on `error_type`, not on this. type: - string - 'null' message: description: >- The raw message from QuickBooks or the Web Connector; for `timed_out` and `discarded`, which neither sent, QuBe Sync's own. type: string user_message: description: A friendly message for the end user. type: string type: - object - 'null' id: description: Unique identifier for the queued request format: uuid type: string inserted_at: description: When the request was queued format: date-time type: string iteration_state: description: >- Whether this response is part of an ongoing iteration, and if so, whether more pages remain. Use this (not `state`) to tell whether a multi-page response is complete. enum: - not_applicable - continue - done - max_sandbox_iterations_reached type: string links: properties: connection_ui: format: uri type: string pages: description: >- The pages of a multi-page (iterated) response answered so far, oldest first, a page of them at a time (`page`, `page_size`), each with its own `iteration_state`. Each page is also delivered to `webhook_url` as it is answered. format: uri type: string self: description: >- This request, on demand (a dashboard link, a retry). The answer itself arrives at `webhook_url`. format: uri type: string ui: description: The request in the QuBe Sync dashboard. format: uri type: string required: - self - ui - connection_ui - pages type: object original_request_id: description: >- The id of the first page of this request's iteration. Equal to `id` on the first page itself. format: uuid type: string page: description: The page number, for a multi-page (iterated) response nullable: true type: integer request_types: description: The qbXML request type(s) compiled into this request items: type: string type: array request_xml: description: >- The qbXML sent to QuickBooks: compiled from the operation and its parameters, or as written for `POST /connections/{connection_id}/queued-requests`. A character above ASCII reaches QuickBooks as a character reference (`é`). type: string response_json: description: QuBe Sync's summary of the answer, once the request is completed nullable: true type: object response_xml: description: >- The qbXML response from QuickBooks. One answer can be at most 4 MB as the Web Connector sends it, about 3 MB of qbXML; QuickBooks' answer over that isn't kept: this is null and `error.error_type` is `response_too_large`. nullable: true type: string state: description: >- `waiting`/`retryable`/`ticketed`/`sent` while the Web Connector is on its way; `response_received` once QuickBooks answered successfully (read `response_json.data`, and `response_json.warning` when QuickBooks warned about something it did); `error` when it did not -- the Web Connector could not reach QuickBooks, the qbXML was rejected, or QuickBooks answered with a business error such as 3100 (then `error.error_type` is `quickbooks_business_error` and `response_json` still carries QuickBooks' own `{status: "error", error: {code, type, message}}`); `timed_out` when no answer came back (QuickBooks may still have applied it, so look before sending it again) and `discarded` when your app discarded it before the Web Connector picked it up. Both carry an `error`. enum: - waiting - retryable - ticketed - sent - response_received - error - timed_out - discarded type: string webhook_attempts: items: type: object type: array webhook_error: nullable: true type: string webhook_state: enum: - not_applicable - pending - succeeded - failed type: string webhook_url: format: uri nullable: true type: string required: - id - state - request_xml - links type: object listTransactions_response_json: description: >- QuBe Sync's summary of QuickBooks' answer. Only an `Error` severity from QuickBooks is `status: "error"` (and makes the request's `state` `error`), so a query that matched nothing is still `success`. A `Warn` severity is a `success` with `warning` beside it. oneOf: - properties: data: items: properties: account_ref: description: >- `account_ref` points to an account in the company file. If both `full_name` and `list_id` are provided, `full_name` is ignored. Meaning depends on context: for checks it is the funding account; for ExpenseLineAdd it may be required by accounting preferences; for credit-card transactions it identifies the bank or card account involved. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object amount: description: A monetary amount. type: number amount_in_home_currency: description: Amount in units of the home currency. type: number currency_ref: description: >- A currency record defines how QuickBooks stores and displays a currency. Built-in currency name/code values are fixed; formatting and active status can vary by settings and workflow. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object entity_ref: description: >- A QuickBooks “entity” is a customer, vendor, employee, or person on the QuickBooks “other names” list. Special cases to note: In a BillToPayQuery message, `entity_ref` refers to the vendor name. In JournalCreditLine and JournalDebitLine messages for A/R accounts, `entity_ref` must refer to a customer, or else the transaction won’t be recorded. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object exchange_rate: description: >- `exchange_rate` is the rate from this currency to the company’s home currency at AsOfDate. You can supply a rate when adding transactions, but QuickBooks does not provide rates through the SDK. If your home currency is USD and internet access is available, rates can be downloaded in the QuickBooks UI via Lists > Currency > Activities > Download Latest Exchange Rates. type: number memo: description: Additional information. type: string ref_number: description: >- `ref_number` is a user-managed transaction reference (for example, a check number). It can be edited and is not guaranteed to be globally unique. Some transaction types auto-populate `ref_number` when omitted, based on QuickBooks preferences and numbering state. type: string time_created: description: Time the object was created. format: date-time type: string time_modified: description: Time the object was last modified. format: date-time type: string txn_date: description: >- The date of the transaction. In some cases, if you leave `txn_date` out of an -Add message, QuickBooks will prefill `txn_date` with the date of the last-saved transaction of the same type. format: date type: string txn_id: description: >- `txn_id` is the unique QuickBooks identifier for a transaction. Use it to reference that transaction in later requests. `txn_id` values are transaction-specific and should not be reused across unrelated transaction types. type: string txn_line_id: description: >- Identification number of the transaction line. (`txn_line_id` is supported as of v2.0 of the SDK. With qbXML v1.0 and v1.1, `txn_line_id` is always returned as zero.) If you need to add a new transaction line in a transaction Mod request, you can do so by setting the `txn_line_id` to -1. type: string txn_type: description: The type of transaction. enum: - ARRefundCreditCard - Bill - BillPaymentCheck - BillPaymentCreditCard - BuildAssembly - Charge - Check - CreditCardCharge - CreditCardCredit - CreditMemo - Deposit - Estimate - InventoryAdjustment - Invoice - ItemReceipt - JournalEntry - LiabilityAdjustment - Paycheck - PayrollLiabilityCheck - PurchaseOrder - ReceivePayment - SalesOrder - SalesReceipt - SalesTaxPaymentCheck - Transfer - VendorCredit - YTDAdjustment type: string type: object type: array message: description: >- QuickBooks' own status message, carried through when there is no data to show for an otherwise successful request (a query that matched nothing, say). * `no_match` (1): The query ran and matched nothing. * `not_found_by_key` (500): A record was looked up by an exact key (a FullName or ListID) and does not exist. What each means and how to handle it: [Error handling](https://docs.qubesync.com/error_handling#quickbooks-said-no). type: string status: const: success warning: description: >- Present only when QuickBooks answered with a `Warn` severity: it carried the request out, and `data` is what it saved or found, but it has something to say about it. For example code `530` with the message `The field "Memo" is not supported by this implementation.` means the record was saved without that field, so an add or update that comes back with a `warning` may not have saved everything it sent. Absent on a plain success and on an error. properties: code: description: >- QuickBooks' own statusCode. The stable thing to branch on. * `not_found_by_key` (500): A record was looked up by an exact key (a FullName or ListID) and does not exist. What each means and how to handle it: [Error handling](https://docs.qubesync.com/error_handling#quickbooks-said-yes-with-a-warning). examples: - 500 type: integer message: description: >- QuickBooks' own statusMessage, such as which field it did not support. type: string required: - code type: object required: - status title: Success type: object - properties: error: properties: code: description: QuickBooks' own statusCode. The stable thing to branch on. examples: - 1030 - 3150 - 3210 - 3220 - 3250 - 3260 type: - integer - 'null' message: description: QuickBooks' own statusMessage. type: string type: description: >- A stable name for `code`, when QuBeSync recognises it. Absent otherwise: coverage widens over time, so treat this as a hint and branch on `code` if you need certainty. * `unsupported_request` (1030): The QuickBooks this connection talks to does not support this request. * `missing_element` (3150): QuickBooks requires an element the request left out; the message names it. * `invalid_value` (3210): A field's value is not one QuickBooks accepts; the message names the field and the value. * `not_authorized` (3220): QuickBooks refused the request: no permission for it, or the feature is turned off in this company file. * `feature_not_enabled` (3250): The feature is turned off in this company file, or this edition of QuickBooks does not have it. * `insufficient_permission` (3260): The permission level QuickBooks granted does not allow this action. What each means and how to handle it: [Error handling](https://docs.qubesync.com/error_handling#quickbooks-said-no). enum: - unsupported_request - missing_element - invalid_value - not_authorized - feature_not_enabled - insufficient_permission type: string type: object status: const: error required: - status - error title: Error type: object Error: description: >- What a refused request answers with. The one key is errors, and its shape says what went wrong: a sentence when the endpoint explains the refusal in words (a parameter the operation does not take, a key already taken, a run that has already ended); an object with detail, and a code when there is one, when the request named nothing that exists or may not do what it asked (402, 403, 404, and a CLI session's 401), or an answer to a run's question was refused (the decisions endpoint's 400, 409 and 422, which always carry a code to branch on); an object of fields, each a list of messages, when a record failed validation and nothing was saved; a list of {path, message} problems when a submitted document or input fails validation. A request without a usable API key gets a 401 Basic challenge with the plain-text body Unauthorized, not JSON. properties: errors: oneOf: - example: 'unknown parameter: "emial"' title: A sentence type: string - properties: code: example: read_only_session type: string detail: example: Not Found type: string required: - detail title: Detail and code type: object - additionalProperties: items: type: string type: array example: webhook_url: - may not contain a username or password title: Field by field type: object - items: properties: message: example: is required type: string path: example: input.customer type: string required: - path - message type: object title: Located problems type: array required: - errors type: object headers: IdempotentReplayed: description: >- `true` when the call repeated an earlier call's `Idempotency-Key`: this is what that call created, as it is now, and nothing new was queued. Absent otherwise. schema: enum: - 'true' type: string responses: BadRequest: content: application/json: example: errors: 'unknown parameter: "emial"' schema: $ref: '#/components/schemas/Error' description: >- A parameter the operation does not take, or a value it cannot use. Nothing was queued. Unauthorized: content: text/plain: example: Unauthorized schema: type: string description: >- No usable API key. The key is Basic auth, so the answer is the challenge, with the plain-text body Unauthorized rather than JSON. headers: WWW-Authenticate: schema: example: Basic realm="Application" type: string SandboxPaused: content: application/json: example: errors: detail: >- Sandbox access is paused for this organization because the sandbox period expired and the organization does not currently have both active billing and a recent production connection. Please request an extension if you're still working on your integration or contact support if you have questions. schema: $ref: '#/components/schemas/Error' description: >- A sandbox app whose organization's sandbox access is paused. Nothing was queued. NotFound: content: application/json: example: errors: detail: Not Found schema: $ref: '#/components/schemas/Error' description: Nothing by that id, or it belongs to another app. UnprocessableEntity: content: application/json: example: errors: webhook_url: - may not contain a username or password schema: $ref: '#/components/schemas/Error' description: >- A field failed validation, field by field, and nothing was queued: a `webhook_url` that is not an absolute http or https URL, carries a username or password, is longer than 2048 characters, or (in production) points at localhost or a private address. An `Idempotency-Key` that isn't 1 to 255 printable ASCII characters, or that was already used for a different request, is refused in a sentence naming the header. securitySchemes: apiKey: description: Use your app's API key as the username, and leave the password blank scheme: basic type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.