Configuration

The QuickBooks Online .NET SDK allows you to configure app settings such as minor version, number of retries, and logging. As installed, the SDK is configured with default values as listed in the table below.Override default settings as follows:

Features you can configure:

General configuration file structure can be found here.

Default values

The following table lists the default values configured in the .NET SDK:

FEATURE CONFIGURATION FILE TAG DEFAULT VALUE
Base URL "BaseUrl": { "Qbo" : "url" } https://quickbooks.api.intuit.com/
Minor version "MinorVersion": { "Qbo" : "n" } Check release notes.
Logging "Logger": { "RequestLog" : { ... } } System.Trace
Serialization and compression "Message": { "Request":{ .. } , "Response":{ .. } } Request: GZip or Xml or Json
Retries ``”Retry”: { “Mode” : {“LinearRetry”:{..}, “IncrementalRetry”:{..}, “ExponentialRetry”:{..} } } `` Retry policy not set.
Security "Security": { "Mode": {"Oauth":{..}, "Custom":{..} } } No defaults.
Webhooks "WebhooksService": { "VerifierToken" : { "Value" : "token" } No defaults.
Configuration Basics
Configuration file level

The SDK allows you to define custom, local app settings in the AppSettings.json file. Then, when your app makes QuickBooks OnlineAPI calls to access QuickBooks Onlinedata, the SDK by default checks for configuration settings in the configuration file before using its defaults. To see the configuration file, click here.

Code level

To configure app settings at the code level, first build the service context and then override the feature setting as described on this page.

Base URL

A base URL defines the work environment accessed for REST API services. Supported work environments include:

WORK ENVIRONMENT OAUTH AUTHORIZATION KEYS QUICKBOOKS COMPANY BASE URL
Development App’s development keys Your sandbox data. For more information, see Sandboxes. https://sandbox-quickbooks.api.intuit.com/
Production App’s production keys Your user’s company data https://quickbooks.api.intuit.com/

The default configuration accesses the QuickBooks Onlineproduction environment for REST API services. To test your code in the development environment using your QuickBooks Online sandbox, you can either create a configuration file setting or explicitly set the Base URL in ServiceContext objects. For more information about sandboxes, click here.

Configuration file setting

Include the following code in the configuration file to override the default production work environment:

1
2
3
4
5
6
7
8
"Service": {
   "BaseUrl": {
      "Qbo": "https://quickbooks.api.intuit.com",
      "Ips": "",
      "OAuthAccessTokenUrl": "",
      "UserNameAuthentication": ""
  }
}
Code-level setting

Use the steps in this section to override the default value or, if set, the value defined in the configuration file.

Once the tokens are received, you can then make QuickBooks Online API calls using the .NET SDK. You can download the latest version using NuGet Package Manager. For example:

1
2
3
4
5
OAuth2RequestValidator oauthValidator = new OAuth2RequestValidator(access_token);
ServiceContext serviceContext = new ServiceContext(realmId, IntuitServicesType.QBO, oauthValidator);
DataService commonServiceQBO = new DataService(serviceContext);
QueryService<Invoice> inService = new QueryService<Invoice>(serviceContext);
Invoice In = inService.ExecuteIdsQuery("SELECT * FROM Invoice").FirstOrDefault();

You must make a RefreshToken call after a 401 error (Invalid Token error) to get a new access token, or call RefreshToken every every hour since the Access Token expires in one hour.

Then, override the base URL setting as follows:

1
context.IppConfiguration.BaseUrl.Qbo = "https://sandbox-quickbooks.api.intuit.com/";
Minor version

QuickBooks Onlinedata services support minor versions in order to provide a way for you to access incremental changes without breaking existing apps. Check release notes for current default value. Click here for more details about minor versions.

Configuration file setting

Override the default QuickBooks OnlineAPI minor version setting by replacing the <minorVersion> value with the desired value.

1
2
3
4
5
 "Service":{
      "MinorVersion":{
           "Qbo": "37"
       }
  }
Code-level setting

Use the steps in this section to override the default value or, if set, the value defined in the configuration file.

Once the tokens are received, you can then make QuickBooks Online API calls using the .NET SDK. You can download the latest version using NuGet Package Manager. For example:

1
2
3
4
5
OAuth2RequestValidator oauthValidator = new OAuth2RequestValidator(access_token);
ServiceContext serviceContext = new ServiceContext(realmId, IntuitServicesType.QBO, oauthValidator);
DataService commonServiceQBO = new DataService(serviceContext);
QueryService<Invoice> inService = new QueryService<Invoice>(serviceContext);
Invoice In = inService.ExecuteIdsQuery("SELECT * FROM Invoice").FirstOrDefault();

You must make a RefreshToken call after a 401 error (Invalid Token error) to get a new access token, or call RefreshToken every every hour since the Access Token expires in one hour.

Then, override the request and response formats, as follows:

1
serviceContext.IppConfiguration.MinorVersion.Qbo = "5";
Logging

Logging diagnostic information plays a key part for any application. The SDK provides several ways to log messages:

For detailed information on how to configure logging, click here.

Configuration file setting
Trace logging

The SDK uses System.Trace as the default logger. For detailed information on how to configure the default logger settings, such as whether to automatically flush the buffer, see Trace Logging.

Request and Response logging

Include the following code in the configuration file to enable request and response logging. Define the local file system (folder) path to store the logs:

1
2
3
4
5
6
"Logger": {
  "RequestLog": {
     "EnableLogs": "true",
     "LogDirectory": "C:\\IdsLogs"
  }
}
Code-level setting

Use the steps in this section to override the default value or, if set, the value defined in the configuration file. For more information on message logging, seeLogging.

Once the tokens are received, you can then make QuickBooks Online API calls using the .NET SDK. You can download the latest version using NuGet Package Manager. For example:

1
2
3
4
5
OAuth2RequestValidator oauthValidator = new OAuth2RequestValidator(access_token);
ServiceContext serviceContext = new ServiceContext(realmId, IntuitServicesType.QBO, oauthValidator);
DataService commonServiceQBO = new DataService(serviceContext);
QueryService<Invoice> inService = new QueryService<Invoice>(serviceContext);
Invoice In = inService.ExecuteIdsQuery("SELECT * FROM Invoice").FirstOrDefault();

You must make a RefreshToken call after a 401 error (Invalid Token error) to get a new access token, or call RefreshToken every every hour since the Access Token expires in one hour.

Then, override the desired logging feature, as described in the following sections.

Request and response logging

Enable Request and Response logging. If you have already enabled Request and Response logging in the configuration file, go to the next step.

1
context.IppConfiguration.Logger.RequestLog.EnableRequestResponsLogging = true;

Set a local path for the log file:

1
context.IppConfiguration.Logger.RequestLog.ServiceRequestLoggingLocation = @"C:\IdsLogs";
Serialization and compression formats

The SDK supports XML and JSON serialization for QuickBooks OnlineAPI request and response payloads. It also supports compression of request and response data to GZip and Deflate formats. You must use the same serialization format for both request and response payloads.

Configuration file settings

Include the following code to set the serialization and compression formats of requests and responses:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
"Message": {
  "Request": {
     "CompressionFormat": "GZip",
     "SerializationFormat": "Json"
  },
  "Response": {
     "CompressionFormat": "GZip",
     "SerializationFormat": "Json"
  }
}
Code-level settings

Use the steps in this section to override the default value or, if set, the value defined in the configuration file.

Once the tokens are received, you can then make QuickBooks Online API calls using the .NET SDK. You can download the latest version using NuGet Package Manager. For example:

1
2
3
4
5
OAuth2RequestValidator oauthValidator = new OAuth2RequestValidator(access_token);
ServiceContext serviceContext = new ServiceContext(realmId, IntuitServicesType.QBO, oauthValidator);
DataService commonServiceQBO = new DataService(serviceContext);
QueryService<Invoice> inService = new QueryService<Invoice>(serviceContext);
Invoice In = inService.ExecuteIdsQuery("SELECT * FROM Invoice").FirstOrDefault();

You must make a RefreshToken call after a 401 error (Invalid Token error) to get a new access token, or call RefreshToken every every hour since the Access Token expires in one hour.

Then, override the request and response formats, as follows.

Serialization

1
2
context.IppConfiguration.Message.Request.SerializationFormat = SerializationFormat.Json;
context.IppConfiguration.Message.Response.SerializationFormat = SerializationFormat.Json;

Similarly, you can set the serialization to XML.​

Data compression

Include the following code to compress request and response code, respectively, data using GZip format:

1
2
context.IppConfiguration.Message.Request.CompressionFormat = CompressionFormat.GZip;
context.IppConfiguration.Message.Response.CompressionFormat = CompressionFormat.GZip;

Similarly, you can set data compression of requests to Deflateor none. When compression is set to none, the SDK leaves the data uncompressed.​

Retry policies

Retry policies enable your app to handle transient errors. For detailed information on retry policies, click here.

Configuration file setting
Linear retry policy

Include the following code to set linear retry attempts:

1
2
3
4
5
"LinearRetry":{
    "Enable": "false",
    "RetryCount": "",
    "RetryInterval": ""
 }
Incremental retry policy

Include the following code to set incremental retry attempts for a specified number of times:

1
2
3
4
5
6
"IncrementatlRetry": {
  "Enable": "false",
  "RetryCount": "",
  "InitialInterval": "",
  "Increment": ""
}
exponential-retry-policy

Include the following code to set randomized exponential retry attempts for a specified number of times:

1
2
3
4
5
6
7
"ExponentialRetry": {
  "Enable": "false",
  "RetryCount": "",
  "MinBackoff": "",
  "MaxBackoff": "",
  "DeltaBackoff": ""
}
Code-level settings

Use the steps in this section to override the default value or, if set, the value defined in the configuration file.

Once the tokens are received, you can then make QuickBooks Online API calls using the .NET SDK. You can download the latest version using NuGet Package Manager. For example:

1
2
3
4
5
OAuth2RequestValidator oauthValidator = new OAuth2RequestValidator(access_token);
ServiceContext serviceContext = new ServiceContext(realmId, IntuitServicesType.QBO, oauthValidator);
DataService commonServiceQBO = new DataService(serviceContext);
QueryService<Invoice> inService = new QueryService<Invoice>(serviceContext);
Invoice In = inService.ExecuteIdsQuery("SELECT * FROM Invoice").FirstOrDefault();

You must make a RefreshToken call after a 401 error (Invalid Token error) to get a new access token, or call RefreshToken every every hour since the Access Token expires in one hour.

Then, override the request and response formats, as follows. The IppConfiguration class has the IntuitRetryPolicy constructors required to override the configuration file settings. The parameters of the IntuitRetryPolicy constructor determine the number and frequency of retries.

Linear retry policy

Include the following code to set a linear retry:

1
context.IppConfiguration.RetryPolicy = new IntuitRetryPolicy(int retryCount, TimeSpan retryInterval);
Incremental retry policy

Include the following code to set an incremental retry:

1
context.IppConfiguration.RetryPolicy = new IntuitRetryPolicy(int retryCount, TimeSpan initialInterval, TimeSpan increment);
Exponential retry policy

Include the following code to set an exponential retry:

1
context.IppConfiguration.RetryPolicy = new IntuitRetryPolicy(int retryCount, TimeSpan minBackoff, TimeSpan maxBackoff, TimeSpan deltaBackoff);
Summary of IntuitRetryPolicy parameters

The following table lists the parameters of the preceding IntuitRetryPolicy() constructors:

PARAMETER DESCRIPTION
retryCount An integer value that specifies the number of retries to attempt.
retryInterval A TimeSpan value that specifies the interval between retries.
minBackoff A TimeSpan value that specifies the initial interval between retries.
maxBackoff A TimeSpan value that specifies the maximum interval permitted between retries.
deltaBackoff A TimeSpan value that specifies the delta to use when the block calculates the exponential intervals between retries.
InitialInterval A TimeSpan value that specifies the initial interval between retries.
increment A TimeSpan value that specifies by how much the interval should increase between retries.
OAuth Authorization

For an app to access a QuickBooks company, you must use OAuth to authorize the app. In this type of authorization, an OAuth token is used to authorize and connect an app to the company. For more information, see Authorization.

Configuration file structure

The basic structure of the configuration information are declared in Appsettings.json file, is as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
 {
  "Logger": {
   "RequestLog": {
       "EnableLogs": "true",
       "LogDirectory": ""
    }
},
 "Security": {
     "Mode": {
         "Oauth": {
             "Enable": "false",
             "AccessToken": ""
           }
  },
  "Message": {
       "Request": {
            "CompressionFormat": "GZip",
            "SerializationFormat": "Json"
         },
       "Response": {
            "CompressionFormat": "GZip",
            "SerializationFormat": "Json"
        }
  },
  "Service": {
      "BaseUrl": {
          "Qbo": "https://quickbooks.api.intuit.com",
          "Ips": "",
          "OAuthAccessTokenUrl": "",
          "UserNameAuthentication": ""
       },
       "MinorVersion": {
         "Qbo": "37"
       }
   },
  "WebhooksService": {
        "VerifierToken": {
              "Value": ""
        }
  },
 "Retry": {
     "Mode": {
         "LinearRetry": {
            "Enable": "false",
            "RetryCount": "",
            "RetryInterval": ""
          },
        "IncrementatlRetry": {
           "Enable": "false",
           "RetryCount": "",
           "InitialInterval": "",
           "Increment": ""
        },
       "ExponentialRetry": {
           "RetryCount": "",
           "MinBackoff": "",
           "MaxBackoff": "",
           "DeltaBackoff": ""
        }
     }
  }
}