List transactions

curl --request GET \
  --url https://qubesync.com/api/v2/connections/{connection_id}/transactions \
  --header 'Authorization: Basic <encoded-value>'

import requests

url = "https://qubesync.com/api/v2/connections/{connection_id}/transactions"

headers = {"Authorization": "Basic <encoded-value>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Basic <encoded-value>'}};

fetch('https://qubesync.com/api/v2/connections/{connection_id}/transactions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://qubesync.com/api/v2/connections/{connection_id}/transactions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://qubesync.com/api/v2/connections/{connection_id}/transactions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Basic <encoded-value>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://qubesync.com/api/v2/connections/{connection_id}/transactions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Basic <encoded-value>'

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "links": {
      "connection_ui": "<string>",
      "pages": "<string>",
      "self": "<string>",
      "ui": "<string>"
    },
    "request_xml": "<string>",
    "state": "waiting",
    "error": {
      "debug_message": "<string>",
      "error_code": 123,
      "error_type": "xml_error",
      "hresult": "<string>",
      "message": "<string>",
      "user_message": "<string>"
    },
    "inserted_at": "2023-11-07T05:31:56Z",
    "iteration_state": "not_applicable",
    "original_request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "page": 123,
    "request_types": [
      "<string>"
    ],
    "response_json": {
      "status": "success",
      "data": [
        {
          "account_ref": {
            "full_name": "<string>",
            "list_id": "<string>"
          },
          "amount": 123,
          "amount_in_home_currency": 123,
          "currency_ref": {
            "full_name": "<string>",
            "list_id": "<string>"
          },
          "entity_ref": {
            "full_name": "<string>",
            "list_id": "<string>"
          },
          "exchange_rate": 123,
          "memo": "<string>",
          "ref_number": "<string>",
          "time_created": "2023-11-07T05:31:56Z",
          "time_modified": "2023-11-07T05:31:56Z",
          "txn_date": "2023-12-25",
          "txn_id": "<string>",
          "txn_line_id": "<string>",
          "txn_type": "ARRefundCreditCard"
        }
      ],
      "message": "<string>",
      "warning": {
        "code": 500,
        "message": "<string>"
      }
    },
    "response_xml": "<string>",
    "webhook_attempts": [
      {}
    ],
    "webhook_error": "<string>",
    "webhook_state": "not_applicable",
    "webhook_url": "<string>"
  }
}

{
  "errors": "unknown parameter: \"emial\""
}

Unauthorized

{
  "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."
  }
}

{
  "errors": {
    "detail": "Not Found"
  }
}

{
  "errors": {
    "webhook_url": [
      "may not contain a username or password"
    ]
  }
}

Transactions

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.

GET

connections

{connection_id}

transactions

List transactions

curl --request GET \
  --url https://qubesync.com/api/v2/connections/{connection_id}/transactions \
  --header 'Authorization: Basic <encoded-value>'

import requests

url = "https://qubesync.com/api/v2/connections/{connection_id}/transactions"

headers = {"Authorization": "Basic <encoded-value>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Basic <encoded-value>'}};

fetch('https://qubesync.com/api/v2/connections/{connection_id}/transactions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://qubesync.com/api/v2/connections/{connection_id}/transactions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://qubesync.com/api/v2/connections/{connection_id}/transactions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Basic <encoded-value>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://qubesync.com/api/v2/connections/{connection_id}/transactions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Basic <encoded-value>'

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "links": {
      "connection_ui": "<string>",
      "pages": "<string>",
      "self": "<string>",
      "ui": "<string>"
    },
    "request_xml": "<string>",
    "state": "waiting",
    "error": {
      "debug_message": "<string>",
      "error_code": 123,
      "error_type": "xml_error",
      "hresult": "<string>",
      "message": "<string>",
      "user_message": "<string>"
    },
    "inserted_at": "2023-11-07T05:31:56Z",
    "iteration_state": "not_applicable",
    "original_request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "page": 123,
    "request_types": [
      "<string>"
    ],
    "response_json": {
      "status": "success",
      "data": [
        {
          "account_ref": {
            "full_name": "<string>",
            "list_id": "<string>"
          },
          "amount": 123,
          "amount_in_home_currency": 123,
          "currency_ref": {
            "full_name": "<string>",
            "list_id": "<string>"
          },
          "entity_ref": {
            "full_name": "<string>",
            "list_id": "<string>"
          },
          "exchange_rate": 123,
          "memo": "<string>",
          "ref_number": "<string>",
          "time_created": "2023-11-07T05:31:56Z",
          "time_modified": "2023-11-07T05:31:56Z",
          "txn_date": "2023-12-25",
          "txn_id": "<string>",
          "txn_line_id": "<string>",
          "txn_type": "ARRefundCreditCard"
        }
      ],
      "message": "<string>",
      "warning": {
        "code": 500,
        "message": "<string>"
      }
    },
    "response_xml": "<string>",
    "webhook_attempts": [
      {}
    ],
    "webhook_error": "<string>",
    "webhook_state": "not_applicable",
    "webhook_url": "<string>"
  }
}

{
  "errors": "unknown parameter: \"emial\""
}

Unauthorized

{
  "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."
  }
}

{
  "errors": {
    "detail": "Not Found"
  }
}

{
  "errors": {
    "webhook_url": [
      "may not contain a username or password"
    ]
  }
}

Authorizations

Authorization

string

header

required

Use your app's API key as the username, and leave the password blank

Headers

Idempotency-Key

string

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.

Required string length: 1 - 255

Pattern: ^[\x20-\x7E]+$

Path Parameters

connection_id

string<uuid>

required

The connection (a customer's QuickBooks company file) this request is queued for.

Query Parameters

request_id

string

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.

meta_data

enum<string>

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.

Available options:

MetaDataAndResponseData,

MetaDataOnly,

NoMetaData

iterator

boolean

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.

currency_filter

ListID · object

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.

ListID
FullName

Show child attributes

include_ret_element

enum<string>[]

Available options:

AccountRef,

Amount,

AmountInHomeCurrency,

CurrencyRef,

EntityRef,

ExchangeRate,

Memo,

RefNumber,

TimeCreated,

TimeModified,

TxnDate,

TxnID,

TxnLineID,

TxnType

max_returned

integer

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.

Required range: x >= 1

ref_number

string[]

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.

ref_number_case_sensitive

string[]

ref_number_filter

object

Filters by ref_number range. Numeric-only bounds are compared numerically; otherwise comparison is lexicographic.

Show child attributes

ref_number_range_filter

object

Filters by ref_number range. Numeric-only bounds are compared numerically; otherwise comparison is lexicographic.

Show child attributes

transaction_account_filter

AccountTypeFilter · object

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”.

AccountTypeFilter
ListID
FullName
ListIDWithChildren
FullNameWithChildren

Show child attributes

transaction_class_filter

ListID · object

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”.

ListID
FullName
ListIDWithChildren
FullNameWithChildren

Show child attributes

transaction_date_range_filter

FromTxnDate + ToTxnDate · object

Filters the transactions based on the transaction’s date either by specifying a “from” and/or “to” date, or by using a date_macro.

FromTxnDate + ToTxnDate
DateMacro

Show child attributes

transaction_detail_level_filter

enum<string>

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.

Available options:

All,

AllExceptSummary,

SummaryOnly

transaction_entity_filter

EntityTypeFilter · object

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”.

EntityTypeFilter
ListID
FullName
ListIDWithChildren
FullNameWithChildren

Show child attributes

transaction_item_filter

ItemTypeFilter · object

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”.

ItemTypeFilter
ListID
FullName
ListIDWithChildren
FullNameWithChildren

Show child attributes

transaction_modified_date_range_filter

FromModifiedDate + ToModifiedDate · object

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.

FromModifiedDate + ToModifiedDate
DateMacro

Show child attributes

transaction_paid_status_filter

enum<string>

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.

Available options:

Closed,

Either,

Open

transaction_posting_status_filter

enum<string>

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

Available options:

Either,

NonPosting,

Posting

transaction_type_filter

object

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.

Show child attributes

txn_id

string[]

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.

webhook_url

string<uri>

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.

Maximum string length: 2048

Callbacks

POST

{$request.query.webhook_url}answered

Body

application/json

POSTed to webhook_url as JSON, signed with X-QUBE-Signature (t=<timestamp>,v1=<hex HMAC-SHA256 of "<timestamp>.<raw body>" with your app's webhook secret>).

app_id

string<uuid>

required

Your app's id.

app_name

string

required

error

object | null

required

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.

Show child attributes

string<uuid>

required

The request's id, as the 201 returned it. For an iterated query, every page carries the first page's id here.

page_request_id

string<uuid>

required

This page's own id. Equal to id except on later pages of an iterated query.

response_json

Success · object

required

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.

Success
Error

Show child attributes

sandbox

boolean

required

Whether the app is a sandbox app.

state

enum<string>

required

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.

Available options:

response_received,

error,

retryable,

timed_out,

discarded

timestamp

integer

required

Unix seconds; the same t the signature covers.

iteration_state

enum<string>

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.

Available options:

not_applicable,

continue,

done,

max_sandbox_iterations_reached

links

object

Present only with response_xml_omitted.

Show child attributes

page

integer | null

The page number, when iterated.

response_xml

string | null

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.

response_xml_omitted

boolean

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.

Response

2XX

Received. Anything else is retried with backoff for about 8 hours.

Response

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.

data

object

required

Show child attributes

Overview

API v2

API v1 (legacy)

List transactions

Authorizations

Headers

Path Parameters

Query Parameters

Callbacks

Body

Response

Response