quickbooks-ruby

In the Quickbooks API, many properties are references (e.g., CustomerRef). In quickbooks-ruby, you can assign these references easily by using the setter for the _id property of the attribute. For example, setting customer_id on an Invoice will automatically create the appropriate CustomerRef XML packet.

invoice = Quickbooks::Model::Invoice.new
invoice.customer_id = 99

For advanced debugging, it is recommended to use an HTTP proxy like Charles Proxy. To do this, pass connection_opts containing the proxy URI and SSL verification settings when initializing your OAuth2::Client.

# Example configuration for using a proxy with OAuth2::Client
oauth_params = {
  site: "https://appcenter.intuit.com/connect/oauth2",
  authorize_url: "https://appcenter.intuit.com/connect/oauth2",
  token_url: "https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer",
  connection_opts: {
    proxy: {uri: "http://127.0.0.1:8888"},
    ssl: {verify: false}  # Required if using a proxy with a self-signed cert
  }
}

oauth2_client = OAuth2::Client.new(ENV['OAUTH_CLIENT_ID'], ENV['OAUTH_CLIENT_SECRET'], oauth_params)

To install the gem, add it to your Gemfile and run bundle, or install it directly via the command line.

Requirements:

• Ruby version: >= 2.6.0 (Version 2.x of the gem no longer supports Ruby 2.5 or below).
• Ruby 1.9.x is not supported.

# Add to Gemfile
gem 'quickbooks-ruby'

# Then run
$ bundle

Or via CLI:

$ gem install quickbooks-ruby

To test the QuickBooks Online OAuth 2.0 flow locally, you may need to expose your local server to the internet so Intuit can send webhooks or redirect callbacks to your machine. Use ngrok to create a tunnel to your local port (e.g., 4567).

ngrok http -subdomain vinoqbwc 4567

You can enable global logging or configure logging for specific service instances. By default, logs are sent to STDOUT. You can redirect logs to a different target, such as Rails.logger.

# Enable global logging
Quickbooks.log = true

# Redirect logs to Rails
Quickbooks.logger = Rails.logger
Quickbooks.log = true

# Disable pretty-printing of XML
Quickbooks.log_xml_pretty_print = false

# Enable logging for a specific service instance only
customer_service = Quickbooks::Service::Customer.new
customer_service.log = true

By default, the gem runs in production mode. To develop or test using a development key and Sandbox Companies, enable sandbox_mode.

You can also specify a specific QBO API minorversion. As of July 2025, 75 is the minimum supported version.

# Enable sandbox mode for development
Quickbooks.sandbox_mode = true

# Specify a specific API minor version
Quickbooks.minorversion = 75

To use a service class inheriting from BaseService, initialize it with an attributes hash. The service automatically determines the base URI based on whether Quickbooks.sandbox_mode is enabled. You must provide a company_id (also referred to as realm_id) to construct valid resource URLs.

Note that company_id and realm_id are synonymous in this library.

# Example initialization
service = MyQuickbooksService.new(
  company_id: 'your_realm_id',
  oauth: oauth_access_token
)

SalesReceipts can be defined using a hash in the constructor. You can use auto_doc_number! to let Intuit generate the transaction number, provided that 'Custom Transaction Numbers' is unchecked in the Quickbooks Company Settings.

salesreceipt = Quickbooks::Model::SalesReceipt.new({
  customer_id: 99,
  txn_date: Date.civil(2013, 11, 20),
  payment_ref_number: "111",
  deposit_to_account_id: 222,
  payment_method_id: 333
})
salesreceipt.auto_doc_number!

line_item = Quickbooks::Model::Line.new
line_item.amount = 50
line_item.description = "Plush Baby Doll"
line_item.sales_item! do |detail|
  detail.unit_price = 50
  detail.quantity = 1
  detail.item_id = 500
end

salesreceipt.line_items << line_item

service = Quickbooks::Service::SalesReceipt.new({access_token: access_token, company_id: "123" })
created_receipt = service.create(salesreceipt)